@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/harness/capture.js

@@ -0,0 +1,248 @@
+/**
+ * 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 { FileCaptureClass } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import { captureBaselineToLedger, captureCandidateToLedger } from "../shared/filereview/capture.js";
+import { createCasProgressSubstrate } from "../shared/filereview/cas-progress.js";
+import { buildCasTurnCaptures } from "../shared/filereview/cas-touched.js";
+import { qualifyTurnCommandProvenance } from "../shared/filereview/command-provenance.js";
+import { hasCandidateCaptured } from "../shared/filereview/events.js";
+import { createGitProgressSubstrate, createHybridProgressSubstrate, newProgressCaptureState, } from "../shared/filereview/progress.js";
+import { collectSettledToolCallIds, collectSubAgentToolCallIds, stampFlowedFileEditRows, stampFlowedSubAgentFileEditRows } from "../shared/tool-row.js";
+import { ApprovalAction, ToolCallStatus } from "../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+const NOTHING_OBSERVED = { before: new Map(), blockedSecretPaths: new Set() };
+/**
+ * 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 async function pinCaptureBaseline(args) {
+    const { rows, executionId, workspace, fileReview, artifactStorage } = args;
+    if (!workspace.captureMode)
+        return undefined;
+    const { primaryDir, gitWorkspace, changeSetId } = workspace;
+    const priorSettledToolCallIds = collectSettledToolCallIds(rows.messages);
+    const priorSubAgentToolCallIds = collectSubAgentToolCallIds(rows.subAgentRuns);
+    const baselineTree = await captureBaselineToLedger({
+        rows,
+        gitRoot: primaryDir,
+        executionId,
+        changeSetId,
+        harnessId: fileReview.harnessId,
+        excludePaths: fileReview.excludePaths,
+        gitWorkspace,
+    });
+    const capture = {
+        changeSetId,
+        baselineTree,
+        progress: {
+            changeSetId,
+            state: newProgressCaptureState(),
+            substrate: buildProgressSubstrate({
+                executionId,
+                workspace,
+                baselineTree,
+                excludePaths: fileReview.excludePaths,
+                transientPaths: fileReview.transientPaths ?? [],
+                casSlice: artifactStorage !== undefined,
+                // Delegates to whatever the adapter binds later; `capture` is
+                // assigned before any capture() can run.
+                readObservations: () => capture.casObservations?.() ?? NOTHING_OBSERVED,
+            }),
+        },
+        priorSettledToolCallIds,
+        priorSubAgentToolCallIds,
+        casObservations: undefined,
+    };
+    return capture;
+}
+/**
+ * The progress substrate for this workspace shape: a git
+ * tree diffs its tracked paths by `--numstat` against the baseline; the CAS
+ * slice reads the engine's observations for the gitignored (git tree) or
+ * every (non-git) path; a git tree with storage composes both. The truth
+ * table is `deriveCaptureMode`'s: capture mode holds only for a git tree or
+ * a workspace with storage, so the fourth cell is unreachable and says so.
+ */
+function buildProgressSubstrate(args) {
+    const { transientPaths } = args;
+    const substrate = buildShapedProgressSubstrate(args);
+    if (transientPaths.length === 0)
+        return substrate;
+    // A path the harness rewrites for the turn only: dropped from what the
+    // progress shows, by path, since the baseline holds it and a tree exclusion
+    // would read its absence as a deletion.
+    const transient = new Set(transientPaths);
+    return {
+        async capture() {
+            const { delta, changed } = await substrate.capture();
+            const entries = delta.entries.filter((e) => !transient.has(e.pathAfter) && !transient.has(e.pathBefore));
+            return { delta: { ...delta, entries }, changed };
+        },
+    };
+}
+function buildShapedProgressSubstrate(args) {
+    const { executionId, workspace, baselineTree, excludePaths, casSlice, readObservations } = args;
+    const git = workspace.gitWorkspace
+        ? createGitProgressSubstrate({ workspaceRoot: workspace.primaryDir, executionId, baselineTree, excludePaths })
+        : undefined;
+    const cas = casSlice ? createCasProgressSubstrate({ workspaceRoot: workspace.primaryDir, read: readObservations }) : undefined;
+    if (git && cas)
+        return createHybridProgressSubstrate(git, cas);
+    const one = git ?? cas;
+    if (!one)
+        throw new Error(`capture: capture mode on a non-git tree without storage (execution=${executionId}); deriveCaptureMode forbids this`);
+    return one;
+}
+/**
+ * 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 async function captureCandidate(args) {
+    const { rows, executionId, workspace, fileReview, artifactStorage, capture, globalBypass } = args;
+    const { primaryDir, gitWorkspace } = workspace;
+    const { changeSetId } = capture;
+    const casCaptureClass = gitWorkspace ? FileCaptureClass.GIT_IGNORED_CAPTURED : FileCaptureClass.NON_GIT_CAS;
+    const observed = artifactStorage && capture.casObservations ? await capture.casObservations() : NOTHING_OBSERVED;
+    const { casCaptures, unreviewablePaths } = await buildCasTurnCaptures(observed, primaryDir, casCaptureClass);
+    const commandProvenance = deriveCommandProvenance(rows, capture, globalBypass);
+    if (commandProvenance) {
+        console.log(`capture: turn qualifies for approved-command auto-keep ` +
+            `(consent rows: ${commandProvenance.consentToolCallIds.join(",") || "(auto_approve_all)"}); ` +
+            `attaching provenance to candidate (execution=${executionId})`);
+    }
+    await captureCandidateToLedger({
+        rows,
+        gitRoot: primaryDir,
+        executionId,
+        changeSetId,
+        baselineTree: capture.baselineTree,
+        harnessId: fileReview.harnessId,
+        excludePaths: fileReview.excludePaths,
+        casCaptures,
+        storage: artifactStorage,
+        unreviewablePaths,
+        unreviewableCaptureClass: casCaptureClass,
+        gitWorkspace,
+        commandProvenance,
+    });
+    const captured = hasCandidateCaptured(rows, changeSetId);
+    if (captured) {
+        // A row must never reference a change set that does not exist, so the
+        // stamp is gated on the authored candidate.
+        stampFlowedFileEditRows(rows.messages, changeSetId, { flowed: isCompletedRow });
+        stampFlowedSubAgentFileEditRows(rows.subAgentRuns, changeSetId, capture.priorSubAgentToolCallIds, isCompletedRow);
+        console.log(`capture: change set ${changeSetId} authored to the file_review ledger; working tree left applied for review (execution=${executionId})`);
+    }
+    return captured;
+}
+/** The row's own evidence that its effect landed on the tree. */
+function isCompletedRow(tc) {
+    return tc.status === ToolCallStatus.TOOL_CALL_COMPLETED;
+}
+/**
+ * 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 function deriveCommandProvenance(rows, capture, globalBypass) {
+    // Any sub-agent activity this turn disqualifies — a sub-agent
+    // that ran contributes at least one row id absent from the pre-turn set,
+    // and its writes fold into this change set without a consented command.
+    for (const id of collectSubAgentToolCallIds(rows.subAgentRuns)) {
+        if (!capture.priorSubAgentToolCallIds.has(id))
+            return undefined;
+    }
+    const turnToolCalls = rows.messages.flatMap((m) => m.toolCalls).filter((tc) => !capture.priorSettledToolCallIds.has(tc.id));
+    return qualifyTurnCommandProvenance({
+        turnToolCalls,
+        messages: rows.messages,
+        isExecutedCommand: isCompletedRow,
+        resolveDirectConsent: (tc) => tc.approvalAction === ApprovalAction.APPROVE || tc.approvalAction === ApprovalAction.APPROVE_ALL ? tc.id : undefined,
+        globalBypass,
+    });
+}
+//# sourceMappingURL=capture.js.map

package/dist/harness/capture.js.map

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

package/dist/harness/cost-cap-watch.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One turn's usage against its cost cap: the accumulator the runtime
+ * prices `streamingUsage` from, and the moment a reported delta reaches
+ * `max_cost_usd` (`shared/cost-guard.ts` is the rule).
+ *
+ * The runtime enforces the cap (`run-turn.ts`): on the crossing delta it
+ * stops the turn and later settles `costCapArm`. The agent host
+ * (`agent-host/host-sink.ts`) applies the same watch to the same deltas,
+ * before they cross the pipe, so the adapter's stop signal aborts inside
+ * `reportUsage`, the instant it does when the adapter runs in the runner's
+ * own process; the engine then stops at its next step boundary, not a step
+ * later. What the turn's terminal says is still the runtime's own watch's
+ * evidence alone.
+ */
+import type { ServiceTier, ThinkingMode } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { UsageDelta } from "./types.js";
+import { UsageAccumulator } from "./usage-accumulator.js";
+export declare class CostCapWatch {
+    /** `status.runConfig.maxCostUsd`; 0 or less is no cap. */
+    readonly maxCostUsd: number;
+    readonly accumulator: UsageAccumulator;
+    private crossed;
+    constructor(
+    /** `status.runConfig.maxCostUsd`; 0 or less is no cap. */
+    maxCostUsd: number, serviceTier: ServiceTier, thinkingMode: ThinkingMode);
+    /** Add one delta. True exactly once: on the delta that reaches the cap. */
+    add(delta: UsageDelta): boolean;
+    /** Add a runtime call's cost (`UsageAccumulator.addAuxiliaryCost`). True exactly once, as {@link add}. */
+    addAuxiliary(costUsd: number): boolean;
+    private reached;
+}

