@haposoft/cafekit 0.16.2 → 0.16.4

package/README.md

@@ -2,7 +2,7 @@
 
 > Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
-[![Version](https://img.shields.io/badge/version-0.16.2-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.4-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Native-orange.svg)](https://claude.ai/code)
 [![Codex%20CLI](https://img.shields.io/badge/Codex%20CLI-Native-111111.svg)](https://developers.openai.com/codex)
@@ -126,9 +126,12 @@ AGENTS.md
 CafeKit owns only its marked block in root `AGENTS.md`. Codex discovers skills
 and custom agents natively after the repository is trusted; no project
 `config.toml` is generated. Review and trust project hooks with `/hooks`.
-Installed hook commands are bound to the canonical project path on every platform,
-so they need no Git repository, stay correct for a project nested inside a larger
-repository, and remain stable when a session starts in a subdirectory.
+Installed Codex hook commands are bound to the canonical project path, so they need no
+Git repository, stay correct for a project nested inside a larger repository, and remain
+stable when a session starts in a subdirectory. They also carry a PATH floor pointing at
+the Node.js that installed them, so a host launched from the macOS GUI — whose children
+inherit only `/usr/bin:/bin:/usr/sbin:/sbin` — can still find the interpreter. The floor
+is appended, so a version manager's current Node still wins in a normal terminal.
 CafeKit uses Codex's native status and usage UI instead of installing the
 Claude statusline.
 

package/bin/__tests__/codex-hooks.test.js

@@ -782,6 +782,41 @@ test('Codex process-v3 Receipt command must match the exact Verification Plan co
   });
 });
 
+test('Codex recorded active feature turns the identity block into receipt validation', () => {
+  // Issue #79 end to end on this runtime. Two legacy packets both claiming closeout make
+  // the gate answer a missing-receipt violation with an identity complaint whose stated
+  // remedy nothing wrote. Naming the feature resolves it and the violation surfaces.
+  inHookFixture((root, hooks) => {
+    for (const name of ['alpha', 'beta']) {
+      const feature = path.join(root, 'specs', name);
+      fs.mkdirSync(path.join(feature, 'tasks'), { recursive: true });
+      fs.writeFileSync(path.join(feature, 'spec.json'), `${JSON.stringify({
+        feature_name: name,
+        status: 'done',
+        current_phase: 'closeout',
+        task_registry: { 'tasks/task-R0-01-x.md': { status: 'done', completed_at: '2026-01-01T00:00:00.000Z' } },
+      }, null, 2)}\n`);
+      fs.writeFileSync(path.join(feature, 'tasks', 'task-R0-01-x.md'), '# Task\n\nStatus: done\n');
+    }
+    const payload = { cwd: root, session_id: 'session-a', hook_event_name: 'Stop', stop_hook_active: false };
+
+    const blocked = runHook(path.join(hooks, 'spec-gate.cjs'), root, payload);
+    assert.equal(blocked.status, 0, blocked.stderr);
+    assert.match(JSON.parse(blocked.stdout).reason, /multiple active specs detected/);
+
+    const shared = path.join(root, 'specs', '_shared');
+    fs.mkdirSync(shared, { recursive: true });
+    fs.writeFileSync(path.join(shared, 'active-feature.json'), '{"featureName": "beta"}\n');
+
+    const resolved = runHook(path.join(hooks, 'spec-gate.cjs'), root, payload);
+    assert.equal(resolved.status, 0, resolved.stderr);
+    const reason = JSON.parse(resolved.stdout).reason;
+    assert.doesNotMatch(reason, /multiple active specs/, 'the recorded feature must resolve it');
+    assert.match(reason, /lack a verification receipt/, 'the gate must now reach receipt validation');
+    assert.match(reason, /specs\/beta\//, 'and validate the named feature, not a sibling');
+  });
+});
+
 test('Codex process-v3 Stop ignores a completed packet when one packet remains active', () => {
   inHookFixture((root, hooks) => {
     const completed = path.join(root, 'specs', 'auth');

package/bin/__tests__/codex-native.test.js

@@ -2035,10 +2035,13 @@ test('Codex Windows hook launchers stay project-bound without Git from nested cw
   });
 });
 
-// Run an installed POSIX launcher with no PATH at all, so neither `git` nor a `node` on
-// PATH can rescue it. The launcher must already carry everything it needs.
-function runPosixLauncher(command, cwd) {
-  return spawnSync(command.replace(/^node /, `"${process.execPath}" `), {
+// Run an installed POSIX launcher verbatim under the environment a macOS GUI host hands
+// its children: no `git`, and no `node` on PATH. Nothing here rewrites the command, so a
+// launcher that cannot find its own interpreter fails the way it fails in the wild.
+const GUI_PATH = '/usr/bin:/bin:/usr/sbin:/sbin';
+
+function runPosixLauncher(command, cwd, pathValue = GUI_PATH) {
+  return spawnSync(command, {
     cwd,
     encoding: 'utf8',
     input: JSON.stringify({
@@ -2047,7 +2050,7 @@ function runPosixLauncher(command, cwd) {
       hook_event_name: 'SessionStart',
       source: 'startup'
     }),
-    env: { ...process.env, PATH: '' },
+    env: { PATH: pathValue, HOME: os.homedir() },
     shell: true
   });
 }
@@ -2076,13 +2079,13 @@ test('Codex POSIX hook launchers run without Git and outside the repository root
     for (const projectRoot of [plain, nested]) {
       const { config, command } = sessionLauncher(projectRoot);
       for (const { handler } of allHookLaunchers(config)) {
-        // `node '<single-quoted absolute path>'` and nothing else. Inside single quotes
-        // the shell expands nothing, so a project path may safely contain $, a backtick,
-        // or the word git — this fixture's own path contains it.
+        // A PATH floor, then `node`, then one single-quoted absolute path. Inside single
+        // quotes the shell expands nothing, so a project path may safely contain $, a
+        // backtick, or the word git — this fixture's own path contains it.
         assert.match(
           handler.command,
-          /^node '(?:[^']|'\\'')+'$/,
-          `launcher must be a plain quoted path: ${handler.command}`
+          /^PATH="\$PATH"(?::'(?:[^']|'\\'')+')+ node '(?:[^']|'\\'')+'$/,
+          `launcher must carry a PATH floor and a quoted path: ${handler.command}`
         );
         assert.doesNotMatch(handler.command, /rev-parse/, `launcher must not consult Git: ${handler.command}`);
         assert.ok(
@@ -2097,38 +2100,49 @@ test('Codex POSIX hook launchers run without Git and outside the repository root
   });
 });
 
-test('a reinstall repairs Codex launchers that resolved their path through Git', () => {
-  inTempProject((root) => {
-    assert.equal(install(root).status, 0);
-    const configPath = path.join(root, '.codex', 'hooks.json');
-
-    // Exactly what an installer before 0.16.2 wrote.
-    const downgraded = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    for (const { handler } of allHookLaunchers(downgraded)) {
-      const script = path.basename(handler.command.replace(/'$/, ''));
-      handler.command = `node "$(git rev-parse --show-toplevel)/.codex/hooks/${script}"`;
-    }
-    const foreign = { type: 'command', command: 'node "$(git rev-parse --show-toplevel)/tools/mine.cjs"' };
-    downgraded.hooks.SessionStart[0].hooks.push(foreign);
-    fs.writeFileSync(configPath, `${JSON.stringify(downgraded, null, 2)}\n`);
-
-    const again = install(root);
-    assert.equal(again.status, 0, again.stderr);
-    assert.match(again.stdout, /repaired \d+ launcher/, 'the repair must be reported, not silent');
+// A reinstall treats an already-registered script as the user's placement, so a launcher
+// an older installer wrote would otherwise keep its broken command forever.
+for (const [label, legacyCommand] of [
+  ['resolved their path through Git', (script) => `node "$(git rev-parse --show-toplevel)/.codex/hooks/${script}"`],
+  ['looked for node on PATH', (script, root) => `node '${path.join(fs.realpathSync(root), '.codex', 'hooks', script)}'`],
+]) {
+  test(`a reinstall rebinds Codex launchers that ${label}`, () => {
+    inTempProject((root) => {
+      assert.equal(install(root).status, 0);
+      const configPath = path.join(root, '.codex', 'hooks.json');
+
+      const downgraded = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      for (const { handler } of allHookLaunchers(downgraded)) {
+        handler.command = legacyCommand(path.basename(handler.command.replace(/'$/, '')), root);
+      }
+      // A hook the user wrote, in the same shape CafeKit used to emit, must never be
+      // rewritten: it points somewhere else entirely.
+      const foreign = { type: 'command', command: 'node "$(git rev-parse --show-toplevel)/tools/mine.cjs"' };
+      downgraded.hooks.SessionStart[0].hooks.push(foreign);
+      fs.writeFileSync(configPath, `${JSON.stringify(downgraded, null, 2)}\n`);
+
+      const again = install(root);
+      assert.equal(again.status, 0, again.stderr);
+      assert.match(again.stdout, /rebound \d+ launcher/, 'the rebind must be reported, not silent');
+
+      const { config, command } = sessionLauncher(root);
+      const commands = allHookLaunchers(config).map(({ handler }) => handler.command);
+      assert.ok(commands.includes(foreign.command), 'a foreign hook must survive untouched');
+      assert.equal(
+        commands.filter((entry) => !entry.startsWith('PATH=')).length,
+        1,
+        'every CafeKit launcher must be rebound, leaving only the foreign one'
+      );
+      const launched = runPosixLauncher(command, root);
+      assert.equal(launched.status, 0, launched.stderr);
+      assert.match(launched.stdout, /Session startup\./);
 
-    const { config, command } = sessionLauncher(root);
-    const commands = allHookLaunchers(config).map(({ handler }) => handler.command);
-    assert.equal(
-      commands.filter((entry) => /rev-parse/.test(entry)).length,
-      1,
-      'only the hook CafeKit did not author may keep its own command'
-    );
-    assert.ok(commands.includes(foreign.command), 'a foreign hook must survive untouched');
-    const launched = runPosixLauncher(command, root);
-    assert.equal(launched.status, 0, launched.stderr);
-    assert.match(launched.stdout, /Session startup\./);
+      // Running the installer again must change nothing.
+      const third = install(root);
+      assert.doesNotMatch(third.stdout, /rebound \d+ launcher/, 'rebinding must be idempotent');
+    });
   });
-});
+}
 
 test('Codex installed Specs and spec-maker reject adaptive coverage mutations', () => {
   inTempProject((root) => {

package/bin/__tests__/package-inventory.test.js

@@ -2162,6 +2162,10 @@ process.stdout.write(JSON.stringify({ ok: result.ok, active: result.active, reas
   });
 }
 
+// `assertInstalledCompletion` leaves this fixture claiming closeout, which is what makes
+// it the one packet closeout approval resolves among the scaffolded siblings.
+const CLOSING_FIXTURE = 'compact-installed';
+
 function assertInstalledResolution(paths, root, platform, explicitFeature) {
   const code = `
 const checker = require(process.argv[1]); const resolver = require(process.argv[2]);
@@ -2170,13 +2174,45 @@ const base = { projectRoot: root, runtime: {}, payload: {} };
 if (platform === 'claude') base.resolver = resolver;
 const explicit = checker.resolveCandidate({ ...base, payload: { featureName: feature } });
 const ambiguous = checker.resolveCandidate(base);
-process.stdout.write(JSON.stringify({ explicit: explicit && explicit.featureName, error: ambiguous && ambiguous.error, candidates: ambiguous && ambiguous.candidates }));`;
-  const result = spawnSync(process.execPath, ['-e', code, paths.completion, paths.resolver, root, platform, explicitFeature], { cwd: root, encoding: 'utf8' });
-  assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
-  const resolution = JSON.parse(result.stdout);
-  assert.equal(resolution.explicit, explicitFeature);
-  assert.equal(resolution.error, 'multiple_persisted');
-  assert.ok(resolution.candidates.length >= 2);
+process.stdout.write(JSON.stringify({ explicit: explicit && explicit.featureName, isNull: ambiguous === null, name: ambiguous && ambiguous.featureName, error: ambiguous && ambiguous.error, candidates: ambiguous && ambiguous.candidates }));`;
+  const run = () => {
+    const result = spawnSync(process.execPath, ['-e', code, paths.completion, paths.resolver, root, platform, explicitFeature], { cwd: root, encoding: 'utf8' });
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    return JSON.parse(result.stdout);
+  };
+
+  // Contract change: closeout approval counts only packets actually claiming closeout.
+  // This used to assert `multiple_persisted` from these fixtures, which pinned the
+  // over-strict behaviour issue #79 reports. `assertInstalledCompletion` above drove
+  // `compact-installed` to closeout, so exactly one of the three is claiming it; the
+  // scaffolded siblings are not rivals and must not block the approval.
+  const narrowed = run();
+  assert.equal(narrowed.explicit, explicitFeature);
+  assert.equal(narrowed.name, CLOSING_FIXTURE, `the one packet claiming closeout must resolve: ${JSON.stringify(narrowed)}`);
+  assert.equal(narrowed.error, undefined);
+
+  // Genuine ambiguity still blocks, and the installed copy must prove it rather than
+  // being assumed from the source tree this test deliberately deleted.
+  const closing = ['closing-a-installed', 'closing-b-installed'];
+  for (const name of closing) {
+    const dir = path.join(root, 'specs', name);
+    fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'spec.json'), `${JSON.stringify({
+      feature_name: name,
+      status: 'done',
+      current_phase: 'closeout',
+      task_registry: { 'tasks/task-R0-01-x.md': { status: 'done', completed_at: '2026-01-01T00:00:00.000Z' } },
+    }, null, 2)}\n`);
+    fs.writeFileSync(path.join(dir, 'tasks', 'task-R0-01-x.md'), '# Task\n\nStatus: done\n');
+  }
+  try {
+    const ambiguous = run();
+    assert.equal(ambiguous.explicit, explicitFeature, 'an explicit target still wins');
+    assert.equal(ambiguous.error, 'multiple_persisted');
+    assert.deepEqual([...ambiguous.candidates].sort(), [...closing, CLOSING_FIXTURE].sort(), 'only claiming packets are named');
+  } finally {
+    for (const name of closing) fs.rmSync(path.join(root, 'specs', name), { recursive: true, force: true });
+  }
 }
 
 function assertStrictSimulatedHandlerGuardrail(paths, root, fixture) {

package/bin/__tests__/spec-narrowing.test.js

@@ -0,0 +1,381 @@
+'use strict';
+
+// Two Stop hooks ask two different questions about the same repository, so they narrow an
+// ambiguous scan differently. The gate asks which packet still has unfinished work, so it
+// can validate that packet's receipts. Closeout approval asks which packet is claiming
+// closeout, so it can demand a one-time approval for it. Counting finished history as
+// ambiguity is what left a repository of accumulated features permanently blocked, with
+// the documented escape — an explicit feature target — unavailable.
+
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+const RESOLVER = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-resolver.cjs'));
+
+function withProject(run) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-narrowing-'));
+  try {
+    return run(fs.realpathSync(dir));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** A legacy packet: spec.json plus nested tasks, the shape issue #79 reports. */
+function legacyPacket(root, name, { status, phase, taskStatus = 'done' } = {}) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+  const spec = { feature_name: name, task_registry: { 'tasks/task-R0-01-x.md': { status: taskStatus, completed_at: '2026-01-01T00:00:00.000Z' } } };
+  if (status !== undefined) spec.status = status;
+  if (phase !== undefined) spec.current_phase = phase;
+  fs.writeFileSync(path.join(dir, 'spec.json'), `${JSON.stringify(spec, null, 2)}\n`);
+  fs.writeFileSync(path.join(dir, 'tasks', 'task-R0-01-x.md'), `# Task\n\nStatus: ${taskStatus}\n`);
+}
+
+/** A process-first packet: plan.md plus one flat task file. */
+function workflowPacket(root, name, taskStatus) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'plan.md'), '# Plan\nSpecs-Contract: process-first-ready-v1\n');
+  fs.writeFileSync(
+    path.join(dir, 'task-01-x.md'),
+    `# Task 01\n\nStatus: ${taskStatus}\n\n## Dependencies\n- none\n`
+  );
+}
+
+function recordActiveFeature(root, contents) {
+  const dir = path.join(root, 'specs', '_shared');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'active-feature.json'), contents);
+}
+
+function gateResolution(root) {
+  const resolved = RESOLVER.resolveWorkflowCandidate({
+    projectRoot: root, runtime: {}, target: null, includeCompleted: true,
+  });
+  return RESOLVER.refineWorkflowGateResolution(resolved);
+}
+
+// ── The gate: which packet still has work ───────────────────────────────────────────
+
+test('a legacy repository resolves its one unfinished packet', () => {
+  withProject((root) => {
+    for (let index = 1; index <= 3; index += 1) {
+      legacyPacket(root, `done-${index}`, { status: 'done', phase: 'closeout' });
+    }
+    legacyPacket(root, 'active-now', { status: 'in_progress', phase: 'execution', taskStatus: 'pending' });
+    const resolved = gateResolution(root);
+    assert.equal(resolved.error, undefined, `expected a resolution, got ${resolved.error}`);
+    assert.equal(resolved.featureName, 'active-now');
+  });
+});
+
+test('a legacy registry written with the older vocabulary counts as finished', () => {
+  // Issue #79's repository was upgraded from an older release whose task_registry used
+  // `completed`. Today's validator allows only pending/in_progress/blocked/done, so
+  // narrowing read those packets as unfinished and the block survived the fix that was
+  // supposed to clear it. Measured on the reported shape before this: 18 candidates.
+  for (const status of ['done', 'completed', 'complete']) {
+    withProject((root) => {
+      for (let index = 1; index <= 3; index += 1) {
+        legacyPacket(root, `history-${index}`, { taskStatus: status });
+      }
+      legacyPacket(root, 'active-now', { status: 'in_progress', phase: 'execution', taskStatus: 'pending' });
+      assert.equal(gateResolution(root).featureName, 'active-now', `task status ${status} must read as finished`);
+    });
+  }
+});
+
+test('a process-first packet keeps the strict task vocabulary', () => {
+  // The widened set is legacy-only. A process-first task saying `completed` is malformed,
+  // not finished, and must not be silently read as done.
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'odd', 'completed');
+    const resolved = gateResolution(root);
+    assert.notEqual(resolved.layoutKind, 'process-v3-completed-set', 'an invalid status is not done');
+  });
+});
+
+test('a legacy candidate never reaches the bulk branch', () => {
+  // The bulk branch exits before the semantic-digest, FLASH_UNVERIFIED, feature-receipt
+  // and completion-policy layers, so a legacy packet reaching it would turn a block into
+  // a silent pass. With every legacy packet finished there is nothing to narrow to, and
+  // the existing ambiguity must stand rather than the set being audited.
+  withProject((root) => {
+    legacyPacket(root, 'done-1', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'done-2', { status: 'done', phase: 'closeout' });
+    const resolved = gateResolution(root);
+    assert.notEqual(resolved.layoutKind, 'process-v3-completed-set');
+    assert.ok(resolved.error, 'an all-legacy finished set must stay ambiguous');
+  });
+});
+
+test('a process-first set still reaches the bulk branch', () => {
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'done-2', 'done');
+    assert.equal(gateResolution(root).layoutKind, 'process-v3-completed-set');
+  });
+});
+
+test('one unfinished process-first packet still narrows', () => {
+  withProject((root) => {
+    workflowPacket(root, 'done-1', 'done');
+    workflowPacket(root, 'active-now', 'pending');
+    assert.equal(gateResolution(root).featureName, 'active-now');
+  });
+});
+
+// ── Closeout approval: which packet is claiming closeout ────────────────────────────
+
+test('one packet claiming closeout among finished ones resolves', () => {
+  withProject((root) => {
+    legacyPacket(root, 'shipped', { status: 'in_progress', phase: 'execution', taskStatus: 'done' });
+    legacyPacket(root, 'closing', { status: 'done', phase: 'closeout' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, undefined);
+    assert.equal(resolved.featureName, 'closing');
+  });
+});
+
+test('a lone finished packet still resolves', () => {
+  // Four existing cases depend on this: closeout approval is claimed against a finished
+  // spec, so a single packet must resolve whatever its status.
+  for (const status of ['done', 'completed']) {
+    withProject((root) => {
+      legacyPacket(root, 'only', { status });
+      const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+      assert.equal(resolved.featureName, 'only', `status ${status} must still resolve`);
+    });
+  }
+});
+
+test('a lone packet mid-execution still resolves', () => {
+  // The closeout filter would drop this one, so the single-candidate return above it is
+  // what keeps a repository holding exactly one in-flight packet resolvable. Without it
+  // the hook goes silent for that repository instead of checking the packet.
+  withProject((root) => {
+    legacyPacket(root, 'solo', { status: 'in_progress', phase: 'implementation', taskStatus: 'pending' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.featureName, 'solo');
+  });
+});
+
+test('no packet claiming closeout resolves to null', () => {
+  // null means nothing is in flight and the hook stays silent; an error would keep
+  // blocking a repository where no closeout is being claimed at all.
+  withProject((root) => {
+    legacyPacket(root, 'a', { status: 'in_progress', phase: 'execution' });
+    legacyPacket(root, 'b', { status: 'in_progress', phase: 'execution' });
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }), null);
+  });
+});
+
+test('several packets claiming closeout stay ambiguous and name only those', () => {
+  withProject((root) => {
+    legacyPacket(root, 'closing-a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'closing-b', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'working', { status: 'in_progress', phase: 'execution' });
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, 'multiple_persisted');
+    assert.deepEqual(resolved.candidates, ['closing-a', 'closing-b']);
+  });
+});
+
+test('codex resolveCandidate agrees with the shared resolver', () => {
+  // Codex kept its own candidate count, reachable because spec-utils did not export the
+  // shared function. A Claude-only change would leave every Codex turn blocked.
+  const codexCheck = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/completion-authority-check.cjs'));
+  const utils = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-utils.cjs'));
+  assert.equal(typeof utils.resolvePersistedSpec, 'function', 'the wrapper must be exported');
+  withProject((root) => {
+    legacyPacket(root, 'shipped', { status: 'in_progress', phase: 'execution', taskStatus: 'done' });
+    legacyPacket(root, 'closing', { status: 'done', phase: 'closeout' });
+    const shared = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    const viaCodex = codexCheck.resolveCandidate({ projectRoot: root, runtime: {}, payload: {} });
+    assert.equal(viaCodex.featureName, shared.featureName);
+  });
+});
+
+// ── The recorded active feature: the escape the block told users to take ────────────
+
+test('a recorded active feature resolves two packets claiming closeout', () => {
+  withProject((root) => {
+    legacyPacket(root, 'closing-a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'closing-b', { status: 'done', phase: 'closeout' });
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).error, 'multiple_persisted');
+    recordActiveFeature(root, '{"featureName": "closing-b"}\n');
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.equal(resolved.error, undefined, `expected a resolution, got ${resolved.error}`);
+    assert.equal(resolved.featureName, 'closing-b');
+  });
+});
+
+test('a payload target beats the recorded file', () => {
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'beta', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "alpha"}\n');
+    const resolved = RESOLVER.resolvePersistedSpec({
+      projectRoot: root, runtime: {}, target: { featureName: 'beta' },
+    });
+    assert.equal(resolved.featureName, 'beta', 'the caller must win');
+  });
+});
+
+test('a blank recorded feature is ignored rather than malformed', () => {
+  // explicitTargetValue turns a blank into null, and a null target becomes an
+  // explicit_malformed error that blocks. The reader must return null instead, or every
+  // project holding a stray file would be blocked by the very escape hatch.
+  for (const contents of ['{"featureName": "   "}', '{"featureName": 42}', '{}', 'not json', '[]']) {
+    withProject((root) => {
+      legacyPacket(root, 'only', { status: 'done', phase: 'closeout' });
+      recordActiveFeature(root, contents);
+      assert.equal(
+        RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null,
+        `${contents} must be invisible`
+      );
+      assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).featureName, 'only');
+    });
+  }
+});
+
+test('a recorded feature cannot escape the specs root', () => {
+  // The reader adds no trust: the value goes through the resolver's existing checks.
+  withProject((root) => {
+    legacyPacket(root, 'a', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'b', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "../../etc"}');
+    const resolved = RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} });
+    assert.ok(resolved.error, 'an escaping name must produce the existing error, not a resolution');
+    assert.notEqual(resolved.featureName, '../../etc');
+  });
+});
+
+test('a symlinked recorded feature is refused', () => {
+  // The file is read from inside the project, so a symlink could name a target the
+  // project does not contain. The repository already refuses symlinked runtime
+  // dependencies elsewhere; this reader follows the same rule.
+  withProject((root) => {
+    legacyPacket(root, 'only', { status: 'done', phase: 'closeout' });
+    const outside = path.join(root, 'outside.json');
+    fs.writeFileSync(outside, '{"featureName": "only"}');
+    const dir = path.join(root, 'specs', '_shared');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(outside, path.join(dir, 'active-feature.json'));
+    assert.equal(RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null);
+  });
+});
+
+test('an absent file leaves every project exactly as it was', () => {
+  withProject((root) => {
+    legacyPacket(root, 'only', { status: 'in_progress', phase: 'execution' });
+    assert.equal(RESOLVER.readActiveFeatureTarget({ projectRoot: root, runtime: {} }), null);
+    assert.equal(RESOLVER.resolvePersistedSpec({ projectRoot: root, runtime: {} }).featureName, 'only');
+  });
+});
+
+test('the approval prompt names its feature', () => {
+  // Without the name a user types a bare nonce and cannot tell which closeout they are
+  // approving, while the recorded file can influence which packet resolves.
+  for (const runtimeDir of ['claude', 'codex']) {
+    const hook = fs.readFileSync(
+      path.join(PACKAGE_ROOT, 'src', runtimeDir, 'hooks', 'completion-authority.cjs'), 'utf8'
+    );
+    assert.match(hook, /const feature = result\.candidate\?\.featureName;/, `${runtimeDir} must read the name`);
+    assert.match(hook, /closeout approval is required for \$\{feature \?/, `${runtimeDir} must print it`);
+  }
+});
+
+test('the shared workflow resolver ignores the recorded file', () => {
+  // resolveWorkflowCandidate has five consumers, including spec-state.cjs and
+  // precompact.cjs. Reading the file inside it would retarget hooks that never asked,
+  // so the two gates apply it at their own call sites instead. Neither of those suites
+  // writes the file, so nothing else pins this containment.
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    legacyPacket(root, 'beta', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "beta"}');
+    const resolved = RESOLVER.resolveWorkflowCandidate({
+      projectRoot: root, runtime: {}, target: null, includeCompleted: true,
+    });
+    assert.ok(resolved.error, 'the shared resolver must stay ambiguous on its own');
+    assert.notEqual(resolved.featureName, 'beta');
+  });
+});
+
+test('the codex gate consults the file only after its payload', () => {
+  const utils = require(path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-utils.cjs'));
+  assert.equal(typeof utils.readActiveFeatureTarget, 'function', 'the wrapper must be exported');
+  assert.equal(typeof utils.extractExplicitTarget, 'function', 'the gate needs the payload extractor');
+  withProject((root) => {
+    legacyPacket(root, 'alpha', { status: 'done', phase: 'closeout' });
+    recordActiveFeature(root, '{"featureName": "alpha"}');
+    assert.deepEqual(
+      utils.extractExplicitTarget({ featureName: 'beta' }) || utils.readActiveFeatureTarget({ projectRoot: root, runtime: {} }),
+      { explicitFeature: 'beta' }
+    );
+    assert.deepEqual(
+      utils.extractExplicitTarget({}) || utils.readActiveFeatureTarget({ projectRoot: root, runtime: {} }),
+      { explicitFeature: 'alpha' }
+    );
+  });
+});
+
+// ── End to end: the block the report describes, and the escape from it ──────────────
+
+/** A git project the Stop gate will accept as a real project root. */
+function gitProject(run) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-gate-')));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+      ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    return run(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function runGate(hook, dir) {
+  const result = spawnSync(process.execPath, [path.join(PACKAGE_ROOT, hook)], {
+    input: JSON.stringify({
+      hook_event_name: 'Stop', session_id: 'test', transcript_path: '/tmp/t',
+      stop_hook_active: false, cwd: dir,
+    }),
+    // PROJECT_ROOT wins over cwd in the hook, so the host's own specs cannot leak in.
+    encoding: 'utf8', env: { ...process.env, PROJECT_ROOT: dir },
+  });
+  return (result.stdout || '').trim();
+}
+
+// The Codex gate resolves PROJECT_ROOT from its own installed location, so its end-to-end
+// twin lives in bin/__tests__/codex-hooks.test.js, which owns the installer fixture.
+for (const [runtimeName, hook] of [['claude', 'src/claude/hooks/spec-gate.cjs']]) {
+  test(`${runtimeName}: the recorded feature turns the identity block into receipt validation`, () => {
+    // This is issue #79 end to end. Ambiguity answers a missing-receipt violation with an
+    // identity complaint whose stated remedy nothing could supply; naming the feature
+    // makes the gate resolve it and report the violation that was there all along.
+    gitProject((dir) => {
+      legacyPacket(dir, 'alpha', { status: 'done', phase: 'closeout' });
+      legacyPacket(dir, 'beta', { status: 'done', phase: 'closeout' });
+
+      const blocked = runGate(hook, dir);
+      assert.match(blocked, /multiple active specs detected/, 'the reported block must reproduce');
+
+      recordActiveFeature(dir, '{"featureName": "beta"}\n');
+      const resolved = runGate(hook, dir);
+      assert.doesNotMatch(resolved, /multiple active specs/, 'the recorded feature must resolve it');
+      assert.match(resolved, /lack a verification receipt/, 'the gate must now reach receipt validation');
+      assert.match(resolved, /specs\/beta\//, 'and validate the named feature, not a sibling');
+    });
+  });
+}

package/bin/phases/codex-hooks.js

@@ -17,8 +17,22 @@ const { PLATFORMS } = require('../lib/context');
 
 const CODEX_SRC = path.join(__dirname, '../../src/codex');
 const HOOK_COMMAND_TEMPLATE = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
-// What an installer before 0.16.2 wrote for POSIX. Kept only to recognize and repair it.
-const LEGACY_GIT_COMMAND = /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
+// Exact shapes earlier installers wrote, kept only to recognize and upgrade them. Before
+// 0.16.2 the path came from Git; 0.16.2 fixed the path but still resolved `node` through
+// PATH. Matching the whole command keeps a hook the user wrote from ever being rewritten.
+const LEGACY_POSIX_COMMANDS = [
+  /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/,
+  /^node '(?:[^']|'\\'')*[/\\]hooks[/\\]([a-z0-9-]+\.cjs)'$/,
+];
+
+function legacyPosixScript(command) {
+  if (typeof command !== 'string') return null;
+  for (const pattern of LEGACY_POSIX_COMMANDS) {
+    const match = command.match(pattern);
+    if (match) return match[1];
+  }
+  return null;
+}
 
 /** The hook script a command runs, which is stable across installs and platforms. */
 function hookScript(command) {
@@ -46,8 +60,26 @@ function hookPathFor(script, projectRoot) {
  * directly. The literal `/hooks/<script>.cjs` segment must survive, because hookScript()
  * reads it as the identity that lets a reinstall recognize CafeKit's own entries.
  */
+/**
+ * Directories to fall back on when PATH carries no `node`.
+ *
+ * `process.execPath` is realpath-resolved, so under Homebrew or a version manager it names
+ * a versioned directory that disappears on the next node upgrade. The stable aliases are
+ * listed after it, and a directory that does not exist costs nothing in PATH.
+ */
+function nodeFallbackDirectories() {
+  const candidates = [path.dirname(process.execPath), '/usr/local/bin', '/opt/homebrew/bin'];
+  return [...new Set(candidates.filter(Boolean))];
+}
+
 function posixHookCommand(script, projectRoot) {
-  return `node ${shellQuote(hookPathFor(script, projectRoot))}`;
+  // `node` is resolved through PATH, and a host launched from the macOS GUI hands its
+  // children the minimal `/usr/bin:/bin:/usr/sbin:/sbin`. Node installed by Homebrew, nvm,
+  // fnm, or Volta is not on that list, so the shell answered 127 and the hook never
+  // started. The fallbacks are appended, never prepended, so a version manager's current
+  // node still wins in a normal terminal and these act only as the floor.
+  const fallbacks = nodeFallbackDirectories().map((dir) => `:${shellQuote(dir)}`).join('');
+  return `PATH="$PATH"${fallbacks} node ${shellQuote(hookPathFor(script, projectRoot))}`;
 }
 
 /**
@@ -88,12 +120,12 @@ function repairLegacyCodexLaunchers(config, projectRoot) {
       return {
         ...group,
         hooks: group.hooks.map((handler) => {
-          const legacy = typeof handler?.command === 'string' && handler.command.match(LEGACY_GIT_COMMAND);
+          const legacy = legacyPosixScript(handler?.command);
           const template = typeof handler?.commandWindows === 'string'
             && handler.commandWindows.match(HOOK_COMMAND_TEMPLATE);
           if (!legacy && !template) return handler;
           const next = { ...handler };
-          if (legacy) next.command = posixHookCommand(legacy[1], projectRoot);
+          if (legacy) next.command = posixHookCommand(legacy, projectRoot);
           if (template) next.commandWindows = windowsHookCommand(template[1], projectRoot);
           repaired += 1;
           return next;
@@ -166,7 +198,7 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
 
   const { config: base, repaired } = repairLegacyCodexLaunchers(pruned, projectRoot);
   if (repaired > 0) {
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: repaired ${repaired} launcher(s) that resolved their path through Git`);
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: rebound ${repaired} launcher(s) written by an older installer`);
     ctx.results.updated++;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.2",
+  "version": "0.16.4",
   "description": "Native spec-driven workflows for Claude Code and Codex CLI. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/__tests__/completion-authority.test.js

@@ -700,7 +700,14 @@ for (const kind of ['claude', 'codex']) {
       assert.match(block(stop(runtime, { featureName: 'other-feature' })).reason, /explicit/i);
       prepare(root, { feature: 'other-feature', phase: 'implementation' });
       assert.ok(nonceFrom(stop(runtime, { featureName: FEATURE })).nonce);
-      assert.match(block(stop(runtime)).reason, /multiple_persisted|multiple/i);
+      // Contract change: a sibling that is not claiming closeout is no longer a rival.
+      // This used to assert ambiguity, which is the over-strict behaviour issue #79
+      // reports: a repository that had merely accumulated features could never name its
+      // current one again. Only FEATURE is at closeout here, so it resolves and its
+      // approval is demanded. Two packets both claiming closeout still block, which
+      // `several packets claiming closeout stay ambiguous and name only those` covers in
+      // bin/__tests__/spec-narrowing.test.js.
+      assert.ok(nonceFrom(stop(runtime)).nonce, 'the one packet claiming closeout resolves');
       for (const malformed of [
         { featureName: '' },
         { featureName: 42 },

package/src/claude/hooks/completion-authority.cjs

@@ -131,7 +131,10 @@ function stop(payload) {
   const consumed = STATE.consumeGrant(root, result.binding);
   if (consumed.ok) return;
   const pending = STATE.createPending(root, result.binding);
-  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
+  // Name the feature: a recorded target can influence which packet resolves, so an
+  // approval the user cannot identify is an approval they cannot withhold.
+  const feature = result.candidate?.featureName;
+  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required for ${feature ? `"${feature}"` : 'the resolved feature'}. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
 }
 
 let mode = process.argv[2] || null;

package/src/claude/hooks/spec-gate.cjs

@@ -119,9 +119,14 @@ try {
   } catch { /* gate stays on */ }
   // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
   const baseDir   = cwd;
-  const target = typeof RESOLVER.extractExplicitTarget === 'function'
+  const target = (typeof RESOLVER.extractExplicitTarget === 'function'
     ? RESOLVER.extractExplicitTarget(payload)
-    : null;
+    : null)
+    // Only when the host named nothing. The recorded target is what makes "Provide
+    // explicit feature target" an instruction a user can actually follow.
+    || (typeof RESOLVER.readActiveFeatureTarget === 'function'
+      ? RESOLVER.readActiveFeatureTarget({ projectRoot: baseDir, runtime })
+      : null);
   let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
     ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
     : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });

