@dzhechkov/harness-core 0.8.10 → 0.8.11

package/src/codex-invoke.ts

@@ -0,0 +1,138 @@
+/**
+ * The one supported way to invoke Codex from a Claude Code session.
+ *
+ * Three failure modes were measured on 2026-08-31, each violating knowledge we had already
+ * written down and could not enforce: the fire-and-forget wrapper returning a dispatch stub for a
+ * stage whose deliverable is its return value; a prompt passed as a shell ARGUMENT whose backticks
+ * the shell read as command substitution, leaving codex to read an empty stdin and hang for 26
+ * minutes; and an unscoped run spending its whole budget exploring the tree and returning no
+ * verdict at all.
+ *
+ * The cure is structural, not advisory: this module has no parameter that accepts a prompt STRING
+ * (so a shell can never mangle it), a timeout is always present, and the outcome set is CLOSED —
+ * either the model's text, or one of five named refusals. There is no third state, which is the
+ * property the tests pin.
+ */
+
+/** Every way this can fail, enumerated. A refusal outside this set is a bug, not a new case. */
+export type CodexRefusal =
+  | 'timeout'
+  | 'no-output'
+  | 'model-unavailable'
+  | 'tool-error'
+  | 'bad-usage';
+
+export interface CodexOk {
+  readonly ok: true;
+  readonly text: string;
+  readonly model: string;
+  readonly elapsedMs: number;
+}
+
+export interface CodexRefused {
+  readonly ok: false;
+  readonly refusal: CodexRefusal;
+  /** Human-readable, names WHAT was observed — never a guess at the cause. */
+  readonly detail: string;
+  readonly model?: string;
+  readonly elapsedMs?: number;
+}
+
+export type CodexOutcome = CodexOk | CodexRefused;
+
+export const CODEX_DEFAULT_TIMEOUT_MS = 600_000;
+export const CODEX_PROBE_TIMEOUT_MS = 90_000;
+
+/** Model ids this account has been seen to answer on. A name here is spellable, never available. */
+export const CODEX_KNOWN_MODELS = ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5'] as const;
+
+export interface CodexRunInput {
+  /** Absolute path to a file holding the prompt. There is deliberately no string variant. */
+  readonly promptFile: string;
+  readonly model: string;
+  readonly timeoutMs?: number;
+  /**
+   * Files the model may read. REQUIRED for review-shaped work: an unscoped run was measured at
+   * 280s / exit 124 / 416KB of exploration and no verdict, while the same question scoped to two
+   * named files answered in 41s. Empty means "no scope declared" and is allowed only for a
+   * self-contained question that needs no repository access.
+   */
+  readonly scope?: readonly string[];
+  readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+}
+
+/** What a runner must provide. Kept tiny so tests can substitute it without spawning anything. */
+export interface CodexRunner {
+  (argv: readonly string[], timeoutMs: number): {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+  };
+}
+
+/** Build the argv. Exported so a test can assert the prompt never rides on the command line. */
+export function codexArgv(input: CodexRunInput): string[] {
+  const argv = ['exec', '-m', input.model, '--skip-git-repo-check'];
+  if (input.effort !== undefined) argv.push('-c', `model_reasoning_effort=${input.effort}`);
+  return argv;
+}
+
+/** Turn a raw runner result into the closed outcome set. */
+export function classifyCodexResult(
+  raw: { status: number | null; stdout: string; stderr: string; timedOut: boolean },
+  model: string,
+  elapsedMs: number,
+): CodexOutcome {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      refusal: 'timeout',
+      detail: `no answer within the deadline (${elapsedMs}ms); narrow the scope rather than raising the ceiling — an unscoped run spends the budget exploring`,
+      model,
+      elapsedMs,
+    };
+  }
+  if (raw.status !== 0) {
+    return {
+      ok: false,
+      refusal: 'tool-error',
+      detail: `codex exited ${raw.status === null ? 'by signal' : String(raw.status)}: ${raw.stderr.trim().slice(0, 300) || '(no stderr)'}`,
+      model,
+      elapsedMs,
+    };
+  }
+  const text = raw.stdout.trim();
+  if (text === '') {
+    // Silence is the failure this module exists to make impossible. A clean exit with nothing
+    // written is what a mangled prompt looks like from the outside, and it must never read as ok.
+    return {
+      ok: false,
+      refusal: 'no-output',
+      detail: 'codex exited 0 but wrote nothing — an empty answer is a refusal, never a clean result',
+      model,
+      elapsedMs,
+    };
+  }
+  return { ok: true, text, model, elapsedMs };
+}
+
+/** Compose the prompt file's content: the task, plus the scope fence when one is declared. */
+export function codexPromptBody(task: string, scope?: readonly string[]): string {
+  const trimmed = String(task ?? '').trim();
+  if (scope === undefined || scope.length === 0) return trimmed;
+  const list = scope.map((p) => `- ${p}`).join('\n');
+  return [
+    trimmed,
+    '',
+    'SCOPE — read ONLY these files and do not open others. This bound is what makes an answer',
+    'possible at all: an unscoped run was measured spending its entire budget exploring the tree',
+    'and returning no verdict.',
+    list,
+  ].join('\n');
+}
+
+/** True when the outcome may be consumed as an answer. Exists so callers cannot forget the check. */
+export function codexAnswered(outcome: CodexOutcome): outcome is CodexOk {
+  return outcome.ok === true;
+}

