clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/context-mode-resolver.js

@@ -0,0 +1,126 @@
+import { getWorkflowsContextDefaultCurator } from "./config.js";
+import { asPreflightDelegateInput, isWorkflowDelegateAbsent, parseWorkflowDelegateInput, } from "./delegate-validate.js";
+export class WorkflowContextModeResolverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowContextModeResolverError";
+    }
+}
+export function resolveWorkflowContextMode(callerValue, contextDefault, preflightEnabled, callerDelegate, defaultCurator) {
+    if (!preflightEnabled) {
+        return {
+            requestedMode: contextDefault,
+            effectiveMode: "disabled",
+            preflightDisabled: true,
+        };
+    }
+    const requestedMode = resolveRequestedMode(callerValue, contextDefault);
+    if (isWorkflowDelegateAbsent(callerDelegate)) {
+        if (requestedMode === "full") {
+            return {
+                requestedMode,
+                effectiveMode: "full",
+                effectiveDelegate: makeDefaultFullDelegate(defaultCurator),
+                preflightDisabled: false,
+            };
+        }
+        return {
+            requestedMode,
+            effectiveMode: requestedMode,
+            preflightDisabled: false,
+        };
+    }
+    const delegate = parseWorkflowDelegateInput(callerDelegate);
+    if (requestedMode === "off") {
+        return {
+            requestedMode,
+            effectiveMode: "off",
+            preflightDisabled: false,
+        };
+    }
+    if (delegate.enabled !== true) {
+        return {
+            requestedMode,
+            effectiveMode: requestedMode === "full" ? "deterministic" : requestedMode,
+            preflightDisabled: false,
+        };
+    }
+    if (requestedMode === "deterministic") {
+        throw new WorkflowContextModeResolverError("cb_delegate with enabled:true requires cb_context_mode full; deterministic mode does not run delegates.");
+    }
+    return {
+        requestedMode,
+        effectiveMode: "full",
+        effectiveDelegate: asPreflightDelegateInput(delegate),
+        preflightDisabled: false,
+    };
+}
+function resolveRequestedMode(callerValue, contextDefault) {
+    if (callerValue == null) {
+        return contextDefault;
+    }
+    if (typeof callerValue !== "string") {
+        throw new WorkflowContextModeResolverError(`cb_context_mode must be one of full, deterministic, off, inherit; got ${typeof callerValue}`);
+    }
+    const normalized = callerValue.trim();
+    if (normalized === "" || normalized === "inherit") {
+        return contextDefault;
+    }
+    if (normalized === "full" ||
+        normalized === "deterministic" ||
+        normalized === "off") {
+        return normalized;
+    }
+    throw new WorkflowContextModeResolverError(`Invalid cb_context_mode "${normalized}"; expected full, deterministic, off, or inherit.`);
+}
+export const DEFAULT_FULL_DELEGATE_FINALIZER_CLI = "codex";
+export const DEFAULT_FULL_DELEGATE_PROVIDER_ROLE = "json";
+const DEFAULT_FULL_DELEGATE_FINALIZER_MIN_SCORE = 8.5;
+/**
+ * The single structural source of truth for the providers the default full
+ * delegate injects. Both {@link makeDefaultFullDelegate} (what runs) and
+ * {@link defaultFullDelegateProviders} (what startup validates) derive from this
+ * array, so cli_name/role can never drift between injected and validated shapes.
+ */
+function defaultFullDelegateDescriptors(defaultCurator) {
+    return [
+        {
+            label: "curator",
+            cli_name: defaultCurator ?? getWorkflowsContextDefaultCurator(),
+            role: DEFAULT_FULL_DELEGATE_PROVIDER_ROLE,
+        },
+        {
+            label: "finalizer",
+            cli_name: DEFAULT_FULL_DELEGATE_FINALIZER_CLI,
+            role: DEFAULT_FULL_DELEGATE_PROVIDER_ROLE,
+        },
+    ];
+}
+/**
+ * The enabled providers injected by {@link makeDefaultFullDelegate}, as a single
+ * source of truth so startup validation cannot drift from what is actually
+ * injected at runtime. Each entry is `{ label, cli_name, role }`.
+ */
+export function defaultFullDelegateProviders(defaultCurator) {
+    return defaultFullDelegateDescriptors(defaultCurator);
+}
+export function makeDefaultFullDelegate(defaultCurator) {
+    const descriptors = defaultFullDelegateDescriptors(defaultCurator);
+    const curator = descriptors.find((d) => d.label === "curator");
+    const finalizer = descriptors.find((d) => d.label === "finalizer");
+    return {
+        enabled: true,
+        curator: {
+            cli_name: curator.cli_name,
+            role: curator.role,
+        },
+        finalizer: {
+            cli_name: finalizer.cli_name,
+            role: finalizer.role,
+            enabled: true,
+            min_score: DEFAULT_FULL_DELEGATE_FINALIZER_MIN_SCORE,
+        },
+        failure_policy: "fallback",
+    };
+}
+//# sourceMappingURL=context-mode-resolver.js.map

