@dzhechkov/harness-core 0.4.5 → 0.5.1

package/dist/targets.js

@@ -36,4 +36,164 @@ export const TARGET_NAMES = Object.keys(TARGETS);
 export function isTargetName(value) {
     return Object.prototype.hasOwnProperty.call(TARGETS, value);
 }
+// ---------------------------------------------------------------------------
+// `--target` resolution — alias table + did-you-mean (feature dz-cli-defects, D3)
+//
+// `isTargetName`, `TARGETS` and `TARGET_NAMES` above are UNCHANGED: `boundaries.json`
+// names `isTargetName` as the scanned validation boundary for `--target`, and every
+// resolution below ends in exactly that guard, so the security boundary is preserved
+// rather than relocated (ADR-002 / architecture §3.1).
+// ---------------------------------------------------------------------------
+/** `TARGET_NAMES` sorted alphabetically, for display in error messages. */
+export const TARGET_NAMES_SORTED = [...TARGET_NAMES].sort();
+/**
+ * Semantic `--target` aliases — DATA, not branching logic. Adding a row is one line
+ * and zero control flow (ADR-002 §Rationale D5).
+ *
+ * Purely typographic variants (`Claude_Code`, `claudecode`, `agents.md`) are handled by
+ * normalisation, not by rows; the rows below carry only meanings normalisation cannot
+ * derive (`claude` ≠ `claude-code` by any string rule — it is an owner decision).
+ */
+export const TARGET_ALIASES = {
+    claude: 'claude-code',
+    cc: 'claude-code',
+    agents: 'agents-md',
+    gpt: 'codex',
+    openai: 'codex',
+};
+/** Levenshtein suggestions are only offered at or below this edit distance. */
+export const TARGET_SUGGESTION_MAX_DISTANCE = 3;
+/**
+ * Normalise a `--target` token for matching: byte-level lowercase (never
+ * `toLocaleLowerCase` — behaviour must not vary with the host locale), trimmed, with
+ * every separator dropped so `Claude_Code`, `claude-code` and `claudecode` collapse.
+ *
+ * Exported so the alias-REACHABILITY test can ask the production normaliser whether a
+ * proposed alias row is already carried by precedence step 2, instead of keeping a
+ * second copy of this rule in the test file (fix round 1, QE F7).
+ */
+export function normalizeTargetToken(value) {
+    return value.trim().toLowerCase().replace(/[-_.\s]/g, '');
+}
+/** Iterative two-row Levenshtein. No dependency: harness-core ships no fuzzy matcher. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let curr = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i += 1) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min((curr[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        const swap = prev;
+        prev = curr;
+        curr = swap;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * Suggest a canonical target for an input that did not resolve.
+ *
+ * Two legs, in order, and each closes a case the other cannot:
+ *
+ * - **unique normalised prefix** — carries `clau → claude-code`, which is edit distance 5
+ *   and therefore unreachable by any sane Levenshtein threshold. An input that prefixes
+ *   TWO OR MORE canonical names is AMBIGUOUS and terminates with **no** suggestion
+ *   (`co` → `codex`/`copilot`): guessing between two live targets is worse than a
+ *   round-trip, and the fall-through would otherwise hand `co` to `codex` on a distance
+ *   of 3 — a confident answer to a question the user has not yet decided.
+ * - **Levenshtein ≤ 3, strictly better than the runner-up** — carries the typo case
+ *   `clade-code → claude-code`. A tie yields `null` for the same reason.
+ */
+function suggestTargetName(normalized) {
+    if (normalized.length === 0)
+        return null;
+    const prefixHits = TARGET_NAMES_SORTED.filter((name) => normalizeTargetToken(name).startsWith(normalized));
+    if (prefixHits.length === 1)
+        return prefixHits[0] ?? null;
+    // Ambiguous prefix is TERMINAL, not a fall-through (see doc comment).
+    if (prefixHits.length > 1)
+        return null;
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let runnerUpDistance = Number.POSITIVE_INFINITY;
+    for (const name of TARGET_NAMES_SORTED) {
+        const distance = levenshtein(normalized, normalizeTargetToken(name));
+        if (distance < bestDistance) {
+            runnerUpDistance = bestDistance;
+            bestDistance = distance;
+            best = name;
+        }
+        else if (distance < runnerUpDistance) {
+            runnerUpDistance = distance;
+        }
+    }
+    if (best === null)
+        return null;
+    if (bestDistance > TARGET_SUGGESTION_MAX_DISTANCE)
+        return null;
+    // Strictly better than the runner-up — a tie is not a suggestion.
+    if (bestDistance === runnerUpDistance)
+        return null;
+    return best;
+}
+/**
+ * Resolve a user-supplied `--target` value to a canonical {@link TargetName}.
+ *
+ * Total, pure, no I/O. Precedence (fixed and tested):
+ *
+ * 1. exact canonical hit → `{kind:'ok', via:'canonical'}` (`isTargetName` semantics);
+ * 2. normalised canonical hit → `{kind:'ok', via:'alias'}` (`Claude_Code`, `agentsmd`);
+ * 3. explicit {@link TARGET_ALIASES} row → `{kind:'ok', via:'alias'}`;
+ * 4. unique normalised prefix → `{kind:'unknown', suggestion}`;
+ * 5. Levenshtein ≤ 3 strictly better than the runner-up → `{kind:'unknown', suggestion}`;
+ * 6. otherwise → `{kind:'unknown', suggestion:null}`.
+ *
+ * **Aliases ACCEPT; prefix and Levenshtein only SUGGEST.** An alias row is an owner
+ * decision recorded in data; a fuzzy match is a guess, and silently installing to the
+ * wrong target on a guess is worse than one round-trip.
+ */
+export function resolveTargetName(value) {
+    if (isTargetName(value))
+        return { kind: 'ok', target: value, via: 'canonical' };
+    const normalized = normalizeTargetToken(value);
+    for (const name of TARGET_NAMES) {
+        if (normalizeTargetToken(name) === normalized) {
+            return { kind: 'ok', target: name, via: 'alias' };
+        }
+    }
+    const aliased = Object.prototype.hasOwnProperty.call(TARGET_ALIASES, normalized)
+        ? TARGET_ALIASES[normalized]
+        : Object.prototype.hasOwnProperty.call(TARGET_ALIASES, value.trim().toLowerCase())
+            ? TARGET_ALIASES[value.trim().toLowerCase()]
+            : undefined;
+    if (aliased !== undefined)
+        return { kind: 'ok', target: aliased, via: 'alias' };
+    return { kind: 'unknown', input: value, suggestion: suggestTargetName(normalized) };
+}
+/**
+ * Render the two-line failure for an unresolvable `--target`.
+ *
+ * Line 2 keeps the literal substring `--target must be one of:` — three shipped
+ * assertions (`test/cli.test.ts`) pin it, and keeping the shape additive is what makes
+ * the D3 change prove itself with NEW tests instead of rewriting old ones. The values
+ * are {@link TARGET_NAMES_SORTED} (alphabetical), which the pre-change message was not.
+ */
+export function formatTargetProblem(command, resolution) {
+    const suggestion = resolution.suggestion !== null ? ` — did you mean ${JSON.stringify(resolution.suggestion)}?` : '';
+    return [
+        `${command}: unknown --target ${JSON.stringify(resolution.input)}${suggestion}`,
+        `  --target must be one of: ${TARGET_NAMES_SORTED.join(', ')}`,
+    ];
+}
+/** The one-line diagnostic emitted (on stderr) when an alias was accepted. */
+export function formatTargetAliasNote(command, input, target) {
+    return `${command}: --target ${JSON.stringify(input)} → ${target} (alias)`;
+}
 //# sourceMappingURL=targets.js.map

