@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/harness/approval-decisions.js

@@ -0,0 +1,80 @@
+/**
+ * The runtime's one settler of a person's approval decision.
+ *
+ * A decision is read at the start of a reinvocation from the session's log
+ * (`approval-answers.ts`, the door), onto the root rows still
+ * WAITING_APPROVAL: the WAITING filter is what keeps a decided row from
+ * being re-gated on the NEXT reinvocation (its row is COMPLETED or SKIPPED
+ * by then) and what lets the adapter still describe the decision to its
+ * engine on THIS one (Cursor's reinvocation prompt names the refused actions
+ * in human terms). The rows are the runtime's working memory: the seed
+ * copies each call's answer from the log onto its row
+ * (`ToolCall.approval_action`, `approval-answers.ts` `copyAnswersOntoRows`),
+ * so the field this module settles by is the log's answer, never a server
+ * stamp:
+ *
+ *  - {@link terminalizeNonExecutingDecisions} settles SKIP and REJECT rows to
+ *    TOOL_CALL_SKIPPED (REJECT also carries `error: "Rejected by user"`),
+ *    root and sub-agent transcripts alike. The runtime calls it once,
+ *    immediately after `adapter.runTurn` returns and before any persist of
+ *    the outcome, for EVERY outcome: a decision that never runs the tool has
+ *    no engine event to flip its row, so the row would otherwise persist
+ *    WAITING on a completed execution. APPROVE and APPROVE_ALL are not
+ *    touched — the tool executes, and the adapter's own events settle it.
+ *
+ * Why after the adapter, not before: the door and the exact-apply filter on
+ * WAITING, so settling first would hide the decision from the reinvocation
+ * prompt and from the exact-apply. Why by decision and not by row status: the outcome
+ * of SKIP and REJECT is fully determined by the recorded decision, whatever
+ * transient status an engine left (a denial ToolMessage with no tool events,
+ * or a replay that never re-drove the gate), so the stamp is idempotent and
+ * checkpointer-independent by construction. REJECT and SKIP share SKIPPED as
+ * the terminal status (the tool did not run) and stay distinguishable by
+ * `approval_action` and by the answer in the session's log.
+ *
+ * This is the contract as of stigmer#197: REJECT denies the tool and the run
+ * CONTINUES; it never fails the execution. The native harness proved it
+ * (`hitl.ts` `reconcileNonExecutingDecisions`, moved here in #1096) and the
+ * conformance suite (`run-approval.conformance.test.ts`) is its
+ * arbiter for both harnesses.
+ */
+import { ApprovalAction, ToolCallStatus } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/** The row's error for a REJECT; byte-pinned by the native goldens (`reject.turn2.status.json`) and the conformance suite. */
+export const REJECTED_BY_USER_ERROR = "Rejected by user";
+/**
+ * Settle every SKIP and REJECT row to TOOL_CALL_SKIPPED, root and sub-agent
+ * transcripts, in place. Idempotent: a row already settled carries the same
+ * decision and re-settles identically. A REJECT row's `error` is set only
+ * when empty, so an engine's own denial text, if any, stands.
+ */
+export function terminalizeNonExecutingDecisions(rows) {
+    const settle = (messages) => {
+        for (const message of messages) {
+            for (const row of message.toolCalls) {
+                switch (row.approvalAction) {
+                    case ApprovalAction.SKIP:
+                        row.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+                        break;
+                    case ApprovalAction.REJECT:
+                        row.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+                        if (!row.error)
+                            row.error = REJECTED_BY_USER_ERROR;
+                        break;
+                    case ApprovalAction.UNSPECIFIED:
+                    case ApprovalAction.APPROVE:
+                    case ApprovalAction.APPROVE_ALL:
+                        break;
+                    default: {
+                        const exhaustive = row.approvalAction;
+                        throw new Error(`terminalizeNonExecutingDecisions: unknown approval action ${String(exhaustive)}`);
+                    }
+                }
+            }
+        }
+    };
+    settle(rows.messages);
+    for (const subAgent of rows.subAgentRuns) {
+        settle(subAgent.messages);
+    }
+}
+//# sourceMappingURL=approval-decisions.js.map

