simt-dev 0.6.3 → 0.7.0

package/src/bench/run.mjs

@@ -10,6 +10,7 @@ import { extractOpenedSkills, matchSkillsForPaths } from '../graph/compile.mjs';
 import { matchGlob } from '../index/govern.mjs';
 import { formatLessonParagraph, listPromotedLessons } from '../memory/lessons.mjs';
 import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+import { LOCAL_DIR } from '../state.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { plan } from '../projection/project.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
@@ -119,7 +120,7 @@ function firstNumeric(obj, paths = []) {
 function emptyUsage() {
   return {
     usage: { input: 0, cacheWrite: 0, cacheRead: 0, output: 0, turns: 0, toolCalls: 0 },
-    costUsd: 0.0,
+    costUsd: null,
   };
 }
 
@@ -163,7 +164,7 @@ function parseJsonObject(text) {
  * @param {string|object} adapterOrId
  * @param {string} stdoutText
  * @param {string} [analyticsText]
- * @returns {{usage: {input: number, cacheWrite: number, cacheRead: number, output: number, turns: number, toolCalls: number}, costUsd: number}}
+ * @returns {{usage: {input: number, cacheWrite: number, cacheRead: number, output: number, turns: number, toolCalls: number}, costUsd: number|null}}
  */
 export function parseAdapterUsage(adapterOrId, stdoutText = '', analyticsText = '') {
   const result = emptyUsage();
@@ -192,7 +193,7 @@ export function parseAdapterUsage(adapterOrId, stdoutText = '', analyticsText =
     result.usage.output = firstNumeric(obj, fields.output) ?? 0;
     result.usage.turns = firstNumeric(obj, fields.turns) ?? 0;
     result.usage.toolCalls = firstNumeric(obj, fields.toolCalls) ?? 0;
-    result.costUsd = firstNumeric(obj, fields.costUsd) ?? 0.0;
+    result.costUsd = firstNumeric(obj, fields.costUsd) ?? null;
 
     // Gemini CLI also nests per-model token totals under `stats.models.<name>.tokens`.
     const models = obj?.stats?.models;
@@ -265,7 +266,7 @@ export function parseAdapterUsage(adapterOrId, stdoutText = '', analyticsText =
     }
   }
 
-  result.costUsd = Number(result.costUsd.toFixed(6));
+  if (result.costUsd !== null) result.costUsd = Number(result.costUsd.toFixed(6));
   return result;
 }
 
@@ -513,7 +514,7 @@ async function writeTaskBrief(workDir, task) {
       : []),
     '',
   ];
-  const briefPath = join(workDir, STATE_DIR, 'brief.md');
+  const briefPath = join(workDir, LOCAL_DIR, 'brief.md');
   await mkdir(dirname(briefPath), { recursive: true });
   await writeFile(briefPath, lines.join('\n'), 'utf8');
 }
@@ -741,7 +742,7 @@ export async function runBench(
     throw new Error(
       filterTaskIds.length > 0
         ? `no mined tasks matched: ${filterTaskIds.join(', ')}`
-        : `no mined tasks found in ${STATE_DIR}/bench/tasks`,
+        : `no mined tasks found in .simt/bench/tasks`,
     );
   }
 
@@ -781,14 +782,14 @@ export async function runBench(
         resolved: null,
         gatesPassed: null,
         usage: emptyUsage().usage,
-        costUsd: 0.0,
+        costUsd: null,
         diff: { files: 0, outsideBlastRadius: 0 },
         probe: null,
       })),
     };
   }
 
