simt-dev 0.6.2 → 0.7.0

package/src/commands/lease.mjs

@@ -0,0 +1,304 @@
+// `simt lease [<paths>...]`: claim files for one session, or read the claims (R54).
+// `lease release` and `lease renew` end and extend the holder's own claims: the
+// denial tells a blocked session to ask the holder to release the path, so the
+// holder needs a command that does it (review 0003 Q20).
+//
+// The claim is the half of ADR-101 a session does by hand: `lease src/a.mjs --session
+// alpha` records that alpha is working on the path until a TTL expires, the pre-edit
+// hook reads the same file to refuse anyone else, and a bare `lease` lists what is
+// currently held — because the first question a blocked session asks is "who has
+// this", and opening a JSON file by hand is not an answer the tool should outsource.
+//
+// Two refusals are deliberate and both come from ADR-101: a path another session
+// still holds is not taken (stealing is what the TTL is for, and the error names the
+// holder and the expiry), and a claim file that will not parse is not overwritten
+// (the hook fails closed on that same file, so writing over it would erase the very
+// claims the hook is about to enforce while telling the author it fixed something).
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import {
+  DEFAULT_TTL_SECONDS,
+  activeLeases,
+  canonicalLeasePath,
+  readLeases,
+  withLeaseLock,
+  writeLeases,
+} from '../lease.mjs';
+import { coreIgnoreCase } from '../repo-root.mjs';
+import { SESSION_ENV } from '../agenthooks/policy.mjs';
+import { CLI } from '../name.mjs';
+
+const ISO = (ms) => new Date(ms).toISOString();
+
+export async function leaseCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+  const [sub, ...rest] = args;
+  // The denial tells a blocked session to ask the holder to release the path,
+  // so releasing is a subcommand, not a missing flag (review 0003 Q20).
+  if (sub === 'release') return releaseLeases(root, rest, flags);
+  if (sub === 'renew') return renewLeases(root, rest, flags);
+
+  // A session or a TTL with no paths is a claim about nothing; the parser would
+  // otherwise hand back a list the caller never asked to see.
+  if (args.length === 0) {
+    if (flags.session !== undefined || flags.ttl !== undefined) {
+      return fail(`lease without paths is a list, so it takes neither --session nor --ttl`, EXIT.USAGE, `run: ${CLI} lease <paths> --session <id>`);
+    }
+    return listLeases(root, flags);
+  }
+
+  const session = String(flags.session ?? process.env[SESSION_ENV] ?? '');
+  if (session === '') {
+    return fail(`lease needs a session to hold the claim`, EXIT.USAGE, `run: ${CLI} lease <paths> --session <id> (or set ${SESSION_ENV})`);
+  }
+  const ttl = flags.ttl === undefined ? DEFAULT_TTL_SECONDS : Number(flags.ttl);
+  if (!Number.isInteger(ttl) || ttl < 1) {
+    return fail(`--ttl must be a positive number of seconds, received ${flags.ttl}`, EXIT.USAGE, `example: run: ${CLI} lease <paths> --ttl 900`);
+  }
+  const harness = typeof flags.harness === 'string' && flags.harness !== '' ? flags.harness : null;
+
+  const wanted = [];
+  const seen = new Set();
+  // The claim is stored in the one spelling the hook's comparison will produce:
+  // a claim taken as `src/Keep.mjs` and an edit that spells `src/keep.mjs` must
+  // be the same claim on a case-insensitive volume, so the stored path is
+  // canonical at write time, not at read time.
+  const ignoreCase = coreIgnoreCase(root);
+  for (const arg of args) {
+    const rel = canonicalLeasePath(root, arg, { ignoreCase });
+    if (rel === null) {
+      return fail(`${arg} is not a path inside the repository`, EXIT.USAGE, `leases are repository-relative: run: ${CLI} lease <path> --session ${session}`);
+    }
+    if (!seen.has(rel)) {
+      seen.add(rel);
+      wanted.push(rel);
+    }
+  }
+
+  // Older claim files hold the pre-canonical spelling, so a stored path is
+  // canonicalised before it is compared: a claim written before the resolver
+  // existed must still conflict with a claim taken for the same file.
+  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
+  const newClaim = (expiresAt) =>
+    wanted.map((path) => ({ path, session, expiresAt, ...(harness === null ? {} : { harness }) }));
+
+  const mode = writeMode(flags);
+  if (!mode.apply) {
+    const mine = newClaim(Date.now() + ttl * 1000);
+    const apply = `run: ${CLI} lease ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`;
+    if (isJson(flags)) {
+      emitJson({ ok: true, command: 'lease', root, dryRun: true, session, ttl, leases: mine, remedy: apply });
+      return EXIT.OK;
+    }
+    const lines = [
+      `repo     ${root}`,
+      `session  ${session}`,
+      `ttl      ${ttl}s`,
+      ...mine.map((l) => `would    lease ${l.path} until ${ISO(l.expiresAt)}`),
+      `apply    ${apply}`,
+    ];
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  // The read-modify-write happens under the lock: twelve concurrent claims
+  // stored seven before this, because every claimant read the same file and
+  // each wrote back only what it had seen (review 0003 Q20).
+  const claimed = await withLeaseLock(root, async () => {
+    const read = await readLeases(root);
+    if (read.error !== null) return { error: read.error, path: read.path };
+    const held = activeLeases(read);
+    const conflicts = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    if (conflicts.length > 0) return { conflicts };
+    // Keep every other live claim, refresh ours, and let an expired one fall out:
+    // the write is also the only sweep the file ever gets.
+    const others = held.filter((l) => !seen.has(keyOf(l)));
+    const mine = newClaim(Date.now() + ttl * 1000);
+    const path = await writeLeases(root, [...others, ...mine]);
+    return { mine, path };
+  });
+  if (claimed.error) {
+    return fail(`${claimed.error}`, EXIT.FAIL, `fix or remove ${claimed.path}; the pre-edit hook fails closed on it too`);
+  }
+  if (claimed.conflicts) {
+    return fail(
+      `${claimed.conflicts.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; ')}`,
+      EXIT.FAIL,
+      `wait for the TTL or ask the holder to release it (${CLI} lease release <paths> --session ${session}); run: ${CLI} lease to see every claim`,
+    );
+  }
+  const { mine, path } = claimed;
+
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'lease', root, session, ttl, dryRun: false, leases: mine, file: path });
+    return EXIT.OK;
+  }
+  const lines = [
+    `repo     ${root}`,
+    `session  ${session}`,
+    `ttl      ${ttl}s`,
+    ...mine.map((l) => `LEASED   ${l.path}  until ${ISO(l.expiresAt)}`),
+  ];
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+/** Resolve release/renew targets to canonical paths, or the usage failure. */
+function resolveTargets(root, args, session, verb) {
+  if (args.length === 0) {
+    return { error: fail(`lease ${verb} needs paths`, EXIT.USAGE, `run: ${CLI} lease ${verb} <paths> --session <id>`) };
+  }
+  const ignoreCase = coreIgnoreCase(root);
+  const wanted = [];
+  const seen = new Set();
+  for (const arg of args) {
+    const rel = canonicalLeasePath(root, arg, { ignoreCase });
+    if (rel === null) {
+      return { error: fail(`${arg} is not a path inside the repository`, EXIT.USAGE, `leases are repository-relative`) };
+    }
+    if (!seen.has(rel)) {
+      seen.add(rel);
+      wanted.push(rel);
+    }
+  }
+  return { wanted, seen, ignoreCase };
+}
+
+function claimSession(flags) {
+  const session = String(flags.session ?? process.env[SESSION_ENV] ?? '');
+  if (session === '') {
+    return { error: fail(`lease needs a session to hold the claim`, EXIT.USAGE, `run: ${CLI} lease <paths> --session <id> (or set ${SESSION_ENV})`) };
+  }
+  return { session };
+}
+
+async function releaseLeases(root, args, flags) {
+  const { session, error: sessionError } = claimSession(flags);
+  if (sessionError !== undefined) return sessionError;
+  const resolved = resolveTargets(root, args, session, 'release');
+  if (resolved.error !== undefined) return resolved.error;
+  const { wanted, seen, ignoreCase } = resolved;
+  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
+  const mode = writeMode(flags);
+
+  const released = await withLeaseLock(root, async () => {
+    const read = await readLeases(root);
+    if (read.error !== null) return { error: read.error, path: read.path };
+    const held = activeLeases(read);
+    const foreign = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    if (foreign.length > 0) {
+      return {
+        conflicts: foreign.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; '),
+      };
+    }
+    const dropped = held.filter((l) => seen.has(keyOf(l)));
+    if (!mode.apply) return { preview: dropped };
+    const kept = held.filter((l) => !seen.has(keyOf(l)));
+    const path = await writeLeases(root, kept);
+    return { dropped, path };
+  });
+  if (released.error) {
+    return fail(`${released.error}`, EXIT.FAIL, `fix or remove ${released.path}`);
+  }
+  if (released.conflicts) {
+    return fail(`${released.conflicts}`, EXIT.FAIL, `only the holder releases a claim; wait for the TTL or ask ${session} to run: ${CLI} lease release`);
+  }
+  if (!mode.apply) {
+    const lines = [
+      `repo     ${root}`,
+      `session  ${session}`,
+      ...released.preview.map((l) => `would    release ${l.path} (held by ${l.session})`),
+      ...(released.preview.length === 0 ? ['(no active claims on those paths)'] : []),
+      `apply    run: ${CLI} lease release ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`,
+    ];
+    if (isJson(flags)) emitJson({ ok: true, command: 'lease release', root, dryRun: true, session, leases: released.preview });
+    else emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  for (const l of released.dropped) note(`note     released ${l.path} (was held by ${l.session})`);
+  if (isJson(flags)) emitJson({ ok: true, command: 'lease release', root, dryRun: false, session, leases: released.dropped });
+  else {
+    emit(
+      [
+        `repo     ${root}`,
+        `session  ${session}`,
+        ...released.dropped.map((l) => `RELEASED ${l.path}`),
+        ...(released.dropped.length === 0 ? ['(no active claims on those paths)'] : []),
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+  }
+  return EXIT.OK;
+}
+
+async function renewLeases(root, args, flags) {
+  const { session, error: sessionError } = claimSession(flags);
+  if (sessionError !== undefined) return sessionError;
+  const resolved = resolveTargets(root, args, session, 'renew');
+  if (resolved.error !== undefined) return resolved.error;
+  const { wanted, seen, ignoreCase } = resolved;
+  const ttl = flags.ttl === undefined ? DEFAULT_TTL_SECONDS : Number(flags.ttl);
+  if (!Number.isInteger(ttl) || ttl < 1) {
+    return fail(`--ttl must be a positive number of seconds, received ${flags.ttl}`, EXIT.USAGE, `example: run: ${CLI} lease renew <paths> --ttl 900`);
+  }
+  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
+  const mode = writeMode(flags);
+
+  const renewed = await withLeaseLock(root, async () => {
+    const read = await readLeases(root);
+    if (read.error !== null) return { error: read.error, path: read.path };
+    const held = activeLeases(read);
+    const foreign = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    if (foreign.length > 0) {
+      return {
+        conflicts: foreign.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; '),
+      };
+    }
+    const expiresAt = Date.now() + ttl * 1000;
+    const mine = held.map((l) => (seen.has(keyOf(l)) ? { ...l, expiresAt } : l));
+    const touched = held.filter((l) => seen.has(keyOf(l)));
+    if (!mode.apply) return { preview: touched.map((l) => ({ ...l, expiresAt })) };
+    const path = await writeLeases(root, mine);
+    return { touched: touched.map((l) => ({ ...l, expiresAt })), path };
+  });
+  if (renewed.error) {
+    return fail(`${renewed.error}`, EXIT.FAIL, `fix or remove ${renewed.path}`);
+  }
+  if (renewed.conflicts) {
+    return fail(`${renewed.conflicts}`, EXIT.FAIL, `only the holder renews a claim; run: ${CLI} lease to see every claim`);
+  }
+  const rows = mode.apply ? renewed.touched : renewed.preview;
+  if (isJson(flags)) emitJson({ ok: true, command: 'lease renew', root, dryRun: !mode.apply, session, ttl, leases: rows });
+  else {
+    emit(
+      [
+        `repo     ${root}`,
+        `session  ${session}`,
+        `ttl      ${ttl}s`,
+        ...rows.map((l) => `${mode.apply ? 'RENEWED  ' : 'would    renew '} ${l.path} until ${ISO(l.expiresAt)}`),
+        ...(rows.length === 0 ? ['(no active claims on those paths)'] : []),
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+  }
+  return EXIT.OK;
+}
+
+async function listLeases(root, flags) {
+  const read = await readLeases(root);
+  if (read.error !== null) {
+    return fail(`${read.error}`, EXIT.FAIL, `fix or remove ${read.path}`);
+  }
+  const held = activeLeases(read);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'lease', root, leases: held });
+    return EXIT.OK;
+  }
+  const lines = [
+    `repo     ${root}`,
+    ...held.map((l) => `LEASED   ${l.path}  ${l.session}${l.harness ? `/${l.harness}` : ''}  until ${ISO(l.expiresAt)}`),
+  ];
+  if (held.length === 0) lines.push(`(no active leases)`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/lessons.mjs

@@ -4,6 +4,8 @@
 import { resolve } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
+import { commitJournal } from '../journal.mjs';
 import { CLI } from '../name.mjs';
 import { parsePathList } from '../argv.mjs';
 import {
@@ -21,13 +23,15 @@ export async function lessonsListCommand(args, flags) {
     return fail(`unknown lessons argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons`);
   }
   const root = resolve(flags.root ?? process.cwd());
-  await captureFromLedger(root);
-  await captureRevertedCommits(root);
-
+  // Pure: listing must not capture. Capture used to run here, so `list` wrote
+  // to the store it was reading and a read-only question had write side
+  // effects. Capturing is `lessons capture` now (review 0003 Q36).
   const [{ candidates, errors }, promoted] = await Promise.all([
     readLessonCandidates(root),
-    listPromotedLessons(root),
+    listPromotedLessons(root, { includeExpired: true }),
   ]);
+  const live = promoted.filter((l) => !l.expired);
+  const expiredCount = promoted.length - live.length;
 
   const payload = {
     ok: errors.length === 0,
@@ -36,9 +40,10 @@ export async function lessonsListCommand(args, flags) {
     ledgerFile: LESSONS_FILE,
     lessonsDir: LESSONS_DIR,
     candidateCount: candidates.length,
-    promotedCount: promoted.length,
+    promotedCount: live.length,
+    expiredCount,
     candidates,
-    promoted,
+    promoted: live,
     errors,
   };
 
@@ -49,7 +54,7 @@ export async function lessonsListCommand(args, flags) {
 
   const lines = [
     `candidates  ${candidates.length} (${LESSONS_FILE})`,
-    `promoted    ${promoted.length} (${LESSONS_DIR})`,
+    `promoted    ${live.length} (${LESSONS_DIR})${expiredCount > 0 ? `, ${expiredCount} expired` : ''}`,
   ];
 
   if (candidates.length > 0) {
@@ -61,12 +66,18 @@ export async function lessonsListCommand(args, flags) {
     }
   }
 
-  if (promoted.length > 0) {
+  if (live.length > 0) {
     lines.push('', 'LESSONS');
-    for (const l of promoted) {
+    for (const l of live) {
       lines.push(`  ${l.id.padEnd(28)}  ${(l.signature ?? 'no-signature').slice(0, 19)}  ${l.title}`);
     }
   }
+  if (expiredCount > 0) {
+    lines.push('', `EXPIRED ${expiredCount}`);
+    for (const l of promoted.filter((l) => l.expired)) {
+      lines.push(`  ${l.id.padEnd(28)}  expired ${l.expires ?? 'no date'}  ${l.title}`);
+    }
+  }
 
   for (const err of errors) lines.push(`error       ${err}`);
 
@@ -74,6 +85,45 @@ export async function lessonsListCommand(args, flags) {
   return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
+/**
+ * `simt lessons capture` — the explicit write half of the old `list`.
+ *
+ * Scans the ledger for fail-then-fix sequences and git history for reverts,
+ * and appends any new candidates. A command that writes says so in its name;
+ * `list` and `review` previews do not (review 0003 Q36).
+ */
+export async function lessonsCaptureCommand(args, flags) {
+  if (args.length > 0) {
+    return fail(`unknown lessons capture argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons capture`);
+  }
+  const root = resolve(flags.root ?? process.cwd());
+  const fromLedger = await captureFromLedger(root);
+  const reverts = await captureRevertedCommits(root);
+
+  const payload = {
+    ok: true,
+    command: 'lessons capture',
+    root,
+    failThenFix: fromLedger.length,
+    reverts: reverts.length,
+    captured: [...fromLedger, ...reverts],
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `captured    ${payload.captured.length} candidates (${LESSONS_FILE})`,
+    `  fail-then-fix  ${fromLedger.length}`,
+    `  reverts        ${reverts.length}`,
+  ];
+  for (const c of payload.captured) {
+    lines.push(`  ${c.id}  ${c.kind}  ${c.summary}`);
+  }
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
 export async function lessonsReviewCommand(args, flags) {
   if (args.length > 1) {
     return fail(`unknown lessons review argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} lessons review [<id>] [--yes]`);
@@ -83,18 +133,33 @@ export async function lessonsReviewCommand(args, flags) {
   const parsedPaths = parsePathList(flags.paths);
   const paths = parsedPaths.length > 0 ? parsedPaths : undefined;
   const title = flags.task ? String(flags.task) : undefined;
+  const expires = typeof flags.expires === 'string' && flags.expires.trim() !== '' ? flags.expires.trim() : undefined;
 
+  // Journaled so `undo` restores the promoted file (R49); committed only when
+  // the run actually wrote, which commitJournal already guarantees.
+  const journal = [];
   const result = await promoteLesson(root, {
     id: args[0],
     apply: mode.apply,
     paths,
     title,
+    expires,
+    journal: mode.apply ? journal : undefined,
   });
+  if (mode.apply && result.ok) await commitJournal(root, 'lessons review', journal);
 
   if (!result.ok) {
     return fail(result.error, EXIT.FAIL, `record a session failure-then-fix or run: ${CLI} lessons`);
   }
 
+  // The `--diff` pair: the promoted lesson file, created or refreshed (R50). The
+  // before-side rides on the result from `promoteLesson`, read before anything
+  // was written, so the diff is true in preview and in apply alike.
+  const diffs =
+    flags.diff === true
+      ? [{ path: result.path, before: result.before ?? null, after: result.markdown }]
+      : [];
+
   const payload = {
     ok: true,
     command: 'lessons review',
@@ -104,6 +169,7 @@ export async function lessonsReviewCommand(args, flags) {
     path: result.path,
     candidate: result.candidate,
     markdown: result.markdown,
+    ...diffField(diffs, flags),
   };
 
   if (isJson(flags)) {
@@ -120,6 +186,8 @@ export async function lessonsReviewCommand(args, flags) {
   ];
 
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   if (!mode.apply) {
     note(`note    dry-run  nothing written; apply with: ${CLI} lessons review --yes`);
   }

package/src/commands/map.mjs

@@ -1,11 +1,13 @@
 // `simt map` ranks the files a task is most likely to touch (R22, ADR-091).
-// The cache is read, and rebuilt once when it is empty, because a map of no
-// files is not an answer. The rebuild writes the gitignored index, which is
-// the same cache `simt index` writes.
+// The cache is refreshed from the git index on every read: `reindex` skips unchanged
+// blobs, so a current repository pays for one `git ls-files -s`, not a walk of the
+// tree. A map of stale files is a wrong answer, and the commands that read with
+// `build` on are ones a person typed at a terminal, where a few hundred
+// milliseconds is not a bar to meet.
 
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { readEdges, readEmbeddings, readFiles, readFts, readSymbols, reindex, searchFtsBm25 } from '../index/store.mjs';
+import { isIndexStale, readEdges, readEmbeddings, readFiles, readFts, readSymbols, reindex, searchFtsBm25 } from '../index/store.mjs';
 import {
   DEFAULT_BUDGET,
   embedTaskQuery,
@@ -89,20 +91,22 @@ async function recall(root, flags) {
 }
 
 /**
- * The files, symbols, edges, FTS rows and stored vector embeddings the index holds,
- * building the index once when it is empty.
+ * The files, symbols, edges, FTS rows and stored vector embeddings the index holds.
  *
- * `build: false` refuses that rebuild and answers with `cold: true` instead. The one
- * caller that passes it is the prompt-submit hook (R29), and the reason is the bar that
- * hook has to meet: a delivered packet that built an index would make a person's first
- * prompt in a fresh clone wait on a walk of the whole repository, and a prompt that takes
- * a minute to appear is how a hook gets uninstalled. The next prompt gets the packet, and
- * a command a person typed at a terminal always builds what it needs.
+ * With `build` (the default) the index is refreshed from the git index before it is
+ * read. The refresh is incremental — a blob that has not changed is not re-read — so
+ * the cost of a current repository is one `git ls-files -s`, not a walk of the tree.
+ * The callers that build are commands a person typed: `map`, `brief`, `slice`.
+ *
+ * `build: false` refuses the refresh and answers with `cold: true` when the index is
+ * empty. The callers that pass it are the prompt-submit hook (R29) and the MCP
+ * surface: a delivered packet that walked the whole repository would make a person's
+ * first prompt in a fresh clone wait, and a prompt that takes a minute to appear is
+ * how a hook gets uninstalled. The next prompt gets the packet, and a command a
+ * person typed at a terminal always builds what it needs.
  */
 export async function loadGraph(root, { build = true } = {}) {
-  let files = await readFiles(root);
-  if (files.length === 0) {
-    if (!build) return { files: [], symbols: [], edges: [], fts: [], embeddings: [], cold: true };
+  if (build) {
     try {
       await reindex(root);
     } catch (error) {
@@ -114,13 +118,24 @@ export async function loadGraph(root, { build = true } = {}) {
         ),
       };
     }
-    files = await readFiles(root);
   }
-  const [symbols, edges, fts, embeddings] = await Promise.all([
+  const [files, symbols, edges, fts, embeddings] = await Promise.all([
+    readFiles(root),
     readSymbols(root),
     readEdges(root),
     readFts(root),
     readEmbeddings(root),
   ]);
-  return { files, symbols, edges, fts, embeddings };
+  // A present index that cannot be read is named, not served as empty
+  // (review 0003 Q44): `cold` is "nothing here", `broken` is "something is
+  // here and the read failed".
+  const broken = !build && Boolean(files.error);
+  if (!build && files.length === 0) {
+    return { files: [], symbols: [], edges: [], fts: [], embeddings: [], cold: true, broken, stale: false };
+  }
+  // A caller that may not build still learns the index is old (review 0003
+  // Q42): the digest compare costs one `git ls-files -s`, and the freshness
+  // signal is what lets a UI distrust the packet instead of quoting it.
+  const stale = !build && files.length > 0 && (await isIndexStale(root));
+  return { files, symbols, edges, fts, embeddings, stale, broken };
 }

package/src/commands/mcp.mjs

@@ -45,10 +45,10 @@ export async function mcpCommand(positional, flags) {
       [
         `simt-dev ${version} - MCP surface over stdio (protocols ${SUPPORTED_VERSIONS.join(', ')})`,
         '',
-        `${TOOLS.length} read-only tools:`,
+        `${TOOLS.length} tools (all read-only except federation_query, which starts a declared server):`,
         ...TOOLS.map((t) => `  ${t.name.padEnd(16)} ${t.description.split('.')[0]}`),
         '',
-        'No tool here writes. init, sync, hooks install, skills install and upgrade stay in the',
+        'Nothing here writes to your repositories. init, sync, hooks install, skills install and upgrade stay in the',
         'CLI, because each is meant to be read as a diff by a human before it touches anything.',
         '',
         `serve them with: ${positional[0] ?? `${CLI} mcp`}`,

package/src/commands/pack.mjs

@@ -27,6 +27,7 @@ import {
   writeScaffold,
 } from '../packs/manage.mjs';
 import { readManifest } from '../projection/manifest.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 
 export async function packCommand(sub, args, flags) {
   if (sub === 'new') return packNew(args, flags);
@@ -100,6 +101,9 @@ async function packNew(args, flags) {
   const dir = join(resolve(flags.root ?? process.cwd()), name);
   const files = scaffoldPack({ name, source });
   const { apply, dryRun } = writeMode(flags);
+  // A scaffold always creates into a directory that must not exist, so every
+  // before side is empty and each pair is a whole file (R50).
+  const diffs = flags.diff === true ? files.map((f) => ({ path: `${name}/${f.path}`, before: null, after: f.text })) : [];
 
   if (isJson(flags)) {
     emitJson({
@@ -110,6 +114,7 @@ async function packNew(args, flags) {
       files: files.map((f) => f.path),
       packFile: PACK_JSON,
       benchFile: BENCH_JSON,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
@@ -126,6 +131,8 @@ async function packNew(args, flags) {
       ].join('\n'),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return EXIT.OK;
   }
 
@@ -144,6 +151,8 @@ async function packNew(args, flags) {
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }
 

package/src/commands/plan.mjs

@@ -1,5 +1,7 @@
+import { relative } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { formatCounts, planDone, planNext, planStatus } from '../plan/index.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 import { CLI } from '../name.mjs';
 
 // Preview unless --yes, and --dry-run wins even then. A tracker row marked done
@@ -79,8 +81,16 @@ async function runDone(root, id, sha, flags) {
     dryRun: !mode.apply,
   });
   if (result.error) return fail(result.error, EXIT.USAGE, result.remedy);
+  // The `--diff` pair: the one changed tracker row (R50). The sides ride on the
+  // result from `planDone`, captured pre-write, so the diff is true in preview
+  // and in apply alike. When nothing changed the sides are equal and the diff
+  // renders empty.
+  const diffs =
+    flags.diff === true && result.beforeLine !== undefined
+      ? [{ path: relative(root, result.file), before: result.beforeLine, after: result.afterLine }]
+      : [];
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'plan done', ...result });
+    emitJson({ ok: true, command: 'plan done', ...result, ...diffField(diffs, flags) });
     return EXIT.OK;
   }
   const lines = [`repo     ${root}`];
@@ -95,5 +105,7 @@ async function runDone(root, id, sha, flags) {
   if (result.evidenceRecorded) lines.push(`evidence ${result.sha}${result.test ? `  test: ${result.test}` : ''}`);
   else if (result.evidenceNote) lines.push(`note     ${result.evidenceNote}`);
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }