nubos-pilot 0.1.0

package/lib/runtime/opencode.cjs

@@ -0,0 +1,35 @@
+const { askUserReadline } = require('./_readline.cjs');
+
+async function askUser(spec) {
+  return askUserReadline({
+    type: spec && spec.type,
+    question: spec && spec.question,
+    options: spec && spec.options,
+    def: spec ? spec.default : undefined,
+  });
+}
+
+module.exports = {
+  name: 'opencode',
+  detectHints: {
+    env: ['OPENCODE', 'OPENCODE_VERSION'],
+    pathBinary: 'opencode',
+    diskMarkers: ['.opencode/', 'opencode.json'],
+  },
+  capabilities: {
+    askUserQuestion: false,
+    slashCommands: false,
+    agentsMd: 'AGENTS.md',
+    textMode: 'auto',
+    modelResolution: 'inherit',
+  },
+  paths: {
+    payload: '.opencode/nubos-pilot/',
+    config: 'opencode.json',
+    agentsMd: '.opencode/nubos-pilot/AGENTS.md',
+  },
+  runtimeNotice:
+    '> **Runtime-Hinweis:** Diese Datei (.opencode/nubos-pilot/AGENTS.md) wird von OpenCode konsumiert. '
+    + 'Interaktive Prompts laufen über readline (stderr); Subagents erben das Modell vom Caller (`/model inherit`).',
+  askUser,
+};

package/lib/runtime/opencode.test.cjs