package/dist/harness/approval-decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-decisions.js","sourceRoot":"","sources":["../../src/harness/approval-decisions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kDAAkD,CAAC;AAElG,8HAA8H;AAC9H,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAAC,IAAiD;IAChG,MAAM,MAAM,GAAG,CAAC,QAAiC,EAAQ,EAAE;QACzD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpC,QAAQ,GAAG,CAAC,cAAc,EAAE,CAAC;oBAC3B,KAAK,cAAc,CAAC,IAAI;wBACtB,GAAG,CAAC,MAAM,GAAG,cAAc,CAAC,iBAAiB,CAAC;wBAC9C,MAAM;oBACR,KAAK,cAAc,CAAC,MAAM;wBACxB,GAAG,CAAC,MAAM,GAAG,cAAc,CAAC,iBAAiB,CAAC;wBAC9C,IAAI,CAAC,GAAG,CAAC,KAAK;4BAAE,GAAG,CAAC,KAAK,GAAG,sBAAsB,CAAC;wBACnD,MAAM;oBACR,KAAK,cAAc,CAAC,WAAW,CAAC;oBAChC,KAAK,cAAc,CAAC,OAAO,CAAC;oBAC5B,KAAK,cAAc,CAAC,WAAW;wBAC7B,MAAM;oBACR,OAAO,CAAC,CAAC,CAAC;wBACR,MAAM,UAAU,GAAU,GAAG,CAAC,cAAc,CAAC;wBAC7C,MAAM,IAAI,KAAK,CAAC,6DAA6D,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;oBACrG,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACzC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC"}

