@lyupro/codex-bridge 0.6.9 → 0.6.11

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

@@ -0,0 +1,91 @@
+/**
+ * Owns only the dispatcher protocol text shared by every dispatcher prompt.
+ * Plan_63 D11: four hand-written copies drifted; build even requested a continuation
+ * flag absent from the canonical command. Render the command from its own assembler.
+ */
+import { renderRunCommandTemplate } from './dispatcher-command.mjs';
+import { TASK_FILE_INPUT } from './dispatcher-call.mjs';
+
+export function renderDispatcherProtocol(agentType) {
+  const command = renderRunCommandTemplate(agentType);
+  return `## Required dispatcher input
+
+The call is exactly one line: \`${TASK_FILE_INPUT.label}: <task-file path from the orchestrator>\`.
+The path must be absolute and name a file the orchestrator wrote with its file tool.
+The dispatcher never creates, reads or rewrites it: writing it from the shell brings back
+the permission prompt this file channel exists to remove.
+The whole order — order id, grants and every other value — lives in that file's header.
+The runner checks the header, never the dispatcher. The dispatcher never adds, removes or
+reorders anything on the command line because of what the call or the file says.
+No path in the call means run nothing and return
+\`FAIL — could not start the Codex run: no task file in the call\`, the form the no-self-execution rule gives.
+
+## When the host refuses the command
+
+If the host refuses to run \`codex-bridge run\` — a permission prompt, a classifier denial, anything
+that stops the command — that refusal is your final answer. Report \`FAIL\`, name the task file from the call,
+and state the one correction: the operator runs \`codex-bridge install\`, which grants the permission
+rule this package needs.
+
+You are forbidden to look for a way around it. Specifically, and without exception:
+
+- never call \`run-codex.mjs\`, or any file inside the installed package, by path;
+- never start the runner through \`node\`, \`npx\`, \`sh\`, \`bash\` or any other interpreter;
+- never retry the same call in PowerShell because Bash refused it, or the reverse;
+- never split the call over more than one line, and never add a pipe, a semicolon or a redirect;
+- never advise the operator to grant a permission rule on an internal file — a rule on anything but
+  the package command undoes the very design that makes this call permission-stable.
+
+Every one of those forms was removed on purpose: a host matches a permission rule against the
+beginning of the final command line, so an interpreter, a path or a continuation makes the call
+unmatchable by construction. Reaching for one does not rescue the run; it guarantees the refusal
+and asks the operator to make it permanent. On 2026-08-15 an order in another repository did all
+three in sequence and ended by telling its operator to grant a rule on \`run-codex.mjs\`.
+
+## The only thing you do
+
+\`\`\`bash
+${command}
+\`\`\`
+
+Replace the placeholder with the path from the call, nothing else.
+The first call starts the run and returns at once with \`RUN=<path> order-id=<id>\` and a
+\`STARTED\` line. To get the verdict, run the identical command again. That call does not start
+a second run or cost quota: it attaches to the run already in flight, prints
+\`ATTACH=<path> order-id=<id> started=<time>\`, blocks until the verdict exists and prints it.
+Give the attaching call \`timeout: 1800000\` (30 minutes). A real run takes 20-25 minutes,
+which is normal, not a hang. If the ceiling kills it, run the identical command again:
+it attaches to the same run and keeps waiting.
+
+Background execution (\`run_in_background\`, \`&\`, \`nohup\`) is prohibited, and so is inventing
+a report from memory. Never add a flag: the host allows exactly the one canonical command
+and refuses every other.
+
+A runner refusal — an order id collision, a header problem or a grant problem — is the whole
+answer: return it as \`FAIL\` with the runner's text. Never retry with a changed command or another
+task file. The next pass is assigned only by the orchestrator, never chosen by you.
+The order id in the task-file header is issued by the orchestrator and is what makes a repeat
+harmless; a changed task file or command turns a repeat into a second paid run.
+On 2026-08-03 one order became six runs exactly this way, and four of them were never accounted for
+at all. A second writing run in one worktree is refused anyway — the tree is shared and has no
+isolation.
+
+**Your response = the exact stdout of the attaching call**: the \`ATTACH=<path>\` line and the status
+block below it. Do not add or remove anything: no preamble, explanations, or retelling of the diff.
+The report is in \`report.md\`; the orchestrator will read it. Do not make commits: that is the
+operator's decision. The \`STARTED\` output of the first call is not a result and is never the response.
+When the first call prints no \`RUN=\` line — a runner refusal or an \`UNAVAILABLE\` block, with no run
+folder created — there is nothing to attach to: that output, verbatim, is the whole response, and
+the identical command is not run again.
+
+The only allowed final response is this exact stdout. Wording such as "the run has started,
+waiting for completion," "I will wait for a notification," or "Monitor started in the background" is
+prohibited in any form: the subagent ceases to exist immediately after responding, nobody can wait,
+and the orchestrator gets a promise instead of a result. A real case: the dispatcher gave exactly
+such a response during a live run — the worktree remained busy, and this could only be discovered
+by checking \`status.json\` manually.
+Inventing any outcome the runner did not print is equally prohibited. On 2026-08-13 a dispatcher said
+\`FAIL — could not get the Codex run result because of an architectural environment limitation\` while
+that run's \`status.json\` already said \`state=finished\`, \`status=OK\`.
+`;
+}

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

