@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/dist/shared/filereview/events.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The runner's file-review event producer: maps a harness-agnostic capture into
+ * the proto {@code CapturedFileChange} + {@code FileReviewEvent} ledger entries
+ * the server folds (append-only, by event_id) into the server-owned stream.
+ *
+ * This is the runner half of the apply-then-review subsystem. It is intentionally
+ * harness-agnostic — it takes per-file before/after content and a kind, not a
+ * git-specific shape — so the Cursor (git substrate) and deep-agent (mutation
+ * buffer) harnesses author IDENTICAL ledger entries through one seam. Event ids
+ * are deterministic ({@link eventId}) so a re-sent heartbeat or a Temporal retry
+ * never duplicates an event.
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { CapturedFileChange, FileReviewEvent, SnapshotRef, TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { DiffCompleteness, FileCaptureClass, FileChangeKind, FileReviewBlockReason, FileReviewEventType, FileReviewFailureKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * The deterministic idempotency key for a file-review event:
+ * `changeSetId:scopeId:eventTypeName`. Capture/reconcile/failure events are
+ * change-set-scoped (scopeId == changeSetId); the per-file decision scope is the
+ * server's concern. Identical to the Go/Java EventID.
+ */
+export declare function eventId(changeSetId: string, scopeId: string, type: FileReviewEventType): string;
+/**
+ * One side (before/after) of a captured file's content, in one of three shapes:
+ *
+ * - `inline` — the raw text bytes, carried on the wire (the git substrate reads
+ *   them from the tree for text files). A plain string is accepted as shorthand.
+ * - `ref` — a reference to an already-stored, content-addressed blob (the CAS
+ *   substrate offloads ignored / non-git bodies to artifact storage and carries
+ *   the ref, so the body is never stored twice).
+ * - `binary` — a git-tracked binary side: NO body is carried (a binary has no
+ *   reviewable text diff, and reconcile sources its bytes byte-exact from the
+ *   git ref, never from the wire), only the byte-true content address. This is
+ *   what keeps the enforcement digest honest for binaries — hashing a UTF-8
+ *   decode of binary bytes would be lossy.
+ */
+export type CapturedContent = {
+    readonly kind: "inline";
+    readonly text: string;
+    /**
+     * Byte-true SHA-256 of the RAW bytes, when the producer computed it at the
+     * source (the git substrate does). Preferred over hashing `text`, which for
+     * a non-UTF-8 blob (e.g. latin-1 with no NUL) would hash a lossy decode.
+     * Absent for the plain-string shorthand, where `text` IS the exact content.
+     */
+    readonly sha256?: string;
+} | {
+    readonly kind: "ref";
+    /** Content address of the referenced blob (the enforcement digest). */
+    readonly sha256: string;
+    readonly storageKey: string;
+    readonly sizeBytes: number;
+    readonly isBinary: boolean;
+    readonly mimeType?: string;
+} | {
+    readonly kind: "binary";
+    /** Byte-true SHA-256 of the raw bytes (the enforcement digest). */
+    readonly sha256: string;
+};
+/** A single captured file delta, harness-agnostic (no git/CAS specifics). */
+export interface CapturedChangeInput {
+    /** Stable id of this file change within its set (correlation key, never a hash). */
+    readonly id: string;
+    /** Path before the change (workspace-root-relative). Empty for ADD. */
+    readonly pathBefore: string;
+    /** Path after the change. Empty for DELETE; differs from pathBefore for RENAME. */
+    readonly pathAfter: string;
+    readonly kind: FileChangeKind;
+    /** Which substrate captured this file (git-tracked, ignored, CAS, ...). */
+    readonly captureClass: FileCaptureClass;
+    /** Pre-edit content (inline string, or a blob ref). Omit for ADD. */
+    readonly before?: string | CapturedContent;
+    /** Post-edit content (inline string, or a blob ref). Omit for DELETE. */
+    readonly after?: string | CapturedContent;
+    /**
+     * False when this file's diff could not be captured completely (too large to
+     * persist inline before CAS exists, truncated, or binary-only). A change set
+     * with any incomplete file cannot be approved as complete.
+     */
+    readonly diffComplete?: boolean;
+    /**
+     * The honest cause the diff is not fully reviewable, set only alongside
+     * `diffComplete === false` (defaults to UNSPECIFIED). Informational provenance
+     * for the review UI — never an enforcement input and never folded into the
+     * digests. Binary is conveyed by FileContent.is_binary, so binary files leave
+     * this UNSPECIFIED. See {@link FileReviewBlockReason}.
+     */
+    readonly blockedReason?: FileReviewBlockReason;
+}
+/**
+ * The enforcement digest of one content side. Inline text is hashed as UTF-8
+ * bytes; a `ref`/`binary` side already carries its byte-true content address, so
+ * it is reused verbatim. This single function is the sole sha authority — used
+ * both at capture (in {@link buildCapturedFileChange}) and at the resume-time
+ * reconcile check — so the two are consistent by construction across substrates.
+ */
+export declare function contentSha256(content: CapturedContent): string;
+/**
+ * Build a proto {@link CapturedFileChange} from harness-agnostic input,
+ * computing the enforcement digests (`before_sha256`, `after_sha256`,
+ * `file_digest`) over the captured bytes. Content may be inline (git) or a blob
+ * ref (CAS) — the digests are identical either way, so the aggregate digest and
+ * the reconcile enforcement compose across both substrates.
+ */
+export declare function buildCapturedFileChange(input: CapturedChangeInput): CapturedFileChange;
+/** Coordinates a change set's lifecycle so every event carries one identity. */
+export interface ChangeSetContext {
+    readonly changeSetId: string;
+    readonly turnId: string;
+    /** "cursor" | "deep-agent". */
+    readonly harnessId: string;
+    /** ISO 8601 timestamp authored onto each event. */
+    readonly timestamp: string;
+}
+/**
+ * The BASELINE_CAPTURED event — the first event of a change set's lifecycle,
+ * authored at turn start so the projection can materialize the set before any
+ * candidate exists.
+ */
+export declare function buildBaselineCapturedEvent(ctx: ChangeSetContext, baselineSnapshot: SnapshotRef | undefined): FileReviewEvent;
+/**
+ * Derive a change set's {@link DiffCompleteness} rollup from its per-file
+ * signals — the single source of the three-way rule, shared by the turn-boundary
+ * capture ({@link buildCandidateCapturedEvent}) and the size backstop
+ * (status-offload), so the value can never be computed two ways:
+ *
+ * - every file complete → `COMPLETE`
+ * - else the ONLY incompleteness is binary (every incomplete file has a binary
+ *   side) → `BINARY_SUMMARY_ONLY` — keepable in one acknowledged action, its
+ *   exact bytes reconcile from the git ref / CAS blob
+ * - else (≥1 non-binary incomplete: secret-withheld / size-elided /
+ *   uncapturable — no keepable bytes) → `PARTIAL_BLOCKED`
+ *
+ * Binary is proven by `FileContent.is_binary` on either side (DD-15 D2), never
+ * by the block reason. This mirrors the backend gate's `isBinaryChange`, so the
+ * runner's rollup and the gate's per-file re-derivation agree by construction.
+ */
+export declare function deriveDiffCompleteness(changes: readonly CapturedFileChange[]): DiffCompleteness;
+/**
+ * The CANDIDATE_CAPTURED event — authored at the turn boundary, carrying the
+ * authoritative per-file diff and the aggregate digest. `diff_completeness` is
+ * the {@link deriveDiffCompleteness} rollup over the changes.
+ *
+ * `commandProvenance` (optional, DD-28) is the harness's approved-command turn
+ * facts: when present, the backend verifies the cited consent rows against its
+ * server-authored approval record and — on success — auto-keeps the set with a
+ * policy-origin decision instead of arming the review gate. Never folded into
+ * the aggregate digest (provenance, not content).
+ */
+export declare function buildCandidateCapturedEvent(ctx: ChangeSetContext, candidateSnapshot: SnapshotRef | undefined, changes: readonly CapturedFileChange[], commandProvenance?: TurnCommandProvenance): FileReviewEvent;
+/** The RECONCILED event — authored after decisions are applied and verified. */
+export declare function buildReconciledEvent(ctx: ChangeSetContext, approvedSnapshot: SnapshotRef | undefined): FileReviewEvent;
+/** A terminal FAILED event in the file-review lifecycle (audit + resume). */
+export declare function buildFailedEvent(ctx: ChangeSetContext, kind: FileReviewFailureKind, detail: string): FileReviewEvent;
+/**
+ * Whether a CANDIDATE_CAPTURED event exists for `changeSetId` on the status's
+ * file_review stream — i.e. this turn actually produced a reviewable change
+ * set. The capture seam authors no event for a no-op turn (an edit fully
+ * reverted before the boundary), so this is the single signal both harnesses
+ * gate on before opening a review or stamping transcript rows: a row must
+ * never reference a change set that does not exist.
+ */
+export declare function hasCandidateCaptured(status: AgentExecutionStatus, changeSetId: string): boolean;
+/**
+ * Append the runner-authored events onto the status's file_review stream
+ * (seeding it if absent), idempotently by event_id. The server re-applies the
+ * same append-only/by-id discipline on receipt, so re-sending across throttled
+ * persists is safe; this keeps the in-runner status consistent between persists.
+ */
+export declare function appendFileReviewEvents(status: AgentExecutionStatus, executionId: string, events: readonly FileReviewEvent[]): void;

package/dist/shared/filereview/events.js

@@ -0,0 +1,298 @@
+/**
+ * The runner's file-review event producer: maps a harness-agnostic capture into
+ * the proto {@code CapturedFileChange} + {@code FileReviewEvent} ledger entries
+ * the server folds (append-only, by event_id) into the server-owned stream.
+ *
+ * This is the runner half of the apply-then-review subsystem. It is intentionally
+ * harness-agnostic — it takes per-file before/after content and a kind, not a
+ * git-specific shape — so the Cursor (git substrate) and deep-agent (mutation
+ * buffer) harnesses author IDENTICAL ledger entries through one seam. Event ids
+ * are deterministic ({@link eventId}) so a re-sent heartbeat or a Temporal retry
+ * never duplicates an event.
+ */
+import { create } from "@bufbuild/protobuf";
+import { CapturedFileChangeSchema, FileReviewBaselineCapturedSchema, FileReviewCandidateCapturedSchema, FileReviewEventSchema, FileReviewEventStreamSchema, FileReviewFailureSchema, FileReviewReconciledSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileContentSchema, ToolCallOutputRefSchema, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { DiffCompleteness, FileReviewBlockReason, FileReviewEventType, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { aggregateDigest, fileDigest, sha256Bytes } from "./digest.js";
+import { looksBinary } from "../file-change.js";
+// The runner is the author of capture/reconcile/failure events. "runner" (not
+// the generic "system") matches the cross-edition corpus fixtures and the
+// proto's actor convention ("runner" for capture/reconcile, "user" for
+// decisions). The projection ignores actor, but keeping it canonical keeps the
+// ledger self-describing and the dual-edition corpus honest.
+const ACTOR_RUNNER = "runner";
+/**
+ * The proto enum value NAME for a {@link FileReviewEventType}, e.g.
+ * `FILE_REVIEW_EVENT_TYPE_BASELINE_CAPTURED`. {@link eventId} hashes this name so
+ * the runner's ids are byte-identical to the Go `author.EventID` / Java
+ * `FileReviewStreamAuthor.eventId` (which use the proto name).
+ */
+const FILE_REVIEW_EVENT_TYPE_NAME = {
+    [FileReviewEventType.UNSPECIFIED]: "FILE_REVIEW_EVENT_TYPE_UNSPECIFIED",
+    [FileReviewEventType.BASELINE_CAPTURED]: "FILE_REVIEW_EVENT_TYPE_BASELINE_CAPTURED",
+    [FileReviewEventType.CANDIDATE_CAPTURED]: "FILE_REVIEW_EVENT_TYPE_CANDIDATE_CAPTURED",
+    [FileReviewEventType.FILE_DECIDED]: "FILE_REVIEW_EVENT_TYPE_FILE_DECIDED",
+    [FileReviewEventType.RECONCILED]: "FILE_REVIEW_EVENT_TYPE_RECONCILED",
+    [FileReviewEventType.FAILED]: "FILE_REVIEW_EVENT_TYPE_FAILED",
+};
+/**
+ * The deterministic idempotency key for a file-review event:
+ * `changeSetId:scopeId:eventTypeName`. Capture/reconcile/failure events are
+ * change-set-scoped (scopeId == changeSetId); the per-file decision scope is the
+ * server's concern. Identical to the Go/Java EventID.
+ */
+export function eventId(changeSetId, scopeId, type) {
+    return `${changeSetId}:${scopeId}:${FILE_REVIEW_EVENT_TYPE_NAME[type]}`;
+}
+/** Normalize the string-shorthand to a {@link CapturedContent}. */
+function normalizeContent(v) {
+    if (v === undefined)
+        return undefined;
+    return typeof v === "string" ? { kind: "inline", text: v } : v;
+}
+/**
+ * The enforcement digest of one content side. Inline text is hashed as UTF-8
+ * bytes; a `ref`/`binary` side already carries its byte-true content address, so
+ * it is reused verbatim. This single function is the sole sha authority — used
+ * both at capture (in {@link buildCapturedFileChange}) and at the resume-time
+ * reconcile check — so the two are consistent by construction across substrates.
+ */
+export function contentSha256(content) {
+    switch (content.kind) {
+        case "inline":
+            return content.sha256 ?? sha256Bytes(Buffer.from(content.text, "utf8"));
+        case "ref":
+        case "binary":
+            return content.sha256;
+    }
+}
+/** Build the proto {@link FileContent} for one content side (inline, ref, or binary). */
+function toFileContent(content) {
+    if (content.kind === "inline") {
+        return create(FileContentSchema, {
+            body: { case: "inline", value: content.text },
+            isBinary: looksBinary(content.text),
+        });
+    }
+    // A git-tracked binary carries no body: its bytes reconcile from the git ref,
+    // and a text diff of binary content is meaningless. Consumers key off the
+    // is_binary flag (the SDK renders "binary file changed"; the backend gates
+    // approval on it), never a body.
+    if (content.kind === "binary") {
+        return create(FileContentSchema, { isBinary: true });
+    }
+    return create(FileContentSchema, {
+        body: {
+            case: "ref",
+            value: create(ToolCallOutputRefSchema, {
+                storageKey: content.storageKey,
+                sizeBytes: BigInt(content.sizeBytes),
+                contentHash: content.sha256,
+                mimeType: content.mimeType ?? "application/octet-stream",
+                isImage: false,
+                truncatedPreview: "",
+            }),
+        },
+        isBinary: content.isBinary,
+    });
+}
+/**
+ * Build a proto {@link CapturedFileChange} from harness-agnostic input,
+ * computing the enforcement digests (`before_sha256`, `after_sha256`,
+ * `file_digest`) over the captured bytes. Content may be inline (git) or a blob
+ * ref (CAS) — the digests are identical either way, so the aggregate digest and
+ * the reconcile enforcement compose across both substrates.
+ */
+export function buildCapturedFileChange(input) {
+    const before = normalizeContent(input.before);
+    const after = normalizeContent(input.after);
+    const beforeSha256 = before ? contentSha256(before) : "";
+    const afterSha256 = after ? contentSha256(after) : "";
+    const fc = create(CapturedFileChangeSchema, {
+        id: input.id,
+        pathBefore: input.pathBefore,
+        pathAfter: input.pathAfter,
+        kind: input.kind,
+        captureClass: input.captureClass,
+        beforeSha256,
+        afterSha256,
+        diffComplete: input.diffComplete ?? true,
+        blockedReason: input.blockedReason ?? FileReviewBlockReason.UNSPECIFIED,
+        fileDigest: fileDigest({
+            pathBefore: input.pathBefore,
+            pathAfter: input.pathAfter,
+            kind: input.kind,
+            beforeSha256,
+            afterSha256,
+        }),
+    });
+    if (before) {
+        fc.before = toFileContent(before);
+    }
+    if (after) {
+        fc.after = toFileContent(after);
+    }
+    return fc;
+}
+/**
+ * The BASELINE_CAPTURED event — the first event of a change set's lifecycle,
+ * authored at turn start so the projection can materialize the set before any
+ * candidate exists.
+ */
+export function buildBaselineCapturedEvent(ctx, baselineSnapshot) {
+    return create(FileReviewEventSchema, {
+        eventId: eventId(ctx.changeSetId, ctx.changeSetId, FileReviewEventType.BASELINE_CAPTURED),
+        changeSetId: ctx.changeSetId,
+        eventType: FileReviewEventType.BASELINE_CAPTURED,
+        timestamp: ctx.timestamp,
+        actor: ACTOR_RUNNER,
+        payload: {
+            case: "baselineCaptured",
+            value: create(FileReviewBaselineCapturedSchema, {
+                changeSetId: ctx.changeSetId,
+                turnId: ctx.turnId,
+                harnessId: ctx.harnessId,
+                ...(baselineSnapshot ? { baselineSnapshot } : {}),
+            }),
+        },
+    });
+}
+/**
+ * Derive a change set's {@link DiffCompleteness} rollup from its per-file
+ * signals — the single source of the three-way rule, shared by the turn-boundary
+ * capture ({@link buildCandidateCapturedEvent}) and the size backstop
+ * (status-offload), so the value can never be computed two ways:
+ *
+ * - every file complete → `COMPLETE`
+ * - else the ONLY incompleteness is binary (every incomplete file has a binary
+ *   side) → `BINARY_SUMMARY_ONLY` — keepable in one acknowledged action, its
+ *   exact bytes reconcile from the git ref / CAS blob
+ * - else (≥1 non-binary incomplete: secret-withheld / size-elided /
+ *   uncapturable — no keepable bytes) → `PARTIAL_BLOCKED`
+ *
+ * Binary is proven by `FileContent.is_binary` on either side (DD-15 D2), never
+ * by the block reason. This mirrors the backend gate's `isBinaryChange`, so the
+ * runner's rollup and the gate's per-file re-derivation agree by construction.
+ */
+export function deriveDiffCompleteness(changes) {
+    let sawIncomplete = false;
+    for (const c of changes) {
+        if (c.diffComplete)
+            continue;
+        sawIncomplete = true;
+        if (!(c.before?.isBinary || c.after?.isBinary)) {
+            // A non-binary incompleteness has no keepable bytes — it blocks the set
+            // outright, regardless of any binaries alongside it.
+            return DiffCompleteness.PARTIAL_BLOCKED;
+        }
+    }
+    if (!sawIncomplete)
+        return DiffCompleteness.COMPLETE;
+    return DiffCompleteness.BINARY_SUMMARY_ONLY;
+}
+/**
+ * The CANDIDATE_CAPTURED event — authored at the turn boundary, carrying the
+ * authoritative per-file diff and the aggregate digest. `diff_completeness` is
+ * the {@link deriveDiffCompleteness} rollup over the changes.
+ *
+ * `commandProvenance` (optional, DD-28) is the harness's approved-command turn
+ * facts: when present, the backend verifies the cited consent rows against its
+ * server-authored approval record and — on success — auto-keeps the set with a
+ * policy-origin decision instead of arming the review gate. Never folded into
+ * the aggregate digest (provenance, not content).
+ */
+export function buildCandidateCapturedEvent(ctx, candidateSnapshot, changes, commandProvenance) {
+    return create(FileReviewEventSchema, {
+        eventId: eventId(ctx.changeSetId, ctx.changeSetId, FileReviewEventType.CANDIDATE_CAPTURED),
+        changeSetId: ctx.changeSetId,
+        eventType: FileReviewEventType.CANDIDATE_CAPTURED,
+        timestamp: ctx.timestamp,
+        actor: ACTOR_RUNNER,
+        payload: {
+            case: "candidateCaptured",
+            value: create(FileReviewCandidateCapturedSchema, {
+                changeSetId: ctx.changeSetId,
+                ...(candidateSnapshot ? { candidateSnapshot } : {}),
+                changes: [...changes],
+                aggregateDigest: aggregateDigest(changes.map((c) => ({
+                    pathBefore: c.pathBefore,
+                    pathAfter: c.pathAfter,
+                    kind: c.kind,
+                    beforeSha256: c.beforeSha256,
+                    afterSha256: c.afterSha256,
+                }))),
+                diffCompleteness: deriveDiffCompleteness(changes),
+                ...(commandProvenance ? { commandProvenance } : {}),
+            }),
+        },
+    });
+}
+/** The RECONCILED event — authored after decisions are applied and verified. */
+export function buildReconciledEvent(ctx, approvedSnapshot) {
+    return create(FileReviewEventSchema, {
+        eventId: eventId(ctx.changeSetId, ctx.changeSetId, FileReviewEventType.RECONCILED),
+        changeSetId: ctx.changeSetId,
+        eventType: FileReviewEventType.RECONCILED,
+        timestamp: ctx.timestamp,
+        actor: ACTOR_RUNNER,
+        payload: {
+            case: "reconciled",
+            value: create(FileReviewReconciledSchema, {
+                changeSetId: ctx.changeSetId,
+                ...(approvedSnapshot ? { approvedSnapshot } : {}),
+            }),
+        },
+    });
+}
+/** A terminal FAILED event in the file-review lifecycle (audit + resume). */
+export function buildFailedEvent(ctx, kind, detail) {
+    return create(FileReviewEventSchema, {
+        eventId: eventId(ctx.changeSetId, ctx.changeSetId, FileReviewEventType.FAILED),
+        changeSetId: ctx.changeSetId,
+        eventType: FileReviewEventType.FAILED,
+        timestamp: ctx.timestamp,
+        actor: ACTOR_RUNNER,
+        payload: {
+            case: "failed",
+            value: create(FileReviewFailureSchema, { changeSetId: ctx.changeSetId, kind, detail }),
+        },
+    });
+}
+/**
+ * Whether a CANDIDATE_CAPTURED event exists for `changeSetId` on the status's
+ * file_review stream — i.e. this turn actually produced a reviewable change
+ * set. The capture seam authors no event for a no-op turn (an edit fully
+ * reverted before the boundary), so this is the single signal both harnesses
+ * gate on before opening a review or stamping transcript rows: a row must
+ * never reference a change set that does not exist.
+ */
+export function hasCandidateCaptured(status, changeSetId) {
+    return (status.fileReviewEventStream?.events ?? []).some((e) => e.changeSetId === changeSetId &&
+        e.eventType === FileReviewEventType.CANDIDATE_CAPTURED);
+}
+/**
+ * Append the runner-authored events onto the status's file_review stream
+ * (seeding it if absent), idempotently by event_id. The server re-applies the
+ * same append-only/by-id discipline on receipt, so re-sending across throttled
+ * persists is safe; this keeps the in-runner status consistent between persists.
+ */
+export function appendFileReviewEvents(status, executionId, events) {
+    if (events.length === 0)
+        return;
+    if (!status.fileReviewEventStream) {
+        status.fileReviewEventStream = create(FileReviewEventStreamSchema, {
+            executionId,
+            events: [],
+        });
+    }
+    const stream = status.fileReviewEventStream;
+    const seen = new Set(stream.events.map((e) => e.eventId));
+    for (const ev of events) {
+        if (seen.has(ev.eventId))
+            continue;
+        seen.add(ev.eventId);
+        stream.events.push(ev);
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/shared/filereview/events.js.map

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

package/dist/shared/filereview/git-substrate.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Git snapshot/restore substrate for the apply-then-review HITL "capture mode".
+ *
+ * THE MODEL
+ * ---------
+ * Edits are applied to the working tree and reviewed AFTER the fact; rejecting a
+ * file snaps it back exactly. We use git as a NO-COMMIT snapshot/restore
+ * substrate at the turn boundary:
+ *
+ *  1. snapshotBaseline() at turn start — record the exact pre-turn working tree
+ *     and pin it behind a ref so it survives a multi-day approval wait.
+ *  2. The agent edits files freely (the gate allows git-tracked write/edit/delete).
+ *  3. captureChangeSet() at turn end — diff the post-turn tree against the
+ *     baseline into a per-file change set, and pin the post-turn ("after") tree
+ *     behind a ref. The working tree is LEFT in its "after" state: the user
+ *     reviews the real, applied change and the workspace browser shows it.
+ *  4. On resume, reconcile the working tree to the per-file decisions, sourced
+ *     ENTIRELY from the two pinned refs (not the live tree, not the persisted
+ *     bodies — the refs are the single source of truth):
+ *       - approved           -> applyApprovedPaths() ensures the "after" bytes.
+ *       - rejected/undecided -> restoreToBaseline() snaps the file back to its
+ *         exact pre-turn bytes.
+ *     This is symmetric and idempotent: it converges to the correct end state
+ *     regardless of the tree's current contents, so a Temporal retry or a tree
+ *     reset is harmless.
+ *  5. dropCaptureRefs() releases the pinned objects.
+ *
+ * HARNESS-AGNOSTIC
+ * ----------------
+ * This is pure git plumbing keyed by `executionId`. It carries no Cursor- or
+ * deep-agent-specific knowledge: the runner-owned files a harness writes into the
+ * workspace (e.g. the Cursor gate's `.cursor/hooks.json`) are passed in as
+ * `excludePaths` so they never pollute the captured diff, rather than being
+ * hard-coded here. Both harnesses author IDENTICAL ledger entries through the
+ * shared producer (events.ts) on top of this substrate. A future CAS substrate
+ * (for ignored / non-git paths) sits beside this module.
+ *
+ * NOTHING IS PERMANENT UNTIL APPROVAL
+ * -----------------------------------
+ * Edits are visible during review, but nothing is committed and the next turn is
+ * blocked until the user decides; a reject snaps the file back byte-for-byte from
+ * the baseline ref. Shell/MCP and gitignored writes/deletes are NOT reversible by
+ * this substrate, so they stay on the approve-before-run gate (see each harness's
+ * gate: the Cursor hook and the deep-agent approval-gate middleware).
+ *
+ * WHY GIT, NO COMMITS
+ * -------------------
+ * Git is used ONLY as an exact, reversible capture/restore mechanism. We never
+ * move HEAD, never touch a branch, never push. Approved work stays uncommitted;
+ * a harness's own writeback path (if any) commits the reconciled tree afterwards.
+ *
+ * HARD INVARIANTS
+ * ---------------
+ * - NEVER `git clean -x`/`-a` or `git stash -a`: the git-excluded `.stigmer/`
+ *   directory holds SDK resume state and MUST survive. `git clean -fd` (no `-x`)
+ *   leaves ignored paths alone, so `.stigmer`/`lost+found` are safe.
+ * - Runner-owned files written into the workspace are EXCLUDED (via `excludePaths`)
+ *   from both the baseline and the after tree, so they never pollute the captured
+ *   diff regardless of gate-teardown ordering.
+ * - All staging uses a TEMP index (GIT_INDEX_FILE) so the repo's real index is
+ *   never disturbed.
+ */
+import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { CapturedContent } from "./events.js";
+/**
+ * Refs that pin the per-execution baseline and after trees against GC. Exported
+ * so the file-review producer can stamp them onto the ledger's SnapshotRef
+ * (GitTreeRef.ref) without re-deriving the format. Keyed by executionId only:
+ * the unified gate guarantees at most one un-reconciled change set per execution
+ * at a time, and the reconcile drops these refs before the next turn re-pins.
+ */
+export declare function baselineRef(executionId: string): string;
+export declare function captureRef(executionId: string): string;
+/**
+ * A single file mutation captured from the git diff between the baseline and
+ * after trees. `path` is repo-relative (forward slashes); `changeType` drives
+ * restore/apply. `before`/`after` are the harness-agnostic {@link CapturedContent}
+ * for each side (absent per changeType: no `before` for a CREATE, no `after` for
+ * a DELETE) — text is carried inline, binary carries only its byte-true content
+ * address (its bytes reconcile byte-exact from the git ref, never the wire).
+ */
+export interface GitSubstrateChange {
+    /** Repo-relative path (the diff's path; the destination for a create/modify). */
+    readonly path: string;
+    readonly changeType: FileChangeType;
+    /** Pre-edit content (absent for a CREATE). */
+    readonly before?: CapturedContent;
+    /** Post-edit content (absent for a DELETE). */
+    readonly after?: CapturedContent;
+}
+/** Result of {@link captureChangeSet} / {@link recomputeChangeSet}. */
+export interface CaptureResult {
+    /**
+     * The pre-turn tree sha (pinned behind the baseline ref). On resume this is
+     * the authoritative source for reverting rejected/undecided files exactly.
+     */
+    readonly baselineTree: string;
+    /** The post-turn tree sha, also pinned behind the capture ref. */
+    readonly afterTree: string;
+    /** One entry per changed file (excluding the passed runner-owned paths). */
+    readonly changes: readonly GitSubstrateChange[];
+}
+/**
+ * Whether `dir` is inside a git work tree (the capability switch: a real git
+ * workspace gets capture mode, anything else keeps the deny-gate fallback).
+ */
+export declare function isGitWorkTree(dir: string): Promise<boolean>;
+/**
+ * Whether a repo-relative path is capturable by this substrate — i.e. it would
+ * appear in the `git add -A` snapshot. A gitignored path is NOT capturable: the
+ * snapshot cannot see it, so it can be neither reviewed nor reverted, and a
+ * capture-mode gate must keep gating it. Mirrors the Cursor hook's
+ * `__stigmer_is_gitignored` check: `git check-ignore -q` exits 0 when the path IS
+ * ignored, non-zero otherwise; a non-git context / error is treated as
+ * not-ignored (capturable), matching the hook's allow-on-error behavior.
+ */
+export declare function isPathCapturable(gitRoot: string, path: string): Promise<boolean>;
+/**
+ * Snapshot the working tree at turn start and pin it behind the baseline ref.
+ * Returns the baseline tree sha (used by {@link captureChangeSet} and
+ * {@link restoreToBaseline} later in the SAME activity invocation). `excludePaths`
+ * are the runner-owned files the harness writes into the workspace (omit for none).
+ */
+export declare function snapshotBaseline(gitRoot: string, executionId: string, excludePaths?: readonly string[]): Promise<string>;
+/**
+ * Capture the change set the turn produced: write the post-turn working tree,
+ * pin it behind the capture ref (so it survives the approval wait), and diff it
+ * against `baselineTree` into a per-file {@link GitSubstrateChange} list.
+ *
+ * Renames are intentionally NOT detected (`--no-renames`): a rename surfaces as
+ * a delete + create, which restores and applies exactly and matches the per-file
+ * review model.
+ */
+export declare function captureChangeSet(gitRoot: string, executionId: string, baselineTree: string, excludePaths?: readonly string[]): Promise<CaptureResult>;
+/**
+ * Restore the given files to their `baselineTree` (pre-turn) bytes. On resume
+ * this reverts the REJECTED/undecided subset so a discarded change snaps back
+ * exactly; it is the generic "ensure baseline bytes" primitive. Surgical
+ * (bounded by the passed change set): an agent-created file is removed; an
+ * agent-modified or agent-deleted file is rewritten with its baseline bytes.
+ * `.stigmer` and other ignored paths are never touched (they are not in the
+ * change set). Idempotent — safe to re-run (e.g. on a Temporal retry).
+ */
+export declare function restoreToBaseline(gitRoot: string, baselineTree: string, changes: readonly GitSubstrateChange[]): Promise<void>;
+/**
+ * Ensure the APPROVED files hold their captured "after" bytes, as uncommitted
+ * working-tree changes (no commit). In capture mode the agent's edits are left
+ * applied through the review window, so on resume this is normally an idempotent
+ * re-assert of bytes already on disk; sourcing from the pinned "after" tree also
+ * makes it self-healing if the tree was reset (Temporal retry / sandbox
+ * recycle). An approved CREATE/MODIFY writes the after bytes; an approved DELETE
+ * removes the file. Rejected/undecided paths are not passed in (they go to
+ * {@link restoreToBaseline}).
+ */
+export declare function applyApprovedPaths(gitRoot: string, afterTree: string, approved: readonly GitSubstrateChange[]): Promise<void>;
+/**
+ * Recompute the captured change set on a RESUME, from the pinned baseline and
+ * capture refs — the authoritative source that survived the approval wait,
+ * independent of any persisted fidelity. Returns `undefined` when this was not a
+ * capture turn (the capture ref is absent), so the caller can fall through to the
+ * non-capture path.
+ */
+export declare function recomputeChangeSet(gitRoot: string, executionId: string): Promise<CaptureResult | undefined>;
+/**
+ * Snapshot the post-reconcile working tree (after approved bytes were applied and
+ * rejected files were reverted) and pin it behind the approved ref. Returns the
+ * approved tree sha for the RECONCILED event's `approved_snapshot`, plus the ref
+ * so the producer can stamp the SnapshotRef. Idempotent under a Temporal retry.
+ */
+export declare function snapshotApproved(gitRoot: string, executionId: string, excludePaths?: readonly string[]): Promise<{
+    treeOid: string;
+    ref: string;
+}>;
+/** Release the per-execution baseline, capture, and approved refs (idempotent). */
+export declare function dropCaptureRefs(gitRoot: string, executionId: string): Promise<void>;