@ionivetech/mugiwara 0.6.6 → 0.7.0

package/src/integrity.ts

@@ -0,0 +1,158 @@
+// src/integrity.ts
+// Closure integrity gate: the audit trail validates itself
+// at archive time. Deterministic checks only — a violation fails the archive
+// with an actionable message instead of shipping a broken or leaking artifact.
+//
+// Three checks:
+//   1. Paths — every relative markdown link in the trail resolves to a file
+//      (mission-relative or repo-root).
+//   2. Secrets — no trail file matches known secret shapes.
+//   3. Evidence — cited wave/evidence paths exist.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+
+export type IntegrityIssue = { kind: 'dangling-path' | 'secret' | 'evidence' | 'evidence-thin'; detail: string };
+
+const SECRET_PATTERNS: Array<[RegExp, string]> = [
+  [/AKIA[0-9A-Z]{16}/, 'AWS access key id'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'private key block'],
+  [/gh[pousr]_[A-Za-z0-9]{20,}/, 'GitHub token'],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/, 'Slack token'],
+  [/sk-[A-Za-z0-9]{32,}/, 'API key (sk-…)'],
+  [/eyJhbGciOi[A-Za-z0-9_.-]{20,}/, 'JWT pasted verbatim'],
+  [/(api[_-]?key|secret|passwd|password)\s*[=:]\s*["'][^"'\s]{8,}["']/i, 'credential assignment'],
+];
+
+const ALLOW_SECRET = 'mugiwara:allow-secret';
+
+/** Secret shapes per line; a line carrying the allow marker is skipped — deliberate examples stay possible. */
+function findSecrets(body: string): Array<{ label: string; hit: string }> {
+  const out: Array<{ label: string; hit: string }> = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (line.includes(ALLOW_SECRET)) continue;
+    for (const [re, label] of SECRET_PATTERNS) {
+      const hit = line.match(re);
+      if (hit) out.push({ label, hit: hit[0] });
+    }
+  }
+  return out;
+}
+
+const TRAIL_EXTS = new Set(['.md', '.json', '.sh']);
+
+function trailFiles(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (TRAIL_EXTS.has(e.name.slice(e.name.lastIndexOf('.')) || '')) out.push(p);
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/** Relative markdown-link targets like `](../src/x.ts)` — skip URLs and anchors. */
+function linkedPaths(md: string): string[] {
+  const out: string[] = [];
+  for (const m of md.matchAll(/\]\(([^)\s]+)\)/g)) {
+    const t = m[1];
+    if (/^(https?:|mailto:|#|\/\/)/.test(t)) continue;
+    out.push(t.split('#')[0]);
+  }
+  return out.filter(Boolean);
+}
+
+function hasCommandOutputShape(body: string): boolean {
+  return /`[^`]+`/.test(body) || /\b(exit\s+[01]|✓|✗|\bPASS\b|\bFAIL\b|passed|failed|\d+\s+(passed|failed))\b/i.test(body);
+}
+
+function collectPassCitedPaths(missionDir: string): string[] {
+  const out: string[] = [];
+  for (const f of trailFiles(missionDir)) {
+    let body: string;
+    try { body = readFileSync(f, 'utf8'); } catch { continue; }
+    for (const line of body.split(/\r?\n/)) {
+      if (!/\bPASS\b/.test(line)) continue;
+      for (const p of linkedPaths(line)) out.push(p);
+      // also catch bare repo-path mentions like flows/04-gates.md or evidence/foo.md
+      for (const m of line.matchAll(/(?:^|[\s"'(])([a-zA-Z0-9._\/-]+\.(?:md|txt|log|json))\b/g)) {
+        const cand = m[1];
+        if (cand.includes('/')) out.push(cand);
+      }
+    }
+  }
+  return [...new Set(out)];
+}
+
+export function checkTrail(missionDir: string, projectRoot: string): IntegrityIssue[] {
+  const issues: IntegrityIssue[] = [];
+  const files = trailFiles(missionDir);
+
+  // 1 + 2: per-file link resolution and secret scan
+  for (const f of files) {
+    let body: string;
+    try { body = readFileSync(f, 'utf8'); } catch { continue; }
+    for (const target of linkedPaths(body)) {
+      if (isAbsolute(target)) continue;
+      const fromMission = join(missionDir, target);
+      const fromRoot = join(projectRoot, target);
+      if (!existsSync(fromMission) && !existsSync(fromRoot)) {
+        issues.push({
+          kind: 'dangling-path',
+          detail: `${relative(projectRoot, f)} links "${target}" — no such file (mission dir or repo root)`,
+        });
+      }
+    }
+    for (const { label, hit } of findSecrets(body)) {
+      issues.push({
+        kind: 'secret',
+        detail: `${relative(projectRoot, f)} matches ${label}: ${hit.slice(0, 12)}…`,
+      });
+    }
+  }
+
+  // 3: evidence entries recorded as repo paths must exist
+  const evidencePaths: string[] = [];
+  const evidenceFile = join(missionDir, 'state.json');
+  if (existsSync(evidenceFile)) {
+    try {
+      const s = JSON.parse(readFileSync(evidenceFile, 'utf8')) as { evidence?: unknown };
+      if (Array.isArray(s.evidence)) {
+        for (const e of s.evidence) {
+          if (typeof e !== 'string' || !e.trim()) continue;
+          evidencePaths.push(e);
+          const cand = join(projectRoot, e);
+          if (!isAbsolute(e) && !existsSync(cand) && !existsSync(join(missionDir, e))) {
+            issues.push({ kind: 'evidence', detail: `state.json evidence "${e}" does not exist` });
+          }
+        }
+      }
+    } catch { /* corrupt state — the state reader owns that error */ }
+  }
+
+  // 4: evidence-content spot check (T7): a PASS verdict that cites an evidence
+  // path must point at a file that exists AND contains command-output shape
+  // (backticked command or exit-status token). Fake-but-consistent trails
+  // defeat existence-only checks — this raises the bar cheaply.
+  const passCited = collectPassCitedPaths(missionDir);
+  for (const e of passCited) {
+    if (!e.trim() || isAbsolute(e)) continue;
+    const candMission = join(missionDir, e);
+    const candRoot = join(projectRoot, e);
+    const resolved = existsSync(candMission) ? candMission : existsSync(candRoot) ? candRoot : null;
+    if (!resolved) continue; // already reported as evidence/dangling elsewhere
+    let body: string;
+    try { body = readFileSync(resolved, 'utf8'); } catch { continue; }
+    if (!hasCommandOutputShape(body)) {
+      issues.push({ kind: 'evidence-thin', detail: `evidence "${e}" exists but lacks command output (no backticked command or exit-status token)` });
+    }
+  }
+
+  return issues;
+}
+
+export function formatIssues(issues: IntegrityIssue[]): string {
+  return issues.map((i) => `  ✗ [${i.kind}] ${i.detail}`).join('\n');
+}

package/src/mission.ts

@@ -1,18 +1,55 @@
 // src/mission.ts
-// Mission-state helpers for the mugiwara CLI (installer + reset only).
-import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
+// Mission-state helpers for the mugiwara CLI.
+import { existsSync, rmSync, readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync, openSync, writeSync, closeSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
+import { checkTrail, formatIssues } from './integrity.ts';
+import { generateRollback } from './rollback.ts';
+import { writeProvenance } from './provenance.ts';
+import { rankFiles, renderRouting } from './routing.ts';
+import { formatFootprint, measureContextChars, readBudgetConfig } from './budget.ts';
+
+function isStateFile(f: string): boolean {
+  // state.json (solo) or <member>.json (team) — never continue*.json
+  const stem = f.replace(/\.json$/, '');
+  return f.endsWith('.json') && stem !== 'continue' && !stem.startsWith('continue-');
+}
+
+/** Primary state for closure artifacts: solo state.json wins over members. */
+function primaryState(dir: string, files: string[]): Record<string, unknown> | null {
+  const name = files.includes('state.json') ? 'state.json' : files.find((f) => f.endsWith('.json') && f !== 'continue.json' && !f.startsWith('continue-'));
+  if (!name) return null;
+  try {
+    return JSON.parse(readFileSync(join(dir, name), 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Files the mission changed, base..branch. Empty on any git failure — routing is best-effort. */
+function changedFiles(projectDir: string, state: Record<string, unknown> | null): string[] {
+  const base = typeof state?.base_sha === 'string' ? state.base_sha : '';
+  const branch = typeof state?.branch === 'string' ? state.branch : '';
+  if (!base || base === 'unknown' || !branch) return [];
+  try {
+    return execFileSync('git', ['diff', '--name-only', base, branch], {
+      cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).split(/\r?\n/).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 function activeActor(projectDir: string): string | null {
-  // state now lives at .mugiwara/state/<mission>/[member].json — scan the
+  // state now lives at .mugiwara/missions/<mission>/[member].json — scan the
   // latest state file for its actor
-  const stateDir = join(projectDir, '.mugiwara', 'state');
-  if (!existsSync(stateDir)) return null;
-  const missions = readdirSync(stateDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+  const missionsDir = join(projectDir, '.mugiwara', 'missions');
+  if (!existsSync(missionsDir)) return null;
+  const missions = readdirSync(missionsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
   let latest: { actor: string; updated: number } | null = null;
   for (const mission of missions) {
-    const d = join(stateDir, mission);
-    for (const f of readdirSync(d).filter(f => f.endsWith('.json'))) {
+    const d = join(missionsDir, mission);
+    for (const f of readdirSync(d).filter(isStateFile)) {
       try {
         const s = JSON.parse(readFileSync(join(d, f), 'utf8'));
         const t = Date.parse(s.updated_at || '') || 0;
@@ -37,12 +74,9 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
 
   const removed: string[] = [];
   const kept: string[] = [];
-  for (const dir of ['spec', 'plans', 'results', 'review', 'issues', 'reports']) {
-    const p = join(root, dir);
-    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
-  }
-  // mission state + continue folders — state/<mission>/, continue/<mission>/
-  for (const dir of ['state', 'continue']) {
+  // current layout: everything lives in missions/. Legacy pre-0.7 dirs are
+  // removed too so an upgraded project ends up with one layout, not two.
+  for (const dir of ['missions', 'spec', 'plans', 'results', 'review', 'issues', 'reports', 'state', 'continue']) {
     const p = join(root, dir);
     if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(dir); }
   }
@@ -53,11 +87,14 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
       if (existsSync(p)) { rmSync(p); removed.push(f); }
     }
   }
+  // lessons.md moved to the .mugiwara root; legacy home was logs/
   if (!keepLogs) {
-    const p = join(root, 'logs');
-    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push('logs'); }
-  } else if (existsSync(join(root, 'logs'))) {
-    kept.push('logs');
+    for (const p of [join(root, 'lessons.md'), join(root, 'logs')]) {
+      if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(p.startsWith(join(root, 'logs')) ? 'logs' : 'lessons.md'); }
+    }
+  } else {
+    if (existsSync(join(root, 'lessons.md'))) kept.push('lessons.md');
+    else if (existsSync(join(root, join('logs', 'lessons.md')))) kept.push(join('logs', 'lessons.md'));
   }
   for (const f of ['config', 'manifest.json', 'backup']) {
     if (existsSync(join(root, f))) kept.push(f);
@@ -68,108 +105,204 @@ export function resetMission(projectDir: string, keepLogs: boolean, force?: bool
 export function archiveMission(projectDir: string, mission: string, opts: { dryRun?: boolean } = {}): { report: string | null; removed: string[]; kept: string[]; index?: string } {
   const { dryRun = false } = opts;
   const root = join(projectDir, '.mugiwara');
-  // mission allowlist — same as savepoint.sh / mission-report.sh. Dot-only
+  // mission allowlist — same as savepoint.sh. Dot-only
   // names (".", "..") would resolve upward through join(...,"..") and let
   // rmSync reach state.json/config outside the mission dir.
   if (!mission || /[^a-zA-Z0-9._-]/.test(mission) || /^\.+$/.test(mission)) throw new Error(`invalid mission name "${mission}" (allowlist: [a-zA-Z0-9._-], not a dot-path)`);
   const removed: string[] = [];
   const kept: string[] = [];
 
-  // A file belongs to this mission when stripping the optional YYYY-MM-DD-
-  // prefix leaves `<mission>.md` or `<mission>-<suffix>.md`. Covers both the
-  // bare names and the date-prefixed names the prose writes (audit-trail.md).
-  const belongs = (f: string): boolean => {
-    const base = f.replace(/^\d{4}-\d{2}-\d{2}-/, '');
-    return base === `${mission}.md` || base.startsWith(`${mission}-`);
-  };
-
-  // locate the report (the archive target that must survive). Reports are
-  // date-prefixed (`reports/YYYY-MM-DD-<mission>.md`); compare the stripped
-  // mission name so `bar-foo.md` is not mistaken for mission `foo`.
-  let report: string | null = null;
-  const reportsDir = join(root, 'reports');
-  if (existsSync(reportsDir)) {
-    const f = readdirSync(reportsDir).find(n => {
-      const m = n.match(/^(\d{4}-\d{2}-\d{2})-(.+)\.md$/);
-      return !!m && m[2] === mission;
-    });
-    if (f) report = join('reports', f);
-  }
+  const dir = join(root, 'missions', mission);
+  if (!existsSync(dir)) return { report: null, removed, kept };
 
-  // step results 01..05 + todos.md are evidence — kept; archive removes
-  // step results 01..05 + todos.md are evidence — kept; archive removes
-  // only spec/review/issues/logs + continue/<mission>/ + state/<mission>/
-  const resultsDir = join(root, 'results', mission);
-  if (existsSync(resultsDir)) {
-    for (const f of readdirSync(resultsDir)) {
-      kept.push(join('results', mission, f));
+  // Closure integrity gate: the trail validates itself before it
+  // folds. Dangling links, secrets, or missing evidence fail the archive.
+  if (!dryRun) {
+    const issues = checkTrail(dir, projectDir);
+    if (issues.length) {
+      throw new Error(`closure integrity gate failed — fix these before archiving:\n${formatIssues(issues)}`);
     }
   }
 
-  // spec, review, issues, per-mission decision log — bare + date-prefixed
-  const specDir = join(root, 'spec');
-  if (existsSync(specDir)) {
-    for (const f of readdirSync(specDir)) {
-      if (!belongs(f)) continue;
-      const p = join(specDir, f);
-      if (!dryRun) rmSync(p);
-      removed.push(join('spec', f));
-    }
-  }
+  const files = readdirSync(dir);
+  const state = primaryState(dir, files);
+  // unique models across every stage's state file (A4) — collected HERE,
+  // before the fold deletes the .json files; team members and solo
+  // re-savepoints each record the model that ran their stage.
+  const stageModels = [...new Set(files.filter(isStateFile).map((f) => {
+    try {
+      const s = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+      return typeof s.model === 'string' ? s.model : '';
+    } catch { return ''; }
+  }).filter(Boolean))];
 
-  for (const dir of ['review', 'issues']) {
-    const d = join(root, dir);
-    if (!existsSync(d)) continue;
-    for (const f of readdirSync(d)) {
-      if (!belongs(f)) continue;
-      const p = join(d, f);
-      if (!dryRun) rmSync(p, { force: true });
-      removed.push(join(dir, f));
+  // Cost surface — always readable section for the report (T8)
+  let costSection = '';
+  if (!dryRun && state) {
+    const chars = measureContextChars(dir);
+    const budget = readBudgetConfig(projectDir);
+    const footprintLine = formatFootprint(chars, budget);
+    if (budget && chars > budget) {
+      throw new Error(`closure context budget failed — ${footprintLine}. Trim the trail or raise context_budget_chars.`);
     }
-  }
-
-  const logsDir = join(root, 'logs');
-  if (existsSync(logsDir)) {
-    for (const f of readdirSync(logsDir)) {
-      if (!belongs(f)) continue;
-      const p = join(logsDir, f);
-      if (!dryRun) rmSync(p);
-      removed.push(join('logs', f));
+    const est = typeof state.tokens_est === 'number' ? state.tokens_est : 0;
+    const src = typeof state.tokens_source === 'string' ? state.tokens_source : 'computed';
+    const lane = typeof state.lane === 'string' ? state.lane : 'unknown';
+    // lane budgets for readable delta (from lane-base.sh, mirrored here for display only)
+    const laneBudget = lane === 'lean' ? 12000 : lane === 'standard' ? 25000 : lane === 'full' ? 50000 : lane === 'spike' ? 3000 : 0;
+    const effBudget = budget || laneBudget;
+    const pct = effBudget ? Math.round((est / effBudget) * 100) : 0;
+    const delta = effBudget ? (est <= effBudget ? `${(effBudget - est).toLocaleString()} under` : `${(est - effBudget).toLocaleString()} over`) : 'no budget configured';
+    const srcLabel = src === 'reported' ? 'provider-reported' : 'estimator';
+    // provider-reported rollup when any stage reported
+    let reportedTotal = 0;
+    let hasReported = false;
+    for (const f of files.filter(isStateFile)) {
+      try {
+        const s = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+        if (s.tokens_source === 'reported' && typeof s.tokens_est === 'number') {
+          reportedTotal += s.tokens_est;
+          hasReported = true;
+        }
+      } catch { /* corrupt — skip */ }
+    }
+    if (!hasReported && src === 'reported' && est > 0) {
+      reportedTotal = est;
+      hasReported = true;
     }
+    costSection = [
+      '## Cost',
+      '',
+      '| Metric | Value |',
+      '|--------|-------|',
+      `| **Tokens used** | ${est.toLocaleString()} (${srcLabel}) |`,
+      `| **Lane** | ${lane} (budget ${effBudget ? effBudget.toLocaleString() : '—'} · warn ${effBudget ? Math.round(effBudget * 1.5).toLocaleString() : '—'} · stop ${effBudget ? (effBudget * 3).toLocaleString() : '—'}) |`,
+      `| **Budget status** | ${effBudget ? `${pct}% of budget · ${delta} · ${est >= effBudget * 3 ? 'STOP' : est >= effBudget * 1.5 ? 'WARN' : 'OK'}` : 'no lane budget'} |`,
+      `| **Context footprint** | ${chars.toLocaleString()} chars${budget ? ` (budget ${budget.toLocaleString()})` : ' (no context budget configured)'} |`,
+    ].join('\n');
+    if (hasReported) {
+      costSection += `\n| **Provider total** | ${reportedTotal.toLocaleString()} (provider-reported — sum of reported stages) |`;
+    }
+    costSection += '\n';
   }
 
-  // continue/<mission>/ is a session handoff — remove this mission's folder
-  const contDir = join(root, 'continue', mission);
-  if (existsSync(contDir)) {
-    if (!dryRun) rmSync(contDir, { recursive: true, force: true });
-    removed.push(join('continue', mission));
+  // Fold order: narrative artifacts first, wave evidence last (chronological).
+  const FOLD_TOP = ['decisions.md', 'blockers.md', 'review.md', 'security.md', 'spec.md'];
+  const fold: string[] = [];
+  for (const f of FOLD_TOP) {
+    if (files.includes(f)) fold.push(f);
   }
-  // state/<mission>/ — remove this mission's computed state (archived)
-  const stateDir = join(root, 'state', mission);
-  if (existsSync(stateDir)) {
-    if (!dryRun) rmSync(stateDir, { recursive: true, force: true });
-    removed.push(join('state', mission));
+  // Flow artifacts: flows/ is the current layout; a legacy mission that still
+  // keeps waves/ folds from there so an upgrade never strands a trail.
+  const flowsDir = join(dir, 'flows');
+  const legacyWavesDir = join(dir, 'waves');
+  const artDir = existsSync(flowsDir) ? flowsDir : existsSync(legacyWavesDir) ? legacyWavesDir : flowsDir;
+  const artRel = artDir === legacyWavesDir ? 'waves' : 'flows';
+  if (existsSync(artDir)) {
+    for (const f of readdirSync(artDir).sort()) fold.push(join(artRel, f));
   }
 
-  // kept: report + the audit-trail survivors
-  if (report) kept.push(report);
-  for (const k of ['plans', 'config', join('logs', 'lessons.md')]) {
-    if (existsSync(join(root, k))) kept.push(k);
+  // The report survives: an existing report.md wins; otherwise the closure
+  // wave seeds it; otherwise it starts empty.
+  let report = '';
+  const reportPath = join(dir, 'report.md');
+  if (files.includes('report.md')) report = readFileSync(reportPath, 'utf8');
+  else if (existsSync(join(artDir, '06-closure.md'))) report = readFileSync(join(artDir, '06-closure.md'), 'utf8');
+
+  if (!dryRun) {
+    mkdirSync(dir, { recursive: true });
+    if (fold.length) {
+      const sections = fold.map((f) => {
+        const body = readFileSync(join(dir, f), 'utf8').trim();
+        const name = f.includes('/') ? (f.split('/').pop() ?? f) : f;
+        return `\n\n## Archived: ${name}\n\n${body}`;
+      }).join('');
+      // atomic: write the folded report to a temp file, then rename over the
+      // target. A crash mid-write must never leave a truncated report — the
+      // fold deletes the wave files right after, so a partial write loses them.
+      const tmp = `${reportPath}.tmp`;
+      const routingSection = state
+        ? renderRouting(rankFiles(changedFiles(projectDir, state), {
+            mission,
+            evidence: Array.isArray(state.evidence) ? (state.evidence as string[]) : [],
+            sensitive_paths: Array.isArray(state.sensitive_paths) ? (state.sensitive_paths as string[]) : [],
+          } as never), mission)
+        : '';
+      writeFileSync(tmp, report.trimEnd() + sections + (routingSection || '') + (costSection ? `\n${costSection}\n` : '') + '\n');
+      renameSync(tmp, reportPath);
+    }
+    for (const f of fold) {
+      rmSync(join(dir, f), { force: true, recursive: true });
+      removed.push(join('missions', mission, f));
+    }
+    // session state dies with the mission
+    for (const f of files.filter((f) => f.endsWith('.json'))) rmSync(join(dir, f), { force: true });
+    // flows/ may now be empty — remove the folder
+    if (existsSync(artDir) && readdirSync(artDir).length === 0) rmSync(artDir, { recursive: true, force: true });
+    // report.md must exist after archive — the closed marker `mugiwara clean`
+    // filters on. A stale in-flight mission folds nothing, so seed a stub.
+    if (!existsSync(reportPath)) {
+      writeFileSync(reportPath, `# Mission: ${mission}\n\nArchived before closure — no wave artifacts were present.\n`);
+    }
+    // Closure artifacts: executable rollback map and the
+    // two-layer provenance record. Best-effort — absent git/base degrades.
+    if (state && typeof state.branch === 'string') {
+      const rb = generateRollback(projectDir, dir, {
+        mission,
+        branch: state.branch,
+        baseSha: typeof state.base_sha === 'string' ? state.base_sha : 'unknown',
+      });
+      if (rb) kept.push(join('missions', mission, rb.file));
+      try {
+        writeProvenance(projectDir, dir, {
+          mission,
+          actor: typeof state.actor === 'string' ? state.actor : '',
+          lane: typeof state.lane === 'string' ? state.lane : '',
+          mode: typeof state.mode === 'string' ? state.mode : '',
+          branch: state.branch,
+          tasks_done: Number(state.tasks_done) || 0,
+          tasks_total: Number(state.tasks_total) || 0,
+          evidence: Array.isArray(state.evidence) ? (state.evidence as string[]) : [],
+          models: stageModels,
+        });
+        kept.push(join('missions', mission, 'provenance.md'));
+      } catch { /* provenance is additive; archive proceeds */ }
+    }
+  } else {
+    for (const f of fold) removed.push(join('missions', mission, f));
   }
