simt-dev 0.6.3 → 0.7.1

package/src/commands/lease.mjs

@@ -1,4 +1,7 @@
 // `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
@@ -12,15 +15,29 @@
 // (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, writeMode } from '../output/index.mjs';
-import { DEFAULT_TTL_SECONDS, activeLeases, leasePathFor, readLeases, writeLeases } from '../lease.mjs';
+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';
+import { commandRoot } from '../repo-root.mjs';
 
 const ISO = (ms) => new Date(ms).toISOString();
 
 export async function leaseCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
+  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.
@@ -39,11 +56,17 @@ export async function leaseCommand(args, flags) {
   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 = leasePathFor(root, arg);
+    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}`);
     }
@@ -53,37 +76,19 @@ export async function leaseCommand(args, flags) {
     }
   }
 
-  const read = await readLeases(root);
-  if (read.error !== null) {
-    return fail(`${read.error}`, EXIT.FAIL, `fix or remove ${read.path}; the pre-edit hook fails closed on it too`);
-  }
-  const held = activeLeases(read);
-  const conflicts = held.filter((l) => seen.has(l.path) && l.session !== session);
-  if (conflicts.length > 0) {
-    return fail(
-      `${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; run: ${CLI} lease to see every claim`,
-    );
-  }
+  // 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 expiresAt = Date.now() + ttl * 1000;
-  const apply = `run: ${CLI} lease ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`;
   const mode = writeMode(flags);
-  const mine = wanted.map((path) => ({ path, session, expiresAt }));
-
   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,
-      });
+      emitJson({ ok: true, command: 'lease', root, dryRun: true, session, ttl, leases: mine, remedy: apply });
       return EXIT.OK;
     }
     const lines = [
@@ -93,14 +98,37 @@ export async function leaseCommand(args, flags) {
       ...mine.map((l) => `would    lease ${l.path} until ${ISO(l.expiresAt)}`),
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
-  // 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(l.path));
-  const path = await writeLeases(root, [...others, ...mine]);
+  // 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 });
@@ -112,7 +140,146 @@ export async function leaseCommand(args, flags) {
     `ttl      ${ttl}s`,
     ...mine.map((l) => `LEASED   ${l.path}  until ${ISO(l.expiresAt)}`),
   ];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
+  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'));
+    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'),
+    );
+  }
+  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'),
+    );
+  }
   return EXIT.OK;
 }
 
@@ -128,9 +295,9 @@ async function listLeases(root, flags) {
   }
   const lines = [
     `repo     ${root}`,
-    ...held.map((l) => `LEASED   ${l.path}  ${l.session}  until ${ISO(l.expiresAt)}`),
+    ...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 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/lessons.mjs

@@ -5,6 +5,7 @@ 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 {
@@ -16,19 +17,22 @@ import {
   promoteLesson,
   readLessonCandidates,
 } from '../memory/lessons.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function lessonsListCommand(args, flags) {
   if (args.length > 0) {
     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);
-
+  const root = resolve(commandRoot(flags));
+  // 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,
@@ -37,20 +41,21 @@ 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,
   };
 
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
   }
 
   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) {
@@ -62,35 +67,87 @@ 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}`);
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   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(commandRoot(flags));
+  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);
+    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'));
+  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]`);
   }
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const mode = writeMode(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`);
@@ -117,7 +174,7 @@ export async function lessonsReviewCommand(args, flags) {
   };
 
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
 
@@ -129,7 +186,7 @@ export async function lessonsReviewCommand(args, flags) {
     result.markdown.trimEnd(),
   ];
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
   if (!mode.apply) {

package/src/commands/local.mjs

@@ -8,6 +8,7 @@ import { resolve } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { probeLocal } from '../local/client.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 function formatRoleLine(role, report) {
   if (!report) return `${role.padEnd(8)} (unset)`;
@@ -55,7 +56,7 @@ function remedyFor(result) {
 }
 
 export async function localDoctorCommand(args, flags) {
-  const root = resolve(flags.root ?? args[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, args));
   const allowRemote = flags.allowRemote === true;
   const result = await probeLocal(root, { allowRemote });
 
@@ -86,7 +87,6 @@ export async function localDoctorCommand(args, flags) {
         findings: result.findings,
         ...(error ? { error, remedy, exitCode: code } : {}),
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return code;
   }
@@ -99,7 +99,7 @@ export async function localDoctorCommand(args, flags) {
     `sockets  ${result.socketsOpened}`,
   ];
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
 
   if (!result.ok) {
     return fail(error, code, remedy);

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 { EXIT, emit, emitJson, fail, isJson, present } 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,
@@ -14,12 +16,13 @@ import {
   rankFiles,
   renderMap,
 } from '../index/map.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const LEVELS = new Set(['outline', 'names', 'signatures']);
 
 export async function mapCommand(args, flags) {
   if (args.length > 0) return fail(`unknown map argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} map`);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (flags.recall === true) return recall(root, flags);
   const level = flags.level ?? 'outline';
   if (!LEVELS.has(level)) {
@@ -42,12 +45,19 @@ export async function mapCommand(args, flags) {
       : null;
   const ranked = rankFiles({ ...loaded, bm25, queryVector, task });
   const rendered = renderMap(ranked, loaded.symbols, { level, budget });
+  // What the ranking is an answer to. `graph-only` says no file or symbol mentioned the
+  // task and the list is the graph hub; reading that as a hit is how `map --task
+  // zebracorn` looked useful (review 0003 Q52).
+  const matched = ranked.filter((row) => (row.score ?? 0) > 0).length;
+  const basis = task.trim().length === 0 ? 'no-task' : matched > 0 ? 'matched' : 'graph-only';
   const payload = {
     ok: true,
     command: 'map',
     root,
     level,
     budget,
+    matched,
+    basis,
     shown: rendered.shown,
     total: rendered.total,
     truncated: rendered.truncated,
@@ -55,17 +65,18 @@ export async function mapCommand(args, flags) {
     text: rendered.text,
   };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = [
     `level    ${level}`,
+    `basis    ${basis}${basis === 'graph-only' ? ' (no file or symbol mentions this task; the list is the graph hub)' : ''}`,
     `shown    ${rendered.shown}`,
     `total    ${rendered.total}`,
     `budget   ${budget}`,
   ];
   if (rendered.text) lines.push(rendered.text);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -80,29 +91,27 @@ async function recall(root, flags) {
     return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
   }
   const payload = { ok: true, command: 'map', root, recall: result };
-  if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
-    return EXIT.OK;
-  }
-  emit(formatRecall(result), { maxBytes: flags.maxBytes ?? 0 });
+  present(payload, () => formatRecall(result), flags);
   return EXIT.OK;
 }
 
 /**
- * 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 +123,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

@@ -53,7 +53,6 @@ export async function mcpCommand(positional, flags) {
         '',
         `serve them with: ${positional[0] ?? `${CLI} mcp`}`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }