clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/delegate-signature.js

@@ -0,0 +1,14 @@
+/**
+ * The context-builder delegate signature for "the finalizer reported external
+ * evidence gaps under external_gap_policy:degrade": status "partial" WITHOUT
+ * fallback. No other path produces that pair (fallback always sets
+ * fallback_used:true; a clean run is "succeeded"), so it is the single shared
+ * definition for engine context_quality, run health, and receipt status.
+ *
+ * Deliberately narrower than workflow-runner's cache predicate
+ * (isDelegateDegradedForCache), which also refuses fallback bundles.
+ */
+export function isDelegateExternalGapDegrade(delegate) {
+    return delegate?.status === "partial" && delegate.fallback_used === false;
+}
+//# sourceMappingURL=delegate-signature.js.map

package/clinkx-workflows/dist/delegate-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-signature.js","sourceRoot":"","sources":["../src/delegate-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAoF;IAEpF,OAAO,QAAQ,EAAE,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,aAAa,KAAK,KAAK,CAAC;AAC5E,CAAC"}

package/clinkx-workflows/dist/delegate-validate.d.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import type { PreflightContextDelegateInput } from "./context-preflight.js";
+export declare const WorkflowDelegateSchema: z.ZodDefault<z.ZodUnion<[z.ZodObject<{
+    enabled: z.ZodLiteral<true>;
+    curator: z.ZodObject<{
+        cli_name: z.ZodString;
+        role: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+    }, {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+    }>;
+    finalizer: z.ZodObject<{
+        cli_name: z.ZodString;
+        role: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+    } & {
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        min_score: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        cli_name: string;
+        role: string;
+        min_score: number;
+        model?: string | undefined;
+        effort?: string | undefined;
+        enabled?: boolean | undefined;
+    }, {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+        enabled?: boolean | undefined;
+        min_score?: number | undefined;
+    }>;
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+    max_response_chars: z.ZodOptional<z.ZodNumber>;
+    failure_policy: z.ZodOptional<z.ZodEnum<["fallback", "fail"]>>;
+    external_gap_policy: z.ZodOptional<z.ZodEnum<["fail", "degrade"]>>;
+}, "strict", z.ZodTypeAny, {
+    curator: {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+    };
+    finalizer: {
+        cli_name: string;
+        role: string;
+        min_score: number;
+        model?: string | undefined;
+        effort?: string | undefined;
+        enabled?: boolean | undefined;
+    };
+    enabled: true;
+    timeout_seconds?: number | undefined;
+    max_response_chars?: number | undefined;
+    failure_policy?: "fail" | "fallback" | undefined;
+    external_gap_policy?: "fail" | "degrade" | undefined;
+}, {
+    curator: {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+    };
+    finalizer: {
+        cli_name: string;
+        role: string;
+        model?: string | undefined;
+        effort?: string | undefined;
+        enabled?: boolean | undefined;
+        min_score?: number | undefined;
+    };
+    enabled: true;
+    timeout_seconds?: number | undefined;
+    max_response_chars?: number | undefined;
+    failure_policy?: "fail" | "fallback" | undefined;
+    external_gap_policy?: "fail" | "degrade" | undefined;
+}>, z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodLiteral<false>>;
+}, "strict", z.ZodTypeAny, {
+    enabled: false;
+}, {
+    enabled?: false | undefined;
+}>]>>;
+export type WorkflowDelegateInput = z.infer<typeof WorkflowDelegateSchema>;
+export declare class WorkflowDelegateValidationError extends Error {
+    constructor(message: string);
+}
+export declare function parseWorkflowDelegateInput(value: unknown): WorkflowDelegateInput;
+/**
+ * Whether a raw (pre-parse) `cb_delegate` value — a JSON string or an object —
+ * carries an explicit `finalizer.min_score`. Parsing defaults `min_score`, so
+ * explicitness is only observable here. Any unparseable or unexpected shape is
+ * not explicit; `parseWorkflowDelegateInput` owns reporting it.
+ */
+export declare function delegateFinalizerMinScoreExplicit(raw: unknown): boolean;
+export declare function isWorkflowDelegateAbsent(value: unknown): boolean;
+export declare function asPreflightDelegateInput(delegate: WorkflowDelegateInput): PreflightContextDelegateInput;

package/clinkx-workflows/dist/delegate-validate.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+const DELEGATE_DEFAULT_FINALIZER_MIN_SCORE = 8.5;
+const DELEGATE_MAX_TIMEOUT_SECONDS = 600;
+const DELEGATE_MAX_RESPONSE_CHARS = 200_000;
+const NonBlankStringSchema = z.string().trim().min(1);
+// Keep in sync with schema.ts model regex and MODEL_OVERRIDE_PATTERN (workflow-tools.ts).
+const ModelSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[^\s\u0000-][^\s\u0000]*$/);
+// Keep in sync with schema.ts effort regex and EFFORT_OVERRIDE_PATTERN (workflow-tools.ts).
+const EffortSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(32)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/);
+const DelegateProviderConfigSchema = z
+    .object({
+    cli_name: NonBlankStringSchema,
+    role: NonBlankStringSchema,
+    model: ModelSchema.optional(),
+    effort: EffortSchema.optional(),
+})
+    .strict();
+const DelegateFinalizerConfigSchema = DelegateProviderConfigSchema.extend({
+    enabled: z.boolean().optional(),
+    min_score: z
+        .number()
+        .min(0)
+        .max(10)
+        .default(DELEGATE_DEFAULT_FINALIZER_MIN_SCORE),
+}).strict();
+const DisabledDelegateSchema = z
+    .object({
+    enabled: z.literal(false).default(false),
+})
+    .strict();
+const EnabledDelegateSchema = z
+    .object({
+    enabled: z.literal(true),
+    curator: DelegateProviderConfigSchema,
+    finalizer: DelegateFinalizerConfigSchema,
+    timeout_seconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(DELEGATE_MAX_TIMEOUT_SECONDS)
+        .optional(),
+    max_response_chars: z
+        .number()
+        .int()
+        .positive()
+        .max(DELEGATE_MAX_RESPONSE_CHARS)
+        .optional(),
+    failure_policy: z.enum(["fallback", "fail"]).optional(),
+    external_gap_policy: z.enum(["fail", "degrade"]).optional(),
+})
+    .strict();
+export const WorkflowDelegateSchema = z
+    .union([EnabledDelegateSchema, DisabledDelegateSchema])
+    .default({ enabled: false });
+export class WorkflowDelegateValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowDelegateValidationError";
+    }
+}
+export function parseWorkflowDelegateInput(value) {
+    const parsedJson = parseDelegateJsonIfNeeded(value);
+    const result = WorkflowDelegateSchema.safeParse(parsedJson);
+    if (!result.success) {
+        throw new WorkflowDelegateValidationError(`Invalid cb_delegate: ${result.error.issues.map((issue) => issue.message).join("; ")}`);
+    }
+    return result.data;
+}
+/**
+ * Whether a raw (pre-parse) `cb_delegate` value — a JSON string or an object —
+ * carries an explicit `finalizer.min_score`. Parsing defaults `min_score`, so
+ * explicitness is only observable here. Any unparseable or unexpected shape is
+ * not explicit; `parseWorkflowDelegateInput` owns reporting it.
+ */
+export function delegateFinalizerMinScoreExplicit(raw) {
+    let value = raw;
+    if (typeof raw === "string") {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            return false;
+        }
+    }
+    const finalizer = ownPlainProperty(value, "finalizer");
+    return ownPlainProperty(finalizer, "min_score") !== undefined;
+}
+function ownPlainProperty(value, key) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return Object.hasOwn(value, key)
+        ? value[key]
+        : undefined;
+}
+export function isWorkflowDelegateAbsent(value) {
+    return value == null || (typeof value === "string" && value.trim() === "");
+}
+function parseDelegateJsonIfNeeded(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new WorkflowDelegateValidationError(`cb_delegate must be a valid JSON string: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function asPreflightDelegateInput(delegate) {
+    if (delegate.enabled !== true) {
+        return { enabled: false };
+    }
+    return {
+        enabled: true,
+        curator: {
+            cli_name: delegate.curator.cli_name,
+            role: delegate.curator.role,
+            ...(delegate.curator.model === undefined ? {} : { model: delegate.curator.model }),
+            ...(delegate.curator.effort === undefined ? {} : { effort: delegate.curator.effort }),
+        },
+        finalizer: {
+            cli_name: delegate.finalizer.cli_name,
+            role: delegate.finalizer.role,
+            ...(delegate.finalizer.enabled === undefined ? {} : { enabled: delegate.finalizer.enabled }),
+            min_score: delegate.finalizer.min_score,
+            ...(delegate.finalizer.model === undefined ? {} : { model: delegate.finalizer.model }),
+            ...(delegate.finalizer.effort === undefined ? {} : { effort: delegate.finalizer.effort }),
+        },
+        ...(delegate.timeout_seconds === undefined ? {} : { timeout_seconds: delegate.timeout_seconds }),
+        ...(delegate.max_response_chars === undefined ? {} : { max_response_chars: delegate.max_response_chars }),
+        ...(delegate.failure_policy === undefined ? {} : { failure_policy: delegate.failure_policy }),
+        ...(delegate.external_gap_policy === undefined
+            ? {}
+            : { external_gap_policy: delegate.external_gap_policy }),
+    };
+}
+//# sourceMappingURL=delegate-validate.js.map

package/clinkx-workflows/dist/delegate-validate.js.map

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

package/clinkx-workflows/dist/engine.d.ts

@@ -63,12 +63,29 @@
  * workflow engine treats as a transient failure eligible for retry.
  */
 import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+import type { PlanReviewCallBinding } from "./plan-review/run-state.js";
+import { type CouncilPlanReviewError } from "./plan-review/publication.js";
 import { type ChildFailureMetadata } from "./errors.js";
 import { type FidelityReport } from "./fidelity.js";
 import type { CallState, FailureClass, RunStatus } from "./state-schema.js";
+import type { InvocationAuditWrite, ObservedInvocationV1 } from "./dashboard/invocation-contract.js";
 import type { ClinkBackend } from "./backend.js";
 import type { ValidatorRegistry } from "./validators/index.js";
 import { type ArtifactRecord } from "./artifacts.js";
+import type { PlanReviewContextPolicy, PlanReviewContextProvenance } from "./plan-review/run-state.js";
+import type { ContextBuilderMetricsShape, ContextBuilderRunner, LightCallerProvenance, PreflightContextResult, WorkflowContext } from "./context-preflight.js";
+import { type WorkflowContextPolicy, type WorkflowContextRequestedMode, type WorkflowContextEffectiveMode } from "./context-mode-resolver.js";
+/**
+ * Maps a runner's {@link PreflightContextResult} to the persisted {@link WorkflowContext}.
+ * Single source of truth for this mapping: the transient `receipt` field is dropped, and
+ * optional `delegate` metadata is spread only when present.
+ */
+export declare function mapPreflightResultToWorkflowContext(result: PreflightContextResult, contextMode?: WorkflowContextEffectiveMode | undefined, lightCaller?: LightCallerProvenance | undefined): WorkflowContext;
+export type PreflightPartialClassification = {
+    readonly severity: "benign" | "degraded";
+    readonly partial_reason: "omissions_only" | "cap_or_truncation";
+};
+export declare function classifyPreflightPartial(metrics: ContextBuilderMetricsShape): PreflightPartialClassification;
 export interface ExecutedCall {
     readonly stageId: string;
     readonly callId: string;
@@ -96,7 +113,9 @@ export interface EngineResumeState {
         readonly stageId: string;
         readonly callId: string;
         readonly error: string;
+        readonly terminal: boolean;
     }> | undefined;
+    readonly nextRetryCounts?: ReadonlyMap<string, number> | undefined;
 }
 type HookResult = Promise<void> | void;
 export interface EngineRunStateChange {
@@ -107,6 +126,7 @@ export interface EngineRunStateChange {
     readonly completedAt?: string | undefined;
     readonly error?: string | undefined;
     readonly failureClass?: FailureClass | undefined;
+    readonly planReviewError?: CouncilPlanReviewError | undefined;
 }
 export interface EngineCallPreparedEvent {
     readonly runId: string;
@@ -117,6 +137,8 @@ export interface EngineCallPreparedEvent {
     readonly retryCount: number;
     readonly contextProducing: boolean;
     readonly input: Readonly<Record<string, unknown>>;
+    /** Root-injected model/effort audit. Omitted when no derive hook is wired. */
+    readonly invocation?: InvocationAuditWrite | undefined;
 }
 export interface EngineCallStateChange {
     readonly runId: string;
@@ -135,6 +157,14 @@ export interface EngineCallStateChange {
     readonly fidelity?: FidelityReport | undefined;
     readonly artifact?: ArtifactRecord | undefined;
     readonly childDebugMetadata?: ChildFailureMetadata | undefined;
+    /**
+     * Runtime-observed model/effort knobs from the child `_debug` block.
+     * Attached only on the terminal succeeded emit today: the failed path
+     * carries childDebugMetadata, whose ChildFailureMetadata shape has no
+     * observed_invocation field, so failed events omit it. Never attached on
+     * running events or intermediate retry failures. Telemetry-only.
+     */
+    readonly observedInvocation?: ObservedInvocationV1 | undefined;
 }
 export interface EngineRetryEvent {
     readonly runId: string;
@@ -167,12 +197,20 @@ export interface EngineHooks {
     readonly onRetryScheduled?: ((event: EngineRetryEvent) => HookResult) | undefined;
     readonly onProgress?: ((event: EngineProgressEvent) => HookResult) | undefined;
 }
+export type EngineTerminalResultPolicy = {
+    readonly kind: "final_call";
+} | {
+    readonly kind: "plan_review_artifacts";
+    readonly project: () => Promise<string>;
+};
 export interface WorkflowEngineOptions {
     readonly definition: NormalizedWorkflowDefinition;
     readonly session: ClinkBackend;
     readonly variables: Readonly<Record<string, unknown>>;
     readonly validatorRegistry: ValidatorRegistry;
     readonly runId: string;
+    /** Portable generation used only for session-log journal ownership. */
+    readonly sessionLogGeneration?: string | undefined;
     readonly runDir: string;
     readonly signal?: AbortSignal | undefined;
     readonly maxParallel?: number | undefined;
@@ -182,13 +220,66 @@ export interface WorkflowEngineOptions {
     readonly allowedRoots?: readonly string[] | undefined;
     readonly hooks?: EngineHooks | undefined;
     readonly resume?: EngineResumeState | undefined;
+    readonly contextBuilderRunner?: ContextBuilderRunner | undefined;
+    readonly contextDefault?: WorkflowContextRequestedMode | undefined;
+    readonly defaultCurator?: string | undefined;
+    readonly commitPreflightContext?: ((input: {
+        readonly variables: Readonly<Record<string, unknown>>;
+        readonly workflow_context: WorkflowContext;
+    }) => Promise<void>) | undefined;
+    /** Persisted workflow_context is the sole resume proof that preflight committed. */
+    readonly restoredWorkflowContext?: WorkflowContext | undefined;
+    /** Fail closed when resumed context is absent and an enabled mode has no runner. */
+    readonly requireContextPreflight?: boolean | undefined;
+    /** Admission-time policy replayed unchanged across execution and resume. */
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
+    /**
+     * Non-overridable plan-review context policy (A-7). Present only for
+     * `plan-review-receipts` runs. When set, the enforced exclusions are folded
+     * into the curator's input BEFORE dispatch and the finalized selection is
+     * post-filtered — the caller cannot re-admit the plan via globs or focus.
+     */
+    readonly planReviewContextPolicy?: PlanReviewContextPolicy | undefined;
+    /** Verified call bindings persisted by plan-review admission and resume. */
+    readonly planReviewCallBindings?: readonly PlanReviewCallBinding[] | undefined;
+    /**
+     * Canonical text of the verified plan snapshot (A-6/D9). Set on resume, where
+     * a persisted prepared retry replays its prompt verbatim and `buildCallInput`
+     * never re-runs the expander — this is what that prompt is checked against.
+     * Omitting it while a bound call has a persisted prepared input fails closed.
+     */
+    readonly planReviewSnapshotText?: string | undefined;
+    /** Records that the policy was enforced, for resume replay (A-7). */
+    readonly commitPlanReviewContextProvenance?: ((provenance: PlanReviewContextProvenance) => Promise<void>) | undefined;
+    /** Narrow opt-in terminal projection. All existing workflows use final_call. */
+    readonly terminalResultPolicy?: EngineTerminalResultPolicy | undefined;
+    /**
+     * Optional root-injected model/effort provenance audit. The engine has no
+     * adapter registry and cannot derive `adapter_pin` itself. Standalone
+     * servers omit this; prepared events then carry no `invocation`.
+     */
+    readonly deriveInvocationAudit?: (cliName: string, role: string, knobs: {
+        model?: string;
+        effort?: string;
+    }) => InvocationAuditWrite;
 }
+/**
+ * The allowed roots a workflow engine derives for itself when the caller supplies
+ * none. Exported so admission-time path checks can validate against the SAME set
+ * the engine will enforce at dispatch, rather than re-deriving a near-copy.
+ *
+ * Note this set is engine-owned: `CLINKX_ALLOWED_ROOTS` is not consulted and
+ * cannot widen it.
+ */
+export declare function defaultWorkflowAllowedRoots(runDir: string): readonly string[];
 export declare class WorkflowEngine {
     private readonly definition;
     private readonly session;
     private readonly variables;
+    private effectiveVariables;
     private readonly validatorRegistry;
     private readonly runId;
+    private readonly sessionLogGeneration;
     private readonly runDir;
     private readonly signal;
     private readonly queueDepth;
@@ -199,22 +290,182 @@ export declare class WorkflowEngine {
     private readonly resumeCompletedCalls;
     private readonly resumePreparedInputs;
     private readonly resumeFailedCalls;
+    private readonly resumeNextRetryCounts;
     private readonly contextProducingCalls;
+    private readonly planReviewDeliveredAliases;
     private readonly artifactStore;
+    private readonly contextBuilderRunner;
+    private readonly contextDefault;
+    private readonly defaultCurator;
+    private readonly commitPreflightContext;
+    private readonly restoredWorkflowContext;
+    private readonly requireContextPreflight;
+    private readonly initialContextPolicy;
+    private readonly planReviewContextPolicy;
+    private readonly planReviewCallBindings;
+    private readonly commitPlanReviewContextProvenance;
+    private readonly terminalResultPolicy;
+    private readonly deriveInvocationAudit;
+    /**
+     * Workflow budget expiry on the MONOTONIC clock (`monotonicNowMs()`), not on
+     * the wall clock. Never compare it to `Date.now()`; read it only through
+     * `workflowRemainingMs()`.
+     */
+    private workflowDeadlineAtMonoMs;
+    /**
+     * `stage.id`.`call.id` keys already written to a terminal state by
+     * `emitTerminalCallAbort`. A parallel stage still surfaces that throw through
+     * `materializeUnexpectedFailure`, whose emit carries no startedAt/durationMs
+     * and attempt 1 / retryCount 0 — persisted unconditionally, it would erase the
+     * terminal entry's timing. Bounded by the run's call count.
+     */
+    private readonly terminalizedCallKeys;
     constructor(options: WorkflowEngineOptions);
     execute(): Promise<WorkflowExecutionResult>;
+    /**
+     * Resume-path entry point. `execute()` is never called on the resume preflight
+     * engine, so without this the deadline is never installed and the
+     * curator/finalizer delegate runs unbounded. Installs the SAME fresh full
+     * `timeout_seconds` budget a resumed run gets (D1), runs preflight under it,
+     * and always tears it down.
+     */
+    prepareContextPreflightWithDeadline(): Promise<void>;
+    /**
+     * Complete the workflow context gate without dispatching a provider call.
+     * Resume uses this before backend construction when workflow_context is absent.
+     */
+    prepareContextPreflight(signal: AbortSignal): Promise<void>;
+    private resolveTerminalResult;
     private executeParallelStage;
     private executeSequentialStage;
     private executeSingleCall;
+    /**
+     * Terminalize a call that is about to be abandoned by a throw rather than
+     * by the retry loop's own failure path.
+     *
+     * Both abort/deadline exits from executeSingleCall leave the loop OUTSIDE
+     * the attempt `try`, so without this the persisted entry is stranded as
+     * "running" with no completedAt — a durable lie that resume, the dashboard
+     * and run health all read. The caller still rethrows: this only records the
+     * outcome, it never swallows it.
+     */
+    private emitTerminalCallAbort;
+    /**
+     * F4: bounded corrective suffix for the next already-scheduled retry after
+     * a JSON/schema-shaped failure. Returns undefined (no suffix) unless ALL of:
+     * - the call declares a JSON contract (mirrors the expect_json derivation
+     *   in buildCallInput);
+     * - the run is NOT typed plan review (identity: the plan-review-receipts
+     *   workflow name on the
+     *   normalized definition, plus the plan-review runtime signals as
+     *   defense-in-depth — plan-review dispatch bytes are pinned);
+     * - the failure is JSON/schema-shaped (SchemaValidationError,
+     *   OutputSizeError as the second correctable class, or a child
+     *   invalid_json_output rejection);
+     * - appending stays inside the same prompt-budget ceiling the dispatch-time
+     *   gate enforces (best-effort re-estimate; skip with a warn on overflow or
+     *   estimator failure — never a new failure mode).
+     * The suffix is always derived from the ORIGINAL prompt, so it can never
+     * stack across attempts, and it is never persisted to state.
+     */
+    /**
+     * Typed plan review (identity: the plan-review-receipts workflow name, plus
+     * the plan-review runtime signals as defense-in-depth). Its dispatch bytes
+     * and retry behavior are pinned, so no corrective machinery may touch it.
+     */
+    private isTypedPlanReviewCall;
+    /**
+     * D7: under retry.mode "transport_only" a malformed-JSON answer is a
+     * permanent failure, so it would never be retried. A JSON-contract call gets
+     * ONE corrective attempt when the failure is primarily JSON-shaped; a
+     * secondary-only invalid_json_output reason never creates eligibility.
+     * failureClass is not reclassified.
+     */
+    private isCorrectiveRetryEligible;
+    private buildCorrectiveRetrySuffix;
     private invokeCall;
+    private computeDispatchDeadline;
+    private prepareDispatchInput;
     private maybeWriteArtifact;
     private resolveDynamicPaths;
+    private resolveDynamicPathVariable;
+    private setEffectiveVariable;
+    /**
+     * Derive the engine-computed `context_available` template variable after
+     * context-builder preflight has had a chance to append to
+     * `context_bundle_files`. True when the union of the effective
+     * `context_files` and `context_bundle_files` path lists is non-empty.
+     * Stored as the STRING "true"/"false" since the template engine stringifies
+     * variable values. Engine-derived; setting it is expected.
+     */
+    private deriveContextAvailable;
+    /**
+     * Build the citation allowlist for a post-processor run: the union of files
+     * parsed from the `diff_context` variable, the resolved `context_files`, the
+     * resolved `context_bundle_files`, and the source files selected by any
+     * curated context-builder bundle among them. Both full paths and basenames
+     * are stored so citation matching is lenient.
+     *
+     * A curated preflight copies only `bundle.md` and `manifest.json` into
+     * `context_bundle_files`, so without the manifest's `selected_context`
+     * every citation to a real source file would be stripped. Reading from the
+     * (persisted) variable keeps this working on resume.
+     */
+    private buildPostProcessorAllowlist;
+    /**
+     * Add each `selected_context` entry of a context-builder manifest to the
+     * allowlist: its root-relative `path` and, when its root resolves, the
+     * absolute form. The allowlist is advisory, so an unreadable, oversized
+     * (> 8 MiB), non-JSON, or non-context-builder manifest is skipped silently
+     * and malformed entries are ignored.
+     */
+    private addCuratedBundleSelections;
+    /**
+     * Resolve a path-list variable to absolute paths without enforcing allowed
+     * roots (the post-processor allowlist is advisory, not a security boundary).
+     * Both the raw and resolved forms are returned so basename matching works
+     * regardless of how a citation spells the file.
+     */
+    private resolvePathListLenient;
+    private runContextBuilderPreflight;
+    /**
+     * Strip every force-excluded plan path from the effective context path
+     * variables (A-7). Idempotent and safe to call on any path — no policy means
+     * no-op, so non-plan-review runs are byte-unchanged.
+     *
+     * Returns the paths that were removed, for provenance.
+     */
+    private enforcePlanReviewContextExclusions;
+    private buildWorkflowContext;
+    private resolveContextPolicy;
+    private readOptionalStringVariable;
+    private readOptionalNumberVariable;
+    private readOptionalBooleanVariable;
+    private readStringArrayVariable;
     private createDeadlineController;
+    /** Remaining workflow budget in ms; undefined when no deadline is installed. */
+    private workflowRemainingMs;
+    /**
+     * True only while a workflow deadline is set AND already past. Pure: reads
+     * the deadline the running `execute()` installed and the clock, nothing else.
+     * `execute()` clears `workflowDeadlineAtMonoMs` in its `finally`, so this can
+     * never report a stale deadline from a prior run. The reading is monotonic:
+     * a wall-clock step (NTP correction, suspend/resume, manual change) can
+     * neither manufacture nor erase an exhausted budget.
+     */
+    private isWorkflowDeadlineExhausted;
     private throwIfAborted;
     private validateFinalStage;
     private validateAdvertisedCliNames;
     private defaultAllowedRoots;
+    private recordPlanReviewDeliveredAliases;
     private buildCallInput;
+    /**
+     * Derive a per-call invocation audit from the materialized input.
+     * Uses the dispatched cli_name/role (plan-review bindings may rewrite
+     * cli_name on resume) and never mutates `input`.
+     */
+    private maybeInvocationAudit;
     private materializeUnexpectedFailure;
     private emitRunStateChange;
     private emitCallPrepared;