@stigmer/runner 3.14.1 → 3.15.1

package/dist/harness/run-turn.js

@@ -0,0 +1,528 @@
+/**
+ * The turn runtime — one agent turn as a Temporal activity, written once for
+ * every harness, with the engine behind the adapter contract (`types.ts`).
+ *
+ * What runs here and nowhere else: the activity's identity and its
+ * execution-scoped context; the status and the single persist chokepoint;
+ * the periodic heartbeat; the stop controller and its four producers (the
+ * stall watchdog, the cost cap, the platform STOP, Temporal's cancellation);
+ * the resolution phases (`turn-context.ts`) composed into the `TurnInput`;
+ * the sink the adapter is handed; the terminal table (`terminal-table.ts`)
+ * with its throw-vs-return rule, applied by `settleWith`, the one writer of
+ * a terminal; the completion epilogue (final text,
+ * structured output, plan artifact, write-back); the finally that releases
+ * the workspace lock last. The adapter owns its SDK slice inside `runTurn`
+ * and its own teardown inside its own `finally`, which runs BEFORE this
+ * module's (the gate is torn down before the lock is released, as it always
+ * was).
+ *
+ * Shape: one activity per registry row (`createHarnessActivities`), each a
+ * closure over the adapter, the activity's byte-pinned name and one shared
+ * `StigmerClient`; `runTurnActivity` is the body. Every `console` line here
+ * names the activity (`ExecuteCursor started: …`) so the log reads as it did
+ * before the extraction, and never a harness literal — the harness is a
+ * registry row, not a branch.
+ *
+ * Extracted from `activities/execute-cursor/index.ts` `executeCursorInner`
+ * (S2 M3; the milestone log in stigmer-cloud
+ * `_projects/2026-09/20260911.03.sp.turn-runtime-extraction/` has every
+ * ruling). Its twelve resolution phases came out at M2; what came out here is
+ * everything between them and after the engine: the seventeen hermetic
+ * goldens under `execute-cursor/__tests__/hermetic/` pin the result byte
+ * for byte, and `__tests__/run-turn.test.ts` proves the table against the
+ * scripted fake without any engine at all.
+ */
+import { setMaxListeners } from "node:events";
+import { heartbeat, CancelledFailure, Context } from "@temporalio/activity";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase, InteractionMode, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { loadArtifactStorageConfig, resolveUsableArtifactStorage } from "../shared/artifact-storage.js";
+import { TimingRecorder } from "../shared/cold-start-timing.js";
+import { costCapExceeded } from "../shared/cost-guard.js";
+import { runWithExecutionContext } from "../shared/execution-context.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
+import { describeExecutionError } from "../shared/model-error.js";
+import { publishPlanArtifact } from "../shared/plan-artifact.js";
+import { StallTimeoutError, startStallWatchdog } from "../shared/stall-watchdog.js";
+import { reportSetupProgress, slimStatus, utcTimestamp } from "../shared/status.js";
+import { cancelInProgressSubAgentProtos } from "../shared/subagent-rows.js";
+import { removeStigmerSymlink } from "../shared/workspace/stigmer-link.js";
+import { cancellationReasonOf, classifyTurnInterruption, getShutdownSignalForQueue, } from "../shared/worker-shutdown.js";
+import { PersistChokepoint } from "./persist-chokepoint.js";
+import { StopController } from "./stop-controller.js";
+import { applyTerminalArm, costCapArm, failedArm, fileReviewResolvedArm, infrastructureCancelArm, pauseArm, platformStopArm, rejectedByUserArm, stallArm, TERMINAL_COPY, unexpectedErrorArm, workerShutdownArm, workspaceLockTimeoutArm, } from "./terminal-table.js";
+import { resolveTurnContext } from "./turn-context.js";
+import { UsageAccumulator } from "./usage-accumulator.js";
+/**
+ * Interval of the activity-wide periodic heartbeat. Started before any phase
+ * runs: setup phases make network calls (blueprint resolution, workspace
+ * clone, MCP backfill, engine create) that can stall, and a pulse only
+ * between them leaves every individual call uncovered — the production
+ * stale-proxy incident hung inside `Agent.create` with zero heartbeats and
+ * surfaced as an opaque five-minute Temporal timeout. The details name the
+ * current step so a stall is attributed. Safe ONLY because every call below
+ * is itself bounded (the resolve timeout, the stall watchdog): an unbounded
+ * hang under a live heartbeat would keep a dead activity alive forever.
+ */
+const PERIODIC_HEARTBEAT_MS = 30_000;
+/**
+ * Vendor SDKs register abort listeners on the cancellation signal for each
+ * concurrent tool call (fetch, MCP, shell). With 10+ parallel tools, Node's
+ * default limit of 10 triggers `MaxListenersExceededWarning` — a diagnostic
+ * warning, not a functional error, but it pollutes logs and creates false
+ * alarm fatigue. 25 covers observed peaks (~12 concurrent tools + the
+ * heartbeat + the shutdown signal + SDK internals) with headroom.
+ */
+const CANCELLATION_SIGNAL_MAX_LISTENERS = 25;
+/**
+ * Run one turn: the activity body behind every harness's registry row. Sets
+ * the execution-scoped context for the WHOLE activity (the interceptors stamp
+ * every proxy-bound request from it, and much of that traffic is the
+ * runtime's own: offload, attachments, the epilogue's extraction) and runs
+ * the turn inside it.
+ */
+export async function runTurnActivity(deps, input) {
+    const { executionId, threadId, turnSeq } = input;
+    console.log(`${deps.activityName} started: execution=${executionId}, threadId=${threadId || "(new)"}, turnSeq=${turnSeq}`);
+    return runWithExecutionContext(executionId, () => runTurn(deps, input));
+}
+async function runTurn(deps, input) {
+    const { adapter, activityName, client, config } = deps;
+    const { executionId } = input;
+    const status = create(AgentExecutionStatusSchema, {
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+        startedAt: utcTimestamp(),
+    });
+    // Cold-start timeline of this turn's setup: one mark after each phase, the
+    // adapter's own segments marked through the sink, emitted by the adapter
+    // once its engine is resolved (an early return skips it — partial setups
+    // are not comparable cold-start samples).
+    const setupTiming = new TimingRecorder();
+    // Artifact storage for offloading oversized tool outputs out of the
+    // persisted status and for publishing the plan artifact. Resolved once so
+    // every persist sees it. Best-effort: `undefined`, never a throw, when no
+    // substrate works; an absent store disables offload (the aggregate size cap
+    // still applies) and flips capture mode off (deny-gate fallback).
+    const artifactStorage = await resolveUsableArtifactStorage(loadArtifactStorageConfig(config), { executionId });
+    setupTiming.mark("resolve_artifact_storage");
+    const frame = { primaryDir: undefined, releaseWorkspaceLock: undefined, writeback: null };
+    const stop = new StopController();
+    let usage;
+    let heartbeatPhase = "setup";
+    let lastActivityDetail;
+    let watchdog;
+    const cancellationSignal = Context.current().cancellationSignal;
+    const shutdownSignal = getShutdownSignalForQueue(Context.current().info.taskQueue);
+    const periodicHeartbeat = startHeartbeat(PERIODIC_HEARTBEAT_MS, () => ({ phase: heartbeatPhase, execution: executionId }));
+    const chokepoint = new PersistChokepoint({
+        client,
+        executionId,
+        status,
+        offload: artifactStorage ? { artifactStorage, executionId } : undefined,
+        usage: () => usage,
+        heartbeat,
+        onPlatformStop: () => stop.stop({ kind: "platform-stop" }),
+    });
+    try {
+        setMaxListeners(CANCELLATION_SIGNAL_MAX_LISTENERS, cancellationSignal);
+    }
+    catch {
+        // An AbortSignal that does not support setMaxListeners (an older SDK):
+        // the warning is harmless, so this is not.
+    }
+    const onCancellation = () => stop.stop({ kind: "cancellation" });
+    if (cancellationSignal.aborted)
+        onCancellation();
+    else
+        cancellationSignal.addEventListener("abort", onCancellation, { once: true });
+    /** The interruption Temporal delivered, read when the table needs it. */
+    const interruption = () => classifyTurnInterruption({
+        cancellationReason: cancellationReasonOf(cancellationSignal),
+        shutdownSignalAborted: shutdownSignal?.aborted ?? false,
+    });
+    /**
+     * The one writer of a terminal: apply the arm, persist it ONCE, and end
+     * the activity the way the arm's disposition says. A thrown arm also marks
+     * the in-progress sub-agent rows cancelled before that persist, so the
+     * status the workflow reads back is the whole terminal state in one write.
+     * (The file-review resume in `settleResolution` is the one place that
+     * applies an arm itself: its write-back must land between the arm and the
+     * persist.)
+     *
+     * The table decides what is written and whether the activity throws; the
+     * caller may supply the `CancelledFailure` to throw. The catch does, to
+     * rethrow the failure it caught (the caught failure IS the evidence, #776)
+     * or to throw the after-error variant of the copy; every other caller lets
+     * the arm's own message stand.
+     */
+    const settleWith = async (arm, failure) => {
+        applyTerminalArm(status, arm);
+        if (arm.disposition.kind === "return") {
+            await chokepoint.write();
+            return { kind: "return", value: slimStatus(status) };
+        }
+        cancelInProgressSubAgentProtos(status.subAgentExecutions);
+        await chokepoint.write();
+        return { kind: "throw", error: failure ?? new CancelledFailure(arm.disposition.message) };
+    };
+    // ── The turn ended during resolution ──────────────────────────────────────
+    async function settleResolution(settlement) {
+        switch (settlement.kind) {
+            case "workspace-lock-timeout": {
+                const outcome = await settleWith(workspaceLockTimeoutArm(settlement.error));
+                console.warn(`${activityName} workspace lock timeout: execution=${executionId}`);
+                return outcome;
+            }
+            case "rejected-by-user":
+                // A reject of an irreversible action (shell/MCP) fails the execution.
+                return settleWith(rejectedByUserArm());
+            case "file-review-resolved": {
+                // Push the APPROVED tree — reconcile snapped rejected files back to
+                // baseline, so what finalize commits is exactly what the user kept.
+                // After reconcile, before persist, never on a failed reconcile
+                // (diverged bytes must not reach the remote).
+                applyTerminalArm(status, fileReviewResolvedArm(settlement));
+                if (!settlement.failed && frame.writeback) {
+                    await frame.writeback.finalize();
+                }
+                await chokepoint.write();
+                console.log(`${activityName} file-review resume short-circuit: execution=${executionId}, ` +
+                    `failed=${settlement.failed}, discarded=${settlement.discardedPaths.length}`);
+                return { kind: "return", value: slimStatus(status) };
+            }
+            default: {
+                const exhaustive = settlement;
+                throw new Error(`${activityName}: unknown resolution settlement ${String(exhaustive)}`);
+            }
+        }
+    }
+    // ── The engine's turn and its outcome ─────────────────────────────────────
+    async function runEngineTurn(turn) {
+        const maxCostUsd = turn.execution.spec?.executionConfig?.maxCostUsd ?? 0;
+        const accumulator = new UsageAccumulator(turn.model.serviceTier, turn.model.thinkingMode);
+        usage = accumulator;
+        // The stall watchdog: the periodic heartbeat proves the process is alive,
+        // not that the engine is progressing; if the engine wedges, nothing
+        // arrives and the turn would hang forever. Armed for the adapter's whole
+        // stretch (Q-M3-13) and reset by every `recordActivity`; on stall the
+        // signal aborts, the adapter cancels its run, and the table reports the
+        // stall with the last detail the adapter named.
+        watchdog = startStallWatchdog(config.cursorStreamStallTimeoutMs, (idleMs) => {
+            const error = new StallTimeoutError(idleMs, lastActivityDetail ? `last tool: ${lastActivityDetail}` : undefined);
+            console.warn(`${activityName} stall detected: execution=${executionId}, idleMs=${idleMs}, lastTool=${lastActivityDetail ?? "none"}`);
+            stop.stop({ kind: "stall", error });
+        });
+        const armedWatchdog = watchdog;
+        const sink = {
+            status,
+            stopSignal: stop.signal,
+            setupTiming,
+            requestPersist: () => chokepoint.request(),
+            recordActivity: (detail) => {
+                if (detail !== undefined)
+                    lastActivityDetail = detail;
+                armedWatchdog.recordActivity();
+            },
+            reportUsage: (delta) => {
+                accumulator.addTurn(delta);
+                // max_cost_usd enforcement (cost-guard.ts): the running estimate only
+                // advances here, so this is the single check point; the abort is how
+                // the adapter learns to end its run.
+                const estimated = accumulator.snapshot().estimatedCostUsd;
+                if (!stop.evidence.costCapExceeded && costCapExceeded(maxCostUsd, estimated)) {
+                    console.warn(`${activityName} cost cap exceeded: execution=${executionId}, ` +
+                        `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`);
+                    stop.stop({ kind: "cost-cap" });
+                }
+            },
+            reportProgress: (label) => reportSetupProgress(client, executionId, label),
+            bindHarnessState: async (harnessStateId) => {
+                turn.session.spec.harnessStateId = harnessStateId;
+                // Clear slug to avoid re-validation of potentially invalid
+                // server-generated slugs. BuildUpdateStateStep preserves the existing
+                // slug from the database record.
+                if (turn.session.metadata)
+                    turn.session.metadata.slug = "";
+                await client.updateSession(turn.session);
+                console.log(`Stored ${harnessStateId} as harness_state_id on session ${turn.sessionId}`);
+            },
+        };
+        heartbeatPhase = "harness";
+        const outcome = await adapter.runTurn(turn, sink);
+        armedWatchdog.stop();
+        heartbeatPhase = "epilogue";
+        switch (outcome.kind) {
+            case "completed":
+                return completeTurn(turn, ExecutionPhase.EXECUTION_COMPLETED);
+            case "cancelled":
+                return completeTurn(turn, ExecutionPhase.EXECUTION_CANCELLED);
+            case "awaiting_approval": {
+                // Pause for review exactly like the native harness: the adapter put
+                // the WAITING rows on the transcript; flip the phase, persist, and
+                // RETURN to the workflow, which waits for the approval signal and
+                // reinvokes.
+                status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
+                await chokepoint.write();
+                return { kind: "return", value: slimStatus(status) };
+            }
+            case "failed": {
+                const settledFailure = await settleWith(failedArm(outcome.message, outcome.surface));
+                console.error(`${activityName} failed (${outcome.surface}): execution=${executionId}, error=${outcome.message}` +
+                    (outcome.cause instanceof Error ? `, cause=${outcome.cause.message}` : ""));
+                return settledFailure;
+            }
+            case "interrupted":
+                return settleInterrupted(maxCostUsd, accumulator);
+            default: {
+                const exhaustive = outcome;
+                throw new Error(`${activityName}: unknown turn outcome ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+    /**
+     * The table for an `interrupted` outcome, in the orchestrator's precedence:
+     * a stall (FAILED, return) outranks everything; a cost cap (TERMINATED,
+     * return); then Temporal's cancellation as the signal's reason reads it —
+     * the runner's drain, the orchestrator's pause, an infrastructure cancel
+     * (all thrown); last a platform stop (COMPLETED, return).
+     */
+    async function settleInterrupted(maxCostUsd, accumulator) {
+        const evidence = stop.evidence;
+        if (evidence.stall) {
+            const outcome = await settleWith(stallArm(evidence.stall));
+            console.warn(`${activityName} stalled: execution=${executionId}, error=${status.error}`);
+            return outcome;
+        }
+        if (evidence.costCapExceeded) {
+            const estimated = accumulator.snapshot().estimatedCostUsd;
+            const outcome = await settleWith(costCapArm(maxCostUsd, estimated));
+            console.warn(`${activityName} terminated (cost cap): execution=${executionId}, ` +
+                `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`);
+            return outcome;
+        }
+        const delivered = interruption();
+        switch (delivered) {
+            case "worker-shutdown":
+                console.log(`${activityName} interrupted (worker shutdown): execution=${executionId}`);
+                return settleWith(workerShutdownArm());
+            case "pause":
+                console.log(`${activityName} paused: execution=${executionId}`);
+                return settleWith(pauseArm());
+            case "infrastructure":
+                console.log(`${activityName} interrupted (infrastructure cancel): execution=${executionId}`);
+                return settleWith(infrastructureCancelArm());
+            case "none":
+                break;
+            default: {
+                const exhaustive = delivered;
+                throw new Error(`${activityName}: unknown interruption ${String(exhaustive)}`);
+            }
+        }
+        if (evidence.platformStop) {
+            console.log(`${activityName} completed (platform stop): execution=${executionId}`);
+            return settleWith(platformStopArm());
+        }
+        // The adapter settled `interrupted` with the signal live: a contract
+        // violation, reported as the runner's own failure rather than guessed at.
+        return settleWith(unexpectedErrorArm("HarnessContractError", `${adapter.name} settled interrupted with no stop`));
+    }
+    /**
+     * A turn the engine finished (COMPLETED) or ended cancelled on its own
+     * (CANCELLED): the final text from the last AI row; the structured output
+     * the execution asked for, extracted from that text unless the adapter
+     * already folded it onto the status; the plan artifact in plan mode; the
+     * write-back safety net; the one persist that makes COMPLETED and the
+     * structured output visible atomically; the slim return with `final_text`
+     * and `structured` beside it.
+     */
+    async function completeTurn(turn, phase) {
+        status.completedAt = utcTimestamp();
+        status.phase = phase;
+        let structuredOutput = status.structuredOutput;
+        let finalText;
+        if (phase === ExecutionPhase.EXECUTION_COMPLETED) {
+            finalText = [...status.messages].reverse().find((m) => m.type === MessageType.MESSAGE_AI)?.content;
+            if (structuredOutput === undefined && turn.structuredOutputSchema && finalText) {
+                structuredOutput = await extractStructuredOutputFromText(turn, finalText);
+                if (structuredOutput !== undefined) {
+                    status.structuredOutput = structuredOutput;
+                }
+            }
+            // Plan mode: publish the final plan message as a plan artifact (named
+            // from the plan's title); the only artifact path a harness without an
+            // auto-publish pipeline has.
+            const interactionMode = turn.execution.spec?.executionConfig?.interactionMode ?? InteractionMode.UNSPECIFIED;
+            if (interactionMode === InteractionMode.PLAN && finalText && turn.artifactStorage) {
+                try {
+                    await publishPlanArtifact({ status, executionId, planText: finalText, artifactStorage: turn.artifactStorage });
+                }
+                catch (err) {
+                    console.warn(`${activityName} plan artifact publish skipped (non-fatal): execution=${executionId}, error=${err}`);
+                }
+            }
+            // Write-back safety net on terminal completion. A capture-mode turn
+            // with captured changes paused for review instead, so reaching here
+            // means no reviewable delta this turn and this is normally a no-op —
+            // it exists for stragglers outside the capture, and never runs
+            // mid-turn.
+            if (frame.writeback) {
+                await frame.writeback.finalize();
+            }
+        }
+        // NOW persist — the subscriber sees the phase and structured_output atomically.
+        await chokepoint.write();
+        console.log(`${activityName} completed: execution=${executionId}, phase=${ExecutionPhase[status.phase]}, ` +
+            `hasStructuredOutput=${structuredOutput !== undefined}` +
+            (status.error ? `, error=${status.error}` : ""));
+        const slim = slimStatus(status);
+        if (finalText !== undefined)
+            slim.final_text = finalText;
+        if (structuredOutput !== undefined)
+            slim.structured = structuredOutput;
+        return { kind: "return", value: slim };
+    }
+    /**
+     * Tier 1 + 1.5: JSON.parse, code-fence extraction, heuristic brace match.
+     * Tier 2: LLM extraction with withStructuredOutput — deterministic,
+     * function-calling guarantees schema-conformant output. Each tier logs
+     * its verdict; a failed LLM extraction is logged and yields nothing.
+     */
+    async function extractStructuredOutputFromText(turn, finalText) {
+        const { extractJsonFromText } = await import("../shared/extract-json.js");
+        const fromText = extractJsonFromText(finalText);
+        if (fromText !== undefined) {
+            console.log(`${activityName} structured output extracted (text): execution=${executionId}, finalTextLength=${finalText.length}`);
+            return fromText;
+        }
+        console.log(`${activityName} text extraction failed, trying LLM extraction: execution=${executionId}, ` +
+            `finalTextLength=${finalText.length}`);
+        try {
+            const { extractStructuredOutput } = await import("../shared/extract-structured-output.js");
+            const extracted = await extractStructuredOutput(finalText, turn.structuredOutputSchema, config, turn.model.requested);
+            if (extracted !== undefined) {
+                console.log(`${activityName} structured output extracted (LLM): execution=${executionId}`);
+            }
+            return extracted;
+        }
+        catch (extractErr) {
+            const errMsg = extractErr instanceof Error ? extractErr.message : String(extractErr);
+            console.error(`${activityName} structured output extraction FAILED: execution=${executionId}, ` +
+                `requestedModel=${turn.model.requested}, finalTextLength=${finalText.length}, error=${errMsg}`);
+            return undefined;
+        }
+    }
+    // ── Something threw ───────────────────────────────────────────────────────
+    /**
+     * The catch. An adapter never throws (its contract), so what lands here is
+     * the runtime's own: a `CancelledFailure` from a resolution phase (the
+     * lock wait), an unexpected error during resolution or the epilogue, or a
+     * contract violation. The cancellation arms are the table's throw arms
+     * through `settleWith`, with the failure this catch chooses to throw; the
+     * generic arm is the `internal` failure surface, returned.
+     */
+    async function settleThrown(err) {
+        const cancelledArm = () => {
+            const delivered = interruption();
+            switch (delivered) {
+                case "worker-shutdown":
+                    console.log(`${activityName} cancelled (worker shutdown) for execution ${executionId}`);
+                    return workerShutdownArm();
+                case "pause":
+                    console.log(`${activityName} cancelled (pause) for execution ${executionId}`);
+                    return pauseArm();
+                case "infrastructure":
+                    console.log(`${activityName} cancelled (infrastructure) for execution ${executionId}`);
+                    return infrastructureCancelArm();
+                case "none":
+                    return undefined;
+                default: {
+                    const exhaustive = delivered;
+                    throw new Error(`${activityName}: unknown interruption ${String(exhaustive)}`);
+                }
+            }
+        };
+        if (err instanceof CancelledFailure) {
+            // The cancellation arrived as a throw (the lock wait observes the
+            // signal); the caught failure IS the evidence (#776). A thrown
+            // cancellation with no delivered cancellation on the signal can only be
+            // the runtime's own `checkCancellation`-style throw: infrastructure.
+            return settleWith(cancelledArm() ?? infrastructureCancelArm(), err);
+        }
+        const errDetail = err instanceof Error ? err.message : String(err);
+        const arm = cancelledArm();
+        if (arm !== undefined) {
+            // A non-cancellation error while cancelled was most likely caused by the
+            // cancellation itself (a teardown mid-flight) and must not overwrite the
+            // state the workflow already expects: a pause stays PAUSED; anything
+            // else reads as the interruption it was.
+            if (arm.phase === ExecutionPhase.EXECUTION_PAUSED) {
+                console.log(`${activityName} error during pause (treating as pause): execution=${executionId}, error=${errDetail}`);
+                return settleWith(arm, new CancelledFailure(TERMINAL_COPY.pause.throwMessageAfterError));
+            }
+            console.log(`${activityName} error during infrastructure cancel: execution=${executionId}, error=${errDetail}`);
+            return settleWith({ ...infrastructureCancelArm(), error: `Execution interrupted: ${errDetail}` }, new CancelledFailure(TERMINAL_COPY.infrastructureCancel.throwMessageAfterError));
+        }
+        // Unwrap + classify before formatting: a model error arrives
+        // MiddlewareError-wrapped with raw provider prose; non-model errors keep
+        // the root error's own identity.
+        const { errorType, errorMessage } = describeExecutionError(err, { proxyMode: !!config.proxyEndpoint });
+        console.error(`${activityName} failed: execution=${executionId}, [${errorType}] ${errorMessage}`);
+        return settleWith(unexpectedErrorArm(errorType, errorMessage));
+    }
+    // ── Drive ─────────────────────────────────────────────────────────────────
+    let settled;
+    try {
+        const resolutionDeps = {
+            input,
+            client,
+            config,
+            status,
+            artifactStorage,
+            timing: setupTiming,
+            signal: cancellationSignal,
+            heartbeat,
+            enterPhase: (step) => {
+                heartbeatPhase = step;
+                heartbeat();
+            },
+            reportProgress: (label) => reportSetupProgress(client, executionId, label),
+        };
+        const resolution = await resolveTurnContext(resolutionDeps, adapter.capabilities, frame, () => chokepoint.write());
+        if (resolution.kind === "settled") {
+            settled = await settleResolution(resolution.settlement);
+        }
+        else {
+            settled = await runEngineTurn(resolution.input);
+        }
+    }
+    catch (err) {
+        settled = await settleThrown(err);
+    }
+    finally {
+        periodicHeartbeat.stop();
+        watchdog?.stop();
+        cancellationSignal.removeEventListener("abort", onCancellation);
+        // Remove the workspace's `.stigmer` link the skill and attachment phases
+        // created, so attaching a real repo leaves it untouched between turns
+        // (issue #173). After the adapter's own teardown (its gate), before the
+        // lock. Idempotent and non-throwing.
+        if (frame.primaryDir)
+            await removeStigmerSymlink(frame.primaryDir);
+        // Release the workspace turn lock LAST — every mutation of this turn has
+        // landed, and the next queued turn must not baseline before that.
+        // Idempotent and non-throwing, so it can never mask the turn's outcome.
+        await frame.releaseWorkspaceLock?.();
+    }
+    switch (settled.kind) {
+        case "return":
+            return settled.value;
+        case "throw":
+            throw settled.error;
+        default: {
+            const exhaustive = settled;
+            throw new Error(`${activityName}: unknown settlement ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=run-turn.js.map

package/dist/harness/run-turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-turn.js","sourceRoot":"","sources":["../../src/harness/run-turn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAmB,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,6DAA6D,CAAC;AACzG,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,8DAA8D,CAAC;AAK5H,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AACxG,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAsB,MAAM,6BAA6B,CAAC;AACxG,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,GAE1B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,qBAAqB,EACrB,uBAAuB,EACvB,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,GAExB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAA4D,MAAM,mBAAmB,CAAC;AAEjH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAU7C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAqB,EAAE,KAA8B;IACzF,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IACjD,OAAO,CAAC,GAAG,CACT,GAAG,IAAI,CAAC,YAAY,uBAAuB,WAAW,cAAc,QAAQ,IAAI,OAAO,aAAa,OAAO,EAAE,CAC9G,CAAC;IACF,OAAO,uBAAuB,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1E,CAAC;AAUD,KAAK,UAAU,OAAO,CAAC,IAAqB,EAAE,KAA8B;IAC1E,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvD,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAE9B,MAAM,MAAM,GAAG,MAAM,CAAC,0BAA0B,EAAE;QAChD,KAAK,EAAE,cAAc,CAAC,qBAAqB;QAC3C,SAAS,EAAE,YAAY,EAAE;KAC1B,CAAC,CAAC;IAEH,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,0CAA0C;IAC1C,MAAM,WAAW,GAAG,IAAI,cAAc,EAAE,CAAC;IAEzC,oEAAoE;IACpE,0EAA0E;IAC1E,0EAA0E;IAC1E,4EAA4E;IAC5E,kEAAkE;IAClE,MAAM,eAAe,GAAG,MAAM,4BAA4B,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAC/G,WAAW,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAE7C,MAAM,KAAK,GAAc,EAAE,UAAU,EAAE,SAAS,EAAE,oBAAoB,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrG,MAAM,IAAI,GAAG,IAAI,cAAc,EAAE,CAAC;IAClC,IAAI,KAAmC,CAAC;IACxC,IAAI,cAAc,GAAG,OAAO,CAAC;IAC7B,IAAI,kBAAsC,CAAC;IAC3C,IAAI,QAAmC,CAAC;IAExC,MAAM,kBAAkB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,kBAAkB,CAAC;IAChE,MAAM,cAAc,GAAG,yBAAyB,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACnF,MAAM,iBAAiB,GAAG,cAAc,CAAC,qBAAqB,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAE3H,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC;QACvC,MAAM;QACN,WAAW;QACX,MAAM;QACN,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS;QACvE,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK;QAClB,SAAS;QACT,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;KAC3D,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,eAAe,CAAC,iCAAiC,EAAE,kBAAkB,CAAC,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,2CAA2C;IAC7C,CAAC;IACD,MAAM,cAAc,GAAG,GAAS,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;IACvE,IAAI,kBAAkB,CAAC,OAAO;QAAE,cAAc,EAAE,CAAC;;QAC5C,kBAAkB,CAAC,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAElF,yEAAyE;IACzE,MAAM,YAAY,GAAG,GAAqB,EAAE,CAC1C,wBAAwB,CAAC;QACvB,kBAAkB,EAAE,oBAAoB,CAAC,kBAAkB,CAAC;QAC5D,qBAAqB,EAAE,cAAc,EAAE,OAAO,IAAI,KAAK;KACxD,CAAC,CAAC;IAEL;;;;;;;;;;;;;;OAcG;IACH,MAAM,UAAU,GAAG,KAAK,EAAE,GAAgB,EAAE,OAA0B,EAAoB,EAAE;QAC1F,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;YACzB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,CAAC;QACD,8BAA8B,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC1D,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,IAAI,IAAI,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5F,CAAC,CAAC;IAEF,6EAA6E;IAE7E,KAAK,UAAU,gBAAgB,CAAC,UAA0B;QACxD,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;YACxB,KAAK,wBAAwB,CAAC,CAAC,CAAC;gBAC9B,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,uBAAuB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC5E,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,sCAAsC,WAAW,EAAE,CAAC,CAAC;gBACjF,OAAO,OAAO,CAAC;YACjB,CAAC;YACD,KAAK,kBAAkB;gBACrB,sEAAsE;gBACtE,OAAO,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;YACzC,KAAK,sBAAsB,CAAC,CAAC,CAAC;gBAC5B,oEAAoE;gBACpE,oEAAoE;gBACpE,+DAA+D;gBAC/D,8CAA8C;gBAC9C,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC;gBAC5D,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;oBAC1C,MAAM,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;gBACnC,CAAC;gBACD,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;gBACzB,OAAO,CAAC,GAAG,CACT,GAAG,YAAY,gDAAgD,WAAW,IAAI;oBAC5E,UAAU,UAAU,CAAC,MAAM,eAAe,UAAU,CAAC,cAAc,CAAC,MAAM,EAAE,CAC/E,CAAC;gBACF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,UAAU,CAAC;gBACrC,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,mCAAmC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;IAED,6EAA6E;IAE7E,KAAK,UAAU,aAAa,CAAC,IAAe;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,UAAU,IAAI,CAAC,CAAC;QACzE,MAAM,WAAW,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC1F,KAAK,GAAG,WAAW,CAAC;QAEpB,0EAA0E;QAC1E,oEAAoE;QACpE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,gDAAgD;QAChD,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,0BAA0B,EAAE,CAAC,MAAM,EAAE,EAAE;YAC1E,MAAM,KAAK,GAAG,IAAI,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,cAAc,kBAAkB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACjH,OAAO,CAAC,IAAI,CACV,GAAG,YAAY,8BAA8B,WAAW,YAAY,MAAM,cAAc,kBAAkB,IAAI,MAAM,EAAE,CACvH,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QACH,MAAM,aAAa,GAAG,QAAQ,CAAC;QAE/B,MAAM,IAAI,GAAa;YACrB,MAAM;YACN,UAAU,EAAE,IAAI,CAAC,MAAM;YACvB,WAAW;YACX,cAAc,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE;YAC1C,cAAc,EAAE,CAAC,MAAM,EAAE,EAAE;gBACzB,IAAI,MAAM,KAAK,SAAS;oBAAE,kBAAkB,GAAG,MAAM,CAAC;gBACtD,aAAa,CAAC,cAAc,EAAE,CAAC;YACjC,CAAC;YACD,WAAW,EAAE,CAAC,KAAK,EAAE,EAAE;gBACrB,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC3B,sEAAsE;gBACtE,qEAAqE;gBACrE,qCAAqC;gBACrC,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC;gBAC1D,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,eAAe,IAAI,eAAe,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC;oBAC7E,OAAO,CAAC,IAAI,CACV,GAAG,YAAY,iCAAiC,WAAW,IAAI;wBAC7D,oBAAoB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAClF,CAAC;oBACF,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;gBAClC,CAAC;YACH,CAAC;YACD,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC;YAC1E,gBAAgB,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;gBACzC,IAAI,CAAC,OAAO,CAAC,IAAK,CAAC,cAAc,GAAG,cAAc,CAAC;gBACnD,2DAA2D;gBAC3D,sEAAsE;gBACtE,iCAAiC;gBACjC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ;oBAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,GAAG,EAAE,CAAC;gBAC3D,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzC,OAAO,CAAC,GAAG,CAAC,UAAU,cAAc,mCAAmC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;YAC3F,CAAC;SACF,CAAC;QAEF,cAAc,GAAG,SAAS,CAAC;QAC3B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAClD,aAAa,CAAC,IAAI,EAAE,CAAC;QACrB,cAAc,GAAG,UAAU,CAAC;QAE5B,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,WAAW;gBACd,OAAO,YAAY,CAAC,IAAI,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;YAChE,KAAK,WAAW;gBACd,OAAO,YAAY,CAAC,IAAI,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;YAChE,KAAK,mBAAmB,CAAC,CAAC,CAAC;gBACzB,oEAAoE;gBACpE,mEAAmE;gBACnE,kEAAkE;gBAClE,aAAa;gBACb,MAAM,CAAC,KAAK,GAAG,cAAc,CAAC,8BAA8B,CAAC;gBAC7D,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;gBACzB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;gBACrF,OAAO,CAAC,KAAK,CACX,GAAG,YAAY,YAAY,OAAO,CAAC,OAAO,gBAAgB,WAAW,WAAW,OAAO,CAAC,OAAO,EAAE;oBAC/F,CAAC,OAAO,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,WAAW,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7E,CAAC;gBACF,OAAO,cAAc,CAAC;YACxB,CAAC;YACD,KAAK,aAAa;gBAChB,OAAO,iBAAiB,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;YACpD,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,OAAO,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,0BAA0B,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACzF,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,UAAU,iBAAiB,CAAC,UAAkB,EAAE,WAA6B;QAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YAC3D,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,uBAAuB,WAAW,WAAW,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YACzF,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,IAAI,QAAQ,CAAC,eAAe,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC;YAC1D,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;YACpE,OAAO,CAAC,IAAI,CACV,GAAG,YAAY,qCAAqC,WAAW,IAAI;gBACjE,oBAAoB,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAClF,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;QACjC,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,iBAAiB;gBACpB,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,6CAA6C,WAAW,EAAE,CAAC,CAAC;gBACvF,OAAO,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;YACzC,KAAK,OAAO;gBACV,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,sBAAsB,WAAW,EAAE,CAAC,CAAC;gBAChE,OAAO,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;YAChC,KAAK,gBAAgB;gBACnB,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,mDAAmD,WAAW,EAAE,CAAC,CAAC;gBAC7F,OAAO,UAAU,CAAC,uBAAuB,EAAE,CAAC,CAAC;YAC/C,KAAK,MAAM;gBACT,MAAM;YACR,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,SAAS,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,0BAA0B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACjF,CAAC;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,yCAAyC,WAAW,EAAE,CAAC,CAAC;YACnF,OAAO,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,qEAAqE;QACrE,0EAA0E;QAC1E,OAAO,UAAU,CAAC,kBAAkB,CAAC,sBAAsB,EAAE,GAAG,OAAO,CAAC,IAAI,mCAAmC,CAAC,CAAC,CAAC;IACpH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,UAAU,YAAY,CAAC,IAAe,EAAE,KAAqB;QAChE,MAAM,CAAC,WAAW,GAAG,YAAY,EAAE,CAAC;QACpC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QAErB,IAAI,gBAAgB,GAAY,MAAM,CAAC,gBAAgB,CAAC;QACxD,IAAI,SAA6B,CAAC;QAElC,IAAI,KAAK,KAAK,cAAc,CAAC,mBAAmB,EAAE,CAAC;YACjD,SAAS,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;YAEnG,IAAI,gBAAgB,KAAK,SAAS,IAAI,IAAI,CAAC,sBAAsB,IAAI,SAAS,EAAE,CAAC;gBAC/E,gBAAgB,GAAG,MAAM,+BAA+B,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;gBAC1E,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;oBACnC,MAAM,CAAC,gBAAgB,GAAG,gBAA8B,CAAC;gBAC3D,CAAC;YACH,CAAC;YAED,sEAAsE;YACtE,sEAAsE;YACtE,6BAA6B;YAC7B,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,eAAe,IAAI,eAAe,CAAC,WAAW,CAAC;YAC7G,IAAI,eAAe,KAAK,eAAe,CAAC,IAAI,IAAI,SAAS,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBAClF,IAAI,CAAC;oBACH,MAAM,mBAAmB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;gBACjH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,yDAAyD,WAAW,WAAW,GAAG,EAAE,CAAC,CAAC;gBACpH,CAAC;YACH,CAAC;YAED,oEAAoE;YACpE,oEAAoE;YACpE,qEAAqE;YACrE,+DAA+D;YAC/D,YAAY;YACZ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;YACnC,CAAC;QACH,CAAC;QAED,gFAAgF;QAChF,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CACT,GAAG,YAAY,yBAAyB,WAAW,WAAW,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI;YAC5F,uBAAuB,gBAAgB,KAAK,SAAS,EAAE;YACvD,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAClD,CAAC;QAEF,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAA4B,CAAC;QAC3D,IAAI,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QACzD,IAAI,gBAAgB,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,gBAAgB,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,KAAK,UAAU,+BAA+B,CAAC,IAAe,EAAE,SAAiB;QAC/E,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,GAAG,CACT,GAAG,YAAY,kDAAkD,WAAW,qBAAqB,SAAS,CAAC,MAAM,EAAE,CACpH,CAAC;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,GAAG,CACT,GAAG,YAAY,6DAA6D,WAAW,IAAI;YACzF,mBAAmB,SAAS,CAAC,MAAM,EAAE,CACxC,CAAC;QACF,IAAI,CAAC;YACH,MAAM,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,wCAAwC,CAAC,CAAC;YAC3F,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,SAAS,EAAE,IAAI,CAAC,sBAAuB,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACvH,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,iDAAiD,WAAW,EAAE,CAAC,CAAC;YAC7F,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,MAAM,MAAM,GAAG,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACrF,OAAO,CAAC,KAAK,CACX,GAAG,YAAY,mDAAmD,WAAW,IAAI;gBAC/E,kBAAkB,IAAI,CAAC,KAAK,CAAC,SAAS,qBAAqB,SAAS,CAAC,MAAM,WAAW,MAAM,EAAE,CACjG,CAAC;YACF,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,6EAA6E;IAE7E;;;;;;;OAOG;IACH,KAAK,UAAU,YAAY,CAAC,GAAY;QACtC,MAAM,YAAY,GAAG,GAA4B,EAAE;YACjD,MAAM,SAAS,GAAG,YAAY,EAAE,CAAC;YACjC,QAAQ,SAAS,EAAE,CAAC;gBAClB,KAAK,iBAAiB;oBACpB,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,8CAA8C,WAAW,EAAE,CAAC,CAAC;oBACxF,OAAO,iBAAiB,EAAE,CAAC;gBAC7B,KAAK,OAAO;oBACV,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,oCAAoC,WAAW,EAAE,CAAC,CAAC;oBAC9E,OAAO,QAAQ,EAAE,CAAC;gBACpB,KAAK,gBAAgB;oBACnB,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,6CAA6C,WAAW,EAAE,CAAC,CAAC;oBACvF,OAAO,uBAAuB,EAAE,CAAC;gBACnC,KAAK,MAAM;oBACT,OAAO,SAAS,CAAC;gBACnB,OAAO,CAAC,CAAC,CAAC;oBACR,MAAM,UAAU,GAAU,SAAS,CAAC;oBACpC,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,0BAA0B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;gBACjF,CAAC;YACH,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;YACpC,kEAAkE;YAClE,+DAA+D;YAC/D,wEAAwE;YACxE,qEAAqE;YACrE,OAAO,UAAU,CAAC,YAAY,EAAE,IAAI,uBAAuB,EAAE,EAAE,GAAG,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnE,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,yEAAyE;YACzE,yEAAyE;YACzE,qEAAqE;YACrE,yCAAyC;YACzC,IAAI,GAAG,CAAC,KAAK,KAAK,cAAc,CAAC,gBAAgB,EAAE,CAAC;gBAClD,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,sDAAsD,WAAW,WAAW,SAAS,EAAE,CAAC,CAAC;gBACpH,OAAO,UAAU,CAAC,GAAG,EAAE,IAAI,gBAAgB,CAAC,aAAa,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC;YAC3F,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,GAAG,YAAY,kDAAkD,WAAW,WAAW,SAAS,EAAE,CAAC,CAAC;YAChH,OAAO,UAAU,CACf,EAAE,GAAG,uBAAuB,EAAE,EAAE,KAAK,EAAE,0BAA0B,SAAS,EAAE,EAAE,EAC9E,IAAI,gBAAgB,CAAC,aAAa,CAAC,oBAAoB,CAAC,sBAAsB,CAAC,CAChF,CAAC;QACJ,CAAC;QAED,6DAA6D;QAC7D,yEAAyE;QACzE,iCAAiC;QACjC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,sBAAsB,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;QACvG,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,sBAAsB,WAAW,MAAM,SAAS,KAAK,YAAY,EAAE,CAAC,CAAC;QAClG,OAAO,UAAU,CAAC,kBAAkB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,6EAA6E;IAE7E,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,cAAc,GAAmB;YACrC,KAAK;YACL,MAAM;YACN,MAAM;YACN,MAAM;YACN,eAAe;YACf,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,kBAAkB;YAC1B,SAAS;YACT,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;gBACnB,cAAc,GAAG,IAAI,CAAC;gBACtB,SAAS,EAAE,CAAC;YACd,CAAC;YACD,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC;SAC3E,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,kBAAkB,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;QACnH,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAClC,OAAO,GAAG,MAAM,gBAAgB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,aAAa,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;YAAS,CAAC;QACT,iBAAiB,CAAC,IAAI,EAAE,CAAC;QACzB,QAAQ,EAAE,IAAI,EAAE,CAAC;QACjB,kBAAkB,CAAC,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAChE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,qCAAqC;QACrC,IAAI,KAAK,CAAC,UAAU;YAAE,MAAM,oBAAoB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACnE,yEAAyE;QACzE,kEAAkE;QAClE,wEAAwE;QACxE,MAAM,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC;IACvC,CAAC;IAED,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,KAAK,CAAC;QACvB,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,KAAK,CAAC;QACtB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,OAAO,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,GAAG,YAAY,wBAAwB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/harness/stop-controller.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one way a turn is told to stop, and the runtime's record of why.
+ *
+ * The adapter contract gives an engine ONE signal (`TurnSink.stopSignal`) for
+ * every cause of stopping and forbids it to branch on the cause; the runtime
+ * keeps the cause here, as evidence its terminal table reads after the
+ * adapter settles `interrupted`. Four producers abort the signal: the stall
+ * watchdog, the usage accumulator's cost cap, the persist chokepoint's
+ * platform STOP, and Temporal's own cancellation (a pause, a worker
+ * shutdown, a heartbeat timeout — told apart later from the signal's reason,
+ * `shared/worker-shutdown.ts`). The first cause wins the abort; every cause
+ * is recorded, because the table's precedence (stall over cost cap over
+ * cancellation over platform stop) is decided at settlement, not at abort.
+ *
+ * Nothing here is engine-specific and nothing here persists; the Cursor
+ * orchestrator kept the same facts as flags on its stream state
+ * (`turn-stream.ts` `TurnStreamState`, before S2 M3 moved them out).
+ */
+import type { StallTimeoutError } from "../shared/stall-watchdog.js";
+/** Why the runtime stopped the turn. */
+export type StopCause = {
+    readonly kind: "stall";
+    readonly error: StallTimeoutError;
+} | {
+    readonly kind: "cost-cap";
+} | {
+    readonly kind: "platform-stop";
+} | {
+    readonly kind: "cancellation";
+};
+/** What the terminal table reads. Each field is set by the first cause of its kind and never cleared. */
+export interface StopEvidence {
+    readonly stall: StallTimeoutError | undefined;
+    readonly costCapExceeded: boolean;
+    readonly platformStop: boolean;
+    /** Temporal delivered a cancellation; its reason is on the cancellation signal itself. */
+    readonly cancellation: boolean;
+}
+export declare class StopController {
+    private readonly controller;
+    private stall;
+    private costCapExceeded;
+    private platformStop;
+    private cancellation;
+    /** The adapter's `stopSignal`. Its `reason` is the first cause's kind, a diagnostic only. */
+    get signal(): AbortSignal;
+    get evidence(): StopEvidence;
+    /** Record a cause and abort the signal (idempotent per cause; the signal aborts once). */
+    stop(cause: StopCause): void;
+}