@lyupro/codex-bridge 0.6.6 → 0.6.7

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

@@ -1,25 +1,47 @@
 /** Reads and compares the order identity carried between dispatcher hook boundaries. */
 import fs from 'node:fs';
+import path from 'node:path';
 import { parseJsonText } from './json-file.mjs';
 import { extractValue } from './required-inputs.mjs';
 
-/** The transcript is diagnostic evidence; malformed or unavailable evidence must fail open. */
-export function transcriptOrderId(transcriptPath) {
+/** Implements Plan_62 D7: keeps untrusted ids from redirecting the host-owned subagent transcript path. */
+export function ownTranscriptPath(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const { transcript_path, session_id, agent_id } = payload;
+  const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0;
+  const unsafeSegment = (value) => value.includes('/') || value.includes('\\') || value.includes('..');
+  if (!nonEmpty(transcript_path) || !nonEmpty(session_id) || !nonEmpty(agent_id)) return null;
+  if (unsafeSegment(session_id) || unsafeSegment(agent_id)) return null;
+  return path.join(path.dirname(transcript_path), session_id, 'subagents', `agent-${agent_id}.jsonl`);
+}
+
+function firstEntry(transcriptPath) {
   try {
-    const firstEntry = fs.readFileSync(transcriptPath, 'utf8').split(/\r?\n/, 1)[0];
-    const transcriptEntry = parseJsonText(transcriptPath, firstEntry);
-    const content = transcriptEntry?.message?.content;
-    const promptText = typeof content === 'string'
+    const line = fs.readFileSync(transcriptPath, 'utf8').split(/\r?\n/, 1)[0];
+    const entry = parseJsonText(transcriptPath, line);
+    const content = entry?.message?.content;
+    const text = typeof content === 'string'
       ? content
       : Array.isArray(content)
         ? content.filter((part) => part?.type === 'text').map((part) => part.text).join('\n')
         : '';
-    return String(extractValue(promptText, 'order id') || '').trim();
+    return { type: entry?.type, text };
   } catch {
-    return '';
+    return null;
   }
 }
 
+/** Reads the first user message; missing or malformed host transcript evidence fails closed. */
+export function transcriptPrompt(transcriptPath) {
+  const entry = firstEntry(transcriptPath);
+  return entry?.type === 'user' ? entry.text : null;
+}
+
+/** The reply guard's transcript is diagnostic evidence, so it keeps the fail-open, type-agnostic read. */
+export function transcriptOrderId(transcriptPath) {
+  return String(extractValue(firstEntry(transcriptPath)?.text ?? '', 'order id') || '').trim();
+}
+
 /** On 2026-08-15 another order's saved reply was returned as the current run's verdict. */
 export function runOrderMismatch(orderedOrderId, runStatus, runDir) {
   const ordered = String(orderedOrderId ?? '').trim();

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

@@ -0,0 +1,111 @@
+/** Keeps dispatcher handback evidence under the package state home without trusting hook ids as paths. */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from './atomic-json.mjs';
+import { parseJsonText } from './json-file.mjs';
+import { withFileLock } from './file-lock.mjs';
+
+function assertIdentity(sessionId, agentId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0
+    || typeof agentId !== 'string' || agentId.length === 0) {
+    throw new TypeError('sessionId and agentId must be non-empty strings');
+  }
+}
+
+export function dispatcherStatePath({ stateDir, sessionId, agentId }) {
+  assertIdentity(sessionId, agentId);
+  const digest = createHash('sha256').update(`${sessionId}\n${agentId}`).digest('hex').slice(0, 32);
+  return path.join(stateDir, 'dispatchers', `${digest}.json`);
+}
+
+export function readDispatcherState(ids) {
+  const file = dispatcherStatePath(ids);
+  let source;
+  try {
+    source = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+
+  let record;
+  try {
+    record = parseJsonText(file, source);
+  } catch {
+    return { corrupt: true };
+  }
+  if (!record || typeof record !== 'object' || Array.isArray(record)
+    || record.sessionId !== ids.sessionId || record.agentId !== ids.agentId) {
+    return { corrupt: true };
+  }
+  return record;
+}
+
+function timestamp(value) {
+  return new Date(value).toISOString();
+}
+
+function clockValue(ids) {
+  return typeof ids.now === 'function' ? ids.now() : (ids.now ?? Date.now());
+}
+
+
+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 () => {
+    let current = readDispatcherState(ids);
+    if (current === null) {
+      current = { sessionId, agentId, createdAt: timestamp(clockValue(ids)) };
+    }
+    const result = await mutate(current);
+    const candidate = result === undefined ? current : result;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      throw new TypeError('mutate must produce a JSON record object');
+    }
+    const record = {
+      ...candidate,
+      sessionId,
+      agentId,
+      updatedAt: timestamp(clockValue(ids)),
+    };
+    writeJsonAtomic(file, record);
+    return record;
+  }, { description: 'dispatcher state' });
+}
+
+export function pruneDispatcherStates({ stateDir, olderThanMs = 7 * 24 * 3600 * 1000, now = Date.now() }) {
+  const directory = path.join(stateDir, 'dispatchers');
+  let entries;
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return 0;
+    throw error;
+  }
+
+  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);
+    let old;
+    try {
+      old = fs.statSync(file).mtimeMs < cutoff;
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
+    if (!old) continue;
+    try {
+      fs.unlinkSync(file);
+      removed += 1;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    fs.rmSync(`${file}.lock`, { force: true });
+  }
+  return removed;
+}

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

