@claudexor/orchestrator 3.0.4 → 3.1.1

package/dist/deepScanReducer.d.ts

@@ -0,0 +1,148 @@
+import type { CostEvidence, DeepScanSynthesis, ExternalContextPolicy, HarnessEvent, HarnessRunSpec } from "@claudexor/schema";
+import { type BudgetLedger } from "@claudexor/budget";
+import type { RunPaths } from "@claudexor/artifact-store";
+import type { EventLog } from "@claudexor/event-log";
+import { type BudgetDenial } from "./budgetFailure.js";
+import type { RoutedAdapter } from "./orchestrator.js";
+import { type WorkReportEnvelopeMode } from "./attemptFinalize.js";
+import { type AttemptTelemetry } from "./attemptTelemetry.js";
+/** The reducer runs under the fixed `synth` attempt id (roster/cost visible). */
+export declare const DEEP_SCAN_REDUCER_ATTEMPT_ID = "synth";
+/**
+ * #27 / D-6: the HONEST fallback artifact for a deep scan whose bounded
+ * synthesis reducer did not run or did not succeed. It is explicitly labeled a
+ * raw scout bundle (a marker heading), never presented as a merged synthesis:
+ * the per-scout reports are concatenated verbatim with attribution, the roster
+ * denominator stays honest, and omissions are preserved. `skipped` (a single
+ * width-1 report) and `failed` (reducer error/timeout/budget-denial or no
+ * synthesize-capable route) get distinct honest intros.
+ */
+export declare function rawScoutBundle(args: {
+    succeeded: {
+        attemptId: string;
+        harnessId: string;
+        report: string;
+        telemetry: AttemptTelemetry;
+    }[];
+    unsuccessful: {
+        attemptId: string;
+        harnessId: string;
+        status: string;
+        error: string | null;
+    }[];
+    status: DeepScanSynthesis | null;
+}): string;
+/** A disposable read-only route context (env + reclaim). */
+export interface ReducerHome {
+    env: Record<string, string>;
+    dispose: () => void;
+}
+/** The engine-owned bits the reducer needs. `buildSpec` keeps the orchestrator's
+ * private route/session/knob machinery on the caller side and hands back only a
+ * finished, public `HarnessRunSpec` plus the disclosed web policy/model, so this
+ * module stays free of those private types (mirrors the council extraction). */
+export interface DeepScanReducerDeps {
+    /** Provision a fresh disposable read-only home (auth is home-independent). */
+    newReadOnlyHome: () => ReducerHome;
+    /** Per-attempt budget cost evidence (finite estimate floor + billing knowledge). */
+    costEvidence: (harnessId: string, attemptId: string) => CostEvidence;
+    /** Build the finished readonly/synthesize spec bound to the reducer home. */
+    buildSpec: (routed: RoutedAdapter, homeEnv: Record<string, string>, prompt: string, attemptId: string) => {
+        spec: HarnessRunSpec;
+        webPolicy: ExternalContextPolicy;
+        effectiveWeb: ExternalContextPolicy;
+        model: string | null;
+        /** D-16: the WorkReport transport mode compiled onto the reducer spec, so the
+         * reducer output is unwrapped + finalized through the SAME contract as every
+         * other attempt (never a fourth divergent deliverable predicate). Inactive on
+         * a route with no work_report transport (the report passes through untouched). */
+        workReportMode: WorkReportEnvelopeMode;
+    };
+    /** Hard (total) timeout for the single bounded pass. */
+    hardTimeoutMs: number;
+    /** Inactivity watchdog timeout (shared with the scout lane). */
+    inactivityTimeoutMs: number;
+    /** Whether the run's contract requires web evidence (telemetry seed). */
+    webRequired: boolean;
+    /** Optional quota event sink (same owner as the agent loop). */
+    quotaEventSink?: (harnessId: string, ev: HarnessEvent) => void;
+}
+export interface DeepScanReducerArgs {
+    taskId: string;
+    goal: string;
+    routed: RoutedAdapter;
+    scoutReports: {
+        attemptId: string;
+        harnessId: string;
+        absPath: string;
+    }[];
+    ledger: BudgetLedger;
+    log: EventLog;
+    paths: RunPaths;
+    signal?: AbortSignal;
+    onHarnessEvent?: (ev: HarnessEvent) => void;
+    attemptTelemetries: {
+        attemptId: string;
+        harnessId: string;
+        telemetry: AttemptTelemetry;
+    }[];
+}
+export type DeepScanReducerResult = {
+    status: "success";
+    report: string;
+} | {
+    status: "failed";
+    error: string;
+} | {
+    status: "budget_denied";
+    denial: BudgetDenial;
+} | {
+    status: "cancelled";
+};
+/**
+ * #27 / D-6: the deep-scan bounded synthesis reducer. After the scouts finish,
+ * ONE synthesize-intent attempt merges the raw scout reports into a real
+ * synthesis. It is READ-ONLY and file-backed (the scout report files are pointed
+ * at by absolute path — the argv-size law: reports ride a file, never argv),
+ * reserves a budget lease like any attempt, and is bounded by a hard timeout. Its
+ * telemetry is pushed to the run roster (cost/route visible). On
+ * failure/timeout/budget-denial the caller degrades to an HONEST raw bundle; this
+ * function never fabricates a synthesis.
+ */
+export declare function runDeepScanReducer(deps: DeepScanReducerDeps, args: DeepScanReducerArgs): Promise<DeepScanReducerResult>;
+/**
+ * #27 / D-6: decide the deep-scan synthesis outcome and, when warranted, run the
+ * bounded reducer. Returns the typed `DeepScanSynthesis` telemetry status plus
+ * the merged report (non-null only on a clean reducer success; the caller writes
+ * an honest raw bundle otherwise). A width-1 (single-report) scan skips the
+ * reducer; a budget-stopped/cancelled scan degrades without spending on a merge;
+ * a scan with no synthesize-capable route degrades honestly.
+ */
+export declare function resolveDeepScanSynthesis(deps: DeepScanReducerDeps, args: {
+    succeeded: {
+        attemptId: string;
+        harnessId: string;
+        report: string;
+        telemetry: AttemptTelemetry;
+    }[];
+    adapters: RoutedAdapter[];
+    budgetStopped: boolean;
+    aborted: boolean;
+    taskId: string;
+    goal: string;
+    findingsDir: string;
+    ledger: BudgetLedger;
+    log: EventLog;
+    paths: RunPaths;
+    signal?: AbortSignal;
+    onHarnessEvent?: (ev: HarnessEvent) => void;
+    attemptTelemetries: {
+        attemptId: string;
+        harnessId: string;
+        telemetry: AttemptTelemetry;
+    }[];
+}): Promise<{
+    deepScanSynthesis: DeepScanSynthesis;
+    reducedReport: string | null;
+}>;
+//# sourceMappingURL=deepScanReducer.d.ts.map

