@stigmer/runner 3.1.2 → 3.1.4

package/dist/activities/execute-cursor/turn-boundary.js

@@ -0,0 +1,163 @@
+/**
+ * The Cursor harness's turn boundary — the single post-run pipeline that turns
+ * a finished agent run into the durable review surfaces:
+ *
+ *  1. read the denial ledger the preToolUse hook appended this turn;
+ *  2. derive the approved-command provenance (DD-28 auto-keep facts);
+ *  3. capture the turn's net file change set to the file_review ledger
+ *     (CANDIDATE_CAPTURED) and stamp the flowed edit rows;
+ *  4. reconcile denied tool calls to WAITING_APPROVAL gate rows and redact the
+ *     model's provisional post-denial narration.
+ *
+ * Extracted from the activity entry point (index.ts Phase 12) so it is directly
+ * unit-testable AND re-enterable: the poisoned-handle / transport-timeout
+ * recoveries re-run the agent with a fresh handle AFTER the primary boundary
+ * already ran, so their edits must flow through this exact pipeline again or
+ * they silently escape review (production case aex_01kws27q1e2esvkqjpvectttxf,
+ * where a Build-from-plan retry created a file with no review gate).
+ *
+ * Re-entry is safe by construction: a retry is only reachable when the primary
+ * boundary captured nothing (a captured change pauses the turn before
+ * run.wait() is ever consulted), `stampFlowedFileEditRows` skips already-stamped
+ * rows, and the denial ledger is per-turn append-only.
+ *
+ * The caller owns everything around the boundary: the stream epilogue
+ * (accumulator/enricher finalize), the WAITING_FOR_APPROVAL phase flip +
+ * persist, and the terminal result mapping.
+ */
+import { collectSubAgentToolCallIds } from "../../shared/tool-row.js";
+import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
+import { primaryToken, readDenialLedger } from "./approval-state.js";
+import { deriveTurnCommandProvenance } from "./command-provenance.js";
+import { captureTurnToLedger } from "./capture-flow.js";
+import { clearProvisionalPostDenialNarration, reconcileDeniedToolCalls, } from "./message-translator.js";
+// How long the boundary waits for the first-denial-stop's run.cancel() to
+// settle before reading the final denial ledger and capturing the turn's tree.
+// Long enough for the SDK's normal teardown, short enough that a wedged cancel
+// cannot noticeably delay the approval pause the user is already waiting on.
+const FIRST_DENIAL_CANCEL_TIMEOUT_MS = 5_000;
+/**
+ * Run the turn boundary: author this turn's change set to the file_review
+ * ledger and overlay the hook's denials as approval gates. Mutates
+ * `opts.status` in place and reports whether the turn must pause.
+ *
+ * The hook records each denial to the ledger; we mark the corresponding tool
+ * calls WAITING_APPROVAL. The backend projects pending_approvals from that
+ * tool-call status (PendingApprovalComputer), so — exactly like the native
+ * harness — the approval surface is driven entirely by tool-call status. We
+ * deliberately do NOT set status.pendingApprovals here: any value would be
+ * discarded by the backend's recompute on the next updateStatus.
+ */
+export async function runTurnBoundary(opts) {
+    const { status, executionId, changeSetId, hitlDir, captureMode, baselineTree, primaryWorkspaceDir, gitWorkspace, turnStartMessageIndex, approvalGrants, globalBypass, seededSubAgents, artifactStorage, mergedPolicies, denialCancelSettled, } = opts;
+    // The timebox keeps a wedged cancel from hanging the pause; the reconcile
+    // trims below remain the backstop for that degraded case.
+    if (denialCancelSettled) {
+        await Promise.race([
+            denialCancelSettled,
+            new Promise((resolve) => {
+                const timer = setTimeout(resolve, FIRST_DENIAL_CANCEL_TIMEOUT_MS);
+                timer.unref();
+            }),
+        ]);
+    }
+    const deniedLedger = await readDenialLedger(hitlDir ?? "");
+    // Capture mode: author the net change set to the file_review ledger as the
+    // CANDIDATE_CAPTURED event (projected server-side to a file_change_set
+    // AWAITING_REVIEW — the single review surface). The runner-owned gate files
+    // are excluded from the capture. The agent's edits are LEFT applied on the
+    // working tree (Cursor parity — the user reviews the real change; nothing is
+    // committed and the next turn is blocked until approval, and a reject snaps
+    // each file back on resume). Runs BEFORE the denial reconcile so a denied
+    // (gitignored) write stays on the deny-gate path while every flowed edit is
+    // captured to the ledger.
+    let capturedChangeCount = 0;
+    if (captureMode && baselineTree !== undefined && primaryWorkspaceDir) {
+        const deniedTokens = new Set(deniedLedger.map((e) => e.token));
+        // Approved-command turn facts (DD-28): when every mutation-capable call
+        // this turn was a consented shell command, attach the provenance so the
+        // backend can verify the cited consent rows and auto-keep the set instead
+        // of arming a second gate. Fail-closed: any non-qualifying turn attaches
+        // nothing and reviews manually exactly as before.
+        const commandProvenance = deriveTurnCommandProvenance({
+            messages: status.messages,
+            turnStartIndex: turnStartMessageIndex,
+            deniedTokens,
+            grantTokenToConsentId: new Map((approvalGrants ?? []).map((g) => [
+                primaryToken(g.key, g.salient, g.contentDigest),
+                g.sourceToolCallId,
+            ])),
+            globalBypass,
+        });
+        if (commandProvenance) {
+            console.log(`ExecuteCursor capture: turn qualifies for approved-command auto-keep ` +
+                `(consent rows: ${commandProvenance.consentToolCallIds.join(",") || "(auto_approve_all)"}); ` +
+                `attaching provenance to candidate (execution=${executionId})`);
+        }
+        const captured = await captureTurnToLedger({
+            status,
+            gitRoot: primaryWorkspaceDir,
+            executionId,
+            changeSetId,
+            baselineTree,
+            messages: status.messages,
+            deniedTokens,
+            commandProvenance,
+            // Scope sub-agent row stamping to this turn: the seeded prior sub-agents
+            // (cloned in on resume) are the "before this turn" rows to skip.
+            priorSubAgentToolCallIds: collectSubAgentToolCallIds(seededSubAgents),
+            // The CAS half: read the sidecar the hook staged this turn and compose it
+            // into the change set. hitlDir + storage are present when captureIgnored
+            // was on (a git tree's gitignored writes, or ALL writes in a non-git
+            // workspace). In a git tree this composes with the git diff (HYBRID); in a
+            // non-git workspace it IS the whole change set (CAS-only).
+            hitlDir,
+            storage: artifactStorage,
+            gitWorkspace,
+        });
+        capturedChangeCount = captured.length;
+        if (capturedChangeCount > 0) {
+            console.log(`ExecuteCursor capture: ${capturedChangeCount} file change(s) authored to the ` +
+                `file_review ledger (change_set=${changeSetId}), working tree left applied ` +
+                `for review (execution=${executionId})`);
+        }
+    }
+    // The gate reads each denied file's pre-edit `before` from the workspace the
+    // runner is co-located with (local FS for OSS; the sandbox in cloud), so a
+    // whole-file rewrite gate renders a true before/after diff. The tool was
+    // DENIED, so disk still holds the old content. User files are never platform
+    // paths, so no platformDir routing is needed here.
+    const gateWorkspaceBackend = new LocalWorkspaceBackend(primaryWorkspaceDir);
+    const deniedToolCalls = await reconcileDeniedToolCalls(status.messages, deniedLedger, mergedPolicies, gateWorkspaceBackend);
+    // Observability: a synthesized placeholder (id `approval:*`) means a denial
+    // correlated to NO streamed tool call in either the exact or the normalized
+    // pass. After the normalized-path fallback this should be ~0; a non-zero rate
+    // is the early-warning signal of a NEW identity drift (the gate would then
+    // show "No preview available" with no diff). Logged, not thrown — the
+    // synthesized gate still safely surfaces the approval.
+    const synthesizedGateCount = deniedToolCalls.filter((tc) => tc.id.startsWith("approval:")).length;
+    if (synthesizedGateCount > 0) {
+        console.warn(`ExecuteCursor reconcile synthesized ${synthesizedGateCount} placeholder gate(s) ` +
+            `with no correlated stream call (execution=${executionId}); ` +
+            `possible hook/stream identity drift — gate(s) will lack a diff`);
+    }
+    if (deniedToolCalls.length > 0) {
+        // Deterministic clean-pause: a turn that pauses for approval must read as
+        // the same shape the native harness produces — pre-tool text + the gated
+        // tool calls — never the model's provisional reaction to Cursor's deny
+        // (e.g. "blocked by a hook; enable it in your Cursor settings"). We blank
+        // that reaction in place (keeping the message count, so the finalize stays
+        // append-only) rather than removing it. See
+        // clearProvisionalPostDenialNarration for the full rationale.
+        const redactedNarration = clearProvisionalPostDenialNarration(status.messages, deniedToolCalls);
+        if (redactedNarration.length > 0) {
+            console.log(`ExecuteCursor redacted ${redactedNarration.length} provisional post-denial narration message(s) before pausing for approval`);
+        }
+    }
+    return {
+        waiting: deniedToolCalls.length > 0 || capturedChangeCount > 0,
+        capturedChangeCount,
+        deniedToolCallCount: deniedToolCalls.length,
+    };
+}
+//# sourceMappingURL=turn-boundary.js.map