@@ -0,0 +1,52 @@
+/** Audits dispatcher tool calls because SubagentHandback delivers the answer before SubagentStop can block it. */
+import fs from 'node:fs';
+import { parseJsonText } from './json-file.mjs';
+import { HANDBACK_TOOL } from './hook-definitions.mjs';
+
+export function transcriptToolUses(transcriptPath) {
+  let source;
+  try {
+    source = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const toolUses = [];
+  for (const line of source.split(/\r?\n/)) {
+    let record;
+    try {
+      record = parseJsonText(transcriptPath, line);
+    } catch {
+      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 });
+    }
+  }
+  return toolUses;
+}
+
+export function decideDispatcherStop({ state, toolUses }) {
+  const seenToolUseIds = !state?.corrupt && Array.isArray(state?.seenToolUseIds)
+    ? state.seenToolUseIds
+    : [];
+  const unseen = toolUses === null || (!state?.corrupt && state?.auditAlarmed)
+    ? []
+    : toolUses.filter((toolUse) => !seenToolUseIds.includes(toolUse.id));
+  const handbackAttempted = (state?.handbackAttempts ?? 0) >= 1
+    || toolUses?.some((toolUse) => toolUse.name === HANDBACK_TOOL) === true;
+
+  let route;
+  if (state?.handback === 'delivered') route = 'yield';
+  else if (handbackAttempted && state?.stopDemanded !== true) route = 'demand';
+  else if (handbackAttempted) route = 'yield';
+  else route = 'legacy';
+
+  const stateUpdate = {};
+  if (route === 'demand') stateUpdate.stopDemanded = true;
+  if (unseen.length) stateUpdate.auditAlarmed = true;
+  return { route, unseen, stateUpdate: Object.keys(stateUpdate).length ? stateUpdate : null };
+}

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

