@lyupro/codex-bridge 0.6.7 → 0.6.9

package/src/agents/codex-advisor.md

@@ -83,8 +83,9 @@ codex-bridge run --agent codex-advisor --repo "<repository-path or .>" --phase "
 ```
 
 That is one command line. Add only the bare `--continue` when the task text contains a line
-beginning with `continue:`; it has no value. The runner accepts only `1/true/yes/0/false/no` as a
-grant value in the task text, so a malformed grant is passed through for the runner to refuse. If
+beginning with `continue:`; the flag itself takes no value (the runner accepts only
+`1/true/yes/0/false/no` there). The grant line names a run folder and a reason, and the runner parses
+it, so a malformed grant is passed through for the runner to refuse. If
 there is no grant line, do not add the flag. Add `--effort "<value>"` only if the orchestrator
 named a depth, and only with one of `none|low|medium|high|xhigh|max`. Never add free text or any
 flags beyond those two conditional flags.
@@ -158,6 +159,8 @@ verbatim; compose nothing.
 The run folder contains its status and artifacts. An abandoned run is not a reason to start over
 yourself: the orchestrator decides whether to continue, and without the `--continue` it issued,
 the runner will reject that continuation itself.
+The orchestrator repeats a failed scope under a NEW order id, never with `continue:` or `--continue`:
+the runner refuses a continued scope, because it would spend the continuation that advise needs.
 
 ## Codex is unavailable
 

package/src/home/conventions.md

@@ -42,3 +42,12 @@ boundary is needed.
 The 2026-08-05 step 2b acceptance found the abandoned-run check below the commit check. Test the
 ordering invariant itself, and leave the incident in the comment so a later cleanup does not
 silently undo it.
+
+## Failing tests are evidence - Plan_73 B3 fixture incident
+
+- Never change a fixture or an expectation only to make a failing test pass.
+- When an existing test fails for a reason the task does not describe, leave it failing and name
+  it under deviations.
+
+The 2026-09-30 Plan_73 B3 run rewrote a witness fixture so that a snapshot codec defect stopped
+showing; that defect would have failed every build started on a clean tree.

package/src/home/hooks/dispatcher-gate.mjs

@@ -17,7 +17,8 @@ import {
   readDispatcherState,
   updateDispatcherState,
 } from '../lib/dispatcher-state.mjs';
-import { hostSdkVersion, recordHandbackWitness } from '../lib/handback-witness.mjs';
+import { recordHandbackWitness, witnessHostVersion } from '../lib/handback-witness.mjs';
+import { observeSessionHost } from '../lib/host-observations.mjs';
 
 function emit(decision, toolInput) {
   const hookSpecificOutput = {
@@ -43,6 +44,18 @@ async function main() {
     return;
   }
 
+  if (payload?.hook_event_name === 'PreToolUse'
+    && typeof payload.session_id === 'string' && payload.session_id.length > 0
+    && typeof payload.transcript_path === 'string' && payload.transcript_path.length > 0) {
+    try {
+      await observeSessionHost({
+        stateDir: BRAND_STATE_DIR,
+        sessionId: payload.session_id,
+        transcriptPath: payload.transcript_path,
+      });
+    } catch {}
+  }
+
   if (!payload || !Object.prototype.hasOwnProperty.call(AGENTS, payload.agent_type)
     || typeof payload.session_id !== 'string' || payload.session_id.length === 0
     || typeof payload.agent_id !== 'string' || payload.agent_id.length === 0) return;
@@ -87,7 +100,7 @@ async function main() {
         await recordHandbackWitness({
           stateDir: BRAND_STATE_DIR,
           kind: 'seen',
-          sdkVersion: hostSdkVersion(),
+          hostVersion: await witnessHostVersion(payload),
         });
       } catch {}
       try {

package/src/home/hooks/guard-tries.mjs

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { BRAND_STATE_DIR } from '../lib/brand-home.mjs';
+import { BRAND_HOME, BRAND_STATE_DIR } from '../lib/brand-home.mjs';
+import { createHomeWriter } from '../lib/home-write.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
 
 /**
@@ -49,8 +49,10 @@ export function takeTry(agentId, kind, maxBlocks = kind === STATE ? MAX_STATE_BL
   const ids = Object.keys(seen);
   if (ids.length > 200) ids.slice(0, ids.length - 200).forEach((id) => delete seen[id]);
   try {
-    fs.mkdirSync(path.dirname(BLOCKED_FILE), { recursive: true });
-    fs.writeFileSync(BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
+    // Plan_65 B4: the budget is the registered guard-tries artifact, so purge can name and remove it.
+    const writer = createHomeWriter({ root: BRAND_HOME.root });
+    writer.mkdirSync('guard-tries', path.dirname(BLOCKED_FILE), { recursive: true });
+    writer.writeFileSync('guard-tries', BLOCKED_FILE, `${JSON.stringify(seen)}\n`);
   } catch {
     return 'untracked';
   }

package/src/home/hooks/order-gate.mjs

@@ -14,7 +14,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS } from '../lib/agents.mjs';
-import { BRAND_STATE_DIR } from '../lib/brand-home.mjs';
+import { recordHookDiagnostic } from '../lib/hook-diagnostics.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
 import {
   diagnoseInput,
@@ -30,7 +30,6 @@ import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
 import { parseTaskDocument } from '../lib/runner/task-file.mjs';
 
-const DIAGNOSTICS_DIR = path.join(BRAND_STATE_DIR, 'diagnostics');
 const GUARDED = new Set(Object.keys(AGENTS));
 /**
  * Both spellings of the subagent-launching tool, from the same list the installer builds its
@@ -58,12 +57,7 @@ try {
   pass();
 }
 
-try {
-  fs.mkdirSync(DIAGNOSTICS_DIR, { recursive: true });
-  fs.writeFileSync(path.join(DIAGNOSTICS_DIR, 'order-gate.last.json'), `${JSON.stringify(input, null, 2)}\n`);
-} catch {
-  // Diagnostics are a convenience, never a reason to fail the turn.
-}
+recordHookDiagnostic('order-gate', input);
 
 if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
 if (!SUBAGENT_TOOL_NAMES.has(input.tool_name)) pass();

package/src/home/hooks/reply-guard.mjs

@@ -22,6 +22,7 @@
  * argument about EXTERNAL run state cannot be argued away by the model and ends the turn
  * with `continue: false` instead of a silent pass. See MAX_FORM_BLOCKS / MAX_STATE_BLOCKS.
  * In the handback era, SubagentHandback delivers the caller-visible answer before SubagentStop.
+ * Alarms name the host by its transcript version: on 2026-09-25 the SDK variable proved inherited.
  * Plan_62 makes this hook yield after delivery and audit every transcript tool call against gate receipts.
  *
  * Input is JSON on stdin. The fields used here (`agent_type`, `last_assistant_message`)
@@ -32,12 +33,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS } from '../lib/agents.mjs';
 import { BRAND_STATE_DIR } from '../lib/brand-home.mjs';
+import { recordHookDiagnostic } from '../lib/hook-diagnostics.mjs';
 import { runOrderMismatch, transcriptOrderId } from '../lib/dispatcher-order.mjs';
 import { decideDispatcherStop, transcriptToolUses } from '../lib/dispatcher-stop.mjs';
 import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
 import { readDispatcherState, updateDispatcherState } from '../lib/dispatcher-state.mjs';
-import { hostSdkVersion, recordHandbackWitness } from '../lib/handback-witness.mjs';
+import { recordHandbackWitness, witnessHostVersion } from '../lib/handback-witness.mjs';
 import { runLiveness } from '../lib/meta/run-liveness.mjs';
 import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
@@ -110,14 +112,27 @@ try {
   pass();
 }
 
-try {
-  const diagnosticsDir = path.join(BRAND_STATE_DIR, 'diagnostics');
-  fs.mkdirSync(diagnosticsDir, { recursive: true });
-  fs.writeFileSync(path.join(diagnosticsDir, 'reply-guard.last.json'), `${JSON.stringify(input, null, 2)}\n`);
-} catch {
-  // Diagnostics are a convenience, never a reason to fail the turn.
-}
+recordHookDiagnostic('reply-guard', input);
 
+// A host that stops sending agent_type would let every dispatcher past the gate and this
+// audit without a word (Plan_66 D2 (c)); say so instead of passing silently.
+if (typeof input.agent_id === 'string' && input.agent_id.length > 0
+  && !(typeof input.agent_type === 'string' && input.agent_type.length > 0)) {
+  try {
+    await recordHandbackWitness({
+      stateDir: BRAND_STATE_DIR,
+      kind: 'alarm',
+      hostVersion: await witnessHostVersion(input),
+      detail: `host omitted agent_type for agent ${input.agent_id}`,
+    });
+  } catch {
+    // Plan_66 H2: the 2026-09-17..24 handback break showed host contract loss must alarm, but never block work.
+  }
+  process.stdout.write(JSON.stringify({
+    systemMessage: 'codex-bridge: the host did not report agent_type for a subagent — the dispatcher gate cannot recognise dispatchers, so their answers are unchecked; run codex-bridge doctor.',
+  }));
+  process.exit(0);
+}
 // Only the Codex dispatchers have this contract. Every other agent is none of our
 // business — an earlier version inferred the agent from transcript text and blocked an
 // unrelated one, which cost a re-answer for nothing.
@@ -144,7 +159,7 @@ try {
       await recordHandbackWitness({
         stateDir: BRAND_STATE_DIR,
         kind: 'alarm',
-        sdkVersion: hostSdkVersion(),
+        hostVersion: await witnessHostVersion(input),
         detail: `${input.agent_type} ${input.agent_id}: ${names} outside the dispatcher gate`,
       });
     }

package/src/home/hooks/worktree-witness.mjs

@@ -15,7 +15,7 @@ import path from 'node:path';
 import { SHELL_TOOLS } from '../lib/hook-definitions.mjs';
 import { parseJsonText } from '../lib/json-file.mjs';
 import { splitRunChanges } from '../lib/meta/environment.mjs';
-import { changedPaths } from '../lib/meta/paths.mjs';
+import { compareSnapshots } from '../lib/meta/snapshot-format.mjs';
 import { outOfScope } from '../lib/meta/verdict.mjs';
 import { git, worktreeSnapshot } from '../lib/runner/git-state.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
@@ -64,16 +64,16 @@ if (beforeText === null || scopeText === null) pass();
 
 let outside;
 try {
-  // changedPaths tolerates malformed rows; a hook must instead fail open on a damaged baseline.
-  if (beforeText.split(/\r?\n/).filter(Boolean).some((row) =>
-    !/^(?:\d+\t\d+|-\t-|U\t\d+)\t\S.*$/.test(row))) pass();
   const patterns = scopeText.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   if (!patterns.length) pass();
   // The shared snapshot returns empty output on git errors; do not call that a restored tree.
   const repository = git(status.repo, ['rev-parse', '--is-inside-work-tree']);
   if (repository.error || repository.status !== 0 || repository.stdout?.trim() !== 'true') pass();
-  const current = worktreeSnapshot(status.repo);
-  const { work } = splitRunChanges(dir, changedPaths(beforeText, current));
+  // Plan_73 / 2026-09-30: a damaged or incompatible baseline proves neither a clean
+  // tree nor a stray edit. The advisory witness stays silent when the codec refuses it.
+  const comparison = compareSnapshots(beforeText, worktreeSnapshot(status.repo));
+  if (!comparison.ok) pass();
+  const { work } = splitRunChanges(dir, comparison.changed);
   outside = outOfScope(work, patterns);
 } catch {
   pass();

package/src/home/lib/agents.mjs

@@ -12,7 +12,7 @@ export const AGENTS = {
   'codex-build': { role: 'build', budget: 25, writes: true, result: 'result.json' },
   'codex-review': { role: 'review', budget: 20, writes: false, result: 'review.json' },
   // Plan_59: design advice needs a bounded scope pass before the continued decision pass.
-  'codex-advisor': { role: 'advisor', budget: { scope: 5, advise: 15 }, writes: false, result: 'result.json' },
+  'codex-advisor': { role: 'advisor', budget: { scope: 10, advise: 25 }, writes: false, result: 'result.json' },
 };
 
 export const agentRole = (agent) => AGENTS[agent]?.role;

package/src/home/lib/atomic-json.mjs

@@ -6,16 +6,34 @@
  * (`config-edit.mjs` keeps its own compare-and-swap publish for that reason).
  */
 import { randomUUID } from 'node:crypto';
-import fs from 'node:fs';
 import path from 'node:path';
 
-export function writeJsonAtomic(file, record) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
+function removeIfPresent(remove, temporary) {
+  try {
+    remove(temporary);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+function publishJsonAtomic(file, record, operations) {
   const temporary = `${file}.${randomUUID()}.tmp`;
   try {
-    fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
-    fs.renameSync(temporary, file);
+    operations.mkdir(path.dirname(file), { recursive: true });
+    operations.write(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
+    operations.rename(temporary, file);
   } finally {
-    fs.rmSync(temporary, { force: true });
+    removeIfPresent(operations.unlink, temporary);
   }
 }
+
+export function writeHomeJsonAtomic(writer, id, file, record) {
+  // Plan_65 B2: `state/` is shared by artifacts, so validate the file before mkdir can create it.
+  writer.assertArtifact(id, file);
+  return publishJsonAtomic(file, record, {
+    mkdir(directory, options) { return writer.mkdirSync(id, directory, options); },
+    write(temporary, contents, options) { return writer.writeFileSync(id, temporary, contents, options); },
+    rename(temporary, target) { return writer.renameSync(id, temporary, target); },
+    unlink(temporary) { return writer.unlinkSync(id, temporary); },
+  });
+}

package/src/home/lib/config-edit.mjs

@@ -13,7 +13,8 @@ import { randomUUID } from 'node:crypto';
 import { BRAND_CONFIG_PATH } from './brand-home.mjs';
 import { parseJsonText } from './json-file.mjs';
 import { validateRunConfig } from './config-validate.mjs';
-import { withFileLock } from './file-lock.mjs';
+import { createHomeWriter } from './home-write.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
 
 function replaceValue(file, raw, key, value) {
   // The shared reader has already checked JSON syntax; tokens locate top-level value spans.
@@ -72,6 +73,14 @@ async function readBytes(file) {
   }
 }
 
+async function removeTemporary(writer, temporary) {
+  try {
+    await writer.unlink('config', temporary);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
 function readBytesSync(file) {
   try {
     return fsSync.readFileSync(file);
@@ -82,15 +91,17 @@ function readBytesSync(file) {
 }
 
 export async function editRunConfig(key, transform, file = BRAND_CONFIG_PATH) {
+  const directory = path.dirname(path.resolve(file));
+  const writer = createHomeWriter({ root: directory });
+  writer.assertArtifact('config', file);
   const reset = key !== null && typeof key === 'object' && !Array.isArray(key)
     && key.reset === true && Object.keys(key).length === 1 && transform === undefined;
   if (!reset && (typeof key !== 'string' || !key || typeof transform !== 'function')) {
     throw new Error('Config edit requires a non-empty string key and a transformer function or { reset: true }');
   }
-  const directory = path.dirname(file);
-  const created = await fs.mkdir(directory, { recursive: true });
+  const created = await writer.mkdir('config', directory, { recursive: true });
   try {
-    return await withFileLock(`${file}.lock`, async () => {
+    return await withHomeFileLock(writer, 'config', `${file}.lock`, async () => {
       let collision;
       for (let attempt = 0; attempt < 3; attempt += 1) {
         const original = await readBytes(file);
@@ -109,9 +120,9 @@ export async function editRunConfig(key, transform, file = BRAND_CONFIG_PATH) {
         }
         // Validate the exact bytes to be persisted, before even creating a temporary file (D27).
         const config = validateRunConfig(file, parseJsonText(file, text));
-        await fs.mkdir(path.dirname(file), { recursive: true });
+        await writer.mkdir('config', directory, { recursive: true });
         const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
-        const handle = await fs.open(temporary, 'wx');
+        const handle = await writer.open('config', temporary, 'wx');
         try {
           await handle.writeFile(text, 'utf8');
           await handle.close();
@@ -121,14 +132,14 @@ export async function editRunConfig(key, transform, file = BRAND_CONFIG_PATH) {
           // suspension point between the two, so a competing edit is seen by whoever compares second.
           const current = readBytesSync(file);
           if (original === null ? current !== null : current === null || !original.equals(current)) {
-            await fs.rm(temporary, { force: true });
+            await removeTemporary(writer, temporary);
             continue;
           }
-          fsSync.renameSync(temporary, file);
+          writer.renameSync('config', temporary, file);
           return config;
         } catch (error) {
           await handle.close().catch(() => {});
-          await fs.rm(temporary, { force: true });
+          await removeTemporary(writer, temporary);
           // Windows refuses the rename outright when another process is publishing onto the same name
           // at that instant: two concurrent `model set` calls returned EPERM here on a live probe, and
           // one operator edit was lost with the file system's wording instead of an answer. A collision
@@ -149,9 +160,13 @@ export async function editRunConfig(key, transform, file = BRAND_CONFIG_PATH) {
     if (created) {
       // Windows mkdir returns a namespaced path; compare that form on both sides of the boundary.
       const boundary = path.toNamespacedPath(path.resolve(created));
+      const homeRoot = path.toNamespacedPath(path.resolve(directory));
       for (let current = path.toNamespacedPath(path.resolve(directory));
         current === boundary || current.startsWith(`${boundary}${path.sep}`); current = path.dirname(current)) {
-        try { await fs.rmdir(current); } catch { break; }
+        try {
+          if (current === homeRoot) writer.rmdirSync('config', directory);
+          else await fs.rmdir(current);
+        } catch { break; }
       }
     }
     throw error;

package/src/home/lib/dispatcher-state.mjs

@@ -2,9 +2,14 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeJsonAtomic } from './atomic-json.mjs';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
 import { parseJsonText } from './json-file.mjs';
-import { withFileLock } from './file-lock.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
+
+// Plan_65 B5: every write goes through the registry id so purge accounts for records, locks and
+// temporaries alike.
+const ARTIFACT = 'dispatcher-state';
 
 function assertIdentity(sessionId, agentId) {
   if (typeof sessionId !== 'string' || sessionId.length === 0
@@ -55,7 +60,8 @@ export async function updateDispatcherState(ids, mutate) {
   if (typeof mutate !== 'function') throw new TypeError('mutate must be a function');
   const file = dispatcherStatePath(ids);
   const { sessionId, agentId } = ids;
-  return withFileLock(`${file}.lock`, async () => {
+  const writer = stateDirWriter(ids.stateDir);
+  return withHomeFileLock(writer, ARTIFACT, `${file}.lock`, async () => {
     let current = readDispatcherState(ids);
     if (current === null) {
       current = { sessionId, agentId, createdAt: timestamp(clockValue(ids)) };
@@ -71,7 +77,7 @@ export async function updateDispatcherState(ids, mutate) {
       agentId,
       updatedAt: timestamp(clockValue(ids)),
     };
-    writeJsonAtomic(file, record);
+    writeHomeJsonAtomic(writer, ARTIFACT, file, record);
     return record;
   }, { description: 'dispatcher state' });
 }
@@ -86,11 +92,19 @@ export function pruneDispatcherStates({ stateDir, olderThanMs = 7 * 24 * 3600 *
     throw error;
   }
 
+  const writer = stateDirWriter(stateDir);
   const cutoff = now - olderThanMs;
   let removed = 0;
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
     const file = path.join(directory, entry.name);
+    // Only the registry's 32-hex records are ours to prune; any other name here is kept (Plan_65 D3).
+    try {
+      writer.assertArtifact(ARTIFACT, file);
+    } catch (error) {
+      if (error.code === 'EHOMEREGISTRY') continue;
+      throw error;
+    }
     let old;
     try {
       old = fs.statSync(file).mtimeMs < cutoff;
@@ -99,13 +113,14 @@ export function pruneDispatcherStates({ stateDir, olderThanMs = 7 * 24 * 3600 *
       throw error;
     }
     if (!old) continue;
-    try {
-      fs.unlinkSync(file);
-      removed += 1;
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
+    for (const target of [file, `${file}.lock`]) {
+      try {
+        writer.unlinkSync(ARTIFACT, target);
+        if (target === file) removed += 1;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
     }
-    fs.rmSync(`${file}.lock`, { force: true });
   }
   return removed;
 }

package/src/home/lib/file-lock.mjs

@@ -15,11 +15,11 @@ function waitForLock(delayMs) {
  * 2026-08-04). An owner update takes milliseconds, so a lock older than the staleness window
  * belongs to a process that is gone.
  */
-async function dropStaleLock(lockPath, staleMs) {
+async function dropStaleLock(lockPath, staleMs, remove) {
   try {
     const { mtimeMs } = await fs.stat(lockPath);
     if (Date.now() - mtimeMs < staleMs) return false;
-    await fs.rm(lockPath, { force: true });
+    await remove(lockPath);
     return true;
   } catch {
     // Vanished or unreadable — let the next open() decide rather than guess here.
@@ -42,17 +42,17 @@ export function isLockTaken(err) {
   return LOCK_TAKEN_CODES.has(err?.code);
 }
 
-async function acquireFileLock(lockPath, { retries, delayMs, staleMs, description }) {
-  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+async function acquireFileLock(lockPath, { retries, delayMs, staleMs, description }, operations) {
+  await operations.mkdir(path.dirname(lockPath), { recursive: true });
   let lastTaken;
   for (let attempt = 0; attempt < retries; attempt += 1) {
     try {
-      const handle = await fs.open(lockPath, 'wx');
-      return { handle, lockPath };
+      const handle = await operations.open(lockPath);
+      return { handle, lockPath, remove: operations.remove };
     } catch (err) {
       if (!isLockTaken(err)) throw err;
       lastTaken = err;
-      if (!(await dropStaleLock(lockPath, staleMs))) await waitForLock(delayMs);
+      if (!(await dropStaleLock(lockPath, staleMs, operations.remove))) await waitForLock(delayMs);
     }
   }
   // The code is part of the message: a timeout on EPERM points at a delete that never completed,
@@ -63,14 +63,45 @@ async function acquireFileLock(lockPath, { retries, delayMs, staleMs, descriptio
   );
 }
 
-export async function withFileLock(lockPath, action, {
+export async function withOutsideFileLock(writer, lockPath, action, {
   retries = 200, delayMs = 5, staleMs = 30_000, description = 'file',
 } = {}) {
-  const lock = await acquireFileLock(lockPath, { retries, delayMs, staleMs, description });
+  writer.assertOutside(lockPath);
+  const remove = (target) => fs.rm(target, { force: true });
+  const lock = await acquireFileLock(lockPath, { retries, delayMs, staleMs, description }, {
+    mkdir(directory, options) { return fs.mkdir(directory, options); },
+    open(lockFile) { return fs.open(lockFile, 'wx'); },
+    remove,
+  });
   try {
     return await action();
   } finally {
     await lock.handle.close().catch(() => {});
-    await fs.rm(lock.lockPath, { force: true }).catch(() => {});
+    await lock.remove(lock.lockPath).catch(() => {});
+  }
+}
+
+export async function withHomeFileLock(writer, id, lockPath, action, {
+  retries = 200, delayMs = 5, staleMs = 30_000, description = 'file',
+} = {}) {
+  // Plan_65 B2: the lock's parent is shared by artifacts, so a wrong id is refused before mkdir.
+  writer.assertArtifact(id, lockPath);
+  const remove = async (target) => {
+    try {
+      return await writer.unlink(id, target);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  };
+  const lock = await acquireFileLock(lockPath, { retries, delayMs, staleMs, description }, {
+    mkdir(directory, options) { return writer.mkdir(id, directory, options); },
+    open(lockFile) { return writer.open(id, lockFile, 'wx'); },
+    remove,
+  });
+  try {
+    return await action();
+  } finally {
+    await lock.handle.close().catch(() => {});
+    await lock.remove(lock.lockPath).catch(() => {});
   }
 }

package/src/home/lib/handback-witness.mjs

@@ -1,27 +1,33 @@
-/** Records the 2026-09-17..24 silent SubagentHandback contract break before it can go unnoticed again. */
+/** Records the 2026-09-17..24 handback break; 2026-09-25 proved SDK env is inherited, so identify hosts from transcripts. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeJsonAtomic } from './atomic-json.mjs';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
 import { parseJsonText } from './json-file.mjs';
-import { withFileLock } from './file-lock.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
+import { transcriptHostVersion } from './host-version.mjs';
 
 export const WITNESS_FILE = 'handback-witness.json';
 
-export function hostSdkVersion(env = process.env) {
-  const version = env.CLAUDE_AGENT_SDK_VERSION;
-  if (typeof version !== 'string') return null;
-  return version.trim() || null;
+export async function witnessHostVersion(payload) {
+  return transcriptHostVersion(payload?.transcript_path);
 }
 
-function isWitness(record) {
-  const witnessEntry = (entry, alarm = false) => entry && typeof entry === 'object'
-    && !Array.isArray(entry)
-    && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string')
-    && typeof entry.at === 'string'
-    && (!alarm || typeof entry.detail === 'string');
-  return record && typeof record === 'object' && !Array.isArray(record)
-    && (record.lastSeen === null || witnessEntry(record.lastSeen))
-    && Array.isArray(record.alarms) && record.alarms.every((entry) => witnessEntry(entry, true));
+function normalizeWitness(record) {
+  const alarmEntry = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && (entry.hostVersion === null || typeof entry.hostVersion === 'string')
+    && typeof entry.at === 'string' && typeof entry.detail === 'string';
+  if (!record || typeof record !== 'object' || Array.isArray(record) || !Array.isArray(record.alarms)) return null;
+  if (record.alarms.every(alarmEntry) && record.lastSeen && typeof record.lastSeen === 'object'
+    && !Array.isArray(record.lastSeen) && !Object.hasOwn(record.lastSeen, 'sdkVersion')
+    && !Object.hasOwn(record.lastSeen, 'at') && Object.values(record.lastSeen).every((at) => typeof at === 'string')) return record;
+  const legacy = record.lastSeen === null || (record.lastSeen && typeof record.lastSeen === 'object'
+    && !Array.isArray(record.lastSeen) && typeof record.lastSeen.sdkVersion === 'string' && typeof record.lastSeen.at === 'string');
+  const legacyAlarm = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string') && typeof entry.at === 'string'
+    && typeof entry.detail === 'string';
+  if (legacy && record.alarms.every(legacyAlarm)) return { lastSeen: {}, alarms: record.alarms.map(({ at, detail }) => ({ hostVersion: null, at, detail })) };
+  return null;
 }
 
 export function readHandbackWitness({ stateDir }) {
@@ -30,12 +36,12 @@ export function readHandbackWitness({ stateDir }) {
   try {
     source = fs.readFileSync(file, 'utf8');
   } catch (error) {
-    if (error.code === 'ENOENT') return { lastSeen: null, alarms: [] };
+    if (error.code === 'ENOENT') return { lastSeen: {}, alarms: [] };
     return { corrupt: true };
   }
   try {
     const record = parseJsonText(file, source);
-    return isWitness(record) ? record : { corrupt: true };
+    return normalizeWitness(record) || { corrupt: true };
   } catch {
     return { corrupt: true };
   }
@@ -46,20 +52,22 @@ function timestamp(now) {
 }
 
 
-export async function recordHandbackWitness({ stateDir, kind, sdkVersion, detail = '', now = new Date() }) {
+export async function recordHandbackWitness({ stateDir, kind, hostVersion, detail = '', now = new Date() }) {
   if (kind !== 'seen' && kind !== 'alarm') throw new TypeError("kind must be 'seen' or 'alarm'");
-  if (sdkVersion !== null && typeof sdkVersion !== 'string') {
-    throw new TypeError('sdkVersion must be a string or null');
+  if (hostVersion !== null && typeof hostVersion !== 'string') {
+    throw new TypeError('hostVersion must be a string or null');
   }
   const file = path.join(stateDir, WITNESS_FILE);
-  return withFileLock(`${file}.lock`, async () => {
+  // Plan_65 B6: the witness, its lock and temporaries are the registered handback-witness artifact.
+  const writer = stateDirWriter(stateDir);
+  return withHomeFileLock(writer, 'handback-witness', `${file}.lock`, async () => {
     const current = readHandbackWitness({ stateDir });
     if (current.corrupt) throw new Error(`Cannot update corrupt handback witness: ${file}`);
     const at = timestamp(now);
     const record = kind === 'seen'
-      ? { ...current, lastSeen: { sdkVersion, at } }
-      : { ...current, alarms: [...current.alarms, { sdkVersion, at, detail }].slice(-20) };
-    writeJsonAtomic(file, record);
+      ? { ...current, lastSeen: hostVersion === null ? current.lastSeen : { ...current.lastSeen, [hostVersion]: at } }
+      : { ...current, alarms: [...current.alarms, { hostVersion, at, detail }].slice(-20) };
+    writeHomeJsonAtomic(writer, 'handback-witness', file, record);
     return record;
   }, { description: 'handback witness' });
 }