@lyupro/codex-bridge 0.6.8 → 0.6.9

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;
+}

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

@@ -0,0 +1,189 @@
+/**
+ * Performs a write into the package home only when the path belongs to the artifact id it names.
+ *
+ * The registry alone is a list someone can forget to consult; routing the write through it is what
+ * makes `uninstall --purge` complete by construction (Plan_62 D22). The check is lexical and
+ * in-memory — no lock, no stat, no listing — because hooks call it on every shell command of every
+ * session, and links are deliberately not resolved, as everywhere else in the package.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { classifyHomePath, HOME_ARTIFACTS, HOME_DIRECTORIES } from './home-registry.mjs';
+
+function registryError(id, absolutePath, reason) {
+  const error = new Error(`Home artifact "${id}" refused path "${absolutePath}": ${reason}`);
+  error.code = 'EHOMEREGISTRY';
+  return error;
+}
+
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function homeRelativePath(root, id, absolutePath) {
+  if (typeof absolutePath !== 'string' || !path.isAbsolute(absolutePath)) {
+    throw registryError(id, absolutePath, 'an absolute path is required');
+  }
+  const relativeNative = path.relative(root, absolutePath);
+  if (
+    path.isAbsolute(relativeNative)
+    || relativeNative === '..'
+    || relativeNative.startsWith(`..${path.sep}`)
+  ) {
+    throw registryError(id, absolutePath, 'path is outside the home root');
+  }
+  return toPosix(relativeNative);
+}
+
+function directoryContainsArtifact(entry, relativeDirectory, imageMembers) {
+  if (Array.isArray(entry.primary)) {
+    if (entry.primary.some((candidate) => candidate.startsWith(`${relativeDirectory}/`))) return true;
+  } else if (
+    entry.primary.dir === relativeDirectory
+    || entry.primary.dir.startsWith(`${relativeDirectory}/`)
+  ) {
+    return true;
+  }
+
+  if (entry.id === 'install-image') {
+    return imageMembers.some((candidate) => candidate.startsWith(`${relativeDirectory}/`));
+  }
+  return false;
+}
+
+function directoryIsAllowed(id, relativeDirectory, imageMembers) {
+  const entry = HOME_ARTIFACTS.find((candidate) => candidate.id === id);
+  if (!entry) return false;
+  if (relativeDirectory === '') return true;
+
+  if (
+    HOME_DIRECTORIES.includes(relativeDirectory)
+    && directoryContainsArtifact(entry, relativeDirectory, imageMembers)
+  ) {
+    return true;
+  }
+
+  // Every ancestor of an image member, not only its direct parent: the installer creates the chain
+  // recursively, and uninstall takes emptied ones down one by one (Plan_65 B15b2b — `agents/` holds
+  // only subfolders, and refusing it left an empty folder or threw mid-uninstall).
+  if (entry.id === 'install-image') {
+    return imageMembers.some((candidate) => candidate.startsWith(`${relativeDirectory}/`));
+  }
+
+  if (Array.isArray(entry.primary)) {
+    return entry.primary.some((candidate) => {
+      const slash = candidate.lastIndexOf('/');
+      const parent = slash < 0 ? '' : candidate.slice(0, slash);
+      return parent === relativeDirectory;
+    });
+  }
+  return entry.primary.dir === relativeDirectory;
+}
+
+function recursiveOptions(options) {
+  if (typeof options === 'string') return { encoding: options, recursive: true };
+  return { ...options, recursive: true };
+}
+
+/**
+ * The state modules receive `stateDir`, which is always `brandStateDir(root)` (Plan_62 D14), so the
+ * home root is its parent. A stateDir anywhere else is refused by the registry, not guessed.
+ */
+export function stateDirWriter(stateDir) {
+  return createHomeWriter({ root: path.dirname(path.resolve(stateDir)) });
+}
+
+export function createHomeWriter({ root, imageMembers } = {}) {
+  const homeRoot = path.resolve(root);
+  const declaredImageMembers = Object.freeze([...(imageMembers ?? [])]);
+
+  function assertArtifactPath(id, absolutePath) {
+    const relativePath = homeRelativePath(homeRoot, id, absolutePath);
+    const artifact = classifyHomePath(relativePath, { imageMembers: declaredImageMembers });
+    if (!artifact || artifact.id !== id) {
+      throw registryError(id, absolutePath, 'path is not declared for this artifact id');
+    }
+  }
+
+  function assertDirectoryPath(id, absolutePath) {
+    const relativeDirectory = homeRelativePath(homeRoot, id, absolutePath);
+    if (!directoryIsAllowed(id, relativeDirectory, declaredImageMembers)) {
+      throw registryError(id, absolutePath, 'directory is not an allowed artifact directory');
+    }
+  }
+
+  return {
+    // Plan_65 B2: a helper whose first write is a shared parent (`state/`) checks the target here, so a
+    // wrong id is refused before mkdir creates anything — without opening the file to find out.
+    assertArtifact(id, absolutePath) {
+      assertArtifactPath(id, absolutePath);
+    },
+    // Plan_65 B9 (advice A1, order 11): a helper that also writes outside the home — the installer's
+    // copier for Claude host files and Codex rules — takes its raw route only past this check, so the
+    // raw route can never land in the home and escape the registry.
+    assertOutside(absolutePath) {
+      if (typeof absolutePath !== 'string' || !path.isAbsolute(absolutePath)) {
+        throw registryError('outside', absolutePath, 'an absolute path is required');
+      }
+      const relativeNative = path.relative(homeRoot, absolutePath);
+      const inside = relativeNative === ''
+        || !(path.isAbsolute(relativeNative) || relativeNative === '..'
+          || relativeNative.startsWith(`..${path.sep}`));
+      if (inside) throw registryError('outside', absolutePath, 'path is inside the home root');
+    },
+    writeFileSync(id, absolutePath, ...args) {
+      assertArtifactPath(id, absolutePath);
+      return fs.writeFileSync(absolutePath, ...args);
+    },
+    writeFile(id, absolutePath, ...args) {
+      assertArtifactPath(id, absolutePath);
+      return fs.promises.writeFile(absolutePath, ...args);
+    },
+    mkdirSync(id, absolutePath, options) {
+      assertDirectoryPath(id, absolutePath);
+      return fs.mkdirSync(absolutePath, recursiveOptions(options));
+    },
+    mkdir(id, absolutePath, options) {
+      assertDirectoryPath(id, absolutePath);
+      return fs.promises.mkdir(absolutePath, recursiveOptions(options));
+    },
+    openSync(id, absolutePath, ...args) {
+      assertArtifactPath(id, absolutePath);
+      return fs.openSync(absolutePath, ...args);
+    },
+    open(id, absolutePath, ...args) {
+      assertArtifactPath(id, absolutePath);
+      return fs.promises.open(absolutePath, ...args);
+    },
+    renameSync(id, oldAbsolutePath, newAbsolutePath) {
+      assertArtifactPath(id, oldAbsolutePath);
+      assertArtifactPath(id, newAbsolutePath);
+      return fs.renameSync(oldAbsolutePath, newAbsolutePath);
+    },
+    rename(id, oldAbsolutePath, newAbsolutePath) {
+      assertArtifactPath(id, oldAbsolutePath);
+      assertArtifactPath(id, newAbsolutePath);
+      return fs.promises.rename(oldAbsolutePath, newAbsolutePath);
+    },
+    copyFile(id, sourceAbsolutePath, destinationAbsolutePath, ...args) {
+      assertArtifactPath(id, destinationAbsolutePath);
+      return fs.promises.copyFile(sourceAbsolutePath, destinationAbsolutePath, ...args);
+    },
+    unlinkSync(id, absolutePath) {
+      assertArtifactPath(id, absolutePath);
+      return fs.unlinkSync(absolutePath);
+    },
+    unlink(id, absolutePath) {
+      assertArtifactPath(id, absolutePath);
+      return fs.promises.unlink(absolutePath);
+    },
+    rmdirSync(id, absolutePath) {
+      assertDirectoryPath(id, absolutePath);
+      return fs.rmdirSync(absolutePath);
+    },
+    async rmdir(id, absolutePath) {
+      assertDirectoryPath(id, absolutePath);
+      return fs.promises.rmdir(absolutePath);
+    },
+  };
+}

