@lyupro/codex-bridge 0.6.14 → 0.6.16

package/src/home/lib/order-diagnostics/cli-flags.mjs

@@ -0,0 +1,56 @@
+/** Plan_79 D4: owns diagnostics for the command-line flags the dispatcher passes to the runner. */
+export const DIAGNOSTICS = Object.freeze({
+  'no-wait-grant-conflict': Object.freeze({
+    data: Object.freeze(['grant']),
+    category: 'cli-flags',
+    message: ({ grant }) =>
+      `--no-wait cannot be combined with a ${grant} grant: ` +
+      'checking an existing run must never authorize a new one.',
+  }),
+  'task-channel-conflict': Object.freeze({
+    data: Object.freeze([]),
+    category: 'cli-flags',
+    message: () => 'task text was supplied through both stdin and --task-file; choose exactly one channel',
+  }),
+  'unexpected-argument': Object.freeze({
+    data: Object.freeze(['value']),
+    category: 'cli-flags',
+    message: ({ value }) => `unexpected argument: ${value}`,
+  }),
+  'unknown-flag': Object.freeze({
+    data: Object.freeze(['name']),
+    category: 'cli-flags',
+    message: ({ name, help }) =>
+      `unknown flag --${name}: codex-bridge run takes only --agent, --task-file and --no-wait; ` +
+      'the order belongs in the task-file header' + (help ? `\n${help}` : ''),
+  }),
+  'boolean-flag-value': Object.freeze({
+    data: Object.freeze(['name', 'value']),
+    category: 'cli-flags',
+    message: ({ name, value }) =>
+      `--${name} takes no value, or one of 1/true/yes/0/false/no; got ${JSON.stringify(value)}. ` +
+      'A placeholder left in from the prompt template is not consent.',
+  }),
+  'missing-flag-value': Object.freeze({
+    data: Object.freeze(['key']),
+    category: 'cli-flags',
+    message: ({ key }) => `missing value for ${key}`,
+  }),
+  'flag-shell-safety': Object.freeze({
+    data: Object.freeze(['name', 'sequence']),
+    category: 'cli-flags',
+    message: ({ name, sequence }) =>
+      `--${name} contains forbidden shell sequence ${JSON.stringify(sequence)}; ` +
+      'put free text in the task file and pass only a short command-line value.',
+  }),
+  'agent-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'cli-flags',
+    message: () => '--agent is required',
+  }),
+  'agent-known': Object.freeze({
+    data: Object.freeze(['agent']),
+    category: 'cli-flags',
+    message: ({ agent }) => `unknown --agent ${agent}`,
+  }),
+});

package/src/home/lib/order-diagnostics/filesystem.mjs

@@ -0,0 +1,18 @@
+/** Plan_79 D4: owns diagnostics for filesystem access. */
+export const DIAGNOSTICS = Object.freeze({
+  'task-file-readable': Object.freeze({
+    data: Object.freeze(['message']),
+    category: 'filesystem',
+    message: ({ message }) => `task file from --task-file could not be read: ${message}`,
+  }),
+  'project-runs-folder-required': Object.freeze({
+    data: Object.freeze(['projectRunsRoot']),
+    category: 'filesystem',
+    message: ({ projectRunsRoot }) => `project runs folder does not exist: ${projectRunsRoot}`,
+  }),
+  'runs-move-record-readable': Object.freeze({
+    data: Object.freeze(['file', 'message']),
+    category: 'filesystem',
+    message: ({ file, message }) => `Cannot read runs move record ${file}: ${message}`,
+  }),
+});

package/src/home/lib/order-diagnostics/host-state.mjs