@@ -0,0 +1,65 @@
+/** Records the 2026-09-17..24 silent SubagentHandback contract break before it can go unnoticed again. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from './atomic-json.mjs';
+import { parseJsonText } from './json-file.mjs';
+import { withFileLock } from './file-lock.mjs';
+
+export const WITNESS_FILE = 'handback-witness.json';
+
+export function hostSdkVersion(env = process.env) {
+  const version = env.CLAUDE_AGENT_SDK_VERSION;
+  if (typeof version !== 'string') return null;
+  return version.trim() || null;
+}
+
+function isWitness(record) {
+  const witnessEntry = (entry, alarm = false) => entry && typeof entry === 'object'
+    && !Array.isArray(entry)
+    && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string')
+    && typeof entry.at === 'string'
+    && (!alarm || typeof entry.detail === 'string');
+  return record && typeof record === 'object' && !Array.isArray(record)
+    && (record.lastSeen === null || witnessEntry(record.lastSeen))
+    && Array.isArray(record.alarms) && record.alarms.every((entry) => witnessEntry(entry, true));
+}
+
+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: null, alarms: [] };
+    return { corrupt: true };
+  }
+  try {
+    const record = parseJsonText(file, source);
+    return isWitness(record) ? record : { corrupt: true };
+  } catch {
+    return { corrupt: true };
+  }
+}
+
+function timestamp(now) {
+  return new Date(now).toISOString();
+}
+
+
+export async function recordHandbackWitness({ stateDir, kind, sdkVersion, detail = '', now = new Date() }) {
+  if (kind !== 'seen' && kind !== 'alarm') throw new TypeError("kind must be 'seen' or 'alarm'");
+  if (sdkVersion !== null && typeof sdkVersion !== 'string') {
+    throw new TypeError('sdkVersion must be a string or null');
+  }
+  const file = path.join(stateDir, WITNESS_FILE);
+  return withFileLock(`${file}.lock`, async () => {
+    const current = readHandbackWitness({ stateDir });
+    if (current.corrupt) throw new Error(`Cannot update corrupt handback witness: ${file}`);
+    const at = timestamp(now);
+    const record = kind === 'seen'
+      ? { ...current, lastSeen: { sdkVersion, at } }
+      : { ...current, alarms: [...current.alarms, { sdkVersion, at, detail }].slice(-20) };
+    writeJsonAtomic(file, record);
+    return record;
+  }, { description: 'handback witness' });
+}

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

@@ -39,6 +39,13 @@ export const SHELL_TOOLS = Object.freeze(['Bash', 'PowerShell']);
 /** A PreToolUse matcher is a regular expression over tool names, so alternation covers both. */
 export const SHELL_TOOL_MATCHER = SHELL_TOOLS.join('|');
 
+// Probed live on 2026-09-24; this is the one place the host handback tool name is spelled.
+export const HANDBACK_TOOL = 'SubagentHandback';
+
+// Plan_62 D15: a dispatcher has only its shell whitelist and handback tool; `*` would tax every session.
+export const DISPATCHER_TOOLS = Object.freeze([...SHELL_TOOLS, HANDBACK_TOOL]);
+export const DISPATCHER_TOOL_MATCHER = DISPATCHER_TOOLS.join('|');
+
 // Plan_31 routes host stop requests through the package guard; keep the matcher derived from
 // the tool list so registration and uninstall cannot drift from the host event spelling.
 export const STOP_TOOLS = Object.freeze(['TaskStop']);
@@ -66,4 +73,7 @@ export const HOOK_DEFINITIONS = Object.freeze([
   Object.freeze({ name: 'prune-guard', event: 'PreToolUse', matcher: SHELL_TOOL_MATCHER, file: 'prune-guard.mjs' }),
   Object.freeze({ name: 'worktree-witness', event: 'PostToolUse', matcher: SHELL_TOOL_MATCHER, file: 'worktree-witness.mjs' }),
   Object.freeze({ name: 'stop-guard', event: 'PreToolUse', matcher: STOP_TOOL_MATCHER, file: 'stop-guard.mjs' }),
+  Object.freeze({ name: 'dispatcher-gate', event: 'PreToolUse', matcher: DISPATCHER_TOOL_MATCHER, file: 'dispatcher-gate.mjs' }),
+  Object.freeze({ name: 'dispatcher-capture', event: 'PostToolUse', matcher: SHELL_TOOL_MATCHER, file: 'dispatcher-gate.mjs' }),
+  Object.freeze({ name: 'dispatcher-capture-failure', event: 'PostToolUseFailure', matcher: SHELL_TOOL_MATCHER, file: 'dispatcher-gate.mjs' }),
 ]);

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