package/src/claude/scripts/spec-resolver.cjs

@@ -289,6 +289,12 @@ function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
   };
 }
 
+// Legacy registries written before the current vocabulary use `completed`, which today's
+// validator rejects but which exists in upgraded repositories. Reading it as finished is
+// what lets those packets stop competing for the gate's attention; `spec-final-state.cjs`
+// already reads spec status the same way. Process-first packets keep the strict set.
+const LEGACY_TASK_DONE = new Set(['done', 'completed', 'complete']);
+
 function normalizeLegacyWorkflowCandidate(candidate) {
   const registry = candidate.spec?.task_registry || {};
   const tasks = Object.entries(registry).map(([taskPath, task]) => ({
@@ -302,7 +308,7 @@ function normalizeLegacyWorkflowCandidate(candidate) {
     phase: candidate.spec?.current_phase || candidate.spec?.phase || 'unknown',
     taskRegistry: registry,
     tasks,
-    allTasksDone: tasks.length > 0 && tasks.every((task) => task.status === 'done'),
+    allTasksDone: tasks.length > 0 && tasks.every((task) => LEGACY_TASK_DONE.has(task.status)),
   };
 }
 
@@ -491,6 +497,47 @@ function explicitTargetValue(value) {
   return typeof value === 'string' ? value.trim() : value;
 }
 
+/**
+ * Read the feature a project has recorded as the one being worked on. This answers a
+ * genuine ambiguity that no host payload resolves, so it is deliberately not a source
+ * inside `extractExplicitTarget`: that function recurses and is shared with consumers
+ * that are not the Stop hooks. Anything other than a non-empty single-line
+ * `featureName` string is invisible rather than an error, because an error here would
+ * block every turn in a project that merely has a stray file. The value is then treated
+ * exactly like a host-supplied feature name and still faces containment, existence, and
+ * JSON checks.
+ */
+function readActiveFeatureTarget({ projectRoot, runtime } = {}) {
+  if (!projectRoot) return null;
+  let specsDir;
+  try {
+    specsDir = specsDirectory(projectRoot, runtime || {});
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    const file = path.join(specsDir, '_shared', 'active-feature.json');
+    // A symlink here could name a file outside the project, so only a regular file counts.
+    const info = lstatOptional(file);
+    if (!info.exists || info.isSymlink || !info.stat.isFile()) return null;
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const value = parsed.featureName;
+  if (typeof value !== 'string' || /[\r\n]/.test(value)) return null;
+  const trimmed = value.trim();
+  return trimmed ? { explicitFeature: trimmed } : null;
+}
+
 /**
  * Normalize host-provided feature targets without making runtime adapters
  * guess from the first active directory. The resolver remains the authority
@@ -708,14 +755,27 @@ function resolvePersistedSpec({ projectRoot, runtime, explicitFeature, explicitP
     }
     return resolveActiveSpec({ projectRoot, runtime, ...normalized });
   }
+  // Only now, with the caller having named nothing: a recorded target must never
+  // redirect a hook that already knows which feature its turn is about.
+  const recorded = readActiveFeatureTarget({ projectRoot, runtime });
+  if (recorded) return resolveActiveSpec({ projectRoot, runtime, ...recorded });
   try {
     const candidates = findAllSpecCandidates(projectRoot, runtime);
     if (candidates.length === 0) return null;
+    // One packet resolves on its own terms. Closeout approval is claimed against a
+    // finished spec, so status must never decide identity here.
     if (candidates.length === 1) return candidates[0];
+    // This path serves closeout approval, so only a packet actually claiming closeout is
+    // a real rival. Counting finished history as ambiguity is what made the gate
+    // unsatisfiable in a repository that had simply accumulated features.
+    const { isDurableCloseout } = require('./spec-final-state.cjs');
+    const claiming = candidates.filter((candidate) => isDurableCloseout(candidate.spec));
+    if (claiming.length === 1) return claiming[0];
+    if (claiming.length === 0) return null;
     return {
       error: 'multiple_persisted',
-      candidates: candidates.map((candidate) => candidate.featureName),
-      reason: `Multiple persisted specs found: ${candidates.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
+      candidates: claiming.map((candidate) => candidate.featureName),
+      reason: `Multiple persisted specs found: ${claiming.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
     };
   } catch (error) {
     return {
@@ -893,10 +953,11 @@ function refineWorkflowGateResolution(resolved) {
     return resolved;
   }
   const candidates = resolved.active;
-  if (candidates.length === 0 || candidates.some((candidate) => candidate.layoutKind !== 'process-v3')) {
-    return resolved;
-  }
+  if (candidates.length === 0) return resolved;
 
+  // Which packet still has work decides this, not which layout it uses: a repository of
+  // legacy packets was permanently ambiguous only because the check below used to sit
+  // here and reject the whole set on sight.
   const unfinished = candidates.filter((candidate) => !candidate.allTasksDone);
   if (unfinished.length === 1) return unfinished[0];
   if (unfinished.length > 1) {
@@ -908,6 +969,10 @@ function refineWorkflowGateResolution(resolved) {
       reason: `Multiple active workflows found: ${unfinished.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
     };
   }
+  // The bulk-audit branch exits before the semantic-digest, FLASH_UNVERIFIED,
+  // feature-receipt, and completion-policy layers that the single-candidate path runs, so
+  // only process-first packets may reach it. Anything else keeps the existing ambiguity.
+  if (candidates.some((candidate) => candidate.layoutKind !== 'process-v3')) return resolved;
   return {
     layoutKind: 'process-v3-completed-set',
     candidates,
@@ -923,6 +988,7 @@ module.exports = {
   findAllSpecCandidates,
   extractExplicitTarget,
   resolveActiveSpec,
+  readActiveFeatureTarget,
   resolvePersistedSpec,
   resolveWorkflowCandidate,
   refineWorkflowGateResolution,

package/src/codex/hooks/completion-authority-check.cjs

@@ -37,6 +37,10 @@ function explicitTarget(payload) {
 function resolveCandidate({ projectRoot, runtime, payload }) {
   const target = explicitTarget(payload);
   if (target) return RESOLVER.resolveActiveSpec({ projectRoot, runtime, ...target });
+  // Delegate so both runtimes answer the same question; the count below stays only as a
+  // fallback for an installed resolver older than this wrapper.
+  const shared = RESOLVER.resolvePersistedSpec({ projectRoot, runtime });
+  if (shared !== null) return shared;
   const candidates = RESOLVER.findAllSpecCandidates(projectRoot, runtime);
   if (candidates.length > 1) return { error: 'multiple_persisted', candidates: candidates.map((candidate) => candidate.featureName) };
   return candidates[0] || null;

package/src/codex/hooks/completion-authority.cjs

@@ -79,7 +79,10 @@ function stop(payload) {
   const consumed = STATE.consumeGrant(projectRoot, result.binding);
   if (consumed.ok) return;
   const pending = STATE.createPending(projectRoot, result.binding);
-  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
+  // Name the feature: a recorded target can influence which packet resolves, so an
+  // approval the user cannot identify is an approval they cannot withhold.
+  const feature = result.candidate?.featureName;
+  emitBlock(`Completion authority: technical proofs pass, but user closeout approval is required for ${feature ? `"${feature}"` : 'the resolved feature'}. Enter exactly "${STATE.PREFIX}${pending.nonce}" as your next user prompt. This approval is one-time and expires in five minutes.`);
 }
 
 let mode = process.argv[2] || null;

package/src/codex/hooks/lib/spec-utils.cjs

@@ -140,8 +140,29 @@ function taskStatusMap(spec) {
   );
 }
 
+function extractExplicitTarget(...sources) {
+  const resolver = sharedResolver();
+  if (typeof resolver.extractExplicitTarget !== 'function') return null;
+  return resolver.extractExplicitTarget(...sources);
+}
+
+function readActiveFeatureTarget(options) {
+  const resolver = sharedResolver();
+  if (typeof resolver.readActiveFeatureTarget !== 'function') return null;
+  return resolver.readActiveFeatureTarget(options);
+}
+
+function resolvePersistedSpec(options) {
+  const resolver = sharedResolver();
+  if (typeof resolver.resolvePersistedSpec !== 'function') return null;
+  return resolver.resolvePersistedSpec(options);
+}
+
 module.exports = {
   findActiveSpec,
+  extractExplicitTarget,
+  readActiveFeatureTarget,
+  resolvePersistedSpec,
   findAllActiveSpecs,
   findAllSpecCandidates,
   resolveActiveSpec,

package/src/codex/hooks/spec-gate.cjs

@@ -49,8 +49,12 @@ try {
     throw new Error('shared workflow policy lacks completion authority functions');
   }
   const resolver = require('./lib/spec-utils.cjs');
+  // The payload is still the authority. The recorded target only answers the ambiguity
+  // the payload leaves, which is what made the block unescapable on this runtime too.
+  const target = resolver.extractExplicitTarget(payload)
+    || resolver.readActiveFeatureTarget({ projectRoot, runtime });
   let resolved = typeof resolver.resolveWorkflowCandidate === 'function'
-    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target: payload, includeCompleted: true })
+    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target, includeCompleted: true })
     : FINAL_STATE.resolveCandidate({ resolver, projectRoot, runtime, payload });
   if (typeof resolver.refineWorkflowGateResolution === 'function') {
     resolved = resolver.refineWorkflowGateResolution(resolved);