agentmash 0.3.0

package/hooks/lib.mjs

@@ -0,0 +1,1957 @@
+// Shared helpers for AgentMash hook scripts.
+//
+// Reliability contract (do not weaken):
+//   - every network call is capped by an AbortSignal, at the budget for its
+//     path (see ADVISORY_TIMEOUT_MS and REPORT_TIMEOUT_MS below)
+//   - no helper ever throws to the caller
+//   - nothing is written to stdout/stderr on the happy path
+
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+// Two budgets, because the hooks have two very different jobs.
+//
+// Both numbers are derived, and `npm run bench:budget` is where they come from.
+// Do not raise or lower either one without re-running it.
+//
+// The advisory check is the only network call Claude Code waits on, so it is
+// the only one a team feels. What it is waiting for is *not* the server: the
+// bench puts findHolders at 0.1 ms on a 20k-event room and the whole response
+// at ~500 bytes. It is waiting for a cold process to reach the server at all.
+// Every hook is a fresh process, so each check pays three round trips before an
+// answer can come back — TCP, then the TLS handshake, then the request — which
+// the bench measures as roughly 110 ms + 3 x round trip. Hence:
+//
+//    500 ms delivers every advisory up to ~130 ms of round trip, and none at
+//           all past it: a team one ocean away would silently get nothing
+//   1500 ms delivers every advisory up to ~460 ms of round trip
+//
+// 1500 ms is the default because it covers every network a team is likely to
+// be on without anyone configuring anything. Past that the budget is sized to
+// the network actually in front of it: `agentmash init` measures the round trip
+// and writes `timeout_ms`. See budgetForRoundTrip, which is that derivation.
+//
+// Reporting hooks are registered with `async: true`, so Claude Code does not
+// wait for them at all — their budget only bounds a stuck background process,
+// and 2500 ms leaves room under Claude Code's own hook timeout.
+//
+// Note what actually protects you when the server is *down*: a refused
+// connection fails in milliseconds, not at the timeout. These budgets only
+// bite when a server is reachable but slow.
+export const ADVISORY_TIMEOUT_MS = 1500;
+export const REPORT_TIMEOUT_MS = 2500;
+/** @deprecated kept so older vendored copies of the hooks keep working */
+export const NETWORK_TIMEOUT_MS = ADVISORY_TIMEOUT_MS;
+
+/**
+ * What one `/check` costs a cold hook against a server this far away. Three
+ * round trips, because a fresh process pays TCP, then TLS, then the request,
+ * plus the client-side setup `npm run bench:budget` measures at about 110 ms.
+ *
+ * This is the number to compare a budget against. A warm round trip — what
+ * `curl` or `agentmash doctor` sees — is about a third of it, and comparing a
+ * budget against *that* is how a config that drops every advisory passes a
+ * health check.
+ */
+export function coldCheckCostMs(roundTripMs) {
+  return 3 * roundTripMs + 110;
+}
+
+/**
+ * The largest advisory budget this hook can actually honour. The installed
+ * PreToolUse entry carries Claude Code's own `timeout: 5` (seconds) and the exit
+ * guard sits 250 ms past the budget, so anything larger is a promise the host
+ * cancels first. Past ~1.25 s of round trip there is no honest budget left —
+ * that is the point to move the server closer or turn the advisory off, not to
+ * write a bigger number.
+ */
+export const MAX_ADVISORY_TIMEOUT_MS = 4000;
+
+/**
+ * The advisory budget a server this far away needs, rounded up to a readable
+ * 500 ms with a little slack for a jittery link. Never below the default, never
+ * above what the host will wait for.
+ */
+export function budgetForRoundTrip(roundTripMs) {
+  if (!Number.isFinite(roundTripMs) || roundTripMs <= 0) return ADVISORY_TIMEOUT_MS;
+  const needed = coldCheckCostMs(roundTripMs) + 140;
+  return Math.min(MAX_ADVISORY_TIMEOUT_MS, Math.max(ADVISORY_TIMEOUT_MS, Math.ceil(needed / 500) * 500));
+}
+
+/** Read all of stdin; give up quietly after 2 s so a missing pipe can't hang the hook. */
+export function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => resolve(data), 2000);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+
+export function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function parseDotEnv(file, into) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return;
+  }
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!m) continue;
+    const value = m[2].replace(/^(['"])(.*)\1$/, '$2');
+    if (into[m[1]] === undefined) into[m[1]] = value;
+  }
+}
+
+/**
+ * Config precedence, highest first: real environment variables,
+ * <repo>/.env, <repo>/.claude/agentmash/.env, then the committed
+ * <repo>/.claude/agentmash/config.json that `agentmash init` writes.
+ *
+ * The committed config is what makes teammate setup a `git pull` — the room
+ * travels with the repo, so nobody hand-writes a .env.
+ */
+export function loadConfig(projectDir) {
+  const vars = { ...process.env };
+  let file = {};
+  if (projectDir) {
+    parseDotEnv(path.join(projectDir, '.env'), vars);
+    parseDotEnv(path.join(projectDir, '.claude', 'agentmash', '.env'), vars);
+    try {
+      const raw = fs.readFileSync(path.join(projectDir, '.claude', 'agentmash', 'config.json'), 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') file = parsed;
+    } catch {
+      // no committed config — env/.env may still supply everything
+    }
+  }
+  const override = Number(vars.AGENTMASH_TIMEOUT_MS || file.timeout_ms);
+  const valid = Number.isFinite(override) && override > 0;
+  const url = (vars.AGENTMASH_URL || file.url || 'http://127.0.0.1:8787').replace(/\/+$/, '');
+  const roomRef = vars.AGENTMASH_ROOM_REF || file.room_ref || '';
+  return {
+    url,
+    room: vars.AGENTMASH_ROOM || file.room || '',
+    roomRef,
+    // Optional and absent by default: rooms that ask for it get a token from
+    // `agentmash login`, which stores it per machine, outside the repo.
+    token: vars.AGENTMASH_TOKEN || readDeveloperToken(url, roomRef),
+    dev: vars.AGENTMASH_DEV || '',
+    strict: vars.AGENTMASH_STRICT === '1' || (file.strict === true && vars.AGENTMASH_STRICT !== '0'),
+    disabled: vars.AGENTMASH_DISABLE === '1',
+    // Task hints are verbatim prompts, and every hook that renders one puts it
+    // in somebody else's agent's context. Off means this developer's prompts
+    // never leave the machine — not that they are hidden downstream.
+    shareHints: vars.AGENTMASH_HINTS !== '0' && !(file.share_hints === false && vars.AGENTMASH_HINTS !== '1'),
+    // Whether this developer will let their edits carry the changed text to
+    // the live view. Two switches must both be on: this one (per developer,
+    // default on) and the room's (per room, default off). Either side can say no.
+    streamDiffs: vars.AGENTMASH_DIFFS !== '0' && !(file.stream_diffs === false && vars.AGENTMASH_DIFFS !== '1'),
+    advisoryTimeoutMs: valid ? override : ADVISORY_TIMEOUT_MS,
+    reportTimeoutMs: valid ? Math.max(override, REPORT_TIMEOUT_MS) : REPORT_TIMEOUT_MS,
+  };
+}
+
+/** Per-machine credentials live outside the repo and are never committed. */
+export function credentialsPath() {
+  const home = process.env.AGENTMASH_HOME || os.homedir();
+  return path.join(home, '.agentmash', 'credentials.json');
+}
+
+/**
+ * The developer token for this server+room, if this machine has one. Keyed by
+ * the room's non-secret ref, so rotating the room key does not orphan it.
+ */
+export function readDeveloperToken(url, roomRef) {
+  if (!roomRef) return '';
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
+    const entry = parsed?.tokens?.[`${url}|${roomRef}`];
+    return typeof entry?.token === 'string' ? entry.token : '';
+  } catch {
+    // no credentials file, unreadable, or malformed — the room may not need one
+    return '';
+  }
+}
+
+/**
+ * Identity. AGENTMASH_DEV wins over git config so two terminals on one
+ * machine (which share git config) can present as different developers.
+ */
+export function getDeveloper(config, cwd) {
+  if (config.dev) return config.dev;
+  try {
+    const email = execFileSync('git', ['config', 'user.email'], {
+      cwd: cwd || process.cwd(),
+      timeout: 400,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+    if (email) return email;
+  } catch {
+    // no git / no config — fall through
+  }
+  try {
+    return os.userInfo().username;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** Current branch by reading .git/HEAD directly — no subprocess, ~1 ms. */
+export function getGitBranch(startDir) {
+  try {
+    let dir = startDir || process.cwd();
+    for (let i = 0; i < 40; i++) {
+      const dotGit = path.join(dir, '.git');
+      let gitDir = null;
+      const stat = fs.statSync(dotGit, { throwIfNoEntry: false });
+      if (stat?.isDirectory()) {
+        gitDir = dotGit;
+      } else if (stat?.isFile()) {
+        // worktree / submodule: .git is a file pointing at the real git dir
+        const m = fs.readFileSync(dotGit, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
+        if (m) gitDir = path.resolve(dir, m[1]);
+      }
+      if (gitDir) {
+        const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
+        const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+        return ref ? ref[1] : head.slice(0, 7);
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // not a repo, unreadable HEAD, etc.
+  }
+  return '';
+}
+
+/**
+ * Repo-relative path with forward slashes, so the same file matches across
+ * machines with different checkouts. Files outside the project keep their
+ * absolute path.
+ */
+export function toRepoRelative(projectDir, filePath) {
+  if (!filePath) return null;
+  let result = filePath;
+  if (projectDir) {
+    const rel = path.relative(projectDir, filePath);
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) result = rel;
+  }
+  return result.replace(/\\/g, '/');
+}
+
+/** Per-session scratch lives in one temp directory, so nothing leaks into the repo. */
+function scratchFile(name) {
+  return path.join(os.tmpdir(), 'agentmash', name);
+}
+
+function cacheFile(sessionId) {
+  const safe = String(sessionId || 'unknown').replace(/[^A-Za-z0-9._-]/g, '_');
+  return scratchFile(`${safe}.json`);
+}
+
+/** Per-session scratch state: cached task hint + advisory cooldowns. */
+export function readSessionCache(sessionId) {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(sessionId), 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+/** The directory the ack log lives in — the block message tells the agent to create it. */
+export function scratchDir() {
+  return scratchFile('');
+}
+
+export function writeSessionCache(sessionId, cache) {
+  try {
+    const file = cacheFile(sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+    // a broken temp dir must not break the hook
+  }
+}
+
+/** The session is over; its scratch file is dead weight in the temp dir. */
+export function clearSessionCache(sessionId) {
+  try {
+    fs.rmSync(cacheFile(sessionId), { force: true });
+  } catch {
+    // best effort — a leftover file is harmless
+  }
+}
+
+export function truncate(text, max = 200) {
+  const clean = String(text).replace(/\s+/g, ' ').trim();
+  return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+
+// Declaration keywords across the languages a mixed team is likely to share.
+const DECLARATION =
+  /\b(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:public\s+|private\s+|protected\s+|static\s+)*(?:function|class|interface|type|enum|struct|trait|impl|def|fn|const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+
+function declaredNames(text) {
+  const names = new Set();
+  for (const match of String(text || '').matchAll(DECLARATION)) names.add(match[1]);
+  return names;
+}
+
+function countLines(text) {
+  if (!text) return 0;
+  return String(text).split('\n').length;
+}
+
+/** Per side, the most text a live diff carries. The server clips at the same bound. */
+export const DIFF_CHARS = 4000;
+
+/**
+ * The changed text itself, for a room that streams diffs to its live view.
+ * Edit: what was replaced and what replaced it. MultiEdit: the first edit,
+ * plus how many there were. Write: the new content, no before. Clipped so
+ * a generated file does not become a 2 MB event; `truncated` says when.
+ * Null when the tool input has nothing textual to show.
+ */
+export function diffForEdit(toolName, toolInput, { maxChars = DIFF_CHARS } = {}) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  let truncated = false;
+  const clip = (v) => {
+    if (typeof v !== 'string') return null;
+    if (v.length <= maxChars) return v;
+    truncated = true;
+    return v.slice(0, maxChars);
+  };
+  try {
+    if (toolName === 'Write') {
+      const after = clip(toolInput.content);
+      return after === null ? null : { before: null, after, truncated, edits: 1 };
+    }
+    const edits = Array.isArray(toolInput.edits) && toolInput.edits.length ? toolInput.edits : [toolInput];
+    const first = edits[0] || {};
+    const before = clip(first.old_string);
+    const after = clip(first.new_string);
+    if (before === null && after === null) return null;
+    return { before, after, truncated: truncated || edits.length > 1, edits: edits.length };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A compact, language-agnostic description of what an edit did — line counts
+ * plus any declarations the edit introduced. This is what turns an advisory
+ * from "someone touched this file" into "someone changed this interface".
+ */
+export function summarizeChange(toolName, toolInput) {
+  if (!toolInput) return null;
+  try {
+    if (toolName === 'Write') {
+      const lines = countLines(toolInput.content);
+      const names = [...declaredNames(toolInput.content)].slice(0, 3);
+      return `wrote ${lines} line${lines === 1 ? '' : 's'}${names.length ? `, defining ${names.join(', ')}` : ''}`;
+    }
+
+    const edits = Array.isArray(toolInput.edits)
+      ? toolInput.edits
+      : [{ old_string: toolInput.old_string, new_string: toolInput.new_string }];
+
+    let added = 0;
+    let removed = 0;
+    const introduced = new Set();
+    for (const edit of edits) {
+      added += countLines(edit?.new_string);
+      removed += countLines(edit?.old_string);
+      const before = declaredNames(edit?.old_string);
+      for (const name of declaredNames(edit?.new_string)) {
+        if (!before.has(name)) introduced.add(name);
+      }
+    }
+
+    const scale = edits.length > 1 ? `${edits.length} edits, ` : '';
+    const names = [...introduced].slice(0, 3);
+    return `${scale}+${added}/-${removed} lines${names.length ? `, touching ${names.join(', ')}` : ''}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Node races the addresses a hostname resolves to and gives each attempt 250 ms
+ * by default. A TCP connect to a server a continent away takes longer than that,
+ * so every attempt is abandoned, fetch rejects with ETIMEDOUT in ~300 ms, and the
+ * caller sees a dead server that curl reaches fine. Give each attempt half the
+ * request's own budget instead: a slow-but-working first address gets to finish,
+ * and a blackholed one still leaves the other half for the next family.
+ */
+export function widenConnectAttempts(timeoutMs) {
+  try {
+    net.setDefaultAutoSelectFamilyAttemptTimeout(Math.max(250, Math.floor(timeoutMs / 2)));
+  } catch {
+    // Node older than 18.18 has no such knob, and no such 250 ms default to undo
+  }
+}
+
+/**
+ * GET/POST JSON under the caller's budget — `timeoutMs`, or the advisory budget
+ * if none is given. Any failure — timeout, refused, non-2xx, bad JSON — returns
+ * null, and never throws.
+ */
+export async function httpJson(method, url, { room, token, body, timeoutMs } = {}) {
+  try {
+    widenConnectAttempts(timeoutMs || ADVISORY_TIMEOUT_MS);
+    const res = await fetch(url, {
+      method,
+      // `connection: close` keeps undici from parking a keep-alive socket that
+      // would otherwise hold this short-lived process open past its work.
+      // The developer token, when there is one, rides along on the request the
+      // hook was already making — authentication costs no extra round trip.
+      headers: {
+        'content-type': 'application/json',
+        'x-agentmash-room': room || '',
+        ...(token ? { 'x-agentmash-token': token } : {}),
+        connection: 'close',
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs || ADVISORY_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Safety net for a hook that hangs. Unref'd on purpose: it never keeps the
+ * process alive by itself, but it still fires if something else (a stuck
+ * socket) is holding the event loop open.
+ */
+export function armExitGuard(ms = 4000) {
+  const timer = setTimeout(() => process.exit(0), ms);
+  timer.unref?.();
+  return timer;
+}
+
+/**
+ * End the hook successfully.
+ *
+ * Deliberately does NOT call process.exit(): tearing the process down while a
+ * TLS socket is still closing crashes Node on Windows (0xC0000409), and a
+ * crashed hook is a non-zero exit, which Claude Code surfaces as an error
+ * notice in the agent's transcript — exactly the noise these hooks promise
+ * never to make. Requests are sent with `connection: close`, so the loop
+ * drains on its own; armExitGuard covers the case where it doesn't.
+ */
+export function finish() {
+  process.exitCode = 0;
+}
+
+/** Print a hook JSON response and finish once stdout has flushed. */
+export function emitAndExit(payload) {
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  finish();
+}
+
+// ── collision advice ────────────────────────────────────────────────────────
+//
+// Everything below is pure string work over the /check response the caller has
+// already fetched: no network, no repo reads, no dependencies. It runs between
+// an agent asking to edit a file and the edit happening, so it stays that cheap.
+//
+// The point of this code is not to announce that a file was touched. It is to
+// change what the agent does next, which means every message has to answer
+// three questions the old one-line advisory left open: what exactly changed,
+// whether that change is in this agent's working tree, and what a good
+// adaptation looks like without leaving the task.
+
+/**
+ * A write this recent means my copy of the file is probably behind theirs.
+ *
+ * It used to double as "and they are still inside the file", which is a guess
+ * this hook has no business making on a timestamp alone. Since presence arrived
+ * that second question has its own answer and its own axis (see classify); this
+ * constant now only bounds the first one.
+ */
+const ACTIVE_MINUTES = 5;
+
+/**
+ * Weakest first — the index in this array *is* the severity, and it is also the
+ * order buildCollisionAdvice uses to pick which of several teammates gets the
+ * full paragraph.
+ *
+ * `stale` sits above `parallel` on purpose. A stale read fails inside this very
+ * edit and nothing catches it: the `old_string` either misses, or it matches
+ * and silently reverts a teammate's work into a diff nobody is reviewing yet. A
+ * parallel edit fails later, at a merge, where git and a human are both looking
+ * at it. Between "wrong now, unseen" and "wrong later, seen", the first one
+ * deserves the reader's attention first.
+ */
+export const ADVICE_LEVELS = ['nearby', 'recent', 'parallel', 'stale', 'active'];
+
+/** How long one acknowledgement keeps covering edits to the same file. */
+export const ACK_TTL_MS = 10 * 60_000;
+
+/** Shorter than this is a reflex, not a judgement. */
+export const ACK_MIN_REASON = 25;
+
+/** Deliberately unmistakable, so "did you actually replace it" needs no heuristics. */
+export const ACK_PLACEHOLDER = 'WHY-THIS-EDIT-STILL-NEEDS-TO-HAPPEN';
+
+/** Stands in for a holder the server could not name. Grounds nothing — see ackGrounding. */
+const ANON_DEVELOPER = 'a teammate';
+
+/** Collapse whitespace, cap length, and turn anything non-string into ''. */
+function clean(value, max) {
+  if (typeof value !== 'string') return '';
+  const text = value.replace(/\s+/g, ' ').trim();
+  if (!text) return '';
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** Every name that reaches a sentence is a declaration name, so it looks like one. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/**
+ * Symbol names, from anywhere: the server's lists and our own re-parse of
+ * change_summary both land here.
+ *
+ * The identifier check is the load-bearing part. These names are interpolated
+ * into sentences that tell an agent what not to rename, so a value that is not
+ * a declaration name is not a weaker name — it is a wrong sentence, and the
+ * only safe thing to do with it is drop it.
+ */
+function nameList(values, max = 3) {
+  const names = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const name = clean(value, 60);
+    if (name && IDENTIFIER.test(name) && !names.includes(name)) names.push(name);
+    if (names.length >= max) break;
+  }
+  return names;
+}
+
+/**
+ * "…, touching deletedAt, User" / "…, defining greet" — the names
+ * summarizeChange left behind, when the server has nothing better.
+ *
+ * change_summary is not a wire format we control: the reporting hook appends an
+ * override note to it (see composeSummary), and a future writer may append
+ * something else. So the tail is cut at the first bracketed note before it is
+ * read as a comma list, and nameList drops whatever still isn't an identifier.
+ */
+function namesFromSummary(summary) {
+  const match = /\b(?:touching|defining)\s+(.+)$/.exec(summary);
+  if (!match) return [];
+  return nameList(match[1].split(' [')[0].split(','));
+}
+
+function joinNames(names) {
+  if (names.length <= 1) return names[0] || '';
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+function whenPhrase(minutes) {
+  if (minutes === null) return 'recently';
+  if (minutes <= 0) return 'seconds ago';
+  return `${minutes} min ago`;
+}
+
+/**
+ * Flatten one Holder into the facts the message shapes read, with every field
+ * defaulted. A field the server never sent must produce a shorter sentence,
+ * never the word "undefined".
+ *
+ * `overlapping_symbols` / `symbols` are the seam for richer detection: when the
+ * server starts reporting which declarations actually collided, they arrive
+ * here and both the wording and the severity pick them up with no other change.
+ * Until then the names summarizeChange already writes into change_summary stand
+ * in — same slot, weaker evidence, so they inform wording but never severity.
+ */
+export function holderFacts(holder, file, myBranch) {
+  const h = holder && typeof holder === 'object' ? holder : {};
+  const developer = clean(h.developer, 80) || ANON_DEVELOPER;
+  const theirFile = clean(h.file_path, 300) || file;
+  const branch = clean(h.branch, 120);
+  const mine = clean(myBranch, 120);
+  const change = clean(h.change_summary, 160);
+  const minutes =
+    typeof h.minutes_ago === 'number' && Number.isFinite(h.minutes_ago) && h.minutes_ago >= 0
+      ? Math.round(h.minutes_ago)
+      : null;
+
+  // SEAM (feat/semantic-conflicts × this branch): detection now does report
+  // which declarations collided. `Holder.symbols` is the *overlap* — the names
+  // both sides touched — and the server says so out loud with match_kind
+  // 'symbol' / confidence 'high'. That is the confirmed evidence
+  // `overlapping_symbols` was reserved for, so it feeds severity too. Without
+  // that signal `symbols` stays what this file always assumed: a weaker claim
+  // that shapes the wording and never the level.
+  const declared = nameList(h.overlapping_symbols);
+  const matchKind = clean(h.match_kind, 20);
+  const confirmed = matchKind === 'symbol' || h.confidence === 'high' ? nameList(h.symbols) : [];
+  const overlapping = declared.length ? declared : confirmed;
+  const reported = overlapping.length ? overlapping : nameList(h.symbols);
+  const touched = reported.length ? reported : namesFromSummary(change);
+
+  // An unknown branch is treated as "same tree" on purpose. That picks the
+  // re-read-the-file advice, which is cheap and harmless when wrong; the
+  // cross-branch advice tells the agent that re-reading is pointless, which is
+  // not harmless when wrong.
+  const sameFile = theirFile === file;
+  const sameTree = !branch || !mine || branch === mine;
+
+  const facts = {
+    developer,
+    who: `${developer}'s agent`,
+    file,
+    theirFile,
+    sameFile,
+    branch,
+    mine,
+    sameTree,
+    minutes,
+    when: whenPhrase(minutes),
+    hint: clean(h.task_hint, 200),
+    change,
+    touched,
+    overlapping,
+    // How the server matched this holder to our file: 'symbol' | 'file' | 'dir'.
+    matchKind,
+    // Whether this teammate is still around: 'active' | 'idle' | 'stale' |
+    // 'ended', or '' from a server that predates presence — in which case the
+    // timestamp is all we have and every decision below falls back to it.
+    //
+    // This used to be decoration: a trailing sentence on a message whose level
+    // had already been decided without it. It now decides whether the loudest
+    // level's headline claim can be made at all. See classify.
+    presence: clean(h.presence, 20),
+    presenceLabel: clean(h.presence_label, 200),
+    // Bound to this teammate's *specific* write, so an acknowledgement of it
+    // cannot double as standing permission. Falls back to a stable string when
+    // an older server sends no timestamp — see ackToken.
+    stamp: clean(h.last_touched, 40) || 'unknown',
+  };
+  // Confirmed at the declaration rather than inferred from the path: either the
+  // server named the overlapping symbols, or it told us it matched by symbol at
+  // all. Hoisted onto the facts because two separate decisions now turn on the
+  // same evidence — the promotion in classify, and classify's refusal to let
+  // presence take that promotion back again.
+  facts.symbolConfirmed = facts.overlapping.length > 0 || facts.matchKind === 'symbol';
+  facts.level = classify(facts);
+  return facts;
+}
+
+/**
+ * "Presumed gone" is deliberately narrower than "not active".
+ *
+ * `idle` is excluded. The server's default active window is two minutes, which
+ * is shorter than a single agent turn — a teammate reading the diff their agent
+ * just produced is `idle`. Demoting on that would demote most real collisions
+ * and leave the loud level for almost nothing; and it would be wrong on the
+ * merits, because `idle` means the session is open and the person is at the
+ * desk. They will be surprised by a rewrite under them, which is exactly what
+ * ACTIVE COLLISION exists to say.
+ *
+ * `stale` and `ended` are the two states that mean the desk is empty. They are
+ * not equally well known — one is a report and the other is a timeout, and
+ * absenceClause keeps them apart in the text — but neither of them supports the
+ * claim that somebody is in this file right now, and that claim is the only
+ * thing being withdrawn.
+ */
+function teammateGone(f) {
+  return f.presence === 'stale' || f.presence === 'ended';
+}
+
+/**
+ * The whole severity model, in one function, so a reviewer can argue with the
+ * design rather than reconstruct it from branches.
+ *
+ * There are two axes, and they are genuinely independent.
+ *
+ * Axis 1 — *my working tree*. Is their change already in the bytes I am about
+ * to edit? Same branch means yes, and the failure is a stale read: my
+ * `old_string` no longer matches, or worse it does match and quietly reverts
+ * them. A different branch means no, re-reading cannot help, and the failure is
+ * a merge conflict instead. Confirmed symbol overlap sharpens this axis rather
+ * than replacing it: it says the collision is at a declaration, so which file
+ * that declaration lives in stops being the interesting question.
+ *
+ * Axis 2 — *the other agent*. Are they still there? That is a fact about them,
+ * not about my tree. A teammate can have gone home an hour ago and their change
+ * still be the exact thing that breaks this edit.
+ *
+ *   evidence \ them        | here, or unknown | presumed gone
+ *   -----------------------+------------------+---------------
+ *   confirmed symbol,      | active           | active
+ *     same tree            |                  |  (never demoted)
+ *   confirmed symbol,      | parallel         | parallel
+ *     other branch         |                  |
+ *   same file, same tree,  | active           | stale
+ *     write <= 5 min       |                  |
+ *   same file,             | parallel         | parallel
+ *     other branch         |                  |
+ *   same file, same tree,  | recent           | recent
+ *     write > 5 min        |                  |
+ *   neighbouring file      | nearby           | nearby
+ *
+ * Only one row moves under axis 2, and that is the model rather than an
+ * omission. ACTIVE COLLISION is the only level whose headline is a claim about
+ * a *person*: someone is in this file right now and will be surprised by what
+ * you do. Once they have closed the laptop that sentence is simply false, and
+ * a reader who catches the loudest label asserting something false learns to
+ * discount the label — which costs us the cases where it is true, and those are
+ * the ones that have to land. The other three levels claim nothing about anyone
+ * being present: PARALLEL EDIT is a statement about two branches, RECENT EDIT
+ * already says out loud that they have likely moved on, NEARBY EDIT asks for
+ * nothing at all. Presence has nothing to withdraw from any of them, so it does
+ * not touch them.
+ *
+ * One asymmetry is load-bearing and easy to miss. Presence is computed per
+ * *developer* — the server folds all of one person's sessions together — so
+ * "alice is active" does not mean alice is active *in this file*; she may be
+ * three packages away. Absence generalises downwards and presence does not:
+ * silence everywhere really does imply silence here, while activity somewhere
+ * implies nothing about here. So presence may only ever take a level away. It
+ * must never add one, and nothing below tries to: a cold 25-minute-old write
+ * from someone who is busy elsewhere stays RECENT EDIT.
+ */
+export function classify(facts) {
+  // A symbol match is the server telling us it found the collision by the
+  // declaration, not by the path. It outranks the directory heuristic below
+  // even if every name was dropped on the way in — the match kind is the
+  // evidence, the names are only how we word it.
+  if (facts.symbolConfirmed) {
+    // Deliberately NOT gated on presence, unlike the same-file case below, and
+    // this is the one place the two axes are allowed to disagree.
+    //
+    // The loud level here was never earned by anybody being at a keyboard. It
+    // was earned by proof that the exact declaration this edit is about to
+    // write against was changed by someone else, and that proof does not lapse
+    // because its author went to lunch. Demoting it would invite precisely the
+    // wrong inference — "they are gone, so the signature I read is the current
+    // one" — which is false and expensive. SHAPES.active says as much in the
+    // text whenever the two signals point different ways.
+    return facts.sameTree ? 'active' : 'parallel';
+  }
+  if (!facts.sameFile) return 'nearby';
+  if (!facts.sameTree) return 'parallel';
+  if (facts.minutes === null || facts.minutes > ACTIVE_MINUTES) return 'recent';
+
+  // WAS: 'active', unconditionally, with presence appended afterwards as a
+  // trailing sentence that changed nothing. NOW: 'active' only while there is
+  // somebody there to collide with.
+  //
+  // Note what is *not* demoted with it. Their write is in this working tree
+  // either way, so STALE READ carries the identical re-read imperative; that is
+  // why the demotion target is a new level rather than 'recent', whose "low
+  // urgency… they have likely moved on" would have thrown away the true half of
+  // the message along with the false half. Only the social claim is dropped.
+  //
+  // Under the old behaviour, an agent shown ACTIVE COLLISION for a teammate who
+  // shut their laptop twenty minutes ago would conclude that another agent was
+  // writing into this file concurrently — and would spend real effort avoiding
+  // a live conflict that cannot happen, while quietly learning that the loudest
+  // label is issued for absent people.
+  return teammateGone(facts) ? 'stale' : 'active';
+}
+
+function branchPhrase(f) {
+  if (f.branch && f.mine && f.branch === f.mine) return ` on your branch (${f.branch})`;
+  if (f.branch && f.mine) return ` on branch ${f.branch} (you are on ${f.mine})`;
+  if (f.branch) return ` on branch ${f.branch}`;
+  return '';
+}
+
+function taskPhrase(f, showHints) {
+  return showHints && f.hint ? `, while working on '${f.hint}'` : '';
+}
+
+function changePhrase(f) {
+  return f.change ? ` (${f.change})` : '';
+}
+
+function overlapPhrase(f) {
+  return f.overlapping.length ? ` You are both changing ${joinNames(f.overlapping)}.` : '';
+}
+
+/** The path, plus a note when it isn't the file this agent is about to edit. */
+function where(f) {
+  if (f.sameFile) return f.file;
+  // SEAM (feat/semantic-conflicts): a holder in another file used to mean only
+  // one thing — a directory neighbour. It can now also be a file this one
+  // depends on, which is a different sentence and a different reason to care.
+  if (f.matchKind === 'symbol') {
+    const names = joinNames(f.overlapping) || joinNames(f.touched);
+    return names ? `${f.theirFile}, which ${f.file} depends on for ${names}` : f.theirFile;
+  }
+  return `${f.theirFile} (a different file in the same directory)`;
+}
+
+/** What the timestamp alone lets us say about whether they are still in there. */
+function inhabits(f) {
+  if (f.minutes === null || f.minutes > ACTIVE_MINUTES) return 'has open work in';
+  return f.minutes <= 1 ? 'is inside' : 'is working in';
+}
+
+/**
+ * The verb. "alice is inside this file" is a lie once alice has gone home, and
+ * it is costlier here than on the dashboard because the agent acts on it. When
+ * the server actually knows whether she is still there, its answer outranks the
+ * timestamp guess `inhabits` makes on its own.
+ *
+ * This softens for `idle` too, which teammateGone deliberately does not demote.
+ * That is not an inconsistency: four minutes of silence is not enough to move
+ * ACTIVE COLLISION off a file, and it is easily enough to make "is inside"
+ * an overstatement. Wording is cheap to be careful with; the level is not.
+ */
+function presence(f) {
+  if (f.presence && f.presence !== 'active') return 'has open work in';
+  return inhabits(f);
+}
+
+/**
+ * Its own sentence, appended once, for a teammate the server knows is no longer
+ * active. An active one needs none — "last write 2 min ago" already says they
+ * are there.
+ *
+ * STALE READ is excluded because it puts the very same fact where it now
+ * belongs. Presence stopped being a footnote to that message and became the
+ * reason for its level, so absenceClause states it up front, next to the
+ * headline it is qualifying, instead of trailing behind the whole paragraph.
+ */
+function presenceSentence(f) {
+  if (f.level === 'stale') return '';
+  if (!f.presenceLabel || !f.presence || f.presence === 'active') return '';
+  return ` ${f.developer} ${f.presenceLabel}.`;
+}
+
+/**
+ * Why this is a stale file rather than a live collision — and, just as
+ * important, how well we actually know that.
+ *
+ * `ended` and `stale` both empty the desk, but one is a report from the client
+ * and the other is this server giving up waiting, and an advisory that renders
+ * them identically is dressing a guess up as a fact. The difference changes
+ * what a reader should do: an agent that believes alice is definitely gone will
+ * happily restructure the file, whereas one told only that the board lost sight
+ * of her should keep the edit small and say what it did.
+ */
+function absenceClause(f) {
+  if (f.presence === 'ended') {
+    return (
+      ` ${f.developer} ${f.presenceLabel || 'ended their session'} — reported by their own client, not inferred,` +
+      ` so there is no second agent in this file to surprise; what is left is your copy of it.`
+    );
+  }
+  return (
+    ` ${f.developer} ${f.presenceLabel || 'has not been heard from in a while'}. That is a timeout on the board's` +
+    ` clock rather than a goodbye — nobody reported leaving — so treat the file as stale, not the desk as certainly` +
+    ` empty: keep this edit small enough to survive them coming back.`
+  );
+}
+
+/**
+ * The one case where the two axes contradict each other, said out loud instead
+ * of resolved silently.
+ *
+ * Presence says nobody is there; the server says you are both changing the same
+ * declaration. classify obeys the second and keeps the loud level, so the text
+ * owes the reader a reason — otherwise ACTIVE COLLISION over an absent teammate
+ * looks exactly like the bug this branch was written to remove, and the next
+ * person to notice will "fix" it.
+ */
+function confirmedDespiteAbsenceSentence(f) {
+  if (!f.symbolConfirmed || !teammateGone(f)) return '';
+  const names = joinNames(f.overlapping) || joinNames(f.touched);
+  return (
+    ` ${f.developer} is not at the keyboard, and this is still a collision rather than a stale file:` +
+    ` the overlap is confirmed at ${names ? `${names},` : 'the declaration,'} and a declaration someone else` +
+    ` has already changed does not become safe to write against because its author stepped away.`
+  );
+}
+
+/**
+ * What goes wrong when their change *is* in your tree, and what fixes it. The
+ * cross-file variant only arises once detection reports symbol overlap: then
+ * the risk isn't a stale edit, it's writing a call against a shape that moved.
+ */
+function staleSentence(f) {
+  if (f.sameFile) {
+    return (
+      ` Their write is already in your working tree, so whatever you read from this file earlier is out of date.` +
+      ` Re-read ${f.file} now and rebuild this edit against what is actually there:` +
+      ` a stale old_string either fails to match or quietly reverts their change.`
+    );
+  }
+  return (
+    ` Their write is already in your working tree. Read ${f.theirFile} before you finish this edit —` +
+    ` you are about to write against ${joinNames(f.overlapping) || 'code'} as it used to be, and it has moved.`
+  );
+}
+
+/** What goes wrong when their change is on a branch you cannot see. */
+function mergeSentence(f) {
+  if (f.sameFile) {
+    return (
+      ` Their version isn't in your working tree, so re-reading the file won't show it —` +
+      ` this is a merge conflict forming, not a stale read.` +
+      ` Keep this edit additive: preserve the names and signatures that are already exported,` +
+      ` don't reformat or reorder the file, and don't rewrite regions your task doesn't require.`
+    );
+  }
+  return (
+    ` Their version isn't in your working tree, so ${f.theirFile} still shows you the old` +
+    ` ${joinNames(f.overlapping) || 'definitions'} here. Write against the shape you can actually see,` +
+    ` and keep the change additive so both sides survive the merge.`
+  );
+}
+
+/**
+ * One shape per level. They differ in what they claim, what they ask for, and
+ * how long they are: a weak signal that spends a paragraph of context reads as
+ * urgent whatever the label says, so the weakest shape is one sentence.
+ *
+ * STALE READ is the exception to "louder is longer", and knowingly so. It asks
+ * for exactly what ACTIVE COLLISION asks for about the working tree and less
+ * than it asks for about the teammate, but it spends extra words saying what is
+ * *not* known about that teammate. Hedging is the opposite of a demand, so it
+ * does not read as escalation; the label carries the volume.
+ */
+const SHAPES = {
+  active: (f, showHints) =>
+    `[AgentMash: ACTIVE COLLISION] ${f.who} ${presence(f)} ${where(f)} — last write ${f.when}` +
+    `${branchPhrase(f)}${taskPhrase(f, showHints)}${changePhrase(f)}.${overlapPhrase(f)}` +
+    confirmedDespiteAbsenceSentence(f) +
+    staleSentence(f) +
+    (f.touched.length
+      ? ` Leave ${joinNames(f.touched)} named and shaped as ${f.developer} left ${f.touched.length > 1 ? 'them' : 'it'} — that is what they just changed.`
+      : '') +
+    ` If your task genuinely needs those same lines, change them and say so in your reply, so the overlap is visible.`,
+
+  // Everything ACTIVE COLLISION says about your working tree, and nothing it
+  // says about a person being in the room with you. The headline verb is past
+  // tense and impersonal for that reason: "left this file changed" is a fact
+  // about the file, where "is working in" was a claim about someone who is not.
+  //
+  // WAS: STALE FILE. Renamed, and only the label moved — the level, the demotion
+  // rule and every sentence below are unchanged. Two things were wrong with the
+  // old word, and both are about how the *pair* of labels reads:
+  //
+  // Against RECENT EDIT it inverted the clock. Both fire on the same file in the
+  // same tree with the teammate absent; this one covers the write from a minute
+  // ago and RECENT EDIT covers the one from twenty-five. Read side by side, the
+  // label containing "RECENT" was the older and quieter case, so a reader
+  // ranking two adjectives about time ranked them backwards. "Read" is not a
+  // word about time at all: it names *whose* state is out of date, and the
+  // ordering then follows from the subject — a defect in what you know outranks
+  // a fact about when somebody typed — instead of from which adjective sounds
+  // fresher.
+  //
+  // And it named the wrong noun. The file on disk is not stale; it is the newest
+  // version there is. What is stale is the copy of it this agent read into
+  // context, which is also the only thing the message asks it to fix. Naming the
+  // file invites "the file is old, so I can overwrite it"; naming the read
+  // invites "re-read it", which is the whole ask.
+  //
+  // Considered and rejected: renaming RECENT EDIT instead (it is accurate, and
+  // it is the level nobody misreads on its own), and folding this level back
+  // into RECENT EDIT (it would drop the re-read imperative, which is still true
+  // — their write is in your tree either way).
+  stale: (f, showHints) =>
+    `[AgentMash: STALE READ] ${f.who} left ${where(f)} changed — last write ${f.when}` +
+    `${branchPhrase(f)}${taskPhrase(f, showHints)}${changePhrase(f)}.${overlapPhrase(f)}` +
+    absenceClause(f) +
+    staleSentence(f) +
+    (f.touched.length
+      ? ` Leave ${joinNames(f.touched)} named and shaped as ${f.developer} left ${f.touched.length > 1 ? 'them' : 'it'} — that is what they changed.`
+      : '') +
+    ` If you change those lines anyway, say so in your reply: ${f.developer} is not here to watch it happen,` +
+    ` so the reply is the only record they will get.`,
+
+  parallel: (f, showHints) =>
+    `[AgentMash: PARALLEL EDIT] ${f.who} modified ${where(f)} ${f.when}` +
+    `${branchPhrase(f)}${taskPhrase(f, showHints)}${changePhrase(f)}.${overlapPhrase(f)}` +
+    mergeSentence(f) +
+    (f.touched.length ? ` Assume ${joinNames(f.touched)} moved under you.` : '') +
+    ` If you have to change something they touched, say so in your reply so the divergence is visible before the merge.`,
+
+  recent: (f, showHints) =>
+    `[AgentMash: RECENT EDIT] ${f.who} modified ${where(f)} ${f.when}` +
+    `${branchPhrase(f)}${taskPhrase(f, showHints)}${changePhrase(f)}.` +
+    ` Low urgency: their write is already in your working tree and they have likely moved on.` +
+    ` Re-read ${f.file} first only if this edit depends on lines they may have moved.` +
+    (f.touched.length ? ` Otherwise carry on, and just don't rename or delete ${joinNames(f.touched)}.` : ' Otherwise carry on.'),
+
+  nearby: (f, showHints) =>
+    `[AgentMash: NEARBY EDIT] ${f.who} modified ${f.theirFile} ${f.when}` +
+    `${branchPhrase(f)}${taskPhrase(f, showHints)}${changePhrase(f)} —` +
+    ` a different file in the same directory as ${f.file}, so nothing of yours is stale.` +
+    ` No action needed unless your edit changes something this directory shares.`,
+};
+
+/**
+ * A short id for one specific collision: this teammate, this file, this write.
+ *
+ * FNV-1a rather than node:crypto, because this is not a secret — anyone who can
+ * append to the ack log can also just unset AGENTMASH_STRICT. Its only job is
+ * specificity: acknowledging alice's 14:32 write to user.ts must not be
+ * expressible as a standing permission to ignore everyone.
+ */
+export function ackToken(facts) {
+  const seed = `${facts.developer}|${facts.theirFile}|${facts.stamp}|${facts.branch}`;
+  let a = 0x811c9dc5;
+  let b = 0x9e3779b9;
+  for (let i = 0; i < seed.length; i++) {
+    const c = seed.charCodeAt(i);
+    a = Math.imul(a ^ c, 0x01000193) >>> 0;
+    b = Math.imul(b + c, 0x85ebca6b) >>> 0;
+  }
+  return `ack_${a.toString(36)}${b.toString(36)}`;
+}
+
+/**
+ * Pick the shape, render it, and hand back everything the caller needs to
+ * decide what to do with it. Holders beyond the first get one clause each:
+ * three full paragraphs about one file is how a useful signal becomes noise.
+ */
+export function buildCollisionAdvice({ file, holders, branch, showHints = true }) {
+  const list = (Array.isArray(holders) ? holders : [])
+    .filter((h) => h && typeof h === 'object')
+    .map((h) => holderFacts(h, file, branch));
+  if (list.length === 0) return null;
+
+  list.sort(
+    (a, b) =>
+      ADVICE_LEVELS.indexOf(b.level) - ADVICE_LEVELS.indexOf(a.level) ||
+      (a.minutes ?? Number.MAX_SAFE_INTEGER) - (b.minutes ?? Number.MAX_SAFE_INTEGER)
+  );
+
+  const top = list[0];
+  const others = list.slice(1, 3);
+  const tail = others.length
+    ? ` Also recently in this area: ${others.map((o) => `${o.developer} (${o.when})`).join(', ')}.`
+    : '';
+
+  return {
+    level: top.level,
+    file,
+    developer: top.developer,
+    token: ackToken(top),
+    grounding: ackGrounding(top),
+    text: SHAPES[top.level](top, showHints) + presenceSentence(top) + tail,
+  };
+}
+
+const REJECTIONS = {
+  placeholder: 'the placeholder was still in it, so it was not your own words',
+  thin: `it was under ${ACK_MIN_REASON} characters, which is not a judgement`,
+  ungrounded:
+    'it named nothing from this collision — not the teammate, not what they changed —' +
+    ' so it was a sentence that would have fitted any collision at all',
+  restated:
+    'it added nothing to what you were already told: it only echoed this collision and the task you are on,' +
+    ' and the question is not what you are doing but why theirs and yours can both stand',
+  recycled: 'you had already given that same reason for a different collision',
+  expired: `it was more than ${Math.round(ACK_TTL_MS / 60_000)} minutes old, and acknowledgements do not stay open`,
+};
+
+/** The particulars the block asks for by name, so the agent isn't guessing. */
+function requiredPhrase(advice) {
+  const named = (advice.grounding?.particulars || []).slice(0, 3);
+  if (!named.length) return `name ${advice.developer} and what they changed`;
+  return `name ${joinNames(named)} in it`;
+}
+
+/**
+ * The other half of strict mode: how an agent, working alone, gets past a block
+ * it has genuinely thought about — without the getting-past becoming automatic.
+ *
+ * Five things keep it from being a rubber stamp, and the text says all five out
+ * loud, because an agent that knows the override is recorded behaves
+ * differently from one that thinks it is free:
+ *   1. the token is bound to one teammate's one write to one file;
+ *   2. it dies when they write again, and expires after ACK_TTL_MS;
+ *   3. the reason is checked against the collision's own particulars — the
+ *      teammate, the declarations they changed, their file, their branch — so a
+ *      sentence that would have fitted any collision fits none;
+ *   4. it must add something to those particulars and to this agent's own task,
+ *      and a reason reused across collisions is rejected as the reflex it is;
+ *   5. the reason rides out on the next reported edit, so the teammate who was
+ *      overridden — and the dashboard — see that it happened and why.
+ *
+ * Guard 3 is not a lock and this file should not pretend otherwise: a model
+ * determined to proceed can read the advisory and write a plausible sentence
+ * about it. What it buys is that the sentence has to be *about this collision*,
+ * which cannot be produced without reading it, cannot be reused, and is wrong
+ * in a way the overridden teammate can see when it is not true. Guard 5 is what
+ * makes that cost real; guard 3 only makes it unavoidable.
+ */
+/**
+ * A claim is stated intent — a teammate's agent has said it is taking this
+ * scope — so it deserves its own shape rather than being dressed up as an edit
+ * that has not happened. Nothing in this agent's tree will show it yet; the
+ * whole point is that the message arrives before there is anything to see.
+ *
+ * Claims never block, even in strict mode: blocking on what someone *intends*
+ * to do is how a coordination layer becomes the thing people route around.
+ */
+export function buildClaimAdvice({ file, claims, showHints = true }) {
+  const list = (Array.isArray(claims) ? claims : []).filter(
+    (c) => c && typeof c === 'object' && typeof c.developer === 'string'
+  );
+  if (list.length === 0) return null;
+
+  const now = Date.now();
+  const minutesAgo = (ts) => (Number.isFinite(ts) ? Math.max(0, Math.round((now - ts) / 60_000)) : null);
+  const minutesLeft = (ts) => (Number.isFinite(ts) ? Math.max(0, Math.round((ts - now) / 60_000)) : null);
+
+  const scopeOf = (c) => {
+    const covering = (c.overlap?.paths?.length ? c.overlap.paths : c.paths || []).find(Boolean);
+    if (!covering || covering === file) return 'this file';
+    if (file.startsWith(`${covering}/`)) return `${covering}/ — which includes ${file}`;
+    const shared = c.overlap?.symbols?.length ? ` (you share ${c.overlap.symbols.slice(0, 3).join(', ')})` : '';
+    return `${covering}${shared}`;
+  };
+  const taskOf = (c) => (showHints && c.task ? ` for '${c.task}'` : '');
+
+  const top = list[0];
+  const ago = minutesAgo(top.created_ts);
+  const left = minutesLeft(top.expires_ts);
+  const when =
+    ago === null ? '' : ` — claimed ${ago === 0 ? 'just now' : `${ago} min ago`}${left !== null ? `, ${left} min left` : ''}`;
+
+  const others = list.slice(1, 3);
+  const tail = others.length
+    ? ` Also claimed by ${others.map((o) => `${o.developer}${taskOf(o)}`).join(' and ')}.`
+    : '';
+
+  const text =
+    `[AgentMash: CLAIMED] ${top.developer}'s agent has claimed ${scopeOf(top)}${taskOf(top)}${when}.` +
+    ` They may not have written to it yet, so nothing in your working tree shows this.` +
+    ` If your change is part of their task, leave it to them or build on what they land;` +
+    ` if it is unrelated, keep out of the lines their task will touch,` +
+    ` and say in your reply that ${top.developer} has this claimed so the overlap is visible.` +
+    tail;
+
+  return { level: 'claimed', file, developer: top.developer, text };
+}
+
+/**
+ * What an agent is handed when it is about to finish having collided with a
+ * teammate: what they changed and why, how to see their version, and what to
+ * do with the reconciled result — which depends on the room's reconcile mode.
+ *
+ * The server never sees code, so this cannot merge anything. It briefs the
+ * one process that has the code and an agent attached to it, and tells it not
+ * to stop yet. Used by the Stop hook (as a block reason) and by the
+ * get_collisions MCP tool (as an answer).
+ */
+export function buildReconciliationBrief({ collisions, mode = 'approve', showHints = true, heading } = {}) {
+  const list = (Array.isArray(collisions) ? collisions : []).filter(
+    (c) => c && typeof c.file_path === 'string' && Array.isArray(c.theirs) && c.theirs.length > 0
+  );
+  if (list.length === 0 || mode === 'off') return null;
+
+  const lines = [];
+  lines.push(
+    heading ??
+      `[AgentMash: RECONCILE BEFORE YOU FINISH] ${
+        list.length === 1
+          ? 'A file you changed in this session was also changed by a teammate.'
+          : `${list.length} files you changed in this session were also changed by teammates.`
+      } Do not end here — reconcile first.`
+  );
+
+  let exampleRef = null;
+  for (const c of list.slice(0, 4)) {
+    const mine = c.mine || {};
+    lines.push('');
+    lines.push(`• ${c.file_path} — also changed by ${c.theirs.map((t) => t.developer).join(' and ')}.`);
+    for (const t of c.theirs.slice(0, 2)) {
+      const when = typeof t.minutes_ago === 'number' ? (t.minutes_ago === 0 ? 'just now' : `${t.minutes_ago} min ago`) : 'recently';
+      let branch = '';
+      if (t.branch && mine.branch && t.branch === mine.branch) branch = ` on your branch (${t.branch})`;
+      else if (t.branch) branch = ` on branch ${t.branch}${mine.branch ? ` — you are on ${mine.branch}` : ''}`;
+      if (t.branch && (!mine.branch || t.branch !== mine.branch) && !exampleRef) exampleRef = t.branch;
+      const task = showHints && t.task_hint ? ` while working on '${t.task_hint}'` : '';
+      const change = t.change_summary ? ` (${t.change_summary})` : '';
+      lines.push(`  ${t.developer}: last write ${when}${branch}${task}${change}.`);
+    }
+    if (Array.isArray(c.shared_symbols) && c.shared_symbols.length) {
+      lines.push(
+        `  You both touched ${c.shared_symbols.slice(0, 5).join(', ')} — that is where a merge is most likely to break.`
+      );
+    }
+    if (showHints && mine.task_hint) {
+      lines.push(`  Your side: '${mine.task_hint}'${mine.change_summary ? ` (${mine.change_summary})` : ''}.`);
+    }
+  }
+  if (list.length > 4) lines.push(`…and ${list.length - 4} more.`);
+
+  const ref = exampleRef ? `origin/${exampleRef}` : 'origin/<their-branch>';
+  lines.push('');
+  lines.push('How to reconcile:');
+  lines.push(
+    `1. See their version: \`git fetch origin\`, then \`git log --oneline ${ref} -- <file>\` and ` +
+      `\`git diff HEAD...${ref} -- <file>\`. If you are on the same branch, \`git pull --rebase\` and resolve ` +
+      'the conflicts git reports.'
+  );
+  lines.push(
+    '2. Merge so that BOTH intents survive: keep the names and shapes they introduced, keep what your task ' +
+      'needed, and run the tests.'
+  );
+  if (mode === 'auto') {
+    lines.push(
+      '3. This room reconciles automatically: commit the reconciled result the way this repository normally ' +
+        'commits, and push if that is its flow.'
+    );
+    lines.push(
+      '4. Call the AgentMash tool `mark_resolved` with the file and outcome "merged" — or, if the tool is not ' +
+        'available, say clearly in your reply what you merged.'
+    );
+  } else {
+    lines.push(
+      '3. This room needs a human to approve reconciliations: commit on a branch named reconcile/<short-file-name> ' +
+        'and open a pull request (for example `gh pr create`) titled "Reconcile <file>: <you> + <them>", ' +
+        'describing both changes and what you kept. Do NOT push the reconciled result to the shared branch directly.'
+    );
+    lines.push(
+      '4. Call the AgentMash tool `mark_resolved` with the file, outcome "pr" and the PR URL — or, if the tool ' +
+        'is not available, put the URL in your reply.'
+    );
+  }
+  lines.push(
+    '5. If, after looking, the two changes do not actually conflict, say so in your reply and call ' +
+      '`mark_resolved` with outcome "no_conflict".'
+  );
+  lines.push('Then finish. You will not be asked about these files again in this session.');
+  return lines.join('\n');
+}
+
+export function buildStrictBlock(advice, { ackDir, ackPath, rejected } = {}) {
+  const minutes = Math.round(ACK_TTL_MS / 60_000);
+  const parts = [
+    advice.text,
+    '',
+    'AgentMash strict mode blocked this edit. The block is a checkpoint, not a veto:' +
+      ' if you have taken the above into account and this edit still has to happen,' +
+      ' acknowledge this specific collision and make the same edit again.',
+  ];
+  if (rejected && REJECTIONS[rejected]) {
+    parts.push(
+      '',
+      `Your previous acknowledgement was not accepted: ${REJECTIONS[rejected]}.`
+    );
+  }
+  parts.push(
+    '',
+    'Run exactly this, with the placeholder replaced by your own one-sentence reason:',
+    '',
+    `  mkdir -p "${ackDir}" && echo "${advice.token} ${ACK_PLACEHOLDER}" >> "${ackPath}"`,
+    '',
+    `That token covers only ${advice.file} and only ${advice.developer}'s current write:` +
+      ` if they write again it changes and you are stopped again, and it expires ${minutes} minutes after you first use it.` +
+      ` Your reason is attached to your next reported edit, so ${advice.developer} and the room dashboard will see that you overrode this, and why.`,
+    `Do not acknowledge on reflex. The reason is checked against this collision, not counted: ${requiredPhrase(advice)}, and say why` +
+      ` ${advice.developer}'s change and yours can both stand.` +
+      ` A sentence that only restates your task ("I need to edit this file to complete my assigned task") names none of that and will be refused,` +
+      ' and so will one that repeats those names back with nothing of your own added.' +
+      ` If you cannot say something that specific, stop and ask the user instead.`
+  );
+  return parts.join('\n');
+}
+
+// ── acknowledgement log ─────────────────────────────────────────────────────
+//
+// A plain append-only text file the agent writes with one shell command we hand
+// it verbatim. Read only in strict mode, and only after /check has already
+// reported a conflict — the ordinary edit path never opens it.
+
+export function ackFile(sessionId) {
+  return scratchFile(`ack-${String(sessionId || 'unknown').replace(/[^A-Za-z0-9._-]/g, '_')}.log`);
+}
+
+/** Lines are "<token> <reason>"; anything else in the file is ignored. */
+export function readAcks(sessionId) {
+  let raw;
+  try {
+    raw = fs.readFileSync(ackFile(sessionId), 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split(/\r?\n/).slice(-200)) {
+    const match = /^\s*(ack_[a-z0-9]+)\s+(.*\S)\s*$/i.exec(line);
+    if (match) entries.push({ token: match[1], reason: match[2].trim() });
+  }
+  return entries;
+}
+
+// Words that carry no claim. Only words of three characters or more are counted
+// at all, so this list only has to cover the longer connectives.
+const REASON_STOPWORDS = new Set(
+  ('the and but for not are was were this that with from have has had you your they their them its' +
+    ' been being will would can could should because into onto out off only also just than then there' +
+    ' here what which who whom while when where all any some each both same other about after before' +
+    ' over under again more most very still now does did doing don won yet already need needs').split(/\s+/)
+);
+
+/** Words a claim is made of: three characters or more, and not a connective. */
+function contentWords(text) {
+  const words = new Set();
+  for (const word of String(text || '').toLowerCase().match(/[a-z0-9_$]+/g) || []) {
+    if (word.length >= 3 && !REASON_STOPWORDS.has(word)) words.add(word);
+  }
+  return words;
+}
+
+/** Domains and the like: parts of an identity that identify nobody. */
+const DEVELOPER_NOISE = new Set(['com', 'org', 'net', 'www', 'agent']);
+/** Branch names shared by every repo on earth ground nothing. */
+const GENERIC_BRANCHES = new Set(['main', 'master', 'trunk', 'dev', 'develop', 'default']);
+
+/**
+ * What a reason for *this* collision can be checked against.
+ *
+ * `terms` are the things an agent can only put in a sentence by having read the
+ * advisory: the teammate's name, the declarations the server says they changed,
+ * the file of theirs that is not the one being edited, the branch it is on.
+ * `particulars` are the same things in their original spelling, for the block
+ * message to ask for by name — the check is a forcing function for reading the
+ * collision, not a password to be guessed.
+ *
+ * A collision can offer nothing: an anonymous holder, same file, same branch, no
+ * symbols. Then there is nothing to check a reason against, and the honest thing
+ * is to check nothing rather than to demand a word that does not exist.
+ */
+export function ackGrounding(facts) {
+  const particulars = [];
+  const terms = new Set();
+  // A particular is only worth asking for if something about it is checkable:
+  // two-character fragments match every sentence, so they ground nothing.
+  const add = (display, matches) => {
+    const usable = matches.filter((m) => m && m.length >= 3);
+    if (!display || !usable.length || particulars.includes(display)) return;
+    particulars.push(display);
+    for (const m of usable) terms.add(m.toLowerCase());
+  };
+
+  for (const name of [...(facts.overlapping || []), ...(facts.touched || [])]) {
+    add(name, [name]);
+  }
+  if (facts.developer && facts.developer !== ANON_DEVELOPER) {
+    const lower = facts.developer.toLowerCase();
+    const parts = lower.split('@')[0].split(/[^a-z0-9]+/).filter((p) => !DEVELOPER_NOISE.has(p));
+    add(facts.developer, [lower, ...parts]);
+  }
+  if (!facts.sameFile && facts.theirFile) {
+    const base = facts.theirFile.split('/').pop();
+    add(base, [base, base.replace(/\.[^.]+$/, '')]);
+  }
+  if (facts.branch && facts.branch !== facts.mine && !GENERIC_BRANCHES.has(facts.branch.toLowerCase())) {
+    add(facts.branch, [facts.branch, facts.branch.split('/').pop()]);
+  }
+
+  return { terms: [...terms], particulars };
+}
+
+function isGrounded(reason, grounding) {
+  const terms = grounding?.terms || [];
+  if (!terms.length) return true; // nothing to check against — see ackGrounding
+  const lower = reason.toLowerCase();
+  return terms.some((term) => lower.includes(term));
+}
+
+/**
+ * True when the reason contributes nothing of its own — every word in it is
+ * either a particular of the collision it was just handed or a word from the
+ * agent's own task. "I must rename createUser, that is my task" is not an
+ * argument that the collision is acceptable; it is the premise restated.
+ */
+function isRestatement(reason, grounding, taskHint) {
+  const words = contentWords(reason);
+  if (words.size === 0) return true;
+  const known = contentWords(`${(grounding?.terms || []).join(' ')} ${taskHint || ''}`);
+  for (const word of words) {
+    if (!known.has(word)) return false;
+  }
+  return true;
+}
+
+/**
+ * A reason reduced to the claim it makes: content words, sorted. Deleting a
+ * full stop or reordering a clause produces the same signature, which is what
+ * the previous exact-string comparison could not survive.
+ */
+function reasonSignature(reason) {
+  return [...contentWords(reason)].sort().join(' ');
+}
+
+/**
+ * Does the log contain a usable acknowledgement of `token`? Returns the reason
+ * if so, and otherwise why the closest attempt was refused, so the next block
+ * message can say what to fix instead of repeating itself.
+ *
+ * `grounding` and `taskHint` are what makes this more than a length check: the
+ * reason is read against the collision the agent was just shown and against
+ * what the agent itself is doing. Both are optional, and absent means the
+ * corresponding test is skipped rather than failed — a check that cannot be
+ * satisfied would only teach the agent to disable strict mode.
+ */
+export function resolveAck(entries, token, { grounding, taskHint } = {}) {
+  const mine = entries.filter((e) => e.token === token);
+  if (mine.length === 0) return { ok: false, rejected: null };
+  const elsewhere = new Set(
+    entries.filter((e) => e.token !== token).map((e) => reasonSignature(e.reason))
+  );
+  let rejected = null;
+  for (const entry of mine) {
+    if (entry.reason.includes(ACK_PLACEHOLDER)) {
+      rejected = 'placeholder';
+      continue;
+    }
+    if (entry.reason.length < ACK_MIN_REASON) {
+      rejected = 'thin';
+      continue;
+    }
+    if (grounding && !isGrounded(entry.reason, grounding)) {
+      rejected = 'ungrounded';
+      continue;
+    }
+    if (grounding && isRestatement(entry.reason, grounding, taskHint)) {
+      rejected = 'restated';
+      continue;
+    }
+    // The same sentence filed under a second token is the signature of a habit,
+    // not of a decision taken twice.
+    if (elsewhere.has(reasonSignature(entry.reason))) {
+      rejected = 'recycled';
+      continue;
+    }
+    return { ok: true, reason: entry.reason, rejected: null };
+  }
+  return { ok: false, rejected };
+}
+
+/** The note rides in change_summary, which the server bounds at 300 characters. */
+const SUMMARY_MAX = 300;
+const OVERRIDE_NOTE_MAX = 140;
+
+/**
+ * Take the override note owed for `file`, if one is still owed. Called by the
+ * reporting hook, so the teammate who was overridden finds out through the
+ * channel they already watch instead of a new one.
+ */
+export function takeOverrideNote(cache, file) {
+  const entry = cache?.overrides?.[file];
+  if (!entry) return null;
+  delete cache.overrides[file];
+  if (!(Date.now() - (Number(entry.at) || 0) < ACK_TTL_MS)) return null;
+  return truncate(`[overrode ${entry.developer}: ${entry.reason}]`, OVERRIDE_NOTE_MAX);
+}
+
+/**
+ * Put the override note on the end of the edit summary without letting the pair
+ * exceed what the server will accept — a rejected event is a lost edit report,
+ * which costs the room more than a shortened sentence. The note is kept whole
+ * and the summary gets what is left, because the summary can always be
+ * recomputed from the next edit and the note cannot.
+ */
+export function composeSummary(summary, note) {
+  const base = summary ? String(summary) : '';
+  if (!note) return truncate(base, SUMMARY_MAX) || null;
+  const room = SUMMARY_MAX - note.length - 1;
+  const head = room > 0 ? truncate(base, room) : '';
+  return head ? `${head} ${note}` : note;
+}
+
+// ── symbol extraction ───────────────────────────────────────────────────────
+//
+// Why regexes and not a parser: these hooks are dependency-free files that
+// travel by `git pull`, and that is what makes teammate setup a single command.
+// A real TypeScript parse would make setup an install step, so it is out.
+//
+// The trade that buys back accuracy is precision over recall. `summarizeChange`
+// above matches *any* declaration keyword and so names locals — `i`, `res`,
+// `text` — which is fine for a sentence a human reads and useless for matching.
+// These extractors only claim a name when the line starts with `export`, which
+// on this repo's own source is 100% precise. Anything they cannot see becomes a
+// miss, never a false alarm, and a miss degrades to today's path matching.
+
+const SYMBOL_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs',
+]);
+
+// Caps, so a huge file can't bloat a URL or a POST body. The reference side
+// is the wider one: it is a whole file's imports plus exports, and it rides in
+// a query string, which is cheap. A single edit that changes 24 exported
+// symbols is already a rewrite, so the definition side stays tight.
+const MAX_REF_SYMBOLS = 60;
+const MAX_DEF_SYMBOLS = 24;
+/** Files past this size are skipped rather than read on the edit path. */
+const MAX_SOURCE_BYTES = 512 * 1024;
+/** Two-character names ("db", "id") match everything; the noise isn't worth it. */
+const MIN_SYMBOL_LENGTH = 3;
+/** Matches the server's bound, so nothing we send can be rejected for length. */
+const MAX_SYMBOL_LENGTH = 120;
+/** Past this many identical occurrences, placing an edit is guesswork. */
+const MAX_ATTRIBUTION_MATCHES = 8;
+
+/** True when this path is a language the extractors understand. */
+export function supportsSymbols(filePath) {
+  const m = /(\.[A-Za-z0-9]+)$/.exec(String(filePath || ''));
+  return Boolean(m) && SYMBOL_EXTENSIONS.has(m[1].toLowerCase());
+}
+
+// A scanner that reads raw text claims whatever *looks* like an export, and a
+// commented-out `export function` looks exactly like a live one. That phantom is
+// stored on the definition side and matches at `high` confidence — the loudest
+// thing this system says — so it is worth one linear pass to remove the whole
+// class: comment, string, regex and template-literal bodies are replaced by
+// spaces before any regex runs. Spaces and not deletion, because every offset
+// `regionEnd` and `enclosingDeclaration` work with is an offset into the
+// original text.
+
+/** Characters after which a `/` opens a regex literal rather than dividing. */
+const REGEX_MAY_FOLLOW = /[({[,;:=!&|?+\-*%~^<>]/;
+const REGEX_MAY_FOLLOW_KEYWORD = /\b(?:return|typeof|instanceof|in|of|new|delete|void|case|do|else|yield|await)$/;
+
+function blanked(span) {
+  return span.replace(/[^\n]/g, ' ');
+}
+
+/** Where a quoted string ends, or `start + 1` if it never closes on its line. */
+function quoteEnd(source, start) {
+  const quote = source[start];
+  for (let i = start + 1; i < source.length; i++) {
+    const c = source[i];
+    if (c === '\\') i++;
+    else if (c === quote) return i + 1;
+    else if (c === '\n') break;
+  }
+  return start + 1;
+}
+
+/**
+ * Where a regex literal ends, or -1 when this `/` is division. A regex cannot
+ * span a line, so an unterminated one is division and we leave the text alone —
+ * which bounds the damage of guessing wrong to that line.
+ */
+function regexEnd(source, start) {
+  let before = start - 1;
+  while (before >= 0 && /\s/.test(source[before])) before--;
+  const prev = before < 0 ? '' : source[before];
+  const isRegex =
+    before < 0 ||
+    REGEX_MAY_FOLLOW.test(prev) ||
+    REGEX_MAY_FOLLOW_KEYWORD.test(source.slice(Math.max(0, before - 11), before + 1));
+  if (!isRegex) return -1;
+  let inClass = false;
+  for (let i = start + 1; i < source.length; i++) {
+    const c = source[i];
+    if (c === '\\') i++;
+    else if (c === '\n') return -1;
+    else if (c === '[') inClass = true;
+    else if (c === ']') inClass = false;
+    else if (c === '/' && !inClass) return i + 1;
+  }
+  return -1;
+}
+
+/**
+ * How many times an unterminated backtick may be demoted to punctuation before
+ * we stop trying. Each demotion re-reads the tail, so this is what keeps a file
+ * full of stray backticks linear-ish rather than quadratic.
+ */
+const MAX_TEMPLATE_RESTARTS = 8;
+
+// Nothing between these characters can change the lexer's state, so the scan
+// jumps from one to the next rather than walking every character: a `{` only
+// matters inside a `${…}` substitution, which is why the top level uses the
+// narrower set.
+const NEXT_IN_CODE = /[/"'`]/g;
+const NEXT_IN_SUBSTITUTION = /[/"'`{}]/g;
+const NEXT_IN_TEMPLATE = /[\\`$]/g;
+
+/** The index of the next character that matters, or -1. */
+function nextStop(pattern, source, from) {
+  pattern.lastIndex = from;
+  const m = pattern.exec(source);
+  return m ? m.index : -1;
+}
+
+/**
+ * The same text with comments, string bodies, regex bodies and template-literal
+ * bodies blanked out, character for character the same length. The length is the
+ * contract: `regionEnd` and `enclosingDeclaration` compare offsets in this copy
+ * against offsets in the original, and everything breaks quietly if they drift.
+ *
+ * This is a lexer, and the state it carries is what a hand-written one usually
+ * gets wrong: a template body may contain `${…}` substitutions holding arbitrary
+ * code, that code may contain strings, comments, regexes and further templates,
+ * and any of those may contain a `}` or a backtick that is text rather than
+ * punctuation. So the open spans are kept on a stack and a template body is
+ * blanked in one piece when its closing backtick turns up — a `}` inside a
+ * substitution's own string then only has to be *tracked*, never separately
+ * reasoned about.
+ */
+export function scrubForScan(input) {
+  const source = String(input || '');
+  const n = source.length;
+  const out = [];
+  let copied = 0;
+  // Every blank goes through here, so "the copy is the same length as the
+  // input" is a property of the construction rather than something each branch
+  // has to remember to preserve.
+  const blank = (from, to) => {
+    if (to <= from || from < copied) return;
+    out.push(source.slice(copied, from), blanked(source.slice(from, to)));
+    copied = to;
+  };
+
+  // What we are inside, innermost last: `{ text: true }` for a template's
+  // literal text, `{ text: false, depth }` for the code of one of its `${…}`
+  // substitutions, where `depth` counts the plain braces open inside it so the
+  // `}` that ends the substitution is told apart from one closing an object
+  // literal or a function body written in it.
+  let stack = [];
+  // Backticks demoted to punctuation because the template they opened never
+  // closed; see the restart below.
+  const notATemplate = new Set();
+  let restarts = 0;
+  let i = 0;
+
+  for (;;) {
+    while (i < n) {
+      const top = stack.length ? stack[stack.length - 1] : null;
+      const inLiteral = top !== null;
+
+      if (top && top.text) {
+        // Template text: only an escape, `${` and the closing backtick matter,
+        // and the body is blanked as a whole when that backtick arrives.
+        const at = nextStop(NEXT_IN_TEMPLATE, source, i);
+        if (at === -1) break;
+        const c = source[at];
+        if (c === '\\') i = at + 2;
+        else if (c === '`') {
+          stack.pop();
+          if (stack.length === 0) blank(top.at + 1, at);
+          i = at + 1;
+        } else if (source[at + 1] === '{') {
+          stack.push({ text: false, depth: 0 });
+          i = at + 2;
+        } else i = at + 1;
+        continue;
+      }
+
+      // Code: the top level, or a substitution's expression.
+      const at = nextStop(inLiteral ? NEXT_IN_SUBSTITUTION : NEXT_IN_CODE, source, i);
+      if (at === -1) break;
+      const c = source[at];
+
+      if (c === '/' && source[at + 1] === '/') {
+        const eol = source.indexOf('\n', at);
+        const end = eol === -1 ? n : eol;
+        if (!inLiteral) blank(at, end);
+        i = end;
+      } else if (c === '/' && source[at + 1] === '*') {
+        const close = source.indexOf('*/', at + 2);
+        const end = close === -1 ? n : close + 2;
+        if (!inLiteral) blank(at, end);
+        i = end;
+      } else if (c === '/') {
+        const end = regexEnd(source, at);
+        if (end === -1) i = at + 1;
+        else {
+          // Blanked like a string, because a regex is data too: `/const \{ a \}
+          // = require\(/` reads as an import to a scanner that only sees text.
+          if (!inLiteral) blank(at + 1, end - 1);
+          i = end;
+        }
+      } else if (c === '"' || c === "'") {
+        const end = quoteEnd(source, at);
+        if (end <= at + 1) i = at + 1;
+        else {
+          // Keep the quotes, blank what is between them: a code generator that
+          // builds `const X = require(...)` as a string is not declaring X here.
+          if (!inLiteral) blank(at + 1, end - 1);
+          i = end;
+        }
+      } else if (c === '`') {
+        if (!notATemplate.has(at)) stack.push({ text: true, at });
+        i = at + 1;
+      } else if (c === '{') {
+        if (top) top.depth++;
+        i = at + 1;
+      } else {
+        if (top) {
+          if (top.depth === 0) stack.pop();
+          else top.depth--;
+        }
+        i = at + 1;
+      }
+    }
+
+    if (stack.length === 0) break;
+    // A backtick with no partner means we are wrong about something — and the
+    // input is as often a fragment of an edit, where half a template literal is
+    // normal, as it is a whole file. Running "inside a literal" to the end of
+    // the input on that guess is what this pass used to do, and it silently cost
+    // every declaration below the guess. So the backtick is demoted to ordinary
+    // punctuation and the rest is re-read as code: being wrong now costs at most
+    // the span itself, never the file.
+    const opened = stack[0].at;
+    stack = [];
+    if (++restarts > MAX_TEMPLATE_RESTARTS) break;
+    notATemplate.add(opened);
+    i = opened + 1;
+  }
+
+  out.push(source.slice(copied));
+  return out.join('');
+}
+
+const EXPORT_DECL =
+  /^[ \t]*export[ \t]+(?:default[ \t]+)?(?:declare[ \t]+)?(?:abstract[ \t]+)?(?:async[ \t]+)?(?:function[ \t]*\*?|class|interface|type|enum|const[ \t]+enum|const|let|var)[ \t]+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_LIST = /^[ \t]*export[ \t]*(?:type[ \t]*)?\{([^}]*)\}/gm;
+const CJS_EXPORT = /^[ \t]*(?:module\.)?exports\.([A-Za-z_$][\w$]*)[ \t]*=/gm;
+const IMPORT_CLAUSE = /^[ \t]*import[ \t]+(?:type[ \t]+)?([^;'"]*?)[ \t]+from[ \t]*['"]/gm;
+const REQUIRE_LIST = /(?:const|let|var)[ \t]*\{([^}]*)\}[ \t]*=[ \t]*require[ \t]*\(/g;
+const REQUIRE_BINDING = /(?:const|let|var)[ \t]+([A-Za-z_$][\w$]*)[ \t]*=[ \t]*require[ \t]*\(/g;
+
+function usableSymbol(name) {
+  return (
+    typeof name === 'string' &&
+    name.length >= MIN_SYMBOL_LENGTH &&
+    name.length <= MAX_SYMBOL_LENGTH &&
+    name !== 'default'
+  );
+}
+
+/** Split `{ a, b as c, type D }` into the names it brings into scope. */
+function parseNameList(inner) {
+  const out = [];
+  for (const raw of String(inner).split(',')) {
+    const part = raw.trim().replace(/^type[ \t]+/, '');
+    if (!part) continue;
+    const pieces = part.split(/\s+as\s+/);
+    const name = pieces[pieces.length - 1].trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(name)) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Exported declarations with the offset they start at, in source order.
+ * `text` must already have been through `scrubForScan`.
+ */
+function exportedDeclarations(text) {
+  const source = String(text || '');
+  const found = [];
+  const add = (name, index) => {
+    if (usableSymbol(name)) found.push({ name, index });
+  };
+  for (const m of source.matchAll(EXPORT_DECL)) add(m[1], m.index);
+  for (const m of source.matchAll(EXPORT_LIST)) {
+    for (const name of parseNameList(m[1])) add(name, m.index);
+  }
+  for (const m of source.matchAll(CJS_EXPORT)) add(m[1], m.index);
+  found.sort((a, b) => a.index - b.index);
+  return found;
+}
+
+/**
+ * Names this file pulls in from elsewhere — its side of the dependency edge.
+ * `text` must already have been through `scrubForScan`.
+ */
+function importedNames(text) {
+  const source = String(text || '');
+  const names = [];
+  for (const m of source.matchAll(IMPORT_CLAUSE)) {
+    for (const piece of m[1].split(/,(?![^{]*\})/)) {
+      const clause = piece.trim();
+      if (!clause) continue;
+      if (clause.startsWith('{')) {
+        for (const name of parseNameList(clause.replace(/^\{|\}$/g, ''))) {
+          if (usableSymbol(name)) names.push(name);
+        }
+      } else {
+        const bare = clause.replace(/^\*[ \t]*as[ \t]+/, '');
+        if (/^[A-Za-z_$][\w$]*$/.test(bare) && usableSymbol(bare)) names.push(bare);
+      }
+    }
+  }
+  for (const m of source.matchAll(REQUIRE_LIST)) {
+    for (const name of parseNameList(m[1])) if (usableSymbol(name)) names.push(name);
+  }
+  for (const m of source.matchAll(REQUIRE_BINDING)) {
+    if (usableSymbol(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+function readSource(filePath) {
+  try {
+    const stat = fs.statSync(filePath, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || stat.size > MAX_SOURCE_BYTES) return null;
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How far a declaration's region reaches: to the next exported declaration, or
+ * to the first line that closes a top-level block, whichever comes first. The
+ * second half is what stops an edit in a trailing helper from being credited to
+ * the last exported function in the file.
+ */
+function regionEnd(text, start, decls) {
+  const next = decls.find((d) => d.index > start);
+  const limit = next ? next.index : text.length;
+  const close = text.indexOf('\n}', start);
+  if (close !== -1 && close < limit) {
+    const eol = text.indexOf('\n', close + 1);
+    return eol === -1 ? limit : eol;
+  }
+  return limit;
+}
+
+/** The declaration whose region contains `at`, or null if none does. */
+function declarationAt(scanned, decls, at) {
+  let found = null;
+  for (const decl of decls) {
+    if (decl.index > at) break;
+    found = decl;
+  }
+  if (!found) return null;
+  return at <= regionEnd(scanned, found.index, decls) ? found.name : null;
+}
+
+/**
+ * An edit inside a function body never repeats the `export function` line, so
+ * the only way to know which symbol it changed is to find the new text in the
+ * post-edit file and walk back to the declaration whose region contains it.
+ *
+ * Which occurrence, though: a body line duplicated across two functions used to
+ * be credited to whichever came first, which is a confident wrong answer — the
+ * one failure mode this design exists to avoid. So every occurrence is placed,
+ * and unless they all land in the same declaration the edit names nobody. The
+ * search runs over the original text, not the scrubbed copy, because an edit's
+ * new text routinely is a comment; the offsets are the same either way.
+ */
+function enclosingDeclaration(text, scanned, decls, added) {
+  const needle = String(added || '').trim();
+  if (!needle) return null;
+  const probe = needle.length > 400 ? needle.slice(0, 400) : needle;
+  let name = null;
+  let at = text.indexOf(probe);
+  for (let seen = 0; at !== -1; seen++) {
+    if (seen >= MAX_ATTRIBUTION_MATCHES) return null;
+    const here = declarationAt(scanned, decls, at);
+    if (here === null || (name !== null && here !== name)) return null;
+    name = here;
+    at = text.indexOf(probe, at + 1);
+  }
+  return name;
+}
+
+function editSegments(toolName, toolInput) {
+  if (toolName === 'Write') return [{ added: toolInput.content, removed: '' }];
+  const edits = Array.isArray(toolInput.edits)
+    ? toolInput.edits
+    : [{ old_string: toolInput.old_string, new_string: toolInput.new_string }];
+  return edits.map((e) => ({ added: e?.new_string || '', removed: e?.old_string || '' }));
+}
+
+/**
+ * The exported symbols an edit changed — the *definition* side.
+ *
+ * Returns null, never throws, whenever it cannot say anything useful: an
+ * unsupported language, an unreadable file, an edit that touches no exported
+ * API. Null means "fall back to path matching".
+ */
+export function symbolsForEdit(filePath, toolName, toolInput) {
+  try {
+    if (!supportsSymbols(filePath) || !toolInput) return null;
+    const segments = editSegments(toolName, toolInput);
+    const touched = new Set();
+
+    // Declarations the edit spells out itself; works with no file access at all.
+    for (const segment of segments) {
+      for (const decl of exportedDeclarations(scrubForScan(segment.added))) touched.add(decl.name);
+      for (const decl of exportedDeclarations(scrubForScan(segment.removed))) touched.add(decl.name);
+    }
+
+    const text = readSource(filePath);
+    if (text !== null) {
+      const scanned = scrubForScan(text);
+      const decls = exportedDeclarations(scanned);
+      if (decls.length) {
+        if (toolName === 'Write') {
+          // A Write replaces the file, so every export in it is in play.
+          for (const decl of decls) touched.add(decl.name);
+        } else {
+          for (const segment of segments) {
+            const name = enclosingDeclaration(text, scanned, decls, segment.added);
+            if (name) touched.add(name);
+          }
+        }
+      }
+    }
+
+    const list = [...touched].slice(0, MAX_DEF_SYMBOLS);
+    return list.length ? list : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The symbols a file is bound to — what it imports plus what it exports. This
+ * is the *reference* side: the set an about-to-edit file is checked against, so
+ * a teammate changing `createUser` three directories away still reaches you.
+ */
+export function symbolsForFile(filePath) {
+  try {
+    if (!supportsSymbols(filePath)) return null;
+    const text = readSource(filePath);
+    if (text === null) return null;
+    // Exports first: they are fewer and carry more weight than imports, so
+    // when MAX_REF_SYMBOLS truncates a big file it truncates the cheaper half.
+    const scanned = scrubForScan(text);
+    const names = new Set();
+    for (const decl of exportedDeclarations(scanned)) names.add(decl.name);
+    for (const name of importedNames(scanned)) names.add(name);
+    const list = [...names].slice(0, MAX_REF_SYMBOLS);
+    return list.length ? list : null;
+  } catch {
+    return null;
+  }
+}