@lyupro/codex-bridge 0.6.10 → 0.6.11

package/src/home/lib/observation-ledger.mjs

@@ -0,0 +1,145 @@
+/** Keeps, per key, the last observation apart from the last confirmed violation and the last confirmed match.
+ * Plan_67 D8 separates these facts to cure the eternal witness warning: an undetermined observation
+ * cannot clear a violation, while a later confirmed match can. Adapters own causes and severity.
+ */
+import fs from 'node:fs';
+import { writeHomeJsonAtomic } from './atomic-json.mjs';
+import { withHomeFileLock } from './file-lock.mjs';
+import { stateDirWriter } from './home-write.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+export const HISTORY_LIMIT = 20;
+const VERDICTS = new Set(['violation', 'match', 'undetermined']);
+const has = (object, key) => Object.hasOwn(object, key);
+const plainObject = (value) => value !== null && typeof value === 'object'
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+function fields(value, required, optional = []) {
+  return plainObject(value) && required.every((key) => has(value, key))
+    && Reflect.ownKeys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+
+function jsonValue(value, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;
+  if (typeof value === 'number') return Number.isFinite(value);
+  if ((!Array.isArray(value) && !plainObject(value)) || ancestors.has(value)) return false;
+  ancestors.add(value);
+  const valid = Array.isArray(value)
+    ? Array.from(value).every((item) => jsonValue(item, ancestors))
+    : Reflect.ownKeys(value).every((key) => typeof key === 'string' && jsonValue(value[key], ancestors));
+  ancestors.delete(value);
+  return valid;
+}
+
+function isoTimestamp(value) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) return false;
+  const parts = /^(\d{4}|[+-]\d{6})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+  if (!parts) return false;
+  const [, year, month, day, hour, minute, second] = parts.map(Number);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return month >= 1 && month <= 12 && day >= 1 && day <= days[month - 1]
+    && hour < 24 && minute < 60 && second < 60;
+}
+
+function validObservation(value, maxSeq) {
+  return fields(value, ['seq', 'verdict', 'at', 'detail'], ['data'])
+    && Number.isInteger(value.seq) && value.seq > 0 && value.seq <= maxSeq
+    && VERDICTS.has(value.verdict) && isoTimestamp(value.at) && typeof value.detail === 'string'
+    && (!has(value, 'data') || (plainObject(value.data) && jsonValue(value.data)));
+}
+
+function validEntry(entry, maxSeq) {
+  if (!fields(entry, ['lastObservation', 'lastViolation', 'lastMatch', 'history'])
+    || !validObservation(entry.lastObservation, maxSeq)
+    || !Array.isArray(entry.history) || entry.history.length > HISTORY_LIMIT) return false;
+  const lastSeq = entry.lastObservation.seq;
+  if (entry.lastViolation !== null && (!validObservation(entry.lastViolation, lastSeq)
+    || entry.lastViolation.verdict !== 'violation')) return false;
+  if (entry.lastMatch !== null && (!validObservation(entry.lastMatch, lastSeq)
+    || entry.lastMatch.verdict !== 'match')) return false;
+  let previous = 0;
+  for (const observation of entry.history) {
+    if (!validObservation(observation, lastSeq) || observation.verdict !== 'violation'
+      || observation.seq <= previous) return false;
+    previous = observation.seq;
+  }
+  if (entry.lastViolation === null ? entry.history.length !== 0 : previous !== entry.lastViolation.seq) return false;
+  const slot = entry.lastObservation.verdict === 'violation' ? entry.lastViolation
+    : entry.lastObservation.verdict === 'match' ? entry.lastMatch : null;
+  return entry.lastObservation.verdict === 'undetermined' || slot?.seq === lastSeq;
+}
+
+export function emptyLedger() {
+  return { format: 1, seq: 0, entries: {} };
+}
+
+export function normalizeLedger(parsed) {
+  if (!fields(parsed, ['format', 'seq', 'entries']) || parsed.format !== 1
+    || !Number.isInteger(parsed.seq) || parsed.seq < 0 || !plainObject(parsed.entries)) return null;
+  return Reflect.ownKeys(parsed.entries).every((key) => typeof key === 'string' && key.length > 0
+    && validEntry(parsed.entries[key], parsed.seq)) ? parsed : null;
+}
+
+export function reduceObservation(ledger, { key, verdict, at, detail, data }) {
+  if (!VERDICTS.has(verdict)) throw new TypeError('verdict must be violation, match or undetermined');
+  if (typeof key !== 'string' || key.length === 0) throw new TypeError('key must be a non-empty string');
+  if (!isoTimestamp(at)) throw new TypeError('at must be an ISO timestamp');
+  if (typeof detail !== 'string') throw new TypeError('detail must be a string');
+  if (data !== undefined && (!plainObject(data) || !jsonValue(data))) {
+    throw new TypeError('data must be a plain JSON object');
+  }
+  if (!normalizeLedger(ledger)) throw new TypeError('ledger must be a valid observation ledger');
+  const seq = ledger.seq + 1;
+  if (seq === ledger.seq) throw new TypeError('ledger sequence cannot increment');
+  const observation = { seq, verdict, at, detail };
+  if (data !== undefined) observation.data = structuredClone(data);
+  const previous = has(ledger.entries, key) ? ledger.entries[key]
+    : { lastObservation: null, lastViolation: null, lastMatch: null, history: [] };
+  const entry = { ...previous, lastObservation: observation };
+  if (verdict === 'violation') {
+    entry.lastViolation = observation;
+    entry.history = [...previous.history, observation].slice(-HISTORY_LIMIT);
+  } else if (verdict === 'match') {
+    entry.lastMatch = observation;
+  }
+  return { format: 1, seq, entries: { ...ledger.entries, [key]: entry } };
+}
+
+export function entryState(entry) {
+  if (!entry) return 'unobserved';
+  if (entry.lastViolation) {
+    return entry.lastMatch?.seq > entry.lastViolation.seq ? 'recovered' : 'violation';
+  }
+  return entry.lastMatch ? 'clean' : 'undetermined';
+}
+
+export function readLedgerFile(file, { normalize = normalizeLedger } = {}) {
+  let source;
+  try {
+    source = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT' ? emptyLedger() : { corrupt: true };
+  }
+  try {
+    return normalize(parseJsonText(file, source)) ?? { corrupt: true };
+  } catch {
+    return { corrupt: true };
+  }
+}
+
+export async function updateLedgerFile({ stateDir, id, file, normalize, update }) {
+  const writer = stateDirWriter(stateDir);
+  // Plan_67 D8: allocation of seq and publication share the registered artifact's lock.
+  return withHomeFileLock(writer, id, `${file}.lock`, async () => {
+    const current = readLedgerFile(file, { normalize });
+    if (current.corrupt) throw new Error(`Cannot update corrupt observation ledger: ${file}`);
+    const next = update(current);
+    writeHomeJsonAtomic(writer, id, file, next);
+    return next;
+  }, { description: 'observation ledger' });
+}
+
+export async function recordObservation({ stateDir, id, file, observation }) {
+  return updateLedgerFile({ stateDir, id, file, update: (current) => reduceObservation(current, observation) });
+}