package/src/home/lib/hook-diagnostics.mjs

@@ -0,0 +1,20 @@
+/**
+ * Records the last hook input through the home artifact registry. Plan_65 B3 consolidates two
+ * duplicated direct writes whose paths must remain purgeable and whose failures must stay fail-open.
+ */
+import path from 'node:path';
+import { BRAND_HOME, brandStateDir } from './brand-home.mjs';
+import { createHomeWriter } from './home-write.mjs';
+
+export function recordHookDiagnostic(hookName, input, { root = BRAND_HOME.root } = {}) {
+  try {
+    const diagnosticsDir = path.join(brandStateDir(root), 'diagnostics');
+    const diagnosticFile = path.join(diagnosticsDir, `${hookName}.last.json`);
+    const writer = createHomeWriter({ root });
+    writer.assertArtifact('diagnostics', diagnosticFile);
+    writer.mkdirSync('diagnostics', diagnosticsDir, { recursive: true });
+    writer.writeFileSync('diagnostics', diagnosticFile, `${JSON.stringify(input, null, 2)}\n`);
+  } catch {
+    // Diagnostics are a convenience, never a reason to fail the turn.
+  }
+}

package/src/home/lib/host-observations.mjs

@@ -1,8 +1,9 @@
 /** Records session host versions after the 2026-09-25 PATH host identity incident. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeJsonAtomic } from './atomic-json.mjs';
-import { withFileLock } from './file-lock.mjs';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
 import { parseJsonText } from './json-file.mjs';
 import { transcriptHostVersion } from './host-version.mjs';
 
@@ -37,7 +38,9 @@ export async function observeSessionHost({
   if (readHostObservations({ stateDir }).sessions[sessionId]) return { recorded: false };
   const version = await readVersion(transcriptPath);
   if (version === null) return { recorded: false };
-  return withFileLock(`${file}.lock`, async () => {
+  // Plan_65 B6: the observations, their lock and temporaries are the registered host-observations artifact.
+  const writer = stateDirWriter(stateDir);
+  return withHomeFileLock(writer, 'host-observations', `${file}.lock`, async () => {
     const current = readHostObservations({ stateDir });
     if (current.corrupt) throw new Error(`Cannot update corrupt host observations: ${file}`);
     if (current.sessions[sessionId]) return { recorded: false };
@@ -51,7 +54,7 @@ export async function observeSessionHost({
     sessions[sessionId] = { version, at };
     const existing = hosts[version];
     hosts[version] = { firstSeen: existing?.firstSeen || at, lastSeen: at };
-    writeJsonAtomic(file, { hosts, sessions });
+    writeHomeJsonAtomic(writer, 'host-observations', file, { hosts, sessions });
     return { recorded: true };
   }, { description: 'host observations' });
 }

package/src/home/lib/meta/advice-status.mjs

@@ -3,11 +3,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULTS } from '../run-config.mjs';
 import { judgeAdvice } from './advice-verdict.mjs';
-import { readJson } from './paths.mjs';
+import { readJson, safeSlice } from './paths.mjs';
 
 function contractReason(reasons) {
   const message = `advice contract broken (${reasons.length}): ${reasons.slice(0, 2).join('; ')}`;
-  return message.length <= 200 ? message : `${message.slice(0, 197)}...`;
+  return message.length <= 200 ? message : `${safeSlice(message, 197)}...`;
 }
 
 export function adviceGap(runDir, result, eventData) {

package/src/home/lib/meta/advice-verdict.mjs

@@ -76,6 +76,16 @@ function* addressesIn(value, root) {
   }
 }
 
+// Plan_68 D7: `<anything>:<digits>` is not evidence of intent. On 2026-09-28 the prose "so 00:05 under
+// yesterday's log" failed a complete advise run as file `00`, line 5 — a lost pass of the quota. A left side
+// with a directory is always a claim and stays strict; a bare name is one only when that root file exists,
+// so times, ratios and host:port pass while package.json and Makefile keep the read boundary. No extension
+// test: `api.example.com:443` would fail as a file. The accepted cost — an invented bare name is not caught.
+function isCitationInProse(address, root) {
+  const file = address.match(/^(.+):\d+(?:-\d+)?$/)?.[1];
+  return file !== undefined && (/[\\/]/.test(file) || entryInRepo(root, file)?.isFile === true);
+}
+
 function citationProblem(file, start, end, root, allowed) {
   if (typeof file !== 'string' || !file) return 'use a repository-relative path:line or path:line-line address';
   const entry = entryInRepo(root, file);
@@ -126,7 +136,9 @@ function checkCitations({ phase, result, task, repoRoot, scopeResult }, reasons)
   // Structured evidence and the free-text early_check.target are handled separately below.
   for (const { field, value } of strings(result)) {
     if (/(?:^|\.)evidence(?:\[|\.|$)|\.early_check\.target$/.test(field)) continue;
-    for (const address of addressesIn(value, root)) checkAddress(field, address);
+    for (const address of addressesIn(value, root)) {
+      if (isCitationInProse(address, root)) checkAddress(field, address);
+    }
   }
   const checkEvidence = (field, evidence) => {
     for (const [index, location] of evidence.entries()) checkLocation(`${field}[${index}]`, location);
@@ -157,6 +169,22 @@ function checkCitations({ phase, result, task, repoRoot, scopeResult }, reasons)
   }
 }
 
+// Plan_68 D6: on 2026-09-27 an advise answer cut by the schema ended in U+0000 and passed as OK.
+// This is integrity, not completeness: a cut that ends on a whole character is not detectable here,
+// which is why the cause — the hidden length cap — was removed from the schema instead.
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/;
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const codePoint = (char) => `U+${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, '0')}`;
+
+function integrityProblems(result, reasons) {
+  for (const { field, value } of strings(result)) {
+    const control = value.match(CONTROL)?.[0];
+    const surrogate = value.match(LONE_SURROGATE)?.[0];
+    if (control) reasons.push(`integrity ${field}: remove control character ${codePoint(control)}.`);
+    else if (surrogate) reasons.push(`integrity ${field}: remove lone surrogate ${codePoint(surrogate)}.`);
+  }
+}
+
 export function judgeAdvice({ phase, result, task, repoRoot, commandsRun, language, scopeResult }) {
   if (phase !== 'scope' && phase !== 'advise') throw new RangeError('phase must be "scope" or "advise".');
   if (!Number.isInteger(commandsRun) || commandsRun < 0) {
@@ -168,6 +196,7 @@ export function judgeAdvice({ phase, result, task, repoRoot, commandsRun, langua
     throw new TypeError('result and a parsed advisor task are required.');
   }
   const reasons = [];
+  integrityProblems(result, reasons);
   if (commandsRun === 0) reasons.push('D4 commandsRun 0: inspect repository evidence before answering.');
   if (phase === 'scope') {
     if (!result.taken_on_trust.length) {

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

@@ -5,6 +5,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { safeSlice } from './paths.mjs';
 
 /**
  * Quota exhaustion, and nothing else that merely says "limit". A bare `limit` also appears in
@@ -16,7 +17,7 @@ const LIMIT_RE = /rate[\s_-]*limit|usage[\s_-]*limit|quota|too many requests|\b4
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
 
 const compact = (value, max = 300) =>
-  String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+  safeSlice(String(value ?? '').replace(/\s+/g, ' ').trim(), max);
 
 /**
  * A broken final line is expected when the runner is stopped while Codex is writing.

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

@@ -3,11 +3,21 @@
  *
  * Two sides spell the same file differently — git prints repo-relative paths with forward
  * slashes, Codex writes whatever it likes — so nothing above this module compares a path
- * before it has been through here. This is also the only module that touches the
- * filesystem for reading artifacts: everything else receives text, JSON or a byte count from it.
+ * before it has been through here. Strict snapshot judgement belongs to run-snapshots.mjs.
  */
 import fs from 'node:fs';
 import { readJsonFileSync } from '../json-file.mjs';
