clinkx 1.0.0 → 1.1.0

package/clinkx-workflows/dist/state.js

@@ -6,17 +6,20 @@ import { dirname, basename, isAbsolute, join, relative, resolve } from "node:pat
 import { hostname } from "node:os";
 import { fileURLToPath } from "node:url";
 import { WorkflowError } from "./errors.js";
+import { computeRunHealth } from "./run-health.js";
 import { buildFidelityMetadata, } from "./fidelity.js";
 import { fingerprintsMatch, generateFingerprint, generateWorkflowFingerprint, } from "./fingerprint.js";
+import { effectiveFinalizerEnabled } from "./delegate-finalizer-policy.js";
 import { parseWorkflowContext, } from "./context-preflight.js";
 import { isLegalContextBuilderLifecycleTransition, parseContextBuilderLifecycleStateV1, } from "./context-builder-lifecycle-contract.js";
+import { ResolvedRosterSchema, RosterNameSchema } from "./roster-contract.js";
 import { PlanReviewRunStateSchema, } from "./plan-review/run-state.js";
 import { CouncilPlanReviewErrorSchema, createPlanReviewPublicationError, serializePlanReviewResult, writeSerializedPlanReviewResultSidecar, } from "./plan-review/publication.js";
 import { isPlanReviewPublicationEligible, projectPlanReviewRun, } from "./plan-review/projector.js";
 import { isPlanReviewRunState } from "./plan-review/admission.js";
 import { restorePlanReviewRun } from "./plan-review/resume.js";
 import { PlanReviewStageError } from "./plan-review/stage-error.js";
-import { DEFAULT_RETAIN_ASYNC_DAYS, DEFAULT_RETAIN_CANCELLED_DAYS, DEFAULT_RETAIN_DEBUG_DAYS, DEFAULT_RETAIN_FAILED_DAYS, DEFAULT_RETAIN_SUCCEEDED_DAYS, deriveAllowedRoots, getArtifactsDir, getChildConfigPath, getChildMaxConcurrent, getChildMaxOutputBytes, getChildMaxPromptBytes, getChildMaxResponseChars, getLogLevel, getRetentionConfig, getRunsDir, getRunStateDir, getStateDir, resolveWorkspaceRoot, } from "./config.js";
+import { DEFAULT_RETAIN_ASYNC_DAYS, DEFAULT_RETAIN_CANCELLED_DAYS, DEFAULT_RETAIN_DEBUG_DAYS, DEFAULT_RETAIN_FAILED_DAYS, DEFAULT_RETAIN_SUCCEEDED_DAYS, deriveAllowedRoots, getArtifactsDir, getChildConfigPath, getChildMaxConcurrent, getChildMaxOutputBytes, getChildMaxPromptBytes, getChildMaxResponseChars, getLogLevel, getRetentionConfig, getRunsDir, getRunStateDir, getStateDir, invocationAuditV2PersistenceEnabled, observedInvocationPersistenceEnabled, resolveWorkspaceRoot, } from "./config.js";
 import { logger } from "./logger.js";
 import { resolveOpenedDescriptorPath } from "./contained-file.js";
 import { deriveWorkflowRunGeneration } from "./dashboard/generation.js";
