agentmash 0.3.0

package/hooks/mcp_launcher.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+// The MCP server as a teammate receives it.
+//
+// It lives beside the hooks because it travels the same way they do: both
+// installers copy it into .claude/agentmash/, the team commits it, and a
+// teammate gets it by `git pull`. Unlike the hooks it cannot be the whole
+// story — the real MCP server needs @modelcontextprotocol/sdk, and a
+// teammate's checkout has no reason to contain it. So this file is a shim
+// with three layers, tried in order:
+//
+//   1. the real server, imported in-process, when its dependencies already
+//      resolve here — a checkout of AgentMash itself, or a repo that
+//      installed the `agentmash` package;
+//   2. the published package by way of `npx`, off unless this machine sets
+//      AGENTMASH_MCP_NPX=1, because it downloads and executes code from the
+//      registry and that is not a decision the repo gets to make for you;
+//   3. a degraded server, implemented below in plain JSON-RPC, that starts,
+//      answers tools/list, and makes every call say that AgentMash could not
+//      start and the answer is UNKNOWN.
+//
+// Layer 3 is why this file exists at all. An MCP server that fails to start is
+// invisible to the agent: the tools are simply absent, so it stops asking and
+// carries on as though nobody else were working in the repo — the one wrong
+// answer this project exists to prevent. Registering a server that says "I do
+// not know" is worse than one that works and far better than one that is
+// missing, because only the agent can act on the difference.
+//
+// Nothing but JSON-RPC is ever written to stdout: that channel is the
+// protocol. Diagnostics go to stderr, where Claude Code logs them.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// The version is stamped in by cli/sync-hooks.mjs at pack time, so the copy of
+// this file that ships inside a package always names the version it shipped
+// with. Change the marker comment and the stamp stops happening silently — the
+// packer throws instead. A hand-edited constant is how this file came to pin a
+// version that was never published. The checked-in value is the one the web
+// installer commits — it has no packer to stamp it — so it has to be moved with
+// the version bump; cli/test/package.test.mjs diffs the two installers and fails
+// if it drifts.
+const PINNED_VERSION = '0.3.0'; // agentmash:pin
+const PACKAGE_SPEC = process.env.AGENTMASH_MCP_PACKAGE || `agentmash@${PINNED_VERSION}`;
+
+/**
+ * Layer 2 is opt-in. It fetches a package from the network and runs it at
+ * session start, which is a decision for the person whose machine it is, not
+ * for whoever ran `agentmash init` and committed the result. Off, the worst
+ * case is layer 3: tools that are present and say they cannot answer.
+ */
+const NPX_ENABLED = process.env.AGENTMASH_MCP_NPX === '1';
+
+/** Long enough for a cold `npx` download, short enough to still answer a client. */
+const NPX_BUDGET_MS = Number(process.env.AGENTMASH_MCP_NPX_TIMEOUT_MS) || 25_000;
+
+/** The version of MCP this shim implements — not whatever the client asks for. */
+const PROTOCOL_VERSION = '2025-06-18';
+/** The `-unavailable` suffix is how `agentmash doctor` recognises layer 3. */
+const DEGRADED_VERSION = '0.1.0-unavailable';
+
+const log = (message) => process.stderr.write(`[agentmash-mcp] ${message}\n`);
+
+/** The repo this was installed into: .claude/agentmash/<this file> is two levels down. */
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || path.resolve(HERE, '..', '..');
+}
+
+/** Candidate copies of the real server, nearest first. */
+function entryCandidates(repo) {
+  const candidates = [];
+  if (process.env.AGENTMASH_MCP_ENTRY) candidates.push(process.env.AGENTMASH_MCP_ENTRY);
+  // A checkout of AgentMash itself, where `npm install` has already run.
+  candidates.push(path.join(repo, 'mcp', 'server.mjs'));
+  // A repo that installed the package, here or in a parent (monorepo roots).
+  let dir = repo;
+  for (let i = 0; i < 6; i++) {
+    candidates.push(path.join(dir, 'node_modules', 'agentmash', 'mcp', 'server.mjs'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return candidates.filter((file) => fs.existsSync(file));
+}
+
+/** Layer 1. Returns false when the file is there but its dependencies are not. */
+async function serveInProcess(repo) {
+  for (const entry of entryCandidates(repo)) {
+    try {
+      const module = await import(pathToFileURL(entry).href);
+      await module.start();
+      return true;
+    } catch (err) {
+      log(`cannot run ${entry}: ${err?.message || err}`);
+    }
+  }
+  return false;
+}
+
+/** Quote one argument for a Windows shell, which is what `.cmd` needs to run. */
+const quoteForShell = (arg) => (/^[\w@.:=/\\-]+$/.test(arg) ? arg : `"${String(arg).replace(/"/g, '""')}"`);
+
+/**
+ * How layer 2 is spawned, per platform. Exported so a test can check the
+ * Windows form on a machine that is not Windows: since the BatBadBut fix
+ * (Node 18.20.2 / 20.12.2 / 21.7.3) `spawn` refuses a `.cmd` without
+ * `shell: true` and throws EINVAL, which silently cost Windows layer 2
+ * altogether — and a shell in turn means the arguments have to be quoted.
+ */
+export function npxInvocation(platform, spec) {
+  // `--package <spec> -- agentmash mcp` rather than `npx <spec> mcp`: it names
+  // the binary explicitly, so a spec that is a path or a tarball is still
+  // installed rather than executed.
+  const args = ['--yes', '--package', spec, '--', 'agentmash', 'mcp'];
+  if (platform !== 'win32') return { command: 'npx', args, shell: false };
+  return { command: 'npx.cmd', args: args.map(quoteForShell), shell: true };
+}
+
+/**
+ * True for a line that is a JSON-RPC message and not, say, an npm update
+ * notice. Forwarding anything else would corrupt the protocol stream, and
+ * treating it as proof the child is alive would strand the client on a server
+ * that never answers.
+ */
+export function isJsonRpcLine(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return false;
+  }
+  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.jsonrpc === '2.0';
+}
+
+/**
+ * Layer 2. Hand stdio to `npx agentmash mcp` and get out of the way.
+ *
+ * The handover is reversible on purpose: everything the client sends is kept
+ * until the child has answered something, so if `npx` cannot reach the
+ * registry — no network, package not published yet — we can still fall through
+ * to layer 3 and replay the requests to it, instead of leaving the client
+ * talking to a corpse.
+ *
+ * @returns {Promise<{served: boolean, detail?: string, replay?: Buffer[]}>}
+ */
+function serveViaNpx(onStdin) {
+  return new Promise((resolve) => {
+    const { command, args, shell } = npxInvocation(process.platform, PACKAGE_SPEC);
+    let child;
+    try {
+      child = spawn(command, args, {
+        stdio: ['pipe', 'pipe', 'inherit'],
+        shell,
+        env: { ...process.env, CLAUDE_PROJECT_DIR: projectDir() },
+      });
+    } catch (err) {
+      return resolve({ served: false, detail: `could not run npx: ${err?.message || err}` });
+    }
+
+    const buffered = [];
+    let answered = false;
+    let settled = false;
+    let out = '';
+
+    const timer = setTimeout(() => {
+      if (answered || settled) return;
+      child.kill();
+      give(`npx ${PACKAGE_SPEC} did not answer within ${NPX_BUDGET_MS}ms`);
+    }, NPX_BUDGET_MS);
+    timer.unref?.();
+
+    function give(detail) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      onStdin(null);
+      resolve({ served: false, detail, replay: buffered });
+    }
+
+    /** Forward whole lines, and only the ones that are protocol. */
+    function drain(final) {
+      let index;
+      while ((index = out.indexOf('\n')) !== -1) {
+        const line = out.slice(0, index);
+        out = out.slice(index + 1);
+        take(line);
+      }
+      if (final && out.trim()) {
+        take(out);
+        out = '';
+      }
+    }
+
+    function take(line) {
+      if (!line.trim()) return;
+      if (!isJsonRpcLine(line)) {
+        log(`ignored non-protocol output from npx: ${line.trim().slice(0, 200)}`);
+        return;
+      }
+      answered = true;
+      clearTimeout(timer);
+      process.stdout.write(line + '\n');
+    }
+
+    onStdin((chunk) => {
+      if (settled) return;
+      buffered.push(chunk);
+      try {
+        child.stdin.write(chunk);
+      } catch {
+        /* the child is gone; the exit handler decides what happens next */
+      }
+    });
+
+    child.stdin.on('error', () => {
+      /* EPIPE when npx fails before reading — handled on exit */
+    });
+    child.stdout.on('data', (chunk) => {
+      out += chunk.toString('utf8');
+      drain(false);
+    });
+    child.on('error', (err) => give(`could not run npx: ${err?.message || err}`));
+    child.on('exit', (code, signal) => {
+      drain(true);
+      if (answered) {
+        // It spoke, so the session had a working server; its death is the
+        // client's problem to report, not something to paper over here.
+        settled = true;
+        clearTimeout(timer);
+        resolve({ served: true });
+        process.exit(code ?? 0);
+      }
+      give(`npx ${PACKAGE_SPEC} exited ${signal || code} before answering`);
+    });
+  });
+}
+
+// ── layer 3: the degraded server ───────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'who_is_working_on_what',
+    title: 'Who is working on what',
+    description:
+      'Reports who else is working in this repository. UNAVAILABLE on this machine: AgentMash could not start its MCP server, so this cannot answer and must not be read as "nobody is working on anything".',
+  },
+  {
+    name: 'has_anyone_touched',
+    title: 'Has anyone touched this path',
+    description:
+      'Reports whether a teammate recently edited a path. UNAVAILABLE on this machine: AgentMash could not start its MCP server, so a quiet answer here would be a guess, not a fact.',
+  },
+  {
+    name: 'list_contested_files',
+    title: 'List contested files',
+    description:
+      'Lists files more than one person has edited recently. UNAVAILABLE on this machine: AgentMash could not start its MCP server.',
+  },
+];
+
+function unavailableText(detail) {
+  return `AgentMash could not start its MCP server on this machine, so it cannot say who is working in this repository.
+
+Treat the answer as UNKNOWN. This is not the same as "nobody is working on anything" — AgentMash never got to ask.
+
+Reason: ${detail}
+
+The hooks are unaffected: if this repo is connected, teammates' edits are still reported and you will still be warned before you edit a file someone just changed. Only these query tools are missing.
+
+To fix it, on this machine:
+  npx agentmash doctor          says exactly what is missing
+  npm install -D agentmash      puts the real server in this repo, for everyone
+  AGENTMASH_MCP_ENTRY=<path>    point at mcp/server.mjs in an AgentMash checkout
+  AGENTMASH_MCP_NPX=1           let this machine fetch the package from npm itself
+
+Each of those needs network access to npm once; without it these tools stay unavailable.`;
+}
+
+/**
+ * MCP over stdio is newline-delimited JSON-RPC, which is little enough
+ * protocol to implement here — and implementing it here is the point: the
+ * degraded server has to run on a machine that has no dependencies at all.
+ */
+function createDegradedServer(detail) {
+  const message = unavailableText(detail);
+  let buffer = '';
+
+  const send = (payload) => process.stdout.write(JSON.stringify(payload) + '\n');
+  const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
+  const fail = (id, code, msg) => send({ jsonrpc: '2.0', id, error: { code, message: msg } });
+
+  function handle(request) {
+    const { id, method } = request;
+    if (id === undefined || id === null) return; // a notification: nothing to answer
+    switch (method) {
+      case 'initialize':
+        return reply(id, {
+          // The version this shim implements. Echoing the client's back would
+          // claim support for whatever it happened to be handed.
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'agentmash', version: DEGRADED_VERSION },
+          instructions:
+            'AgentMash is registered here but could not start. Its tools report themselves unavailable; never read that as "nobody is working on anything".',
+        });
+      case 'ping':
+        return reply(id, {});
+      case 'tools/list':
+        return reply(id, {
+          tools: TOOLS.map((tool) => ({
+            ...tool,
+            inputSchema: { type: 'object', properties: {}, additionalProperties: true },
+            annotations: { readOnlyHint: true, openWorldHint: true },
+          })),
+        });
+      case 'tools/call':
+        return reply(id, { content: [{ type: 'text', text: message }], isError: true });
+      default:
+        return fail(id, -32601, `method not found: ${method}`);
+    }
+  }
+
+  return {
+    feed(chunk) {
+      buffer += chunk.toString('utf8');
+      let index;
+      while ((index = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        let request;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+          continue;
+        }
+        handle(request);
+      }
+    },
+  };
+}
+
+// ── wiring ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const repo = projectDir();
+  if (await serveInProcess(repo)) return;
+
+  // One stdin reader for the whole process: layer 2 borrows it and hands it
+  // back, so no request is lost when the handover fails.
+  let sink = null;
+  const pending = [];
+  process.stdin.on('data', (chunk) => (sink ? sink(chunk) : pending.push(chunk)));
+  const setSink = (next) => {
+    sink = next;
+    if (!next) return;
+    while (pending.length) next(pending.shift());
+  };
+
+  let detail = 'the MCP server and its dependencies are not installed here';
+  if (NPX_ENABLED) {
+    const attempt = await serveViaNpx(setSink);
+    if (attempt.served) return;
+    detail = attempt.detail || detail;
+    pending.unshift(...(attempt.replay || []));
+  }
+
+  log(`degraded: ${detail}`);
+  const degraded = createDegradedServer(detail);
+  setSink((chunk) => degraded.feed(chunk));
+}
+
+// Set only by the tests, which import this file to check the pieces that cannot
+// be run on the platform the tests run on. Unset — which is everywhere else —
+// this file always starts a server, because a launcher that quietly declines to
+// start is the failure it exists to prevent.
+if (process.env.AGENTMASH_MCP_IMPORT_ONLY !== '1') {
+  main().catch((err) => {
+    log(`fatal: ${err?.stack || err}`);
+    process.exit(1);
+  });
+}