package/dist/activities/execute-cursor/turn-boundary.js.map

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

package/dist/activities/execute-cursor/turn-stream.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The Cursor harness's stream phase — the single per-event consumption loop that
+ * turns a live Cursor SDK run into the streamed transcript, mid-run progress, and
+ * the flags that decide how the turn ends.
+ *
+ * Extracted from the activity entry point (index.ts) so that BOTH the primary
+ * turn and the two recovery retries (poisoned-handle / transport-timeout) drive
+ * the exact same code. The retries previously re-implemented a stripped "bare"
+ * loop that dropped live persist, DD-32/DD-33 mid-run progress, sub-agent
+ * tracking, the first-denial early stop, and correct pause/stall handling — so a
+ * retry froze the UI and mis-handled a mid-retry pause. One loop removes that
+ * drift by construction.
+ *
+ * This mirrors the deep-agent harness's `streamExecution` seam
+ * (execute-deep-agent/streaming.ts): injected `heartbeat`/`isCancelled` so it
+ * runs without Temporal, a structural `StreamableRun` so it runs without the live
+ * SDK, and a result (the terminal reason) instead of internal terminal mapping.
+ * The one deliberate difference: this consumer REPORTS why the stream ended and
+ * leaves the terminal MAPPING to the activity, because Cursor's mapping is
+ * entangled with worker-shutdown-vs-pause disambiguation, the turn boundary,
+ * structured output, and recovery retries — all of which must stay in index.ts.
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { SDKMessage, InteractionUpdate } from "@cursor/sdk";
+import { StallTimeoutError, type StallWatchdog } from "../../shared/stall-watchdog.js";
+import { type ProgressCaptureState, type ProgressSubstrate } from "../../shared/filereview/progress.js";
+import type { MessageAccumulator } from "./message-translator.js";
+import type { DeltaEnricher } from "./delta-enricher.js";
+import type { TodoTracker } from "./todo-tracker.js";
+import type { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
+import type { UsageAccumulator } from "./usage-accumulator.js";
+import type { createCursorEventRecorder } from "./cursor-event-recorder.js";
+/**
+ * The subset of the Cursor SDK `Run` the stream phase consumes. Kept structural
+ * so the loop is unit-testable with a mock run — no live SDK, no Temporal.
+ */
+export interface StreamableRun {
+    stream(): AsyncIterable<SDKMessage>;
+    supports?(feature: string): boolean;
+    cancel(): Promise<void>;
+}
+export type CursorTurnEventRecorder = ReturnType<typeof createCursorEventRecorder>;
+/**
+ * Why the turn's stream ended. The activity maps each reason to a terminal
+ * outcome (see resolvePreBoundaryTerminal in index.ts): `completed` and
+ * `first-denial` proceed to the turn boundary; the rest are pre-boundary
+ * terminals that return or throw.
+ */
+export type TurnStreamReason = "completed" | "paused" | "stalled" | "first-denial" | "platform-stop";
+/**
+ * Single owner for every flag the turn's stream produces. Before this, these
+ * eleven fields lived as scattered `let`s co-written by FOUR concurrent
+ * producers — the SDK `onDelta`, the fs denial-watcher, the stall-watchdog, and
+ * the loop — the classic "who writes this field?" hazard. Consolidating them into
+ * one object (created once per turn, shared by every producer, the epilogue, and
+ * the outer catch/finally) makes ownership explicit and lets the primary turn and
+ * both recovery retries drive the identical stream code.
+ *
+ * Field ownership is annotated per field: exactly one primary writer, plus any
+ * documented producer/consumer handshakes.
+ */
+export interface TurnStreamState {
+    /** Written by: onDelta (heartbeat cancel) + the loop's cancellation check. Read by: the loop, epilogue, outer catch. */
+    pauseDetected: boolean;
+    /** Written by: the stall-watchdog callback. Read by: the loop + epilogue. */
+    stallDetected: boolean;
+    stallError: StallTimeoutError | undefined;
+    /** Written by: the loop (on the first ledger entry). Read by: the loop, epilogue, settleRetryTurn. */
+    firstDenialDetected: boolean;
+    /** Written by: the fs denial-watcher (→ true) + the loop (→ false after a read). Read by: the loop. */
+    denialLedgerDirty: boolean;
+    /** Written by: the loop (the first-denial run.cancel()). Read by: the turn boundary. */
+    denialCancelSettled: Promise<void> | undefined;
+    /** Written by: the loop (a platform STOP signal from persist). Read by: the loop + epilogue. */
+    platformStopSignaled: boolean;
+    /** Written by: the loop (a stream ERROR status event) + the retry setup (reset). Read by: error classification. */
+    streamErrorMessage: string | undefined;
+    /** Written by: the loop (each tool_call). Read by: the stall-watchdog (message enrichment). */
+    lastToolName: string | undefined;
+    /** Written by: the loop. Read by: the event recorder, the persist cadence, and logs. */
+    eventCount: number;
+    /** Written + read by: onDelta (log the first turn's context attribution exactly once). */
+    firstTurnAttributionLogged: boolean;
+    /** The stall watchdog for the CURRENT stream, armed by consumeCursorTurnStream; held so onDelta can reset it and the activity's finally can stop it. */
+    stallWatchdog: StallWatchdog | undefined;
+}
+export declare function newTurnStreamState(): TurnStreamState;
+/**
+ * The subset of collaborators the shared onDelta needs. Broken out from
+ * CursorTurnStreamDeps because the primary send happens BEFORE the accumulator
+ * exists — onDelta only touches usage, the enricher, the heartbeat, and state.
+ */
+export interface TurnOnDeltaDeps {
+    readonly usageAccumulator: UsageAccumulator;
+    readonly deltaEnricher: DeltaEnricher;
+    /** Temporal heartbeat. Injected so the callback is testable without Temporal. */
+    readonly heartbeat: () => void;
+    readonly promptEstimatedTokens: number;
+    readonly executionId: string;
+    readonly state: TurnStreamState;
+}
+export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
+    readonly status: AgentExecutionStatus;
+    readonly accumulator: MessageAccumulator;
+    readonly todoTracker: TodoTracker;
+    readonly eventRecorder: CursorTurnEventRecorder | undefined;
+    readonly scheduler: StreamingUpdateScheduler;
+    readonly progressSubstrate: ProgressSubstrate | undefined;
+    readonly progressState: ProgressCaptureState;
+    readonly changeSetId: string;
+    /** Session HITL dir holding the denial ledger; undefined → no gate installed → no first-denial stop. */
+    readonly hitlDir: string | undefined;
+    readonly stallTimeoutMs: number;
+    /** The single size-bounded persist chokepoint. Returns the platform control signal. */
+    readonly persist: (status: AgentExecutionStatus) => Promise<ExecutionControlSignal>;
+    /** Temporal cancellation check. Injected so the loop is testable without Temporal. */
+    readonly isCancelled: () => boolean;
+}
+/**
+ * Build the shared onDelta callback. The Cursor SDK's fine-grained delta channel
+ * carries token usage, live shell output, and precise tool-call timings; it also
+ * fires far more often than discrete stream events, so it is where the stall
+ * timer is reset during a long model generation. A heartbeat CancelledFailure
+ * here flags the pause so the loop and epilogue treat it as a user pause (the
+ * bare retry loops swallowed this — the cause of the mid-retry mislabel).
+ */
+export declare function makeCursorTurnOnDelta(deps: TurnOnDeltaDeps): (event: {
+    update: InteractionUpdate;
+}) => void;
+/**
+ * Consume a Cursor SDK run to completion (or to a clean early stop), driving the
+ * transcript, todos, sub-agent tracking, live persist, and DD-32/DD-33 mid-run
+ * progress, and reporting WHY the stream ended.
+ *
+ * Arms + stops its own stall watchdog (stored on `state.stallWatchdog` so the
+ * shared onDelta can reset it and the activity's finally can stop it as a
+ * backstop). Mutates `deps.status` + `deps.state` in place. The caller owns the
+ * post-stream finalize and the terminal mapping.
+ */
+export declare function consumeCursorTurnStream(run: StreamableRun, deps: CursorTurnStreamDeps): Promise<TurnStreamReason>;