@@ -0,0 +1,124 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const { _setReadlineImplForTests } = require('./_readline.cjs');
+const oc = require('./opencode.cjs');
+
+function captureStderr(fn) {
+  const chunks = [];
+  const orig = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (chunk) => { chunks.push(chunk.toString()); return true; };
+  return Promise.resolve(fn()).then(
+    (val) => { process.stderr.write = orig; return { val, out: chunks.join('') }; },
+    (err) => { process.stderr.write = orig; throw err; },
+  );
+}
+
+test('opencode-adapter: exports five-key contract', () => {
+  for (const k of ['name', 'detectHints', 'capabilities', 'paths', 'askUser']) {
+    assert.ok(k in oc, 'missing ' + k);
+  }
+  assert.equal(oc.name, 'opencode');
+});
+
+test('opencode-adapter: capabilities match D-07 + RESEARCH refinement', () => {
+  const c = oc.capabilities;
+  assert.equal(c.askUserQuestion, false);
+  assert.equal(c.slashCommands, false);
+  assert.equal(c.agentsMd, 'AGENTS.md');
+  assert.equal(c.textMode, 'auto');
+  assert.equal(
+    c.modelResolution,
+    'inherit',
+    'RUN-02 RESEARCH: OpenCode inheritance is signaled by OMITTING model field; capability flag must read "inherit"',
+  );
+});
+
+test('opencode-adapter: paths.config is project-root opencode.json (NOT .opencode/config.json)', () => {
+  assert.equal(
+    oc.paths.config,
+    'opencode.json',
+    'RESEARCH refinement of D-13: OpenCode config lives at project root as opencode.json',
+  );
+  assert.notEqual(oc.paths.config, '.opencode/config.json');
+});
+
+test('opencode-adapter: paths.payload and paths.agentsMd live under .opencode/nubos-pilot/ (8.1 D-02)', () => {
+  assert.equal(oc.paths.payload, '.opencode/nubos-pilot/');
+  assert.equal(oc.paths.agentsMd, '.opencode/nubos-pilot/AGENTS.md');
+  assert.notEqual(oc.paths.agentsMd, '.opencode/AGENTS.md');
+  assert.notEqual(oc.paths.payload, '.opencode/');
+});
+
+test('opencode-adapter: readline select parses 1-based index', async () => {
+  _setReadlineImplForTests(async () => '2');
+  try {
+    const { val } = await captureStderr(() =>
+      oc.askUser({ type: 'select', question: 'P', options: ['A', 'B', 'C'] }),
+    );
+    assert.equal(val.value, 'B');
+    assert.equal(val.source, 'readline');
+  } finally {
+    _setReadlineImplForTests(null);
+  }
+});
+
+test('opencode-adapter: readline multiselect parses comma-indices', async () => {
+  _setReadlineImplForTests(async () => '1,3');
+  try {
+    const { val } = await captureStderr(() =>
+      oc.askUser({ type: 'multiselect', question: 'P', options: ['A', 'B', 'C'] }),
+    );
+    assert.deepEqual(val.value, ['A', 'C']);
+  } finally {
+    _setReadlineImplForTests(null);
+  }
+});
+
+test('opencode-adapter: input with injected line', async () => {
+  _setReadlineImplForTests(async () => 'hello');
+  try {
+    const { val } = await captureStderr(() =>
+      oc.askUser({ type: 'input', question: 'Q' }),
+    );
+    assert.equal(val.value, 'hello');
+    assert.equal(val.source, 'readline');
+  } finally {
+    _setReadlineImplForTests(null);
+  }
+});
+
+test('opencode-adapter: confirm y/n', async () => {
+  _setReadlineImplForTests(async () => 'n');
+  try {
+    const { val } = await captureStderr(() =>
+      oc.askUser({ type: 'confirm', question: 'OK' }),
+    );
+    assert.equal(val.value, false);
+  } finally {
+    _setReadlineImplForTests(null);
+  }
+});
+
+test('opencode-adapter: does not require install-layer modules (single responsibility)', () => {
+  const src = fs.readFileSync(require.resolve('./opencode.cjs'), 'utf-8');
+  assert.ok(
+    !/require\(['"]\.\.\/install\//.test(src),
+    'adapter must not reach into lib/install/ — install logic stays in install layer',
+  );
+});
+
+test('opencode-adapter: exports runtimeNotice compatible with agents-md SC-5 check', () => {
+  const notice = oc.runtimeNotice;
+  assert.equal(typeof notice, 'string');
+  assert.ok(notice.length > 0);
+  assert.match(notice, /readline|prompt/i, 'runtimeNotice must match /readline|prompt/i');
+});
+
+test('opencode-adapter: runtimeNotice references .opencode/nubos-pilot/AGENTS.md (8.1 D-02)', () => {
+  assert.ok(oc.runtimeNotice.includes('.opencode/nubos-pilot/AGENTS.md'));
+});
+
+test('opencode-adapter: runtimeNotice does not contain the forbidden joined Claude-tool literal (SC-5 guard)', () => {
+  assert.ok(!/Ask-User-Question/.test(oc.runtimeNotice));
+});

package/lib/state.cjs

@@ -0,0 +1,205 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { withFileLock, atomicWriteFileSync, projectStateDir, NubosPilotError } = require('./core.cjs');
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const KV_RE = /^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)$/;
+const CANONICAL_KEYS = [
+  'schema_version',
+  'milestone',
+  'milestone_name',
+  'current_phase',
+  'current_plan',
+  'current_task',
+  'last_updated',
+  'progress',
+  'session',
+];
+
+const NESTED_KEYS = new Set(['progress', 'session']);
+
+function _coerceScalar(v) {
+  if (v === 'null' || v === '') return null;
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+$/.test(v)) return Number(v);
+  if (/^-?\d+\.\d+$/.test(v)) return Number(v);
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) return v.slice(1, -1);
+  return v;
+}
+
+function _parseFlatOrNested(yamlText) {
+
+  
+  const fm = {};
+  const lines = yamlText.split(/\r?\n/);
+  let currentNestedKey = null;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+    const indent = (line.match(/^ */) || [''])[0].length;
+    const trimmed = line.trim();
+
+    if (indent === 0) {
+      const kv = trimmed.match(KV_RE);
+      if (!kv) continue;
+      const key = kv[1];
+      const rawVal = kv[2].trim();
+      if (NESTED_KEYS.has(key) && rawVal === '') {
+
+        fm[key] = {};
+        currentNestedKey = key;
+      } else {
+        fm[key] = _coerceScalar(rawVal);
+        currentNestedKey = null;
+      }
+    } else if (currentNestedKey) {
+
+      const kv = trimmed.match(KV_RE);
+      if (!kv) continue;
+      fm[currentNestedKey][kv[1]] = _coerceScalar(kv[2].trim());
+    }
+  }
+  return fm;
+}
+
+function _defaultProgress() {
+  return {
+    total_phases: 0,
+    completed_phases: 0,
+    total_plans: 0,
+    completed_plans: 0,
+    percent: 0,
+  };
+}
+
+function _defaultSession(preservedLastActivity) {
+  return {
+    stopped_at: null,
+    resume_file: null,
+    last_activity: preservedLastActivity == null ? null : preservedLastActivity,
+  };
+}
+
+function migrateV1ToV2(fmV1) {
+  const out = {
+    schema_version: 2,
+    milestone: fmV1.milestone == null ? null : fmV1.milestone,
+    milestone_name: fmV1.milestone_name == null ? null : fmV1.milestone_name,
+    current_phase: fmV1.current_phase == null ? null : fmV1.current_phase,
+    current_plan: fmV1.current_plan == null ? null : fmV1.current_plan,
+    current_task: 'current_task' in fmV1 ? fmV1.current_task : null,
+    last_updated: fmV1.last_updated == null ? null : fmV1.last_updated,
+    progress: _isPlainObject(fmV1.progress) ? { ..._defaultProgress(), ...fmV1.progress } : _defaultProgress(),
+    session: _isPlainObject(fmV1.session)
+      ? { ..._defaultSession(fmV1.last_updated), ...fmV1.session }
+      : _defaultSession(fmV1.last_updated),
+  };
+  return out;
+}
+
+function _isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function parseState(raw) {
+  const m = raw.match(FM_RE);
+  if (!m) {
+    throw new NubosPilotError(
+      'schema-version-mismatch',
+      'STATE.md missing frontmatter',
+      { raw: raw.slice(0, 200) },
+    );
+  }
+  const fm = _parseFlatOrNested(m[1]);
+
+  if (fm.schema_version === 1) {
+    return { frontmatter: migrateV1ToV2(fm), body: m[2] };
+  }
+  if (fm.schema_version === 2) {
+
+    if (!_isPlainObject(fm.progress)) fm.progress = _defaultProgress();
+    if (!_isPlainObject(fm.session)) fm.session = _defaultSession(fm.last_updated);
+    return { frontmatter: fm, body: m[2] };
+  }
+  throw new NubosPilotError(
+    'schema-version-mismatch',
+    `STATE.md schema_version=${fm.schema_version}, supported: [1, 2]`,
+    { got: fm.schema_version, supported: [1, 2] },
+  );
+}
+
+function _formatScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  const s = String(v);
+  if (s.includes(':') || /^\s/.test(s)) return `"${s}"`;
+  return s;
+}
+
+function serializeState({ frontmatter, body }) {
+
+  const fm = { ...frontmatter, schema_version: 2 };
+
+  const lines = ['---'];
+  const seen = new Set();
+
+  function emitKey(k) {
+    if (!(k in fm)) return;
+    const v = fm[k];
+    if (NESTED_KEYS.has(k) && _isPlainObject(v)) {
+      lines.push(`${k}:`);
+      for (const nk of Object.keys(v)) {
+        lines.push(`  ${nk}: ${_formatScalar(v[nk])}`);
+      }
+    } else {
+      lines.push(`${k}: ${_formatScalar(v)}`);
+    }
+    seen.add(k);
+  }
+
+  for (const k of CANONICAL_KEYS) emitKey(k);
+  for (const k of Object.keys(fm)) {
+    if (seen.has(k)) continue;
+    emitKey(k);
+  }
+
+  lines.push('---', '');
+  const bodyClean = String(body == null ? '' : body).replace(/^\n+/, '');
+  return lines.join('\n') + bodyClean;
+}
+
+function statePath(cwd = process.cwd()) {
+  return path.join(projectStateDir(cwd), 'STATE.md');
+}
+
+function readState(cwd = process.cwd()) {
+  const p = statePath(cwd);
+  return parseState(fs.readFileSync(p, 'utf-8'));
+}
+
+function writeState(next, cwd = process.cwd()) {
+  const p = statePath(cwd);
+  return withFileLock(p, () => atomicWriteFileSync(p, serializeState(next)));
+}
+
+function mutateState(mutator, cwd = process.cwd()) {
+  const p = statePath(cwd);
+  return withFileLock(p, () => {
+    const current = parseState(fs.readFileSync(p, 'utf-8'));
+    const next = mutator(current);
+    atomicWriteFileSync(p, serializeState(next));
+    return next;
+  });
+}
+
+module.exports = {
+  readState,
+  writeState,
+  mutateState,
+  statePath,
+  parseState,
+  serializeState,
+  migrateV1ToV2,
+  CANONICAL_KEYS,
+};