package/dist/targets.js.map

@@ -1 +1 @@
-{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAU9D,iFAAiF;AACjF,iFAAiF;AACjF,wEAAwE;AACxE,MAAM,CAAC,MAAM,OAAO,GAAgC;IAClD,aAAa,EAAE,aAAa;IAC5B,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,aAAa;IACrB,UAAU,EAAE,iBAAiB;IAC7B,OAAO,EAAE,cAAc;IACvB,WAAW,EAAE,eAAe;IAC5B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,wEAAwE;IACxE,8EAA8E;IAC9E,QAAQ,EAAE,eAAe;CAC1B,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAiB,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../src/targets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAU9D,iFAAiF;AACjF,iFAAiF;AACjF,wEAAwE;AACxE,MAAM,CAAC,MAAM,OAAO,GAAgC;IAClD,aAAa,EAAE,aAAa;IAC5B,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,aAAa;IACrB,UAAU,EAAE,iBAAiB;IAC7B,OAAO,EAAE,cAAc;IACvB,WAAW,EAAE,eAAe;IAC5B,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,wEAAwE;IACxE,8EAA8E;IAC9E,QAAQ,EAAE,eAAe;CAC1B,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAiB,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,8EAA8E;AAC9E,kFAAkF;AAClF,EAAE;AACF,sFAAsF;AACtF,oFAAoF;AACpF,qFAAqF;AACrF,uDAAuD;AACvD,8EAA8E;AAE9E,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAA0B,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyC;IAClE,MAAM,EAAE,aAAa;IACrB,EAAE,EAAE,aAAa;IACjB,MAAM,EAAE,WAAW;IACnB,GAAG,EAAE,OAAO;IACZ,MAAM,EAAE,OAAO;CAChB,CAAC;AAqBF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,yFAAyF;AACzF,SAAS,WAAW,CAAC,CAAS,EAAE,CAAS;IACvC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,IAAI,GAAa,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,IAAI,GAAa,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,IAAI,GAAG,IAAI,CAAC;QACZ,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,iBAAiB,CAAC,UAAkB;IAC3C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CACrD,oBAAoB,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAClD,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1D,sEAAsE;IACtE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,IAAI,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC5C,IAAI,gBAAgB,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,mBAAmB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,WAAW,CAAC,UAAU,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;QACrE,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;YAC5B,gBAAgB,GAAG,YAAY,CAAC;YAChC,YAAY,GAAG,QAAQ,CAAC;YACxB,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;aAAM,IAAI,QAAQ,GAAG,gBAAgB,EAAE,CAAC;YACvC,gBAAgB,GAAG,QAAQ,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,YAAY,GAAG,8BAA8B;QAAE,OAAO,IAAI,CAAC;IAC/D,kEAAkE;IAClE,IAAI,YAAY,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC;IAEhF,MAAM,UAAU,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC/C,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YAC9C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QACpD,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GACX,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC;QAC9D,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC;QAC5B,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAChF,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC5C,CAAC,CAAC,SAAS,CAAC;IAClB,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAEhF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,UAA0D;IAE1D,MAAM,UAAU,GACd,UAAU,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,OAAO;QACL,GAAG,OAAO,sBAAsB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,EAAE;QAC/E,8BAA8B,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;KAC/D,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,KAAa,EAAE,MAAkB;IACtF,OAAO,GAAG,OAAO,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,MAAM,UAAU,CAAC;AAC7E,CAAC"}

package/dist/workflow-run-dispatch.d.ts

@@ -0,0 +1,230 @@
+/**
+ * `workflow-run-dispatch` — the DISPATCHER SEAM of `dz workflow run` (ADR-002 O1).
+ *
+ * Why a seam at all: the two runtimes disagree about almost everything that matters (stdin open vs
+ * closed, envelope shape, where a deliverable appears, what a clean exit means), and the scheduler
+ * must not know any of it. What it knows is: ask for a dispatch, get back a typed outcome whose
+ * failure reason is a member of ONE list.
+ *
+ * Everything below the contract is CONVENTION — and every convention here is a MEASURED lesson, not
+ * a preference. Each one is named at its definition with the observation that produced it, because
+ * a convention whose reason is lost is the next thing somebody "cleans up".
+ */
+import type { Deliverable } from './loop-plan.js';
+import { type BridgeFamily } from './qe-bridge.js';
+import type { WfRunReason } from './workflow-run.js';
+/** The dispatch REQUEST — every field resolved by the scheduler, so an adapter never re-decides. */
+export interface DispatchRequest {
+    stepId: string;
+    /** The fanout member key, or null for a top-level step. */
+    itemKey: string | null;
+    /** 1-based; INCLUDES the initial attempt. */
+    attempt: number;
+    /** Fully assembled (USER prompt + shared contract lines + item binding), ingress-defanged. */
+    prompt: string;
+    /** Resolved at preflight (AM-8) — TOTAL, never inferred inside the adapter. */
+    family: BridgeFamily;
+    /** The PROBED id, never the requested spec: an allowlist says a name is spellable, only a probe
+     * says it answers. */
+    resolvedModelId: string;
+    deliverable: Deliverable;
+    /** Declared reads — the input paths a file-mode step is asked to OPEN. They travel so the adapter
+     * (and the scheduler's dispatch-time containment re-check) can hold them to the SAME realpath /
+     * symlinked-ancestor discipline as writes: a read that escapes the root is not safer than a write
+     * that does (Step-8 re-QE R3-A). */
+    expectedReads: string[];
+    /** Declared writes. The scheduler owns the landed barrier (it snapshots the baseline); the
+     * adapter only needs to know the step is in file mode. */
+    expectedWrites: string[];
+    timeoutMs: number;
+    /** Target tree for file mode; ignored by a return-value claude dispatch (isolated temp cwd). */
+    cwd: string;
+}
+export interface DispatchFailure {
+    reason: WfRunReason;
+    detail: string;
+}
+export interface DispatchResult {
+    /** Pinned to the trace settle vocabulary (`loop-trace.ts` settle outcomes) — one word, two planes. */
+    outcome: 'ok' | 'null' | 'error';
+    /** Envelope-extracted text; null on null/error. */
+    text: string | null;
+    family: BridgeFamily;
+    modelUsed: string | null;
+    wallMs: number;
+    /** null when the runtime did not report a count — NEVER 0, never estimated (ADR-004 C4). */
+    tokensIn: number | null;
+    tokensOut: number | null;
+    tokensSource: 'claude-envelope' | 'codex-stderr' | null;
+    failure?: DispatchFailure;
+}
+export interface ProbeOutcome {
+    /** The id that ANSWERED, or null when no candidate did. */
+    id: string | null;
+    wallMs: number;
+    detail: string;
+}
+export interface Dispatcher {
+    /** Once per run per family; the result is cached by the SCHEDULER and persisted into run-state
+     * (AM-8), so a resume compares against the id that actually ran. */
+    probe(candidates: string[]): Promise<ProbeOutcome>;
+    dispatch(req: DispatchRequest): Promise<DispatchResult>;
+}
+/**
+ * The 4 reasons an ADAPTER may produce — the producer PARTITION of the one 22-member
+ * `WF_RUN_REASONS` list (K3). There is no second taxonomy: the type stays `WfRunReason`, and this
+ * array is the data a test uses to assert who is allowed to produce what. The other 18 members have
+ * preflight, scheduler or state-plane producers.
+ */
+export declare const DISPATCH_REASONS: readonly ["dispatch-timeout", "dispatch-dead", "prompt-over-ceiling", "probe-failed"];
+export type DispatchReason = (typeof DISPATCH_REASONS)[number];
+/** Measured 2026-08-12: a codex `exec` at xhigh effort needs this much wall clock at the far end of
+ * its distribution. Used as the scheduler's DEFAULT per-stage timeout when the operator gives none. */
+export declare const CODEX_EXEC_XHIGH_TIMEOUT_MS = 560000;
+export interface ChildRun {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    spawnError: string | null;
+}
+export type ChildRunner = (bin: string, argv: string[], opts: {
+    stdinText: string | null;
+    timeoutMs: number;
+    cwd: string;
+    detached: boolean;
+}) => Promise<ChildRun>;
+/**
+ * W1 — the timeout/dead discriminator, decided on the WRAPPER'S OWN FIELDS and nothing else.
+ *
+ * The distinction is load-bearing because the two have different retry semantics and different
+ * operator meanings: a timeout says "it was still working", a dead dispatch says "nothing came
+ * back". Deciding it from stderr text would make the verdict depend on a runtime's phrasing.
+ *
+ *   • `timedOut === true` ⇒ `timeout` — the deadline timer FIRED, full stop;
+ *   • a spawn error, or `exitCode === null` WITHOUT a timeout ⇒ `dead` (the process never ran, or
+ *     vanished);
+ *   • anything else ⇒ `exited`, and the FAMILY parser decides. A clean exit with no parseable
+ *     envelope is ALSO dead — the "spawned but mute" case — but that call belongs to the parser
+ *     that knows what an envelope looks like, not to this function.
+ */
+export declare function classifyChildRun(run: ChildRun): {
+    kind: 'timeout';
+} | {
+    kind: 'dead';
+    detail: string;
+} | {
+    kind: 'exited';
+    exitCode: number;
+};
+/**
+ * Prepended to a RETURN-VALUE codex dispatch. Codex `exec` is an agent with a workspace, not a
+ * completion endpoint: without this it will happily start reading files to answer a question whose
+ * whole answer is in the prompt. Paired with `--sandbox read-only`, which makes the instruction
+ * enforceable rather than advisory.
+ */
+export declare const CODEX_SCOPING_PREFIX = "Answer directly from this prompt text alone; no commands, no files, no tools.";
+/**
+ * The REAL prompt ceiling for `codex exec`.
+ *
+ * The folk value 1200 is refuted history: it came from an era when the prompt travelled through a
+ * fire-and-forget wrapper. Over-ceiling ⇒ a LOUD `prompt-over-ceiling`, never truncation — a
+ * truncated prompt produces a confident answer to a question nobody asked.
+ */
+export declare const CODEX_EXEC_PROMPT_CEILING_CHARS = 24000;
+/**
+ * argv for one codex dispatch. The prompt travels as ONE argv element (no shell, no quoting), and
+ * `stdinText` is ALWAYS null for codex — MEASURED this session: with stdin left open, codex-cli
+ * 0.148.0 prints `Reading additional input from stdin...` and waits. `< /dev/null` is not a style
+ * choice; it is the difference between a 5.7 s answer and a hang.
+ *
+ * Return-value mode gets the scoping prefix AND `--sandbox read-only`. File mode gets NEITHER: the
+ * step's whole deliverable is a file it must be able to write.
+ */
+export declare function codexExecArgv(modelId: string, prompt: string, deliverable: Deliverable): string[];
+/** The liveness probe: an allowlist says an id is SPELLABLE, only a probe says it ANSWERS. */
+export declare function codexProbeArgv(candidateId: string): string[];
+/** Word-bounded `OK` on a clean exit — the `interpretClaudeProbe` twin. */
+export declare function interpretCodexProbe(out: {
+    stdout: string;
+    exitCode: number | null;
+}): boolean;
+/**
+ * Best-effort token extraction from codex stderr — null when absent, NEVER 0 and never estimated.
+ *
+ * MEASURED (codex-cli 0.148.0, this session): the trailer is a TOTAL only —
+ * `tokens used\n9,820` — with no input/output split. `wf-budget-1` has no field for a total, and
+ * attributing a total to either half would be a fabrication, so this returns BOTH nulls for that
+ * shape and the row's `tokensSource` stays null. The split branch below exists because some
+ * builds/configs do print one; it is tested, not assumed. (Named consequence: codex runs report no
+ * token counts today. That is the honest state, not a bug to paper over — see the manifest.)
+ */
+export declare function extractCodexTokens(stderr: string): {
+    tokensIn: number | null;
+    tokensOut: number | null;
+};
+/**
+ * The claude `--output-format json` USAGE fields, pinned to the LIVE envelope shape.
+ *
+ * MEASURED this session (`claude -p --output-format json`, sonnet):
+ * `usage.input_tokens = 2`, `usage.output_tokens = 4`, alongside `cache_read_input_tokens` and
+ * `cache_creation_input_tokens`. Only the two plain counters are reported — cache tokens are a
+ * SEPARATE dimension `wf-budget-1` has no field for, and silently folding them into `tokensIn`
+ * would inflate every cached run's cost picture. Added to the architecture's export list; see the
+ * manifest.
+ */
+export declare function extractClaudeUsage(stdout: string): {
+    tokensIn: number | null;
+    tokensOut: number | null;
+};
+/**
+ * The codex adapter. Conventions, each a Confirmation-1 assertion:
+ * stdin ALWAYS closed; the prompt as one argv element; scoping prefix + `--sandbox read-only` on
+ * return-value and NEITHER on file mode; `detached: true` on every spawn (AM-10).
+ */
+export declare function makeCodexExecDispatcher(run: ChildRunner, opts?: {
+    bin?: string;
+    ceilingChars?: number;
+    isolatedCwd?: () => string;
+    monotonicMs?: () => number;
+}): Dispatcher;
+/**
+ * The claude adapter. Return-value mode is the `dz qe-bridge` ISOLATION discipline verbatim:
+ * `claudeReviewArgs(model)` (which carries `CLAUDE_ISOLATION_ARGS`: `--output-format json`,
+ * `--safe-mode`, `--strict-mcp-config`, `--tools ''`, `--no-session-persistence`), an EMPTY temp
+ * cwd so no project state leaks in, the prompt on STDIN (no ARG_MAX ceiling, no shell), and a
+ * LAST-anchored envelope parse so anything a customization printed first is structurally outside
+ * the reviewed text.
+ *
+ * File mode drops `--tools ''` and `--safe-mode` (the step's deliverable is a file it must write)
+ * and runs in `req.cwd`, but keeps `--output-format json` and the envelope parse — and the
+ * scheduler's landed barrier still has the last word.
+ */
+export declare function makeClaudePDispatcher(run: ChildRunner, opts?: {
+    bin?: string;
+    isolatedCwd?: () => string;
+    monotonicMs?: () => number;
+}): Dispatcher;
+/**
+ * FILE-mode claude argv: the isolation set MINUS the two flags that would make writing impossible
+ * (`--tools ''` and `--safe-mode`). Everything that makes the reply READABLE stays — the envelope
+ * is how the runner tells an answer from a banner, in either mode.
+ */
+export declare function claudeFileArgs(model: string): string[] | null;
+/**
+ * Neutralize anchored `GATE: PASS|FAIL` lines inside UPSTREAM text before it is spliced into a
+ * DOWNSTREAM prompt.
+ *
+ * Why this exists as a second defence, when `gateVerdict` is already LAST-anchored: the two attacks
+ * are different. The egress parser stops a single reply from smuggling a verdict past its own
+ * terminal line. This stops a reply that legitimately CONTAINS a verdict — an upstream gate's own
+ * answer — from becoming the terminal line of a DOWNSTREAM step's reply once the model quotes its
+ * input back. Without it, "please review the previous verdict" is a working exploit against a plan
+ * that never did anything wrong.
+ *
+ * NEUTRALIZATION, not deletion: the words survive so the downstream model can still read what the
+ * upstream said. Only the ANCHORED grammar is broken. Idempotent — defanging twice is defanging
+ * once, so a value that travels through three steps is not progressively mangled.
+ */
+export declare function defangGateEchoes(text: string): string;
+//# sourceMappingURL=workflow-run-dispatch.d.ts.map

package/dist/workflow-run-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-run-dispatch.d.ts","sourceRoot":"","sources":["../src/workflow-run-dispatch.ts"],"names":[],"mappings":"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"}