package/dist/activities/execute-cursor/turn-stream.js

@@ -0,0 +1,249 @@
+/**
+ * The Cursor harness's stream phase — the single per-event consumption loop that
+ * turns a live Cursor SDK run into the streamed transcript, mid-run progress, and
+ * the flags that decide how the turn ends.
+ *
+ * Extracted from the activity entry point (index.ts) so that BOTH the primary
+ * turn and the two recovery retries (poisoned-handle / transport-timeout) drive
+ * the exact same code. The retries previously re-implemented a stripped "bare"
+ * loop that dropped live persist, DD-32/DD-33 mid-run progress, sub-agent
+ * tracking, the first-denial early stop, and correct pause/stall handling — so a
+ * retry froze the UI and mis-handled a mid-retry pause. One loop removes that
+ * drift by construction.
+ *
+ * This mirrors the deep-agent harness's `streamExecution` seam
+ * (execute-deep-agent/streaming.ts): injected `heartbeat`/`isCancelled` so it
+ * runs without Temporal, a structural `StreamableRun` so it runs without the live
+ * SDK, and a result (the terminal reason) instead of internal terminal mapping.
+ * The one deliberate difference: this consumer REPORTS why the stream ended and
+ * leaves the terminal MAPPING to the activity, because Cursor's mapping is
+ * entangled with worker-shutdown-vs-pause disambiguation, the turn boundary,
+ * structured output, and recovery retries — all of which must stay in index.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+import { CancelledFailure } from "@temporalio/activity";
+import { ExecutionControlSignal } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import { startStallWatchdog, StallTimeoutError, } from "../../shared/stall-watchdog.js";
+import { shouldPersistStreamingStatus } from "./persist-decision.js";
+import { readDenialLedger } from "./approval-state.js";
+import { captureFileChangeProgress, } from "../../shared/filereview/progress.js";
+export function newTurnStreamState() {
+    return {
+        pauseDetected: false,
+        stallDetected: false,
+        stallError: undefined,
+        firstDenialDetected: false,
+        denialLedgerDirty: false,
+        denialCancelSettled: undefined,
+        platformStopSignaled: false,
+        streamErrorMessage: undefined,
+        lastToolName: undefined,
+        eventCount: 0,
+        firstTurnAttributionLogged: false,
+        stallWatchdog: undefined,
+    };
+}
+/**
+ * Build the shared onDelta callback. The Cursor SDK's fine-grained delta channel
+ * carries token usage, live shell output, and precise tool-call timings; it also
+ * fires far more often than discrete stream events, so it is where the stall
+ * timer is reset during a long model generation. A heartbeat CancelledFailure
+ * here flags the pause so the loop and epilogue treat it as a user pause (the
+ * bare retry loops swallowed this — the cause of the mid-retry mislabel).
+ */
+export function makeCursorTurnOnDelta(deps) {
+    const { usageAccumulator, deltaEnricher, heartbeat, promptEstimatedTokens, executionId, state } = deps;
+    return ({ update }) => {
+        // Reset the stall timer on the delta channel too: a long model generation
+        // emits token deltas but few discrete stream events, so resetting only in the
+        // stream loop would false-positive a stall.
+        state.stallWatchdog?.recordActivity();
+        if (update.type === "turn-ended" && update.usage) {
+            usageAccumulator.addTurn(update.usage);
+            if (!state.firstTurnAttributionLogged) {
+                state.firstTurnAttributionLogged = true;
+                const sdkInputTokens = update.usage.inputTokens ?? 0;
+                const cursorOverhead = Math.max(0, sdkInputTokens - promptEstimatedTokens);
+                console.log(`ExecuteCursor context attribution (first turn): execution=${executionId}, ` +
+                    `sdkInputTokens=${sdkInputTokens}, stigmerPreamble=${promptEstimatedTokens}, ` +
+                    `cursorOverhead=${cursorOverhead} (estimated)`);
+            }
+        }
+        deltaEnricher.processDelta(update);
+        try {
+            heartbeat();
+        }
+        catch (hbErr) {
+            if (hbErr instanceof CancelledFailure) {
+                state.pauseDetected = true;
+                return;
+            }
+            throw hbErr;
+        }
+    };
+}
+/**
+ * Consume a Cursor SDK run to completion (or to a clean early stop), driving the
+ * transcript, todos, sub-agent tracking, live persist, and DD-32/DD-33 mid-run
+ * progress, and reporting WHY the stream ended.
+ *
+ * Arms + stops its own stall watchdog (stored on `state.stallWatchdog` so the
+ * shared onDelta can reset it and the activity's finally can stop it as a
+ * backstop). Mutates `deps.status` + `deps.state` in place. The caller owns the
+ * post-stream finalize and the terminal mapping.
+ */
+export async function consumeCursorTurnStream(run, deps) {
+    const { status, accumulator, todoTracker, deltaEnricher, eventRecorder, scheduler, usageAccumulator, progressSubstrate, progressState, changeSetId, hitlDir, executionId, stallTimeoutMs, persist, heartbeat, isCancelled, state, } = deps;
+    // Arm the stall watchdog now that the run exists. The activity's periodic
+    // heartbeat proves the process is alive, not that the agent is progressing: if
+    // the stream wedges (a tool call or model connection that never returns), no
+    // event/delta arrives and the turn would hang forever. On stall we end the run
+    // cleanly via the SDK's run.cancel() (guarded by supports("cancel")), which
+    // unblocks the for-await; the caller then reports EXECUTION_FAILED with a
+    // recognizable, actionable message.
+    state.stallWatchdog = startStallWatchdog(stallTimeoutMs, (idleMs) => {
+        state.stallDetected = true;
+        state.stallError = new StallTimeoutError(idleMs, state.lastToolName ? `last tool: ${state.lastToolName}` : undefined);
+        console.warn(`ExecuteCursor stall detected: execution=${executionId}, idleMs=${idleMs}, lastTool=${state.lastToolName ?? "none"}`);
+        if (run.supports?.("cancel")) {
+            void run.cancel().catch((cancelErr) => {
+                console.warn(`ExecuteCursor run.cancel() after stall failed (non-fatal): execution=${executionId}, ` +
+                    `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`);
+            });
+        }
+    });
+    try {
+        for await (const event of run.stream()) {
+            if (state.pauseDetected || isCancelled()) {
+                state.pauseDetected = true;
+                break;
+            }
+            if (state.stallDetected)
+                break;
+            // Progress: reset the stall timer on every stream event.
+            state.stallWatchdog.recordActivity();
+            if (event.type === "tool_call" && typeof event.name === "string") {
+                state.lastToolName = event.name;
+            }
+            eventRecorder?.record(event, state.eventCount);
+            accumulator.processEvent(event);
+            todoTracker.processEvent(event);
+            if (event.type === "tool_call" && event.name === "task") {
+                accumulator.trackSubAgentExecution(event);
+            }
+            // First-denial stop (HITL clean pause). In CAPTURE mode this fires only for
+            // an IRREVERSIBLE tool the hook still gates (shell, MCP, or a gitignored
+            // write/delete) — file edits flow freely and are captured at the turn
+            // boundary, so they never enter the ledger. In the deny-gate FALLBACK
+            // (non-git workspace) it fires for every gated file edit too. Either way:
+            // the preToolUse hook appends to the denial ledger the instant it gates a
+            // tool — before Cursor surfaces the failure to the model — and the fs
+            // watcher flips denialLedgerDirty the moment that write lands. Confirming
+            // the flag with a read on the very next event (of ANY type — thinking
+            // deltas arrive within milliseconds) ends the turn before the model's
+            // reaction can persist: waiting for the next tool_call event let the full
+            // post-denial reaction (thinking, narration, a workaround shell) stream and
+            // persist live (production case aex_01kwj07f7g23c3wp9sn8496z5g). The
+            // tool_call-event read stays as the backstop for platforms where fs.watch
+            // is unreliable; the current event was already accumulated above, so the
+            // anchor's own row is always present for the turn-boundary gate overlay.
+            if (!state.firstDenialDetected && hitlDir && (state.denialLedgerDirty || event.type === "tool_call")) {
+                state.denialLedgerDirty = false;
+                const denials = await readDenialLedger(hitlDir);
+                if (denials.length > 0) {
+                    state.firstDenialDetected = true;
+                    console.log(`ExecuteCursor first denial detected (${denials.length} ledger ` +
+                        `entr${denials.length === 1 ? "y" : "ies"}); stopping turn to pause ` +
+                        `cleanly for approval: execution=${executionId}`);
+                    if (run.supports?.("cancel")) {
+                        // Kept (not fire-and-forget): awaited timeboxed by the turn boundary
+                        // so the ledger read and tree capture see a stopped agent.
+                        state.denialCancelSettled = run.cancel().then(() => { }, (cancelErr) => {
+                            console.warn(`ExecuteCursor run.cancel() after first denial failed (non-fatal): ` +
+                                `execution=${executionId}, ` +
+                                `error=${cancelErr instanceof Error ? cancelErr.message : cancelErr}`);
+                        });
+                    }
+                    break;
+                }
+            }
+            deltaEnricher.applyEnrichments(status.messages);
+            state.eventCount++;
+            if (event.type === "status") {
+                console.log(`ExecuteCursor stream status: execution=${executionId}, status=${JSON.stringify(event)}`);
+                const statusEvent = event;
+                if (statusEvent.status === "ERROR" && statusEvent.message) {
+                    state.streamErrorMessage = statusEvent.message;
+                }
+            }
+            const shouldPersist = shouldPersistStreamingStatus({
+                deltaEnricherDirty: deltaEnricher.isDirty,
+                todosDirty: todoTracker.isDirty,
+                contentDirty: accumulator.isDirty,
+            }, scheduler, state.eventCount);
+            if (usageAccumulator.hasTurns) {
+                status.streamingUsage = create(StreamingUsageSummarySchema, usageAccumulator.snapshot());
+            }
+            if (shouldPersist) {
+                // Sync sub-agent executions into status before every persist so the live
+                // UI reflects delegation (including the IN_PROGRESS state) while the
+                // parent is still running — matching the native harness.
+                status.subAgentExecutions = accumulator.subAgentExecutions;
+                // Mid-run live capture (DD-32 / DD-33): attach the "N files changed so
+                // far" snapshot onto status.file_change_progress, throttled internally by
+                // the floor. Never authoritative — the turn-boundary candidate remains
+                // the reviewed diff.
+                if (progressSubstrate) {
+                    await captureFileChangeProgress({
+                        status,
+                        changeSetId,
+                        substrate: progressSubstrate,
+                        state: progressState,
+                    });
+                }
+                const signal = await persist(status);
+                deltaEnricher.markPersisted();
+                todoTracker.markPersisted();
+                accumulator.markPersisted();
+                scheduler.markUpdateSent(state.eventCount);
+                heartbeat();
+                if (signal === ExecutionControlSignal.STOP) {
+                    state.platformStopSignaled = true;
+                    console.warn(`ExecuteCursor platform stop signal received: execution=${executionId}`);
+                }
+            }
+            if (state.platformStopSignaled) {
+                console.log(`ExecuteCursor stopping stream due to platform stop signal: execution=${executionId}`);
+                break;
+            }
+        }
+    }
+    catch (streamErr) {
+        // run.cancel() — from the stall watchdog or the first-denial stop — can make
+        // the stream iterator reject as it tears down; that is the expected teardown
+        // for both, so swallow it and fall through. Anything else is a genuine stream
+        // failure — rethrow it to the activity's error handler.
+        if (!state.stallDetected && !state.firstDenialDetected)
+            throw streamErr;
+        console.warn(`ExecuteCursor stream ended via cancel: execution=${executionId}, ` +
+            `stall=${state.stallDetected}, firstDenial=${state.firstDenialDetected}`);
+    }
+    finally {
+        state.stallWatchdog.stop();
+    }
+    // Report why the stream ended, in the same precedence the activity's epilogue
+    // applies: a stall (an EXECUTION_FAILED terminal) outranks everything; a
+    // platform stop and a first denial are distinct proceed/return outcomes; a
+    // pause is the fallback for a cancellation with no other cause.
+    if (state.stallDetected)
+        return "stalled";
+    if (state.platformStopSignaled)
+        return "platform-stop";
+    if (state.firstDenialDetected)
+        return "first-denial";
+    if (state.pauseDetected || isCancelled())
+        return "paused";
+    return "completed";
+}
+//# sourceMappingURL=turn-stream.js.map