+import { compareSnapshots, decodeSnapshot } from './snapshot-format.mjs';
+
+/**
+ * `slice` counts UTF-16 units and can leave half of an emoji or a rare CJK character at the cut;
+ * a lone surrogate in a reply is the same kind of broken text Plan_68 D6 refuses from the model.
+ */
+export const safeSlice = (value, max) => {
+  const text = String(value ?? '').toWellFormed();
+  const result = text.slice(0, max);
+  return result.isWellFormed() ? result : result.slice(0, -1);
+};
 
 /** One line, no newlines, bounded length — a five-line reply must stay five lines. */
 export const line = (value, max = 200) => {
@@ -15,7 +25,7 @@ export const line = (value, max = 200) => {
   if (text.length <= max) return text;
 
   const ellipsis = '...';
-  if (max <= ellipsis.length) return text.slice(0, Math.max(0, max));
+  if (max <= ellipsis.length) return safeSlice(text, Math.max(0, max));
 
   const contentLimit = max - ellipsis.length;
   const boundary = text.lastIndexOf(' ', contentLimit);
@@ -24,11 +34,11 @@ export const line = (value, max = 200) => {
   // where a word ended. Dropping a trailing number here as well cost `All 298 12345678 rest`
   // its 298 — a number that fitted whole — because the digit test compared the limit rather
   // than the point the text was actually cut at.
-  if (boundary > 0) return `${text.slice(0, boundary)}${ellipsis}`;
+  if (boundary > 0) return `${safeSlice(text, boundary)}${ellipsis}`;
 
   // No space to retreat to: the limit lands inside a single long word. Only here can the cut
   // land mid-number, so only here is a partial number dropped.
-  return `${text.slice(0, contentLimit).replace(/\d+$/, '')}${ellipsis}`;
+  return `${safeSlice(text, contentLimit).replace(/\d+$/, '')}${ellipsis}`;
 };
 
 export const readText = (file) => {
@@ -60,32 +70,22 @@ export const size = (file) => {
 };
 
 /**
- * Snapshot lines are `<added>\t<deleted>\t<path>` for tracked files and `U\t<bytes>\t<path>`
- * for untracked ones — see worktreeSnapshot() in runner/git-state.mjs. Path last, state first.
+ * Tolerant display reader for reply, run-state and write-meta; invalid snapshots display
+ * an empty Map. Strict judgement goes through run-snapshots.mjs.
  */
 export const snapshotMap = (text) => {
-  const map = new Map();
-  for (const row of text.split(/\r?\n/).filter(Boolean)) {
-    const parts = row.split('\t');
-    if (parts.length < 3) continue;
-    map.set(parts.slice(2).join('\t').trim(), `${parts[0]}\t${parts[1]}`);
-  }
-  return map;
+  const snapshot = decodeSnapshot(text);
+  return snapshot.ok ? snapshot.rows : new Map();
 };
 
 /**
- * Paths Codex actually touched, by content rather than by porcelain letter: a file that
- * was already ` M` stays ` M` after further edits, so status codes would report zero
- * work. Line counts (or size, for untracked files) do change.
+ * Tolerant display reader for reply, run-state and write-meta; invalid comparisons display
+ * no changes. Strict judgement goes through run-snapshots.mjs. Snapshot states measure
+ * edits even when a file's porcelain letter stays unchanged.
  */
 export const changedPaths = (before, after) => {
-  const was = snapshotMap(before);
-  const now = snapshotMap(after);
-  const paths = [];
-  for (const [file, state] of now) if (was.get(file) !== state) paths.push(file);
-  // A path that dropped out was touched too: Codex restored it to its committed state.
-  for (const file of was.keys()) if (!now.has(file)) paths.push(file);
-  return paths;
+  const comparison = compareSnapshots(before, after);
+  return comparison.ok ? comparison.changed : [];
 };
 
 /** Directories a delegated build has no business editing, whatever the task says. */

package/src/home/lib/meta/run-snapshots.mjs

@@ -0,0 +1,29 @@
+/**
+ * Read a run's before/after snapshots and compare them strictly.
+ * On 2026-09-30 git-quoted Cyrillic names made an in-scope edit look out of scope;
+ * missing or untrustworthy snapshots must refuse judgement, never imply a clean tree.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { compareSnapshots } from './snapshot-format.mjs';
+
+export function readSnapshot(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function runSnapshotChanges(runDir) {
+  return compareSnapshots(
+    readSnapshot(path.join(runDir, 'state-before.txt')),
+    readSnapshot(path.join(runDir, 'state-after.txt')),
+  );
+}
+
+export function snapshotRefusal(comparison) {
+  const issue = comparison.side ? `${comparison.side} ${comparison.issue}` : comparison.issue;
+  return `worktree snapshots cannot be compared (${issue}): ${comparison.detail}`;
+}