@@ -0,0 +1,263 @@
+/** Plan_79 D4: owns diagnostics for the host's Codex CLI readiness and availability. */
+import { DIAGNOSTICS as INTERNAL_DIAGNOSTICS } from './internal.mjs';
+
+export const DIAGNOSTICS = Object.freeze({
+  'codex-readiness-unconfirmed': Object.freeze({
+    data: Object.freeze(['detail']),
+    category: 'host-state',
+    message: ({ detail }) => [
+      `Codex CLI readiness unconfirmed: ${detail}`,
+      'Do not skip this bridge: check codex --version for up to about 2 minutes; when it answers, repeat the same order exactly once; if it does not answer, hand the order to the next executor and name that in the summary.',
+    ].join('\n'),
+  }),
+  'codex-unavailable': Object.freeze({
+    data: Object.freeze(['detail']),
+    category: 'host-state',
+    message: ({ detail }) => [
+      `Codex CLI unavailable: ${detail}`,
+      'Operator check: codex --version (and codex login if authorization is rejected)',
+    ].join('\n'),
+  }),
+  'codex-availability-detail': Object.freeze({
+    data: Object.freeze(['variant', 'command', 'status', 'message']),
+    category: 'host-state',
+    message: ({ variant, command, status, message }) => {
+      if (variant === 'path-miss') return 'codex could not be resolved in this process PATH; readiness is unconfirmed';
+      if (variant === 'exit-status') return `${command} exited ${status}`;
+      if (variant === 'failed') return 'codex availability probe failed';
+      if (variant === 'logged-out') return 'codex login status: Not logged in';
+      if (variant === 'message') return message;
+      throw new Error(`unknown codex-availability-detail variant: ${variant}`);
+    },
+  }),
+  'codex-unavailable-handoff': Object.freeze({
+    data: Object.freeze(['variant', 'signal']),
+    category: 'host-state',
+    message: ({ variant, signal }) => {
+      if (variant === 'handoff') {
+        return 'UNAVAILABLE — Codex is not available (signed out); ' +
+          'hand the task to the next executor, do not retry';
+      }
+      if (variant === 'signal') return `Signal: ${signal}`;
+      if (variant === 'operator-check') {
+        return 'Operator check: codex --version; codex login status (sign in with codex login)';
+      }
+      throw new Error(`unknown codex-unavailable-handoff variant: ${variant}`);
+    },
+  }),
+  'stale-runs-root-override': Object.freeze({
+    data: Object.freeze([]),
+    category: 'host-state',
+    message: () => 'CODEX_RUNS_ROOT points under a retired runs root; remove it or set it to the new location.',
+  }),
+  'runs-move-record-invalid': Object.freeze({
+    data: Object.freeze(['file', 'violation', 'detail', 'index']),
+    category: 'host-state',
+    message: ({ file, violation, detail, index }) => {
+      let defect;
+      if (violation === 'parse') defect = detail;
+      else if (violation === 'version') defect = 'version must be 1';
+      else if (violation === 'retired-array') defect = 'retired must be a non-empty array';
+      else if (violation === 'retired-root') defect = `retired[${index}].root must be an absolute path`;
+      else if (violation === 'retired-time') defect = `retired[${index}].movedAt must be a parseable ISO time`;
+      else throw new Error(`unknown runs-move-record-invalid violation: ${violation}`);
+      return `Invalid runs move record ${file}: ${defect}`;
+    },
+  }),
+  'sandbox-probe-reason': Object.freeze({
+    data: Object.freeze(['variant', 'form', 'status', 'signal']),
+    category: 'host-state',
+    message: ({ variant, form, status, signal }) => {
+      if (variant === 'timeout') return `The ${form} sandbox probe timed out.`;
+      if (variant === 'incomplete') return `The ${form} sandbox probe could not start or complete.`;
+      if (variant === 'signal') return `The ${form} sandbox probe was terminated by ${signal}.`;
+      if (variant === 'arguments') return `Codex rejected the ${form} sandbox probe arguments.`;
+      if (variant === 'no-status') return `The ${form} sandbox probe returned no exit status.`;
+      if (variant === 'alive') return 'The Codex sandbox started a process.';
+      if (variant === 'marker-exit') return `The flagged sandbox probe printed the marker but exited ${status}.`;
+      if (variant === 'flags') return 'This version of Codex no longer accepts the package sandbox flags.';
+      if (variant === 'unavailable') return 'Codex CLI is unavailable.';
+      if (variant === 'dead') return 'The Codex sandbox on this host cannot start a process.';
+      throw new Error(`unknown sandbox-probe-reason variant: ${variant}`);
+    },
+  }),
+  'sandbox-refusal-repair': Object.freeze({
+    data: Object.freeze([]),
+    category: 'host-state',
+    message: () => 'Repair the host sandbox; do not rewrite or retry the order.',
+  }),
+  // Ubuntu 23.10+ forbids unprivileged user namespaces unless an AppArmor profile allows bwrap; that
+  // is the ordinary state of a fresh server, not an accident like the corrupted Windows state file.
+  'sandbox-linux-repair': Object.freeze({
+    data: Object.freeze([]),
+    category: 'host-state',
+    message: () => [
+      'On Ubuntu 23.10 and later this usually means AppArmor does not let bubblewrap create a user namespace.',
+      'Official repair: https://learn.chatgpt.com/docs/sandboxing — the bwrap-userns-restrict AppArmor profile',
+      '(Ubuntu 24.04) or the bubblewrap package (25.04 and later). Do not set',
+      'kernel.apparmor_restrict_unprivileged_userns=0: it lifts the restriction for every program on the host.',
+    ].join(' '),
+  }),
+  'sandbox-operator-check': Object.freeze({
+    data: Object.freeze(['command']),
+    category: 'host-state',
+    message: ({ command }) => `Operator check (run from the repository directory): ${command}`,
+  }),
+  'sandbox-stderr-evidence': Object.freeze({
+    data: Object.freeze(['form', 'stderrTail']),
+    category: 'host-state',
+    message: ({ form, stderrTail }) =>
+      `${form} stderr:\n> ${(stderrTail || '(empty)').replace(/\r\n?/g, '\n').replace(/\n/g, '\n> ')}`,
+  }),
+  'sandbox-diagnosis-source': Object.freeze({
+    data: Object.freeze(['source']),
+    category: 'host-state',
+    message: ({ source }) => `Sandbox diagnosis source: ${source}`,
+  }),
+  'sandbox-diagnosis-attribution': Object.freeze({
+    data: Object.freeze(['attributed']),
+    category: 'host-state',
+    message: ({ attributed }) => attributed ? 'Sandbox log lines attributed to this probe:'
+      : 'Recent sandbox log lines only; not attributed to this probe:',
+  }),
+  'sandbox-setup-change': Object.freeze({
+    data: Object.freeze(['changed']),
+    category: 'host-state',
+    message: ({ changed }) =>
+      `setup_error.json changed since snapshot: ${changed === null ? 'unknown' : changed ? 'yes' : 'no'}`,
+  }),
+  'sandbox-evidence-line': Object.freeze({
+    data: Object.freeze(['line']),
+    category: 'host-state',
+    message: ({ line }) => `> ${line}`,
+  }),
+  'sandbox-evidence-unknown': Object.freeze({
+    data: Object.freeze(['variant', 'file']),
+    category: 'host-state',
+    message: ({ variant, file }) => {
+      if (variant === 'unreadable') return `Unknown: unable to read ${file}.`;
+      if (variant === 'baseline') return `Unknown: pre-probe size unavailable for ${file}.`;
+      throw new Error(`unknown sandbox-evidence-unknown variant: ${variant}`);
+    },
+  }),
+  'sandbox-no-repair': Object.freeze({
+    data: Object.freeze([]),
+    category: 'host-state',
+    message: () => 'No verified repair signature; inspect this log.',
+  }),
+  'sandbox-known-failure-runtime-file-locked': Object.freeze({
+    data: Object.freeze(['part']),
+    category: 'host-state',
+    message: ({ part }) => {
+      if (part === 'summary') {
+        return 'A file under the Codex runtimes folder is held open by another process, so sandbox setup cannot update its access rights (openai/codex #51634).';
+      }
+      if (part === 'repair') {
+        return 'Find and close the process holding the file named in the line (on 2026-10-10, the Codex desktop app\'s computer-use helper), then rerun codex-bridge doctor; on Codex CLI 0.162.x the proven workaround is npm install -g @openai/codex@0.160.1.';
+      }
+      throw new Error(`unknown sandbox-known-failure-runtime-file-locked part: ${part}`);
+    },
+  }),
+  'sandbox-known-failure-deny-read-state-corrupt': Object.freeze({
+    data: Object.freeze(['part', 'file']),
+    category: 'host-state',
+    message: ({ part, file }) => {
+      if (part === 'summary') return 'The sandbox state file is empty or corrupt.';
+      if (part === 'repair') {
+        return `Back up and rename ${file}, then rerun codex-bridge doctor; the helper recreates it.`;
+      }
+      throw new Error(`unknown sandbox-known-failure-deny-read-state-corrupt part: ${part}`);
+    },
+  }),
+  'cmd-argument-transport': Object.freeze({
+    data: Object.freeze(['argument']),
+    category: 'host-state',
+    message: ({ argument }) => `argument cannot be passed through cmd.exe (contains % or "): ${argument}`,
+  }),
+  'run-worker-start-failure': Object.freeze({
+    data: Object.freeze(['message']),
+    category: 'host-state',
+    message: ({ message }) => `run worker process failed to start: ${message}`,
+  }),
+  'subagent-model-env-pin': Object.freeze({
+    data: Object.freeze(['model', 'pinFamily', 'hostVersion']),
+    category: 'host-state',
+    message: ({ model, pinFamily, hostVersion }) =>
+      `Order gate denied the Agent call because CLAUDE_CODE_SUBAGENT_MODEL=${JSON.stringify(model)} `
+      + `overrides the installed dispatcher pin ${pinFamily} on host ${hostVersion}. `
+      + `Unset CLAUDE_CODE_SUBAGENT_MODEL or set it to the pinned family ${pinFamily}.`,
+  }),
+  'dispatcher-pin-file-readable': Object.freeze({
+    data: Object.freeze(['file', 'problem', 'cli', 'root']),
+    category: 'host-state',
+    message: ({ file, problem, cli, root }) => {
+      if (problem === 'missing') return `Dispatcher file "${file}" is missing; repair with ${cli} install --host "${root}".`;
+      if (problem === 'unreadable') return `Dispatcher file "${file}" cannot be read; repair with ${cli} install --host "${root}".`;
+      throw new Error(`unknown dispatcher-pin-file-readable problem: ${problem}`);
+    },
+  }),
+  'dispatcher-pin-frontmatter-readable': Object.freeze({
+    data: Object.freeze(['file']),
+    category: 'host-state',
+    message: ({ file }) => `The frontmatter in "${file}" is unreadable.`,
+  }),
+  'dispatcher-pin-agent-name': Object.freeze({
+    data: Object.freeze(['file', 'agentType']),
+    category: 'host-state',
+    message: ({ file, agentType }) => `Dispatcher file "${file}" does not declare the required frontmatter name "${agentType}".`,
+  }),
+  'dispatcher-pin-model-family': Object.freeze({
+    data: Object.freeze(['file']),
+    category: 'host-state',
+    message: ({ file }) => `Dispatcher file "${file}" has no parseable model family in its frontmatter model.`,
+  }),
+  'dispatcher-pin-owner-agreement': Object.freeze({
+    data: Object.freeze(['disagreement']),
+    category: 'host-state',
+    message: ({ disagreement }) => `Installed dispatcher model families disagree across owners: ${disagreement}.`,
+  }),
+  'dispatcher-model-observation': Object.freeze({
+    data: Object.freeze(['verdict', 'agentType', 'models', 'pinFamily', 'incompleteMatch']),
+    category: 'host-state',
+    message: ({ verdict, agentType, models, pinFamily, incompleteMatch }) => {
+      if (verdict === 'violation') return `${agentType} ran on ${models} while the installed contract pins ${pinFamily}`;
+      if (verdict === 'match') return `${agentType} ran on ${models} matching the installed contract pin ${pinFamily}`;
+      if (verdict !== 'undetermined') throw new Error(`unknown dispatcher-model-observation verdict: ${verdict}`);
+      return incompleteMatch
+        ? `${agentType} model comparison is undetermined: the transcript has unreadable records`
+        : `${agentType} model comparison against the installed contract is undetermined`;
+    },
+  }),
+  'dispatcher-model-stop-warning': Object.freeze({
+    data: Object.freeze(['agentType', 'models', 'pinFamily']),
+    category: 'host-state',
+    message: ({ agentType, models, pinFamily }) =>
+      `codex-bridge: dispatcher ${agentType} ran on ${models} while the installed contract pins ${pinFamily} — Claude quota was spent on it; run codex-bridge doctor.`,
+  }),
+  'install-record-owners-readable': Object.freeze({
+    data: Object.freeze(['file', 'problem', 'cli']),
+    category: 'host-state',
+    message: ({ file, problem, cli }) => {
+      if (problem === 'missing') return `Installation record at ${file} is missing.`;
+      if (problem === 'unreadable') return `Installation record at ${file} cannot be read.`;
+      if (problem === 'invalid-json') return `Installation record at ${file} contains invalid JSON.`;
+      if (problem === 'not-format-2') return `Installation record at ${file} is not format 2.`;
+      if (problem === 'no-owners') return `Installation record at ${file} has no owners.`;
+      if (problem === 'inventory-incomplete') {
+        // Plan_67 D11: match cli/inventory-confirm.mjs INVENTORY_CONFIRM_COMMAND; hooks cannot import cli/.
+        return `Installation record at ${file} has an incomplete inventory; if the recorded hosts are all the hosts using this home, run ${cli} inventory confirm.`;
+      }
+      if (problem === 'legacy-partition') return `Installation record at ${file} contains a legacy partition.`;
+      if (problem === 'malformed-owner') return `Installation record at ${file} has an owner without a non-empty root.`;
+      throw new Error(INTERNAL_DIAGNOSTICS['install-record-owners-problem-known'].message({ problem }));
+    },
+  }),
+  'dispatcher-model-latch': Object.freeze({
+    data: Object.freeze(['agentType', 'models', 'pinFamily', 'hostVersion', 'at']),
+    category: 'host-state',
+    message: ({ agentType, models, pinFamily, hostVersion, at }) =>
+      `codex-bridge: the last ${agentType} ran on ${models} `
+      + `while the installed contract pins ${pinFamily} (${hostVersion ?? 'unknown'}, ${at}); `
+      + 'the cause is outside this call — another hook or the host; run codex-bridge doctor.',
+  }),
+});