package/dist/activities/execute-cursor/turn-stream.js.map

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

package/dist/activities/execute-deep-agent/command-provenance.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Approved-command turn provenance (DD-28) — the DEEP-AGENT (native) harness
+ * adapter over the shared qualification rule ({@link qualifyTurnCommandProvenance}).
+ *
+ * The deep-agent's consent model differs from Cursor's in exactly two ways, and
+ * this adapter is precisely those two differences:
+ *
+ * 1. IDENTITY turn scoping (not positional). Cursor scopes a turn by the message
+ *    index its stream started at. The deep-agent cannot: an approved command
+ *    executes IN PLACE at its seeded transcript position (it was proposed in a
+ *    prior segment, seeded into this segment, and updated to COMPLETED by
+ *    `StatusBuilder.findResumableSeededToolCall`). So "this turn's calls" are
+ *    those whose id is absent from a pre-stream {@link collectSettledToolCallIds}
+ *    snapshot, and "executed" is a COMPLETED status.
+ *
+ * 2. SAME-ROW direct consent (not a grant token). A gated deep-agent tool pauses
+ *    on a LangGraph interrupt; SubmitApproval writes `approval_action` onto that
+ *    same row, and the row keeps its id + `approval_action` when it executes on
+ *    resume. So the executed command IS its own consent row — cite its own id.
+ *    (The server's PreserveApprovalFields keeps that `approval_action` on the row
+ *    across the status write regardless of its new status, so the backend's
+ *    verification finds it.)
+ *
+ * A turn that delegated ANY sub-agent fails closed (DD-28 D1: "delegated zero
+ * sub-agents"). A sub-agent's writes fold into the parent turn's change set
+ * (DD-19) but are not attributable to a consented top-level command. The
+ * top-level `task` call (a SUBAGENT kind) already trips the shared rule's
+ * `!== SHELL` fail-closed; the explicit sub-agent-novelty guard below also covers
+ * the (currently-impossible under the replace-per-turn model) case of a sub-agent
+ * that mutates across a turn boundary without a fresh top-level `task` row.
+ *
+ * (Trust boundary + fail-closed contract: see the shared module.)
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+export interface DeepAgentCommandProvenanceInputs {
+    /** The status at capture time — top-level messages + sub-agent executions. */
+    readonly status: AgentExecutionStatus;
+    /**
+     * The top-level tool-call ids that had already SETTLED before this turn's
+     * stream (from {@link collectSettledToolCallIds}). A top-level call whose id is
+     * absent is this-turn's; the shared rule then keeps only the COMPLETED ones.
+     */
+    readonly priorSettledToolCallIds: ReadonlySet<string>;
+    /**
+     * The sub-agent tool-call ids that existed before this turn's stream (from
+     * {@link collectSubAgentToolCallIds}). Any growth means a sub-agent acted this
+     * turn → fail closed.
+     */
+    readonly priorSubAgentToolCallIds: ReadonlySet<string>;
+    /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+    readonly globalBypass: boolean;
+}
+/**
+ * Derive the {@link TurnCommandProvenance} for a deep-agent turn, or undefined
+ * when it does not qualify. Scopes this turn's top-level calls by id-novelty,
+ * resolves consent from the row's own server-authored `approval_action`, fails
+ * closed on any sub-agent activity, and delegates the DD-28 rule to
+ * {@link qualifyTurnCommandProvenance}.
+ */
+export declare function deriveTurnCommandProvenance(inputs: DeepAgentCommandProvenanceInputs): TurnCommandProvenance | undefined;