package/dist/deepScanReducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepScanReducer.d.ts","sourceRoot":"","sources":["../src/deepScanReducer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA8B,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGlF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,KAAK,YAAY,EAAyB,MAAM,oBAAoB,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EACL,KAAK,gBAAgB,EAMtB,MAAM,uBAAuB,CAAC;AAE/B,iFAAiF;AACjF,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,gBAAgB,CAAC;KAC7B,EAAE,CAAC;IACJ,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IAC/F,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAClC,GAAG,MAAM,CAmCT;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;gFAGgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,eAAe,EAAE,MAAM,WAAW,CAAC;IACnC,oFAAoF;IACpF,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,YAAY,CAAC;IACrE,6EAA6E;IAC7E,SAAS,EAAE,CACT,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,KACd;QACH,IAAI,EAAE,cAAc,CAAC;QACrB,SAAS,EAAE,qBAAqB,CAAC;QACjC,YAAY,EAAE,qBAAqB,CAAC;QACpC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB;;;0FAGkF;QAClF,cAAc,EAAE,sBAAsB,CAAC;KACxC,CAAC;IACF,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,WAAW,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;CAChE;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1E,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,kBAAkB,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAA;KAAE,EAAE,CAAC;CAC7F;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAIjD;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAE5B;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CA+LhC;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE;IACJ,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,gBAAgB,CAAC;KAC7B,EAAE,CAAC;IACJ,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,QAAQ,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,kBAAkB,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAA;KAAE,EAAE,CAAC;CAC7F,GACA,OAAO,CAAC;IAAE,iBAAiB,EAAE,iBAAiB,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA2FjF"}

