fix(mcp): separate log cutoffs from backend failures

docs/guides/agent-first-setup.md

@@ -59,11 +59,15 @@ completed operations or delete persistent project data. These controls do not re
 the number of servers for clients that remain connected.
 
 MCP command results capture at most 8 MiB of combined stdout/stderr bytes before
-text decoding. This also bounds log tails with oversized or newline-free messages.
-Exceeding the budget stops the command and returns an error with
-`outputTruncated: true`; parsed `data` is omitted so a prefix cannot masquerade as
-a complete result. Run the equivalent CLI command when full output is needed.
-The budget bounds captured bytes, not total process memory or JSON response size.
+text decoding. For tools other than the log tools, exceeding the budget stops the
+command and returns an error with `outputTruncated: true`; parsed `data` is omitted
+so a prefix cannot masquerade as a complete result. The log tools
+(`hack.project.logs.tail` and `hack.project.logs.snapshot`) use the same budget,
+but reaching it is a cutoff: the result is `ok: true` with `outputTruncated: true`,
+`data.cutoff` set to the `bytes` bound, and the events parsed before the cut. See
+[MCP logs contract](../reference/mcp-logs.md). Run the equivalent CLI command when
+full output is needed. The budget bounds captured bytes, not total process memory
+or JSON response size.
 
 Each MCP session captures its launch working directory and environment. Project
 registry selection, command execution and audit-file locations use that snapshot;

docs/reference.md

@@ -27,3 +27,4 @@
 - [Extensions](./extensions.md)
 - [Creating an extension](./guides/create-extension.md)
 - [Integrations](./integrations.md)
+- [MCP logs contract](./reference/mcp-logs.md) — cutoff versus backend failure for the MCP log tools, and the cursor/handle decision

docs/reference/mcp-logs.md