package/src/home/lib/order-diagnostics/internal.mjs

@@ -0,0 +1,82 @@
+/** Plan_79 D4: owns diagnostics for internal order contracts. */
+export const DIAGNOSTICS = Object.freeze({
+  'dispatcher-agent-known': Object.freeze({
+    data: Object.freeze(['agent']),
+    category: 'internal',
+    message: ({ agent }) => `unknown dispatcher agent "${agent}"`,
+  }),
+  'order-input-name-known': Object.freeze({
+    data: Object.freeze(['label']),
+    category: 'internal',
+    message: ({ label }) => `Unknown order input label "${label}"`,
+  }),
+  'advise-scope-input-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'Cannot carry advise scope result: runsRoot and grantRun are required.',
+  }),
+  'order-claim-input-valid': Object.freeze({
+    data: Object.freeze(['violation']),
+    category: 'internal',
+    message: ({ violation }) => {
+      if (violation === 'order-id') return 'orderId must be a non-empty string';
+      if (violation === 'role') return 'role must be launcher or worker';
+      throw new Error(`unknown order-claim-input-valid violation: ${violation}`);
+    },
+  }),
+  'advisor-task-text-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'Advisor task text must be a string.',
+  }),
+  'sandbox-probe-repository-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'sandbox probe requires a repository path',
+  }),
+  'dispatcher-agent-input-known': Object.freeze({
+    data: Object.freeze(['agentType']),
+    category: 'internal',
+    message: ({ agentType }) => `unknown dispatcher agent ${JSON.stringify(agentType)}`,
+  }),
+  'dispatcher-prompt-text-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'prompt text is missing or is not text',
+  }),
+  'dispatcher-refusal': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: ({ reason }) => `Refused: ${reason}.`,
+  }),
+  'dispatcher-gate-internal-error': Object.freeze({
+    data: Object.freeze(['message']),
+    category: 'internal',
+    message: ({ message }) => `codex-bridge dispatcher gate: internal error: ${message}`,
+  }),
+  'dispatcher-protocol-key-known': Object.freeze({
+    data: Object.freeze(['key']),
+    category: 'internal',
+    message: ({ key }) => `unknown dispatcher protocol key: ${key}`,
+  }),
+  'dispatcher-state-identity-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'sessionId and agentId must be non-empty strings',
+  }),
+  'dispatcher-state-mutator-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'mutate must be a function',
+  }),
+  'dispatcher-state-record-required': Object.freeze({
+    data: Object.freeze([]),
+    category: 'internal',
+    message: () => 'mutate must produce a JSON record object',
+  }),
+  'install-record-owners-problem-known': Object.freeze({
+    data: Object.freeze(['problem']),
+    category: 'internal',
+    message: ({ problem }) => `unknown dispatcher-pin-owner-record problem: ${problem}`,
+  }),
+});