package/clinkx-workflows/dist/context-mode-resolver.js.map

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

package/clinkx-workflows/dist/context-preflight.d.ts

@@ -0,0 +1,189 @@
+import { type ContextBuilderLifecycleStateV1 } from "./context-builder-lifecycle-contract.js";
+/**
+ * Structural passthrough mirror of the root context_builder public budget input
+ * (`src/context-builder/schema.ts` `ContextBuilderPublicBudgetInput`). All keys
+ * are optional; the root frozen schema remains the single deep validator.
+ */
+export interface PreflightContextBudgetInput {
+    readonly max_estimated_tokens?: number;
+    readonly max_files?: number;
+    readonly max_scan_files?: number;
+    readonly max_bytes_per_file?: number;
+    readonly max_total_bytes?: number;
+    readonly max_search_results?: number;
+}
+/**
+ * Structural passthrough mirror of the root context_builder `DelegateSchema`
+ * union (`src/context-builder/schema.ts`). Discriminated on `enabled`; this is a
+ * shallow shape only — the root frozen schema deep-validates provider configs.
+ */
+export type PreflightContextDelegateInput = {
+    readonly enabled?: false;
+} | {
+    readonly enabled: true;
+    readonly curator: {
+        readonly cli_name: string;
+        readonly role: string;
+        readonly model?: string;
+        readonly effort?: string;
+    };
+    readonly finalizer: {
+        readonly cli_name: string;
+        readonly role: string;
+        readonly enabled?: boolean;
+        readonly min_score?: number;
+        readonly model?: string;
+        readonly effort?: string;
+    };
+    readonly timeout_seconds?: number;
+    readonly max_response_chars?: number;
+    readonly failure_policy?: "fallback" | "fail";
+    readonly external_gap_policy?: "fail" | "degrade";
+};
+export interface PreflightContextInput {
+    readonly runId: string;
+    readonly runDir: string;
+    readonly cb_task: string;
+    readonly user_request: string;
+    readonly roots: readonly string[];
+    readonly focus_paths: readonly string[];
+    readonly include_globs: readonly string[];
+    readonly exclude_globs: readonly string[];
+    readonly search_terms: readonly string[];
+    readonly profile?: string | undefined;
+    readonly allow_secrets?: boolean | undefined;
+    readonly context_mode?: "full" | "deterministic" | "off" | "disabled" | undefined;
+    readonly allowRootWideDiscovery?: boolean | undefined;
+    readonly includeSelectedContext?: boolean | undefined;
+    readonly context_budget_adapter?: string | undefined;
+    readonly budget?: PreflightContextBudgetInput | undefined;
+    readonly delegate?: PreflightContextDelegateInput | undefined;
+}
+export interface ContextBuilderCacheShape {
+    readonly hit: boolean;
+    readonly write: boolean;
+    readonly target_id: string | null;
+    readonly key_prefix: string;
+}
+export interface ContextBuilderMetricsShape {
+    readonly files_seen: number;
+    readonly files_considered: number;
+    readonly files_selected: number;
+    readonly files_omitted: number;
+    readonly scan_cap_hit: boolean;
+    readonly search_cap_hit: boolean;
+    readonly discovery_byte_cap_hit: boolean;
+    readonly discovery_candidate_cap_hit: boolean;
+    readonly candidate_cap_hit: boolean;
+    readonly bytes_read: number;
+    readonly bytes_written: number;
+    readonly estimated_tokens: number;
+    readonly truncated: boolean;
+}
+export interface PreflightContextBudgetCapsShape {
+    readonly max_estimated_tokens?: number | undefined;
+    readonly max_files?: number | undefined;
+    readonly max_scan_files?: number | undefined;
+    readonly max_bytes_per_file?: number | undefined;
+    readonly max_total_bytes?: number | undefined;
+    readonly max_search_results?: number | undefined;
+}
+export interface PreflightContextObservabilityShape {
+    readonly curator_ms: number | null;
+    readonly finalizer_ms: number | null;
+    readonly candidate_pool_size: number;
+    readonly delegate_packet_size: number;
+    readonly budget_caps?: PreflightContextBudgetCapsShape | undefined;
+}
+export type ContextBuilderReceiptShape = Readonly<Record<string, unknown>>;
+export type ContextEvidenceClassShape = "review_target" | "public_entrypoint" | "reverse_consumer" | "configuration" | "dependency" | "regression_test";
+export interface ContextCoverageReportShape {
+    readonly policy_id: "review_deep_v1" | null;
+    readonly status: "satisfied" | "degraded" | "not_evaluated";
+    readonly required_when_available: readonly ContextEvidenceClassShape[];
+    readonly available: readonly ContextEvidenceClassShape[];
+    readonly selected: readonly ContextEvidenceClassShape[];
+    readonly missing_required: readonly ContextEvidenceClassShape[];
+    readonly advisory_missing: readonly ContextEvidenceClassShape[];
+    readonly unclassifiable: readonly ContextEvidenceClassShape[];
+}
+export interface WorkflowContextBuilderMetadata {
+    readonly source_run_id: string;
+    readonly source_artifact_dir: string;
+    readonly cache: ContextBuilderCacheShape;
+    readonly schema_version: number;
+    readonly status: "succeeded" | "partial";
+    readonly context_mode?: "full" | "deterministic" | "off" | "disabled" | undefined;
+    readonly copied_paths: readonly string[];
+    readonly coverage?: ContextCoverageReportShape | undefined;
+    readonly metrics: ContextBuilderMetricsShape;
+    readonly warning_count: number;
+    readonly omission_count: number;
+    /**
+     * Optional H0 lifecycle subtree. When a later producer supplies it, the
+     * subtree belongs in workflow state.json, never the standalone journal.
+     */
+    readonly lifecycle?: ContextBuilderLifecycleStateV1 | undefined;
+    readonly delegate?: {
+        readonly enabled: true;
+        readonly status: string;
+        readonly fallback_used: boolean;
+    } | undefined;
+}
+/**
+ * Light-caller provenance: records how the workflow context preflight derived
+ * its source-selection anchors. Sibling of {@link WorkflowContextBuilderMetadata}
+ * on {@link WorkflowContext} (NOT nested inside it) and NOT covered by
+ * `schema_version` — older persisted states simply omit it.
+ */
+export interface LightCallerProvenance {
+    /** "synthesized" when seed terms were derived (no caller focus/search), else "caller". */
+    readonly anchor_source: "caller" | "synthesized";
+    /** Whether root-wide discovery was actually requested on the runner input. */
+    readonly root_wide_used: boolean;
+    /** Effective synthesized search terms (empty when caller-anchored). */
+    readonly synthesized_search_terms: readonly string[];
+}
+export interface WorkflowContext {
+    readonly context_builder: WorkflowContextBuilderMetadata;
+    readonly light_caller?: LightCallerProvenance | undefined;
+}
+/**
+ * Decode the complete persisted workflow-context completion fence.
+ *
+ * Resume must never treat mere object presence as proof that preflight
+ * committed. This decoder rejects missing, extra, or malformed fields and
+ * delegates lifecycle validation to the lifecycle contract parser.
+ */
+export declare function parseWorkflowContext(value: unknown): WorkflowContext;
+export interface PreflightContextResult extends WorkflowContextBuilderMetadata {
+    readonly receipt: ContextBuilderReceiptShape;
+    readonly observability?: PreflightContextObservabilityShape | undefined;
+}
+export interface ContextBuilderRunner {
+    runOrReuse(input: PreflightContextInput, opts: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<PreflightContextResult>;
+    /**
+     * Eagerly validate caller-supplied context_builder `cb_roots` against the
+     * host source allowlist before any workflow backend dispatch can occur.
+     *
+     * The MCP tool boundary maps failures from this method to -32602
+     * InvalidParams. Empty roots are a no-op here because the runner validates
+     * its fallback source root during preflight mapping. Artifact-only
+     * CLINKX_ALLOWED_ROOTS entries (the `/.` marker form) are child I/O roots
+     * for copied artifacts/state and must never authorize context_builder source
+     * roots.
+     */
+    assertRootsAllowed(roots: readonly string[]): void;
+    /**
+     * Eagerly enforce the task-string secret guard BEFORE any workflow state is
+     * persisted. When the effective allow-secrets policy resolves false
+     * (cb_allow_secrets:false or CLINKX_CONTEXT_ALLOW_SECRETS=false), a
+     * high-confidence secret in a persisted free-text task variable (cb_task,
+     * user_request) is rejected here so it never lands in inputs.snapshot.json.
+     * Under the default allow-secrets:true this is a no-op. Failures map to
+     * -32602 InvalidParams at the tool boundary.
+     */
+    assertTaskSecretsAllowed(variables: Readonly<Record<string, unknown>>): void;
+}

package/clinkx-workflows/dist/context-preflight.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { parseContextBuilderLifecycleStateV1, } from "./context-builder-lifecycle-contract.js";
+const NonNegativeIntegerSchema = z.number().int().nonnegative();
+const ContextBuilderMetricsSchema = z.object({
+    files_seen: NonNegativeIntegerSchema,
+    files_considered: NonNegativeIntegerSchema,
+    files_selected: NonNegativeIntegerSchema,
+    files_omitted: NonNegativeIntegerSchema,
+    scan_cap_hit: z.boolean(),
+    search_cap_hit: z.boolean(),
+    discovery_byte_cap_hit: z.boolean(),
+    discovery_candidate_cap_hit: z.boolean(),
+    candidate_cap_hit: z.boolean(),
+    bytes_read: NonNegativeIntegerSchema,
+    bytes_written: NonNegativeIntegerSchema,
+    estimated_tokens: NonNegativeIntegerSchema,
+    truncated: z.boolean(),
+}).strict();
+const ContextCoverageClassSchema = z.enum([
+    "review_target",
+    "public_entrypoint",
+    "reverse_consumer",
+    "configuration",
+    "dependency",
+    "regression_test",
+]);
+const ContextCoverageSchema = z.object({
+    policy_id: z.enum(["review_deep_v1"]).nullable(),
+    status: z.enum(["satisfied", "degraded", "not_evaluated"]),
+    required_when_available: z.array(ContextCoverageClassSchema),
+    available: z.array(ContextCoverageClassSchema),
+    selected: z.array(ContextCoverageClassSchema),
+    missing_required: z.array(ContextCoverageClassSchema),
+    advisory_missing: z.array(ContextCoverageClassSchema),
+    unclassifiable: z.array(ContextCoverageClassSchema),
+}).strict();
+const WorkflowContextSchema = z.object({
+    context_builder: z.object({
+        source_run_id: z.string().min(1),
+        source_artifact_dir: z.string().min(1),
+        cache: z.object({
+            hit: z.boolean(),
+            write: z.boolean(),
+            target_id: z.string().min(1).nullable(),
+            key_prefix: z.string(),
+        }).strict(),
+        schema_version: z.number().int().positive(),
+        status: z.enum(["succeeded", "partial"]),
+        context_mode: z.enum(["full", "deterministic", "off", "disabled"]).optional(),
+        copied_paths: z.array(z.string()),
+        coverage: ContextCoverageSchema.optional(),
+        metrics: ContextBuilderMetricsSchema,
+        warning_count: NonNegativeIntegerSchema,
+        omission_count: NonNegativeIntegerSchema,
+        lifecycle: z.unknown().optional(),
+        delegate: z.object({
+            enabled: z.literal(true),
+            status: z.string(),
+            fallback_used: z.boolean(),
+        }).strict().optional(),
+    }).strict(),
+    light_caller: z.object({
+        anchor_source: z.enum(["caller", "synthesized"]),
+        root_wide_used: z.boolean(),
+        synthesized_search_terms: z.array(z.string()),
+    }).strict().optional(),
+}).strict();
+/**
+ * Decode the complete persisted workflow-context completion fence.
+ *
+ * Resume must never treat mere object presence as proof that preflight
+ * committed. This decoder rejects missing, extra, or malformed fields and
+ * delegates lifecycle validation to the lifecycle contract parser.
+ */
+export function parseWorkflowContext(value) {
+    const parsed = WorkflowContextSchema.parse(value);
+    const lifecycle = parsed.context_builder.lifecycle === undefined
+        ? undefined
+        : parseContextBuilderLifecycleStateV1(parsed.context_builder.lifecycle);
+    const { lifecycle: _unparsedLifecycle, ...contextBuilder } = parsed.context_builder;
+    return {
+        context_builder: {
+            ...contextBuilder,
+            ...(lifecycle === undefined ? {} : { lifecycle }),
+        },
+        ...(parsed.light_caller === undefined
+            ? {}
+            : { light_caller: parsed.light_caller }),
+    };
+}
+//# sourceMappingURL=context-preflight.js.map

package/clinkx-workflows/dist/context-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-preflight.js","sourceRoot":"","sources":["../src/context-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mCAAmC,GAEpC,MAAM,yCAAyC,CAAC;AA0KjD,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;AAChE,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,UAAU,EAAE,wBAAwB;IACpC,gBAAgB,EAAE,wBAAwB;IAC1C,cAAc,EAAE,wBAAwB;IACxC,aAAa,EAAE,wBAAwB;IACvC,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE;IACzB,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE;IAC3B,sBAAsB,EAAE,CAAC,CAAC,OAAO,EAAE;IACnC,2BAA2B,EAAE,CAAC,CAAC,OAAO,EAAE;IACxC,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE;IAC9B,UAAU,EAAE,wBAAwB;IACpC,aAAa,EAAE,wBAAwB;IACvC,gBAAgB,EAAE,wBAAwB;IAC1C,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC,MAAM,EAAE,CAAC;AACZ,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,CAAC;IACxC,eAAe;IACf,mBAAmB;IACnB,kBAAkB;IAClB,eAAe;IACf,YAAY;IACZ,iBAAiB;CAClB,CAAC,CAAC;AACH,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;IAC1D,uBAAuB,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IAC5D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IAC9C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IAC7C,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IACrD,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IACrD,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;CACpD,CAAC,CAAC,MAAM,EAAE,CAAC;AACZ,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC;QACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QAChC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;YACd,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE;YAChB,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;YAClB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;YACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;SACvB,CAAC,CAAC,MAAM,EAAE;QACX,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;QAC3C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACxC,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;QAC7E,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACjC,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,EAAE;QAC1C,OAAO,EAAE,2BAA2B;QACpC,aAAa,EAAE,wBAAwB;QACvC,cAAc,EAAE,wBAAwB;QACxC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;QACjC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;YACjB,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;YACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;YAClB,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;SAC3B,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACvB,CAAC,CAAC,MAAM,EAAE;IACX,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;QACrB,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QAChD,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE;QAC3B,wBAAwB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KAC9C,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvB,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,CAAC,eAAe,CAAC,SAAS,KAAK,SAAS;QAC9D,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,mCAAmC,CAAC,MAAM,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,EACJ,SAAS,EAAE,kBAAkB,EAC7B,GAAG,cAAc,EAClB,GAAG,MAAM,CAAC,eAAe,CAAC;IAC3B,OAAO;QACL,eAAe,EAAE;YACf,GAAG,cAAc;YACjB,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SAClD;QACD,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS;YACnC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/clinkx-workflows/dist/council-execution-policy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime-only policy for the shipped generic council workflows.
+ *
+ * Keep this allow-list separate from council expansion/runtime-member lists,
+ * for two reasons that are NOT "plan review configures retries differently" —
+ * the shipped YAMLs are value-identical on every retry/timeout/validator field:
+ *
+ * (a) `plan-review-receipts` pins its dispatched prompt byte-identically under
+ *     D9, so appending per-dispatch deadline guidance to it is forbidden, not
+ *     merely undesirable.
+ * (b) Membership is a deliberate allow-list, not a derived set. A generic
+ *     council — `council-plan-review` included — stays out until it is added
+ *     here on purpose.
+ */
+export declare const COUNCIL_EXECUTION_WORKFLOW_NAMES: readonly ["council-default", "council-answer", "council-code-review", "council-debug", "council-discover"];
+/**
+ * Workflows deliberately kept OUT of the council execution policy.
+ *
+ * Every workflow shipped in `workflows/` must appear in exactly one of
+ * `COUNCIL_EXECUTION_WORKFLOW_NAMES` or this list. The completeness pin in
+ * `tests/council-execution-policy.test.ts` reads the shipped catalog directly
+ * and fails the suite for any newly shipped workflow until it is classified on
+ * purpose — exclusion is a decision, not a default.
+ *
+ * There are exactly two entries, each excluded for its own reason. Nothing
+ * here is excluded merely for being unreviewed — a newly shipped workflow
+ * must still be classified either way before the suite goes green.
+ *
+ * - `council-plan-review` is ALSO the legacy persisted name of the typed
+ *   plan-review workflow, from before it was renamed to
+ *   `plan-review-receipts` (see `LEGACY_PLAN_REVIEW_RECEIPTS_WORKFLOW_NAME`
+ *   in `src/plan-review/admission.ts`). A resumed legacy typed run is
+ *   restored with typed plan-review policy (`planReviewContextPolicy`,
+ *   `plan_review_snapshot_text`), so admitting this name here would let such
+ *   a run receive per-dispatch deadline guidance appended to its D9-pinned
+ *   prompt. Admitting it requires a structural typed-run guard in
+ *   `prepareDispatchInput` first, not just a name check.
+ * - `plan-review-receipts` pins its dispatched prompt byte-identically under
+ *   D9, so appending per-dispatch deadline guidance to it is forbidden.
+ */
+export declare const COUNCIL_EXECUTION_EXCLUDED_WORKFLOW_NAMES: readonly ["council-plan-review", "plan-review-receipts"];
+/** Maximum UTF-8 size reserved for the per-dispatch advisory guidance. */
+export declare const COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES = 512;
+/** Finite time kept for final serialization before the provider cutoff. */
+export declare const COUNCIL_FINALIZATION_RESERVE_MS = 5000;
+export declare function isCouncilExecutionWorkflow(workflowName: string): boolean;
+/**
+ * Veto only an automatically scheduled retry after a confirmed wall timeout.
+ * Idle timeouts and other transient failures retain the existing retry policy.
+ */
+export declare function shouldVetoWallTimeoutRetry(workflowName: string, terminationReason: unknown): boolean;
+/**
+ * Build the bounded per-dispatch advisory time budget appended to council seat
+ * prompts.
+ *
+ * Takes DURATIONS, not epochs: the caller owns the monotonic budget arithmetic,
+ * and this function only projects those durations onto wall-clock timestamps at
+ * render time, because the model reads the rendered string against its own wall
+ * clock.
+ *
+ * Scope (D1): a resumed run starts a FRESH, full `timeout_seconds` budget.
+ * These values therefore describe the CURRENT execution only; they are not a
+ * total across resumes and must not be read as one.
+ */
+export declare function buildCouncilDeadlineGuidance(input: {
+    readonly workflowRemainingMs: number;
+    readonly callRemainingMs: number;
+}): string;

package/clinkx-workflows/dist/council-execution-policy.js

@@ -0,0 +1,110 @@
+/**
+ * Runtime-only policy for the shipped generic council workflows.
+ *
+ * Keep this allow-list separate from council expansion/runtime-member lists,
+ * for two reasons that are NOT "plan review configures retries differently" —
+ * the shipped YAMLs are value-identical on every retry/timeout/validator field:
+ *
+ * (a) `plan-review-receipts` pins its dispatched prompt byte-identically under
+ *     D9, so appending per-dispatch deadline guidance to it is forbidden, not
+ *     merely undesirable.
+ * (b) Membership is a deliberate allow-list, not a derived set. A generic
+ *     council — `council-plan-review` included — stays out until it is added
+ *     here on purpose.
+ */
+export const COUNCIL_EXECUTION_WORKFLOW_NAMES = [
+    "council-default",
+    "council-answer",
+    "council-code-review",
+    "council-debug",
+    "council-discover",
+];
+/**
+ * Workflows deliberately kept OUT of the council execution policy.
+ *
+ * Every workflow shipped in `workflows/` must appear in exactly one of
+ * `COUNCIL_EXECUTION_WORKFLOW_NAMES` or this list. The completeness pin in
+ * `tests/council-execution-policy.test.ts` reads the shipped catalog directly
+ * and fails the suite for any newly shipped workflow until it is classified on
+ * purpose — exclusion is a decision, not a default.
+ *
+ * There are exactly two entries, each excluded for its own reason. Nothing
+ * here is excluded merely for being unreviewed — a newly shipped workflow
+ * must still be classified either way before the suite goes green.
+ *
+ * - `council-plan-review` is ALSO the legacy persisted name of the typed
+ *   plan-review workflow, from before it was renamed to
+ *   `plan-review-receipts` (see `LEGACY_PLAN_REVIEW_RECEIPTS_WORKFLOW_NAME`
+ *   in `src/plan-review/admission.ts`). A resumed legacy typed run is
+ *   restored with typed plan-review policy (`planReviewContextPolicy`,
+ *   `plan_review_snapshot_text`), so admitting this name here would let such
+ *   a run receive per-dispatch deadline guidance appended to its D9-pinned
+ *   prompt. Admitting it requires a structural typed-run guard in
+ *   `prepareDispatchInput` first, not just a name check.
+ * - `plan-review-receipts` pins its dispatched prompt byte-identically under
+ *   D9, so appending per-dispatch deadline guidance to it is forbidden.
+ */
+export const COUNCIL_EXECUTION_EXCLUDED_WORKFLOW_NAMES = [
+    "council-plan-review",
+    "plan-review-receipts",
+];
+const COUNCIL_EXECUTION_WORKFLOW_NAME_SET = new Set(COUNCIL_EXECUTION_WORKFLOW_NAMES);
+/** Maximum UTF-8 size reserved for the per-dispatch advisory guidance. */
+export const COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES = 512;
+/** Finite time kept for final serialization before the provider cutoff. */
+export const COUNCIL_FINALIZATION_RESERVE_MS = 5_000;
+export function isCouncilExecutionWorkflow(workflowName) {
+    return COUNCIL_EXECUTION_WORKFLOW_NAME_SET.has(workflowName);
+}
+/**
+ * Veto only an automatically scheduled retry after a confirmed wall timeout.
+ * Idle timeouts and other transient failures retain the existing retry policy.
+ */
+export function shouldVetoWallTimeoutRetry(workflowName, terminationReason) {
+    return isCouncilExecutionWorkflow(workflowName) && terminationReason === "wall";
+}
+/**
+ * Build the bounded per-dispatch advisory time budget appended to council seat
+ * prompts.
+ *
+ * Takes DURATIONS, not epochs: the caller owns the monotonic budget arithmetic,
+ * and this function only projects those durations onto wall-clock timestamps at
+ * render time, because the model reads the rendered string against its own wall
+ * clock.
+ *
+ * Scope (D1): a resumed run starts a FRESH, full `timeout_seconds` budget.
+ * These values therefore describe the CURRENT execution only; they are not a
+ * total across resumes and must not be read as one.
+ */
+export function buildCouncilDeadlineGuidance(input) {
+    // The one legitimate wall read in this module: display timestamps are
+    // projected forward from now so the reading model can compare them against
+    // its own clock. No budget decision is derived from it.
+    const nowMs = Date.now();
+    const callRemaining = Math.max(0, input.callRemainingMs);
+    const workflowRemaining = Math.max(0, input.workflowRemainingMs);
+    const analysisMs = callRemaining - COUNCIL_FINALIZATION_RESERVE_MS;
+    // When the call window is at or under the finalization reserve there is no
+    // honest analysis cutoff to state. Omit the sentence rather than clamping it
+    // to now: "finish analysis by <now>" reads as an already-blown deadline and
+    // invites the model to abandon the call.
+    const analysisSentence = analysisMs > 0
+        ? `finish analysis and begin finalization by ${new Date(nowMs + analysisMs).toISOString()}; `
+        : "";
+    const guidance = `\n\n---\n` +
+        `EXECUTION TIME BUDGET (advisory; applies to this call in this execution): ` +
+        analysisSentence +
+        `final serialization cutoff is ${new Date(nowMs + callRemaining).toISOString()}. ` +
+        `Overall workflow budget ends in ${String(Math.ceil(workflowRemaining / 1000))}s; ` +
+        `approximately ${String(Math.ceil(callRemaining / 1000))}s remain for this call. ` +
+        `Do not begin optional work you cannot finish; return the best complete answer available within this budget.\n`;
+    // The template is fixed-width apart from at most two ISO timestamps and two
+    // seconds values; the analysis sentence is conditional. These bytes ship
+    // inside every admitted council seat prompt, so the reserve is a hard
+    // invariant for future edits to the wording.
+    if (Buffer.byteLength(guidance, "utf8") > COUNCIL_DEADLINE_GUIDANCE_RESERVE_BYTES) {
+        throw new Error("Council deadline guidance exceeds its reserved prompt budget");
+    }
+    return guidance;
+}
+//# sourceMappingURL=council-execution-policy.js.map

package/clinkx-workflows/dist/council-execution-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"council-execution-policy.js","sourceRoot":"","sources":["../src/council-execution-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,iBAAiB;IACjB,gBAAgB;IAChB,qBAAqB;IACrB,eAAe;IACf,kBAAkB;CACV,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAAG;IACvD,qBAAqB;IACrB,sBAAsB;CACd,CAAC;AAEX,MAAM,mCAAmC,GAAwB,IAAI,GAAG,CACtE,gCAAgC,CACjC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,uCAAuC,GAAG,GAAG,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAErD,MAAM,UAAU,0BAA0B,CAAC,YAAoB;IAC7D,OAAO,mCAAmC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CACxC,YAAoB,EACpB,iBAA0B;IAE1B,OAAO,0BAA0B,CAAC,YAAY,CAAC,IAAI,iBAAiB,KAAK,MAAM,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAG5C;IACC,sEAAsE;IACtE,2EAA2E;IAC3E,wDAAwD;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACzD,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACjE,MAAM,UAAU,GAAG,aAAa,GAAG,+BAA+B,CAAC;IAEnE,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,yCAAyC;IACzC,MAAM,gBAAgB,GACpB,UAAU,GAAG,CAAC;QACZ,CAAC,CAAC,6CAA6C,IAAI,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC,WAAW,EAAE,IAAI;QAC7F,CAAC,CAAC,EAAE,CAAC;IAET,MAAM,QAAQ,GACZ,WAAW;QACX,4EAA4E;QAC5E,gBAAgB;QAChB,iCAAiC,IAAI,IAAI,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC,WAAW,EAAE,IAAI;QAClF,mCAAmC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC,KAAK;QACnF,iBAAiB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC,0BAA0B;QAClF,+GAA+G,CAAC;IAElH,4EAA4E;IAC5E,yEAAyE;IACzE,sEAAsE;IACtE,6CAA6C;IAC7C,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,uCAAuC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/clinkx-workflows/dist/council-expander.d.ts

@@ -1,7 +1,7 @@
 /**
  * Council expander — runtime composition override.
  *
- * For the five council workflows, this module rewrites stages of a normalized
+ * For the runtime-member council workflows, this module rewrites stages of a normalized
  * workflow definition to match caller-supplied overrides:
  *   - `members`: rewrites stage 0 (members) and stage 1 (reviewers) to match
  *     the member count and cli_name mapping. Stances are applied to stage 0
@@ -18,6 +18,13 @@ export declare const COUNCIL_RUNTIME_MEMBER_WORKFLOWS: Set<string>;
 export declare function supportsRuntimeMembers(workflowName: string): boolean;
 /** All council workflows have exactly 4 stages: members, reviewers, ranking, chairman. */
 export declare const COUNCIL_STAGE_COUNT = 4;
+/** Caller-supplied runtime composition for one council seat. */
+export interface CouncilMemberInput {
+    readonly cli_name: string;
+    readonly stance?: string | undefined;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
 /**
  * Expand council workflow stages to match caller-supplied composition overrides.
  *
@@ -27,17 +34,11 @@ export declare const COUNCIL_STAGE_COUNT = 4;
  *
  * Returns a **new** `NormalizedWorkflowDefinition`; the input is never mutated.
  */
-export declare function expandCouncilComposition(definition: NormalizedWorkflowDefinition, members: ReadonlyArray<{
-    cli_name: string;
-    stance?: string;
-}> | undefined, workflowName: string, chairman?: string): NormalizedWorkflowDefinition;
+export declare function expandCouncilComposition(definition: NormalizedWorkflowDefinition, members: ReadonlyArray<CouncilMemberInput> | undefined, workflowName: string, chairman?: string, chairmanModel?: string, chairmanEffort?: string): NormalizedWorkflowDefinition;
 /**
  * @deprecated Use `expandCouncilComposition()` instead.
  *
  * Legacy wrapper that delegates to the new composition expander with
  * members-only expansion (no chairman override).
  */
-export declare function expandCouncilFirstStage(definition: NormalizedWorkflowDefinition, members: ReadonlyArray<{
-    cli_name: string;
-    stance?: string;
-}>, workflowName: string): NormalizedWorkflowDefinition;
+export declare function expandCouncilFirstStage(definition: NormalizedWorkflowDefinition, members: ReadonlyArray<CouncilMemberInput>, workflowName: string): NormalizedWorkflowDefinition;