@@ -0,0 +1,20 @@
+/** Runs the installed home copy so the registering package cannot drift from its live guards. */
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HOOK_DEFINITIONS } from './hook-definitions.mjs';
+
+export async function runHook(name, io = console) {
+  const definition = HOOK_DEFINITIONS.find(({ name: candidate }) => candidate === name);
+  try {
+    if (!definition) throw new Error(`unknown hook name "${name}"`);
+    // Plan_25 replaces absolute paths in foreign settings.json with this command. Importing the
+    // proven top-level script keeps its stdin reader and process.exit() contract intact; exporting
+    // guard functions would be a second implementation of the live hook boundary.
+    const hooksDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+    await import(pathToFileURL(path.join(hooksDir, definition.file)).href);
+    return typeof process.exitCode === 'number' ? process.exitCode : 0;
+  } catch (error) {
+    io.error(`codex-bridge hook: guard "${name}" did not run: ${error?.message ?? String(error)}. Run codex-bridge doctor.`);
+    return 1;
+  }
+}

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

@@ -76,10 +76,9 @@ function* addressesIn(value, root) {
   }
 }
 
-function citationProblem(raw, root, allowed) {
-  const match = raw.match(/^(.+):(\d+)(?:-(\d+))?$/);
-  if (!match) return 'use a repository-relative path:line or path:line-line address';
-  const entry = entryInRepo(root, match[1]);
+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);
   if (!entry?.isFile) return 'cite an existing file under repoRoot';
   let count;
   try {
@@ -87,8 +86,6 @@ function citationProblem(raw, root, allowed) {
   } catch {
     return 'cite a readable file under repoRoot';
   }
-  const start = Number(match[2]);
-  const end = match[3] === undefined ? start : Number(match[3]);
   if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start || end > count) {
     return `use an ascending line range within this file's ${count} lines`;
   }
@@ -103,40 +100,59 @@ function checkCitations({ phase, result, task, repoRoot, scopeResult }, reasons)
   const root = path.resolve(repoRoot);
   const allowed = [...task.paths, ...(phase === 'scope' ? result.missing_paths : scopeResult?.missing_paths ?? [])]
     .map((raw) => entryInRepo(root, raw)).filter(Boolean);