@@ -0,0 +1,102 @@
+# MCP logs contract
+
+This page covers the `hack.project.logs.tail` and `hack.project.logs.snapshot`
+MCP tools. Both tools run `hack logs --json` once per call and return the stream
+events they collected. When a shell is available, use `hack logs` directly.
+
+## Outcomes
+
+Each call ends in exactly one outcome.
+
+| Outcome | `ok` | `isError` | `data.cutoff` | `error` |
+| --- | --- | --- | --- | --- |
+| Complete: the backend ended the stream and exited 0 | `true` | absent | `null` | absent |
+| Cutoff: the server stopped at one of its bounds | `true` | absent | set | absent |
+| Backend failure | `false` | `true` | `null` | `backend_error` |
+
+A cutoff is a success. The collected events are valid. The stream simply
+continued past the bound. `data.cutoff` is `{ "bound": ..., "limit": ... }`:
+
+- `events`: `maxEvents` log events were collected (tail only). Only
+  `type: "log"` events count. `start`, `heartbeat`, `error` and `end` events
+  are returned in `data.events` but do not use up the limit.
+- `time`: the collection window ended. For tail this is `maxMs`. For snapshot
+  it is the fixed 120 second command timeout.
+- `bytes`: stdout plus stderr reached the 8 MiB capture limit.
+  `outputTruncated` is `true`, and `data` still carries every event parsed
+  before the cut. The cut never splits a UTF-8 code point. A trailing partial
+  line can be present in `stdout`, but it is never parsed as an event.
+
+After a cutoff, the server stopped the child process, so `exitCode` is often
+non-zero. Use `ok` and `data.cutoff` to read the result, not `exitCode`.
+`data.stop_reason` (tail only) keeps its earlier values: `eof`, `max_events`,
+`timeout`, `output_limit`, `cancelled` or `interrupted`.
+
+A backend failure is not a truncated success. It is reported when the stream
+contains an `error` event or an `end` event with a reason other than `eof` or
+`closed`, or when the child exits non-zero at the end of the stream. The error
+is closed: `code` is `E_UNEXPECTED`, `reason` is `backend_error`, and `message`
+is fixed text that never repeats backend output, caller input or the query.
+Raw `stdout` and `stderr` are still returned, as they are for other tools.
+
+Failure evidence counts only before the server stops the child. A child that
+writes `error` or `end` events, or exits non-zero, in response to the server's
+own stop signal still produces a cutoff. The byte bound is an exception for
+events: every retained byte was written before the child was signalled, and
+nothing after the cut is parsed, so an `error` or failing `end` event in the
+returned prefix is still a backend failure. For the `events` and `time` bounds,
+an `error` event that the backend wrote just before the stop but that the server
+read after it is reported as a cutoff. The server cannot tell it apart from an
+event written in response to the stop.
+
+## Reconnects and repeated calls
+
+The server keeps no log state between calls. Every call starts a new backend
+stream:
+
+- A repeated call does not replay events from an earlier call, and it does not
+  continue after the earlier call's last event.
+- A cancelled request, or a session that closes mid-call, stops the backend
+  process group. The interrupted call's events are not delivered later, to this
+  session or to a reconnected one.
+
+To continue a stream approximately, call again with `since` set to the last
+event's `ts`. `since` selects the Loki backend and cannot be combined with
+`compose`. Expect overlap at the boundary and remove duplicates on the client.
+
+## Decision: no handles, cursors or idempotency keys (no-go)
+
+Status: no-go for now (HACK-1134). This decision adds no cursor implementation.
+
+We considered three additions:
+
+- A stream handle, so a later call can attach to a running tail.
+- A resume cursor, so a later call can continue after the last returned event.
+- An idempotency key, so a retried call returns the same result.
+
+Reasons for no-go:
+
+1. **The backends have no exact cursor.** Hack's compose path accepts only
+   `tail`, and `docker compose logs` itself offers only timestamp filters that
+   can repeat or skip lines with the same timestamp. The lifecycle log
+   companion is a file tail. Loki selects by time range, and its timestamps
+   are not unique. A cursor would promise gapless, duplicate-free resume that
+   Hack cannot deliver, least of all for the default compose backend.
+2. **A handle needs state that does not survive the common reconnect.** A
+   stdio MCP client reconnects by starting a new `hack mcp serve` process, so
+   in-memory handles are lost. Keeping them on disk under `HACK_HOME` would add
+   retained log data, plus ownership, expiry and cleanup rules. Logs can hold
+   secrets, so that retention is a risk.
+3. **Idempotency adds nothing to a read.** Both tools are read-only and
+   annotated `readOnlyHint`. A retry is already safe. It returns current data
+   rather than a replay, and that is the documented behavior above.
+4. **Bounded calls already cover the need.** Agents call tail with a small
+   window, read `data.cutoff`, and call again with `since` when they need more.
+
+Revisit this decision (go) only when all of these are true:
+
+- A backend exposes a stable, monotonic position, such as a daemon-owned log
+  index.
+- Hack has a daemon-owned buffer with defined retention, ownership and secret
+  handling.
+- A real agent workflow shows that `since` overlap is not good enough.

src/mcp/logs-contract.ts