@@ -186,38 +189,44 @@ class RunLockOwnershipLostError extends Error {
     }
 }
 export function classifyRunDirectory(runDirPath) {
+    return inspectRunDirectory(runDirPath).classification;
+}
+function inspectRunDirectory(runDirPath) {
     try {
         const state = readRunStateSync(runDirPath);
         const lockStatus = classifyRunLockSync(join(runDirPath, RUN_LOCK_FILENAME));
         if (lockStatus === "held") {
-            return "active_locked";
+            return { classification: "active_locked" };
         }
         if (lockStatus === "unknown") {
-            return "unknown";
+            return { classification: "unknown" };
         }
         switch (state.status) {
             case "failed":
-                return "failed";
+                return { classification: "failed", state };
             case "cancelled":
-                return "cancelled";
+                return { classification: "cancelled", state };
             case "succeeded": {
                 if ((state.debugKeepArtifacts !== undefined && typeof state.debugKeepArtifacts !== "boolean") ||
                     (state.async !== undefined && typeof state.async !== "boolean")) {
-                    return "unknown";
+                    return { classification: "unknown" };
                 }
-                return state.debugKeepArtifacts === true
-                    ? "debug_kept"
-                    : (state.async === true ? "succeeded_async" : "succeeded_sync");
+                return {
+                    classification: state.debugKeepArtifacts === true
+                        ? "debug_kept"
+                        : (state.async === true ? "succeeded_async" : "succeeded_sync"),
+                    state,
+                };
             }
             case "running":
             case "pending":
-                return "running_or_pending";
+                return { classification: "running_or_pending" };
             default:
-                return "unknown";
+                return { classification: "unknown" };
         }
     }
     catch {
-        return "unknown";
+        return { classification: "unknown" };
     }
 }
 export async function pruneRunDirectories(runsRootDir, options) {
@@ -246,8 +255,17 @@ export async function pruneRunDirectories(runsRootDir, options) {
         }
         const runDirPath = join(runsRootDir, entry.name);
         try {
-            const classification = classifyRunDirectory(runDirPath);
-            const retainDays = retentionDaysForClassification(classification, retention);
+            const { classification, state } = inspectRunDirectory(runDirPath);
+            let retainDays = retentionDaysForClassification(classification, retention);
+            if ((classification === "succeeded_async" || classification === "succeeded_sync") &&
+                state != null && retainDays != null && retainDays > 0 &&
+                computeRunHealth(state, state.context_builder_lifecycle).classification === "degraded") {
+                // Zero means unlimited retention, not the smallest TTL. Keep explicit
+                // debug policy separate and never shorten a longer success override.
+                retainDays = retention.retainFailedDays === 0
+                    ? 0
+                    : Math.max(retainDays, retention.retainFailedDays);
+            }
             if (retainDays == null || retainDays === 0) {
                 result.skipped += 1;
                 continue;
@@ -391,6 +409,8 @@ export class WorkflowStateStore {
     heartbeat;
     heartbeatInFlight;
     heartbeatError;
+    persistInvocationAuditV2;
+    persistObservedInvocation;
     constructor(options) {
         this.runDir = options.runDir;
         this.sessionLogGeneration = options.sessionLogGeneration;
@@ -402,6 +422,8 @@ export class WorkflowStateStore {
         this.debugKeepArtifacts = options.debugKeepArtifacts;
         this.lockPath = join(options.runDir, RUN_LOCK_FILENAME);
         this.lockToken = options.lockToken;
+        this.persistInvocationAuditV2 = invocationAuditV2PersistenceEnabled();
+        this.persistObservedInvocation = observedInvocationPersistenceEnabled();
         this.startHeartbeat();
         this.hooks = {
             onRunStateChange: async (event) => {
@@ -426,7 +448,9 @@ export class WorkflowStateStore {
                     }
                     const nextState = structuredClone(this.state);
                     nextState.status = event.state;
-                    nextState.startedAt = event.startedAt ?? nextState.startedAt;
+                    // First emit to set startedAt wins: a fresh run fills an empty
+                    // field, and a resume can never overwrite the original run start.
+                    nextState.startedAt = nextState.startedAt ?? event.startedAt;
                     nextState.completedAt = event.completedAt;
                     nextState.error = cappedError;
                     nextState.failureClass = event.failureClass;
@@ -443,6 +467,10 @@ export class WorkflowStateStore {
                     callEntry.materializedInputPath = inputPath;
                     callEntry.contextProducing = event.contextProducing;
                     callEntry.retryCount = event.retryCount;
+                    if (this.persistInvocationAuditV2 &&
+                        event.invocation !== undefined) {
+                        callEntry.invocation = event.invocation;
+                    }
                     this.state = nextState;
                     await this.writeState();
                 });
@@ -460,9 +488,33 @@ export class WorkflowStateStore {
                     callEntry.completedAt = event.completedAt;
                     callEntry.durationMs = event.durationMs;
                     callEntry.errorMessage = capPersistedError(event.error);
-                    callEntry.failureClass = event.failureClass;
+                    // Two opposite hazards, hence three branches:
+                    //   (1) ERASURE — a terminal emit that omits failureClass would, under
+                    //       an unconditional assignment, wipe a class the engine did
+                    //       classify. Only assign from the event when it carries one.
+                    //   (2) STALE CARRY-OVER — the succeeded emit carries no failureClass
+                    //       (engine.ts), while applyRetryUpdate persists one on every
+                    //       scheduled retry. Without the explicit clear, a call that
+                    //       finally succeeds after a retry stays stamped with the failed
+                    //       attempt's class forever, and is read as such by
+                    //       dashboard/scanner.ts and run-summary-derived.ts.
+                    // "running" is deliberately in neither branch: a running emit must
+                    // not clear the prior attempt's class, which resume reads.
+                    if (event.failureClass !== undefined) {
+                        callEntry.failureClass = event.failureClass;
+                    }
+                    else if (event.state === "succeeded") {
+                        callEntry.failureClass = undefined;
+                    }
                     callEntry.childDebugMetadata = event.childDebugMetadata;
                     callEntry.contextProducing = callEntry.contextProducing ?? false;
+                    // Observed-invocation telemetry rides only the terminal succeeded
+                    // emit; running/failed events carry none and must not write it.
+                    if (this.persistObservedInvocation &&
+                        event.observedInvocation !== undefined &&
+                        event.state === "succeeded") {
+                        callEntry.observedInvocation = event.observedInvocation;
+                    }
                     if (event.outputText != null) {
                         const { outputInline, outputPath } = await persistOutput(this.runDir, event.stageId, event.callId, event.outputText);
                         callEntry.outputInline = outputInline;
@@ -511,13 +563,19 @@ export class WorkflowStateStore {
             const childConfigPath = getChildConfigPath();
             const resumable = childConfigPath != null;
             const fingerprintData = resumable
-                ? await buildChildConfigFingerprint(options.definition)
+                ? await buildChildConfigFingerprint(options.definition, options.initialContextPolicy, options.variables)
                 : undefined;
             if (fingerprintData != null) {
                 const childConfigDir = join(runDir, CHILD_CONFIG_DIRNAME);
                 await mkdir(childConfigDir, { recursive: true });
                 await writeJsonAtomic(join(childConfigDir, CHILD_CONFIG_SNAPSHOT_FILENAME), fingerprintData.snapshot);
             }
+            const resolvedRoster = options.resolvedRoster !== undefined
+                ? ResolvedRosterSchema.parse(options.resolvedRoster)
+                : undefined;
+            const rosterName = options.rosterName !== undefined
+                ? RosterNameSchema.parse(options.rosterName)
+                : undefined;
             const state = {
                 state_version: 1,
                 runId: options.runId,
@@ -549,6 +607,8 @@ export class WorkflowStateStore {
                 initialContextPolicy: options.initialContextPolicy,
                 debugKeepArtifacts,
                 async: options.async ?? false,
+                ...(resolvedRoster !== undefined ? { resolvedRoster } : {}),
+                ...(rosterName !== undefined ? { rosterName } : {}),
             };
             await writeJsonAtomic(join(runDir, STATE_FILENAME), state);
             if (recycled.recycled) {
@@ -635,10 +695,12 @@ export class WorkflowStateStore {
             // Also verify live config hasn't drifted from original run
             const childConfigPath = getChildConfigPath();
             if (childConfigPath != null) {
-                const currentFingerprint = await buildChildConfigFingerprint(definition);
+                const currentFingerprint = await buildChildConfigFingerprint(definition, state.initialContextPolicy, state.variables);
                 if (!fingerprintsMatch(state.fingerprint, currentFingerprint.fingerprint)) {
                     throw new Error(`Run ${options.runId} cannot be resumed: live child config at ${childConfigPath} has changed since the original run. ` +
-                        `Restore the original config or start a new run.`);
+                        `Restore the original config or start a new run. ` +
+                        `The fingerprint can also mismatch after a ClinkX upgrade that changes fingerprint composition ` +
+                        `(for example context-delegate curator/finalizer refs), not only after live adapter JSON edits.`);
                 }
             }
             else {
@@ -1409,6 +1471,22 @@ function validateStrictStateSubtrees(state, statePath) {
                 .join("; ")}`);
         }
     }
+    if (state.resolvedRoster !== undefined) {
+        const parsed = ResolvedRosterSchema.safeParse(state.resolvedRoster);
+        if (!parsed.success) {
+            throw new Error(`Invalid resolvedRoster in ${statePath}: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "resolvedRoster"}: ${issue.message}`)
+                .join("; ")}`);
+        }
+    }
+    if (state.rosterName !== undefined) {
+        const parsed = RosterNameSchema.safeParse(state.rosterName);
+        if (!parsed.success) {
+            throw new Error(`Invalid rosterName in ${statePath}: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "rosterName"}: ${issue.message}`)
+                .join("; ")}`);
+        }
+    }
 }
 function lifecycleSnapshotsEqual(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
@@ -1958,7 +2036,27 @@ function buildPersistedFidelity(fidelity, contextProducing) {
         resultContractEnabled: fidelity.parseSource === "result_contract",
     });
 }
-async function buildChildConfigFingerprint(definition) {
+function resolveEnabledDelegateFingerprintRefs(policy, variables) {
+    const delegate = policy?.effectiveDelegate;
+    if (delegate?.enabled !== true) {
+        return undefined;
+    }
+    const curator = {
+        cli_name: delegate.curator.cli_name,
+        role: delegate.curator.role,
+    };
+    if (!effectiveFinalizerEnabled(delegate, variables)) {
+        return { curator };
+    }
+    return {
+        curator,
+        finalizer: {
+            cli_name: delegate.finalizer.cli_name,
+            role: delegate.finalizer.role,
+        },
+    };
+}
+async function buildChildConfigFingerprint(definition, policy, variables) {
     const configPath = getChildConfigPath();
     if (configPath == null) {
         throw new Error("Persistent resume requires CLINKX_WORKFLOWS_CHILD_CONFIG_PATH");
@@ -1975,7 +2073,10 @@ async function buildChildConfigFingerprint(definition) {
         CLINKX_ALLOWED_ROOTS: deriveAllowedRoots(workspaceRoot, getStateDir(), getArtifactsDir()),
         CLINKX_LOG_LEVEL: getLogLevel(),
     };
-    return generateWorkflowFingerprint(definition, adapterConfigs, resolvedPrompts, childEnv);
+    const delegateRefs = resolveEnabledDelegateFingerprintRefs(policy, variables);
+    return delegateRefs === undefined
+        ? generateWorkflowFingerprint(definition, adapterConfigs, resolvedPrompts, childEnv)
+        : generateWorkflowFingerprint(definition, adapterConfigs, resolvedPrompts, childEnv, delegateRefs);
 }
 async function loadNormalizedAdapterConfigs(configPath) {
     const paths = await listConfigFiles(configPath);
@@ -2039,6 +2140,8 @@ async function resolveRolePrompt(configFilePath, role) {
 function normalizeAdapterConfig(raw) {
     const rolesRecord = asRecord(raw["roles"]);
     const roles = Object.fromEntries(Object.entries(rolesRecord).map(([name, value]) => [name, normalizeRoleConfig(asRecord(value))]));
+    const invocationOverrides = raw["invocation_overrides"];
+    const promptFileFlag = asOptionalString(raw["prompt_file_flag"]);
     return {
         name: expectString(raw["name"], "adapter.name"),
         command: expectString(raw["command"], "adapter.command"),
@@ -2061,6 +2164,10 @@ function normalizeAdapterConfig(raw) {
         stdin_placeholder_arg: asOptionalString(raw["stdin_placeholder_arg"]),
         native_output_file_flag: asOptionalString(raw["native_output_file_flag"]),
         suppress_stdout: asOptionalBoolean(raw["suppress_stdout"]) ?? false,
+        ...(invocationOverrides !== undefined
+            ? { invocation_overrides: invocationOverrides }
+            : {}),
+        ...(promptFileFlag !== undefined ? { prompt_file_flag: promptFileFlag } : {}),
     };
 }
 function normalizeRoleConfig(raw) {