package/dist/deepScanReducer.js

@@ -0,0 +1,348 @@
+import { join } from "node:path";
+import { attemptUsageCostSettlement } from "@claudexor/budget";
+import { AnswerAssembly, withInactivityWatchdog } from "@claudexor/core";
+import { appendLine, redactSecrets, safeInvoke } from "@claudexor/util";
+import { buildDeepScanReducerPrompt } from "@claudexor/synthesis";
+import { classifyBudgetFailure } from "./budgetFailure.js";
+import { finalizeAttempt, unwrapWorkReportEnvelope, } from "./attemptFinalize.js";
+import { redactHarnessEvent, harnessEventPayload, observeBudgetSignals, safeErrorMessage, } from "./runSupport.js";
+import { createAttemptTelemetry, observeAttemptTelemetry, setAttemptOutcome, telemetrySummary, toolWarnings, } from "./attemptTelemetry.js";
+/** The reducer runs under the fixed `synth` attempt id (roster/cost visible). */
+export const DEEP_SCAN_REDUCER_ATTEMPT_ID = "synth";
+/**
+ * #27 / D-6: the HONEST fallback artifact for a deep scan whose bounded
+ * synthesis reducer did not run or did not succeed. It is explicitly labeled a
+ * raw scout bundle (a marker heading), never presented as a merged synthesis:
+ * the per-scout reports are concatenated verbatim with attribution, the roster
+ * denominator stays honest, and omissions are preserved. `skipped` (a single
+ * width-1 report) and `failed` (reducer error/timeout/budget-denial or no
+ * synthesize-capable route) get distinct honest intros.
+ */
+export function rawScoutBundle(args) {
+    const total = args.succeeded.length + args.unsuccessful.length;
+    const intro = args.status?.status === "skipped"
+        ? [
+            "## Raw scout report (single scout — no merge needed)",
+            "",
+            "Only one scout produced a report, so no synthesis reducer was run.",
+        ]
+        : [
+            "## Raw scout bundle — NOT a merged synthesis",
+            "",
+            `The bounded synthesis reducer did not produce a merge (${args.status?.reason ?? "synthesis unavailable"}). The scout reports below are raw and unmerged; claims are not deduplicated and disagreements are not reconciled.`,
+        ];
+    return [
+        ...intro,
+        "",
+        `Explorers succeeded: ${args.succeeded.length}/${total}.`,
+        "",
+        "## Scout reports (raw, not merged)",
+        ...args.succeeded.map((a) => {
+            const warnings = toolWarnings(a.telemetry);
+            const warningText = warnings.length
+                ? `\n\n> Tool warnings: ${warnings.map((e) => `${e.tool}: ${e.summary}`).join("; ")}`
+                : "";
+            return `\n### ${a.attemptId} / ${a.harnessId}\n\n${a.report}${warningText}`;
+        }),
+        "",
+        "## Omissions / Uncertainty",
+        ...(args.unsuccessful.length
+            ? args.unsuccessful.map((a) => `- ${a.attemptId} / ${a.harnessId} ${a.status}: ${a.error}`)
+            : [
+                "- No explorer failures recorded. Claims still need evidence review before edit execution.",
+            ]),
+    ].join("\n");
+}
+/**
+ * #27 / D-6: the deep-scan bounded synthesis reducer. After the scouts finish,
+ * ONE synthesize-intent attempt merges the raw scout reports into a real
+ * synthesis. It is READ-ONLY and file-backed (the scout report files are pointed
+ * at by absolute path — the argv-size law: reports ride a file, never argv),
+ * reserves a budget lease like any attempt, and is bounded by a hard timeout. Its
+ * telemetry is pushed to the run roster (cost/route visible). On
+ * failure/timeout/budget-denial the caller degrades to an HONEST raw bundle; this
+ * function never fabricates a synthesis.
+ */
+export async function runDeepScanReducer(deps, args) {
+    const { ledger, log, paths } = args;
+    const attemptId = DEEP_SCAN_REDUCER_ATTEMPT_ID;
+    const adapter = args.routed.adapter;
+    log.emit("synthesis.started", {
+        synthesize: true,
+        reason: `deep-scan reducer over ${args.scoutReports.length} scout reports`,
+    });
+    const lease = ledger.reserve({
+        taskId: args.taskId,
+        attemptId,
+        intent: "synthesize",
+        harnessId: adapter.id,
+        cost: deps.costEvidence(adapter.id, attemptId),
+    });
+    if (!lease.granted) {
+        log.emit("budget.lease.created", {
+            granted: false,
+            reason: lease.reason,
+            denied: lease.denied,
+            attempt_id: attemptId,
+            harness_id: adapter.id,
+        });
+        return {
+            status: "budget_denied",
+            denial: {
+                code: lease.denied ?? "hard_cap",
+                reason: lease.reason ?? "budget lease denied",
+                harnessId: adapter.id,
+                attemptId,
+            },
+        };
+    }
+    // A fresh disposable read-only home: the scouts' shared route context was
+    // already disposed, and auth truth is home-independent (credentials come from
+    // the profile/keychain/default store), so a fresh home shares the auth source.
+    const reducerHome = deps.newReadOnlyHome();
+    const prompt = buildDeepScanReducerPrompt(args.goal, args.scoutReports);
+    const built = deps.buildSpec(args.routed, reducerHome.env, prompt, attemptId);
+    const spec = built.spec;
+    // Hard (total) timeout — one attempt, no failover/transient retry loop.
+    const reducerAbort = new AbortController();
+    let timedOut = false;
+    const hardTimer = setTimeout(() => {
+        timedOut = true;
+        reducerAbort.abort();
+        void adapter.cancel?.(spec.session_id)?.catch(() => { });
+    }, deps.hardTimeoutMs);
+    spec.extra["abortSignal"] = args.signal
+        ? AbortSignal.any([args.signal, reducerAbort.signal])
+        : reducerAbort.signal;
+    const telemetry = createAttemptTelemetry(built.webPolicy, deps.webRequired || built.webPolicy === "cached" || built.webPolicy === "live", built.effectiveWeb, [], built.model);
+    const answer = new AnswerAssembly();
+    const attemptEventsPath = join(paths.attemptsDir, attemptId, "events.jsonl");
+    const budgetSignalState = { quotaPressureDisclosed: false };
+    let cost = 0;
+    let costEstimated = false;
+    let harnessError = null;
+    log.emit("harness.started", {
+        harness_id: adapter.id,
+        attempt_id: attemptId,
+        external_context_policy: built.webPolicy,
+    });
+    try {
+        const watched = withInactivityWatchdog(adapter.run(spec), {
+            timeoutMs: deps.inactivityTimeoutMs,
+            onTimeout: () => {
+                reducerAbort.abort();
+                void adapter.cancel?.(spec.session_id)?.catch(() => { });
+            },
+            isSuspended: () => false,
+        });
+        for await (const ev of watched) {
+            if (reducerAbort.signal.aborted)
+                break;
+            const safeEv = redactHarnessEvent(ev);
+            safeInvoke(args.onHarnessEvent, safeEv);
+            log.emit("harness.event", harnessEventPayload(adapter.id, attemptId, safeEv));
+            appendLine(attemptEventsPath, JSON.stringify(safeEv));
+            observeAttemptTelemetry(telemetry, safeEv);
+            observeBudgetSignals(ledger, log, adapter.id, attemptId, safeEv, budgetSignalState);
+            deps.quotaEventSink?.(adapter.id, safeEv);
+            if (safeEv.type === "usage" && safeEv.usage?.cost_usd) {
+                cost += safeEv.usage.cost_usd;
+                if (safeEv.usage.estimated)
+                    costEstimated = true;
+                log.emit("budget.observation", {
+                    harness_id: adapter.id,
+                    attempt_id: attemptId,
+                    kind: "spend",
+                    usd: safeEv.usage.cost_usd,
+                    estimated: safeEv.usage.estimated === true,
+                });
+            }
+            answer.observe(safeEv);
+            if (safeEv.type === "error")
+                harnessError = safeEv.error ? redactSecrets(safeEv.error) : "harness emitted an error";
+        }
+    }
+    catch (err) {
+        harnessError = safeErrorMessage(err);
+    }
+    finally {
+        clearTimeout(hardTimer);
+        reducerHome.dispose();
+        ledger.settle(lease.lease?.lease_id ?? "", attemptUsageCostSettlement(cost, costEstimated, attemptId, adapter.id, telemetry.authMode, telemetry.usageCost));
+    }
+    // D-16: unwrap the WorkReport envelope and finalize through the SAME contract as
+    // every other attempt — a capable reducer route that broke its WorkReport
+    // contract (or reported needs_input/incomplete/context-exhausted) must NEVER be
+    // accepted as a clean synthesis; the caller then degrades to an honest raw
+    // bundle. On an inactive-transport route the unwrap passes the report through
+    // untouched (unchanged behavior for schema-free reducer harnesses).
+    const unwrapped = unwrapWorkReportEnvelope(answer.machineText() ?? "", built.workReportMode, {
+        sideToolReport: telemetry.sideToolWorkReport ?? undefined,
+    });
+    const report = redactSecrets(unwrapped.deliverable);
+    const finalized = finalizeAttempt({
+        deliverableEvidence: report.trim().length > 0,
+        harnessErrored: harnessError !== null,
+        workReport: unwrapped.workReport,
+        workReportSource: unwrapped.source,
+        workReportViolation: unwrapped.contractViolation,
+        contextTerminalExhausted: telemetry.contextExhausted,
+    });
+    if (timedOut && !harnessError)
+        harnessError = `deep-scan reducer timed out after ${deps.hardTimeoutMs}ms`;
+    // A reducer must produce a CLEAN merged synthesis: a broken WorkReport contract,
+    // a needs_input/incomplete attestation, or a terminal context exhaustion is a
+    // typed reducer failure (degrade to the raw bundle), never a laundered success.
+    if (!harnessError && finalized.outcomeClass === "contract_failure") {
+        harnessError = `deep-scan reducer work_report contract: ${unwrapped.contractViolation}`;
+    }
+    else if (!harnessError && finalized.outcomeClass === "veto") {
+        harnessError = `deep-scan reducer reported ${finalized.workState.state} instead of a merged synthesis`;
+    }
+    else if (!harnessError && finalized.outcomeClass === "interrupted") {
+        harnessError = "deep-scan reducer ran out of context before completing the synthesis";
+    }
+    const reportPresent = finalized.deliverablePresent && report.trim().length > 0;
+    if (!harnessError && !reportPresent)
+        harnessError = "deep-scan reducer produced no synthesis";
+    // INV-116: a cancel on the OUTER run signal that landed WHILE this bounded
+    // reducer streamed is a cancellation — not a clean synthesis and not a typed
+    // failure. Any partial output is discarded (deliverablePresent forced false)
+    // so it can never be accepted as a merge, and the run terminalizes cancelled.
+    const runCancelled = args.signal?.aborted === true;
+    setAttemptOutcome(telemetry, {
+        deliverablePresent: reportPresent && !runCancelled,
+        gatesPassed: null,
+        harnessErrored: harnessError !== null || runCancelled,
+        webRequiredUnsatisfied: false,
+        workState: finalized.workState,
+    });
+    // Roster/cost visible: the reducer is a normal attempt in run telemetry.
+    args.attemptTelemetries.push({ attemptId, harnessId: adapter.id, telemetry });
+    if (runCancelled) {
+        log.emit("harness.completed", {
+            harness_id: adapter.id,
+            attempt_id: attemptId,
+            status: "cancelled",
+            ...telemetrySummary(telemetry),
+        });
+        return { status: "cancelled" };
+    }
+    if (harnessError) {
+        log.emit("harness.completed", {
+            harness_id: adapter.id,
+            attempt_id: attemptId,
+            status: "failed",
+            error: harnessError,
+            ...telemetrySummary(telemetry),
+        });
+        return { status: "failed", error: harnessError };
+    }
+    log.emit("harness.completed", {
+        harness_id: adapter.id,
+        attempt_id: attemptId,
+        status: "success",
+        ...telemetrySummary(telemetry),
+    });
+    return { status: "success", report };
+}
+/**
+ * #27 / D-6: decide the deep-scan synthesis outcome and, when warranted, run the
+ * bounded reducer. Returns the typed `DeepScanSynthesis` telemetry status plus
+ * the merged report (non-null only on a clean reducer success; the caller writes
+ * an honest raw bundle otherwise). A width-1 (single-report) scan skips the
+ * reducer; a budget-stopped/cancelled scan degrades without spending on a merge;
+ * a scan with no synthesize-capable route degrades honestly.
+ */
+export async function resolveDeepScanSynthesis(deps, args) {
+    if (args.succeeded.length < 2) {
+        return {
+            deepScanSynthesis: {
+                status: "skipped",
+                reducer_attempt_id: null,
+                reason: "single scout report needs no merge",
+            },
+            reducedReport: null,
+        };
+    }
+    if (args.budgetStopped || args.aborted) {
+        return {
+            deepScanSynthesis: {
+                status: "failed",
+                reducer_attempt_id: null,
+                reason: args.aborted
+                    ? "run cancelled before synthesis"
+                    : "budget exhausted before synthesis",
+            },
+            reducedReport: null,
+        };
+    }
+    // Eligible route: a successful scout whose harness manifest supports the
+    // synthesize intent. Deep-scan repeats a surviving harness, so any routed slot
+    // for that harness id is a valid reducer route.
+    const eligible = args.succeeded
+        .map((s) => args.adapters.find((a) => a.adapter.id === s.harnessId && a.supportsSynthesize))
+        .find((a) => Boolean(a));
+    if (!eligible) {
+        return {
+            deepScanSynthesis: {
+                status: "failed",
+                reducer_attempt_id: null,
+                reason: "no synthesize-capable route among the scout harnesses",
+            },
+            reducedReport: null,
+        };
+    }
+    const reduced = await runDeepScanReducer(deps, {
+        taskId: args.taskId,
+        goal: args.goal,
+        routed: eligible,
+        scoutReports: args.succeeded.map((s) => ({
+            attemptId: s.attemptId,
+            harnessId: s.harnessId,
+            absPath: join(args.findingsDir, `${s.attemptId}.md`),
+        })),
+        ledger: args.ledger,
+        log: args.log,
+        paths: args.paths,
+        signal: args.signal,
+        onHarnessEvent: args.onHarnessEvent,
+        attemptTelemetries: args.attemptTelemetries,
+    });
+    if (reduced.status === "success") {
+        return {
+            deepScanSynthesis: {
+                status: "succeeded",
+                reducer_attempt_id: DEEP_SCAN_REDUCER_ATTEMPT_ID,
+                reason: null,
+            },
+            reducedReport: reduced.report,
+        };
+    }
+    // INV-116: a mid-reducer cancellation degrades with NO merged report (the
+    // partial output is discarded). The schema status has no `cancelled` member,
+    // so it is disclosed as a failed synthesis whose reason names the cancel; the
+    // run's own terminal is routed to `cancelled` by the caller's re-check.
+    if (reduced.status === "cancelled") {
+        return {
+            deepScanSynthesis: {
+                status: "failed",
+                reducer_attempt_id: DEEP_SCAN_REDUCER_ATTEMPT_ID,
+                reason: "run cancelled during synthesis",
+            },
+            reducedReport: null,
+        };
+    }
+    const reason = reduced.status === "budget_denied"
+        ? `reducer budget-denied: ${classifyBudgetFailure({ denial: reduced.denial, terminal: args.ledger.terminal() }).safeMessage}`
+        : reduced.error;
+    return {
+        deepScanSynthesis: {
+            status: "failed",
+            reducer_attempt_id: DEEP_SCAN_REDUCER_ATTEMPT_ID,
+            reason,
+        },
+        reducedReport: null,
+    };
+}
+//# sourceMappingURL=deepScanReducer.js.map