package/src/home/lib/order-diagnostics/run-state.mjs

@@ -0,0 +1,58 @@
+/** Plan_79 D4: owns diagnostics for the run's state at refusal. */
+export const DIAGNOSTICS = Object.freeze({
+  'run-not-created': Object.freeze({
+    data: Object.freeze([]),
+    category: 'run-state',
+    message: () => 'The run folder was not created; quota was not spent.',
+  }),
+  'advise-scope-result-readable': Object.freeze({
+    data: Object.freeze(['scopeFile', 'message']),
+    category: 'run-state',
+    message: ({ scopeFile, message }) => `Cannot read advise scope result at ${scopeFile}: ${message}`,
+  }),
+  'advise-scope-result-shape': Object.freeze({
+    data: Object.freeze(['scopeFile']),
+    category: 'run-state',
+    message: ({ scopeFile }) =>
+      `Malformed advise scope result at ${scopeFile}: expected predicted_risks and missing_paths arrays.`,
+  }),
+  'repository-detached-after-abandoned-run': Object.freeze({
+    data: Object.freeze(['run', 'branch']),
+    category: 'run-state',
+    message: ({ run, branch }) =>
+      `repository is detached after abandoned run ${run}, which recorded branch ${branch}. ` +
+      `Return with: git checkout ${branch}. No run folder was created and no quota was spent.`,
+  }),
+  'codex-not-started': Object.freeze({
+    data: Object.freeze([]),
+    category: 'run-state',
+    message: () => 'Codex was not started; quota was not spent',
+  }),
+  'dispatcher-order-transcript-readable': Object.freeze({
+    data: Object.freeze(['transcriptPath']),
+    category: 'run-state',
+    message: ({ transcriptPath }) => `the order could not be read from the agent transcript ${transcriptPath}`,
+  }),
+  'dispatcher-order-refusal': Object.freeze({
+    data: Object.freeze([]),
+    category: 'run-state',
+    message: ({ refusal }) => `FAIL — dispatcher gate: ${refusal}`,
+  }),
+  'dispatcher-receipt-conflict': Object.freeze({
+    data: Object.freeze(['runReceipt', 'runReceiptConflict']),
+    category: 'run-state',
+    message: ({ runReceipt, runReceiptConflict }) =>
+      'FAIL — dispatcher gate: the runner reported two different run folders for one dispatcher: ' +
+      `${runReceipt} and ${runReceiptConflict}; the answer is not delivered.`,
+  }),
+  'dispatcher-did-not-delegate': Object.freeze({
+    data: Object.freeze(['command']),
+    category: 'run-state',
+    message: ({ command }) => 'FAIL — dispatcher did not delegate: it handed back without running `' + command + '`',
+  }),
+  'dispatcher-runner-output': Object.freeze({
+    data: Object.freeze(['output']),
+    category: 'run-state',
+    message: ({ output }) => output,
+  }),
+});

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

