@ionivetech/mugiwara 0.6.5 → 0.7.0

package/scripts/verify-install.ts

@@ -1,61 +1,72 @@
 #!/usr/bin/env bun
-// scripts/verify-install.ts — G1: verify all references/*.md pointers resolve after install.
-// Installs to temp dir for one target per tier, then checks every pointer.
+// scripts/verify-install.ts — G1: prove the shipped prose does not lie.
+//
+// Three checks, all of which failed silently before:
+//   A. pointer resolution  — every `references/*.md` pointer resolves after install
+//   B. prose path validity — every `.mugiwara/…`, `scripts/…`, `docs/…` path a
+//      skill or agent NAMES either exists in the repo or matches a declared
+//      runtime shape. Four BLOCKER/MAJOR findings shared one root cause:
+//      nothing verified that a path named in prose actually exists.
+//   C. reference reachability — every reference file has an inbound pointer.
+//      Unreachable files still install into every project.
 
 import { existsSync, mkdtempSync, rmSync, readFileSync, readdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename, relative } from 'node:path';
 import { tmpdir } from 'node:os';
 import { installTo } from '../src/installer.ts';
-import { targets } from '../src/targets/index.ts';
+import { targets, TARGET_IDS } from '../src/targets/index.ts';
 
-const tierTargets = [
-  { id: 'claude', tier: 1 },
-  { id: 'codex', tier: 2 },
-  { id: 'kilo', tier: 3 },
-];
+const repoRoot = join(import.meta.dirname, '..');
+const fail: string[] = [];
+
+function findMd(root: string, out: string[] = []): string[] {
+  if (!existsSync(root)) return out;
+  for (const ent of readdirSync(root, { withFileTypes: true })) {
+    const p = join(root, ent.name);
+    if (ent.isDirectory()) findMd(p, out);
+    else if (ent.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
 
-let total = 0;
-let broken = 0;
+// ---------------------------------------------------------------------------
+// A. pointer resolution, across EVERY install target (was 3 of 9)
+// ---------------------------------------------------------------------------
+let pointers = 0;
+let brokenPointers = 0;
 
-for (const tt of tierTargets) {
-  const target = targets[tt.id];
-  if (!target) { console.log(`⚠  target ${tt.id} not found, skipping`); continue; }
-  const dir = mkdtempSync(join(tmpdir(), `mugi-verify-${tt.id}-`));
+for (const id of TARGET_IDS) {
+  const target = targets[id];
+  const dir = mkdtempSync(join(tmpdir(), `mugi-verify-${id}-`));
   try {
     installTo(target, { scope: 'project', projectDir: dir, dryRun: false, force: true });
 
     const skillsDir = target.paths({ scope: 'project', projectDir: dir, home: '' }).skillsDir;
     const mugiwaraRefsDir = join(dir, '.mugiwara', 'refs');
 
-    function findSkillFiles(root: string): string[] {
-      const out: string[] = [];
-      if (!existsSync(root)) return out;
-      for (const ent of readdirSync(root, { withFileTypes: true })) {
-        const p = join(root, ent.name);
-        if (ent.isDirectory()) out.push(...findSkillFiles(p));
-        else if (ent.name.endsWith('.md')) out.push(p);
-      }
-      return out;
-    }
-
-    const skillFiles = findSkillFiles(skillsDir)
-      .filter(f => !f.replace(skillsDir, '').includes('/references/'));
+    const skillFiles = findMd(skillsDir).filter((f) => !f.replace(skillsDir, '').includes('/references/'));
 
     for (const file of skillFiles) {
-      const body = readFileSync(file, 'utf8');
-      const refs = [...body.matchAll(/`([^`]*references\/[^`]+\.md)`/g)];
+      // Targets emit skills either as `<skillsDir>/<name>/SKILL.md` (claude) or
+      // as a flat `<skillsDir>/<name>.instructions.md` (copilot). Both forms
+      // must yield the skill name, because non-native targets store references
+      // per-skill under `.mugiwara/refs/<name>/`.
+      const relSkill = relative(skillsDir, file);
+      const skillName = relSkill.includes('/') ? relSkill.split('/')[0] : basename(relSkill).split('.')[0];
 
-      for (const m of refs) {
-        total++;
+      for (const m of readFileSync(file, 'utf8').matchAll(/`([^`]*references\/[^`]+\.md)`/g)) {
+        pointers++;
         const pointer = m[1];
-        const localResolve = join(dirname(file), pointer);
-        const mugiwaraResolve = join(mugiwaraRefsDir, pointer.replace(/^(?:_shared\/)?references\//, ''));
-        const resolved = [localResolve, mugiwaraResolve].find(p => existsSync(p));
-
-        if (!resolved) {
-          broken++;
-          const relFile = file.replace(dir + '/', '');
-          console.log(`✗ ${relFile}: \`${pointer}\` → not found`);
+        const candidates = [
+          join(dirname(file), pointer),
+          join(mugiwaraRefsDir, pointer.replace(/^(?:_shared\/)?references\//, '')),
+          ...(target.refsDir
+            ? [join(target.refsDir({ scope: 'project', projectDir: dir, home: '' }, skillName), basename(pointer))]
+            : []),
+        ];
+        if (!candidates.some((p) => existsSync(p))) {
+          brokenPointers++;
+          fail.push(`✗ [${id}] ${file.replace(dir + '/', '')}: \`${pointer}\` → not found`);
         }
       }
     }
@@ -64,9 +75,110 @@ for (const tt of tierTargets) {
   }
 }
 
-if (broken > 0) {
-  console.log(`\n✗ ${broken}/${total} pointers cannot resolve after install`);
-  process.exit(1);
+// ---------------------------------------------------------------------------
+// B. prose path validity
+// ---------------------------------------------------------------------------
+// `.mugiwara/**` paths are written at RUNTIME — they never exist in a clone
+// (`.mugiwara/` is gitignored), so existence proves nothing. What can be
+// verified is the SHAPE: prose must name the same filename template the
+// scripts actually write. This is the check that would have caught
+// savepoint.sh globbing `issues/<mission>-blockers.md` while 15 prose sites
+// mandated the dated `issues/YYYY-MM-DD-<mission>-blockers.md`.
+const RUNTIME_SHAPES: RegExp[] = [
+  /^\.mugiwara\/?(\*\*)?$/,                                       // bare mention of the dir
+  /^~?\/?\.mugiwara\/config$/,                                    // project + global config
+  /^\.mugiwara\/lessons\.md$/,
+  /^\.mugiwara\/index\.md$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/(plan|spec|decisions|blockers|review|security|report)\.md$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/flows\/([0-9]{2}-[a-z-]+|eval|resume|todos)\.md$/,
+  /^\.mugiwara\/missions\/<mission>\/flows\/?$/,
+  /^\.mugiwara\/missions\/(<mission>|[a-z0-9._-]+)\/waves\/([0-9]{2}-[a-z-]+|eval|resume|todos)\.md$/, // legacy layout, still read
+  /^\.mugiwara\/missions\/<mission>\/waves\/?$/, // legacy layout, still read
+  /^\.mugiwara\/missions\/<mission>\/(state\.json|<member>\.json)$/,
+  /^\.mugiwara\/missions\/<mission>\/(continue\.json|continue-<member>\.json)$/,
+];
+
+// Shape violations that exist today and are NOT fixed in this mission because
+// another worker holds `content/**` prose this wave. Ratchet: a NEW violation
+// fails the gate; these two are reported, then must be deleted from this list.
+// Prose paths whose SHAPE is known-wrong but not yet fixed. Reported every run
+// so they cannot rot quietly; emptied as each is repaired. Keep this empty —
+// an entry here is a defect with a due date, never a permanent exemption.
+const KNOWN_SHAPE_DRIFT = new Map<string, string>([]);
+
+/** `[label](path)`, `bun scripts/x.ts --flag`, trailing punctuation → the bare path. */
+function normalizePath(raw: string): string {
+  let s = raw.trim();
+  const link = s.match(/^\[[^\]]*\]\(([^)]+)\)$/);
+  if (link) s = link[1];
+  s = s.replace(/^(?:bun|bash|sh|npx|node)\s+/, '');
+  s = s.split(/\s/)[0];
+  return s.replace(/[.,;:]$/, '');
+}
+
+const PROSE_PATH = /`([^`\n]*?(?:\.mugiwara\/|scripts\/|docs\/)[^`\n]*?)`/g;
+const proseFiles = [...findMd(join(repoRoot, 'content')), ...findMd(join(repoRoot, 'references'))];
+
+let prosePaths = 0;
+const drift: string[] = [];
+for (const file of proseFiles) {
+  const rel = relative(repoRoot, file);
+  readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
+    for (const m of line.matchAll(PROSE_PATH)) {
+      const p = normalizePath(m[1]);
+      if (!p.includes('/')) continue;
+      prosePaths++;
+      const at = `${rel}:${i + 1}`;
+
+      if (/(^|\/)\.mugiwara\//.test(p) || p === '.mugiwara/' || p === '.mugiwara/**') {
+        if (RUNTIME_SHAPES.some((re) => re.test(p))) continue;
+        if (KNOWN_SHAPE_DRIFT.has(p)) { drift.push(`  ${at}: \`${p}\` — ${KNOWN_SHAPE_DRIFT.get(p)}`); continue; }
+        fail.push(`✗ ${at}: \`${p}\` → not a declared runtime path shape`);
+        continue;
+      }
+      // scripts/ and docs/ are SHIPPED files — they must exist in the repo
+      if (!existsSync(join(repoRoot, p))) fail.push(`✗ ${at}: \`${p}\` → file does not exist`);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// C. reference reachability (file → pointer, the inverse of check A)
+// ---------------------------------------------------------------------------
+// Hard zero. The 18 orphans this ratchet was holding were all substantive —
+// worksheets, rubrics and worked examples their own skill visibly needed — so
+// every one was wired to its parent section rather than deleted. With the
+// backlog at zero the ratchet becomes what it should always have been: a new
+// reference file must be pointed at by the prose that needs it, or it is not
+// a reference, it is dead weight shipped to every project.
+const ORPHAN_BASELINE = 0;
+
+const corpus = proseFiles.map((f) => ({ file: f, body: readFileSync(f, 'utf8') }));
+const refFiles = proseFiles.filter((f) => f.includes('/references/') || relative(repoRoot, f).startsWith('references/'));
+const orphans: string[] = [];
+for (const rf of refFiles) {
+  const needle = `references/${basename(rf)}`;
+  const reachable = corpus.some((c) => c.file !== rf && c.body.includes(needle));
+  if (!reachable) orphans.push(relative(repoRoot, rf));
+}
+if (orphans.length > ORPHAN_BASELINE) {
+  fail.push(
+    `✗ ${orphans.length} unreachable reference files (baseline ${ORPHAN_BASELINE}) — a new orphan was added:\n` +
+      orphans.map((o) => `    ${o}`).join('\n'),
+  );
 }
 
-console.log(`✓ ${total} pointers checked across ${tierTargets.length} targets — all resolve`);
+// ---------------------------------------------------------------------------
+console.log(`  ${pointers} pointers checked across ${TARGET_IDS.length} targets`);
+console.log(`  ${prosePaths} prose paths checked in ${proseFiles.length} files`);
+console.log(`  ${orphans.length}/${refFiles.length} reference files unreachable (baseline ${ORPHAN_BASELINE})`);
+if (orphans.length) orphans.forEach((o) => console.log(`    orphan: ${o}`));
+if (drift.length) { console.log('  known prose-path drift (owned elsewhere, must be fixed):'); drift.forEach((d) => console.log(d)); }
+
+if (fail.length) {
+  console.log('');
+  fail.forEach((f) => console.log(f));
+  console.log(`\n✗ verify-install: ${fail.length} problem(s) (${brokenPointers} broken pointers)`);
+  process.exit(1);
+}
+console.log('✓ verify-install: pointers resolve, prose paths valid, no new orphans');

package/src/args.ts

@@ -6,10 +6,10 @@ export type Args = {
   flags: Record<string, FlagValue>;
 };
 
-const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target' };
+const VALUE_FLAGS: Record<string, string> = { '--project': 'project', '--target': 'target', '--before': 'before' };
 const BOOL_FLAGS: Record<string, string> = {
   '--global': 'global', '--yes': 'yes', '-y': 'yes', '--force': 'force',
-  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs', '--check': 'check',
+  '--dry-run': 'dryRun', '--keep-logs': 'keepLogs', '--check': 'check', '--all': 'all', '--verify': 'verify',
   '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version',
 };
 

package/src/budget.ts

@@ -0,0 +1,56 @@
+// src/budget.ts
+// Context budget as a gate: a mission's trail is itself
+// context the next reader must load. At archive time, measure the total
+// footprint of the artifacts that survive and compare against the configured
+// ceiling — a bloated trail is caught like a failed test, with a visible
+// number in the report.
+//
+// Token telemetry stays honest elsewhere: the estimator remains the default;
+// `tokens_source: reported` activates only where the harness exposes real
+// usage (see docs/concepts/cost.md). This module does not estimate tokens.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function readBudgetConfig(projectDir: string): number {
+  for (const base of [projectDir, homedir()]) {
+    const file = join(base, '.mugiwara', 'config');
+    if (!existsSync(file)) continue;
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t || t.startsWith('#')) continue;
+      const eq = t.indexOf('=');
+      if (eq === -1) continue;
+      if (t.slice(0, eq).trim() !== 'context_budget_chars') continue;
+      const n = Number(t.slice(eq + 1).trim());
+      return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+  }
+  return 0; // unset — measurement still recorded, never enforced
+}
+
+/** Sum of bytes across the trail: top-level *.md + flows/* (legacy waves/* counts too). */
+export function measureContextChars(missionDir: string): number {
+  let total = 0;
+  const add = (p: string): void => {
+    try { total += statSync(p).size; } catch { /* vanished mid-measure */ }
+  };
+  for (const f of readdirSync(missionDir)) {
+    if (/\.md$/.test(f)) add(join(missionDir, f));
+  }
+  for (const sub of ['flows', 'waves']) {
+    const dir = join(missionDir, sub);
+    if (existsSync(dir)) {
+      for (const f of readdirSync(dir)) add(join(dir, f));
+    }
+  }
+  return total;
+}
+
+export function formatFootprint(chars: number, budget: number): string {
+  const base = `Context footprint: ${chars} chars`;
+  if (!budget) return `${base} (no budget configured)`;
+  return chars > budget
+    ? `${base} — OVER budget ${budget}`
+    : `${base} (budget ${budget})`;
+}

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,6 +11,10 @@ import { targets, TARGET_IDS } from './targets/index.ts';
 import { installTo, removeInstalled, VERSION, ensureProjectGitignore, removeProjectGitignore } from './installer.ts';
 import { manifestPath, readManifest, writeManifest, type Scope } from './manifest.ts';
 import { resetMission, archiveMission } from './mission.ts';
+import { runScript, RUNNABLE } from './run.ts';
+import { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor } from './continue.ts';
+import { blamePath } from './provenance.ts';
+import { signReport, verifyReport } from './sign.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
@@ -25,6 +30,14 @@ export async function run(argv: string[]): Promise<void> {
     case 'list': return list(flags);
     case 'reset': return resetCmd(flags);
     case 'archive': return archive(flags, _);
+    case 'clean': return cleanCmd(flags);
+    case 'continue': return continueCmd(flags, _);
+    case 'status': return statusCmd(flags);
+    case 'run': return runCmd(flags, _);
+    case 'savepoint': return runCmd(flags, ['run', 'savepoint.sh', ..._.slice(1)]);
+    case 'blame': return blameCmd(flags, _);
+    case 'handoff': return handoffCmd(flags, _);
+    case 'sign': return signCmd(flags, _);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
@@ -48,11 +61,74 @@ function archive(flags: Args['flags'], positionals: string[]): void {
   if (!mission) { console.error('usage: mugiwara archive <mission> [--project <dir>] [--dry-run]'); process.exit(1); }
   const result = archiveMission(projectDir, mission, { dryRun: flag(flags.dryRun) });
   if (result.report) console.log(`archive target: ${result.report}`);
+  else console.error(`no mission dir for "${mission}" under .mugiwara/missions/`);
   if (result.removed.length) console.log(`${flag(flags.dryRun) ? 'would remove' : 'removed'}: ${result.removed.join(', ')}`);
   if (result.kept.length) console.log(`kept: ${result.kept.join(', ')}`);
   if (result.index) console.log(`index updated: ${result.index}`);
 }
 
+/**
+ * `mugiwara clean` — batch-archive every closed mission. A mission is closed
+ * when its dir holds a report.md and no live state.json/<member>.json. With
+ * --all, missions with live state are included too (--force overrides the
+ * safety stop). --before <date> restricts to missions whose state was last
+ * touched before that date.
+ */
+function cleanCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const dryRun = flag(flags.dryRun);
+  const root = join(projectDir, '.mugiwara', 'missions');
+  if (!existsSync(root)) { console.log('nothing to clean (.mugiwara/missions/ does not exist).'); return; }
+  const before = str(flags.before);
+  const beforeMs = before ? Date.parse(before) : NaN;
+  if (before && !Number.isFinite(beforeMs)) { console.error(`invalid --before date: ${before}`); process.exit(1); }
+
+  let candidates = readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && /^[A-Za-z0-9._-]+$/.test(e.name) && !/^\.+$/.test(e.name))
+    .map((e) => e.name);
+  // default: CLOSED missions only — a report.md present and no live session
+  // state. --all widens to every mission dir, including in-flight ones.
+  // --before additionally treats an in-flight mission as closable when its
+  // newest state was last touched before the date: untouched work is safe to
+  // fold even without a report.md yet.
+  const stateFiles = (m: string): string[] =>
+    readdirSync(join(root, m)).filter((f) => {
+      const stem = f.replace(/\.json$/, '');
+      return f.endsWith('.json') && stem !== 'continue' && !stem.startsWith('continue-');
+    });
+  const hasLiveState = (m: string): boolean => stateFiles(m).length > 0;
+  const staleBefore = (m: string): boolean => {
+    if (!Number.isFinite(beforeMs)) return false;
+    for (const f of stateFiles(m)) {
+      try {
+        const ts = Date.parse(JSON.parse(readFileSync(join(root, m, f), 'utf8')).updated_at ?? '') || 0;
+        if (ts === 0 || ts >= beforeMs) return false; // unknown freshness → never assume stale
+      } catch { return false; }
+    }
+    return true;
+  };
+  if (!flag(flags.all)) {
+    candidates = candidates.filter((m) =>
+      (existsSync(join(root, m, 'report.md')) && !hasLiveState(m))
+      || staleBefore(m),
+    );
+  } else if (!flag(flags.force)) {
+    const live = candidates.filter((m) => hasLiveState(m) && !staleBefore(m));
+    if (live.length) {
+      console.error(`✗ in-flight mission(s): ${live.join(', ')}. Use --force to archive them anyway.`);
+      process.exit(1);
+    }
+  }
+  if (!candidates.length) { console.log('nothing to clean.'); return; }
+  for (const m of candidates) {
+    const r = archiveMission(projectDir, m, { dryRun });
+    console.log(`${dryRun ? 'would clean' : 'cleaned'} ${m}${r.report ? ` → ${r.report}` : ''}`);
+    if (r.index) console.log(`index updated: ${r.index}`);
+  }
+}
+
+
+
 async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; projectDir: string; targetIds: string[] }> {
   const interactive = !flag(flags.yes);
   if (interactive && !process.stdin.isTTY) {
@@ -123,6 +199,8 @@ async function install(flags: Args['flags']): Promise<void> {
   });
   console.log(`\nOK mugiwara ${VERSION} installed (manifest: ${file})`);
   if (allNotes.length) console.log(`${allNotes.length} note(s) above may need attention.`);
+  // A fresh install writes a default .mugiwara/config — point at it directly.
+  console.log('\nNext: edit .mugiwara/config to customise (mode, branch, coverage, depths).');
 }
 
 async function uninstall(flags: Args['flags']): Promise<void> {
@@ -150,6 +228,16 @@ async function uninstall(flags: Args['flags']): Promise<void> {
     if (!ok) { console.log('Aborted.'); return; }
   }
   const removed = removeInstalled(manifest, { dryRun: flag(flags.dryRun) });
+  // Un-merge anything we injected into files the user owns. These are
+  // deliberately absent from the manifest — deleting them would destroy the
+  // user's own configuration alongside ours.
+  for (const id of manifest.targets) {
+    const t = targets[id];
+    if (!t?.postUninstall) continue;
+    const post = t.postUninstall({ scope, projectDir, home, dryRun: flag(flags.dryRun) });
+    for (const f of post.changed) console.log(`   unwired mugiwara hooks from ${f}`);
+    for (const n of post.notes) console.log(`   note: ${n}`);
+  }
   if (!flag(flags.dryRun)) {
     if (scope === 'project') {
       const gi = removeProjectGitignore(projectDir);
@@ -192,6 +280,168 @@ function list(flags: Args['flags']): void {
   if (!found) console.log('No mugiwara installation found.');
 }
 
+/**
+ * `mugiwara continue [mission] [member]` — the deterministic half of resume.
+ *
+ * Selecting which mission/member to resume is a directory scan, not a judgement
+ * call, so it runs here instead of costing the host model a reasoning turn.
+ * Only the last step (verifying next_action against the plan) needs a model,
+ * and that happens after this prints.
+ *
+ * Exit codes: 0 = a single resume point was printed; 2 = ambiguous or absent,
+ * the caller must stop and let the user pick.
+ */
+function continueCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const [mission, member] = positionals.slice(1);
+  let entries = readContinue(projectDir);
+
+  // default to this actor's work; --all crosses actors on a shared checkout
+  if (!flag(flags.all)) {
+    const actor = gitActor(projectDir);
+    const mine = entries.filter((e) => e.actor === actor);
+    // an actor-less savepoint (older file, or git identity unset) is still the
+    // only thing on disk — showing nothing would look like "no missions"
+    if (mine.length) entries = mine;
+  }
+
+  const r = resolveContinue(entries, mission, member);
+  if (r.kind === 'resume') {
+    console.log(formatResume(r.entry));
+    const st = readState(projectDir).find((s) => s.mission === r.entry.mission && s.member === r.entry.member);
+    const stale = st ? stalenessLine(projectDir, st.base_sha) : null;
+    if (stale) console.log(stale);
+    return;
+  }
+
+  if (r.kind === 'none') {
+    console.log('No mission in flight. Start one with Flow 0 triage (mugiwara-orchestration).');
+  } else if (r.kind === 'missions') {
+    console.log(`${new Set(r.entries.map((e) => e.mission)).size} missions in flight:\n`);
+    console.log(formatTable(r.entries));
+    console.log('\nPick one: mugiwara continue <mission> [member]');
+  } else if (r.kind === 'members') {
+    console.log(`Mission "${r.mission}" has ${r.entries.length} members in flight:\n`);
+    console.log(formatTable(r.entries));
+    console.log(`\nPick one: mugiwara continue ${r.mission} <member>`);
+  } else if (r.kind === 'unknown-mission') {
+    console.error(`No in-flight mission "${r.mission}". Known: ${r.known.join(', ') || '(none)'}`);
+  } else {
+    console.error(`Mission "${r.mission}" has no member "${r.member}". Known: ${r.known.join(', ')}`);
+  }
+  process.exit(2);
+}
+
+/** `mugiwara status` — one screen of computed mission state, no model needed. */
+function statusCmd(flags: Args['flags']): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const states = readState(projectDir);
+  if (!states.length) { console.log('No mission state on disk.'); return; }
+  const actor = flag(flags.all) ? null : gitActor(projectDir);
+  const rows = actor ? (states.filter((s) => s.actor === actor).length ? states.filter((s) => s.actor === actor) : states) : states;
+  for (const s of rows) {
+    const scope = s.member ? ` [${s.member}]` : '';
+    console.log(`${s.mission}${scope}`);
+    console.log(`  flow ${s.flow} · ${s.tasks_done}/${s.tasks_total} tasks · lane ${s.lane}${s.lane_rose ? ' ⬆ ROSE' : ''}${s.lane_reason ? ` (${s.lane_reason})` : ''} · mode ${s.mode}`);
+    console.log(`  blockers ${s.blockers_open} · heal cycle ${s.heal_cycle}/${s.heal_max_cycles}${s.heal_halt ? ' — HALT' : ''} · files touched ${s.files_touched}`);
+    if (s.budget) console.log(`  tokens ${s.tokens_est}/${s.budget} (${s.budget_status})${s.delegate_due ? ' · delegate due' : ''}`);
+    console.log(`  branch ${s.branch} · updated ${s.updated_at}`);
+    if (s.evidence.length) console.log(`  evidence: ${s.evidence.join(', ')}`);
+  }
+}
+
+/** `mugiwara run <script.sh> [args]` — run a bundled harness script here. */
+function runCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const name = positionals[1];
+  if (!name) {
+    console.error(`usage: mugiwara run <script> [args...]\n  scripts: ${RUNNABLE.join(', ')}`);
+    process.exit(1);
+  }
+  const code = runScript(name, positionals.slice(2), projectDir);
+  if (code !== 0) process.exit(code);
+}
+
+/** `mugiwara blame <path>` — provenance note on the last commit touching path. */
+function blameCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const path = positionals[1];
+  if (!path) { console.error('usage: mugiwara blame <file-path>'); process.exit(1); }
+  console.log(blamePath(projectDir, path));
+}
+
+/**
+ * Staleness: has main moved since the mission's recorded base?
+ * N commits behind = the ground this mission started from has shifted.
+ */
+export function stalenessLine(projectDir: string, baseSha: string): string | null {
+  if (!baseSha || baseSha === 'unknown') return null;
+  const git = (args: string[]): string => {
+    try {
+      return execFileSync('git', args, { cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch { return ''; }
+  };
+  let main = '';
+  for (const ref of ['main', 'master']) {
+    main = git(['rev-parse', '--verify', ref]);
+    if (main) break;
+  }
+  if (!main) return null;
+  try {
+    const behind = Number(git(['rev-list', '--count', `${baseSha}..${main}`])) || 0;
+    return behind > 0
+      ? `⚠ stale base: main is ${behind} commit(s) ahead of this mission's base ${baseSha.slice(0, 7)} — rebase check before continuing`
+      : null;
+  } catch { return null; }
+}
+
+/** `mugiwara handoff <mission>` — a report the next engineer can act on. */
+function handoffCmd(flags: Args['flags'], positionals: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const mission = positionals[1];
+  if (!mission) { console.error('usage: mugiwara handoff <mission> [--project <dir>]'); process.exit(1); }
+  const states = readState(projectDir).filter((s) => s.mission === mission);
+  if (!states.length) { console.error(`no in-flight mission "${mission}"`); process.exit(1); }
+  const lines = [
+    `# Handoff: ${mission}`,
+    '',
+    `Generated ${new Date().toISOString()} by \`mugiwara handoff\`.`,
+    '',
+    '| | |',
+    '|---|---|',
+  ];
+  for (const s of states) {
+    const scope = s.member ? ` [${s.member}]` : '';
+    lines.push(`| Mission${scope} | flow ${s.flow}, tasks ${s.tasks_done}/${s.tasks_total}, lane ${s.lane}${s.lane_rose ? ' (rose)' : ''}, mode ${s.mode} |`);
+    lines.push(`| Branch | \`${s.branch}\` |`);
+    lines.push(`| Actor | ${s.actor || '(unknown)'} |`);
+    if (s.next_action) lines.push(`| Next action | ${s.next_action} |`);
+    if (s.blockers_open) lines.push(`| Open blockers | ${s.blockers_open} |`);
+    if (s.heal_cycle) lines.push(`| Heal cycles | ${s.heal_cycle}/${s.heal_max_cycles}${s.heal_halt ? ' — HALTED' : ''} |`);
+    if (s.evidence.length) lines.push(`| Evidence | ${s.evidence.join(', ')} |`);
+    const stale = stalenessLine(projectDir, s.base_sha);
+    if (stale) lines.push(`| Staleness | ${stale.replace('⚠ stale base: ', '')} |`);
+  }
+  lines.push('', '## Resuming', '', `\`mugiwara continue ${mission}\` prints the exact resume point.`);
+  lines.push('Verify `next_action` against plan.md before executing — the table above is computed state, not judgement.');
+  const out = join('.mugiwara', 'missions', mission, 'handoff.md');
+  writeFileSync(resolve(projectDir, out), lines.join('\n') + '\n');
+  console.log(lines.join('\n'));
+  console.log(`\nwritten: ${out}`);
+}
+
+/** `mugiwara sign <mission>` / `--verify` — optional minisign attestation. */
+function signCmd(flags: Args['flags'], _: string[]): void {
+  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const mission = _[1];
+  if (!mission) { console.error('usage: mugiwara sign <mission> [--verify] [--project <dir>]'); process.exit(1); }
+  const missionDir = join(projectDir, '.mugiwara', 'missions', mission);
+  if (!existsSync(missionDir)) { console.error(`no mission dir: ${missionDir}`); process.exit(1); }
+  const r = flag(flags.verify) ? verifyReport(projectDir, missionDir) : signReport(projectDir, missionDir);
+  console.log(`${r.ok ? '✓' : '✗'} ${r.message}`);
+  if (!r.ok) process.exit(1);
+}
+
 function help(): void {
   console.log(`mugiwara ${VERSION} — the Straw Hat crew for AI agents
 
@@ -201,8 +451,23 @@ Usage:
   mugiwara uninstall     remove installed files via manifest
   mugiwara list          show installations
   mugiwara list --check  health check: show installations + missing files
-  mugiwara reset         wipe mission state (spec/plans/results/review/issues[/logs])
-  mugiwara archive <m>    fold a closed mission's evidence into its report, then remove loose files
+  mugiwara reset         wipe mission state (missions/ + legacy dirs)
+  mugiwara archive <m>   fold a closed mission's waves into its report, then remove loose files
+  mugiwara clean [--all] [--before <date>]
+                         batch-archive every closed mission (report.md present, no live state)
+  mugiwara continue      list in-flight missions (exit 2 = pick one, nothing resumed)
+  mugiwara continue <m> [member]
+                         print the exact resume point for that mission/member
+  mugiwara status        computed mission state: wave, tasks, lane, blockers, budget
+  mugiwara blame <path>  provenance note on the last commit touching <path>
+                         (fetch notes first: git fetch origin 'refs/notes/mugiwara:refs/notes/mugiwara')
+  mugiwara handoff <m>   write .mugiwara/missions/<m>/handoff.md — a report the next
+                         engineer can act on (computed state + staleness check)
+  mugiwara sign <m>      optional attestation: minisign-sign report.md (--verify to check)
+  mugiwara run <script> [args...]
+                         run a bundled harness script here (${RUNNABLE.join(', ')})
+  mugiwara savepoint <mission> [member] [flow] [mode]
+                         shorthand for: mugiwara run savepoint.sh ...
   mugiwara --help        this help
   mugiwara --version     print version
 
@@ -214,7 +479,10 @@ Flags:
   --force                overwrite differing files (with backup)
   --dry-run              print actions without writing
   --check                with list: report missing files (health check)
-  --keep-logs            with reset: keep .mugiwara/logs (lessons ledger survives)`);
+   --all                  with continue/status: every actor; with clean: include in-flight missions
+   --force                with clean --all: archive in-flight missions anyway
+   --before <date>        with clean: also archive missions untouched since this date
+   --keep-logs            with reset: keep lessons.md (lessons ledger survives)`);
 }
 
 const isMain = process.argv[1] !== undefined && fileURLToPath(import.meta.url) === resolve(process.argv[1]);