package/src/home/lib/order-schema.mjs

@@ -0,0 +1,204 @@
+/**
+ * Owns the dispatcher order registry for task-file headers.
+ * Plan_63 D9: the call carries only task file, so order entries belong here without runner flags.
+ * The D1/D3 `continue: none` regression still requires one schema for all header readers.
+ */
+import { isInputPlaceholder } from './order-values.mjs';
+import { firstShellUnsafeSequence } from './shell-unsafe.mjs';
+
+const freezeEntries = (entries) => Object.freeze(entries.map((entry) => Object.freeze(entry)));
+
+export const CONTINUATION_ORDER_INPUT = Object.freeze({
+  label: 'continue',
+  explanation:
+    'The run folder this pass is ordered to continue, followed by why the orchestrator is spending another pass. A continuation is assigned by the orchestrator; after a verdict, the dispatcher returns it and stops.',
+  example: '2026-08-05_092913_plan14-build — LIMIT at step 3, tests unwritten',
+  conditional: 'when this pass continues or repeats a named run',
+});
+
+export const RETRY_ORDER_INPUT = Object.freeze({
+  label: 'retry',
+  explanation:
+    'The failed run this pass repeats, followed by why the orchestrator pays for the same pass again. A retry repeats that failed pass under its own order; it does not authorize the next pass.',
+  example: '2026-10-03_172017_cc-d66-advisor — model at capacity, same pass again',
+  conditional: 'when this pass continues or repeats a named run',
+});
+
+const REQUIRED_ORDER_INPUTS = Object.freeze({
+  'codex-scout': freezeEntries([
+    {
+      label: 'order id',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-scout-20260804',
+    },
+    CONTINUATION_ORDER_INPUT,
+    RETRY_ORDER_INPUT,
+  ]),
+  'codex-build': freezeEntries([
+    {
+      label: 'order id',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-build-20260804',
+    },
+    {
+      label: 'scope',
+      explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
+      example: 'src/home/lib/runner/**,tests/runner/**',
+    },
+    CONTINUATION_ORDER_INPUT,
+    RETRY_ORDER_INPUT,
+  ]),
+  'codex-review': freezeEntries([
+    {
+      label: 'order id',
+      explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
+      example: 'plan-13-review-20260804',
+    },
+    CONTINUATION_ORDER_INPUT,
+    RETRY_ORDER_INPUT,
+  ]),
+  // Plan_59 D7: the caller must name the phase and authorize the continued decision pass.
+  'codex-advisor': freezeEntries([
+    {
+      label: 'order id',
+      explanation: 'The label this design order is known by. Keep the same order id for scope and advise so phase 2 can settle the risks predicted in phase 1.',
+      example: 'plan-59-advisor-20260922',
+    },
+    CONTINUATION_ORDER_INPUT,
+    RETRY_ORDER_INPUT,
+    {
+      label: 'phase',
+      explanation: 'Pass scope first to predict risks and check the reading boundary, then advise with a continue: grant naming the scope run of the same order.',
+      example: 'scope',
+    },
+  ]),
+});
+
+export const ORDER_AGENTS = Object.freeze(Object.keys(REQUIRED_ORDER_INPUTS));
+
+const OPTIONAL_ORDER_INPUTS = freezeEntries([
+  {
+    label: 'repository',
+    agents: ORDER_AGENTS,
+    explanation: 'The repository the runner works in. Pass its path as a labelled value so the dispatcher needs no cd.',
+    example: 'C:/work/codex-bridge',
+  },
+  {
+    label: 'scope new',
+    agents: Object.freeze(['codex-build']),
+    explanation: 'Comma-separated globs for new files this build may create, relative to the repository root.',
+    example: 'src/home/lib/dispatcher-call.mjs,tests/dispatcher-call.test.mjs',
+  },
+  {
+    label: 'slug',
+    agents: ORDER_AGENTS,
+    explanation: 'The readable name used for the run folder. It names this pass without replacing the order id.',
+    example: 'plan-76-parser',
+  },
+  {
+    label: 'effort',
+    agents: ORDER_AGENTS,
+    explanation: 'The reasoning effort assigned to this pass. The runner checks which effort values it accepts.',
+    example: 'high',
+  },
+  {
+    label: 'changeset',
+    agents: Object.freeze(['codex-review']),
+    explanation: 'The changes to review: uncommitted, base:<branch>, or commit:<sha>. Name only the ordered changeset.',
+    example: 'base:main',
+  },
+]);
+
+const schemas = new Map(ORDER_AGENTS.map((agentType) => [agentType,
+  freezeEntries([
+    ...REQUIRED_ORDER_INPUTS[agentType],
+    ...OPTIONAL_ORDER_INPUTS.filter((entry) => entry.agents.includes(agentType))
+      .map((entry) => ({ ...entry, optional: true })),
+  ].map((entry) => ({
+    ...entry,
+    required: !entry.conditional && !entry.optional,
+    conditional: Boolean(entry.conditional),
+    optional: Boolean(entry.optional),
+  }))),
+]));
+const NO_LABELS = Object.freeze([]);
+
+export function orderLabelsFor(agentType) {
+  return schemas.get(agentType) ?? NO_LABELS;
+}
+
+export const ALL_ORDER_LABELS = Object.freeze([...new Set(
+  ORDER_AGENTS.flatMap((agentType) => orderLabelsFor(agentType).map(({ label }) => label)),
+)].sort());
+
+const inputNames = new Set(ALL_ORDER_LABELS);
+
+// Plan_63 D7: switching the order input channel changes only this function.
+export function orderInputName(label) {
+  if (!inputNames.has(label)) throw new Error(`Unknown order input label "${label}"`);
+  return `\`${label}:\``;
+}
+
+export function orderFromHeader(agentType, parsed) {
+  const order = new Map();
+  const problems = [];
+  if (!schemas.has(agentType)) {
+    problems.push({ lineNo: null, line: '', reason: `unknown dispatcher agent "${agentType}"` });
+    return { order, problems };
+  }
+
+  const labels = orderLabelsFor(agentType);
+  const accepted = new Set(labels.map(({ label }) => label));
+  for (const [label, value] of Object.entries(parsed.fields)) {
+    if (!ALL_ORDER_LABELS.includes(label)) continue;
+    // parseTaskHeader retains the first duplicate value; diagnostics must name that same line.
+    const entry = parsed.entries?.find((entry) => entry.label === label);
+    const location = entry ? { lineNo: entry.lineNo, line: entry.line }
+      : { lineNo: null, line: '' };
+    if (!accepted.has(label)) {
+      problems.push({ ...location, reason: `label "${label}" is not accepted by ${agentType}` });
+      continue;
+    }
+    // Grant values are validated by parseTaskHeader; re-reporting them would duplicate its problem.
+    if (label === 'continue' || label === 'retry') continue;
+    order.set(label, value);
+    if (isInputPlaceholder(value, label)) {
+      problems.push({ ...location, reason: `label "${label}" is still a placeholder` });
+    }
+    // Plan_63 D5: the flag-era refusal (Plan_42) keeps its pair in the header — an order value is a short
+    // identifier, so a shell sequence in it is free text written in the wrong place.
+    const sequence = firstShellUnsafeSequence(value);
+    if (sequence !== null) {
+      problems.push({ ...location, reason: `${orderInputName(label)} contains forbidden shell sequence ` +
+        `${JSON.stringify(sequence)}; put free text in the task file body and keep header values short` });
+    }
+    // Plan_63 D5: new paths cannot replace the existing-file boundary of a writing order.
+    if (agentType === 'codex-build' && label === 'scope'
+        && !value.split(',').some((pattern) => pattern.trim())) {
+      problems.push({ ...location,
+        reason: `${orderInputName(label)} is required for codex-build: declare at least one existing path pattern; ` +
+          `${orderInputName('scope new')} does not replace it.` });
+    }
+  }
+  for (const { label, required, example } of labels) {
+    if (required && !Object.hasOwn(parsed.fields, label)) {
+      problems.push({ lineNo: null, line: '',
+        reason: `missing required header label "${label}:"; example: ${label}: ${example}` });
+    }
+  }
+  return { order, problems };
+}
+
+export function renderOrderProblems(agentType, problems) {
+  return [...problems.map(({ lineNo, line, reason }) => lineNo === null
+    ? reason : `line ${lineNo}: ${reason}: ${line}`), renderOrderHeaderHelp(agentType)].join('\n');
+}
+
+export function renderOrderHeaderHelp(agentType) {
+  const labels = orderLabelsFor(agentType);
+  return [
+    ...labels.filter(({ required }) => required),
+    ...labels.filter(({ conditional }) => conditional),
+    ...labels.filter(({ optional }) => optional),
+  ].map(({ label, example }) => `${label}: ${example}`).join('\n');
+}

