@lyupro/codex-bridge 0.6.8 → 0.6.10

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-command.mjs

@@ -4,7 +4,7 @@ import {
   extractValue,
   isAbsoluteTaskFilePath,
   isInputPlaceholder,
-  parseContinuationGrant,
+  parseGrant,
   REQUIRED_INPUTS,
 } from './required-inputs.mjs';
 import { firstShellUnsafeSequence } from './shell-unsafe.mjs';
@@ -69,7 +69,9 @@ export function canonicalRunCommand(agentType, promptText) {
   tokens.push('--order-id', quote(inputs.get('order id')));
   tokens.push('--task-file', quote(inputs.get('task file')));
   if (inputs.get('effort')) tokens.push('--effort', quote(inputs.get('effort')));
-  if (parseContinuationGrant(promptText)) tokens.push('--continue');
+  // Plan_75 D1, TradeForge capacity incident: forward either grant; the runner owns conflicting-grant refusal.
+  const grant = parseGrant(promptText);
+  if (grant?.kind || grant?.error) tokens.push('--continue');
   return { command: tokens.join(' ') };
 }
 

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,9 +1,10 @@
 /** 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';
@@ -57,14 +58,16 @@ export async function recordHandbackWitness({ stateDir, kind, hostVersion, detai
     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: hostVersion === null ? current.lastSeen : { ...current.lastSeen, [hostVersion]: at } }
       : { ...current, alarms: [...current.alarms, { hostVersion, at, detail }].slice(-20) };
-    writeJsonAtomic(file, record);
+    writeHomeJsonAtomic(writer, 'handback-witness', file, record);
     return record;
   }, { description: 'handback witness' });
 }

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

@@ -0,0 +1,211 @@
+/**
+ * Declares every file the package may write into its home, each with the removal class it belongs to.
+ *
+ * `uninstall` removed only what the installation record listed, and until 0.6.7 said nothing about
+ * the rest: `state/` fell out of its message, and every next file a feature added would have too
+ * (Plan_62 D22). A registry the writers must name makes an undeclared file unwritable instead of
+ * forgotten. Side files (locks, temporaries) are spelled here and nowhere else, because a purge that
+ * knows the target but not its `.lock` leaves the lock behind. Image members are supplied by the
+ * caller: the home image ships without `cli/`, so this module cannot read the manifest itself.
+ */
+import path from 'node:path';
+
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}';
+
+// Plan_62 D22 requires side files to be as explicit as their owning artifacts.
+const SIDE_SPELLINGS = Object.freeze({
+  lock: /^(.+)\.lock$/,
+  'clear-gate': /^(.+)\.lock\.clear$/,
+  'atomic-temporary': new RegExp(`^(.+)\\.${UUID}\\.tmp$`),
+  'dot-temporary': new RegExp(`^\\.(.+)\\.${UUID}\\.tmp$`),
+  'copy-temporary': new RegExp(`^\\.(.+)\\.${UUID}\\.tmp$`),
+  'pid-temporary': new RegExp(`^(.+)\\.[0-9]+\\.${UUID}\\.tmp$`),
+});
+
+const entries = [
+  {
+    id: 'install-image',
+    removal: 'install-owned',
+    consequence: "The package's code and guards; reinstall restores them.",
+    primary: [],
+    sides: ['copy-temporary'],
+  },
+  {
+    id: 'install-record',
+    removal: 'install-owned',
+    consequence: 'The installation record is lost and uninstall can no longer identify installed files.',
+    primary: ['.installed.json'],
+    sides: ['lock', 'clear-gate', 'atomic-temporary'],
+  },
+  {
+    id: 'config',
+    removal: 'purge-only',
+    consequence: "The operator's model and retention settings are lost.",
+    primary: ['config.json'],
+    sides: ['lock', 'dot-temporary'],
+  },
+  {
+    id: 'conventions',
+    removal: 'purge-only',
+    consequence: "The operator's edited conventions are lost.",
+    primary: ['conventions.md'],
+    // Plan_65 B9: install seeds it through the planned-file copier, which publishes via a temporary.
+    sides: ['copy-temporary'],
+  },
+  {
+    id: 'host-contract',
+    removal: 'purge-only',
+    consequence: 'Refusal measurements are lost and collecting them again costs a paid probe of about two minutes of Claude quota.',
+    primary: ['.host-contract.json'],
+    sides: ['pid-temporary'],
+  },
+  {
+    id: 'dispatcher-contract',
+    removal: 'purge-only',
+    consequence: 'Dispatcher contract measurements are lost and collecting them again costs a paid probe of about two minutes of Claude quota.',
+    primary: ['state/dispatcher-contract.json'],
+    sides: ['atomic-temporary'],
+  },
+  {
+    id: 'dispatcher-state',
+    removal: 'purge-only',
+    consequence: 'A dispatcher still running loses the runner output its handback is replaced with.',
+    primary: {
+      dir: 'state/dispatchers',
+      pattern: /^[0-9a-f]{32}\.json$/,
+    },
+    sides: ['lock', 'atomic-temporary'],
+  },
+  {
+    id: 'handback-witness',
+    removal: 'purge-only',
+    consequence: 'Doctor forgets on which host a handback was last seen and every alarm it recorded.',
+    primary: ['state/handback-witness.json'],
+    sides: ['lock', 'atomic-temporary'],
+  },
+  {
+    id: 'host-observations',
+    removal: 'purge-only',
+    consequence: 'Doctor forgets which host versions sessions ran on until the next shell command in a session.',
+    primary: ['state/host-observations.json'],
+    sides: ['lock', 'atomic-temporary'],
+  },
+  {
+    id: 'guard-tries',
+    removal: 'purge-only',
+    consequence: 'Guard budgets start over.',
+    primary: ['state/reply-guard-tries.json'],
+    sides: [],
+  },
+  {
+    id: 'diagnostics',
+    removal: 'purge-only',
+    consequence: 'This artifact holds the full hook input of the last call.',
+    primary: ['state/diagnostics/order-gate.last.json', 'state/diagnostics/reply-guard.last.json'],
+    sides: [],
+  },
+];
+
+export const HOME_ARTIFACTS = Object.freeze(entries.map((entry) => Object.freeze({
+  ...entry,
+  primary: Array.isArray(entry.primary)
+    ? Object.freeze([...entry.primary])
+    : Object.freeze({
+      dir: entry.primary.dir,
+      pattern: Object.freeze(new RegExp(entry.primary.pattern.source, entry.primary.pattern.flags)),
+    }),
+  sides: Object.freeze([...entry.sides]),
+})));
+
+export const HOME_DIRECTORIES = Object.freeze([
+  'state',
+  'state/dispatchers',
+  'state/diagnostics',
+]);
+
+const artifactsById = new Map(HOME_ARTIFACTS.map((entry) => [entry.id, entry]));
+
+function validRelativePath(relativePath) {
+  if (typeof relativePath !== 'string' || relativePath.length === 0) return false;
+  if (relativePath.includes('\\') || path.posix.isAbsolute(relativePath) || path.win32.isAbsolute(relativePath)) {
+    return false;
+  }
+  return !relativePath.split('/').some((segment) => (
+    segment.length === 0 || segment === '.' || segment === '..'
+  ));
+}
+
+function imagePathSet(imageMembers) {
+  const paths = new Set();
+  for (const relativePath of imageMembers ?? []) {
+    if (validRelativePath(relativePath)) paths.add(relativePath);
+  }
+  return paths;
+}
+
+function primaryMatches(entry, relativePath) {
+  if (Array.isArray(entry.primary)) return entry.primary.includes(relativePath);
+  const slash = relativePath.lastIndexOf('/');
+  const dir = slash < 0 ? '' : relativePath.slice(0, slash);
+  const name = slash < 0 ? relativePath : relativePath.slice(slash + 1);
+  return dir === entry.primary.dir && entry.primary.pattern.test(name);
+}
+
+function sideMatches(entry, relativePath) {
+  const slash = relativePath.lastIndexOf('/');
+  const dir = slash < 0 ? '' : relativePath.slice(0, slash);
+  const name = slash < 0 ? relativePath : relativePath.slice(slash + 1);
+  for (const side of entry.sides) {
+    const match = SIDE_SPELLINGS[side].exec(name);
+    if (!match) continue;
+    const primaryName = match[1];
+    const primaryPath = dir ? `${dir}/${primaryName}` : primaryName;
+    if (primaryMatches(entry, primaryPath)) return side;
+  }
+  return null;
+}
+
+export function classifyHomePath(relativePath, { imageMembers } = {}) {
+  if (!validRelativePath(relativePath)) return null;
+  const images = imagePathSet(imageMembers);
+
+  for (const entry of HOME_ARTIFACTS) {
+    if (entry.id === 'install-image') continue;
+    if (primaryMatches(entry, relativePath)) return { id: entry.id, role: 'primary' };
+  }
+  for (const entry of HOME_ARTIFACTS) {
+    if (entry.id === 'install-image') continue;
+    const role = sideMatches(entry, relativePath);
+    if (role) return { id: entry.id, role };
+  }
+
+  if (images.has(relativePath)) return { id: 'install-image', role: 'primary' };
+  const imageArtifact = artifactsById.get('install-image');
+  const role = sideMatches({ ...imageArtifact, primary: [...images] }, relativePath);
+  return role ? { id: 'install-image', role } : null;
+}
+
+export function homeArtifact(id) {
+  const entry = artifactsById.get(id);
+  if (!entry) throw new Error(`Unknown home artifact id: ${id}`);
+  return entry;
+}
+
+export function directoryArtifact(relativeDirectory, { imageMembers } = {}) {
+  if (relativeDirectory === '') return 'install-image';
+  if (!validRelativePath(relativeDirectory)) return null;
+  const prefix = `${relativeDirectory}/`;
+  if (!HOME_DIRECTORIES.includes(relativeDirectory)
+    && [...imagePathSet(imageMembers)].some((member) => member.startsWith(prefix))) {
+    return 'install-image';
+  }
+  for (const entry of HOME_ARTIFACTS) {
+    const containsArtifact = Array.isArray(entry.primary)
+      ? entry.primary.some((primary) => primary.startsWith(prefix))
+      : entry.primary.dir === relativeDirectory || entry.primary.dir.startsWith(prefix);
+    if (containsArtifact) {
+      return entry.id;
+    }
+  }
+  return null;
+}