package/dist/harness/cost-cap-watch.js

@@ -0,0 +1,44 @@
+/**
+ * One turn's usage against its cost cap: the accumulator the runtime
+ * prices `streamingUsage` from, and the moment a reported delta reaches
+ * `max_cost_usd` (`shared/cost-guard.ts` is the rule).
+ *
+ * The runtime enforces the cap (`run-turn.ts`): on the crossing delta it
+ * stops the turn and later settles `costCapArm`. The agent host
+ * (`agent-host/host-sink.ts`) applies the same watch to the same deltas,
+ * before they cross the pipe, so the adapter's stop signal aborts inside
+ * `reportUsage`, the instant it does when the adapter runs in the runner's
+ * own process; the engine then stops at its next step boundary, not a step
+ * later. What the turn's terminal says is still the runtime's own watch's
+ * evidence alone.
+ */
+import { costCapExceeded } from "../shared/cost-guard.js";
+import { UsageAccumulator } from "./usage-accumulator.js";
+export class CostCapWatch {
+    maxCostUsd;
+    accumulator;
+    crossed = false;
+    constructor(
+    /** `status.runConfig.maxCostUsd`; 0 or less is no cap. */
+    maxCostUsd, serviceTier, thinkingMode) {
+        this.maxCostUsd = maxCostUsd;
+        this.accumulator = new UsageAccumulator(serviceTier, thinkingMode);
+    }
+    /** Add one delta. True exactly once: on the delta that reaches the cap. */
+    add(delta) {
+        this.accumulator.addTurn(delta);
+        return this.reached();
+    }
+    /** Add a runtime call's cost (`UsageAccumulator.addAuxiliaryCost`). True exactly once, as {@link add}. */
+    addAuxiliary(costUsd) {
+        this.accumulator.addAuxiliaryCost(costUsd);
+        return this.reached();
+    }
+    reached() {
+        if (this.crossed || !costCapExceeded(this.maxCostUsd, this.accumulator.snapshot().estimatedCostUsd))
+            return false;
+        this.crossed = true;
+        return true;
+    }
+}
+//# sourceMappingURL=cost-cap-watch.js.map

