@ionivetech/mugiwara 0.8.0 → 0.8.2

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -12,7 +12,7 @@ import { installTo, removeInstalled, VERSION, ensureProjectGitignore, removeProj
 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 { readContinue, readState, resolveContinue, formatTable, formatResume, gitActor, hasLegacyLayout, CURRENT_SCHEMA_VERSION, unreadableStateFiles } from './continue.ts';
 import { blamePath } from './provenance.ts';
 import { signReport, verifyReport, ensurePureKey, hasMinisign } from './sign.ts';
 import { ensureConfig } from './config.ts';
@@ -20,31 +20,50 @@ import { costEnvelope } from './cost.ts';
 import { computeLiveSlop } from './slop.ts';
 import { loadRegistry } from './evidence.ts';
 import { buildCostLedger, toCostJSON } from './reporting.ts';
+import { enforceHarnessPolicy } from './policy.ts';
 
 const str = (v: FlagValue): string | undefined => (typeof v === 'string' ? v : undefined);
 const flag = (v: FlagValue): boolean => v === true;
 
+// Anchor to the repo root so running from a package subdirectory does not
+// create a shadow .mugiwara/ there. (B4)
+function resolveProjectDir(explicit?: string): string {
+  if (explicit) return resolve(explicit);
+  try {
+    const root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+    if (root) return root;
+  } catch { /* not a git repo — fall through */ }
+  return process.cwd();
+}
+
 export async function run(argv: string[]): Promise<void> {
   const { command, flags, _ } = parseArgs(argv);
   if (flag(flags.help) || command === 'help') return help();
   if (flag(flags.version)) { console.log(`mugiwara ${VERSION}`); return; }
-  // `continue` and `status` are read-only position commands: dispatch before
-  // config bootstrap so a fresh project never gets a .mugiwara/config created
-  // and no setup chatter is printed before missions/members are listed.
-  if (command === 'continue' || command === 'status') {
-    return command === 'continue' ? continueCmd(flags, _) : statusCmd(flags);
+  // harness.require_enforcement — enterprise gate: refuse rules-based harnesses
+  // (only opencode is runtime-enforced). Covers run/savepoint/archive/status
+  // + other workflow commands; install/update/uninstall/list are setup and bypass.
+  {
+    const bypass = new Set(['install', 'update', 'uninstall', 'list']);
+    if (!bypass.has(command)) {
+      const projectDirForHarness = resolveProjectDir(str(flags.project));
+      enforceHarnessPolicy(projectDirForHarness);
+    }
   }
-  // A command on a fresh project must be immediately usable — bootstrap the
-  // default .mugiwara/config when it is missing (not only at install time).
-  // Skipped for install/update --dry-run: a dry run must not mutate the
-  // project (the installer writes the config itself on a real install).
+  // Bootstrap default .mugiwara/config on any command when missing — including
+  // `continue`/`status` — so tier-3 agents that only mkdir .mugiwara still get
+  // a config. Also covered by readConfig() auto-create for non-CLI entry.
+  // Skipped for install/update --dry-run: a dry run must not mutate the project.
   const isDryRunInstall = (command === 'install' || command === 'update') && flag(flags.dryRun);
   if (!isDryRunInstall) {
-    const projectDir = resolve(str(flags.project) ?? process.cwd());
+    const projectDir = resolveProjectDir(str(flags.project));
     if (ensureConfig(projectDir)) {
       console.log(`default .mugiwara/config written at ${join(projectDir, '.mugiwara', 'config')} (edit it to customise)`);
     }
   }
+  if (command === 'continue' || command === 'status') {
+    return command === 'continue' ? continueCmd(flags, _) : statusCmd(flags);
+  }
   switch (command) {
     case 'install': return install(flags);
     case 'update': return install({ ...flags, force: true });
@@ -61,12 +80,13 @@ export async function run(argv: string[]): Promise<void> {
     case 'blame': return blameCmd(flags, _);
     case 'handoff': return handoffCmd(flags, _);
     case 'sign': return signCmd(flags, _);
+    case 'migrate': return migrateCmd(flags);
     default: throw new Error(`Unknown command: ${command}`);
   }
 }
 
 function resetCmd(flags: Args['flags']): void {
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   const force = flag(flags.force);
   const result = resetMission(projectDir, flag(flags.keepLogs), force);
   if (result.blocked) {
@@ -79,7 +99,7 @@ function resetCmd(flags: Args['flags']): void {
 }
 
 function archive(flags: Args['flags'], positionals: string[]): void {
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   const mission = positionals[1];
   if (!mission) { console.error('usage: mugiwara archive <mission> [--project <dir>] [--dry-run]'); process.exit(1); }
   const result = archiveMission(projectDir, mission, { dryRun: flag(flags.dryRun) });
@@ -98,7 +118,7 @@ function archive(flags: Args['flags'], positionals: string[]): void {
  * touched before that date.
  */
 function cleanCmd(flags: Args['flags']): void {
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   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; }
@@ -164,7 +184,7 @@ async function resolveOptions(flags: Args['flags']): Promise<{ scope: Scope; pro
       if (!interactive) { scope = 'project'; }
       else scope = (await choose(rl!, 'Install scope?', ['global (user-wide)', 'project (this repo)'])) === 0 ? 'global' : 'project';
     }
-    const projectDir = resolve(str(flags.project) ?? process.cwd());
+    const projectDir = resolveProjectDir(str(flags.project));
     if (scope === 'project' && !existsSync(projectDir)) throw new Error(`Project dir not found: ${projectDir}`);
 
     let targetIds = str(flags.target)?.split(',').map(s => s.trim()) ?? null;
@@ -222,13 +242,15 @@ 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.`);
+  console.log('CLI: run `npm i -g @ionivetech/mugiwara` so the crew can call `mugiwara savepoint/archive/continue`.');
+  console.log('     Without it the crew degrades to inline-only — no state, no resume, no closure gate.');
   // 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> {
   const scope: Scope = flag(flags.global) ? 'global' : 'project';
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   const home = homedir();
   const file = manifestPath({ scope, projectDir, home });
   const manifest = readManifest(file);
@@ -282,9 +304,27 @@ async function uninstall(flags: Args['flags']): Promise<void> {
   console.log(`OK removed ${removed.length} files`);
 }
 
+function legacyWarning(projectDir: string): void {
+  if (hasLegacyLayout(projectDir)) {
+    console.error('⚠ legacy layout detected (v0.6 .mugiwara/state/ — run `mugiwara migrate` to move to missions/)');
+  }
+}
+
+function schemaWarnings(projectDir: string): void {
+  const states = readState(projectDir);
+  for (const s of states) {
+    const v = s.schema_version;
+    if (v !== CURRENT_SCHEMA_VERSION) {
+      const wrote = v === null || v === undefined || v === '' ? 'unknown' : String(v);
+      console.error(`⚠ state written by v${wrote} (mission ${s.mission}${s.member ? `/${s.member}` : ''}) — current expects v${CURRENT_SCHEMA_VERSION} — run \`mugiwara migrate\``);
+    }
+  }
+}
+
 function list(flags: Args['flags']): void {
   const home = homedir();
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
+  legacyWarning(projectDir);
   let found = false;
   for (const [label, file] of [
     ['project', manifestPath({ scope: 'project', projectDir, home })],
@@ -315,10 +355,28 @@ function list(flags: Args['flags']): void {
  * 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 projectDir = resolveProjectDir(str(flags.project));
+  legacyWarning(projectDir);
+  schemaWarnings(projectDir);
   const [mission, member] = positionals.slice(1);
   let entries = readContinue(projectDir);
 
+  // If the requested member's state file is unreadable, refuse rather than
+  // resuming from continue-<member>.json alone. A resume point without its
+  // state is a guess. (B6)
+  if (mission) {
+    // readState populates unreadableStateFiles for state files; entries already captured
+    readState(projectDir);
+    const badState = unreadableStateFiles();
+    const target = member ? `${mission}/${member}.json` : `${mission}/state.json`;
+    if (badState.includes(target)) {
+      console.error(`✗ mission "${mission}"${member ? ` member "${member}"` : ''} has unreadable state: ${target}`);
+      process.exit(1);
+    }
+    // re-read continue entries after the state scan cleared unreadable (preserve original entries)
+    // entries already holds the correct continue data, no need to re-read
+  }
+
   // default to this actor's work; --all crosses actors on a shared checkout
   if (!flag(flags.all)) {
     const actor = gitActor(projectDir);
@@ -357,9 +415,19 @@ function continueCmd(flags: Args['flags'], positionals: string[]): void {
 
 /** `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 projectDir = resolveProjectDir(str(flags.project));
+  legacyWarning(projectDir);
+  schemaWarnings(projectDir);
   const states = readState(projectDir);
-  if (!states.length) { console.log('No mission state on disk.'); return; }
+  const bad = unreadableStateFiles();
+  if (bad.length) {
+    console.error(`⚠ ${bad.length} unreadable state file(s): ${bad.join(', ')}`);
+    console.error('  These are not "no mission" — they are corrupt. Inspect or delete them.');
+  }
+  if (!states.length) {
+    console.log(bad.length ? 'No readable mission state on disk.' : '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) {
@@ -375,7 +443,7 @@ function statusCmd(flags: Args['flags']): void {
 
 /** `mugiwara cost [--mission <id>] [--json] [--ledger]` — show cost ledger, avoided work, efficiency, trail. */
 function costCmd(flags: Args['flags'], positionals: string[]): void {
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   const mission = str(flags.mission) ?? positionals[1] ?? (() => {
     const states = readState(projectDir);
     if (states.length === 1) return states[0].mission;
@@ -430,7 +498,7 @@ function costCmd(flags: Args['flags'], positionals: string[]): void {
 
 /** `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 projectDir = resolveProjectDir(str(flags.project));
   const name = positionals[1];
   if (!name) {
     console.error(`usage: mugiwara run <script> [args...]\n  scripts: ${RUNNABLE.join(', ')}`);
@@ -442,7 +510,7 @@ function runCmd(flags: Args['flags'], positionals: string[]): void {
 
 /** `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 projectDir = resolveProjectDir(str(flags.project));
   const path = positionals[1];
   if (!path) { console.error('usage: mugiwara blame <file-path>'); process.exit(1); }
   console.log(blamePath(projectDir, path));
@@ -475,10 +543,15 @@ export function stalenessLine(projectDir: string, baseSha: string): string | nul
 
 /** `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 projectDir = resolveProjectDir(str(flags.project));
   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);
+  const bad = unreadableStateFiles().filter((p) => p.startsWith(`${mission}/`));
+  if (bad.length) {
+    console.error(`✗ mission "${mission}" has unreadable state: ${bad.join(', ')}`);
+    process.exit(1);
+  }
   if (!states.length) { console.error(`no in-flight mission "${mission}"`); process.exit(1); }
   const lines = [
     `# Handoff: ${mission}`,
@@ -508,9 +581,91 @@ function handoffCmd(flags: Args['flags'], positionals: string[]): void {
   console.log(`\nwritten: ${out}`);
 }
 
+export function migrateCmd(flags: Args['flags']): void {
+  const projectDir = resolveProjectDir(str(flags.project));
+  const dryRun = flag(flags.dryRun);
+  const legacyState = join(projectDir, '.mugiwara', 'state');
+  const legacyContinue = join(projectDir, '.mugiwara', 'continue');
+  const missionsRoot = join(projectDir, '.mugiwara', 'missions');
+  const moves: Array<{ src: string; dest: string }> = [];
+
+  const collect = (srcRoot: string, isContinue: boolean) => {
+    if (!existsSync(srcRoot)) return;
+    const walk = (dir: string) => {
+      for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (e.isFile() && e.name.endsWith('.json')) {
+          const rel = full.slice(srcRoot.length + 1);
+          let destRel: string;
+          if (isContinue) {
+            const parts = rel.split('/');
+            const file = parts.pop()!;
+            const mission = parts.join('/');
+            const stem = file.slice(0, -'.json'.length);
+            let destFile: string;
+            if (stem === 'state') destFile = 'continue.json';
+            else destFile = `continue-${stem}.json`;
+            destRel = mission ? join(mission, destFile) : destFile;
+          } else {
+            destRel = rel;
+          }
+          moves.push({ src: full, dest: join(missionsRoot, destRel) });
+        }
+      }
+    };
+    walk(srcRoot);
+  };
+  collect(legacyState, false);
+  collect(legacyContinue, true);
+
+  // legacy flat: .mugiwara/state.json style? treat any top-level .mugiwara/state*.json as not legacy missions but still warn
+  // Already covered by state/ dir; nothing more to collect.
+
+  if (!moves.length) {
+    if (!existsSync(legacyState) && !existsSync(legacyContinue)) {
+      console.log('no legacy layout found (.mugiwara/state/ does not exist)');
+    } else {
+      console.log('no legacy state files to migrate');
+    }
+    return;
+  }
+
+  for (const m of moves) {
+    console.log(`${dryRun ? 'would migrate' : 'migrated'} ${m.src} → ${m.dest}`);
+    if (!dryRun) {
+      mkdirSync(dirname(m.dest), { recursive: true });
+      try {
+        const raw = JSON.parse(readFileSync(m.src, 'utf8')) as Record<string, unknown>;
+        raw.schema_version = CURRENT_SCHEMA_VERSION;
+        writeFileSync(m.dest, JSON.stringify(raw, null, 2) + '\n');
+        rmSync(m.src, { force: true });
+      } catch {
+        try { renameSync(m.src, m.dest); } catch { /* ignore */ }
+      }
+    }
+  }
+  if (!dryRun) {
+    const prune = (root: string) => {
+      if (!existsSync(root)) return;
+      const walkPrune = (dir: string) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          if (e.isDirectory()) walkPrune(join(dir, e.name));
+        }
+        try { if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+      };
+      walkPrune(root);
+      try { if (existsSync(root) && readdirSync(root).length === 0) rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
+    };
+    prune(legacyState);
+    prune(legacyContinue);
+  }
+  console.log(`${dryRun ? 'would migrate' : 'migrated'} ${moves.length} file(s)${dryRun ? ' (dry run)' : ''}`);
+}
+
 /** `mugiwara sign <mission>` / `--verify` / `--gen-key` — optional attestation. */
 function signCmd(flags: Args['flags'], _: string[]): void {
-  const projectDir = resolve(str(flags.project) ?? process.cwd());
+  const projectDir = resolveProjectDir(str(flags.project));
   if (flag(flags.genKey)) {
     const backend = str(flags.backend) ?? 'auto';
     const home = homedir();
@@ -562,10 +717,12 @@ Usage:
   mugiwara sign <m>      attestation: sign report.md (auto/minisign/pure/off; --verify to check)
   mugiwara sign --gen-key [--backend pure|minisign]
                          create signing keys (pure ed25519 default)
+  mugiwara migrate [--dry-run] [--project <dir>]
+                          move legacy .mugiwara/state/ layout to .mugiwara/missions/
   mugiwara run <script> [args...]
-                         run a bundled harness script here (${RUNNABLE.join(', ')})
+                          run a bundled harness script here (${RUNNABLE.join(', ')})
   mugiwara savepoint <mission> [member] [flow] [mode]
-                         shorthand for: mugiwara run savepoint.sh ...
+                          shorthand for: mugiwara run savepoint.sh ...
   mugiwara --help        this help
   mugiwara --version     print version
 

package/src/config.ts

@@ -40,6 +40,12 @@ function configPaths(projectDir: string): string[] {
  * blank lines are skipped; values are trimmed.
  */
 export function readConfig(projectDir: string): Record<string, string> {
+  try {
+    const file = join(projectDir, '.mugiwara', 'config');
+    let exists = false;
+    try { exists = lstatSync(file).isFile() || lstatSync(file).isSymbolicLink(); } catch { exists = false; }
+    if (!exists) ensureConfig(projectDir);
+  } catch { /* best-effort: auto-create must not break reads */ }
   const out: Record<string, string> = {};
   for (const file of configPaths(projectDir)) {
     if (!existsSync(file)) continue;

package/src/continue.ts

@@ -14,6 +14,32 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 
+export const CURRENT_SCHEMA_VERSION = 2;
+
+/**
+ * v0.6 legacy layout: `.mugiwara/state/<mission>/<member>.json`
+ * (and `.mugiwara/continue/<mission>/...`) is invisible to v0.8
+ * `missions/` readers. Detect it so status/continue can warn.
+ */
+export function hasLegacyLayout(projectDir: string): boolean {
+  for (const legacy of [join(projectDir, '.mugiwara', 'state'), join(projectDir, '.mugiwara', 'continue')]) {
+    if (!existsSync(legacy)) continue;
+    try {
+      const walk = (dir: string): boolean => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+          if (e.isFile() && e.name.endsWith('.json')) return true;
+          if (e.isDirectory() && walk(join(dir, e.name))) return true;
+        }
+        return false;
+      };
+      if (walk(legacy)) return true;
+    } catch { /* ignore */ }
+  }
+  // also legacy flat files at .mugiwara/state.json style already handled by missions scan,
+  // but treat top-level .mugiwara/state/*.json absence as no legacy
+  return false;
+}
+
 /** Mission/member allowlist — identical to savepoint.sh and mission.ts. */
 const SAFE = /^[A-Za-z0-9._-]+$/;
 const isSafeKey = (s: string): boolean => SAFE.test(s) && !/^\.+$/.test(s);
@@ -51,6 +77,7 @@ export type StateEntry = ContinueEntry & {
   budget_status: string;
   files_touched: number;
   evidence: string[];
+  schema_version: number | string | null;
 };
 
 const num = (v: unknown): number => {
@@ -84,6 +111,11 @@ export function gitActor(cwd: string): string {
   return name || process.env.USER || process.env.USERNAME || '';
 }
 
+const unreadable: string[] = [];
+
+/** State files that exist but could not be parsed. Cleared by each scan. (B6) */
+export function unreadableStateFiles(): string[] { return [...unreadable]; }
+
 /**
  * Read every mission dir under `.mugiwara/missions/<mission>/`, picking the
  * files this reader owns: state readers take `state.json` / `<member>.json`,
@@ -91,6 +123,7 @@ export function gitActor(cwd: string): string {
  * files are skipped.
  */
 function scan<T>(projectDir: string, kind: 'state' | 'continue', map: (raw: Record<string, unknown>, member: string | null) => T): T[] {
+  unreadable.length = 0;
   const base = join(projectDir, '.mugiwara', 'missions');
   if (!existsSync(base)) return [];
   const out: T[] = [];
@@ -121,7 +154,7 @@ function scan<T>(projectDir: string, kind: 'state' | 'continue', map: (raw: Reco
         if (text(raw.mission) !== mission) continue;
         out.push(map(raw, member));
       } catch {
-        // corrupt savepoint — skip, never crash the listing
+        unreadable.push(join(mission, f));
       }
     }
   }
@@ -148,6 +181,7 @@ export function readContinue(projectDir: string): ContinueEntry[] {
 export function readState(projectDir: string): StateEntry[] {
   return scan(projectDir, 'state', (r, member) => {
     const tasks = (r.tasks ?? {}) as Record<string, unknown>;
+    const sv = r.schema_version;
     return {
       mission: text(r.mission),
       member,
@@ -178,6 +212,7 @@ export function readState(projectDir: string): StateEntry[] {
       budget_status: text(r.budget_status) || 'ok',
       files_touched: num(r.files_touched),
       evidence: Array.isArray(r.evidence) ? r.evidence.map(text).filter(Boolean) : [],
+      schema_version: typeof sv === 'number' || typeof sv === 'string' ? sv : null,
     };
   });
 }

package/src/cost.ts

@@ -33,7 +33,7 @@ export const LANE_BUDGET: Record<string, number> = {
   lean: 12000,
   standard: 25000,
   full: 50000,
-  spike: 3000,
+  spike: 9000,
 };
 
 /** Token estimate for skills/agents loaded in this lane (0 for unknown/direct). */
@@ -149,6 +149,9 @@ export function appendCostEvent(missionDir: string, event: Omit<CostEvent, 'ts'>
   appendFileSync(join(missionDir, COST_EVENTS_FILE), JSON.stringify(line) + '\n', 'utf8');
 }
 
+// ── Auto-compress (T4) — compressed event kind ───────────────────────────────
+export const COMPRESSED_KIND = 'compressed';
+
 // ── Optimization decision records — structured rows in decisions.md ──
 
 export type OptDecision = {

package/src/installer.ts

@@ -1,5 +1,5 @@
 // src/installer.ts
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync, lstatSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync, lstatSync, chmodSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -57,6 +57,7 @@ export interface Target {
 }
 
 export const CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'content');
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')) as { version: string };
 export const VERSION = pkg.version;
 
@@ -99,9 +100,13 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
   const backupRoot = join(scope === 'global' ? home : projectDir, '.mugiwara');
   const result: InstallResult = { written: [], skipped: [], backedUp: [], notes: [] };
 
-  const writeOne = (absPath: string, text: string) => {
+  const writeOne = (absPath: string, text: string, mode?: number) => {
     if (existsSync(absPath)) {
-      if (readFileSync(absPath, 'utf8') === text) { result.skipped.push(absPath); return; }
+      if (readFileSync(absPath, 'utf8') === text) {
+        // ensure mode even when content unchanged
+        if (!dryRun && mode !== undefined) { try { chmodSync(absPath, mode); } catch { /* ignore */ } }
+        result.skipped.push(absPath); return;
+      }
       if (!force) {
         result.skipped.push(absPath);
         result.notes.push(`conflict (not overwritten; run update to replace with backup): ${absPath}`);
@@ -114,7 +119,11 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
       if (!dryRun) { mkdirSync(backupDir, { recursive: true }); copyFileSync(absPath, backupFile); }
       result.backedUp.push(absPath);
     }
-    if (!dryRun) { mkdirSync(dirname(absPath), { recursive: true }); writeFileSync(absPath, text); }
+    if (!dryRun) {
+      mkdirSync(dirname(absPath), { recursive: true });
+      writeFileSync(absPath, text);
+      if (mode !== undefined) { try { chmodSync(absPath, mode); } catch { /* ignore */ } }
+    }
     result.written.push(absPath);
   };
 
@@ -156,6 +165,20 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     for (const r of sharedRefs) writeOne(join(sharedRoot, r.relPath), r.text);
   }
 
+  // Shell fallbacks: pure sh, no Node. The critical path (lane sizing + state)
+  // must survive on a harness where the CLI cannot run. See plan.md B1.
+  {
+    const SHELL_FALLBACKS = ['lane.sh', 'savepoint.sh', 'lib/patterns.sh', 'lib/lane-base.sh'];
+    const mugiwaraDir = join(scope === 'global' ? home : projectDir, '.mugiwara');
+    for (const rel of SHELL_FALLBACKS) {
+      const src = join(REPO_ROOT, 'scripts', rel);
+      if (!existsSync(src)) continue;
+      const text = readFileSync(src, 'utf8');
+      const dest = join(mugiwaraDir, 'bin', rel);
+      writeOne(dest, text, 0o755);
+    }
+  }
+
   if (target.postInstall) {
     const post = target.postInstall({ scope, projectDir, home, dryRun, files: result.written });
     result.written.push(...post.written);