@@ -0,0 +1,139 @@
+/**
+ * Result contract for the MCP `hack.project.logs.tail` and
+ * `hack.project.logs.snapshot` tools.
+ *
+ * A collection ends in exactly one outcome:
+ * - `complete`: the backend reached end of stream and exited 0.
+ * - `cutoff`: the MCP server stopped collection at one of its own bounds. This
+ *   is a success; `data.cutoff` names the bound and its effective limit.
+ * - `backend_error`: the log backend reported failure (a stream `error` event,
+ *   a failing `end` event, or a non-zero exit the server did not cause). This
+ *   is a closed error, never a truncated success.
+ * - `cancelled`: the request was aborted or the session closed; nothing is
+ *   kept for a later request (see docs/reference/mcp-logs.md).
+ *
+ * Failure evidence counts only while collection is still running. Once the
+ * server stops the command for a bound, a later `error`/`end` event or a
+ * signal exit status is a consequence of that stop, not a backend failure.
+ * The byte bound is the exception for events: the retained prefix was written
+ * before the child was signalled and nothing after the cut is parsed, so an
+ * `error` or failing `end` event inside that prefix is still a failure.
+ */
+
+/** Why collection stopped, as reported in `data.stop_reason`. */
+export type McpLogStopReason =
+  | "eof"
+  | "max_events"
+  | "timeout"
+  | "output_limit"
+  | "cancelled"
+  | "interrupted";
+
+/** The bound that ended a successful, incomplete collection. */
+export type McpLogCutoff = {
+  /** `events` counts `type: "log"` events only; `bytes` is the shared stdout
+   * plus stderr capture budget; `time` is the collection window. */
+  readonly bound: "events" | "bytes" | "time";
+  readonly limit: number;
+};
+
+export type McpLogOutcome =
+  | { readonly kind: "complete" }
+  | { readonly kind: "cutoff"; readonly cutoff: McpLogCutoff }
+  | { readonly kind: "backend_error" }
+  | { readonly kind: "cancelled" };
+
+/** Closed post-spawn failure. The message is fixed and never repeats backend
+ * output, caller input or query text. */
+export const MCP_LOG_BACKEND_ERROR = Object.freeze({
+  code: "E_UNEXPECTED",
+  reason: "backend_error",
+  message: "Log backend failed. Run 'hack logs' for details.",
+} as const);
+
+/** End reasons written by the CLI's JSON stream for a normal end of stream. */
+const CLEAN_END_REASONS: ReadonlySet<string> = new Set(["eof", "closed"]);
+
+/** Classify one parsed `hack logs --json` stream event. */
+export function observeLogStreamEvent(event: Record<string, unknown>): {
+  readonly isLog: boolean;
+  readonly backendFailure: boolean;
+} {
+  const type = event.type;
+  if (type === "log") {
+    return { isLog: true, backendFailure: false };
+  }
+  if (type === "error") {
+    return { isLog: false, backendFailure: true };
+  }
+  if (type === "end") {
+    const reason = event.reason;
+    return {
+      isLog: false,
+      backendFailure:
+        typeof reason === "string" && !CLEAN_END_REASONS.has(reason),
+    };
+  }
+  return { isLog: false, backendFailure: false };
+}
+
+/**
+ * Decide the outcome of a finished collection. Backend failure evidence wins
+ * over a cutoff; a non-zero exit after a server-initiated stop is ignored.
+ */
+export function classifyLogCollection(opts: {
+  readonly stopReason: McpLogStopReason;
+  readonly exitCode: number;
+  readonly backendFailureObserved: boolean;
+  readonly limits: {
+    readonly maxEvents?: number;
+    readonly timeMs: number;
+    readonly bytes: number;
+  };
+}): McpLogOutcome {
+  if (opts.backendFailureObserved) {
+    return { kind: "backend_error" };
+  }
+  switch (opts.stopReason) {
+    case "cancelled":
+    case "interrupted":
+      return { kind: "cancelled" };
+    case "max_events":
+      return {
+        kind: "cutoff",
+        cutoff: { bound: "events", limit: opts.limits.maxEvents ?? 0 },
+      };
+    case "timeout":
+      return {
+        kind: "cutoff",
+        cutoff: { bound: "time", limit: opts.limits.timeMs },
+      };
+    case "output_limit":
+      return {
+        kind: "cutoff",
+        cutoff: { bound: "bytes", limit: opts.limits.bytes },
+      };
+    case "eof":
+      return opts.exitCode === 0
+        ? { kind: "complete" }
+        : { kind: "backend_error" };
+    default: {
+      const unreachable: never = opts.stopReason;
+      return unreachable;
+    }
+  }
+}
+
+/** Narrow a lifetime stop reason to the closed set the logs contract reports. */
+export function toLogStopReason(reason: string): McpLogStopReason {
+  switch (reason) {
+    case "max_events":
+    case "timeout":
+    case "output_limit":
+    case "cancelled":
+    case "interrupted":
+      return reason;
+    default:
+      return "interrupted";
+  }
+}