package/dist/harness/capabilities.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Harness capability flags — the facts about an engine the runtime branches
+ * on, declared once per adapter and read nowhere else.
+ *
+ * The runtime is written against the flags, not against harness names: a
+ * phase that must differ per engine asks "does this harness accept a system
+ * prompt?" rather than "is this Cursor?". That is what keeps a new harness a
+ * registry row and an SDK slice instead of a new branch in every phase.
+ * Every row of the matrix below is either a flag here or internal to one
+ * adapter; nothing in it needed a third kind of thing.
+ *
+ * One flag is declared for the matrix and read by no runtime phase today:
+ * `systemPrompt`. Its readers are the adapters' own prompt builders, by
+ * placement (the native builder renders a system prompt rebuilt every turn;
+ * the Cursor builder renders the session's first user message), and the
+ * shared prompt glue (`shared/prompt-sections.ts`) is written so that
+ * placement stays each adapter's. The runtime would branch on it only if it
+ * ever composed prompts itself — an open unification question (#1135), not a
+ * phase that exists.
+ *
+ * The matrix the contract was designed against (2026-09; Claude and Codex are
+ * the surveyed SDKs, not built harnesses):
+ *
+ * | Capability        | Native (LangGraph)          | Cursor (`@cursor/sdk`)                  | Claude (`@anthropic-ai/claude-agent-sdk`)     | Codex (`@openai/codex-sdk`)                    |
+ * |-------------------|-----------------------------|-----------------------------------------|-----------------------------------------------|------------------------------------------------|
+ * | `pausePrimitive`  | `interrupt` (checkpoint)    | `deny-and-retry` (hook, ledger, cancel) | `callback` (`canUseTool`, in-process)         | `none` (approvalPolicy only) → capture-only    |
+ * | `stateIdSource`   | `deterministic` (thread id) | `engine-minted` (agent id)              | either (caller-supplied or minted)            | `engine-minted` (thread id)                    |
+ * | `systemPrompt`    | yes                         | no (rides the first message)            | yes                                           | no (`AGENTS.md` or first message)              |
+ * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
+ * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
+ * | `runsHooks`       | yes (in the approval gate)  | yes (the gate's hook server)            | yes (its own hooks)                           | (surveyed later)                               |
+ * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, the gate's files excluded     | (surveyed later)                              | (surveyed later)                               |
+ * | `boundaryRewritesRow` | none                    | the boundary's reopened, hidden and refused rows | (surveyed later)                     | (surveyed later)                               |
+ *
+ * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
+ * metering is routed, how the cost cap is applied inside the engine, how a
+ * run is cancelled. Those differ per engine but the runtime never needs to
+ * know.
+ *
+ * Two flags matter to the contract kit directly: `pausePrimitive` (the kit
+ * proves the two real primitives are indistinguishable above the contract
+ * line — both end a turn `awaiting_approval` and both take the decisions on
+ * reinvocation) and `stateIdSource` (an `engine-minted` adapter must bind its
+ * id before its first persist; a `deterministic` one must never bind).
+ */
+import type { Harness } from "@stigmer/apis/ai/stigmer/agentic/session/v1/enum_pb";
+import type { VisionProfile } from "../shared/attachment-vision.js";
+import type { ToolCall } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/**
+ * How the engine can be made to stop before a gated side effect.
+ *
+ *  - `interrupt`: the engine checkpoints and stops at the gate (LangGraph
+ *    `interrupt`); the adapter resumes it with the decisions.
+ *  - `deny-and-retry`: an out-of-process hook denies the tool, the adapter
+ *    records the denial, cancels the run, and re-runs with grants on the next
+ *    invocation.
+ *  - `callback`: an in-process callback decides per tool. The intended shape
+ *    is the `interrupt` one seen from the runtime: the turn still ends
+ *    `awaiting_approval` and reinvokes, and the adapter answers the callback
+ *    with "deny, stop" and resumes with the decisions.
+ *  - `none`: the engine offers no gate. The intended shape is that the
+ *    runtime confines such a harness to capture-only work (a read-only
+ *    sandbox) so a gated action never reaches the engine.
+ *
+ * Two of the four are built and two are reserved. `interrupt` (native) and
+ * `deny-and-retry` (Cursor) each have a real adapter and the contract kit
+ * runs under both. `callback` and `none` come from the 2026-09 survey of the
+ * Claude and Codex SDKs: the type carries them so an adapter can declare
+ * them, but no adapter does, and the runtime reads `pausePrimitive` in one
+ * place only (`turn-context.ts` `regeneratesApprovedWrites`, which returns
+ * false for `none`). The capture-only confinement for `none` is design
+ * still to be done before the first gate-less harness lands.
+ */
+export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none";
+/**
+ * Who mints the engine's state id. `deterministic`: the runtime derives it
+ * from the session before the first turn (`EnsureThread`), so it is known
+ * before any engine exists. `engine-minted`: the engine issues it on first
+ * use and the adapter must hand it to the runtime at once
+ * (`TurnSink.bindHarnessState`) so a crash mid-turn still resumes.
+ */
+export type StateIdSource = "deterministic" | "engine-minted";
+/**
+ * The two facts the runtime's file-review capture and reconcile need from
+ * the harness and cannot know: the id the projection reads from the
+ * BASELINE payload (`shared/filereview/capture.ts`), and the
+ * workspace-relative paths the harness writes into the repo that a turn's
+ * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
+ * once per adapter, read by `harness/capture.ts` (the pin, the progress
+ * slice, the candidate) and `turn-context.ts` (the reconcile). First passed
+ * as an argument, then homed here as a capability (#1070); the capture joined
+ * the reconcile as a reader in #1096.
+ */
+export interface FileReviewIdentity {
+    readonly harnessId: string;
+    readonly excludePaths: readonly string[];
+    /**
+     * Workspace-relative paths the harness rewrites for the turn's duration
+     * only and restores before it returns: left out of the mid-run progress
+     * diff, which would show the harness's own rewrite, and never out of the
+     * baseline or the candidate, which see the file as its owner and the
+     * agent left it, so an agent's own edit to one is still reviewed.
+     */
+    readonly transientPaths?: readonly string[];
+}
+export interface HarnessCapabilities {
+    /**
+     * The engine, as an agent's `harness` names it: a subagent's own run
+     * defaults (its model) count only on the engine they were chosen for,
+     * and a model counts only when this engine's registry section lists it.
+     */
+    readonly harness: Harness.NATIVE | Harness.CURSOR;
+    readonly pausePrimitive: PausePrimitive;
+    readonly stateIdSource: StateIdSource;
+    /** The engine accepts a system prompt; otherwise instructions ride the first user message. */
+    readonly systemPrompt: boolean;
+    /** The engine runs delegated sub-agents from a definition map. */
+    readonly subAgents: boolean;
+    /** The engine can hide or deny every tool an agent's tool lists exclude; otherwise its approval hook refuses what it cannot hide. */
+    readonly toolRestriction: boolean;
+    /**
+     * The engine runs an agent's hooks around its tool calls. A turn whose
+     * agent has hooks is refused on an engine that does not, before anything
+     * is fetched: a hook that silently does not run is a policy that vanished.
+     */
+    readonly runsHooks: boolean;
+    /**
+     * The engine loads the turn's MCP tools itself and reads each one's
+     * destructive mark from what it loaded, building the approval default
+     * there. Otherwise the runtime lists each plugin server's tools at turn
+     * start (shared/mcp-tool-listing.ts) and builds the default for it.
+     */
+    readonly readsToolMarks: boolean;
+    /** Which image types the engine can display inline; the runtime degrades the rest before the turn. */
+    readonly visionProfile: VisionProfile;
+    /** How the harness's captured file changes are identified and what its own repo writes are excluded from a diff. */
+    readonly fileReview: FileReviewIdentity;
+    /**
+     * The rows the harness's turn boundary may still rewrite after the stream
+     * settled them (reopen as a gate, hide as a twin, settle as a refusal);
+     * absent when the boundary never rewrites a row. The session event emitter
+     * (`events/emitter.ts`) holds such a row, and everything after it in its
+     * thread, until the turn's terminal write, so the log never records a
+     * fact the boundary reverses. A predicate rather than a flag because only
+     * the adapter knows which rows its boundary touches.
+     */
+    readonly boundaryRewritesRow?: (row: ToolCall) => boolean;
+}

package/dist/harness/capabilities.js

@@ -0,0 +1,48 @@
+/**
+ * Harness capability flags — the facts about an engine the runtime branches
+ * on, declared once per adapter and read nowhere else.
+ *
+ * The runtime is written against the flags, not against harness names: a
+ * phase that must differ per engine asks "does this harness accept a system
+ * prompt?" rather than "is this Cursor?". That is what keeps a new harness a
+ * registry row and an SDK slice instead of a new branch in every phase.
+ * Every row of the matrix below is either a flag here or internal to one
+ * adapter; nothing in it needed a third kind of thing.
+ *
+ * One flag is declared for the matrix and read by no runtime phase today:
+ * `systemPrompt`. Its readers are the adapters' own prompt builders, by
+ * placement (the native builder renders a system prompt rebuilt every turn;
+ * the Cursor builder renders the session's first user message), and the
+ * shared prompt glue (`shared/prompt-sections.ts`) is written so that
+ * placement stays each adapter's. The runtime would branch on it only if it
+ * ever composed prompts itself — an open unification question (#1135), not a
+ * phase that exists.
+ *
+ * The matrix the contract was designed against (2026-09; Claude and Codex are
+ * the surveyed SDKs, not built harnesses):
+ *
+ * | Capability        | Native (LangGraph)          | Cursor (`@cursor/sdk`)                  | Claude (`@anthropic-ai/claude-agent-sdk`)     | Codex (`@openai/codex-sdk`)                    |
+ * |-------------------|-----------------------------|-----------------------------------------|-----------------------------------------------|------------------------------------------------|
+ * | `pausePrimitive`  | `interrupt` (checkpoint)    | `deny-and-retry` (hook, ledger, cancel) | `callback` (`canUseTool`, in-process)         | `none` (approvalPolicy only) → capture-only    |
+ * | `stateIdSource`   | `deterministic` (thread id) | `engine-minted` (agent id)              | either (caller-supplied or minted)            | `engine-minted` (thread id)                    |
+ * | `systemPrompt`    | yes                         | no (rides the first message)            | yes                                           | no (`AGENTS.md` or first message)              |
+ * | `subAgents`       | yes (compiled sub-graphs)   | yes (`agents` option)                   | yes (`AgentDefinition`)                       | no                                             |
+ * | `toolRestriction` | yes (tool list)             | no (the hook enforces)                  | yes (`disallowedTools`, `tools`)              | per-server config                              |
+ * | `runsHooks`       | yes (in the approval gate)  | yes (the gate's hook server)            | yes (its own hooks)                           | (surveyed later)                               |
+ * | `visionProfile`   | PNG, JPEG, WebP, GIF        | PNG, JPEG (transport re-sniffs)         | (surveyed later)                              | (surveyed later)                               |
+ * | `fileReview`      | `deep-agent`, no excludes   | `cursor`, the gate's files excluded     | (surveyed later)                              | (surveyed later)                               |
+ * | `boundaryRewritesRow` | none                    | the boundary's reopened, hidden and refused rows | (surveyed later)                     | (surveyed later)                               |
+ *
+ * Adapter-internal, deliberately NOT flags: how MCP servers are bound, how
+ * metering is routed, how the cost cap is applied inside the engine, how a
+ * run is cancelled. Those differ per engine but the runtime never needs to
+ * know.
+ *
+ * Two flags matter to the contract kit directly: `pausePrimitive` (the kit
+ * proves the two real primitives are indistinguishable above the contract
+ * line — both end a turn `awaiting_approval` and both take the decisions on
+ * reinvocation) and `stateIdSource` (an `engine-minted` adapter must bind its
+ * id before its first persist; a `deterministic` one must never bind).
+ */
+export {};
+//# sourceMappingURL=capabilities.js.map

package/dist/harness/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/harness/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG"}

package/dist/harness/capture.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The runtime's file-review capture — apply-then-review for every harness,
+ * written once: the baseline pinned before the engine runs, the mid-run
+ * progress the chokepoint refreshes on every write, the candidate captured
+ * after the engine's turn, the approved-command provenance, and the flowed
+ * transcript rows stamped with the change set.
+ *
+ * Capture runs only when the turn's review is on (the session's
+ * `file_review`, or a eval-run try) and the workspace has a substrate
+ * (`TurnWorkspace.captureMode`). It never holds the turn: the edits are
+ * applied, the turn takes its own terminal (`run-turn.ts`), and the change
+ * set is offered for Keep or Undo after it, on the run's file record
+ * (`RunStatus.file_changes`, read from the turn's ledger at every persist)
+ * and as the session's `stigmer.file_review.changes` (`events/emitter.ts`).
+ *
+ * ONE CAPTURE, ONE MOMENT, ONE OWNER
+ * ----------------------------------
+ * A turn's reviewable change is a property of the TREE, not of the engine:
+ * whatever sits on the working tree when the engine's turn is over is what
+ * the user reviews, whoever wrote it — the engine, a sub-agent, a recovery
+ * retry, a stdio MCP server the engine spawned. So the runtime pins the
+ * baseline as its LAST act before `adapter.runTurn` (after its own writes
+ * into the tree — the owed undos, the skill and attachment mounts — so they
+ * cancel out of the diff) and captures ONCE after `runTurn` returns, over
+ * the whole turn. Anything written into the tree after the pin is the
+ * turn's change. An adapter needs neither the baseline nor the change-set
+ * id and never learns whether a change was captured; the one fact it holds
+ * that the runtime cannot read is what its engine observed touching
+ * CAS-owned paths (`TurnSink.bindCasObservations`).
+ *
+ * Until #1096 both adapters carried this whole act (Cursor in its
+ * `turn-boundary.ts` between the stream and `run.wait()`, the deep-agent in
+ * its `turn-settle.ts`), each with its own evidence source and its own
+ * scoping rules for the provenance and the stamp. The two rules here are the
+ * one reading both engines already produce:
+ *
+ *  - PROVENANCE (`shared/filereview/command-provenance.ts` is the
+ *    rule; this is its two inputs). "This turn's commands" are the top-level
+ *    rows whose id had not SETTLED before the engine ran — never a message
+ *    position, because on BOTH engines an approved command executes on the
+ *    row the runtime seeded for it (the deep-agent's builder and Cursor's
+ *    translator both reconcile the re-attempt onto the seeded WAITING row),
+ *    at its prior position; a positional scope misses it (Cursor's
+ *    did, so its auto-keep never qualified a gated-then-approved command).
+ *    "Executed" is a COMPLETED row. "Consented" is the row's own
+ *    `approval_action`, the person's answer the seed copied from the
+ *    session's log (`approval-answers.ts`) — the seeded row keeps its id and
+ *    its verdict when it executes on resume, so the executed command IS its
+ *    consent row. Any sub-agent activity fails closed.
+ *  - THE STAMP (`shared/tool-row.ts` `stampFlowedFileEditRows`). A write or
+ *    delete row created this turn that reached COMPLETED flowed onto the
+ *    tree and is badged with the change set; a WAITING (denied, gated) or
+ *    FAILED row did not and is not. The row's own status is the evidence,
+ *    not a ledger of denial tokens.
+ *
+ * WHAT IS NOT HERE
+ * ----------------
+ * The substrate and the ledger authoring (`shared/filereview/capture.ts`,
+ * `cas-touched.ts`, `progress.ts`); the undo after the turn, done at every
+ * turn's start (`owed-undos.ts`); the log's `changes` event
+ * (`events/emitter.ts`).
+ *
+ * TWO GAPS THIS MODULE DOES NOT CLOSE (recorded as #1115)
+ * ----------------------------------------------------------------------
+ * A turn that ends `interrupted` is not captured (a stop fired; the tree may
+ * be mid-edit). So a platform STOP returns COMPLETED with unreviewed edits
+ * on the tree, and a pause or worker shutdown reinvokes the same turn, whose
+ * new pin absorbs the pre-pause edits into its baseline and authors a second
+ * BASELINE for the same change set. Both predate the lift on both harnesses.
+ */
+import type { TurnCommandProvenance } from "@stigmer/apis/ai/stigmer/agentic/run/v1/filereview_pb";
+import type { ArtifactStorage } from "../shared/artifact-storage.js";
+import { type CasTouchedReader } from "../shared/filereview/cas-touched.js";
+import { type ProgressCaptureState, type ProgressSubstrate } from "../shared/filereview/progress.js";
+import type { FileReviewIdentity } from "./capabilities.js";
+import type { TurnWorkspace } from "./types.js";
+import type { TurnRows } from "../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+/** The mid-run progress the chokepoint refreshes on every write: the substrate and the floor it throttles by. */
+export interface TurnProgress {
+    readonly changeSetId: string;
+    readonly substrate: ProgressSubstrate;
+    readonly state: ProgressCaptureState;
+}
+/**
+ * One turn's capture as the runtime holds it between the pin and the
+ * boundary — a `runTurn` closure value beside the usage accumulator and the
+ * watchdog, on neither `TurnInput` (the adapter needs none of it) nor the
+ * frame (nothing here is a resource to release). Absent outside capture
+ * mode.
+ */
+export interface TurnCapture {
+    readonly changeSetId: string;
+    /** The pre-turn tree on a git work tree; `""` on a non-git one (the CAS manifest is the baseline there). */
+    readonly baselineTree: string;
+    readonly progress: TurnProgress;
+    /** Top-level rows already settled before the engine ran: the complement is "this turn's" (the provenance scope). */
+    readonly priorSettledToolCallIds: ReadonlySet<string>;
+    /** Sub-agent rows present before the engine ran: the stamp's scope, and any growth fails provenance closed. */
+    readonly priorSubAgentToolCallIds: ReadonlySet<string>;
+    /**
+     * What the engine observed touching CAS-owned paths, once the adapter has
+     * bound it (`TurnSink.bindCasObservations`); read at each progress capture
+     * and at the boundary. Unbound reads as nothing observed: git-only capture.
+     */
+    casObservations: CasTouchedReader | undefined;
+}
+/**
+ * Turn start, in capture mode: snapshot the pre-turn ids, pin the pre-turn
+ * tree behind the baseline ref and author BASELINE_CAPTURED under the
+ * harness's identity (the event rides the next persist), and build the
+ * progress substrate for this workspace shape — the git slice over the
+ * baseline and the harness's excluded paths, the CAS slice over whatever
+ * observations the adapter later binds (a delegating reader, since the bind
+ * happens inside `runTurn`), hybrid when both apply. The CAS slice exists
+ * only when artifact storage does: without it a gitignored write is
+ * deny-gated by the harness (`captureIgnored`), never captured, and the
+ * ledger could not store its blobs anyway.
+ *
+ * Returns `undefined` outside capture mode: nothing to pin, nothing to
+ * capture. With review off file writes flow uncaptured; with review on and
+ * no substrate the classic deny-gate governs them.
+ */
+export declare function pinCaptureBaseline(args: {
+    readonly rows: TurnRows;
+    readonly executionId: string;
+    readonly workspace: TurnWorkspace;
+    readonly fileReview: FileReviewIdentity;
+    readonly artifactStorage: ArtifactStorage | undefined;
+}): Promise<TurnCapture | undefined>;
+/**
+ * Turn end: compose the CAS captures from the bound observations, derive the
+ * approved-command provenance, author CANDIDATE_CAPTURED (the seam authors
+ * nothing for a turn that changed nothing), and — iff a candidate exists —
+ * stamp the flowed rows. The working tree is LEFT applied: the user reviews
+ * the real change, and an Undo puts files back at a later turn's start
+ * (`owed-undos.ts`). Returns whether a change set was authored; it never
+ * decides how the turn ends.
+ */
+export declare function captureCandidate(args: {
+    readonly rows: TurnRows;
+    readonly executionId: string;
+    readonly workspace: TurnWorkspace;
+    readonly fileReview: FileReviewIdentity;
+    readonly artifactStorage: ArtifactStorage | undefined;
+    readonly capture: TurnCapture;
+    /** `spec.auto_approve_all`, the one whole-run bypass: qualifies every executed command as consented. */
+    readonly globalBypass: boolean;
+}): Promise<boolean>;
+/**
+ * The runtime's two inputs to the shared approved-command rule (see the
+ * header). Pure
+ * over the rows and the pre-turn snapshots; exported for its own tests.
+ */
+export declare function deriveCommandProvenance(rows: Pick<TurnRows, "messages" | "subAgentRuns">, capture: Pick<TurnCapture, "priorSettledToolCallIds" | "priorSubAgentToolCallIds">, globalBypass: boolean): TurnCommandProvenance | undefined;