-  const runsBaseDir = join(root, STATE_DIR, 'bench', 'runs');
+  const runsBaseDir = join(root, LOCAL_DIR, 'bench', 'runs');
   for (const armSpec of armSpecs) {
     for (let rep = 1; rep <= reps; rep += 1) {
       const runDir = join(runsBaseDir, runIdFor(harness, armSpec.name, rep));
@@ -877,7 +878,7 @@ export async function runBench(
 }
 
 async function resolveRegradeTargets(root, target) {
-  const runsBaseDir = join(root, STATE_DIR, 'bench', 'runs');
+  const runsBaseDir = join(root, LOCAL_DIR, 'bench', 'runs');
   const direct = resolve(root, target);
   const candidate = existsSync(direct) ? direct : join(runsBaseDir, target);
 
@@ -933,8 +934,8 @@ export async function regradeRun(
     throw new Error(`no stored task runs found under ${target}`);
   }
 
-  const tasksDir = join(root, STATE_DIR, 'bench', 'runs');
-  const taskDefsDir = join(root, STATE_DIR, 'bench', 'tasks');
+  const tasksDir = join(root, LOCAL_DIR, 'bench', 'runs');
+  const taskDefsDir = join(root, '.simt', 'bench', 'tasks');
   const parentDir = await mkdtemp(join(tmpdir(), 'bench-regrade-'));
 
   try {

package/src/bench/variants.mjs

@@ -3,14 +3,14 @@
 // Discovers `simt-variants` slots across applicable rules, runs candidate
 // variants on the 10-task canary suite (escalating when significant), records
 // the winning variant with `{winner, variant, model, harness, dR, dC, n, p}`
-// in `simt-dev.lock.json`, and re-opens the experiment whenever the target
+// in `simt.lock.json`, and re-opens the experiment whenever the target
 // model or harness changes.
 
 import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 
 import { extractVariantsFromRule, readLockedVariants } from '../kernel/variants.mjs';
-import { MANIFEST_FILE, STATE_DIR } from '../name.mjs';
+import { LOCK_FILE, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { writeLockVariants } from '../projection/lock.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
@@ -21,12 +21,22 @@ import { CANARY_ALPHA, DEFAULT_CANARY_SIZE, DEL_R_TOLERANCE, shouldEscalateCanar
 import {
   DEFAULT_BOOTSTRAP_SAMPLES,
   DEFAULT_BOOTSTRAP_SEED,
+  collapseArmByTask,
   compareArms,
   evaluateRunRecord,
+  holmAdjust,
   loadPrices,
   loadRunRecords,
 } from './report.mjs';
 
+/**
+ * Harnesses that grade, not answer: `gold` applies the oracle patch and `noop` does
+ * nothing (`src/bench/adapters.json`, `kind: "builtin"`). Their runs measure the
+ * grader, not the rule text, so they must never close a variant experiment by
+ * writing a lock entry (Q45). A test asserts this set matches the adapter table.
+ */
+export const BUILTIN_HARNESSES = new Set(['gold', 'noop']);
+
 /**
  * Discover every `simt-variants` slot across applicable rules for `root`.
  */
@@ -131,6 +141,19 @@ export async function applyVariantInWorkspace(workDir, variant) {
   delete nextManifest.mode;
   await writeFile(manifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
 
+  // plan() writes the lock as a target (Q29). Left behind, it records this arm's
+  // winner as locked, and the next selectRuleVariants on the same tree reads the
+  // experiment as closed and never runs the runner. Restore it, like the manifest.
+  const lockPath = join(workDir, LOCK_FILE);
+  let originalLockBytes = null;
+  let hadLock = false;
+  try {
+    originalLockBytes = await readFile(lockPath, 'utf8');
+    hadLock = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
   const planned = await plan(workDir, {
     variants: { [slotId]: { winner: variantKey } },
   });
@@ -146,30 +169,36 @@ export async function applyVariantInWorkspace(workDir, variant) {
   } else if (originalManifestBytes !== null) {
     await writeFile(manifestPath, originalManifestBytes, 'utf8');
   }
+  if (!hadLock) {
+    await unlink(lockPath).catch(() => {});
+  } else {
+    await writeFile(lockPath, originalLockBytes, 'utf8');
+  }
 }
 
+/**
+ * Mean per-task R and C for one arm's evaluated runs.
+ *
+ * `collapseArmByTask` is the shared per-task aggregation: the evaluated rows carry
+ * the cost in `C`, and the old body summed `costUsd` — a field the rows never had —
+ * so C was NaN and the cost rank degenerated to a key tie-break (Q45).
+ */
 function summarizeEvaluated(evaluated) {
-  if (evaluated.length === 0) {
-    return { n: 0, R: 0, C: 0 };
-  }
-  const byTask = new Map();
-  for (const row of evaluated) {
-    const list = byTask.get(row.task) ?? [];
-    list.push(row);
-    byTask.set(row.task, list);
-  }
+  const tasks = collapseArmByTask(evaluated);
+  if (tasks.length === 0) return { n: 0, R: 0, C: null };
   let sumR = 0;
   let sumC = 0;
-  for (const list of byTask.values()) {
-    sumR += list.reduce((a, x) => a + x.R, 0) / list.length;
-    sumC += list.reduce((a, x) => a + x.costUsd, 0) / list.length;
+  let costComplete = true;
+  for (const t of tasks) {
+    sumR += t.R;
+    if (t.C === null) costComplete = false;
+    else sumC += t.C;
   }
-  const n = byTask.size;
-  return { n, R: sumR / n, C: sumC / n };
+  return { n: tasks.length, R: sumR / tasks.length, C: costComplete ? sumC / tasks.length : null };
 }
 
 /**
- * Run or evaluate variant selection on the canary suite and record winners in `simt-dev.lock.json`.
+ * Run or evaluate variant selection on the canary suite and record winners in `simt.lock.json`.
  */
 export async function selectRuleVariants(
   root,
@@ -267,19 +296,31 @@ export async function selectRuleVariants(
       for (const { slot } of openStates) {
         const baseArm = variantArmName(slot.slotId, slot.baseline);
         const baseRecs = canaryEvaluated.filter((r) => r.arm === baseArm);
+        const slotComps = [];
         for (const key of Object.keys(slot.variants)) {
           if (key === slot.baseline) continue;
           const candArm = variantArmName(slot.slotId, key);
           const candRecs = canaryEvaluated.filter((r) => r.arm === candArm);
           if (baseRecs.length > 0 && candRecs.length > 0) {
-            const comp = compareArms(baseArm, baseRecs, candArm, candRecs, { samples, seed });
-            if (shouldEscalateCanary(comp, { alpha: CANARY_ALPHA })) {
-              includeBaseline.add(baseArm);
-              armsToEscalate.push(candArm);
-              escalatedArms.add(candArm);
-            }
+            slotComps.push({
+              candArm,
+              comp: compareArms(baseArm, baseRecs, candArm, candRecs, { samples, seed }),
+            });
           }
         }
+        // Family = every variant of this slot versus its baseline: testing several
+        // variants at α 0.05 each inflates the false-positive rate, so the p-values
+        // are Holm-adjusted before the escalation decision (review 0003 Q46).
+        const adjusted = holmAdjust(
+          slotComps.map(({ comp }) => Math.min(comp.rTest.pValue, comp.wilcoxon.pValue)),
+        );
+        slotComps.forEach(({ candArm, comp }, i) => {
+          if (shouldEscalateCanary(comp, { alpha: CANARY_ALPHA, pValue: adjusted[i] })) {
+            includeBaseline.add(baseArm);
+            armsToEscalate.push(candArm);
+            escalatedArms.add(candArm);
+          }
+        });
       }
       const fullEscalationArms = [...includeBaseline, ...armsToEscalate];
       if (fullEscalationArms.length > 0) {
@@ -321,6 +362,7 @@ export async function selectRuleVariants(
         reason,
         measured: true,
         winner: winnerKey,
+        locked: true,
         model: lockedEntry.model ?? resolvedModel,
         harness: lockedEntry.harness ?? harness,
         dR: Number(lockedEntry.dR ?? 0),
@@ -367,6 +409,7 @@ export async function selectRuleVariants(
         reason,
         measured: false,
         winner: slot.baseline,
+        locked: false,
         model: resolvedModel,
         harness,
         dR: 0,
@@ -377,13 +420,16 @@ export async function selectRuleVariants(
       continue;
     }
 
-    // Rank variants: higher R (beyond tolerance), then lower C, then fewer bytes, then key.
+    // Rank variants: higher R (beyond tolerance), then lower C (an unknown cost is
+    // worst — it cannot be ranked cheaper), then fewer bytes, then key.
     const ranked = [...candidates].sort((a, b) => {
       if (Math.abs(b.summary.R - a.summary.R) > DEL_R_TOLERANCE) {
         return b.summary.R - a.summary.R;
       }
-      if (Math.abs(a.summary.C - b.summary.C) > 1e-9) {
-        return a.summary.C - b.summary.C;
+      const ca = a.summary.C === null ? Number.POSITIVE_INFINITY : a.summary.C;
+      const cb = b.summary.C === null ? Number.POSITIVE_INFINITY : b.summary.C;
+      if (Math.abs(ca - cb) > 1e-9) {
+        return ca - cb;
       }
       if (a.bytes !== b.bytes) return a.bytes - b.bytes;
       return a.key.localeCompare(b.key);
@@ -397,10 +443,13 @@ export async function selectRuleVariants(
 
     if (best.key !== slot.baseline && best.comparison) {
       dR = Number(best.comparison.deltas.R.toFixed(4));
-      dC = Number(best.comparison.deltas.C.toFixed(4));
+      dC =
+        best.comparison.deltas.C === null
+          ? 0
+          : Number(best.comparison.deltas.C.toFixed(4));
       n = best.comparison.pairedTasks;
       p = Number(
-        Math.min(best.comparison.mcnemar.pValue, best.comparison.wilcoxon.pValue).toFixed(4),
+        Math.min(best.comparison.rTest.pValue, best.comparison.wilcoxon.pValue).toFixed(4),
       );
     } else {
       const runnerUp = ranked.find((c) => c.key !== slot.baseline && c.comparison);
@@ -409,17 +458,33 @@ export async function selectRuleVariants(
       }
     }
 
-    const lockEntry = {
-      winner: best.key,
-      variant: best.key,
-      model: resolvedModel,
-      harness,
-      dR,
-      dC,
-      n,
-      p,
-    };
-    nextVariantsLock[slot.slotId] = lockEntry;
+    // A non-baseline winner locks only when it is significant AND non-inferior
+    // (Q45): p below the canary alpha, and dR within the deletion tolerance.
+    // Anything else locks the baseline: the experiment ran, and its conclusion is
+    // "keep what we had" - recorded, so the next run on this model and harness
+    // reads it as closed instead of re-measuring.
+    const significant =
+      best.key !== slot.baseline &&
+      best.comparison !== null &&
+      p < CANARY_ALPHA &&
+      dR >= -DEL_R_TOLERANCE;
+    const winnerKey = significant ? best.key : slot.baseline;
+
+    // Built-in harnesses grade, they do not answer: their runs must not close the
+    // experiment, so no lock entry is written for them and the next run re-measures
+    // (Q45). The result still reports the measured best, flagged `locked: false`.
+    if (!BUILTIN_HARNESSES.has(harness)) {
+      nextVariantsLock[slot.slotId] = {
+        winner: winnerKey,
+        variant: winnerKey,
+        model: resolvedModel,
+        harness,
+        dR,
+        dC,
+        n,
+        p,
+      };
+    }
 
     results.push({
       slotId: slot.slotId,
@@ -430,7 +495,14 @@ export async function selectRuleVariants(
       reopened,
       reason,
       measured: true,
-      ...lockEntry,
+      winner: BUILTIN_HARNESSES.has(harness) ? best.key : winnerKey,
+      locked: significant && !BUILTIN_HARNESSES.has(harness),
+      model: resolvedModel,
+      harness,
+      dR,
+      dC,
+      n,
+      p,
     });
   }
 

package/src/brief/assemble.mjs

@@ -132,6 +132,7 @@ export async function assembleBrief({
   const graph = await loadGraph(root, { build });
   if (graph.error) return { error: graph.error };
   if (graph.cold) return { cold: true };
+  const graphStale = graph.stale === true;
   const { files, symbols, edges, fts = [], embeddings = [] } = graph;
   const filePaths = new Set(files.map((file) => file.path));
 
@@ -150,6 +151,11 @@ export async function assembleBrief({
       why: ['an unasked question has no answer to be short of'],
     });
   }
+  if (graphStale) {
+    packet.add('CAUTIONS', 'the index predates the current tree, so files added or removed since the last build are missing or ghosted', {
+      why: ['this caller may not rebuild the index; run a command that can before quoting the file list'],
+    });
+  }
 
   const repo = await fingerprint(root);
   const card = await commandCard({ root, manifest: repo.manifest ?? null, stack: repo.stack, facts: repo.facts });

package/src/ci/workflow.mjs

@@ -52,6 +52,7 @@ import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
 import { LOCAL_BIN, LOCAL_BIN_DIR, assetNameExpr, localInstall, platformLines, releaseBase } from '../distribute/release.mjs';
+import { installCommands as nodeInstallCommands } from '../ecosystem/node-runner.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -253,7 +254,7 @@ function indent(text, spaces) {
  * @param {{own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderWorkflow({ own = false, npm = true, version } = {}) {
+export function renderWorkflow({ own = false, npm = true, manager = null, version } = {}) {
   if (own) {
     const floor = nodeFloor();
     return `${header(true)}${skeleton(
@@ -286,6 +287,12 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
   }
 
   const v = version ?? packageVersion();
+  // Q31: the install step names the repo's own manager. `manager` wins over the
+  // legacy `npm` boolean so old callers keep their bytes; a Node repo installs
+  // with its lockfile's frozen command, anything else takes the release binary.
+  // The resolver row also decides setup-node (bun ships its own runtime).
+  const nodeManager = manager ?? (npm ? 'npm' : null);
+  const nodeInstall = nodeManager ? nodeInstallCommands(nodeManager) : null;
   // The install step is the whole of S35's consumer CI: a repository with npm pins
   // simt-dev as a devDependency and `npm ci` restores it; one without (Gradle,
   // Connect IQ) has no node_modules to pin in, so CI downloads the release binary
@@ -301,11 +308,11 @@ export function renderWorkflow({ own = false, npm = true, version } = {}) {
   // `${{ runner.* }}` expression: an expression substituted into `$( … )` is a
   // command substitution trying to execute "Linux", which set -eu refuses - the
   // install would fail on every run in the one repository kind this channel is for.
-  const install = npm
+  const install = nodeInstall
     ? [
         '      - name: install dependencies',
-        '        # `npm ci` needs a lockfile; a repo without one is still gated, not skipped.',
-        '        run: npm ci || npm install',
+        `        # \`${nodeInstall.install}\` needs a lockfile; a repo without one is still gated, not skipped.`,
+        `        run: ${nodeInstall.install} || ${nodeInstall.fallback}`,
       ]
     : [
         '      - name: install the pinned gate binary',
@@ -329,8 +336,9 @@ mkdir -p ${LOCAL_BIN_DIR}
 mv "$asset" ${LOCAL_BIN}
 chmod +x ${LOCAL_BIN}`, 10),
       ];
-  const remedy = npm
-    ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
+  const addDev = { npm: `npm i -D ${PACKAGE_NAME}`, pnpm: `pnpm add -D ${PACKAGE_NAME}`, yarn: `yarn add -D ${PACKAGE_NAME}`, bun: `bun add -d ${PACKAGE_NAME}` }[nodeManager] ?? null;
+  const remedy = nodeInstall && addDev
+    ? `REMEDY run: ${addDev}   (the gate runs from the pinned dependency)`
     : `REMEDY run: ${localInstall(v)}   (the gate runs from the release binary in .simt/bin)`;
   const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
@@ -338,7 +346,8 @@ chmod +x ${LOCAL_BIN}`, 10),
     [
       uses('checkout'),
       // The binary branch has no setup-node: see the install step above.
-      ...(npm ? [setupNode(nodeFloor())] : []),
+      // Q31: bun ships its own runtime, so only managers that need Node get it.
+      ...(nodeInstall && nodeInstall.setupNode ? [setupNode(nodeFloor())] : []),
       ...install,
       `      - name: ${CLI} check`,
       '        run: |',

package/src/commands/agent.mjs

@@ -0,0 +1,206 @@
+// simt agents install | simt agents status
+//
+// Two commands, one subject: the one agent this tool ships, written into each
+// harness's own agents directory. `install` writes the file, and `status`
+// reports what each harness carries and what still has to be installed.
+//
+// An agent is a file the tool owns whole — markdown with a frontmatter the
+// harness documents, or a TOML file for Codex — not a config entry to merge.
+// So the install is a byte comparison: created, unchanged, updated. There is no
+// parse that can fail and no partial state, which is what makes this command
+// shorter than `agent-hooks install`.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { commitJournal } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import {
+  adapter,
+  adapters,
+  agentPath,
+  agentRows,
+  loadAgent,
+  planAgents,
+  rendered,
+  writeAgentPlan,
+} from '../agents/render.mjs';
+
+export async function agentsCommand(sub, args, flags) {
+  const root = flags.root ?? args[0] ?? process.cwd();
+  if (sub === 'install') return installAgents(root, flags);
+  if (sub === 'status') return agentsStatus(root, flags);
+  return fail(`unknown agents subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agents status`);
+}
+
+// The label for a reader the run did not write, by the state that names why:
+// `none` documents no agents file, `other` is a reader this tool does not write,
+// `skipped` was an adapter the caller did not ask for (ADR-107).
+const OTHER_LABEL = { none: 'NO FILE ', other: 'NOT OURS', skipped: 'SKIPPED ' };
+
+async function installAgents(root, flags) {
+  const mode = writeMode(flags);
+  // `--harness` narrows the install to one reader (ADR-107). The id is validated
+  // against the same table the loop reads, so a typo fails before anything is
+  // planned; the remedy names the ids the way `agent-hook` does.
+  const selected = flags.harness;
+  if (selected !== undefined && adapter(selected) === null) {
+    return fail(
+      `unknown harness \`${selected}\``,
+      EXIT.USAGE,
+      `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
+    );
+  }
+
+  const plan = await planAgents(root, { harness: selected });
+
+  // The readers this tool does not write a file for, reported rather than skipped in
+  // silence: a command that writes six files and says nothing about the two harnesses
+  // that document no agents file reads as "those are covered too". A narrowed install
+  // adds a third state: an adapter that is this tool's but was not requested (ADR-107).
+  const others = [];
+  for (const r of agentRows()) {
+    if (r.path === null) others.push({ id: r.id, path: null, state: 'none', note: r.note });
+    else if (adapter(r.id) === null) others.push({ id: r.id, path: r.path, state: 'other', note: r.note });
+    else if (selected !== undefined && r.id !== selected) {
+      others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
+    }
+  }
+
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50).
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        plan
+          .filter((p) => p.action !== 'unchanged')
+          .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text })),
+      )
+      : [];
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'agents install',
+        root,
+        dryRun: true,
+        plan: plan.map(({ text, ...rest }) => rest),
+        notWritten: others,
+        filesWritten: false,
+        ...diffField(diffs, flags),
+      });
+      return EXIT.OK;
+    }
+    emit(
+      [
+        `repo     ${root}`,
+        ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
+        ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no agents file is documented)'}`),
+        '',
+        `PLAN     nothing written; apply with: ${CLI} agents install --yes`,
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
+    return EXIT.OK;
+  }
+
+  // Journaled so `undo` restores this run (R49).
+  const journal = [];
+  const written = await writeAgentPlan(root, journal, plan);
+  await commitJournal(root, 'agents install', journal);
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'agents install',
+      root,
+      plan: plan.map(({ text, ...rest }) => rest),
+      notWritten: others,
+      written,
+      filesWritten: true,
+      ...diffField(diffs, flags),
+    });
+    return EXIT.OK;
+  }
+  emit(
+    [
+      `repo     ${root}`,
+      ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
+      ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no agents file is documented)'}`),
+      '',
+      `WROTE    ${written.length} agent file(s)`,
+    ].join('\n'),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
+  for (const o of others) note(`note     ${o.id}: not written - ${o.note}`);
+  if (written.length === 0) note('note     every documented agents file already carried this agent');
+  note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
+  return EXIT.OK;
+}
+
+async function agentsStatus(root, flags) {
+  const agent = await loadAgent();
+  const rows = [];
+  const problems = [];
+
+  // The file this tool owns whole is compared against what `install` would write
+  // right now, so status reads the same bytes install reads: a file that matches
+  // the preview is present, anything else is drift an install will rewrite.
+  for (const row of adapters()) {
+    const path = agentPath(row.id);
+    const existing = await readIfExists(join(root, path));
+    if (existing === null) {
+      rows.push({ id: row.id, path, state: 'absent', note: null });
+      continue;
+    }
+    const present = rendered(row, agent, existing).action === 'unchanged';
+    rows.push({
+      id: row.id,
+      path,
+      state: present ? 'present' : 'drift',
+      note: present ? null : 'differs from what install would write; run install to restore it',
+    });
+  }
+
+  // The readers whose agents are not a file this tool can write — a vendor page
+  // that documents none — are reported from the same table that documents them,
+  // rather than from a second list of the harnesses this command happens to know.
+  for (const r of agentRows()) {
+    if (r.path === null) rows.push({ id: r.id, path: null, state: 'none', note: r.note });
+    else if (adapter(r.id) === null) rows.push({ id: r.id, path: r.path, state: 'other', note: r.note });
+  }
+
+  if (isJson(flags)) {
+    emitJson({ ok: problems.length === 0, command: 'agents status', root, harnesses: rows, problems });
+    return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
+  }
+
+  const lines = [`repo     ${root}`];
+  for (const r of rows) {
+    const state = { present: 'PRESENT ', absent: 'ABSENT  ', drift: 'DRIFT   ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
+    lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no agents file is documented)'}`);
+    if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agents install --yes`);
+    if (r.note) lines.push(`          ${' '.repeat(12)} ${r.note}`);
+  }
+  if (problems.length > 0) {
+    lines.push('', 'problems:');
+    for (const p of problems) lines.push(`  ${p}`);
+  }
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
+}
+
+async function readIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}