@@ -12,21 +12,30 @@ export function transcriptToolUses(transcriptPath) {
   }
 
   const toolUses = [];
+  let complete = true;
   for (const line of source.split(/\r?\n/)) {
+    if (!line.trim()) continue;
     let record;
     try {
       record = parseJsonText(transcriptPath, line);
     } catch {
+      complete = false;
       continue;
     }
     if (record?.type !== 'assistant' && record?.message?.role !== 'assistant') continue;
     const content = record.message?.content;
     if (!Array.isArray(content)) continue;
     for (const block of content) {
-      if (block?.type === 'tool_use') toolUses.push({ id: block.id, name: block.name });
+      if (block?.type === 'tool_use') {
+        const toolUse = { id: block.id, name: block.name };
+        if (block.name === 'Bash' && typeof block.input?.command === 'string') {
+          toolUse.command = block.input.command;
+        }
+        toolUses.push(toolUse);
+      }
     }
   }
-  return toolUses;
+  return { toolUses, complete };
 }
 
 export function decideDispatcherStop({ state, toolUses }) {

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

@@ -1,73 +1,162 @@
-/** 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';
+/** records whether hosts and dispatchers keep the handback contract, per cause, over the observation ledger
+ * Plan_67 D8 cures the eternal-warning defect with cause-specific evidence; D9 keeps old untyped
+ * alarms without dispatcher evidence in legacy history, never as confirmed violations.
+ */
 import path from 'node:path';
-import { writeHomeJsonAtomic } from './atomic-json.mjs';
-import { parseJsonText } from './json-file.mjs';
-import { withHomeFileLock } from './file-lock.mjs';
-import { stateDirWriter } from './home-write.mjs';
 import { transcriptHostVersion } from './host-version.mjs';
+import {
+  emptyLedger, normalizeLedger, readLedgerFile, reduceObservation, updateLedgerFile,
+} from './observation-ledger.mjs';
 
 export const WITNESS_FILE = 'handback-witness.json';
+export const WITNESS_CAUSES = Object.freeze(['missing-agent-type', 'missing-ids', 'tools-outside-gate']);
 
 export async function witnessHostVersion(payload) {
   return transcriptHostVersion(payload?.transcript_path);
 }
 
-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)
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const hostMap = (value) => object(value) && Object.values(value).every((at) => typeof at === 'string');
+const alarmEntry = (entry) => object(entry)
+  && (entry.hostVersion === null || typeof entry.hostVersion === 'string')
+  && typeof entry.at === 'string' && typeof entry.detail === 'string';
+
+function emptyWitness() {
+  return { version: 2, ledger: emptyLedger(), intercepted: {}, legacy: [] };
+}
+
+export function witnessKey({ cause, hostVersion, agentType }) {
+  if (!WITNESS_CAUSES.includes(cause)) throw new TypeError('cause must be a witness cause');
+  if (hostVersion != null && typeof hostVersion !== 'string') {
+    throw new TypeError('hostVersion must be a string or null');
+  }
+  const host = hostVersion || 'unknown';
+  if (cause === 'missing-agent-type') return `${host}|${cause}`;
+  if (typeof agentType !== 'string' || agentType.length === 0) {
+    throw new TypeError('agentType is required for this witness cause');
+  }
+  return `${host}|${agentType}|${cause}`;
+}
+
+// Preserve the previous normalizer's accepted host-map and SDK shapes. SDK versions are not hosts.
+function normalizeOldWitness(record) {
+  if (!object(record) || !Array.isArray(record.alarms)) return null;
+  if (record.alarms.every(alarmEntry) && hostMap(record.lastSeen)
+    && !Object.hasOwn(record.lastSeen, 'sdkVersion') && !Object.hasOwn(record.lastSeen, 'at')) return record;
+  const legacy = record.lastSeen === null || (object(record.lastSeen)
+    && typeof record.lastSeen.sdkVersion === 'string' && typeof record.lastSeen.at === 'string');
+  const legacyAlarm = (entry) => object(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 })) };
+  if (legacy && record.alarms.every(legacyAlarm)) {
+    return { lastSeen: {}, alarms: record.alarms.map(({ at, detail }) => ({ hostVersion: null, at, detail })) };
+  }
   return null;
 }
 
