clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/shutdown.js

@@ -12,90 +12,116 @@
 import { logger } from "./logger.js";
 /**
  * Manages graceful shutdown across signal handlers and MCP cancellation.
+ *
+ * Keyed registry: each run registers its own entry so concurrent runs (cap > 1)
+ * never clobber each other. Shutdown/cancel iterate over ALL registered entries.
  */
 export class ShutdownCoordinator {
-    state = {
-        session: null,
-        controller: null,
-        persistState: null,
-    };
+    entries = new Map();
+    nextHandle = 1;
     shuttingDown = false;
+    shutdownDrain;
+    shutdownSignal;
     /**
-     * Register the active session and abort controller for this run.
-     * Call at the start of each workflow run.
+     * Synchronously latch shutdown admission and abort every entry currently
+     * owned by the coordinator. The asynchronous persistence/termination drain
+     * is deliberately separate so no awaited cleanup for one entry can let
+     * another registered run continue dispatching work.
      */
-    register(session, controller, persistState) {
-        this.state = { session, controller, persistState };
-        this.shuttingDown = false;
+    beginShutdown(signal) {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.shutdownSignal = signal;
+        logger.info({ signal }, "received shutdown signal");
+        const abortReason = new Error(`Shutdown: ${signal}`);
+        for (const entry of this.entries.values()) {
+            try {
+                entry.controller.abort(abortReason);
+            }
+            catch (err) {
+                // AbortController listeners are caller-owned. A faulty listener must
+                // not prevent the remaining registered controllers from being latched.
+                logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to abort workflow during shutdown admission latch");
+            }
+        }
     }
-    /**
-     * Unregister the current run (on normal completion).
-     */
-    unregister() {
-        this.state = { session: null, controller: null, persistState: null };
+    /** Internal admission guard used by workflow-tools before acquiring a slot. */
+    isShuttingDown() {
+        return this.shuttingDown;
     }
     /**
-     * Get the AbortSignal for the current run.
-     * Use this to propagate cancellation to in-flight calls.
+     * Register a run's session and abort controller. Returns an opaque handle
+     * to be passed to unregister(). Each call adds a new entry; existing entries
+     * are never clobbered. Setup may supply a lazy terminate-only session and a
+     * completion fence covering its entire cleanup. Such runs own persistence
+     * themselves and pass a no-op persistState callback.
      */
-    get signal() {
-        return this.state.controller?.signal;
+    register(session, controller, persistState, completion) {
+        if (this.shuttingDown) {
+            try {
+                controller.abort(new Error(`Shutdown: ${this.shutdownSignal ?? "unknown"}`));
+            }
+            catch (err) {
+                logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to abort workflow rejected during shutdown");
+            }
+            throw new Error("Cannot register workflow after shutdown has started");
+        }
+        const handle = this.nextHandle;
+        this.nextHandle += 1;
+        this.entries.set(handle, { session, controller, persistState, completion });
+        return handle;
     }
     /**
-     * Cancel the current run (e.g., from MCP notifications/cancelled).
-     * Aborts in-flight calls, persists state, terminates child.
-     * Does NOT call process.exit — caller decides response behavior.
+     * Unregister a single run (on normal completion). Deletes only this handle's
+     * entry; other registered runs remain.
      */
-    async cancelRun() {
-        if (this.shuttingDown)
-            return;
-        this.shuttingDown = true;
-        logger.info("cancelling current workflow run");
-        // 1. Abort in-flight calls
-        this.state.controller?.abort(new Error("Workflow cancelled"));
-        // 2. Best-effort state persistence
-        await this.safePersistState();
-        // 3. Terminate child session
-        await this.safeTerminateSession();
+    unregister(handle) {
+        this.entries.delete(handle);
     }
     /**
      * Handle process shutdown.
-     * Cancel, persist, and terminate. The entrypoint owns process.exit.
+     * Cancel, persist, and terminate all registered runs. The entrypoint owns
+     * process.exit.
      */
     async shutdown(signal) {
-        if (this.shuttingDown) {
+        this.beginShutdown(signal);
+        if (this.shutdownDrain !== undefined) {
             logger.warn({ signal }, "duplicate shutdown signal ignored");
-            return;
-        }
-        this.shuttingDown = true;
-        logger.info({ signal }, "received shutdown signal");
-        // 1. Abort in-flight calls
-        this.state.controller?.abort(new Error(`Shutdown: ${signal}`));
-        // 2. Best-effort state persistence
-        await this.safePersistState();
-        // 3. Terminate child session
-        await this.safeTerminateSession();
-        logger.info({ signal }, "shutdown cleanup complete");
-    }
-    async safePersistState() {
-        if (this.state.persistState == null)
-            return;
-        try {
-            await this.state.persistState();
-        }
-        catch (err) {
-            logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to persist state during shutdown");
+            return await this.shutdownDrain;
         }
+        this.shutdownDrain = this.handleAll();
+        await this.shutdownDrain;
+        logger.info({ signal: this.shutdownSignal ?? signal }, "shutdown cleanup complete");
     }
-    async safeTerminateSession() {
-        if (this.state.session == null)
-            return;
-        try {
-            await this.state.session.terminate();
-        }
-        catch (err) {
-            logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to terminate child session during shutdown");
-        }
+    /** Abort, persist, and terminate every registered entry (best-effort). */
+    async handleAll() {
+        // Admission is latched and every controller was aborted synchronously.
+        // Start all drains before awaiting any run's setup/completion fence.
+        const snapshot = Array.from(this.entries.entries());
+        await Promise.all(snapshot.map(async ([handle, entry]) => {
+            // 2. Best-effort state persistence
+            try {
+                await entry.persistState();
+            }
+            catch (err) {
+                logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to persist state during shutdown");
+            }
+            // 3. Terminate child session
+            try {
+                await entry.session.terminate();
+            }
+            catch (err) {
+                logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to terminate child session during shutdown");
+            }
+            // Owned setup/run entries persist cancellation in their own unwind, then
+            // finish backend termination and store.close before resolving this fence.
+            // The coordinator never writes their store after it has closed.
+            if (entry.completion !== undefined)
+                await entry.completion;
+            // 4. Delete only the processed handle.
+            this.entries.delete(handle);
+        }));
     }
 }
 /** Singleton shutdown coordinator. */

package/clinkx-workflows/dist/shutdown.js.map

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

package/clinkx-workflows/dist/state-schema.d.ts

@@ -19,18 +19,34 @@
  */
 import type { ChildFailureMetadata } from "./errors.js";
 import type { FidelityMetadata } from "./fidelity.js";
+import type { WorkflowContext } from "./context-preflight.js";
+import type { ContextBuilderLifecycleStateV1 } from "./context-builder-lifecycle-contract.js";
+import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
+import type { PlanReviewRunState } from "./plan-review/run-state.js";
+import type { CouncilPlanReviewError } from "./plan-review/publication.js";
+import type { InvocationAuditRead, ObservedInvocationV1 } from "./dashboard/invocation-contract.js";
+import type { ResolvedRoster } from "./roster-contract.js";
 /** Call-level state progression. */
 export type CallState = "pending" | "running" | "succeeded" | "failed" | "cancelled";
 /** Run-level state progression. */
 export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
 /** Failure classification for diagnostics and retry decisions. */
 export type FailureClass = "transient" | "permanent";
+/** The canonical run-level terminal fields overwritten by a generic resume. */
+export interface PreviousTerminalEnvelope {
+    readonly status: "succeeded" | "failed" | "cancelled";
+    readonly completedAt?: string | undefined;
+    readonly error?: string | undefined;
+    readonly failureClass?: FailureClass | undefined;
+}
 /** Per-call state entry in the run state. */
 export interface CallStateEntry {
     readonly callId: string;
     readonly stageId: string;
     readonly state: CallState;
     readonly retryCount: number;
+    /** Durable count of provider attempts already dispatched for this call. */
+    readonly attemptsConsumed?: number | undefined;
     readonly startedAt?: string | undefined;
     readonly completedAt?: string | undefined;
     readonly durationMs?: number | undefined;
@@ -53,6 +69,16 @@ export interface CallStateEntry {
     readonly fidelity?: FidelityMetadata | undefined;
     /** Structured metadata from child _debug block on failure. */
     readonly childDebugMetadata?: ChildFailureMetadata | undefined;
+    /**
+     * Per-call model/effort provenance. Present only when the root server
+     * injected `deriveInvocationAudit`; omitted means "not recorded".
+     */
+    readonly invocation?: InvocationAuditRead | undefined;
+    /**
+     * Runtime-observed model/effort knobs from the child `_debug` block on a
+     * succeeded call. Telemetry-only; not fingerprint/cache identity.
+     */
+    readonly observedInvocation?: ObservedInvocationV1 | undefined;
 }
 /** Per-stage state entry. */
 export interface StageStateEntry {
@@ -112,6 +138,10 @@ export interface RunState {
     readonly workflowVersion: string;
     /** Overall run status. */
     readonly status: RunStatus;
+    /** Most recently overwritten generic terminal envelope; never recursive. */
+    readonly previousTerminal?: PreviousTerminalEnvelope | undefined;
+    /** Effective context policy fixed at initial admission for deterministic resume. */
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
     /** Whether this run is resumable (requires explicit child config). */
     readonly resumable: boolean;
     /** Child config fingerprint for fast mismatch rejection. */
@@ -130,6 +160,24 @@ export interface RunState {
     readonly stages: readonly StageStateEntry[];
     /** Resolved variables snapshot (non-secret only per 0-11a). */
     readonly variables: Readonly<Record<string, unknown>>;
+    /** Optional context-builder provenance metadata for preflight-enabled runs. */
+    readonly workflow_context?: WorkflowContext | undefined;
+    /**
+     * Latest live workflow-preflight lifecycle snapshot. This is observability
+     * only: workflow_context remains the sole durable completion/reuse fence.
+     */
+    readonly context_builder_lifecycle?: ContextBuilderLifecycleStateV1 | undefined;
+    /**
+     * Optional plan-review aux subtree (A-5). Present only for typed
+     * plan-review runs (`plan-review-receipts`, or the pre-rename name
+     * `council-plan-review`). Strictly Zod-validated on create and on read —
+     * unlike the rest of this state, a corrupt subtree here is a hard failure, not
+     * a degraded read, because it is the SOLE resume input for the execution
+     * contract, the immutable snapshot, and the per-call bindings.
+     */
+    readonly plan_review_state?: PlanReviewRunState | undefined;
+    /** Structured plan-review failure details; generic `error` remains canonical for older clients. */
+    readonly plan_review_error?: CouncilPlanReviewError | undefined;
     /** Run-level timing. */
     readonly startedAt?: string | undefined;
     readonly completedAt?: string | undefined;
@@ -138,4 +186,17 @@ export interface RunState {
     readonly failureClass?: FailureClass | undefined;
     /** Retain run directory on success for debugging when true. */
     readonly debugKeepArtifacts?: boolean | undefined;
+    /** Whether the run was admitted for detached async execution. */
+    readonly async?: boolean | undefined;
+    /**
+     * Requested-value council roster captured at admission (no provenance).
+     * Omitted on older state and on non-council / plan-review-receipts runs.
+     */
+    readonly resolvedRoster?: ResolvedRoster | undefined;
+    /**
+     * Named roster preset used at admission. Observability only; resume
+     * must not re-read the preset file. Omitted on older state and on
+     * runs that did not use a roster.
+     */
+    readonly rosterName?: string | undefined;
 }

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

@@ -1,23 +1,67 @@
 import type { EngineHooks, EngineResumeState } from "./engine.js";
 import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
-import type { RunState } from "./state-schema.js";
-export type RunDirectoryClassification = "failed" | "cancelled" | "debug_kept" | "active_locked" | "running_or_pending" | "unknown";
+import type { FailureClass, RunState } from "./state-schema.js";
+import { type WorkflowContext } from "./context-preflight.js";
+import type { WorkflowContextBuilderLifecycleTransition } from "./context-builder-lifecycle-router.js";
+import type { WorkflowContextPolicy } from "./context-mode-resolver.js";
+import { type ResolvedRoster } from "./roster-contract.js";
+import { type PlanReviewContextProvenance, type PlanReviewRunState } from "./plan-review/run-state.js";
+import { type CouncilPlanReviewError } from "./plan-review/publication.js";
+/**
+ * Reader-side staleness floor the shipped cadence is designed against; the
+ * dashboard observer derives its own threshold from the declared interval.
+ * Re-exported for tests and cross-module documentation only — nothing in this
+ * module consults it, because run-lock CONTROL decisions
+ * (`classifyRunLockSync`, `reapRunCancelled`, pruning) must never depend on
+ * mtime freshness.
+ */
+export { RUN_LOCK_HEARTBEAT_STALE_FLOOR_MS } from "./run-lock-heartbeat.js";
+/**
+ * Run-level error written by reconcileStaleRunDirectories. Deliberately
+ * distinct from STALE_RUNNING_RECOVERY_ERROR (the resume-path recovery string)
+ * so the two reconcile paths remain distinguishable in persisted state.
+ */
+export declare const STALE_RUN_RECONCILE_ERROR = "Reconciled stale running run: no live worker process";
+export type RunDirectoryClassification = "failed" | "cancelled" | "debug_kept" | "succeeded_async" | "succeeded_sync" | "active_locked" | "running_or_pending" | "unknown";
 export interface PruneRunDirectoriesOptions {
     readonly retainFailedDays?: number | undefined;
     readonly retainCancelledDays?: number | undefined;
     readonly retainDebugDays?: number | undefined;
+    readonly retainAsyncDays?: number | undefined;
+    readonly retainSucceededDays?: number | undefined;
 }
 export interface PruneRunDirectoriesResult {
     readonly pruned: number;
     readonly skipped: number;
     readonly errors: number;
 }
+export interface ReconcileStaleRunDirectoriesResult {
+    readonly scanned: number;
+    readonly reconciled: number;
+    readonly skipped_held: number;
+    readonly skipped_terminal: number;
+    readonly errors: number;
+}
+export type RunLockStatus = "held" | "stale_or_absent" | "unknown";
 export interface CreateWorkflowStateOptions {
     readonly runId: string;
     readonly definition: NormalizedWorkflowDefinition;
     readonly variables: Readonly<Record<string, unknown>>;
     readonly runDir?: string | undefined;
     readonly debugKeepArtifacts?: boolean | undefined;
+    readonly async?: boolean | undefined;
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
+    readonly resolvedRoster?: ResolvedRoster | undefined;
+    readonly rosterName?: string | undefined;
+}
+/**
+ * Warn-only signal recorded at create() when a sibling run with byte-identical
+ * workflow + inputs snapshot hashes previously failed with
+ * `failureClass:"permanent"`. Advisory only — see detectDuplicateReplay.
+ */
+export interface DuplicateReplaySignal {
+    readonly runId: string;
+    readonly completedAt?: string | undefined;
 }
 export interface ResumeWorkflowStateOptions {
     readonly runId: string;
@@ -28,8 +72,15 @@ export declare function classifyRunDirectory(runDirPath: string): RunDirectoryCl
 export declare function pruneRunDirectories(runsRootDir: string, options?: PruneRunDirectoriesOptions): Promise<PruneRunDirectoriesResult>;
 export declare class WorkflowStateStore {
     readonly runDir: string;
+    /** Portable journal identity; absent only for a legacy or failed-open run. */
+    readonly sessionLogGeneration: string | undefined;
+    /**
+     * Warn-only duplicate-replay signal detected at create(); undefined on
+     * resume and when no permanently-failed identical sibling was found.
+     */
+    readonly duplicateOfFailedRun: DuplicateReplaySignal | undefined;
     readonly definition: NormalizedWorkflowDefinition;
-    readonly variables: Readonly<Record<string, unknown>>;
+    variables: Readonly<Record<string, unknown>>;
     readonly hooks: EngineHooks;
     readonly resume: EngineResumeState;
     private state;
@@ -37,14 +88,135 @@ export declare class WorkflowStateStore {
     private readonly debugKeepArtifacts;
     private writeChain;
     private lockHeld;
+    private planReviewTerminalResult;
+    private readonly lockToken;
+    private heartbeat;
+    private heartbeatInFlight;
+    private heartbeatError;
+    private readonly persistInvocationAuditV2;
+    private readonly persistObservedInvocation;
     private constructor();
     static create(options: CreateWorkflowStateOptions): Promise<WorkflowStateStore>;
     static resume(options: ResumeWorkflowStateOptions): Promise<WorkflowStateStore>;
     get runState(): RunState;
+    /**
+     * Open a new generic resume attempt before any context preflight or provider
+     * setup. Provider-call attempt counters remain untouched; only the run-level
+     * terminal envelope is cleared so a pre-dispatch failure/cancellation can be
+     * persisted as the outcome of this resume attempt.
+     *
+     * Plan-review stale-run recovery has its own terminal-intent protocol and is
+     * deliberately left unchanged here.
+     */
+    beginResumeAttempt(): Promise<void>;
     markCancelled(reason?: string): Promise<void>;
+    /**
+     * Idempotently mark the run failed. Only applies when the current status is
+     * non-terminal (pending/running) so it never clobbers a richer engine-emitted
+     * terminal status (succeeded/failed/cancelled).
+     */
+    markFailed(error: string, failureClass?: FailureClass, planReviewError?: CouncilPlanReviewError): Promise<void>;
     flush(): Promise<void>;
+    commitPreflightContext({ variables, workflow_context, }: {
+        readonly variables: Readonly<Record<string, unknown>>;
+        readonly workflow_context: WorkflowContext;
+    }): Promise<void>;
+    observeContextBuilderLifecycleTransition(transition: WorkflowContextBuilderLifecycleTransition): Promise<void>;
+    /**
+     * Persist the plan-review aux subtree (A-5).
+     *
+     * Called immediately after `create()` and BEFORE any seat can be dispatched.
+     * It cannot be a `create()` argument in the runtime path: the subtree binds
+     * the canonical snapshot's hash, and the snapshot can only be materialized
+     * into a run directory that `create()` itself makes — and the plan requires a
+     * snapshot/digest failure to be a POST-state `failed` run, not a pre-state
+     * reject. `create()` still validates+persists the subtree when a caller
+     * already has one (e.g. a rebuild), so both entry points are strict.
+     */
+    commitPlanReviewState(state: PlanReviewRunState): Promise<void>;
+    /**
+     * Record that the plan-review context policy was actually enforced at the
+     * preflight seam, together with the post-filtered copied paths (A-7).
+     *
+     * Committed before stage dispatch so a resumed run replays the same enforced
+     * exclusion instead of re-deriving it from caller variables.
+     */
+    commitPlanReviewContextProvenance(provenance: PlanReviewContextProvenance): Promise<void>;
+    /** Persisted-state terminal projection used only by the engine's opt-in policy. */
+    projectPlanReviewTerminalResult(): Promise<string>;
+    /**
+     * Refresh this store's own `run.lock` mtime so a reader that cannot verify our
+     * PID namespace (a containerized or bind-mounted dashboard) has portable
+     * liveness evidence. Observation only — nothing in this module reads the
+     * mtime, and no control path consults it.
+     */
+    private startHeartbeat;
+    /**
+     * One descriptor-bound heartbeat beat: open the lock O_NOFOLLOW read-only,
+     * fstat + bounded positional read through the SAME handle, verify it is still
+     * our token, then utimes that still-open handle. Throws
+     * `RunLockOwnershipLostError` only on a complete valid record whose token
+     * differs; every other failure is an ordinary Error.
+     */
+    private beatRunLock;
+    private stopHeartbeat;
     close(): Promise<void>;
     private applyRetryUpdate;
+    /** Runs inside the caller's existing queue task; never enqueue from here. */
+    private finalizePlanReviewTerminalIntent;
     private enqueueWrite;
     private writeState;
 }
+export declare function readRunStateForStatus(runId: string): Promise<{
+    state: RunState;
+    lock: RunLockStatus;
+} | null>;
+/**
+ * Reap a run that has no live worker (orphaned/stale/prior-process) by writing a
+ * terminal "cancelled" state and unlinking its lock. Used by cancel_workflow when
+ * the run is not in this process's in-memory cancel registry.
+ *
+ * The run.lock is the single source of truth for ownership: this acquires the
+ * lock itself (reusing acquireRunLock, which atomically creates the lock and
+ * reclaims a stale same-host/dead-PID lock) BEFORE mutating, closing the TOCTOU
+ * where a concurrent resume_workflow could grab the lock between a caller's
+ * status read and the reap write.
+ *
+ * Returns:
+ *  - "locked"    — a LIVE lock blocks acquisition (held by a running worker, or a
+ *                  same-process blocking run); nothing is mutated.
+ *  - "ownership_unknown" — the lock is malformed/unreadable; nothing is mutated
+ *                           or reclaimed.
+ *  - "skipped"   — lock acquired but the run is already terminal (not
+ *                  pending/running); the lock is released and nothing is mutated.
+ *                  The caller re-reads to report already_terminal.
+ *  - "cancelled" — lock acquired and run was pending/running; terminal
+ *                  "cancelled" state is written and the lock removed.
+ *
+ * NOTE: This intentionally does NOT use WorkflowStateStore.resume() (which
+ * recovers + re-locks the run — the wrong intent here).
+ */
+export declare function reapRunCancelled(runId: string): Promise<"cancelled" | "skipped" | "locked" | "ownership_unknown">;
+/**
+ * Terminalize run directories frozen as running/pending with no live worker.
+ *
+ * A worker that dies between state writes (e.g. during a retry backoff delay,
+ * where applyRetryUpdate has already persisted errorMessage/failureClass while
+ * the call state stays "running") leaves the run persisted as `running`
+ * forever: the only other reconcile lives in WorkflowStateStore.resume(),
+ * which non-resumable runs never reach, and pruning skips running_or_pending
+ * directories. This scan converts such runs to terminal `failed` so status
+ * projection and retention can move on. No new persisted status is introduced;
+ * STALE_RUN_RECONCILE_ERROR is the distinct terminal representation.
+ *
+ * Liveness authority is classifyRunLockSync's same-host PID probe only:
+ * a run is touched solely when its lock is "stale_or_absent" (missing lock or
+ * same-host dead PID). "held" (live PID, or ANY foreign-host lock) and
+ * "unknown" (malformed lock) are skipped entirely, and no decision here
+ * consults heartbeat mtime freshness. TOCTOU-safety mirrors reapRunCancelled:
+ * acquire the run.lock (no heartbeat declaration, like other reap
+ * acquisitions), re-read state under the lock, re-verify non-terminal, write
+ * once, then release. Idempotent: reconciled runs are terminal `failed` and
+ * count as skipped_terminal on re-scan.
+ */
+export declare function reconcileStaleRunDirectories(runsRootDir: string): Promise<ReconcileStaleRunDirectoriesResult>;