package/hooks/post_tool_use.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// AgentMash PostToolUse hook (Write|Edit|MultiEdit): report the edit to the
+// coordination server. Fire-and-forget — always exits 0, always silent.
+
+import {
+  armExitGuard,
+  composeSummary,
+  finish,
+  getDeveloper,
+  getGitBranch,
+  httpJson,
+  loadConfig,
+  parseJson,
+  readSessionCache,
+  readStdin,
+  summarizeChange,
+  takeOverrideNote,
+  toRepoRelative,
+  writeSessionCache,
+} from './lib.mjs';
+// Namespace import for anything added after v0: hooks and lib.mjs are vendored
+// into the repo and can drift apart in a partial merge. A missing *named*
+// import is a module-link error — a non-zero exit and a stack trace in the
+// agent's transcript, which is exactly what these hooks promise never to do.
+import * as lib from './lib.mjs';
+
+armExitGuard();
+
+async function main() {
+  const input = parseJson(await readStdin());
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) return;
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || input?.cwd || process.cwd();
+  const config = loadConfig(projectDir);
+  if (config.disabled || !config.room) return;
+
+  const sessionId = input?.session_id || 'unknown';
+  const cache = readSessionCache(sessionId);
+  const file = toRepoRelative(projectDir, filePath);
+
+  // If strict mode was overridden for this file, the reason rides out here, on
+  // the existing event stream — so the teammate who was overridden sees it in
+  // their own advisory, and the room sees it on the dashboard. No new call, no
+  // new field, and this hook is async, so it costs the edit nothing.
+  const override = takeOverrideNote(cache, file);
+  if (override) writeSessionCache(sessionId, cache);
+  const summary = composeSummary(summarizeChange(input?.tool_name, input?.tool_input), override);
+
+  await httpJson('POST', `${config.url}/events`, {
+    room: config.room,
+    token: config.token,
+    timeoutMs: config.reportTimeoutMs,
+    body: {
+      developer: getDeveloper(config, input?.cwd),
+      session_id: sessionId,
+      event_type: 'edit',
+      tool: input?.tool_name || null,
+      file_path: file,
+      git_branch: getGitBranch(input?.cwd || projectDir),
+      task_hint: config.shareHints ? cache.task_hint || null : null,
+      change_summary: summary || null,
+      symbols: lib.symbolsForEdit?.(filePath, input?.tool_name, input?.tool_input) ?? null,
+      // The changed text, only when this developer allows it and the room
+      // asked for it (PreToolUse cached the room's answer). Absent otherwise,
+      // and an older vendored lib.mjs cannot build it at all.
+      diff:
+        config.streamDiffs && cache.stream_diffs === true
+          ? (lib.diffForEdit?.(input?.tool_name, input?.tool_input) ?? null)
+          : undefined,
+      timestamp: new Date().toISOString(),
+    },
+  });
+}
+
+main()
+  .catch(() => {})
+  .finally(finish);