package/dist/deepScanReducer.js.map

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

package/dist/effortGovernance.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Run-preflight effort gate (INV-105), the effort analog of `modelGovernance`.
+ *
+ * This gate DISCLOSES, it does not clamp. It answers exactly one question:
+ * does the harness's merged advertised ladder (`capabilities.effort_levels`,
+ * the positional merge of its models' vendor-ordered lists) know this level at
+ * all? A level the merged ladder has never seen is disclosed as ignored — the
+ * adapter would otherwise just omit the flag and the user would never learn
+ * their level went nowhere. A level the ladder DOES know rides through
+ * VERBATIM and is resolved by the adapter.
+ *
+ * Why the clamp lives downstream and not here: the manifest is discovered
+ * ONCE, against the DEFAULT native harness home (`discover()` takes no
+ * arguments), so its ladders describe the DEFAULT account's catalog. Codex
+ * advertises its ladders per ACCOUNT — every credential profile and API-key
+ * route gets its own `CODEX_HOME`, and `model/list` answers for whoever that
+ * home is logged into. Clamping here would therefore hold a profile-scoped run
+ * to another account's ceiling. The adapter re-resolves against the catalog
+ * for the env the child will ACTUALLY run in (`codexEffortsForEnv`), so it is
+ * the only layer entitled to clamp — and clamping is only ever a move INSIDE
+ * the vendor's own order, which only the adapter's resolved catalog carries.
+ *
+ * The membership test runs against the harness-wide merged ladder rather than
+ * the per-model narrowing, because the ladder is the broadest and least
+ * account-specific signal the manifest carries: a level any of the harness's
+ * models advertises is in it, so this gate cannot reject a level merely
+ * because the routed model's copy happens not to list it.
+ */
+import type { EffortHint } from "@claudexor/schema";
+export interface EffortGovernedRoute {
+    id: string;
+    /** Harness-wide merged advertised ladder; empty = effort is not a tunable surface. */
+    effortLevels: readonly EffortHint[];
+}
+/**
+ * The effort this route should FORWARD, plus any disclosure text.
+ * `effort: null` means "send no flag" — either nothing was asked for, or what
+ * was asked for could not be honored anywhere and is disclosed instead.
+ *
+ * A returned level is the RAW request, deliberately un-clamped: it is the
+ * adapter's `effort_hint`, and every adapter that consumes it resolves through
+ * the shared normalizer against its own profile-resolved advertised set
+ * (`normalizeEffort` in harness-claude, `codexEffortFor` in harness-codex).
+ */
+export declare function governRouteEffort(requested: EffortHint | null, route: EffortGovernedRoute): {
+    effort: EffortHint | null;
+    ignored: string | null;
+};
+//# sourceMappingURL=effortGovernance.d.ts.map