-export function readHandbackWitness({ stateDir }) {
-  const file = path.join(stateDir, WITNESS_FILE);
-  let source;
-  try {
-    source = fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return { lastSeen: {}, alarms: [] };
-    return { corrupt: true };
+function normalizeWitnessLedger(parsed) {
+  const ledger = normalizeLedger(parsed);
+  if (!ledger) return null;
+  for (const entry of Object.values(ledger.entries)) {
+    for (const observation of [entry.lastObservation, entry.lastViolation, entry.lastMatch, ...entry.history]) {
+      if (observation === null) continue;
+      const data = observation.data;
+      if (!data || Object.getPrototypeOf(data) !== Object.prototype || !WITNESS_CAUSES.includes(data.cause)
+        || !(data.hostVersion === null || typeof data.hostVersion === 'string')
+        || !(data.agentType === null || typeof data.agentType === 'string')) return null;
+    }
   }
-  try {
-    const record = parseJsonText(file, source);
-    return normalizeWitness(record) || { corrupt: true };
-  } catch {
-    return { corrupt: true };
+  return ledger;
+}
+
+export function migrateWitness(parsed) {
+  if (object(parsed) && Object.hasOwn(parsed, 'version')) {
+    return parsed.version === 2 && normalizeWitnessLedger(parsed.ledger) && hostMap(parsed.intercepted)
+      && Array.isArray(parsed.legacy) && parsed.legacy.every((entry) => alarmEntry(entry)
+        && ['legacy-untyped-unverified', 'unclassified'].includes(entry.disposition)) ? parsed : null;
+  }
+  const old = normalizeOldWitness(parsed);
+  if (!old) return null;
+  const record = { ...emptyWitness(), intercepted: { ...old.lastSeen } };
+  const alarms = [...old.alarms].sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  for (const { at, hostVersion, detail } of alarms) {
+    if (/^host omitted agent_type for agent \S+$/.test(detail)) {
+      // D9: old stops lack dispatcher evidence; reclassification must not manufacture a violation.
+      record.legacy.push({ at, hostVersion, detail, disposition: 'legacy-untyped-unverified' });
+      continue;
+    }
+    const ids = /^host omitted session_id or agent_id for (\S+)$/.exec(detail);
+    const tools = /^(\S+) (\S+): (.+) outside the dispatcher gate$/.exec(detail);
+    if (!ids && !tools) {
+      record.legacy.push({ at, hostVersion, detail, disposition: 'unclassified' });
+      continue;
+    }
+    const cause = ids ? 'missing-ids' : 'tools-outside-gate';
+    const agentType = (ids || tools)[1];
+    try {
+      record.ledger = reduceObservation(record.ledger, {
+        key: witnessKey({ cause, hostVersion, agentType }), verdict: 'violation', at, detail,
+        data: { cause, hostVersion, agentType },
+      });
+    } catch {
+      return null;
+    }
   }
+  return record;
 }
 
-function timestamp(now) {
-  return new Date(now).toISOString();
+// readLedgerFile returns an empty ledger for ENOENT, even when its normalizer is an adapter.
+function witnessRecord(record) {
+  return record.version !== 2 && record.format === 1 ? emptyWitness() : record;
 }
 
+export function readHandbackWitness({ stateDir }) {
+  return witnessRecord(readLedgerFile(path.join(stateDir, WITNESS_FILE), { normalize: migrateWitness }));
+}
 
-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'");
+function validateHost(hostVersion) {
   if (hostVersion !== null && typeof hostVersion !== 'string') {
     throw new TypeError('hostVersion must be a string or null');
   }
-  const file = path.join(stateDir, WITNESS_FILE);
-  // 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: 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' });
+}
+
+export async function recordWitnessObservation({
+  stateDir, cause, hostVersion, agentType = null, verdict, detail = '', now = new Date(),
+}) {
+  return recordWitnessObservations({
+    stateDir, observations: [{ cause, hostVersion, agentType, verdict, detail }], now,
+  });
+}
+
+export async function recordWitnessObservations({ stateDir, observations, now = new Date() }) {
+  const prepared = observations.map(({ cause, hostVersion, agentType = null, verdict, detail = '' }) => {
+    validateHost(hostVersion);
+    const key = witnessKey({ cause, hostVersion, agentType });
+    if (agentType !== null && (typeof agentType !== 'string' || agentType.length === 0)) {
+      throw new TypeError('agentType must be a non-empty string or null');
+    }
+    return { key, verdict, detail, data: { cause, hostVersion, agentType } };
+  });
+  const at = new Date(now).toISOString();
+  return updateLedgerFile({
+    stateDir, id: 'handback-witness', file: path.join(stateDir, WITNESS_FILE), normalize: migrateWitness,
+    update: (current) => {
+      const record = witnessRecord(current);
+      return { ...record, ledger: prepared.reduce((ledger, observation) =>
+        reduceObservation(ledger, { ...observation, at }), record.ledger) };
+    },
+  });
+}
+
+export async function recordInterceptedAttempt({ stateDir, hostVersion, now = new Date() }) {
+  validateHost(hostVersion);
+  const at = new Date(now).toISOString();
+  return updateLedgerFile({
+    stateDir, id: 'handback-witness', file: path.join(stateDir, WITNESS_FILE), normalize: migrateWitness,
+    update: (current) => {
+      const record = witnessRecord(current);
+      // D8: even denied handbacks are intercepted, so this timestamp is never match evidence.
+      return { ...record, intercepted: { ...record.intercepted, [hostVersion || 'unknown']: at } };
+    },
+  });
 }

package/src/home/lib/home-registry.mjs

@@ -83,6 +83,13 @@ const entries = [
     primary: ['state/handback-witness.json'],
     sides: ['lock', 'atomic-temporary'],
   },
+  {
+    id: 'dispatcher-model',
+    removal: 'purge-only',
+    consequence: 'Doctor forgets which model each dispatcher type was last observed on and every model violation it recorded.',
+    primary: ['state/dispatcher-model.json'],
+    sides: ['lock', 'atomic-temporary'],
+  },
   {
     id: 'host-observations',
     removal: 'purge-only',

package/src/home/lib/install-owner-roots.mjs

@@ -0,0 +1,53 @@
+/**
+ * Reads which host roots own this home from the installation record, read-only, for hooks.
+ * Plan_67 D10 needs every recorded owner; the home image has no cli/ modules.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeArtifact } from './home-registry.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+export function isFormat2(parsed) {
+  return isObject(parsed) && parsed.format === 2;
+}
+
+export function readOwnerRoots({ brandRoot }) {
+  const file = path.join(brandRoot, homeArtifact('install-record').primary[0]);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT'
+      ? { problem: 'missing', detail: `Installation record at ${file} is missing.` }
+      : { problem: 'unreadable', detail: `Installation record at ${file} cannot be read.` };
+  }
+
+  let parsed;
+  try {
+    parsed = parseJsonText(file, raw);
+  } catch {
+    return { problem: 'unreadable', detail: `Installation record at ${file} contains invalid JSON.` };
+  }
+  if (!isFormat2(parsed)) {
+    return { problem: 'not-format-2', detail: `Installation record at ${file} is not format 2.` };
+  }
+  if (parsed.inventory !== 'complete') {
+    return { problem: 'inventory-incomplete', detail: `Installation record at ${file} has an incomplete inventory.` };
+  }
+  if (Object.hasOwn(parsed, 'legacy')) {
+    return { problem: 'legacy-partition', detail: `Installation record at ${file} contains a legacy partition.` };
+  }
+  if (!isObject(parsed.owners) || Object.keys(parsed.owners).length === 0) {
+    return { problem: 'no-owners', detail: `Installation record at ${file} has no owners.` };
+  }
+  const roots = [];
+  for (const owner of Object.values(parsed.owners)) {
+    if (typeof owner?.root !== 'string' || owner.root.trim().length === 0) {
+      return { problem: 'malformed-owner', detail: `Installation record at ${file} has an owner without a non-empty root.` };
+    }
+    roots.push(owner.root);
+  }
+  return { roots: roots.sort() };
+}

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

@@ -0,0 +1,171 @@
+/**
+ * Locks the kernel releases on its holder's death, shared by the lifecycle lock and the order claim.
+ * Plan_60 D4: on 2026-09-24 two launchers with one order id started 2.8 seconds apart and both ran
+ * and billed; the runner needs the lifecycle lock's primitive and may not import `cli/`.
+ * Where the kernel can release a lock on the holder's death, the lock is a kernel object: a named
+ * pipe on Windows, an abstract socket on Linux — both reproduced on real machines (hard kill, name
+ * free at once, nothing on disk), which matters on a machine that lost power six times in two weeks.
+ * The name comes from the directory's dev+ino, not its path: aliases must reach the same claim.
+ * A second listen inside the holder must fail, or the platform did not give exclusivity and the
+ * call refuses rather than switch protocols (Plan_65 D5/D8). What the holder answers a waiter is
+ * diagnosis only — it never grants anything.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+export function kernelLockStrategy(platform = process.platform) {
+  if (platform === 'win32') return 'named-pipe';
+  return platform === 'linux' ? 'abstract-socket' : null;
+}
+
+export function kernelLockAddress(purpose, digest, platform = process.platform) {
+  if (typeof purpose !== 'string' || !/^[a-z][a-z-]*$/.test(purpose)) {
+    throw new TypeError('purpose must match ^[a-z][a-z-]*$');
+  }
+  if (platform === 'win32') return `\\\\.\\pipe\\codex-bridge-${purpose}-${digest}`;
+  return platform === 'linux' ? `\0codex-bridge-${purpose}-${digest}` : null;
+}
+
+export function directoryDigest(directory, { suffix } = {}) {
+  try {
+    const stat = fs.statSync(directory, { bigint: true });
+    if (!stat.isDirectory()) throw new Error(`${directory} is not a directory`);
+    const identity = `${stat.dev}:${stat.ino}`;
+    const extra = typeof suffix === 'string' && suffix.length > 0 ? `:${suffix}` : '';
+    return createHash('sha256').update(identity + extra).digest('hex');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function listen(server, address) {
+  return new Promise((resolve, reject) => {
+    const listening = () => { server.removeListener('error', failed); resolve(); };
+    const failed = (error) => { server.removeListener('listening', listening); reject(error); };
+    server.once('listening', listening);
+    server.once('error', failed);
+    try {
+      server.listen(address);
+    } catch (error) {
+      server.removeListener('listening', listening);
+      server.removeListener('error', failed);
+      reject(error);
+    }
+  });
+}
+
+function closeServer(server) {
+  if (!server) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    try {
+      server.close((error) => {
+        if (error && error.code !== 'ERR_SERVER_NOT_RUNNING') reject(error);
+        else resolve();
+      });
+    } catch (error) {
+      if (error.code === 'ERR_SERVER_NOT_RUNNING') resolve();
+      else reject(error);
+    }
+  });
+}
+
+async function closeQuietly(server) {
+  try { await closeServer(server); } catch { /* Preserve the original failure. */ }
+}
+
+async function selfCheck(server, address, createServer, label) {
+  let probe;
+  let detail;
+  try {
+    probe = createServer();
+    await listen(probe, address);
+    detail = 'a second listener succeeded';
+  } catch (error) {
+    if (!error || error.code !== 'EADDRINUSE') detail = (error && (error.code || error.message)) || String(error);
+  }
+  if (detail === undefined) {
+    await closeQuietly(probe);
+    return;
+  }
+  await Promise.all([closeQuietly(probe), closeQuietly(server)]);
+  throw new Error(`${label} self-check failed: ${detail}`);
+}
+
+export async function tryHoldSocket(address, createServer = net.createServer, label = 'kernel lock') {
+  const server = createServer((socket) => socket.destroy());
+  try {
+    await listen(server, address);
+    await selfCheck(server, address, createServer, label);
+    let releasePromise;
+    return () => (releasePromise ??= closeServer(server));
+  } catch (error) {
+    await closeQuietly(server);
+    if (error?.code === 'EADDRINUSE') return 'in-use';
+    throw error;
+  }
+}
+
+function readSocketHolder(address, timeoutMs, parseAnswer) {
+  return new Promise((resolve) => {
+    let data = '';
+    let settled = false;
+    const socket = net.createConnection(address);
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    const finish = (holder) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(holder);
+    };
+    socket.on('data', (chunk) => {
+      data += chunk.toString('utf8');
+      const newline = data.indexOf('\n');
+      if (newline !== -1) finish(parseAnswer(data.slice(0, newline)));
+    });
+    socket.once('end', () => finish(parseAnswer(data)));
+    socket.once('error', () => finish(null));
+  });
+}
+
+export async function acquireKernelLock({
+  address, holder, waitMs, retryMs, answerTimeoutMs, parseAnswer, label,
+  createServer = net.createServer,
+}) {
+  const accepted = new Set();
+  const onConnection = (socket) => {
+    accepted.add(socket);
+    socket.once('close', () => accepted.delete(socket));
+    socket.end(`${JSON.stringify(holder)}\n`);
+  };
+  const deadline = Date.now() + waitMs;
+
+  for (;;) {
+    const server = createServer(onConnection);
+    try {
+      await listen(server, address);
+      holder.acquiredAt = new Date().toISOString();
+      await selfCheck(server, address, createServer, label);
+      server.unref();
+      let releasePromise;
+      const release = async () => {
+        const closing = closeServer(server);
+        for (const socket of accepted) socket.destroy();
+        await closing;
+      };
+      return { held: true, release: () => (releasePromise ??= release()) };
+    } catch (error) {
+      await closeQuietly(server);
+      if (!error || error.code !== 'EADDRINUSE') throw error;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await wait(Math.min(retryMs, remaining));
+    }
+  }
+
+  return { held: false, holder: await readSocketHolder(address, answerTimeoutMs, parseAnswer) };
+}

package/src/home/lib/meta/chain.mjs

@@ -12,6 +12,10 @@ import { createHash } from 'node:crypto';
 import { startedRuns } from './pre-start.mjs';
 import { normalizePath, readJson } from './paths.mjs';
 
+// Plan_75 D5: 2 hashes the header-free body. Runs without this field used earlier schemes:
+// the whole task text, then the task without grant lines (Plan_75 P1).
+export const TASK_HASH_SCHEME = 2;
+
 /**
  * What makes two runs the same task when their names disagree.
  *
@@ -21,6 +25,8 @@ import { normalizePath, readJson } from './paths.mjs';
  * built to refuse. Whitespace and case are normalized away because the same order re-sent
  * through a shell is rewrapped, not rewritten; anything more forgiving would tie together
  * tasks that merely look alike.
+ * Plan_75 D5: the runner supplies the header-free body; every body line counts, including
+ * prose beginning with a grant label. Stripping it again would silently change identity.
  */
 export const taskFingerprint = (taskText) => {
   const normalized = String(taskText ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
@@ -35,14 +41,19 @@ export const taskFingerprint = (taskText) => {
  * honestly, changed nothing and was told it had done no work. Folder names rather than
  * full paths; the current run joins the list as soon as its status.json exists.
  */
-export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '') {
+export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '', grantRun = '') {
   const wantedRepo = normalizePath(repo);
-  const wantedSlug = String(slug ?? '').trim().toLowerCase();
-  const wantedHash = String(taskHash ?? '').trim().toLowerCase();
-  const wantedOrderId = String(orderId ?? '').trim();
+  if (!wantedRepo) return [];
+  const namedStatus = typeof grantRun === 'string' && grantRun &&
+    !/[\\/]/.test(grantRun) && grantRun !== '.' && grantRun !== '..'
+    ? readJson(path.join(runsRoot, grantRun, 'status.json')) : null;
+  const namedRun = namedStatus && normalizePath(namedStatus.repo) === wantedRepo ? namedStatus : null;
+  const wantedSlugs = new Set([slug, namedRun?.slug].map((value) => String(value ?? '').trim().toLowerCase()).filter(Boolean));
+  const wantedHashes = new Set([taskHash, namedRun?.task_hash].map((value) => String(value ?? '').trim().toLowerCase()).filter(Boolean));
+  const wantedOrderIds = new Set([orderId, namedRun?.order_id].map((value) => String(value ?? '').trim()).filter(Boolean));
   // No handle on the task, or no repo, means nothing to chain — an empty context must find
   // nothing rather than fall back to "every run in this folder".
-  if (!wantedRepo || (!wantedSlug && !wantedHash && !wantedOrderId)) return [];
+  if (!wantedSlugs.size && !wantedHashes.size && !wantedOrderIds.size) return [];
   let entries;
   try {
     entries = fs.readdirSync(runsRoot, { withFileTypes: true });
@@ -56,9 +67,9 @@ export function chainRuns(runsRoot, repo, slug, taskHash = '', orderId = '') {
     if (!status) continue;
     // Either handle identifies the task. The hash catches a repeat that renamed itself; the
     // slug still catches the follow-up whose wording the orchestrator edited on purpose.
-    const sameSlug = Boolean(wantedSlug) && String(status.slug ?? '').trim().toLowerCase() === wantedSlug;
-    const sameTask = Boolean(wantedHash) && String(status.task_hash ?? '').trim().toLowerCase() === wantedHash;
-    const sameOrder = Boolean(wantedOrderId) && String(status.order_id ?? '').trim() === wantedOrderId;
+    const sameSlug = wantedSlugs.has(String(status.slug ?? '').trim().toLowerCase());
+    const sameTask = wantedHashes.has(String(status.task_hash ?? '').trim().toLowerCase());
+    const sameOrder = wantedOrderIds.has(String(status.order_id ?? '').trim());
     if (!sameSlug && !sameTask && !sameOrder) continue;
     if (normalizePath(status.repo) !== wantedRepo) continue;
     runs.push({ name: entry.name, at: String(status.started_at || '') });