package/hooks/pre_tool_use.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// AgentMash PreToolUse hook (Write|Edit|MultiEdit): ask the coordination
+// server whether a teammate's agent recently touched this file, and if so
+// inject a message shaped to change what this agent does next.
+//
+// Advisory mode (default): exit 0 with hookSpecificOutput.additionalContext —
+// the agent sees the heads-up but the edit proceeds through the normal
+// permission flow. Strict mode (AGENTMASH_STRICT=1): permissionDecision
+// "deny", plus an acknowledge protocol the agent can complete on its own.
+//
+// The wording, the severity rule and the acknowledge protocol all live in
+// lib.mjs; this file is the plumbing around them.
+//
+// Anything going wrong — server down, slow, misconfigured — is a silent
+// exit 0 within the advisory budget (AGENTMASH_TIMEOUT_MS, default 1500 ms).
+
+import {
+  ACK_TTL_MS,
+  ADVISORY_TIMEOUT_MS,
+  ackFile,
+  armExitGuard,
+  buildCollisionAdvice,
+  buildStrictBlock,
+  emitAndExit,
+  finish,
+  getDeveloper,
+  getGitBranch,
+  httpJson,
+  loadConfig,
+  parseJson,
+  readAcks,
+  readSessionCache,
+  readStdin,
+  resolveAck,
+  scratchDir,
+  toRepoRelative,
+  writeSessionCache,
+} from './lib.mjs';
+// See the note in post_tool_use.mjs: guarded access for post-v0 helpers.
+import * as lib from './lib.mjs';
+
+// A server that is *unreachable* rather than down — a firewall, a hung
+// instance — accepts nothing and refuses nothing, so the AbortSignal fires on
+// schedule but the connecting socket keeps the event loop alive and this guard
+// is the only thing that ends the process. Sized from the advisory budget
+// instead of a flat 4 s, because strict mode deliberately has no cooldown (see
+// below) and so every single edit pays this in full.
+const EXIT_GUARD_SLACK_MS = 250;
+const exitGuard = armExitGuard(ADVISORY_TIMEOUT_MS + EXIT_GUARD_SLACK_MS);
+
+// Don't re-inject the same advisory for the same file for a while; the agent
+// already knows, and repeated context is noise.
+//
+// Strict mode gets no such cooldown, and that is the point: a cooldown there
+// would be a ten-minute pass earned by one block, which is the rubber stamp the
+// acknowledge protocol exists to prevent. The acknowledgement *is* strict
+// mode's cooldown — scoped to one collision, and paid for with a reason.
+const ADVISORY_COOLDOWN_MS = 10 * 60_000;
+
+function advisory(context) {
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: context } };
+}
+
+/**
+ * Strict mode, second half. An acknowledgement buys passage, not silence: the
+ * full advisory still goes into the agent's context, and the reason is parked
+ * for the reporting hook to publish. Note what is deliberately *not* returned —
+ * permissionDecision "allow" — because getting past AgentMash must not also get
+ * past the user's own permission rules.
+ */
+function strictOutcome(advice, sessionId, cache, file) {
+  // The reason is read against the collision the agent was just shown and
+  // against what the agent itself is working on — see resolveAck.
+  const verdict = resolveAck(readAcks(sessionId), advice.token, {
+    grounding: advice.grounding,
+    taskHint: cache.task_hint,
+  });
+  const firstUsed = cache.acks?.[advice.token];
+
+  if (verdict.ok && (!firstUsed || Date.now() - firstUsed < ACK_TTL_MS)) {
+    cache.acks = { ...(cache.acks || {}), [advice.token]: firstUsed || Date.now() };
+    cache.overrides = {
+      ...(cache.overrides || {}),
+      [file]: { developer: advice.developer, reason: verdict.reason, at: Date.now() },
+    };
+    writeSessionCache(sessionId, cache);
+    return advisory(
+      `${advice.text}\n\nYou acknowledged this collision: "${verdict.reason}". Proceeding — ` +
+        `that acknowledgement is recorded and rides out with your next reported edit.`
+    );
+  }
+
+  // An expired acknowledgement is a rejection with a specific cause, so say so
+  // rather than letting the agent re-run a command that already worked once.
+  const rejected = verdict.ok ? 'expired' : verdict.rejected;
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: buildStrictBlock(advice, {
+        ackDir: scratchDir(),
+        ackPath: ackFile(sessionId),
+        rejected,
+      }),
+    },
+  };
+}
+
+async function main() {
+  const input = parseJson(await readStdin());
+  const filePath = input?.tool_input?.file_path;
+  if (!filePath) return null;
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || input?.cwd || process.cwd();
+  const config = loadConfig(projectDir);
+  if (config.disabled || !config.room) return null;
+
+  // A distant server may be given a longer budget; the guard has to outlive it.
+  if (config.advisoryTimeoutMs > ADVISORY_TIMEOUT_MS) {
+    clearTimeout(exitGuard);
+    armExitGuard(config.advisoryTimeoutMs + EXIT_GUARD_SLACK_MS);
+  }
+
+  const sessionId = input?.session_id || 'unknown';
+  const file = toRepoRelative(projectDir, filePath);
+  const cache = readSessionCache(sessionId);
+
+  if (!config.strict) {
+    const advisedAt = cache.advised?.[file] || 0;
+    if (Date.now() - advisedAt < ADVISORY_COOLDOWN_MS) return null;
+  }
+
+  const developer = getDeveloper(config, input?.cwd);
+  // What this file is bound to — its imports and its own exports. The server
+  // matches them against what teammates recently changed, so a signature change
+  // in another file still reaches us. Old servers ignore the parameter.
+  const symbols = lib.symbolsForFile?.(filePath) ?? null;
+  const url =
+    `${config.url}/check?file_path=${encodeURIComponent(file)}` +
+    `&developer=${encodeURIComponent(developer)}` +
+    (symbols?.length ? `&symbols=${encodeURIComponent(symbols.join(','))}` : '');
+  const result = await httpJson('GET', url, {
+    room: config.room,
+    token: config.token,
+    timeoutMs: config.advisoryTimeoutMs,
+  });
+  const holders = Array.isArray(result?.holders) ? result.holders : [];
+  // The room says whether edits here may carry their text to the live view.
+  // PostToolUse is fire-and-forget with no answer to read, so the answer is
+  // kept for it here, per session. A missing field (older server) means no.
+  if (result && (result.stream_diffs === true) !== (cache.stream_diffs === true)) {
+    cache.stream_diffs = result.stream_diffs === true;
+    writeSessionCache(sessionId, cache);
+  }
+  // Claims are teammates' stated intent for this file — see buildClaimAdvice.
+  // An older server never sends them, and the guarded access keeps an older
+  // vendored lib.mjs from throwing on a newer server.
+  const claims = Array.isArray(result?.claims) ? result.claims : [];
+  if (holders.length === 0 && claims.length === 0) return null;
+
+  const advice = holders.length
+    ? buildCollisionAdvice({
+        file,
+        holders,
+        branch: getGitBranch(input?.cwd || projectDir),
+        showHints: config.shareHints,
+      })
+    : null;
+  const claimAdvice = claims.length
+    ? (lib.buildClaimAdvice?.({ file, claims, showHints: config.shareHints }) ?? null)
+    : null;
+  if (!advice && !claimAdvice) return null;
+
+  // A collision and a claim on the same file are one message, not two.
+  if (advice && claimAdvice) advice.text += `\n\n${claimAdvice.text}`;
+
+  // Strict mode blocks on writes that happened; a claim alone is intent, and
+  // intent gets the advisory path in every mode.
+  if (advice && config.strict) return strictOutcome(advice, sessionId, cache, file);
+
+  cache.advised = { ...(cache.advised || {}), [file]: Date.now() };
+  writeSessionCache(sessionId, cache);
+  return advisory(advice ? advice.text : claimAdvice.text);
+}
+
+main()
+  .then((payload) => {
+    if (payload) emitAndExit(payload);
+    else finish();
+  })
+  .catch(finish);