clinkx 1.1.2 → 1.2.0

package/clinkx-workflows/dist/workflow-tools.js

@@ -5,11 +5,12 @@
  * - Standalone STDIO server (ClinkSession child process backend)
  * - In-process integration (LocalClinkBackend via root ClinkX)
  *
- * The `registerWorkflowTools()` function registers five tools on a Server:
+ * The `registerWorkflowTools()` function registers six tools on a Server:
  * - run_workflow: start a new workflow execution
  * - resume_workflow: resume a failed/cancelled run
  * - list_workflows: list available workflow definitions
  * - workflow_run_status: read workflow run progress/result
+ * - workflow_run_wait: observe local execution settlement
  * - cancel_workflow: cancel a live or orphaned workflow run
  *
  * The caller provides a `createBackend` factory that determines how clink
@@ -51,7 +52,7 @@ import { restorePlanReviewRun, } from "./plan-review/resume.js";
 import { PlanReviewStageError } from "./plan-review/stage-error.js";
 import { CouncilPlanReviewErrorSchema, createPlanReviewPublicationError, inspectPlanReviewPublication, } from "./plan-review/publication.js";
 import { validatePlanReviewCallBindings, validatePlanReviewPreparedInputPolicy, } from "./plan-review/runtime-policy.js";
-import { ContainedFilePolicyError, readContainedRelativeFile, } from "./contained-file.js";
+import { ContainedFileChangedError, ContainedFilePolicyError, readContainedRelativeFile, } from "./contained-file.js";
 import { createDashboardRunReader } from "./dashboard/read-model.js";
 import { ROSTER_NAME_PATTERN, ResolvedRosterSchema, } from "./roster-contract.js";
 import { materializeArchitectureRoutes } from "./architecture-comparison/admission.js";
@@ -62,6 +63,8 @@ import { materializeVerifiedRepairRoutes, repairRoutesFromVariables } from "./ve
 import { VerifiedRepairRuntime } from "./verified-repair/runtime.js";
 import { inspectVerifiedRepairRecord } from "./verified-repair/result.js";
 import { readWorkflowVerification } from "./workflow-verification.js";