package/src/home/lib/order-values.mjs

@@ -0,0 +1,46 @@
+/**
+ * Owns one responsibility: the grammar of a single order value.
+ * Plan_63 D9: call and header readers share this leaf without importing either registry.
+ */
+import path from 'node:path';
+
+const PLACEHOLDER_VALUES = new Set(['todo', 'tbd', 'label', 'none', 'order id', 'scope', 'xxx']);
+
+function cleanValue(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
+}
+
+export function isAbsoluteTaskFilePath(value) {
+  const cleaned = cleanValue(value);
+  return path.posix.isAbsolute(cleaned) || path.win32.isAbsolute(cleaned);
+}
+
+export function isPlaceholder(value) {
+  const cleaned = cleanValue(value);
+  if (!cleaned) return true;
+  if (cleaned.startsWith('<') && cleaned.endsWith('>')) return true;
+  return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
+}
+
+// Plan_59: scope is a real phase value, while it remains a placeholder for existing inputs. Plan_63 D5: none is a
+// real reasoning effort the flag channel always accepted, so the header channel must not refuse it as a template.
+const REAL_VALUES = Object.freeze({ phase: 'scope', effort: 'none' });
+export const isInputPlaceholder = (value, label) =>
+  !(Object.hasOwn(REAL_VALUES, label) && cleanValue(value) === REAL_VALUES[label]) && isPlaceholder(value);
+
+// Plan_75 D5, 2026-10-03 20:42: header parsing must reuse the existing grant value grammar.
+export function splitGrantValue(value) {
+  if (isPlaceholder(value)) return null;
+
+  for (const separator of [/\s+—\s+/, /\s+-\s+/, /\s*:\s*/]) {
+    const match = value.match(new RegExp(`^(.+?)${separator.source}(.+)$`));
+    if (!match) continue;
+    const run = cleanValue(match[1]);
+    const reason = cleanValue(match[2]);
+    if (isPlaceholder(run) || isPlaceholder(reason)) return null;
+    return { run, reason };
+  }
+  return null;
+}
+