@@ -0,0 +1,48 @@
+/** Plan_79 D4: each diagnostic category owns its own file named after it under order-diagnostics/. */
+import { DIAGNOSTICS as CLI_FLAGS_DIAGNOSTICS } from './order-diagnostics/cli-flags.mjs';
+import { DIAGNOSTICS as FILESYSTEM_ACCESS_DIAGNOSTICS } from './order-diagnostics/filesystem.mjs';
+import { DIAGNOSTICS as HOST_STATE_DIAGNOSTICS } from './order-diagnostics/host-state.mjs';
+import { DIAGNOSTICS as RUN_STATE_DIAGNOSTICS } from './order-diagnostics/run-state.mjs';
+import { DIAGNOSTICS as INTERNAL_DIAGNOSTICS } from './order-diagnostics/internal.mjs';
+import { recordOrderText, checkOrderTextParameters } from './order-text-record.mjs';
+
+export const DIAGNOSTIC_CATEGORIES = Object.freeze([
+  'cli-flags', 'filesystem', 'host-state', 'run-state', 'internal',
+]);
+
+const categories = [CLI_FLAGS_DIAGNOSTICS, FILESYSTEM_ACCESS_DIAGNOSTICS, HOST_STATE_DIAGNOSTICS, RUN_STATE_DIAGNOSTICS, INTERNAL_DIAGNOSTICS];
+const keys = new Set();
+for (const diagnostics of categories) {
+  for (const key of Object.keys(diagnostics)) {
+    if (keys.has(key)) throw new Error(`duplicate order diagnostic key: ${key}`);
+    keys.add(key);
+  }
+}
+export const ORDER_DIAGNOSTICS = Object.freeze(Object.assign({}, ...categories));
+
+export function orderDiagnosticMessage(key, values = {}) {
+  if (!Object.hasOwn(ORDER_DIAGNOSTICS, key)) throw new Error(`unknown order diagnostic: ${key}`);
+  checkOrderTextParameters('orderDiagnosticMessage', key, values, ORDER_DIAGNOSTICS[key].data);
+  return recordOrderText(ORDER_DIAGNOSTICS[key].message(values));
+}
+
+export function validateOrderDiagnostics(diagnostics) {
+  for (const [key, entry] of Object.entries(diagnostics)) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(key)) {
+      throw new Error(`invalid order diagnostic key: ${key}`);
+    }
+    if (!entry || Object.keys(entry).length !== 3 ||
+        !['category', 'message', 'data'].every((field) => Object.hasOwn(entry, field))) {
+      throw new Error(`invalid order diagnostic entry: ${key}`);
+    }
+    if (!DIAGNOSTIC_CATEGORIES.includes(entry.category)) {
+      throw new Error(`unknown order diagnostic category: ${key}`);
+    }
+    if (typeof entry.message !== 'function') throw new Error(`invalid order diagnostic message: ${key}`);
+    if (!Array.isArray(entry.data) ||
+        ![...entry.data].every((name) => typeof name === 'string' && name.trim()) ||
+        new Set(entry.data).size !== entry.data.length) {
+      throw new Error(`invalid order diagnostic data: ${key}`);
+    }
+  }
+}