package/lib/state.test.cjs

@@ -0,0 +1,264 @@
+const { test, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const state = require('./state.cjs');
+
+const CANONICAL_STATE_MD =
+  '---\n' +
+  'schema_version: 1\n' +
+  'current_phase: 2\n' +
+  'current_plan: 02-02\n' +
+  'last_updated: 2026-04-14T19:30:00Z\n' +
+  '---\n' +
+  '\n' +
+  '# nubos-pilot State\n' +
+  '\n' +
+  '(freeform prose body)\n';
+
+const sandboxes = [];
+
+function makeSandbox(initialStateMd) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-test-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'));
+  if (initialStateMd !== null && initialStateMd !== undefined) {
+    fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), initialStateMd);
+  }
+  sandboxes.push(root);
+  return root;
+}
+
+afterEach(() => {
+  while (sandboxes.length) {
+    const p = sandboxes.pop();
+    try { fs.rmSync(p, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('R1: readState on seeded v1 STATE.md auto-migrates to v2 shape', () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  const s = state.readState(root);
+  assert.equal(s.frontmatter.schema_version, 2, 'v1 inputs are read back as v2');
+  assert.equal(s.frontmatter.current_phase, 2);
+  assert.equal(s.frontmatter.current_plan, '02-02');
+  assert.equal(s.frontmatter.current_task, null, 'v1 migration defaults current_task to null');
+  assert.equal(s.frontmatter.last_updated, '2026-04-14T19:30:00Z');
+  assert.ok(s.frontmatter.progress && typeof s.frontmatter.progress === 'object', 'progress block filled');
+  assert.ok(s.frontmatter.session && typeof s.frontmatter.session === 'object', 'session block filled');
+  assert.match(s.body, /nubos-pilot State/);
+});
+
+test('R2: writeState(next) + readState() round-trip preserves frontmatter (v2)', () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  const cur = state.readState(root);
+  const next = {
+    ...cur,
+    frontmatter: { ...cur.frontmatter, current_phase: 42 },
+  };
+  state.writeState(next, root);
+  const back = state.readState(root);
+  assert.equal(back.frontmatter.current_phase, 42);
+  assert.equal(back.frontmatter.schema_version, 2);
+  assert.equal(back.frontmatter.current_plan, '02-02');
+});
+
+test('R3: write then re-read reproduces identical state (stable round-trip)', () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  const first = state.readState(root);
+  state.writeState(first, root);
+  const afterWrite = fs.readFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), 'utf-8');
+  const second = state.readState(root);
+  state.writeState(second, root);
+  const afterWrite2 = fs.readFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), 'utf-8');
+  assert.equal(afterWrite, afterWrite2, 'serialize(parse(serialize(parse(x)))) is stable');
+});
+
+test('R4: parseState on input without frontmatter throws schema-version-mismatch', () => {
+  const root = makeSandbox('no frontmatter here just body text\n');
+  assert.throws(
+    () => state.readState(root),
+    (err) => err && err.code === 'schema-version-mismatch',
+  );
+});
+
+test('R5: parseState on unsupported schema_version (e.g. 3) throws schema-version-mismatch with supported list', () => {
+  const bad =
+    '---\n' +
+    'schema_version: 3\n' +
+    'current_phase: null\n' +
+    'current_plan: null\n' +
+    'last_updated: 2026-04-14T00:00:00Z\n' +
+    '---\n\nbody\n';
+  const root = makeSandbox(bad);
+  assert.throws(
+    () => state.readState(root),
+    (err) => {
+      return err
+        && err.code === 'schema-version-mismatch'
+        && err.details
+        && err.details.got === 3
+        && Array.isArray(err.details.supported)
+        && err.details.supported.includes(1)
+        && err.details.supported.includes(2);
+    },
+  );
+});
+
+test('R5b: parseState accepts schema_version:2 natively (pass-through, no migration)', () => {
+  const v2 =
+    '---\n' +
+    'schema_version: 2\n' +
+    'milestone: null\n' +
+    'milestone_name: null\n' +
+    'current_phase: 3\n' +
+    'current_plan: 03-04\n' +
+    'current_task: null\n' +
+    'last_updated: "2026-04-15T00:00:00Z"\n' +
+    'progress:\n' +
+    '  total_phases: 10\n' +
+    '  completed_phases: 2\n' +
+    '  total_plans: 12\n' +
+    '  completed_plans: 6\n' +
+    '  percent: 50\n' +
+    'session:\n' +
+    '  stopped_at: null\n' +
+    '  resume_file: null\n' +
+    '  last_activity: "2026-04-15T00:00:00Z"\n' +
+    '---\n\nbody\n';
+  const root = makeSandbox(v2);
+  const s = state.readState(root);
+  assert.equal(s.frontmatter.schema_version, 2);
+  assert.equal(s.frontmatter.current_phase, 3);
+  assert.equal(s.frontmatter.current_plan, '03-04');
+  assert.equal(s.frontmatter.progress.total_phases, 10);
+  assert.equal(s.frontmatter.progress.percent, 50);
+  assert.equal(s.frontmatter.session.last_activity, '2026-04-15T00:00:00Z');
+});
+
+test('R5c: nested progress/session serialize as block and round-trip losslessly', () => {
+  const v2 =
+    '---\n' +
+    'schema_version: 2\n' +
+    'current_phase: 4\n' +
+    'current_plan: 04-01\n' +
+    'current_task: 04-01-T03\n' +
+    'last_updated: "2026-04-15T00:00:00Z"\n' +
+    'progress:\n' +
+    '  total_phases: 10\n' +
+    '  completed_phases: 3\n' +
+    '  total_plans: 13\n' +
+    '  completed_plans: 10\n' +
+    '  percent: 77\n' +
+    'session:\n' +
+    '  stopped_at: "mid-plan"\n' +
+    '  resume_file: .planning/phases/04-base/04-01-PLAN.md\n' +
+    '  last_activity: "2026-04-15T00:00:00Z"\n' +
+    '---\n\nbody\n';
+  const root = makeSandbox(v2);
+  const first = state.readState(root);
+  state.writeState(first, root);
+  const after = fs.readFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), 'utf-8');
+
+  assert.match(after, /\nprogress:\n  total_phases: 10\n/);
+  assert.match(after, /\nsession:\n  stopped_at: /);
+  const back = state.readState(root);
+  assert.equal(back.frontmatter.progress.completed_plans, 10);
+  assert.equal(back.frontmatter.progress.percent, 77);
+  assert.equal(back.frontmatter.session.resume_file, '.planning/phases/04-base/04-01-PLAN.md');
+});
+
+test('R6: frontmatter scalar types — number / string / null / quoted-string (v1 migrates to v2)', () => {
+  const raw =
+    '---\n' +
+    'schema_version: 1\n' +
+    'current_phase: 7\n' +
+    'current_plan: null\n' +
+    'last_updated: "2026-04-14T00:00:00Z"\n' +
+    '---\n\nbody\n';
+  const root = makeSandbox(raw);
+  const s = state.readState(root);
+  assert.strictEqual(s.frontmatter.schema_version, 2);
+  assert.strictEqual(s.frontmatter.current_phase, 7);
+  assert.strictEqual(s.frontmatter.current_plan, null);
+  assert.strictEqual(s.frontmatter.last_updated, '2026-04-14T00:00:00Z');
+});
+
+test('R7: CANONICAL_KEYS exports the full Phase-4 v2 key list', () => {
+  for (const k of ['schema_version', 'milestone', 'milestone_name', 'current_phase', 'current_plan', 'current_task', 'last_updated', 'progress', 'session']) {
+    assert.ok(state.CANONICAL_KEYS.includes(k), `missing ${k}`);
+  }
+});
+
+test('PR1: statePath(sandboxRoot) equals <root>/.nubos-pilot/STATE.md', () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  const p = state.statePath(root);
+  assert.equal(p, path.join(root, '.nubos-pilot', 'STATE.md'));
+});
+
+test('PR2: readState with no .nubos-pilot ancestor surfaces not-in-project error', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-noproj-'));
+  sandboxes.push(root);
+  assert.throws(
+    () => state.readState(root),
+    (err) => err && err.code === 'not-in-project',
+  );
+});
+
+test('C1: two concurrent mutateState calls — final STATE is one of the two writes, atomic', async () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  let counter = 0;
+  const mutatorA = (s) => {
+    counter++;
+    return { ...s, frontmatter: { ...s.frontmatter, current_phase: 10, last_updated: '2030-01-01T00:00:00Z' } };
+  };
+  const mutatorB = (s) => {
+    counter++;
+    return { ...s, frontmatter: { ...s.frontmatter, current_phase: 20, last_updated: '2030-02-02T00:00:00Z' } };
+  };
+  await Promise.all([
+    Promise.resolve().then(() => state.mutateState(mutatorA, root)),
+    Promise.resolve().then(() => state.mutateState(mutatorB, root)),
+  ]);
+  assert.equal(counter, 2, 'both mutators ran exactly once');
+  const final = state.readState(root);
+  assert.ok(
+    final.frontmatter.current_phase === 10 || final.frontmatter.current_phase === 20,
+    'final phase is one of the two writes (not mixed)',
+  );
+  if (final.frontmatter.current_phase === 10) {
+    assert.equal(final.frontmatter.last_updated, '2030-01-01T00:00:00Z', 'timestamp matches chosen phase (A)');
+  } else {
+    assert.equal(final.frontmatter.last_updated, '2030-02-02T00:00:00Z', 'timestamp matches chosen phase (B)');
+  }
+});
+
+test('C2: 10-iteration stress — every iteration passes C1 assertions', async () => {
+  for (let i = 0; i < 10; i++) {
+    const root = makeSandbox(CANONICAL_STATE_MD);
+    let counter = 0;
+    const a = (s) => { counter++; return { ...s, frontmatter: { ...s.frontmatter, current_phase: 10, last_updated: '2030-01-01T00:00:00Z' } }; };
+    const b = (s) => { counter++; return { ...s, frontmatter: { ...s.frontmatter, current_phase: 20, last_updated: '2030-02-02T00:00:00Z' } }; };
+    await Promise.all([
+      Promise.resolve().then(() => state.mutateState(a, root)),
+      Promise.resolve().then(() => state.mutateState(b, root)),
+    ]);
+    assert.equal(counter, 2, `iteration ${i}: both mutators ran`);
+    const f = state.readState(root);
+    assert.ok(f.frontmatter.current_phase === 10 || f.frontmatter.current_phase === 20, `iteration ${i}: clean one-of-two`);
+  }
+});
+
+test('C3: mutateState releases lock when mutator throws (subsequent writeState succeeds)', () => {
+  const root = makeSandbox(CANONICAL_STATE_MD);
+  const throwing = () => { throw new Error('boom'); };
+  assert.throws(() => state.mutateState(throwing, root), /boom/);
+  const start = Date.now();
+  const next = { ...state.readState(root), frontmatter: { schema_version: 1, current_phase: 99, current_plan: 'x', last_updated: '2030-03-03T00:00:00Z' } };
+  state.writeState(next, root);
+  const elapsed = Date.now() - start;
+  assert.ok(elapsed < 500, `writeState completed in ${elapsed}ms (lock was released)`);
+  const back = state.readState(root);
+  assert.equal(back.frontmatter.current_phase, 99);
+});