package/dist/effortGovernance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortGovernance.d.ts","sourceRoot":"","sources":["../src/effortGovernance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,GAAG,IAAI,EAC5B,KAAK,EAAE,mBAAmB,GACzB;IAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAuBvD"}

package/dist/effortGovernance.js

@@ -0,0 +1,35 @@
+/**
+ * The effort this route should FORWARD, plus any disclosure text.
+ * `effort: null` means "send no flag" — either nothing was asked for, or what
+ * was asked for could not be honored anywhere and is disclosed instead.
+ *
+ * A returned level is the RAW request, deliberately un-clamped: it is the
+ * adapter's `effort_hint`, and every adapter that consumes it resolves through
+ * the shared normalizer against its own profile-resolved advertised set
+ * (`normalizeEffort` in harness-claude, `codexEffortFor` in harness-codex).
+ */
+export function governRouteEffort(requested, route) {
+    if (!requested)
+        return { effort: null, ignored: null };
+    if (route.effortLevels.length === 0) {
+        return {
+            effort: null,
+            ignored: `effort=${requested} (manifest capabilities.effort_levels is empty for ${route.id})`,
+        };
+    }
+    // Pure membership against the merged vendor ladder: with no static rank
+    // table there is nothing else for this layer to rank against, which is the
+    // point — a level the harness's own advertised order has never seen is one
+    // no honest "nearest" could be invented for, so it is disclosed instead of
+    // vanishing. Anything the ladder knows is forwardable; WHERE it lands on the
+    // routed model is the adapter's call.
+    if (!route.effortLevels.includes(requested)) {
+        return {
+            effort: null,
+            ignored: `effort=${requested} (not on the advertised ladder of ${route.id}: ` +
+                `${route.effortLevels.join(", ")})`,
+        };
+    }
+    return { effort: requested, ignored: null };
+}
+//# sourceMappingURL=effortGovernance.js.map