-  const check = (field, address) => {
-    const problem = citationProblem(address, root, allowed);
-    if (problem) reasons.push(`D3 ${field} ${JSON.stringify(address)}: ${problem}.`);
+  const locationLabel = ({ file, line_start, line_end }) =>
+    `${file}:${line_start}${line_end === line_start ? '' : `-${line_end}`}`;
+  const checkLocation = (field, location) => {
+    const { file, line_start: start, line_end: end } = location;
+    const label = locationLabel(location);
+    const problem = citationProblem(file, start, end, root, allowed);
+    if (problem) reasons.push(`D3 ${field} ${JSON.stringify(label)}: ${problem}.`);
   };
   const checkAddress = (field, raw) => {
-    const trimmed = raw.trim();
-    check(field, /^`.*`$/.test(trimmed) ? trimmed.slice(1, -1) : trimmed);
+    const match = raw.match(/^(.+):(\d+)(?:-(\d+))?$/);
+    if (!match) {
+      reasons.push(`D3 ${field} ${JSON.stringify(raw)}: use a repository-relative path:line or path:line-line address.`);
+      return;
+    }
+    const start = Number(match[2]);
+    checkLocation(field, {
+      file: match[1],
+      line_start: start,
+      line_end: match[3] === undefined ? start : Number(match[3]),
+    });
   };
   // D3 covers every address anywhere in the answer. A list of prose fields had to be edited by
   // hand when `falsifier` became `pre_mortem`, and each new field would have joined it unchecked.
-  // Fields that ARE an address are checked whole below, so they are skipped here.
+  // Structured evidence and the free-text early_check.target are handled separately below.
   for (const { field, value } of strings(result)) {
-    if (/\.address$|\.early_check\.target$/.test(field)) continue;
-    for (const address of addressesIn(value, root)) check(field, address);
+    if (/(?:^|\.)evidence(?:\[|\.|$)|\.early_check\.target$/.test(field)) continue;
+    for (const address of addressesIn(value, root)) checkAddress(field, address);
   }
+  const checkEvidence = (field, evidence) => {
+    for (const [index, location] of evidence.entries()) checkLocation(`${field}[${index}]`, location);
+  };
   if (result.independent_checks) {
     for (const [index, item] of result.independent_checks.entries()) {
-      checkAddress(`independent_checks[${index}].address`, item.address);
+      checkEvidence(`independent_checks[${index}].evidence`, item.evidence);
     }
   }
   if (phase === 'advise') {
     for (const [index, item] of result.assumptions.entries()) {
-      if (item.rating === 'VERIFIED' || item.address !== '') {
-        checkAddress(`assumptions[${index}].address`, item.address);
+      if (item.rating === 'VERIFIED' && item.evidence.length === 0) {
+        reasons.push(`D10 assumptions[${index}].evidence []: a VERIFIED assumption needs at least one location.`);
       }
+      checkEvidence(`assumptions[${index}].evidence`, item.evidence);
     }
     for (const [index, item] of result.pre_mortem.entries()) {
-      if (item.early_check.kind === 'inspect') {
-        checkAddress(`pre_mortem[${index}].early_check.target`, item.early_check.target);
+      const { early_check: earlyCheck } = item;
+      if (earlyCheck.kind === 'inspect' && earlyCheck.evidence.length === 0) {
+        reasons.push(`D10 pre_mortem[${index}].early_check.evidence []: an inspect check needs at least one location.`);
       }
+      checkEvidence(`pre_mortem[${index}].early_check.evidence`, earlyCheck.evidence);
     }
-    // An outcome's address is evidence whether or not the phase-1 answer is at hand.
+    // A risk outcome's locations are evidence whether or not the phase-1 answer is at hand.
     for (const [index, item] of result.risk_outcomes.entries()) {
-      checkAddress(`risk_outcomes[${index}].address`, item.address);
+      checkEvidence(`risk_outcomes[${index}].evidence`, item.evidence);
     }
   }
 }

package/src/home/lib/required-inputs.mjs

@@ -119,7 +119,7 @@ export function isPlaceholder(value) {
 }
 
 // Plan_59: scope is a real phase value, while it remains a placeholder for existing inputs.
-const isInputPlaceholder = (value, label) =>
+export const isInputPlaceholder = (value, label) =>
   !(label === 'phase' && cleanValue(value) === 'scope') && isPlaceholder(value);
 
 export function extractValue(promptText, label) {

package/src/home/lib/runner/codex-cmd.mjs

@@ -77,7 +77,7 @@ export function spawnCaptured(command, args, options) {
     throw new TypeError('spawnCaptured requires a finite timeout greater than zero');
   }
   return new Promise((resolve) => {
-    const child = spawn(command, args, { ...rest, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(command, args, { ...rest, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
     let stdout = Buffer.alloc(0);
     let stderr = Buffer.alloc(0);
     let captureError = null;
@@ -232,6 +232,7 @@ export function runCodex(args, taskText, eventsPath, budgetMinutes, graceMs = ST
   const child = spawn(spec.command, spec.args, {
     ...spec.options,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 
   return new Promise((resolve) => {
@@ -345,7 +346,7 @@ export function codexUnavailableReason() {
   const probe = spawnSync(
     process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex',
     process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'],
-    { encoding: 'utf8' },
+    { encoding: 'utf8', windowsHide: true },
   );
   if (probe.error || probe.status !== 0) {
     return (probe.stderr || probe.error?.message || 'codex --version is not responding').trim();

package/src/home/lib/runner/git-state.mjs

@@ -15,7 +15,7 @@ import { runsRoot } from './runs-root.mjs';
 export const MAX_LOG = 256 * 1024 * 1024;
 
 export const git = (repo, args) =>
-  spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: MAX_LOG });
+  spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: MAX_LOG, windowsHide: true });
 
 /**
  * Prefix of the run folders as seen from inside the repository, or null when they live

package/src/home/lib/runner/preflight.mjs

@@ -33,8 +33,10 @@ export function taskPreflight({ agent, taskText }) {
     }
     if (path.isAbsolute(advice)) {
       try {
-        if (fs.statSync(advice).isDirectory() &&
-            readJson(path.join(advice, 'meta.json'))?.agent === 'codex-advisor') {
+        // Plan_59 D26: only a judged advice authorizes a construction. On 2026-09-24 the gate took
+        // any codex-advisor folder, so a scope run or a FAIL advice would have passed as a second opinion.
+        const meta = fs.statSync(advice).isDirectory() ? readJson(path.join(advice, 'meta.json')) : null;
+        if (meta?.agent === 'codex-advisor' && meta.phase === 'advise' && meta.status === 'OK') {
           return { refusal: null, advice };
         }
       } catch {
@@ -43,7 +45,8 @@ export function taskPreflight({ agent, taskText }) {
     }
   }
   return freeRefusal('codex-build requires exactly one advice: line: mechanical | revert | docs-only | test-only ' +
-    'or an absolute path to an existing advisor run directory with meta.json agent codex-advisor. ' +
+    'or an absolute path to an existing advisor run directory whose meta.json says agent codex-advisor, ' +
+    'phase advise, status OK. ' +
     'An order that invents a construction needs a second opinion first; only work with no design choice may skip it.');
 }
 

package/src/home/lib/runner/prompts.mjs

@@ -18,8 +18,9 @@ const BODIES = {
 Rules for both phases:
 - Read ONLY the paths listed under \`## Paths\` and, in the advise phase, under \`## Scope phase results\`, plus \`git log\` / \`git show\` on those paths.
 - Write nothing. Do your own reading and checks; do not spawn or delegate to other agents.
-- Every claim about code must carry a \`path:line\` address inside those paths. Addresses are
-  machine-checked for existence; do not invent addresses or treat an unchecked claim as evidence.
+- Prose fields cite code as \`path:line\`; every \`evidence\` field is a list of
+  \`{file, line_start, line_end}\` objects, ONE location per object. Several places mean several
+  objects, never a list inside \`file\`. Locations are machine-checked for existence.
 - Do not guess which option the caller prefers: the task carries no preference on purpose.
 - Two failure modes are forbidden: agreeing without independent checks ("both options are good",
   "you know better"), and disagreeing to look independent. A disagreement without an address is
@@ -32,18 +33,18 @@ Scope phase:
   (facts accepted from the task without checking, never empty), together with predicted_risks.
 ` : `
 Advise phase:
-- Settle every predicted risk listed under \`## Scope phase results\` in risk_outcomes: its risk_id, an outcome of
-  confirmed or refuted, and an address supporting that outcome.
+- Settle every predicted risk listed under \`## Scope phase results\` in risk_outcomes with its
+  risk_id, an outcome of confirmed or refuted, a \`note\` explaining it, and evidence.
 - Give ONE recommendation by task option_id, or none-of-these with a described unlisted_option.
   Put every rejected task option in rejected with its cost; for none-of-these this means EVERY
   task option. Set unlisted_option to "none" when recommending a listed option.
 - Each field is a distinct lens: strongest_counterargument comes from a skeptic;
   pre_mortem comes from the executor who has only this advice and the repository. Give each
-  scenario an early_check of kind test | command | inspect with a target; inspect requires an address.
+  scenario an early_check of kind test | command | inspect with a target; inspect requires evidence.
 - question_defect comes from the requester who needs the problem solved, not an option picked.
-- Rate assumptions VERIFIED (requires an address) | REASONABLE | FRAGILE. Anything the requester
+- Rate assumptions VERIFIED (requires evidence) | REASONABLE | FRAGILE. Anything the requester
   could refute with knowledge you lack belongs in open_questions, not why.
-- independent_checks lists what you verified yourself, with addresses. Ground why in those checks
+- independent_checks lists what you verified yourself, with evidence. Ground why in those checks
   and state confidence honestly.
 `}`;
   },

package/src/home/lib/runner/schemas.mjs

@@ -150,6 +150,30 @@ const REVIEW_SCHEMA = {
   },
 };
 
+// The 2026-09-24_094352_plan62-g1-dispatcher-gate run folded 3-5 citations into one advisor
+// address; like the 2026-07-31 build changes[].file precedent, constrain a single location here.
+export const EVIDENCE_LOCATION = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['file', 'line_start', 'line_end'],
+  properties: {
+    file: {
+      type: 'string',
+      minLength: 1,
+      pattern: '^[^:;,*?{}\\r\\n]+$',
+      description: 'Exactly one repository-root-relative path. Spaces are allowed; lists, globs, drive letters and line suffixes are not — use a separate location object for each place.',
+    },
+    line_start: { type: 'integer', minimum: 1 },
+    line_end: { type: 'integer', minimum: 1 },
+  },
+};
+
+const EVIDENCE_LIST = (minItems) => ({
+  type: 'array',
+  ...(minItems === undefined ? {} : { minItems }),
+  items: EVIDENCE_LOCATION,
+});
+
 /** Plan_59: execution schemas stay static; schemaFor selects the advisor contract by phase. */
 export const SCHEMAS = {
   'codex-scout': SCOUT_SCHEMA,
@@ -220,11 +244,11 @@ export const PHASE_SCHEMAS = {
           items: {
             type: 'object',
             additionalProperties: false,
-            required: ['claim', 'rating', 'address'],
+            required: ['claim', 'rating', 'evidence'],
             properties: {
               claim: { type: 'string' },
               rating: { type: 'string', enum: ['VERIFIED', 'REASONABLE', 'FRAGILE'] },
-              address: { type: 'string' },
+              evidence: EVIDENCE_LIST(),
             },
           },
         },
@@ -233,11 +257,12 @@ export const PHASE_SCHEMAS = {
           items: {
             type: 'object',
             additionalProperties: false,
-            required: ['risk_id', 'outcome', 'address'],
+            required: ['risk_id', 'outcome', 'note', 'evidence'],
             properties: {
               risk_id: { type: 'string' },
               outcome: { type: 'string', enum: ['confirmed', 'refuted'] },
-              address: { type: 'string' },
+              note: { type: 'string' },
+              evidence: EVIDENCE_LIST(1),
             },
           },
         },
@@ -254,10 +279,11 @@ export const PHASE_SCHEMAS = {
               early_check: {
                 type: 'object',
                 additionalProperties: false,
-                required: ['kind', 'target'],
+                required: ['kind', 'target', 'evidence'],
                 properties: {
                   kind: { type: 'string', enum: ['test', 'command', 'inspect'] },
                   target: { type: 'string', minLength: 3 },
+                  evidence: EVIDENCE_LIST(),
                 },
               },
             },
@@ -271,8 +297,8 @@ export const PHASE_SCHEMAS = {
           items: {
             type: 'object',
             additionalProperties: false,
-            required: ['check', 'address'],
-            properties: { check: { type: 'string' }, address: { type: 'string' } },
+            required: ['check', 'evidence'],
+            properties: { check: { type: 'string' }, evidence: EVIDENCE_LIST(1) },
           },
         },
       },