package/lib/surface-audit.test.cjs

@@ -0,0 +1,46 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LIB_DIR = path.resolve(__dirname);
+const BAN_RE = /require\s*\(\s*['"](node:)?child_process['"]\s*\)|from\s+['"](node:)?child_process['"]/;
+const SUBPROCESS_IDENTIFIERS = /\b(execSync|execFileSync|spawnSync|spawn|exec|execFile|fork)\s*\(/;
+
+const SUBPROCESS_WHITELIST = new Set(['git.cjs']);
+
+function libFiles() {
+  return fs
+    .readdirSync(LIB_DIR)
+    .filter(
+      (f) =>
+        f.endsWith('.cjs') &&
+        !f.endsWith('.test.cjs') &&
+        f !== 'surface-audit.test.cjs' &&
+        !SUBPROCESS_WHITELIST.has(f)
+    )
+    .map((f) => path.join(LIB_DIR, f));
+}
+
+test('SC 4 / ADR-0001: no lib/*.cjs imports child_process', () => {
+  const files = libFiles();
+  assert.ok(files.length >= 2, `expected >=2 lib/*.cjs files, scanned ${files.length}`);
+  for (const file of files) {
+    const src = fs.readFileSync(file, 'utf-8');
+    assert.ok(
+      !BAN_RE.test(src),
+      `SC 4 violation in ${path.relative(LIB_DIR, file)}: lib/ must NOT import child_process (see ADR-0001 / CONTEXT D-14).`
+    );
+  }
+});
+
+test('SC 4 (defense-in-depth): no subprocess identifiers in lib/*.cjs', () => {
+  const files = libFiles();
+  for (const file of files) {
+    const src = fs.readFileSync(file, 'utf-8');
+    assert.ok(
+      !SUBPROCESS_IDENTIFIERS.test(src),
+      `SC 4 violation in ${path.relative(LIB_DIR, file)}: lib/ must not call subprocess APIs (see ADR-0001 / CONTEXT D-14).`
+    );
+  }
+});