package/src/discrimination-gate.ts

@@ -137,12 +137,103 @@ export interface ClassifyResultRow {
   readonly tipEvidence?: ExecutionEvidence;
 }
 
+/** A CLOSED runner selection derived from the target package, never a command copied from package.json. */
+export type RunnerSelection =
+  | {
+      readonly kind: 'vitest';
+      readonly command: 'npx vitest run';
+      readonly runnerName: 'vitest';
+      readonly how: 'scripts.test' | 'dev-dependency';
+    }
+  | {
+      readonly kind: 'node-test';
+      readonly command: 'node --test';
+      readonly runnerName: 'node --test';
+      readonly how: 'scripts.test';
+    }
+  | {
+      readonly kind: 'unsupported';
+      readonly runnerName: string;
+      readonly scriptsTest: string | null;
+    };
+
+export type PlannedRunnerSelection =
+  | RunnerSelection
+  | {
+      readonly kind: 'explicit';
+      readonly command: string;
+      readonly runnerName: string;
+      readonly how: 'explicit-flag';
+    };
+
+export interface BaseRefResolution {
+  readonly requestedRef: string;
+  readonly resolvedRef: string;
+  readonly how: 'explicit-ref' | 'merge-base';
+}
+
+/**
+ * Select one of the two runner families this instrument can measure honestly.
+ *
+ * The package script is used only for classification. Its flags and shell text are never spliced
+ * into a command: a wrapper or a third runner family is an explicit unsupported result. Vitest in
+ * devDependencies is the sole tie-break when scripts.test is absent; it still maps to the fixed
+ * command template below.
+ */
+export function selectRunner(scriptsTest: string | null, devDeps: readonly string[]): RunnerSelection {
+  const script = typeof scriptsTest === 'string' && scriptsTest.trim() ? scriptsTest.trim() : null;
+  const tokens = script?.split(/\s+/) ?? [];
+  const hasShellControl = script !== null && /[\0`$;&|<>()\n\r]/.test(script);
+
+  if (!hasShellControl) {
+    const vitestOffset =
+      tokens[0] === 'vitest'
+        ? 0
+        : tokens[0] === 'npx' && tokens[1] === 'vitest'
+          ? 1
+          : tokens[0] === 'pnpm' && tokens[1] === 'exec' && tokens[2] === 'vitest'
+            ? 2
+            : -1;
+    if (vitestOffset >= 0) {
+      return { kind: 'vitest', command: 'npx vitest run', runnerName: 'vitest', how: 'scripts.test' };
+    }
+    if (tokens[0] === 'node' && tokens[1] === '--test') {
+      return { kind: 'node-test', command: 'node --test', runnerName: 'node --test', how: 'scripts.test' };
+    }
+  }
+
+  const deps = Array.isArray(devDeps) ? devDeps : [];
+  if (script === null && deps.some((dep) => dep === 'vitest')) {
+    return { kind: 'vitest', command: 'npx vitest run', runnerName: 'vitest', how: 'dev-dependency' };
+  }
+
+  return { kind: 'unsupported', runnerName: tokens[0] ?? 'none', scriptsTest: script };
+}
+
+/** Resolve an audited pre-feature ref supplied by the executor. HEAD never wins over a merge-base. */
+export function resolveDiscriminationBaseRef(requestedRef: string, mergeBaseRef?: string): BaseRefResolution {
+  const requested = typeof requestedRef === 'string' ? requestedRef.trim() : '';
+  const mergeBase = typeof mergeBaseRef === 'string' ? mergeBaseRef.trim() : '';
+  if (requested === 'HEAD' && mergeBase) {
+    return { requestedRef: requested, resolvedRef: mergeBase, how: 'merge-base' };
+  }
+  return { requestedRef: requested, resolvedRef: requested, how: 'explicit-ref' };
+}
+
 export interface DiscriminationPlanInput {
   /** the git ref of pre-feature HEAD — the "base" the property test must fail against. */
   readonly baseRef: string;
+  /** merge-base already measured by the executor; mandatory to displace a sweeping HEAD. */
+  readonly mergeBaseRef?: string;
   /** property test(s) mapped from the ADR Confirmation. Empty ⇒ CANNOT_ISOLATE. */
   readonly propertyTests: readonly PropertyTestRef[];
-  /** test-runner command template; sanitized. Default `npx vitest run`. */
+  /** repo-relative directory owning the TARGET package.json; `.` when the repository root owns it. */
+  readonly packageDir?: string;
+  /** TARGET package.json scripts.test. It is classified, never executed verbatim. */
+  readonly packageTestScript?: string | null;
+  /** TARGET package devDependency names, used only for the documented vitest tie-break. */
+  readonly packageDevDependencies?: readonly string[];
+  /** explicit safe escape hatch. Absence derives from packageTestScript; unsafe input refuses. */
   readonly runner?: string;
 }
 
@@ -151,19 +242,33 @@ export interface DiscriminationPlan {
   readonly runnable: boolean;
   /** why not runnable, when `runnable` is false. */
   readonly reason?: string;
+  /** Plan-time state. REFUSE is non-passing; PENDING says execution evidence is still required. */
+  readonly verdict: 'PENDING' | 'REFUSE';
+  /** A plan alone has measured nothing; in particular every refusal is false. */
+  readonly measurementValid: false;
+  readonly primaryAction: PrimaryAction;
   /** the sanitized base ref actually used. */
   readonly baseRef: string;
+  readonly baseRefResolution: BaseRefResolution;
+  readonly runnerSelection: PlannedRunnerSelection;
+  readonly packageDir: string;
   /** the accepted, sanitized targets. */
   readonly targets: readonly PropertyTestRef[];
   /** refs rejected by sanitation, with the reason — surfaced so a rejection is never silent. */
   readonly rejected: readonly { readonly file: string; readonly reason: string }[];
   /**
-   * Ordered shell steps the caller runs: add a detached worktree at baseRef, copy each NEW property test
-   * file into it (they do not exist at base), run the runner over the targets, then remove the worktree.
+   * Ordered shell steps the caller runs: add the complete detached revision at baseRef, run the selected
+   * package-scoped command over positional targets, then remove the worktree. No lone-file tree is valid.
    * `{{WORKTREE}}` is a placeholder the caller substitutes with a fresh temp dir path it owns — the engine
    * never invents a filesystem path. Commands use only sanitized tokens.
    */
   readonly commands: readonly string[];
+  /** The detached worktree itself supplies the complete revision; no lone-file copy is an isolation tree. */
+  readonly isolation: {
+    readonly materialization: 'full-revision-tree';
+    readonly revision: string;
+    readonly overlays: readonly string[];
+  };
 }
 
 export interface ClassifyInput {
@@ -228,7 +333,6 @@ const SAFE_REF = /^[A-Za-z0-9_][A-Za-z0-9_./~^@{}-]{0,199}$/;
  * relative file, and anything exotic is safer rejected (and surfaced) than quoted-and-hoped.
  */
 const UNSAFE_PATH = /(^\/)|(^[A-Za-z]:)|(^~)|(^-)|(\/-)|(\.\.(\/|\\|$))|[\0`$;&|<>*?"'\n\r\t \\]/;
-const DEFAULT_RUNNER = 'npx vitest run';
 /** a runner must be a plain command with flags — no shell metacharacters that could chain a second command. */
 const UNSAFE_RUNNER = /[\0`$;&|<>()\n\r]/;
 
@@ -244,15 +348,42 @@ function sanitizeName(name: string): string | null {
  * ordered worktree commands. Returns `runnable:false` with a reason when there is nothing safe to run.
  */
 export function planDiscriminationCheck(input: DiscriminationPlanInput): DiscriminationPlan {
-  const baseRef = typeof input.baseRef === 'string' ? input.baseRef.trim() : '';
+  const requestedBaseRef = typeof input.baseRef === 'string' ? input.baseRef.trim() : '';
+  const baseRefResolution = resolveDiscriminationBaseRef(requestedBaseRef, input.mergeBaseRef);
+  const baseRef = baseRefResolution.resolvedRef;
+  const packageDirRaw = typeof input.packageDir === 'string' ? input.packageDir.trim().replace(/\/$/, '') : '.';
+  const packageDir = packageDirRaw || '.';
   const rejected: { file: string; reason: string }[] = [];
+  const explicitRunner = typeof input.runner === 'string' && input.runner.trim() ? input.runner.trim() : null;
+  const runnerName = explicitRunner?.split(/\s+/)[0] ?? 'none';
+  const runnerSelection: PlannedRunnerSelection = explicitRunner
+    ? { kind: 'explicit', command: explicitRunner, runnerName, how: 'explicit-flag' }
+    : selectRunner(input.packageTestScript ?? null, input.packageDevDependencies ?? []);
+  const isolation = { materialization: 'full-revision-tree', revision: baseRef, overlays: [] } as const;
+
+  const refuse = (reason: string, action: PrimaryAction = 'fix-runner-invocation'): DiscriminationPlan => ({
+    runnable: false,
+    reason,
+    verdict: 'REFUSE',
+    measurementValid: false,
+    primaryAction: action,
+    baseRef,
+    baseRefResolution,
+    runnerSelection,
+    packageDir,
+    targets: [],
+    rejected,
+    commands: [],
+    isolation,
+  });
 
-  if (!SAFE_REF.test(baseRef)) {
-    return { runnable: false, reason: 'unsafe-or-missing-base-ref', baseRef, targets: [], rejected, commands: [] };
+  if (!SAFE_REF.test(requestedBaseRef) || !SAFE_REF.test(baseRef)) {
+    return refuse('unsafe-or-missing-base-ref');
   }
 
-  const runnerRaw = typeof input.runner === 'string' && input.runner.trim() ? input.runner.trim() : DEFAULT_RUNNER;
-  const runner = UNSAFE_RUNNER.test(runnerRaw) ? DEFAULT_RUNNER : runnerRaw;
+  if (packageDir !== '.' && UNSAFE_PATH.test(packageDir)) {
+    return refuse('unsafe-package-dir');
+  }
 
   const targets: PropertyTestRef[] = [];
   const seen = new Set<string>();
@@ -260,6 +391,10 @@ export function planDiscriminationCheck(input: DiscriminationPlanInput): Discrim
     const file = t && typeof t.file === 'string' ? t.file.trim() : '';
     if (!file) { rejected.push({ file: String(t?.file ?? ''), reason: 'empty-path' }); continue; }
     if (UNSAFE_PATH.test(file)) { rejected.push({ file, reason: 'unsafe-path' }); continue; }
+    if (packageDir !== '.' && !file.startsWith(`${packageDir}/`)) {
+      rejected.push({ file, reason: 'outside-target-package' });
+      continue;
+    }
     const name = t && typeof t.name === 'string' ? sanitizeName(t.name) : null;
     if (t && typeof t.name === 'string' && name === null) { rejected.push({ file, reason: 'unsafe-test-name' }); continue; }
     const key = `${file}|${name ?? ''}`;
@@ -269,22 +404,51 @@ export function planDiscriminationCheck(input: DiscriminationPlanInput): Discrim
   }
 
   if (targets.length === 0) {
-    return { runnable: false, reason: 'no-isolable-test', baseRef, targets, rejected, commands: [] };
+    const plan = refuse('no-isolable-test', 'map-a-test');
+    return { ...plan, targets };
+  }
+
+  if (explicitRunner !== null && UNSAFE_RUNNER.test(explicitRunner)) {
+    const plan = refuse(`unsafe-runner:${runnerName}`);
+    return { ...plan, targets };
+  }
+
+  if (runnerSelection.kind === 'unsupported') {
+    const plan = refuse(`unsupported-runner:${runnerSelection.runnerName}`);
+    return { ...plan, targets };
   }
 
   // `{{WORKTREE}}` is substituted by the caller with a temp dir IT owns; the engine never invents a path.
-  // Paths are already metacharacter-free (UNSAFE_PATH), but quote them + use `--` so a leading-dash or spaced
-  // path can never become a runner option or split a word — belt-and-suspenders over the sanitation above.
+  // `git worktree add` materialises the complete base revision. No lone property-test copy is emitted:
+  // a copied test without its sibling source/config tree is not an isolated revision and cannot measure.
   const commands: string[] = [`git worktree add --detach {{WORKTREE}} ${baseRef}`];
-  for (const t of targets) {
-    commands.push(`mkdir -p "{{WORKTREE}}/$(dirname -- '${t.file}')" && cp -- '${t.file}' "{{WORKTREE}}/${t.file}"`);
-  }
-  const fileArgs = [...new Set(targets.map((t) => t.file))].map((f) => `'${f}'`).join(' ');
-  const nameFilters = targets.filter((t) => t.name).map((t) => `-t '${t.name}'`).join(' ');
-  commands.push(`( cd {{WORKTREE}} && ${runner}${nameFilters ? ' ' + nameFilters : ''} -- ${fileArgs} )`);
+  const relativeToPackage = (file: string): string => (packageDir === '.' ? file : file.slice(packageDir.length + 1));
+  const fileArgs = [...new Set(targets.map((t) => relativeToPackage(t.file)))].map((f) => `'${f}'`).join(' ');
+  const testNames = targets.filter((t) => t.name).map((t) => t.name as string);
+  const nameFilters =
+    runnerSelection.kind === 'node-test'
+      ? testNames.map((name) => `--test-name-pattern '${name}'`).join(' ')
+      : testNames.map((name) => `-t '${name}'`).join(' ');
+  const runner = runnerSelection.command;
+  const runnerArgs = `${runner}${nameFilters ? ` ${nameFilters}` : ''} ${fileArgs}`;
+  const worktreePackageDir = packageDir === '.' ? '{{WORKTREE}}' : `{{WORKTREE}}/${packageDir}`;
+  commands.push(`( cd "${worktreePackageDir}" && ${runnerArgs} )`);
   commands.push(`git worktree remove --force {{WORKTREE}}`);
 
-  return { runnable: true, baseRef, targets, rejected, commands };
+  return {
+    runnable: true,
+    verdict: 'PENDING',
+    measurementValid: false,
+    primaryAction: 'none',
+    baseRef,
+    baseRefResolution,
+    runnerSelection,
+    packageDir,
+    targets,
+    rejected,
+    commands,
+    isolation,
+  };
 }
 
 

package/src/event-chain.ts

@@ -224,6 +224,47 @@ export function readTailInfo(tailText: string, opts: { readonly partial?: boolea
 /** An empty log — what an appender assumes when the file is absent. */
 export const EMPTY_LOG_TAIL: LogTail = { lastLine: undefined, endsWithNewline: true, unreadable: false };
 
+/**
+ * ONE journal whose records are hash-chained, and the decision that rests on it.
+ *
+ * `decides` is not documentation garnish: it is the reason integrity matters HERE and not
+ * everywhere. A chain costs nothing to read and something to maintain, so a journal earns one by
+ * being the basis of a verdict — where a lost or duplicated record is a WRONG ANSWER WITH NO
+ * SYMPTOM. A journal nobody decides on does not need a chain, and saying so keeps the registry from
+ * growing into a list of every file we happen to append to.
+ */
+export interface ChainedJournal {
+  /** Path relative to the project root. */
+  readonly rel: string;
+  /** The verdict that would silently go wrong if a record were lost or duplicated. */
+  readonly decides: string;
+}
+
+/**
+ * THE registry of chained journals — the single list every verification surface reads.
+ *
+ * Why this exists (backlog `bc4ee35c`, W0-chain): the chain machinery was built, and then each
+ * consumer grew its OWN private list of which files carry a chain — `dz doctor` had a two-element
+ * array inline, the score aggregate checked its own file, and nothing checked the rest. Three
+ * surfaces, three lists, and no way to ask "are all the chained journals intact?" So a journal
+ * could be given a chain and STILL be checked by nobody: the mechanism present, the coverage
+ * absent, and no red anywhere to say so.
+ *
+ * MEASURED 2026-09-01: of eight append-only journals under `.dz/`, exactly two carry a chain
+ * (probe: `tail -1 <file>` for a `seq` field). Adding the third must be one line HERE, not one line
+ * in each surface — which is the whole point of a registry, and what its test pins.
+ */
+export const CHAINED_JOURNALS: readonly ChainedJournal[] = [
+  {
+    rel: '.dz/recall-usage.jsonl',
+    decides: 'dz compounding — whether a taught lesson is actually paying off',
+  },
+  {
+    rel: '.dz/guard-audit.jsonl',
+    decides: 'dz guard promote — whether a lesson has won twice and may become a rule',
+  },
+];
+
 /**
  * The exact text to append for a run of records: chained, newline-terminated, and preceded by a
  * newline when the file ends mid-line. THE one place that knows how to extend one of these logs —

package/src/guard.ts

@@ -77,6 +77,11 @@ export interface GuardFacts {
   readonly packages?: readonly { readonly name: string; readonly deps: Readonly<Record<string, string>> }[];
   /** for no-skill-drift: the names that byte-drift between copies (from sweepSkillDrift). */
   readonly drift?: readonly string[];
+  /**
+   * for codex-wrapper-for-value-stage: workflow scripts to scan, as (path, text). Absent ⇒ the
+   * rule reports nothing: a guard with no evidence must stay silent rather than invent a verdict.
+   */
+  readonly workflowScripts?: readonly { readonly path: string; readonly text: string }[];
   /** for no-secrets: labelled blobs to scan (lesson text, staged files). */
   readonly secretTargets?: readonly { readonly label: string; readonly text: string }[];
   /** for readme-consistency: labelled (a,b) count pairs that must be equal. */
@@ -306,6 +311,7 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'feature-artifact-diff-ratio', severity: 'soft', ops: ['publish'], description: 'observe feature artifact bytes against attributable unified-diff bytes, explicitly a proxy; advisory only' },
   { id: 'feature-tier-artifact-set', severity: 'soft', ops: ['publish'], description: 'observe artifacts due for the recorded feature tier, active steps, consumers, and lifecycle; advisory only' },
   { id: 'agents-md-policy-sync', severity: 'soft', ops: ['publish'], description: 'proves the AGENTS.md copy is in SYNC with its source — not that the runtime read or obeyed it; heal drift with dz agents-sync' },
+  { id: 'codex-wrapper-for-value-stage', severity: 'hard', ops: ['publish'], description: 'a workflow stage routed to the fire-and-forget codex wrapper must not have its return value consumed — the wrapper answers with a dispatch stub, never with the model' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
   // Description ASSEMBLED from STUB_MARKERS so guard.ts itself stays clean under the scan it defines
@@ -510,6 +516,40 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
       detail: `${drifted.length} AGENTS.md policy section(s) are out of sync: ${drifted.slice(0, 8).join(', ')}${drifted.length > 8 ? '…' : ''} — heal with: dz agents-sync`,
     }];
   },
+  /**
+   * The fire-and-forget wrapper returns a DISPATCH STUB, so a stage whose deliverable is its
+   * return value gets a receipt instead of an answer. MEASURED 2026-08-31: eight stages of one
+   * research swarm each returned "Codex Task started in the background as task-…", downstream
+   * agents built on those stubs, and no artifact was produced. The misuse is visible in the
+   * program text — the stage's result is assigned to a name that a later prompt interpolates —
+   * so it belongs on layer 1 rather than in a rule nobody re-reads.
+   */
+  'codex-wrapper-for-value-stage': (f, sev) => {
+    const scripts = f.workflowScripts;
+    if (scripts === undefined || scripts.length === 0) return [];
+    const out: Violation[] = [];
+    for (const s of scripts) {
+      const text = String(s.text ?? '');
+      // Find `const <name> = await agent(… codex:codex-rescue …)` and ask whether <name> is later
+      // interpolated into another prompt. Assignment alone is not the defect: a stage may keep its
+      // handle for logging. Consumption in a prompt is what proves the VALUE was the deliverable.
+      const re = /(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+agent\(([\s\S]{0,4000}?)\)\s*(?:\n|;)/g;
+      for (const m of text.matchAll(re)) {
+        const name = String(m[1]);
+        const call = String(m[2]);
+        if (!/codex:codex-rescue/.test(call)) continue;
+        const consumed = new RegExp('\\$\\{\\s*(?:String\\()?' + name.replace(/[.*+?^{}()|[\]\\]/g, '\\$&') + '\\b');
+        if (consumed.test(text)) {
+          out.push({
+            rule: 'codex-wrapper-for-value-stage',
+            severity: sev,
+            detail: `${s.path}: stage "${name}" is routed to codex:codex-rescue AND its result is interpolated into another prompt — the wrapper returns a dispatch stub, so that prompt would receive a receipt, not an answer. Invoke codex synchronously (dz codex / codex exec) for a stage whose deliverable is its return value.`,
+          });
+        }
+      }
+    }
+    return out;
+  },
   'lockfile-in-sync': (f, _sev) => {
     // The 2026-07-28 CI break, mechanized: an overnight dep bump edited package.json and left
     // pnpm-lock.yaml stale, so `pnpm install --frozen-lockfile` died with ERR_PNPM_OUTDATED_LOCKFILE.

package/src/index.ts

@@ -83,8 +83,8 @@ export type { SyncUpstreamReport, UpstreamCheckResult, SourcesManifest, SourcePa
 export { sweepSkillDrift, syncCanonicalSkill } from './skill-drift.js';
 export { SKILL_INSTALL_ROOTS, SKILL_INSTALL_ROOT_BY_TARGET, DEV_SKILL_ROOT, TARGET_ENRICHMENT_ASSETS } from './skill-install-roots.js';
 export { stampCheckpointLine } from './checkpoint-stamp.js';
-export { TELEMETRY_VOCAB_VERSION, TELEMETRY_FIELDS, PROVISIONAL_TELEMETRY_FIELDS, LOCAL_FIELD_ALIASES, telemetryFieldFor } from './telemetry-vocabulary.js';
-export type { TelemetryField, FieldSource } from './telemetry-vocabulary.js';
+export { TELEMETRY_VOCAB_VERSION, TELEMETRY_FIELDS, PROVISIONAL_TELEMETRY_FIELDS, LOCAL_FIELD_ALIASES, RUN_OUTCOMES, telemetryFieldFor, runOutcomeOf } from './telemetry-vocabulary.js';
+export type { TelemetryField, FieldSource, RunOutcome } from './telemetry-vocabulary.js';
 export { planLedgerBackfill, LEDGER_FILL_SOURCE, AMBIGUOUS, resolveLedgerRunId } from './ledger-backfill.js';
 // project-skills root resolution (field report doc-25b): the ONE builder behind both the Step-0
 // probe and the PS_GUIDANCE paragraph, so the two can never look at different roots again.
@@ -92,7 +92,8 @@ export { projectSkillsOneRoot, projectSkillsProbeCommand } from './project-skill
 export type { LedgerBackfillPlan, LedgerBackfillRow, RunCostFacts } from './ledger-backfill.js';
 export type { SweepResult, DriftedSkill, SyncResult, SyncCanonicalOptions } from './skill-drift.js';
 export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
-export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs, discoverVerifiablePackDirs } from './registry.js';
+export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs, discoverSkillCarryingDirs, discoverVerifiablePackDirs } from './registry.js';
+export { tokenize, stemToken, stems } from './stem.js';
 // Package skill-layout resolution (feature dz-install-npx-init) — the ONE seam that knows where an
 // npm package keeps its skills (flat / templates/.claude/skills / skills). `cmdInstall` calls it;
 // `dz init`/`dz registry` are the filed follow-up consumers.
@@ -577,6 +578,7 @@ export {
   DEFAULT_REWRITE_ATTEMPTS,
   liveSegmentStart,
   classifyChainDefects,
+  CHAINED_JOURNALS,
 } from './event-chain.js';
 export type {
   ChainFields,
@@ -593,6 +595,7 @@ export type {
   VerifyEventChainOptions,
   ChainDefectAge,
   ChainDefectAges,
+  ChainedJournal,
 } from './event-chain.js';
 export { decideProvenance, environmentCanMintProvenance, publishArgv, discoverPackages, publishPackages, bumpPatch, compareVersions, findUnpackagedSkills, findUnpublishedWorkspaceFloors, orderByDependencies, syncReadmeVersion, isChangelogEntryLine, changelogRegion } from './publish.js';
 export { fetchAllDownloads } from './downloads.js';
@@ -961,7 +964,8 @@ export {
 } from './epoch-replay.js';
 
 // Run-process scorecard (feature dz-score, Reading C) — scores the DISCIPLINE of a feature-adr run
-// from its artifacts. Descriptive-only, permanently: it never gates.
+// from its artifacts and folds immutable receipts into a chained aggregate. Descriptive-only,
+// permanently: neither the single-run score nor the aggregate gates.
 export * from './score.js';
 export * from './recap.js';
 export * from './provenance.js';
@@ -1037,3 +1041,5 @@ export type {
   Register, Domain, OperatorProfile, ProfileReadResult, ProfileSyncResult,
   ProfileDriftVerdict, ProfileDriftResult,
 } from './profile.js';
+export * from './codex-invoke.js';
+export * from './skill-selection.js';