package/dist/harness/cost-cap-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-cap-watch.js","sourceRoot":"","sources":["../../src/harness/cost-cap-watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,OAAO,YAAY;IAMZ;IALF,WAAW,CAAmB;IAC/B,OAAO,GAAG,KAAK,CAAC;IAExB;IACE,0DAA0D;IACjD,UAAkB,EAC3B,WAAwB,EACxB,YAA0B;QAFjB,eAAU,GAAV,UAAU,CAAQ;QAI3B,IAAI,CAAC,WAAW,GAAG,IAAI,gBAAgB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IACrE,CAAC;IAED,2EAA2E;IAC3E,GAAG,CAAC,KAAiB;QACnB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,0GAA0G;IAC1G,YAAY,CAAC,OAAe;QAC1B,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,gBAAgB,CAAC;YAAE,OAAO,KAAK,CAAC;QAClH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/harness/events/emitter.d.ts

@@ -0,0 +1,220 @@
+/**
+ * SessionEventEmitter: writes what the agent did into its session's event
+ * log (`SessionCommandController.appendEvents`), in Claude Managed Agents'
+ * events, from the rows the turn holds (`TurnRows`, the runner's own proto).
+ *
+ * Where it reads. The persist chokepoint calls {@link flush} on every write
+ * of the status, after the secret backstop and the tool-output offload of
+ * that write and before the status itself is sent (`persist-chokepoint.ts`),
+ * so the log sees the rows redacted and bounded, in both process modes (the
+ * agent host's rows reach the runtime's on every persist). The status
+ * carries no rows: the log is where they go. One reader of the rows, never
+ * a second writer of them.
+ *
+ * What it writes: only sealed facts, in order. Each thread (the root, or
+ * one sub-agent) is walked in its rows' order: per message, the message,
+ * then its tool uses, then their results. A `task` call's use opens its
+ * sub-agent's thread; its result follows the thread's idle. The emitter
+ * writes the longest sealed prefix of each thread's walk and never a fact
+ * past an unsealed one, so the log is in order within a thread and parallel
+ * sub-agents interleave as they run. Sealed means no later step can
+ * rewrite it:
+ *   - a message, once it stops streaming (an empty one writes nothing);
+ *   - a tool use, once it is known to run, to ask or to be skipped: at
+ *     start on a harness whose boundary never rewrites a row, and on one
+ *     that does (Cursor, the `boundaryRewritesRow` capability) once the row
+ *     is beyond the boundary's reach or the turn's terminal write proves
+ *     the boundary ran. A call an unattended turn skipped carries
+ *     `evaluated_permission: "deny"` ({@link permissionOf}): native's gate
+ *     opens its row already saying so, and Cursor's boundary stamps it
+ *     before the row's use is written;
+ *   - a tool result, once its row settles, with the same boundary rule;
+ *   - a hidden row (the collapsed shape) writes nothing.
+ * A result whose output the chokepoint offloaded carries the output's
+ * head, and `stigmer.tool_result.full_output` after it says where the
+ * whole output is stored.
+ * So narration a boundary later blanks sits behind an unsealed row and
+ * reaches neither the log nor a preview.
+ *
+ * File review. A change set the turn captured (a CANDIDATE_CAPTURED on the
+ * turn's own ledger, `rows.file_review_event_stream`) is written as one
+ * `stigmer.file_review.changes`, read from that ledger at the same
+ * chokepoint, once. The undo a turn's start does for an earlier turn
+ * (`harness/owed-undos.ts`) is written as `stigmer.file_review.reconciled`
+ * through {@link writeReconciled}, at once, before the engine's turn begins
+ * and before the workspace lock is released. A decision is never the
+ * runner's to write: `stigmer.file_review.decided` is the server's.
+ *
+ * Which rows are its to write. The rows a terminal arm appends are
+ * reported ({@link skipRootRows}) and skipped, because the session's status
+ * events and the run's stop cause say it; every other SYSTEM row is a note
+ * of the harness (`stigmer.harness.note`). A reinvocation's seeded asks
+ * (`harness/transcript/resume-seed.ts`) sit on messages with no text, which write
+ * nothing, and their tool uses are already in the log.
+ *
+ * Its memory is the log. A resumed or retried turn first lists its run's
+ * events ({@link begin}) and treats those ids as sent, so it resends
+ * nothing whatever later edits did to the rows; a fresh turn skips the
+ * read. Ids are derived (`ids.ts`), so a fact is named the same way by
+ * every invocation. A message, thinking or note is named by its place in
+ * its scope, and a resumed invocation's rows are its own: the asks it
+ * seeded sit on messages before them that write nothing, so each scope's
+ * own places are numbered on from the highest index the log already holds
+ * there ({@link nextScopeIndexes}), and no id is reused.
+ *
+ * Previews. The transcript builder's observer hands every token delta to
+ * {@link observe}; the previews ride the next append. A message is
+ * previewed only while its thread's sealed prefix has reached it, and one
+ * whose previews were ever held back is never previewed again (a partial
+ * preview would show a client half a sentence).
+ *
+ * Failure. A transient append failure is retried; if it still fails the
+ * events stay queued for the next write, whose status write goes ahead
+ * (STOP and the heartbeat ride it). A refusal is a runner defect: the batch
+ * is logged with its ids and dropped, so one bad event cannot wedge a turn.
+ * The terminal write retries the queue once more and then logs the loss.
+ *
+ * Proven by `__tests__/emitter.test.ts` and the hermetic event goldens.
+ */
+import { FileChangeKind } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
+import type { CapturedFileChange } from "@stigmer/apis/ai/stigmer/agentic/run/v1/filereview_pb";
+import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { ReconciledUndo } from "../owed-undos.js";
+import type { TranscriptEvent } from "../transcript/events.js";
+import type { ToolCall, TurnRows } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import { ApprovalPolicySource } from "../../gen/turn/ai/stigmer/runner/turn/v1/enum_pb.js";
+/** The most bytes one encoded event may hold: the session log's own cap (the server's `SESSION_EVENT_MAX_BYTES`). */
+export declare const SESSION_EVENT_MAX_BYTES: number;
+export interface SessionEventEmitterDeps {
+    readonly client: Pick<StigmerClient, "appendSessionEvents" | "listRunSessionEvents">;
+    readonly runId: string;
+    /** The credential the append presents, as the values fetch acquires it; read once, at the first append. */
+    readonly credential: () => Promise<string | undefined>;
+    /** The harness's `boundaryRewritesRow` capability; absent when its boundary never rewrites a row. */
+    readonly boundaryRewritesRow?: (row: ToolCall) => boolean;
+    /** Waits between transient retries; the tests pass an immediate one. */
+    readonly delay?: (ms: number) => Promise<void>;
+}
+/** Where one fold left a delta's row: its place in its scope's message array. */
+export interface ObservedPlace {
+    readonly messageIndex: number;
+}
+/**
+ * The ask's policy source as the log's word, the enum value without its
+ * prefix. Typed over every value, so a new source fails the build until
+ * it has a word, and the event's validation lists the same words.
+ */
+export declare const POLICY_SOURCE_WORDS: Readonly<Record<ApprovalPolicySource, string>>;
+/** A ledger change kind as the log's word (`stigmer.file_review.changes`): a binary change is a modification. */
+export declare const FILE_CHANGE_WORDS: Readonly<Record<FileChangeKind, string>>;
+/** How much of a captured change can be shown, as the log's word. */
+export declare function reviewableWord(change: CapturedFileChange): string;
+export declare class SessionEventEmitter {
+    private readonly deps;
+    private began;
+    /** Ids the log holds, or that were dropped as refused: never sent again. */
+    private readonly sent;
+    /** Built and awaiting an append that succeeds, in order. */
+    private queue;
+    private readonly queued;
+    private pendingPreviews;
+    /** Previewed message ids already opened with an event_start. */
+    private readonly previewStarted;
+    /** Message ids never to preview again (their previews were held back once). */
+    private readonly previewWithheld;
+    /** Per scope prefix (`ids.ts` `scopeEventPrefix`), the index this invocation's own first place takes. */
+    private scopeBases;
+    /** Per scope (root ""), where this invocation's own messages begin: after the seeded asks' messages. */
+    private readonly ownFrom;
+    /** Root positions of the rows a terminal arm appended. */
+    private readonly armRows;
+    /** Per scope (root ""), where its last walk stopped. */
+    private readonly frontiers;
+    /** The sub-agent threads of the write being read, by sub-agent id. */
+    private threads;
+    private token;
+    private lost;
+    constructor(deps: SessionEventEmitterDeps);
+    /**
+     * Start writing: note where each scope's own messages begin in `rows`
+     * (after the asks a reinvocation seeded, which write nothing), and on a
+     * resumed or retried turn read back what this run already wrote and where
+     * each scope's numbering stands. Before this call every flush writes
+     * nothing, and the rows wait for the first flush after it. A failed read
+     * is logged and the turn writes on: what it resends with the same bytes
+     * the log accepts again, and anything else is refused and dropped, never
+     * fatal.
+     */
+    begin(args: {
+        readonly sessionId: string;
+        readonly resumed: boolean;
+        readonly rows: TurnRows;
+    }): Promise<void>;
+    /** The root positions of rows a terminal arm appended: never written (the module header). */
+    skipRootRows(indices: readonly number[]): void;
+    /**
+     * A folded transcript event, for previews. `place` is where the fold left
+     * a delta's row (absent for a fact with no row of its own).
+     */
+    observe(event: TranscriptEvent, place?: ObservedPlace): void;
+    /**
+     * One write's events: what sealed since the last, then the append, before
+     * the status write that follows it. `final` is the turn's terminal write:
+     * every row is past the boundary and nothing streams. Never throws.
+     */
+    flush(rows: TurnRows, opts: {
+        readonly final: boolean;
+    }): Promise<void>;
+    private collect;
+    /** One `stigmer.file_review.changes` per change set the turn's own ledger captured (the module header). */
+    private collectFileReviewChanges;
+    /**
+     * Write what a turn's start put back for earlier turns, one
+     * `stigmer.file_review.reconciled` per change set, at once: whether or not
+     * the engine's turn has begun (a reconcile turn never begins one), and
+     * before the caller releases the workspace lock, so the next holder of the
+     * tree reads it and does not undo the same files again. Retried as a
+     * terminal write is; a loss is logged, never thrown. An outcome the log
+     * already holds is not sent again.
+     */
+    writeReconciled(answers: readonly ReconciledUndo[]): Promise<void>;
+    /** One thread's sealed prefix, from its start, skipping what is already sent or queued. */
+    private walk;
+    /**
+     * The index a row's place in its scope is named by: the scope's own rows
+     * numbered on from what the log already holds there. A seeded ask's
+     * message sits before them and writes nothing.
+     */
+    private placeIndex;
+    /** The message's events, or false when it still streams. */
+    private writeMessage;
+    /** Whether the boundary may still rewrite this row (never on a harness that declares no boundary). */
+    private awaitsBoundary;
+    /** The row's tool use (and its ask, and a sub-agent's thread start), or false when it is not yet known to run or ask. */
+    private writeToolUse;
+    /** The row's result (after a sub-agent's thread end), or false when it has not settled beyond the boundary's reach. */
+    private writeToolResult;
+    /** A sub-agent's thread opens: created, the message it was sent, running. Written on the primary thread. */
+    private writeThreadStart;
+    /** A sub-agent's thread closes, once it finished and its own walk wrote everything; false until then. */
+    private writeThreadEnd;
+    private known;
+    /** Queue one event, bounded to the log's cap, unless the log already holds it. */
+    private push;
+    /** The queued previews this write may send: a message only while its thread's prefix has reached it. */
+    private decidePreviews;
+    private append;
+    /** The queue in appends that each fit the input's limits. */
+    private batches;
+    /** The first `count` queued events are in the log (or refused for good): never sent again. */
+    private settle;
+    /** Give up the first `count` queued events: logged as lost, never resent by this invocation. */
+    private forget;
+}
+/**
+ * For each scope prefix the run's logged ids name, the index after the
+ * highest place the log holds there: where a resumed invocation numbers its
+ * own rows from, so it never reuses an id an earlier invocation wrote under
+ * other bytes. Ids that are not place-named are ignored.
+ */
+export declare function nextScopeIndexes(runId: string, ids: readonly string[]): Map<string, number>;