simt-dev 0.6.3 → 0.7.0

package/src/kernel/checks.mjs

@@ -14,6 +14,8 @@ import { readFile, stat } from 'node:fs/promises';
 import { relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
+import { CLI } from '../name.mjs';
+
 const exec = promisify(execFile);
 
 export const CHECK_MARKER = 'simt-check';
@@ -48,11 +50,32 @@ export function checkDefect(body) {
   return null;
 }
 
+/**
+ * What a runnable check enforces, in the reader's terms. The bare checker id is
+ * vocabulary for the manifest author; the projected region is read by a repository
+ * that has no manifest and no checker registry.
+ */
+function checkSummary(check) {
+  const arg = check.arg;
+  switch (check.name) {
+    case 'max-file-lines':
+      return `by \`${CLI} check\`: more than ${DEFAULT_WARN} lines warns, more than ${DEFAULT_ERROR} fails (\`limits.fileLines\`)`;
+    case 'forbid-regex':
+      return `added lines matching \`${arg}\` are rejected`;
+    case 'forbidden-path-edit':
+      return `\`${arg}\` is not to be edited`;
+    case 'required-file':
+      return `\`${arg}\` must exist`;
+    default:
+      return check.name;
+  }
+}
+
 /**
  * Replace each runnable check with one `Enforced:` line. A body with no marker
  * is returned unchanged, so a rule nobody marked does not move a byte.
  *
- * @returns {{body: string, enforced: {name: string}[], changed: boolean}}
+ * @returns {{body: string, enforced: {name: string, summary: string}[], changed: boolean}}
  */
 export function foldChecks(body) {
   if (checkDefect(body) !== null || !HAS_MARKER.test(body)) {
@@ -73,8 +96,9 @@ export function foldChecks(body) {
     }
     const indent = ITEM_START.exec(unit)?.[1] ?? '';
     const bullet = ITEM_START.test(unit) ? '- ' : '';
-    kept.push(`${indent}${bullet}Enforced: ${parsed.name}`);
-    enforced.push({ name: parsed.name });
+    const summary = checkSummary(parsed);
+    kept.push(`${indent}${bullet}Enforced: ${summary}`);
+    enforced.push({ name: parsed.name, summary });
   }
   const next = kept.join('\n');
   return { body: next, enforced, changed: next !== body };
@@ -130,15 +154,24 @@ async function runOne(root, check, manifest) {
   return forbiddenPath(check, diff);
 }
 
+const TEXT_EXTENSIONS = new Set(['.md', '.txt', '.doc', '.docx', '.rst', '.adoc', '.tex']);
+
+function isTextFile(rel) {
+  const segments = rel.split('/');
+  if (segments.includes('doc') || segments.includes('docs')) return true;
+  const dot = rel.lastIndexOf('.');
+  return dot !== -1 && TEXT_EXTENSIONS.has(rel.slice(dot).toLowerCase());
+}
+
 async function fileLines(root, check, manifest) {
   const limits = manifest?.limits?.fileLines ?? {};
-  const generated = limits.generated;
-  if (generated !== undefined && !Array.isArray(generated)) {
+  const exclude = limits.exclude;
+  if (exclude !== undefined && !Array.isArray(exclude)) {
     return [{
       file: 'simt.json',
       status: 'invalid',
-      detail: 'limits.fileLines.generated must be a list of paths',
-      remedy: 'name each generated path, or remove the key',
+      detail: 'limits.fileLines.exclude must be a list of paths',
+      remedy: 'name each excluded path, or remove the key',
     }];
   }
   const warnAt = Number.isInteger(limits.warn) ? limits.warn : DEFAULT_WARN;
@@ -146,13 +179,15 @@ async function fileLines(root, check, manifest) {
   const files = await tracked(root);
   if (files === null) return [];
   const findings = [];
-  const prefixes = Array.isArray(generated) ? generated.filter((g) => typeof g === 'string' && g !== '') : [];
+  const prefixes = Array.isArray(exclude) ? exclude.filter((g) => typeof g === 'string' && g !== '') : [];
+  const skipText = limits.excludeTextFiles === true;
   for (const rel of files) {
     // A committed dependency is not a file this repository wrote. Counting it
     // fails every install of this package, because the package's own sources
     // are longer than the ceiling the consumer declared.
     if (rel.split('/').includes('node_modules')) continue;
     if (exempt(rel, prefixes)) continue;
+    if (skipText && isTextFile(rel)) continue;
     let text;
     try {
       text = await readFile(resolve(root, rel));
@@ -170,7 +205,7 @@ async function fileLines(root, check, manifest) {
         file: rel,
         status: 'file-lines',
         detail: `${lines} lines, over the ceiling of ${errorAt}`,
-        remedy: 'split the file, or name its generator in limits.fileLines.generated',
+        remedy: 'split the file, or name it in limits.fileLines.exclude',
       });
     } else if (lines > warnAt) {
       findings.push({

package/src/kernel/variants.mjs

@@ -4,34 +4,45 @@
 // A rule line or list item may carry `<!-- simt-variants: <slot> <spec> -->`.
 // When unlocked, projection uses the baseline variant (`a`, or the line's own
 // prose) and strips the marker so `simt-` annotations never reach a reader.
-// When `simt-dev.lock.json` records a locked winner for `<ruleId>.<slot>`,
+// When `simt.lock.json` records a locked winner for `<ruleId>.<slot>`,
 // projection deterministically renders that winning variant.
 
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
+import { LOCK_FILE, LOCK_LEGACY } from '../name.mjs';
+
 export const VARIANTS_MARKER = 'simt-variants';
-const LOCK_FILE_NAME = 'simt-dev.lock.json';
 
 /**
- * Read the locked `variants` map from `simt-dev.lock.json` in `root`, or `{}` when absent.
+ * Read the locked `variants` map from `simt.lock.json` in `root`, or `{}` when absent.
+ * A lock under the legacy name is read until the next write migrates it (ADR-110); a
+ * lock that exists but does not parse is damage, and damage is not repaired by an
+ * older file.
  */
 export async function readLockedVariants(root) {
   if (!root) return {};
-  try {
-    const raw = await readFile(join(root, LOCK_FILE_NAME), 'utf8');
-    const parsed = JSON.parse(raw);
-    if (
-      parsed &&
-      typeof parsed === 'object' &&
-      parsed.variants &&
-      typeof parsed.variants === 'object' &&
-      !Array.isArray(parsed.variants)
-    ) {
-      return parsed.variants;
+  for (const name of [LOCK_FILE, LOCK_LEGACY]) {
+    let raw;
+    try {
+      raw = await readFile(join(root, name), 'utf8');
+    } catch {
+      continue; // no lock under this name; try the next one
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === 'object' &&
+        parsed.variants &&
+        typeof parsed.variants === 'object' &&
+        !Array.isArray(parsed.variants)
+      ) {
+        return parsed.variants;
+      }
+    } catch {
+      return {};
     }
-  } catch {
-    // Missing or unreadable lockfile falls back to baseline variants.
   }
   return {};
 }

package/src/lease.mjs

@@ -14,13 +14,15 @@
 // path to the session that broke it. Which way that fails is the caller's decision —
 // the hook refuses edits, the command refuses to write (ADR-101 rulings 4).
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
+import { mkdir, open, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 
-import { STATE_DIR } from './name.mjs';
+import { localRel, readStateFile } from './state.mjs';
 
 /** Where the claims live, in every repository: beside the index and the ledger. */
-export const LEASE_FILE = join(STATE_DIR, 'leases.json');
+export const LEASE_FILE = localRel('leases.json');
+const LEASE_FILE_LEGACY = '.simt/leases.json';
 
 /** The schema the file is written with; a reader that does not know it refuses. */
 const LEASE_SCHEMA = 1;
@@ -34,18 +36,46 @@ const LEASE_SCHEMA = 1;
 export const DEFAULT_TTL_SECONDS = 3600;
 
 /**
- * The repository-relative name of a path this tool may lease, or null when it is not
- * inside the repository at all.
+ * The one spelling a path has for lease matching: repository-relative, symlinks
+ * resolved, case-folded when the repository's git compares case-insensitively, or
+ * null when the path is not inside the repository at all.
  *
- * Relative to the root and slash-normalised, because that is the spelling the file
- * holds and the one a payload's absolute `file_path` has to become before the two can
- * be compared. The root itself leases nothing — there is no edit that "is" the
- * repository — so it answers null like a path that escapes it.
+ * A payload that reaches a file through a symlinked directory spells it one way,
+ * the claim recorded for the file spells it the other, and on a case-insensitive
+ * volume the two spellings that differ in case are the same file (review 0003
+ * Q16). Both sides of a comparison go through this, so a claim and an edit meet
+ * in the same spelling whatever road each one took to get there.
+ *
+ * The real path of the deepest existing ancestor is joined with the remainder,
+ * because `realpath` on a file that does not exist yet — the normal state of a
+ * write payload — would refuse. The root itself leases nothing — there is no
+ * edit that "is" the repository — so it answers null like a path that escapes it.
  */
-export function leasePathFor(root, input) {
-  const rel = relative(resolve(root), resolve(root, String(input ?? '')));
+export function canonicalLeasePath(root, input, { ignoreCase = false } = {}) {
+  const base = resolve(root, String(input ?? ''));
+  let anchor = base;
+  while (anchor !== resolve(anchor, '..')) {
+    if (existsSync(anchor)) break;
+    anchor = dirname(anchor);
+  }
+  let realAnchor;
+  try {
+    realAnchor = realpathSync(anchor);
+  } catch {
+    realAnchor = anchor;
+  }
+  const rest = relative(anchor, base);
+  const abs = rest === '' ? realAnchor : join(realAnchor, rest);
+  let realRoot;
+  try {
+    realRoot = realpathSync(resolve(root));
+  } catch {
+    realRoot = resolve(root);
+  }
+  const rel = relative(realRoot, abs);
   if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`)) return null;
-  return rel.split(sep).join('/');
+  const slashed = rel.split(sep).join('/');
+  return ignoreCase ? slashed.toLowerCase() : slashed;
 }
 
 /**
@@ -60,13 +90,14 @@ export function leasePathFor(root, input) {
  */
 export async function readLeases(root) {
   const path = join(root, LEASE_FILE);
+  // The pre-move path is a fallback for one release (review 0003 Q19).
   let text;
   try {
-    text = await readFile(path, 'utf8');
+    ({ text } = await readStateFile(root, LEASE_FILE, [LEASE_FILE_LEGACY]));
   } catch (error) {
-    if (error.code === 'ENOENT') return { path, leases: [], error: null };
     return { path, leases: [], error: `${LEASE_FILE} could not be read (${error.message})` };
   }
+  if (text === null) return { path, leases: [], error: null };
   try {
     const parsed = JSON.parse(text);
     if (parsed === null || typeof parsed !== 'object' || !Array.isArray(parsed.leases)) {
@@ -108,6 +139,57 @@ export async function writeLeases(root, leases) {
   const sorted = [...leases].sort((a, b) => a.path.localeCompare(b.path));
   const body = `${JSON.stringify({ schemaVersion: LEASE_SCHEMA, leases: sorted }, null, 2)}\n`;
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, body, 'utf8');
+  // Atomic against a concurrent writer and a concurrent reader: a half-written
+  // claim file fails closed for every edit (review 0003 Q20).
+  const tmp = `${path}.tmp-${process.pid}`;
+  await writeFile(tmp, body, 'utf8');
+  await rename(tmp, path);
   return path;
 }
+
+/** A lock is stale when its holder died holding it, not when it is merely slow. */
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 10_000;
+
+/**
+ * Run `fn` with the claim file held: an `O_EXCL` lockfile (stale ones reaped),
+ * the read-modify-write re-done inside, the lock released afterwards.
+ *
+ * Twelve concurrent claims stored seven before this: every claimant read the
+ * same file, each wrote back only what it had seen. Re-reading under the lock
+ * closes that race (review 0003 Q20).
+ */
+export async function withLeaseLock(root, fn) {
+  const lockPath = join(root, `${LEASE_FILE}.lock`);
+  await mkdir(dirname(lockPath), { recursive: true });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const fd = await open(lockPath, 'wx');
+      await fd.close();
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let stale = false;
+      try {
+        const st = await stat(lockPath);
+        stale = Date.now() - st.mtimeMs > LOCK_STALE_MS;
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        await unlink(lockPath).catch(() => {});
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`could not take the lease lock; remove ${lockPath} if no lease run is active`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    await unlink(lockPath).catch(() => {});
+  }
+}

package/src/ledger/index.mjs

@@ -7,26 +7,31 @@
 
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import { appendFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { appendFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
 import {
-  LESSONS_FILE,
   errorSignature,
   firstErrorLine,
   normaliseErrorLine,
   recordFailThenFix,
 } from '../memory/lessons.mjs';
+import { TREE_EXCLUDES, localRel, readStateFile } from '../state.mjs';
 
 const exec = promisify(execFile);
 
-const LEDGER_FILE = '.simt/ledger.jsonl';
+export const LEDGER_FILE = localRel('ledger.jsonl');
+const LEDGER_FILE_LEGACY = '.simt/ledger.jsonl';
 
 /** Phrases that claim a run happened. `unverified` and `not verified` are removed
- *  first, because both contain the word and neither is a claim. */
-const CLAIM = /\btests?\s+pass(?:ed)?\b|\bverified\b/i;
+ *  first, because both contain the word and neither is a claim. Trailers
+ *  (Signed-off-by and friends) are ignored, because they describe the commit,
+ *  not the run (review 0003 Q18). */
+const CLAIM =
+  /\btests?\s+pass(?:ed|ing)?\b|\btest\s+suite\s+(?:is\s+)?green\b|\bsuite\s+is\s+green\b|\bnpm\s+test\s+pass(?:es|ed)?\b|\bverified\b/i;
+const TRAILER = /^(signed-off-by|co-authored-by|reviewed-by|acked-by|tested-by|fixes|closes)\s*:/i;
 
 /**
  * The tree of everything in the worktree, without staging any of it.
@@ -39,14 +44,12 @@ export async function treeId(root) {
   const index = join(dir, 'index');
   const env = { ...process.env, GIT_INDEX_FILE: index };
   try {
-    // The ledger is a record of the tree, so it cannot be part of the tree it names.
-    // `git add -A` would take it once the file exists, and the line would prove a
-    // tree that stopped existing when the line was written.
-    await exec(
-      'git',
-      ['add', '-A', '--', '.', `:(exclude)${LEDGER_FILE}`, `:(exclude)${LESSONS_FILE}`],
-      { cwd: root, env },
-    );
+    // Machine-local state is a record of the tree, so it cannot be part of the
+    // tree it names. `git add -A` would take it once the file exists, and the
+    // line would prove a tree that stopped existing when the line was written
+    // (review 0003 Q19).
+    const excludes = TREE_EXCLUDES.map((p) => `:(exclude)${p}`);
+    await exec('git', ['add', '-A', '--', '.', ...excludes], { cwd: root, env });
     const { stdout } = await exec('git', ['write-tree'], { cwd: root, env });
     return stdout.trim();
   } finally {
@@ -58,12 +61,31 @@ export async function treeId(root) {
  * Append one run. The output itself is not stored: the digest is enough to notice a
  * change, and a ledger that kept logs would keep whatever the command printed.
  */
-export async function recordRun(root, { cmd, exit, ms, output }) {
+/** The staged tree (`git write-tree` on the real index): what a commit-msg
+ *  check must match, because the commit records the index, not the worktree.
+ *  Null when git cannot answer; the caller then falls back to the worktree tree. */
+export async function indexTreeId(root) {
+  try {
+    const { stdout } = await exec('git', ['write-tree'], { cwd: root });
+    const tree = String(stdout ?? '').trim();
+    return /^[0-9a-f]{40}$/.test(tree) ? tree : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function recordRun(root, { cmd, exit, ms, output, gate = null, kind = null }) {
   const { entries: prior } = await readLedger(root).catch(() => ({ entries: [] }));
+  const worktreeTree = await treeId(root);
+  const indexTree = await indexTreeId(root);
   const line = {
-    v: 1,
+    v: 2,
     ts: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
-    tree: await treeId(root),
+    tree: worktreeTree,
+    worktreeTree,
+    ...(indexTree !== null ? { indexTree } : {}),
+    ...(typeof gate === 'string' ? { gate } : {}),
+    ...(typeof kind === 'string' ? { kind } : {}),
     cmd,
     exit,
     ms,
@@ -76,7 +98,7 @@ export async function recordRun(root, { cmd, exit, ms, output }) {
         }
       : {}),
   };
-  await mkdir(join(root, '.simt'), { recursive: true });
+  await mkdir(join(root, '.simt', 'local'), { recursive: true });
   await appendFile(join(root, LEDGER_FILE), `${JSON.stringify(line)}\n`);
 
   if (exit === 0 && typeof cmd === 'string') {
@@ -100,13 +122,9 @@ export async function recordRun(root, { cmd, exit, ms, output }) {
 /** Every well-formed line. A line that does not parse is returned as an error so a
  *  damaged ledger cannot look empty. */
 export async function readLedger(root) {
-  let text;
-  try {
-    text = await readFile(join(root, LEDGER_FILE), 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return { entries: [], errors: [] };
-    throw error;
-  }
+  // The pre-move path is a fallback for one release (review 0003 Q19).
+  const { text } = await readStateFile(root, LEDGER_FILE, [LEDGER_FILE_LEGACY]);
+  if (text === null) return { entries: [], errors: [] };
   const entries = [];
   const errors = [];
   for (const [i, raw] of text.split('\n').entries()) {
@@ -125,8 +143,56 @@ export async function readLedger(root) {
   return { entries, errors };
 }
 
+/** Whether the entry counts as a test-kind run (review 0003 Q18). v1 lines
+ *  carry no kind, so a command naming test counts; v2 lines use the recorded kind. */
+function isTestKind(entry) {
+  if (typeof entry?.kind === 'string') return entry.kind === 'test';
+  return typeof entry?.cmd === 'string' && /\btest\b/i.test(entry.cmd);
+}
+
+/**
+ * The surviving passing entry for one gate on one staged tree, or null.
+ *
+ * A later failure for the same gate on the same tree cancels the pass, the
+ * way `hasTestEvidence` cancels a test pass — a gate that passed, then
+ * failed, proves nothing about the tree. Entries without an `indexTree`
+ * predate the staged-tree record and never match: a pass on an unknown tree
+ * is not evidence for this one (review 0003 Q23).
+ */
+export function passEntryForGate(entries, gate, tree) {
+  const scoped = (entries ?? []).filter((e) => e?.gate === gate && e?.indexTree === tree);
+  for (let i = 0; i < scoped.length; i += 1) {
+    if (scoped[i].exit !== 0) continue;
+    const laterFailure = scoped.slice(i + 1).some((later) => later.exit !== 0);
+    if (!laterFailure) return scoped[i];
+  }
+  return null;
+}
+
+/** A passing test-kind entry for `tree` with no later failure of the same
+ *  command on the same tree. v1 lines (no `kind`) keep today's reading: any
+ *  passing entry for the tree counts, so old ledgers do not go red. */
+export function hasTestEvidence(entries, tree) {
+  const scoped = entries.filter((e) => e.tree === tree || e.worktreeTree === tree || e.indexTree === tree);
+  for (let i = 0; i < scoped.length; i += 1) {
+    const candidate = scoped[i];
+    if (candidate.exit !== 0) continue;
+    const legacy = candidate.v !== 2 || candidate.kind === undefined || candidate.kind === null;
+    if (!legacy && !isTestKind(candidate)) continue;
+    const laterFailure = scoped
+      .slice(i + 1)
+      .some((later) => later.cmd === candidate.cmd && later.exit !== 0);
+    if (!laterFailure) return true;
+  }
+  return false;
+}
+
 export function claimsVerification(message) {
-  const text = String(message).replace(/\bunverified\b/gi, ' ').replace(/\bnot\s+verified\b/gi, ' ');
+  const lines = String(message).split('\n').filter((line) => !TRAILER.test(line.trim()));
+  const text = lines
+    .join('\n')
+    .replace(/\bunverified\b/gi, ' ')
+    .replace(/\bnot\s+verified\b/gi, ' ');
   return CLAIM.test(text);
 }
 

package/src/mcp/resources.mjs

@@ -16,7 +16,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { DECISIONS_DIR, loadDecisions, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
+import { DECISIONS_DIR, loadDecisionsCached, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
 import { planNext } from '../plan/index.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
 import { desiredRegion, loadRules } from '../projection/rules.mjs';
@@ -122,7 +122,9 @@ export async function listResources(root = process.cwd()) {
   const [rules, mdc, { decisions }, region, plan] = await Promise.all([
     loadRules(null),
     loadMdcRules(),
-    loadDecisions({ all: true }),
+    // Q55: the shipped records through the shared cache (root locates the cache
+    // file; the directory stays the package's own, which is what is served).
+    loadDecisionsCached({ root, dir: DECISIONS_DIR, all: true }),
     kernelRegion(root),
     planNext(root, null),
   ]);
@@ -211,7 +213,7 @@ export async function readResource(uri, root = process.cwd()) {
   // `loadDecisions` reads the index, not the records: it reports status, currency and
   // byte count, and keeps no body. Reading the file the index named is one read of a
   // record the reader has already asked for by id.
-  const { decisions } = await loadDecisions({ all: true });
+  const { decisions } = await loadDecisionsCached({ root, dir: DECISIONS_DIR, all: true });
   const decision = decisions.find((candidate) => candidate.id === parsed.id);
   if (decision === undefined) return null;
   const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');

package/src/mcp/server.mjs

@@ -103,12 +103,17 @@ const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
  * caller names the root and the default is the process's cwd, which is what an editor's
  * stdio server sits in.
  *
+ * `signal` aborts the one in-flight `tools/call` (wired by `serve` to
+ * `notifications/cancelled`); `notify` emits `notifications/progress` while it
+ * runs. Both are null in tests that call this directly, and every tool must
+ * treat a missing context as "run to completion quietly".
+ *
  * @param {object|null} request a parsed JSON-RPC message
  * @param {object[]} tools
- * @param {{packageVersion?: string, state?: {version: string|null}, root?: string}} options
+ * @param {{packageVersion?: string, state?: {version: string|null}, root?: string, signal?: AbortSignal|null, notify?: ((message: object) => void)|null}} options
  * @returns {Promise<object|null>}
  */
-export async function handle(request, tools, { packageVersion, state, root } = {}) {
+export async function handle(request, tools, { packageVersion, state, root, signal = null, notify = null } = {}) {
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
@@ -195,8 +200,24 @@ export async function handle(request, tools, { packageVersion, state, root } = {
         return error(id, RPC.METHOD, `no tool named "${name}"; call tools/list first`);
       }
       const args = params?.arguments ?? {};
+      // The one impurity in this file, and scoped to it: progress has to reach
+      // the client while the tool runs, not after it returns. Nothing else
+      // writes here - diagnostics still go to stderr, never this stream.
+      const progressToken = params?._meta?.progressToken;
+      const toolCtx = {
+        signal,
+        onProgress:
+          progressToken !== undefined && progressToken !== null && typeof notify === 'function'
+            ? (progress, total) =>
+                notify({
+                  jsonrpc: '2.0',
+                  method: 'notifications/progress',
+                  params: { progressToken, progress, total },
+                })
+            : null,
+      };
       try {
-        const payload = await tool.run(args);
+        const payload = await tool.run(args, toolCtx);
         // Both blocks, always. `structuredContent` is what a client validates against
         // `outputSchema` and what it can index; the text block is what a client that
         // predates structured output reads. Emitting one without the other leaves half
@@ -384,33 +405,71 @@ function error(id, code, message) {
 export async function serve(tools, { input = process.stdin, output = process.stdout, packageVersion, onError } = {}) {
   const rl = createInterface({ input, crlfDelay: Infinity });
   const state = { version: null };
-  for await (const line of rl) {
-    if (line.trim() === '') continue;
-
-    // Parse and handling fail differently and must answer differently. A line that is
-    // not JSON has no id to answer to, so it is a parse error with `id: null`; a
-    // throw inside `handle` belongs to the request it was answering, so it keeps
-    // that request's id — answering it as a parse error hangs the client that is
-    // still waiting for its answer (Q12).
-    let response;
+  // The in-flight call a `notifications/cancelled` can abort. Read this way
+  // because the loop below is blocked awaiting the tool while the client
+  // decides: the event loop still turns on subprocess waits, so the peek
+  // fires mid-run and the tool checks the signal between rows. The async
+  // iterator below yields the same line afterwards and `handle` answers it
+  // with null, as every notification is answered - the peek consumes nothing.
+  let inflight = null;
+  const peekCancel = (line) => {
+    if (!inflight || line.trim() === '') return;
     let message;
     try {
       message = JSON.parse(line);
-    } catch (parseFailure) {
-      response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
+    } catch {
+      return;
+    }
+    if (message?.method === 'notifications/cancelled' && message?.params?.requestId === inflight.id) {
+      inflight.controller.abort();
     }
-    if (response === undefined) {
+  };
+  rl.on('line', peekCancel);
+  try {
+    for await (const line of rl) {
+      if (line.trim() === '') continue;
+
+      // Parse and handling fail differently and must answer differently. A line that is
+      // not JSON has no id to answer to, so it is a parse error with `id: null`; a
+      // throw inside `handle` belongs to the request it was answering, so it keeps
+      // that request's id — answering it as a parse error hangs the client that is
+      // still waiting for its answer (Q12).
+      let response;
+      let message;
       try {
-        response = await handle(message, tools, { packageVersion, state });
-      } catch (handlerFailure) {
-        const id = message !== null && typeof message === 'object' && 'id' in message ? message.id : null;
-        response = error(id, RPC.INTERNAL, `internal error: ${handlerFailure?.message ?? handlerFailure}`);
+        message = JSON.parse(line);
+      } catch (parseFailure) {
+        response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
+      }
+      if (response === undefined) {
+        // A notification never runs: without an id there is nothing to cancel
+        // and nothing to answer, so `notifications/cancelled` for an idle server
+        // is a no-op rather than an error.
+        const isNotification =
+          message === null || typeof message !== 'object' || Array.isArray(message) || message.id === undefined || message.id === null;
+        const controller = isNotification ? null : new AbortController();
+        if (controller) inflight = { id: message.id, controller };
+        try {
+          response = await handle(message, tools, {
+            packageVersion,
+            state,
+            signal: controller?.signal ?? null,
+            notify: (notification) => output.write(`${JSON.stringify(notification)}\n`),
+          });
+        } catch (handlerFailure) {
+          const id = message !== null && typeof message === 'object' && 'id' in message ? message.id : null;
+          response = error(id, RPC.INTERNAL, `internal error: ${handlerFailure?.message ?? handlerFailure}`);
+        } finally {
+          if (controller) inflight = null;
+        }
       }
+      if (response === null) continue;
+      output.write(`${JSON.stringify(response)}\n`);
     }
-    if (response === null) continue;
-    output.write(`${JSON.stringify(response)}\n`);
+    return EXIT_OK;
+  } finally {
+    rl.off('line', peekCancel);
   }
-  return EXIT_OK;
 }
 
 const EXIT_OK = 0;