+import { readSessionLogGeneration } from "./dashboard/session-log-identity.js";
+import { WorkflowCompletionRegistry, inspectPublication, persistedIdentityFailure, WORKFLOW_WAIT_BUDGET_MS, } from "./workflow-completion.js";
 async function inspectLegacyWorkflowSessionLogGeneration(runDir, runId) {
     try {
         const result = await createDashboardRunReader().inspectGeneration?.(dirname(runDir), runId);
@@ -104,6 +107,7 @@ function createPreflightOnlyBackend(advertisedCliNames) {
 // Admission control
 // ---------------------------------------------------------------------------
 const activeRuns = new Map();
+const completions = new WorkflowCompletionRegistry();
 /**
  * Number of workflow tool handlers currently executing in the standalone
  * registration path. This includes non-run tools such as status/list/cancel;
@@ -173,6 +177,9 @@ function releaseMutex(runId) {
 /** Own setup before its first await, and keep that ownership through cleanup. */
 function acquireWorkflowRun(runId, options, requestSignal) {
     acquireMutex(runId, options);
+    // Bound lazily: a request rejected before it owns state never becomes an
+    // execution, so it cannot displace a settled one or consume a retained slot.
+    const owner = completions.owner(runId, getRunStateDir(runId));
     const controller = new AbortController();
     const signal = requestSignal === undefined
         ? controller.signal
@@ -201,6 +208,15 @@ function acquireWorkflowRun(runId, options, requestSignal) {
     if (requestSignal === undefined)
         cancelRegistry.set(runId, controller);
     return {
+        get executionId() { return owner.entry?.executionId; },
+        bindStore: async (store) => {
+            // Register first, so a pin on the previous execution already fails as
+            // identity_changed while this execution's id is being persisted.
+            const entry = owner.bind(store);
+            await store.bindExecution(entry.executionId);
+            completions.markStamped(entry);
+            return entry.executionId;
+        },
         signal,
         throwIfCancelled: () => {
             if (signal.aborted)
@@ -215,6 +231,14 @@ function acquireWorkflowRun(runId, options, requestSignal) {
                 catch (err) {
                     logger.warn({ err }, "backend.terminate() failed during cleanup");
                 }
+                try {
+                    await store?.flush?.();
+                    if (owner.entry !== undefined)
+                        await completions.recordPublication(owner.entry);
+                }
+                catch (err) {
+                    logger.warn({ err }, "workflow publication identity unavailable during cleanup");
+                }
                 try {
                     await store?.close();
                 }
@@ -226,6 +250,8 @@ function acquireWorkflowRun(runId, options, requestSignal) {
                 cancelRegistry.delete(runId);
                 releaseMutex(runId);
                 shutdownCoordinator.unregister(handle);
+                if (owner.entry !== undefined)
+                    completions.settle(owner.entry);
                 complete();
             }
         },
@@ -1124,18 +1150,22 @@ function appendDuplicateReplayBlock(content, store) {
     });
 }
 /**
- * Trailing additive content block for the admission-time requested-value
- * roster. Omitted when the run did not persist one (non-council, plan-review,
- * or pre-roster state). Defensive optional access: partial store mocks may
- * omit runState.
+ * Trailing additive identity block, always last: the admission-time
+ * requested-value roster (omitted for non-council, plan-review, or pre-roster
+ * state) and the execution_id bound to this request (omitted when the request
+ * was rejected before it owned state). No block when neither is present.
+ * Defensive optional access: partial store mocks may omit runState.
  */
-function appendResolvedRosterBlock(content, store) {
+function appendIdentityBlock(content, store, executionId) {
     const resolvedRoster = store?.runState?.resolvedRoster;
-    if (resolvedRoster === undefined)
+    if (resolvedRoster === undefined && executionId === undefined)
         return;
     content.push({
         type: "text",
-        text: JSON.stringify({ resolved_roster: resolvedRoster }),
+        text: JSON.stringify({
+            ...(resolvedRoster !== undefined ? { resolved_roster: resolvedRoster } : {}),
+            ...(executionId !== undefined ? { execution_id: executionId } : {}),
+        }),
     });
 }
 // ---------------------------------------------------------------------------
@@ -1527,6 +1557,7 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
         let effectiveDefinition;
         let initializedPlanReview;
         let preparedSnapshot;
+        let executionId;
         try {
             ownership.throwIfCancelled();
             const runDir = getRunStateDir(runId);
@@ -1559,6 +1590,7 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
             catch (err) {
                 throw new McpError(ErrorCode.InternalError, `Failed to initialize async run ${runId}: ${err instanceof Error ? err.message : String(err)}`);
             }
+            executionId = await ownership.bindStore(store);
             ownership.throwIfCancelled();
             // A-10: the async acknowledgement is a durability boundary. A caller
             // cannot observe `running` until every plan-review snapshot and the
@@ -1574,7 +1606,9 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
                     await markWorkflowCancelled(store);
                     throw new WorkflowCancellationError();
                 }
-                if (store !== undefined && planReviewPlan !== undefined) {
+                // Once bound (plan-review init, or a failed id stamp), the run owns a
+                // persisted record: terminalize it and disclose the bound identity.
+                if (store !== undefined && ownership.executionId !== undefined) {
                     try {
                         await markWorkflowFailed(store, runId, err);
                     }
@@ -1601,6 +1635,8 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
                         summary: failureSummary,
                         debugBlock: debug ? buildErrorDebugBlock(runId, store) : undefined,
                     });
+                    // Bound even if persisting the id then failed: the entry exists.
+                    appendIdentityBlock(content, store, ownership.executionId);
                     return { content, isError: true };
                 }
                 throw err;
@@ -1619,7 +1655,7 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
                 }
             }
         }
-        if (store === undefined || effectiveDefinition === undefined) {
+        if (store === undefined || effectiveDefinition === undefined || executionId === undefined) {
             await ownership.finish(store);
             throw new McpError(ErrorCode.InternalError, `Failed to initialize async run ${runId}`);
         }
@@ -1640,6 +1676,7 @@ async function executeRunWorkflow(server, options, args, signal, progressToken)
                     type: "text",
                     text: JSON.stringify({
                         run_id: runId,
+                        execution_id: executionId,
                         status: "running",
                         ...(duplicateOfFailedRun !== undefined
                             ? { duplicate_of_failed_run: duplicateOfFailedRun }
@@ -1877,6 +1914,7 @@ async function runWorkflowDetached(server, options, workflow, runId, resolvedVar
                 ...(rosterName !== undefined ? { rosterName } : {}),
             });
         }
+        await ownership.bindStore(store);
         ownership.throwIfCancelled();
         releaseLifecycleBinding = options.contextBuilderLifecycleRouter?.bind(runId, store);
         // A-5/A-6: snapshot + contract + typed subtree land here — after state
@@ -1986,7 +2024,7 @@ async function runWorkflowDetached(server, options, workflow, runId, resolvedVar
             debugBlock: debug ? buildDebugBlock(runId, result, store) : undefined,
         });
         appendDuplicateReplayBlock(content, store);
-        appendResolvedRosterBlock(content, store);
+        appendIdentityBlock(content, store, ownership.executionId);
         return { content };
     }
     catch (error) {
@@ -2039,7 +2077,7 @@ async function runWorkflowDetached(server, options, workflow, runId, resolvedVar
             debugBlock: debug && store != null ? buildErrorDebugBlock(runId, store) : undefined,
         });
         appendDuplicateReplayBlock(content, store);
-        appendResolvedRosterBlock(content, store);
+        appendIdentityBlock(content, store, ownership.executionId);
         return { content, isError: true };
     }
     finally {
@@ -2053,18 +2091,9 @@ async function runWorkflowDetached(server, options, workflow, runId, resolvedVar
     }
 }
 async function executeResumeWorkflow(server, options, args, signal, progressToken) {
-    const runId = args["run_id"];
+    const runId = runIdArg(args);
     const debug = args["debug"] === true;
     const receipt = args["receipt"] === true;
-    if (typeof runId !== "string" || runId === "") {
-        throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid "run_id" parameter');
-    }
-    try {
-        validateRunId(runId);
-    }
-    catch {
-        throw new McpError(ErrorCode.InvalidParams, `Invalid run_id "${runId}". Must match [A-Za-z0-9_-]{1,64}.`);
-    }
     // Plan-review terminal state is authoritative even while the detached run's
     // finally still owns the in-process mutex. Read it before duplicate-run
     // arbitration so terminal-before-cleanup never leaks as "already running".
@@ -2117,6 +2146,7 @@ async function executeResumeWorkflow(server, options, args, signal, progressToke
         // Open this attempt before classifying an abort during reconstruction;
         // otherwise a prior terminal record would suppress markCancelled.
         await store.beginResumeAttempt();
+        await ownership.bindStore(store);
         ownership.throwIfCancelled();
         releaseLifecycleBinding = options.contextBuilderLifecycleRouter?.bind(runId, store);
         const validatorRegistry = createValidatorRegistry();
@@ -2293,16 +2323,27 @@ async function executeResumeWorkflow(server, options, args, signal, progressToke
             summary,
             debugBlock: debug ? buildDebugBlock(runId, result, store) : undefined,
         });
+        appendIdentityBlock(content, null, ownership.executionId);
         return { content };
     }
     catch (error) {
+        // Only a bound attempt owns the persisted record. Before bind, a failed
+        // beginResumeAttempt leaves in-memory state "pending" while disk still
+        // holds the settled run's terminal bytes; persisting it would displace
+        // that settled execution.
+        const owned = ownership.executionId !== undefined;
         if (ownedSignal.aborted || error instanceof WorkflowCancellationError) {
-            await markWorkflowCancelled(store);
+            if (owned)
+                await markWorkflowCancelled(store);
             throw new WorkflowCancellationError();
         }
+        // A verified-repair store is never bound: this is the pre-mutex rejection
+        // reached when that read failed, so report it the same way (-32602).
+        if (!owned && store?.runState.workflowName === VERIFIED_REPAIR_WORKFLOW)
+            throw error;
         // Persist a terminal "failed" record for post-admission setup failures.
         // Idempotent: won't clobber an engine-emitted terminal status.
-        if (store != null) {
+        if (owned && store != null) {
             try {
                 await markWorkflowFailed(store, runId, error);
             }
@@ -2328,6 +2369,7 @@ async function executeResumeWorkflow(server, options, args, signal, progressToke
             summary: failureSummary,
             debugBlock: debug && store != null ? buildErrorDebugBlock(runId, store) : undefined,
         });
+        appendIdentityBlock(content, null, ownership.executionId);
         return { content, isError: true };
     }
     finally {
@@ -2428,9 +2470,18 @@ function parseLifecycleForStatus(value) {
         return undefined;
     }
 }
-async function executeWorkflowRunStatus(options, args) {
+function expectedExecutionId(args) {
+    const expected = args["expected_execution_id"];
+    if (expected === undefined)
+        return undefined;
+    if (typeof expected !== "string" || expected.length === 0 || expected.length > 128) {
+        throw new McpError(ErrorCode.InvalidParams, "expected_execution_id must be a nonempty string of at most 128 characters");
+    }
+    return expected;
+}
+/** Shared by resume and pinned/unpinned status/wait, preserving their existing messages. */
+function runIdArg(args) {
     const runId = args["run_id"];
-    const includeResult = args["include_result"] === true;
     if (typeof runId !== "string" || runId === "") {
         throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid "run_id" parameter');
     }
@@ -2440,12 +2491,242 @@ async function executeWorkflowRunStatus(options, args) {
     catch {
         throw new McpError(ErrorCode.InvalidParams, `Invalid run_id "${runId}". Must match [A-Za-z0-9_-]{1,64}.`);
     }
-    const read = await readRunStateForStatus(runId);
+    return runId;
+}
+function identityError(runId, reason) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify({ run_id: runId, error: reason }) }],
+    };
+}
+/**
+ * Project status for one bound execution and fence it. A settled execution is
+ * fenced on the digest of the exact state bytes the projection parsed (one
+ * state.json read on the success path); an active one only on provenance and
+ * directory incarnation, since it legitimately republishes state.
+ */
+async function projectGuardedStatus(options, args, entry) {
+    const wasSettled = entry.settled;
+    const wasStamped = entry.stamped;
+    const guard = {};
+    let result;
+    try {
+        result = await projectWorkflowRunStatus(options, args, guard);
+    }
+    catch (error) {
+        const reread = wasSettled ? (await inspectPublication(entry.runDir))?.fingerprint ?? null : undefined;
+        const failure = await completions.check(entry, reread);
+        if (failure !== undefined)
+            return { failure };
+        if (error instanceof ContainedFileChangedError) {
+            return { failure: wasSettled ? "identity_unavailable" : "state_read_unstable" };
+        }
+        throw error;
+    }
+    const failure = await completions.check(entry, wasSettled ? guard.stateDigest ?? null : undefined);
+    if (failure !== undefined)
+        return { failure };
+    // Another process sharing the state dir can resume the run in place, which
+    // keeps the directory incarnation; only the persisted id shows the change.
+    if (wasStamped && guard.executionId !== entry.executionId) {
+        return { failure: typeof guard.executionId === "string" ? "identity_changed" : "identity_unavailable" };
+    }
+    return { result };
+}
+async function executeWorkflowRunStatus(options, args) {
+    const expected = expectedExecutionId(args);
+    if (expected === undefined)
+        return projectWorkflowRunStatus(options, args);
+    const runId = runIdArg(args);
+    const selected = completions.select(getRunStateDir(runId), expected);
+    if (selected === "identity_unavailable") {
+        const persisted = await projectPersistedSettledStatus(options, args, runId, expected);
+        return "failure" in persisted ? identityError(runId, persisted.failure) : persisted.result;
+    }
+    if (typeof selected === "string")
+        return identityError(runId, selected);
+    if (selected === undefined)
+        return identityError(runId, "identity_unavailable");
+    const release = completions.retain(selected);
+    try {
+        const before = await completions.check(selected);
+        if (before !== undefined)
+            return identityError(runId, before);
+        const fenced = await projectGuardedStatus(options, args, selected);
+        return "failure" in fenced ? identityError(runId, fenced.failure) : fenced.result;
+    }
+    finally {
+        release();
+    }
+}
+async function executeWorkflowRunWait(options, args, signal) {
+    const started = Date.now();
+    const runId = runIdArg(args);
+    const expected = expectedExecutionId(args);
+    const selected = completions.select(getRunStateDir(runId), expected);
+    let outcome;
+    let entry;
+    let persistedExecutionId;
+    const release = typeof selected === "object" ? completions.retain(selected) : undefined;
+    const respond = (projection = { run_id: runId }) => {
+        if (signal.aborted)
+            throw new WorkflowCancellationError();
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ...projection,
+                        wait: {
+                            outcome,
+                            ...(entry !== undefined ? { execution_id: entry.executionId } : {}),
+                            ...(persistedExecutionId !== undefined ? { execution_id: persistedExecutionId } : {}),
+                            budget_ms: WORKFLOW_WAIT_BUDGET_MS,
+                            elapsed_ms: Math.max(0, Date.now() - started),
+                        },
+                    }),
+                }],
+        };
+    };
+    try {
+        if (selected === "identity_unavailable" && expected !== undefined) {
+            // No local record: settled only if state.json proves this execution ended.
+            const persisted = await projectPersistedSettledStatus(options, { run_id: runId }, runId, expected);
+            if (signal.aborted)
+                throw new WorkflowCancellationError();
+            if ("failure" in persisted) {
+                outcome = persisted.failure;
+                return respond();
+            }
+            outcome = "settled";
+            persistedExecutionId = expected;
+            return respond(JSON.parse(persisted.result.content[0].text));
+        }
+        if (typeof selected === "string")
+            outcome = selected;
+        else if (selected === undefined)
+            outcome = "not_owned";
+        else {
+            entry = selected;
+            outcome = await completions.wait(entry, signal);
+            const failure = await completions.check(entry);
+            if (failure !== undefined)
+                outcome = failure;
+        }
+        if (signal.aborted)
+            throw new WorkflowCancellationError();
+        // Never inspect a replacement or unreadable state after provenance fails.
+        if (outcome === "identity_changed" || outcome === "identity_unavailable")
+            return respond();
+        // Metadata only: the result body is fetched separately through the guarded status tool.
+        if (entry !== undefined) {
+            const fenced = await projectGuardedStatus(options, { run_id: runId }, entry);
+            if (signal.aborted)
+                throw new WorkflowCancellationError();
+            if ("failure" in fenced) {
+                // An unstable active read is a normal re-arm, never a hard error.
+                outcome = fenced.failure === "state_read_unstable" ? "budget_elapsed" : fenced.failure;
+                return respond();
+            }
+            return respond(JSON.parse(fenced.result.content[0].text));
+        }
+        const status = await projectWorkflowRunStatus(options, { run_id: runId });
+        const projection = JSON.parse(status.content[0].text);
+        if (projection["status"] === "not_found")
+            outcome = "not_found";
+        else if (projection["status"] === "orphaned")
+            outcome = "orphaned";
+        if (signal.aborted)
+            throw new WorkflowCancellationError();
+        return respond(projection);
+    }
+    finally {
+        release?.();
+    }
+}
+/**
+ * A pin with no local record (bound by an earlier process, or evicted here) is
+ * resolved from the executionId persisted in state.json. The id, terminal
+ * status and released run.lock are checked on the exact bytes the projection
+ * then renders. After the projection a second contained read must return the
+ * same bytes with the lock still released, the directory incarnation must be
+ * unchanged, and no local execution may have bound the run dir; otherwise the
+ * read fails closed, since a foreign resume keeps the generation.
+ */
+async function projectPersistedSettledStatus(options, args, runId, expected) {
+    const runDir = getRunStateDir(runId);
+    const latest = completions.select(runDir);
+    if (latest !== undefined && !latest.settled)
+        return { failure: "identity_changed" };
+    const before = await readSessionLogGeneration(runDir);
+    if (before.kind !== "available")
+        return { failure: "identity_unavailable" };
+    const guard = { persistedExecutionId: expected };
+    let result;
+    let projectionError;
+    try {
+        result = await projectWorkflowRunStatus(options, args, guard);
+    }
+    catch (error) {
+        // Unreadable, oversized, malformed or persistently changing state.
+        if (guard.persistedIdentity === undefined)
+            return { failure: "identity_unavailable" };
+        projectionError = error;
+    }
+    if (guard.persistedIdentity !== "matched")
+        return { failure: guard.persistedIdentity ?? "identity_unavailable" };
+    let reread;
+    try {
+        reread = await readRunStateForStatus(runId, true);
+    }
+    catch {
+        return { failure: "identity_unavailable" };
+    }
+    if (reread == null)
+        return { failure: "identity_unavailable" };
+    // Same rule as the first check: only a different stamped id is a change.
+    const rereadId = reread.state.executionId;
+    if (typeof rereadId === "string" && rereadId !== expected)
+        return { failure: "identity_changed" };
+    if (reread.stateDigest !== guard.stateDigest || reread.lock !== "stale_or_absent") {
+        return { failure: "identity_unavailable" };
+    }
+    const after = await readSessionLogGeneration(runDir);
+    // A new local bind supersedes the pin; mere eviction of `latest` does not.
+    const current = completions.select(runDir);
+    if (current !== undefined && current !== latest)
+        return { failure: "identity_changed" };
+    if (after.kind !== "available")
+        return { failure: "identity_unavailable" };
+    if (after.sessionLogGeneration !== before.sessionLogGeneration)
+        return { failure: "identity_changed" };
+    if (result !== undefined)
+        return { result };
+    // Same mapping as the in-memory settled path: a racing contained read fails closed.
+    if (projectionError instanceof ContainedFileChangedError)
+        return { failure: "identity_unavailable" };
+    throw projectionError;
+}
+async function projectWorkflowRunStatus(options, args, guard) {
+    const runId = runIdArg(args);
+    const includeResult = args["include_result"] === true;
+    const read = await readRunStateForStatus(runId, guard !== undefined);
     if (read == null) {
+        if (guard?.persistedExecutionId !== undefined)
+            guard.persistedIdentity = "identity_unavailable";
         return {
             content: [{ type: "text", text: JSON.stringify({ status: "not_found", run_id: runId }) }],
         };
     }
+    if (guard !== undefined) {
+        guard.stateDigest = read.stateDigest;
+        guard.executionId = read.state.executionId;
+    }
+    if (guard?.persistedExecutionId !== undefined) {
+        // Checked before any further I/O, on the bytes this projection renders.
+        guard.persistedIdentity = persistedIdentityFailure(read.state, read.lock, runId, guard.persistedExecutionId) ?? "matched";
+        if (guard.persistedIdentity !== "matched")
+            return { content: [] };
+    }
     const { state, lock } = read;
     const status = (state.status === "running" || state.status === "pending") && lock === "stale_or_absent"
         ? "orphaned"
@@ -3028,7 +3309,7 @@ const RUN_WORKFLOW_SCHEMA = {
         async: {
             type: "boolean",
             default: false,
-            description: "When true, start the run detached and return {run_id, status:'running'} immediately; poll workflow_run_status for progress and result.",
+            description: "When true, start detached and return {run_id, execution_id, status:'running'} immediately. Prefer workflow_run_wait for local completion, then workflow_run_status with expected_execution_id and include_result:true; status polling remains available for recovery. When false (blocking), the final content block carries execution_id once the run owned state.",
         },
         roster: {
             type: "string",
@@ -3121,6 +3402,12 @@ const LIST_WORKFLOWS_SCHEMA = {
     properties: {},
     additionalProperties: false,
 };
+const EXECUTION_ID_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    maxLength: 128,
+    description: "Opaque execution identity (also persisted in run state) returned by run_workflow (async ack or trailing sync block), resume_workflow, or a bare wait. A fence, not a capability: it grants nothing and only makes reads fail closed (identity_changed/identity_unavailable) if they would observe a different execution.",
+};
 const WORKFLOW_RUN_STATUS_SCHEMA = {
     type: "object",
     properties: {
@@ -3128,6 +3415,7 @@ const WORKFLOW_RUN_STATUS_SCHEMA = {
             type: "string",
             pattern: "^[A-Za-z0-9_-]{1,64}$",
         },
+        expected_execution_id: EXECUTION_ID_SCHEMA,
         include_result: {
             type: "boolean",
             default: false,
@@ -3137,6 +3425,15 @@ const WORKFLOW_RUN_STATUS_SCHEMA = {
     required: ["run_id"],
     additionalProperties: false,
 };
+const WORKFLOW_RUN_WAIT_SCHEMA = {
+    type: "object",
+    properties: {
+        run_id: { type: "string", pattern: "^[A-Za-z0-9_-]{1,64}$" },
+        expected_execution_id: EXECUTION_ID_SCHEMA,
+    },
+    required: ["run_id"],
+    additionalProperties: false,
+};
 const CANCEL_WORKFLOW_SCHEMA = {
     type: "object",
     properties: {
@@ -3248,13 +3545,14 @@ export function getWorkflowToolDefinitions(workflowsPath, availableCliNames) {
     return [
         {
             name: "run_workflow",
-            description: `Start a new multi-stage workflow execution.${workflowSuffix}\nAccepts optional \`members\` and \`chairman\` parameters for council workflows (council-default, council-answer, council-code-review, council-debug, council-discover, council-plan-review) to override member/reviewer composition and chairman CLI adapter at runtime. Council runs include a \`resolved_roster\` of requested seat and delegate values (no provenance) on the async ack, a trailing sync content block, and workflow_run_status.`,
+            description: `Start a new multi-stage workflow execution.${workflowSuffix}\nAccepts optional \`members\` and \`chairman\` parameters for council workflows (council-default, council-answer, council-code-review, council-debug, council-discover, council-plan-review) to override member/reviewer composition and chairman CLI adapter at runtime. Council runs include a \`resolved_roster\` of requested seat and delegate values (no provenance) on the async ack, a trailing sync content block, and workflow_run_status. Blocking runs end with one trailing identity block {resolved_roster?, execution_id?}; execution_id is present once the run owned state, absent when rejected before that.`,
             inputSchema: runSchema,
         },
         {
             name: "resume_workflow",
             description: "Resume a previously failed or cancelled workflow from its last checkpoint. " +
-                "Requires the original run_id and matching child config.",
+                "Requires the original run_id and matching child config. " +
+                "Once the resume owns the run, the final content block is {execution_id} for this attempt; pin workflow_run_wait/workflow_run_status to it. A resume rejected before then returns no execution_id and leaves the previous execution observable.",
             inputSchema: RESUME_WORKFLOW_SCHEMA,
         },
         {
@@ -3265,10 +3563,16 @@ export function getWorkflowToolDefinitions(workflowsPath, availableCliNames) {
         },
         {
             name: "workflow_run_status",
-            description: "Read-only status/progress of a workflow run. The full result is included only with include_result:true. Generic workflows preserve succeeded-final-call behavior; plan-review-receipts reports marker-driven availability and bytes independently of terminal status, with body-blind default polling. Every found run also carries a top-level `health` block {classification: \"ok\"|\"degraded\", reasons: string[]} computed read-time from persisted data — a run can be status:\"succeeded\" yet degraded when on_failure:continue swallowed failed calls or context preflight was partial/degraded (reasons: failed_calls_in_succeeded_run, context_partial, context_lifecycle_failed, coverage_degraded, delegate_fallback_used, context_external_gaps — the finalizer reported evidence gaps outside the delegate packet under external_gap_policy:\"degrade\", so conclusions depending on them are conditional). When a context-builder lifecycle snapshot is persisted, the `context` block additionally includes `lifecycle_status` and `coverage` {policy, status, required, selected, missing}. A parsed snapshot also projects `context.delegate.finalizer` {effective_enabled, execution_status, score?}; `score` is present only for a succeeded finalizer that recorded one, and the finalizer key is omitted when the lifecycle is missing, unparseable, or those fields are absent. While context preflight is still running (non-terminal lifecycle, no committed context yet) the `context` block is absent and a top-level `context_progress` {phase, status, updated_at, counts} reports scan progress instead. Found council runs also include a top-level `resolved_roster` of requested seat and delegate values (no provenance) when the run persisted one; older runs omit the key. Architecture comparisons additionally project comparison completeness and retained record availability independently of run execution status. Every found run has a separately versioned verification projection of historical inspected-at evidence; it establishes neither current source/runtime applicability nor owner acceptance.",
+            description: "Read-only status/progress of a workflow run. The full result is included only with include_result:true. Generic workflows preserve succeeded-final-call behavior; plan-review-receipts reports marker-driven availability and bytes independently of terminal status, with body-blind default polling. Every found run also carries a top-level `health` block {classification: \"ok\"|\"degraded\", reasons: string[]} computed read-time from persisted data — a run can be status:\"succeeded\" yet degraded when on_failure:continue swallowed failed calls or context preflight was partial/degraded (reasons: failed_calls_in_succeeded_run, context_partial, context_lifecycle_failed, coverage_degraded, delegate_fallback_used, context_external_gaps — the finalizer reported evidence gaps outside the delegate packet under external_gap_policy:\"degrade\", so conclusions depending on them are conditional). When a context-builder lifecycle snapshot is persisted, the `context` block additionally includes `lifecycle_status` and `coverage` {policy, status, required, selected, missing}. A parsed snapshot also projects `context.delegate.finalizer` {effective_enabled, execution_status, score?}; `score` is present only for a succeeded finalizer that recorded one, and the finalizer key is omitted when the lifecycle is missing, unparseable, or those fields are absent. While context preflight is still running (non-terminal lifecycle, no committed context yet) the `context` block is absent and a top-level `context_progress` {phase, status, updated_at, counts} reports scan progress instead. Found council runs also include a top-level `resolved_roster` of requested seat and delegate values (no provenance) when the run persisted one; older runs omit the key. Architecture comparisons additionally project comparison completeness and retained record availability independently of run execution status. Every found run has a separately versioned verification projection of historical inspected-at evidence; it establishes neither current source/runtime applicability nor owner acceptance. With expected_execution_id the response is fenced to that execution: a mismatch is isError {run_id, error:\"identity_changed\"|\"identity_unavailable\"} with no result, and an active execution whose state kept changing through every bounded reread is isError {run_id, error:\"state_read_unstable\"} — retryable; re-issue the same pinned call after a short backoff.",
             inputSchema: WORKFLOW_RUN_STATUS_SCHEMA,
             annotations: { readOnlyHint: true },
         },
+        {
+            name: "workflow_run_wait",
+            description: "Observe one local workflow execution through its cleanup fence for at most 30 seconds. Returns metadata status plus wait.outcome and execution_id; wait.budget_ms is the configured budget, not the time waited (see elapsed_ms). Re-arm budget_elapsed with the same identity; a persistently unstable state read on an active execution also re-arms as budget_elapsed, without projection. not_owned, orphaned and not_found return immediately: no local execution is witnessable here yet or any longer (a request still admitting has not bound one). expected_execution_id is a fence, not a capability. The settled fingerprint covers state.json bytes only, not result files. Cancellation detaches observation only. Unpinned foreign/historical state is not witnessed settlement; a pin whose execution reached terminal state settles from persisted state (e.g. after a restart). Fetch final results via workflow_run_status with expected_execution_id (it may return the retryable error state_read_unstable for an active execution; re-issue the same pinned call).",
+            inputSchema: WORKFLOW_RUN_WAIT_SCHEMA,
+            annotations: { readOnlyHint: true },
+        },
         {
             name: "cancel_workflow",
             description: "Cancel a workflow run by run_id. Aborts a live in-process async run (returns status:'cancelling'; poll workflow_run_status until it reaches terminal 'cancelled'). Reaps an orphaned/no-live-worker run to terminal 'cancelled' (reaped:true). Refuses a lock-held run owned by another live worker or a blocking run (cancellable:false). Idempotent; not_found and already_terminal are soft results.",
@@ -3283,6 +3587,7 @@ export const WORKFLOW_TOOL_NAMES = new Set([
     "resume_workflow",
     "list_workflows",
     "workflow_run_status",
+    "workflow_run_wait",
     "cancel_workflow",
 ]);
 /**
@@ -3301,6 +3606,8 @@ export async function handleWorkflowToolCall(server, options, name, args, signal
             return executeListWorkflows(options);
         case "workflow_run_status":
             return await executeWorkflowRunStatus(options, args);
+        case "workflow_run_wait":
+            return await executeWorkflowRunWait(options, args, signal);
         case "cancel_workflow":
             return await executeCancelWorkflow(options, args);
         default:
@@ -3314,8 +3621,8 @@ export async function handleWorkflowToolCall(server, options, name, args, signal
  * Register workflow tools on an MCP Server instance.
  *
  * This is the reusable core extracted from createWorkflowServer().
- * It registers five tools: run_workflow, resume_workflow, list_workflows,
- * workflow_run_status, cancel_workflow.
+ * It registers six tools: run_workflow, resume_workflow, list_workflows,
+ * workflow_run_status, workflow_run_wait, cancel_workflow.
  *
  * The `options.createBackend` factory determines how clink calls are
  * dispatched — callers provide either a child-process or in-process backend.