package/dist/effortGovernance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effortGovernance.js","sourceRoot":"","sources":["../src/effortGovernance.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA4B,EAC5B,KAA0B;IAE1B,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,UAAU,SAAS,sDAAsD,KAAK,CAAC,EAAE,GAAG;SAC9F,CAAC;IACJ,CAAC;IACD,wEAAwE;IACxE,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,sCAAsC;IACtC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5C,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EACL,UAAU,SAAS,qCAAqC,KAAK,CAAC,EAAE,IAAI;gBACpE,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SACtC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/dist/harnessFailure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Harness-error remediation (GH #31), the transient-taxonomy sibling of the
+ * QA-050 budget classifier (budgetFailure.ts). A terminal harness error used to
+ * emit "Check harness authentication" unconditionally — doomed guidance when the
+ * cause was a timeout, a rate limit, or a process crash. This module maps the
+ * classified failure category onto the right required-actions: authentication
+ * guidance appears ONLY on `auth_failed`, exactly as budget guidance appears
+ * only on a real budget refusal.
+ */
+import type { HarnessFailureCategory } from "@claudexor/schema";
+import type { TransientFailureObservation } from "./transientClassify.js";
+/**
+ * The category that best explains a terminal harness failure across a run's
+ * attempt telemetries. `auth_failed` and `capability_refused` are deterministic
+ * refusals that dominate (retrying never clears them, so they are the true
+ * cause even when a later transient also fired); otherwise the most recent
+ * classified failure wins. Null when no transient failure was classified.
+ */
+export declare function dominantHarnessFailureCategory(transientFailures: TransientFailureObservation[]): HarnessFailureCategory | null;
+/**
+ * Required-actions for a terminal harness failure, keyed off the classified
+ * category. Authentication guidance appears ONLY on `auth_failed`; every other
+ * category gets remediation that fits its actual cause. A null category (no
+ * classified transient) keeps the neutral diagnostics/retry guidance.
+ */
+export declare function harnessFailureNextActions(category: HarnessFailureCategory | null): string[];
+//# sourceMappingURL=harnessFailure.d.ts.map

package/dist/harnessFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harnessFailure.d.ts","sourceRoot":"","sources":["../src/harnessFailure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,iBAAiB,EAAE,2BAA2B,EAAE,GAC/C,sBAAsB,GAAG,IAAI,CAO/B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI,GAAG,MAAM,EAAE,CAsC3F"}