package/src/home/lib/order-rules/call.mjs

@@ -0,0 +1,130 @@
+/** Plan_79 D4: owns rules for the call line and the task file itself. */
+export const RULES = Object.freeze({
+  'task-file-path': Object.freeze({
+    data: Object.freeze(['value']),
+    topic: 'order',
+    rule: 'The call names the task file by an absolute path to a file the orchestrator wrote with its file tool.',
+    message: ({ value }) => `--task-file must be an absolute path; got ${JSON.stringify(value)}`,
+  }),
+  'task-body-required': Object.freeze({
+    data: Object.freeze(['channel', 'taskFile']),
+    topic: 'order',
+    rule: 'The task file carries a non-empty body after the header and the blank line.',
+    message: ({ channel, taskFile }) => {
+      if (channel === 'task-file') return `task file from --task-file is empty: ${taskFile}`;
+      if (channel === 'stdin') return 'task text on stdin is empty';
+      throw new Error(`unknown task-body-required channel: ${channel}`);
+    },
+  }),
+  'writing-run-exclusive': Object.freeze({
+    data: Object.freeze(['run', 'activePath', 'identity']),
+    topic: 'order',
+    rule: 'Wait for the active writing run to finish before starting another writing run in the same working tree.',
+    message: ({ run, activePath, identity }) => {
+      const identityNote = identity === 'unverified' ? '; process identity could not be confirmed' : '';
+      return [
+        `run ${run} is already active for this repository; two writing runs in one tree are prohibited${identityNote}`,
+        `Active run: ${activePath}`,
+      ].join('\n');
+    },
+  }),
+  'order-launch-exclusive': Object.freeze({
+    data: Object.freeze(['variant', 'orderId', 'role', 'pid', 'acquiredAt', 'run']),
+    topic: 'order',
+    rule: 'Launch one run per order id at a time; repeat the same command to attach to that run.',
+    message: ({ variant, orderId, role, pid, acquiredAt, run, holderDescription }) => {
+      if (variant === 'holder-unverified') return 'a process that did not answer (unverified)';
+      if (variant === 'holder') return `${role} pid ${pid} since ${acquiredAt}`;
+      if (variant === 'busy') {
+        return `order id "${orderId}" is being launched by ${holderDescription}; repeat the same command later — ` +
+          'it attaches to that run instead of starting another.';
+      }
+      if (variant === 'race') {
+        return `another launch of order id "${orderId}" registered ${run} while this one was preparing; ` +
+          'repeat the same command — it attaches to that run.';
+      }
+      throw new Error(`unknown order-launch-exclusive variant: ${variant}`);
+    },
+  }),
+  'agent-call-model': Object.freeze({
+    data: Object.freeze(['agentType']),
+    topic: 'order',
+    rule: 'Call a dispatcher without model; its installed agent file owns the model.',
+    message: ({ agentType }) =>
+      "Order gate denied the Agent call because it passes `model`: a dispatcher's model is set in one place, "
+      + `its installed agent file. Call ${agentType} without model.`,
+  }),
+  'agent-call-teammate': Object.freeze({
+    data: Object.freeze(['field', 'agentType']),
+    topic: 'order',
+    rule: 'Call a dispatcher with subagent_type only, without teammate fields.',
+    message: ({ field, agentType }) =>
+      `Order gate denied the Agent call because it passes \`${field}\`: a dispatcher launched as a `
+      + 'teammate escapes the dispatcher gate, whose agent_type becomes the teammate name. Call '
+      + `${agentType} with subagent_type only, without name or team_name.`,
+  }),
+  'dispatcher-call-shape': Object.freeze({
+    data: Object.freeze(['violation', 'label', 'first', 'line', 'sequence']),
+    topic: 'order',
+    rule: 'The call contains one exact task file label with a non-empty absolute path safe inside shell double quotes.',
+    message: ({ violation, label, first, line, sequence }) => {
+      if (violation === 'free-text') return 'not a `label: value` line; free text belongs in the task file';
+      if (violation === 'empty') return `label \`${label}\` has an empty value`;
+      if (violation === 'duplicate') return `label \`${label}\` is given twice (line ${first} and line ${line})`;
+      if (violation === 'spelling') return `write the label exactly as \`${label}:\``;
+      if (violation === 'header') {
+        return `label \`${label}\` moved to the task-file header; the call is only \`task file: <absolute path>\``;
+      }
+      if (violation === 'missing') return `missing required label \`${label}\``;
+      if (violation === 'placeholder') return `label \`${label}\` is still a placeholder`;
+      if (violation === 'absolute') return 'label `task file` must be an absolute path';
+      if (violation === 'unsafe') {
+        return `label \`${label}\` contains ${JSON.stringify(sequence)}; put free text in the task file`;
+      }
+      if (violation === 'rewritten') {
+        return `label \`${label}\` contains ${JSON.stringify(sequence)}, which the shell rewrites inside double quotes; `
+          + 'write the path with forward slashes and without `$`';
+      }
+      throw new Error(`unknown dispatcher-call-shape violation: ${violation}`);
+    },
+  }),
+  'dispatcher-task-file-help': Object.freeze({
+    data: Object.freeze([]),
+    topic: 'order',
+    rule: 'The orchestrator writes the task file verbatim with its file tool and supplies its absolute path.',
+    message: () => 'Absolute path to a file holding the task statement verbatim, written by the orchestrator with its file tool. The dispatcher passes the path to the runner and never creates, reads or rewrites the file: writing it from the shell reintroduces the permission prompt this file channel exists to remove. Given no path, return the refusal.',
+  }),
+  'dispatcher-call-refusal': Object.freeze({
+    data: Object.freeze(['part', 'line', 'text', 'label', 'example']),
+    topic: 'order',
+    rule: 'The Agent call text is only `task file: <absolute path>`; every order label goes in the task-file header ' +
+      'and free text in the task file body.',
+    message: ({ part, line, text, label, example, reason, detail, explanation, reasons }) => {
+      if (part === 'intro') return 'Order gate denied the Agent call: the call text must be only `label: value` lines.';
+      if (part === 'detail') return ` — ${explanation} Example: \`${label}: ${example}\`.`;
+      if (part === 'problem') return `- ${reason}${detail}`;
+      if (part === 'line') return `- line ${line}: \`${text}\` — ${reason}`;
+      if (part === 'call') return 'The call is only `task file: <absolute path>`.';
+      if (part === 'header') return 'The order goes in the header at the top of that file:';
+      if (part === 'free-text') return 'Free text belongs in the task file.';
+      if (part === 'command-line') return `line ${line}: ${reason}`;
+      if (part === 'command') return `the call text must be only label: value lines: ${reasons}`;
+      throw new Error(`unknown dispatcher-call-refusal part: ${part}`);
+    },
+  }),
+  'dispatcher-call-summary': Object.freeze({
+    data: Object.freeze(['variant', 'required', 'conditional', 'optional']),
+    topic: 'order',
+    rule: 'Each dispatcher description names the header labels its task file requires, the conditional ones ' +
+      'with their condition, and the optional ones.',
+    message: ({ variant, required, conditional, optional }) => {
+      if (variant === 'unknown-agent') return '';
+      if (variant === 'labels') {
+        return `The call is only \`task file\` (an absolute path). The task-file header requires ${required.join(', ')}; `
+          + `conditional labels: ${conditional.join(', ')}; optional labels: ${optional.join(', ')}. `
+          + 'Free text belongs in the task file.';
+      }
+      throw new Error(`unknown dispatcher-call-summary variant: ${variant}`);
+    },
+  }),
+});