+  removed.push(join('missions', mission, '<session state>'));
+  if (files.includes('plan.md')) kept.push(join('missions', mission, 'plan.md'));
+  if (files.includes('handoff.md')) kept.push(join('missions', mission, 'handoff.md'));
+  kept.push(join('missions', mission, 'report.md'));
 
-  // summary index: append one line per archived mission (retention aid),
-  // idempotently — never duplicate a line for an already-indexed mission.
+  // summary index: append one line per archived mission (retention aid).
+  // Atomic-append contract (finding A3): the line is written as ONE write()
+  // on an O_APPEND fd — POSIX positions O_APPEND writes atomically, so
+  // concurrent archivers never overwrite each other's bytes, and a small
+  // (<4k) single write does not interleave in practice. The pre-read
+  // idempotency check below still has a benign race window under true
+  // concurrency: two racers may both see the line missing and both append.
+  // That is a duplicate line, not a lost one — duplicates are the preferred
+  // failure mode; any future consumer of index.md must dedupe lines on read.
+  // Header creation stays racy-but-safe: two first-appends may each prepend
+  // "# Mission index\n\n", and header-only-plus-lines remains valid markdown
+  // either way.
   let index: string | undefined;
-  const indexFile = join(root, 'reports', 'index.md');
-  const line = `- ${mission} — ${new Date().toISOString().slice(0, 10)}${report ? ` → ${report}` : ''}\n`;
+  const indexFile = join(root, 'index.md');
+  const line = `- ${mission} — ${new Date().toISOString().slice(0, 10)}\n`;
   if (!dryRun) {
-    mkdirSync(join(root, 'reports'), { recursive: true });
     const existing = existsSync(indexFile) ? readFileSync(indexFile, 'utf8') : '';
     if (!existing.split(/\r?\n/).some(l => l.startsWith(`- ${mission} —`))) {
       const header = existing ? '' : '# Mission index\n\n';
-      appendFileSync(indexFile, header + line);
+      const fd = openSync(indexFile, 'a');
+      try {
+        writeSync(fd, header + line);
+      } finally {
+        closeSync(fd);
+      }
     }
-    index = join('reports', 'index.md');
+    index = 'index.md';
   }
-  return { report, removed, kept, index };
+  return { report: join('missions', mission, 'report.md'), removed, kept, index };
 }