@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/dist/activities/execute-cursor/capture-flow.js

@@ -0,0 +1,234 @@
+/**
+ * Cursor adapter over the harness-agnostic capture-mode orchestration
+ * ({@link ../../shared/filereview/capture.js}).
+ *
+ * The substrate (git snapshot/restore) and the orchestration (baseline/candidate/
+ * reconcile authoring) live in `shared/filereview/` so the Cursor and deep-agent
+ * harnesses author IDENTICAL ledger entries. This adapter binds the Cursor
+ * specifics:
+ *  - `harnessId = "cursor"` (stamped on the BASELINE payload the projection reads);
+ *  - the Cursor gate files written into the workspace, excluded from the captured
+ *    diff (`CURSOR_RUNNER_OWNED_PATHS`);
+ *  - stamping the streamed file-edit transcript rows that flowed this turn with
+ *    the change set id (`stampFlowedFileEditRows`) — the rows stay visible as
+ *    observational/audit records at their transcript positions, while
+ *    `file_change_sets` remains the single DECISION surface.
+ *
+ * The three turn-boundary functions keep their original signatures so the
+ * activity wiring (index.ts) and the cutover tests are unchanged.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { FileCaptureClass } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { approvalCategory } from "./approval-policy.js";
+import { toolIdentity, primaryToken } from "./approval-state.js";
+import { readCasObservations } from "./cas-observations.js";
+import { contentDigest } from "../../shared/file-tools.js";
+import { isToolCallRowHidden, stampFileEditRow } from "../../shared/tool-row.js";
+import { applyCaptureDecisions as sharedApplyCaptureDecisions, captureBaselineToLedger as sharedCaptureBaselineToLedger, captureCandidateToLedger as sharedCaptureCandidateToLedger, } from "../../shared/filereview/capture.js";
+import { hasCandidateCaptured } from "../../shared/filereview/events.js";
+import { partitionIgnoredPathsBySecret } from "../../shared/filereview/secret-paths.js";
+import { casBlobReader } from "../../shared/filereview/cas-substrate.js";
+/** The harness id the projection reads from the BASELINE payload (load-bearing). */
+const HARNESS_ID = "cursor";
+/**
+ * Workspace-relative paths the Cursor gate writes into the repo. They are excluded
+ * from capture so a turn's diff never shows the gate's own machinery. (The
+ * workspace-scoped gate dir and SDK state live under `~/.stigmer` / the
+ * git-excluded `.stigmer`, so they need no exclusion here.)
+ */
+const CURSOR_RUNNER_OWNED_PATHS = [
+    ".cursor/hooks.json",
+    ".cursor/rules/stigmer-tool-approval.mdc",
+];
+// `deriveCaptureMode` is the single capture-vs-deny-gate decision, now shared by
+// BOTH harnesses from `shared/filereview/capture.ts`. Re-exported here so existing
+// Cursor imports (index.ts, the deny-gate-exact-apply seam test) keep resolving
+// from this adapter.
+export { deriveCaptureMode } from "../../shared/filereview/capture.js";
+/**
+ * Turn start: pin the pre-turn working tree behind the baseline ref and author
+ * BASELINE_CAPTURED (harnessId "cursor"). Returns the baseline tree sha for the
+ * turn-end diff.
+ */
+export function captureBaselineToLedger(opts) {
+    return sharedCaptureBaselineToLedger({
+        ...opts,
+        harnessId: HARNESS_ID,
+        excludePaths: CURSOR_RUNNER_OWNED_PATHS,
+    });
+}
+/**
+ * Turn end: capture the change set + author CANDIDATE_CAPTURED, then stamp the
+ * streamed file-edit rows that flowed this turn with the change set id — the
+ * rows stay visible in place as observational records while `file_change_sets`
+ * remains the single decision surface. The working tree is LEFT applied
+ * (Cursor parity).
+ *
+ * The change set is HYBRID (git tree) or CAS-only (non-git): the hook-staged
+ * writes from the cas-observations sidecar this turn ({@link readCasObservations})
+ * — the Cursor analog of deep-agent's `buildCasTurnCaptures` — composed with the
+ * git-tracked diff when `gitWorkspace`. Non-secret staged paths become
+ * `GIT_IGNORED_CAPTURED` (git tree) or `NON_GIT_CAS` (non-git) CAS captures
+ * (before-bytes from the sidecar, after-bytes re-read from disk);
+ * secret-blocked paths become content-less `DIFF_UNREVIEWABLE` entries. The
+ * boundary re-runs {@link partitionIgnoredPathsBySecret} as a fail-closed
+ * backstop, so a secret that ever slipped into the captured set still has its
+ * bytes withheld from durable storage.
+ *
+ * `deniedTokens` are the identities the hook gated this turn (shell/MCP, or a
+ * gitignored delete). A streamed file-edit row whose identity is in that set is
+ * left for the deny-gate reconcile path — it did NOT flow. A flowed gitignored
+ * write is NOT in that set (the hook allowed it), so it is stamped like any
+ * other flowed edit and its captured delta surfaces as a CAS entry in the set.
+ *
+ * `hitlDir`/`storage` are omitted only by callers with no artifact storage
+ * (captureIgnored off); the CAS half is then skipped and this is a git-only
+ * capture exactly as before.
+ *
+ * Mutates `messages` and `status` in place. Returns the captured git changes.
+ */
+export async function captureTurnToLedger(opts) {
+    const { status, gitRoot, executionId, changeSetId, baselineTree, messages, deniedTokens, hitlDir, storage, priorSubAgentToolCallIds, commandProvenance } = opts;
+    const gitWorkspace = opts.gitWorkspace ?? true;
+    // The CAS substrate class for this turn's staged writes: gitignored paths in a
+    // git tree, all touched paths in a non-git workspace.
+    const casCaptureClass = gitWorkspace
+        ? FileCaptureClass.GIT_IGNORED_CAPTURED
+        : FileCaptureClass.NON_GIT_CAS;
+    const { casCaptures, unreviewablePaths } = await buildCasTurnCaptures(gitRoot, hitlDir, storage, casCaptureClass);
+    const changes = await sharedCaptureCandidateToLedger({
+        status,
+        gitRoot,
+        executionId,
+        changeSetId,
+        baselineTree,
+        harnessId: HARNESS_ID,
+        excludePaths: CURSOR_RUNNER_OWNED_PATHS,
+        casCaptures,
+        storage,
+        unreviewablePaths,
+        unreviewableCaptureClass: casCaptureClass,
+        gitWorkspace,
+        commandProvenance,
+    });
+    // Observational rows: the reviewable diff lives on the file_review ledger
+    // (projected to file_change_sets); the streamed file-edit rows that flowed
+    // this turn stay visible in place, stamped with the change set id so clients
+    // badge them and anchor the decision surface. Denied (gitignored-delete/
+    // shell) rows stay on the deny-gate path. Gated on an authored CANDIDATE —
+    // a no-op turn (every edit reverted before the boundary) authors no event,
+    // and a row must never reference a change set that does not exist.
+    if (hasCandidateCaptured(status, changeSetId)) {
+        stampFlowedFileEditRows(messages, deniedTokens, changeSetId);
+        // Sub-agent edit rows fold their files into the SAME parent turn set, so they
+        // carry the same change set id. Walked separately (they live under
+        // subAgentExecutions, not the top-level transcript) and scoped to this turn
+        // via the pre-turn snapshot of seeded sub-agent tool-call ids.
+        for (const sa of status.subAgentExecutions) {
+            stampFlowedFileEditRows(sa.messages, deniedTokens, changeSetId, priorSubAgentToolCallIds);
+        }
+    }
+    return changes;
+}
+/**
+ * Compose this turn's CAS captures from the sidecar the hook staged, mirroring
+ * deep-agent's `buildCasTurnCaptures`: for each non-secret observed path, the
+ * before-bytes come from the sidecar and the after-bytes are re-read from disk now
+ * (`null` = the file was removed after the write). Secret-blocked paths are
+ * returned as `unreviewablePaths`. The secret partition is re-run as a
+ * fail-closed backstop over the observed set. `captureClass` labels each captured
+ * path's provenance (GIT_IGNORED_CAPTURED for a git tree's ignored paths,
+ * NON_GIT_CAS for a non-git workspace).
+ *
+ * Returns empty when the harness has no storage (captureIgnored off) or the
+ * sidecar is empty — leaving the shared capture unchanged.
+ */
+async function buildCasTurnCaptures(gitRoot, hitlDir, storage, captureClass) {
+    if (!hitlDir || !storage)
+        return { casCaptures: [], unreviewablePaths: [] };
+    const { captured, secretPaths } = await readCasObservations(hitlDir);
+    const beforeByPath = new Map(captured.map((c) => [c.path, c.before]));
+    const { capturablePaths, unreviewablePaths } = partitionIgnoredPathsBySecret(beforeByPath.keys(), new Set(secretPaths));
+    const casCaptures = [];
+    for (const relPath of capturablePaths) {
+        const after = await readFileOrNull(join(gitRoot, relPath));
+        casCaptures.push({
+            path: relPath,
+            before: beforeByPath.get(relPath) ?? null,
+            after,
+            captureClass,
+        });
+    }
+    return { casCaptures, unreviewablePaths: [...unreviewablePaths] };
+}
+/** Raw bytes of a file, or `null` when it does not exist (an ADD-then-removed). */
+async function readFileOrNull(absolutePath) {
+    try {
+        return await readFile(absolutePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resume: reconcile the working tree to the change set's DECIDED decisions
+ * (keep approved "after" bytes, snap rejected/undecided back to baseline,
+ * hash-verified), author RECONCILED / FAILED, and release the refs. Delegates to
+ * the shared orchestration with the Cursor harness id + exclude paths.
+ *
+ * `storage` threads the CAS blob store + reader so gitignored (CAS) files in the
+ * change set reconcile from the durable manifest — approved after-blobs written
+ * (hash-verified), rejected files snapped back to their before-blobs. Omit for a
+ * git-only harness/turn; the shared CAS branch is then skipped. The read path is
+ * the same one `exact-apply` already uses (`ArtifactStorage.download`).
+ */
+export function applyCaptureDecisions(opts) {
+    const { storage, ...rest } = opts;
+    return sharedApplyCaptureDecisions({
+        ...rest,
+        harnessId: HARNESS_ID,
+        excludePaths: CURSOR_RUNNER_OWNED_PATHS,
+        storage,
+        readBlob: storage ? casBlobReader(storage) : undefined,
+    });
+}
+// ---------------------------------------------------------------------------
+// Cursor-specific presentation
+// ---------------------------------------------------------------------------
+/**
+ * Stamp every streamed file-edit row (category write/delete) that flowed this
+ * turn with the change set id, so the row stays visible as an observational
+ * record and clients can badge it / anchor the decision surface. Skips:
+ *  - already-stamped rows — the stamp is the idempotency AND cross-turn guard:
+ *    a resume seeds prior turns' rows into this transcript, and re-stamping
+ *    them with this turn's id would mis-attribute them ({@link stampFileEditRow});
+ *  - legacy hidden rows (sessions persisted before stamping existed) — they
+ *    belong to an earlier turn's change set, not this one;
+ *  - denied identities (the deny-gate reconcile path owns those rows);
+ *  - tool-call ids in `skipToolCallIds` — used for sub-agent rows, which lack
+ *    the already-stamped/hidden shields the top-level transcript has, to scope
+ *    the stamp to rows created this turn (the seeded prior sub-agents' ids).
+ */
+function stampFlowedFileEditRows(messages, deniedTokens, changeSetId, skipToolCallIds) {
+    for (const msg of messages) {
+        for (const tc of msg.toolCalls) {
+            if (tc.fileChangeSetId)
+                continue;
+            if (skipToolCallIds?.has(tc.id))
+                continue;
+            if (isToolCallRowHidden(tc))
+                continue;
+            const category = approvalCategory(tc.name);
+            if (category !== "write" && category !== "delete")
+                continue;
+            const args = (tc.args ?? {});
+            const id = toolIdentity(tc.name, tc.mcpServerSlug, args);
+            const token = primaryToken(id.key, id.salient, contentDigest(args));
+            if (deniedTokens.has(token))
+                continue; // denied -> reconcile path owns it
+            stampFileEditRow(tc, changeSetId);
+        }
+    }
+}
+//# sourceMappingURL=capture-flow.js.map

package/dist/activities/execute-cursor/capture-flow.js.map

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

package/dist/activities/execute-cursor/cas-observations.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The Cursor harness's disk-backed observer for gitignored file writes — the
+ * out-of-process analog of the deep-agent `CasCaptureFilesystemBackend`
+ * ({@link ../execute-deep-agent/cas-capture-backend.js}).
+ *
+ * Deep-agent runs the agent in-process, so it records a gitignored file's
+ * pre-turn bytes in an in-memory `CasBeforeMap` at the mutation point (before
+ * `super.write`). Cursor runs the agent as an EXTERNAL CLI subprocess whose only
+ * pre-write interception is the generated preToolUse bash hook — and each hook
+ * invocation is a FRESH, EPHEMERAL process that cannot hold in-memory state
+ * across writes. So Cursor's before-map must be DISK-BACKED: the hook stages each
+ * first-touched gitignored path into a per-turn "cas-observations" sidecar, and
+ * the runner reads it back at the turn boundary.
+ *
+ * The sidecar lives under the session HITL directory
+ * (`~/.stigmer/sessions/{id}/hitl/cas-observations/`), OUTSIDE the user's
+ * workspace — so staged before-bytes and secret markers never land in the repo,
+ * cannot pollute the captured git diff, and are never pushed. It is reset every
+ * turn (alongside the denial ledger) and consumed within the same activity
+ * invocation that produced it; resume reconciles from the durable CAS manifest,
+ * never this scratch. A Temporal retry re-runs the reset and re-observes.
+ *
+ * ONE MODULE OWNS THE ON-DISK FORMAT. Both sides live here so they cannot drift:
+ *  - the READER ({@link readCasObservations}) the runner boundary calls;
+ *  - the WRITER-SCRIPT GENERATOR ({@link buildObservationStagingScript}) whose
+ *    output the hook embeds and runs on the runner's own Node binary. The writer
+ *    classifies secrets from the SAME {@link isSecretLikePath} pattern arrays the
+ *    boundary backstop uses (`shared/filereview/secret-paths.ts`), reconstructed
+ *    as byte-identical `RegExp`s — no bash-regex, no divergence.
+ *
+ * Each observed path becomes one entry:
+ *  - `captured`  — a non-secret gitignored write/edit: `{path, kind, existed}`
+ *    metadata plus a `.blob` of the pre-turn bytes (omitted for an ADD, where the
+ *    file did not exist). First-touch-wins via atomic exclusive-create, so
+ *    repeated edits to one path keep the true pre-turn before.
+ *  - `secret`    — a secret-like gitignored path the hook hard-blocked (denied,
+ *    nothing written): `{path, kind}` only. The boundary authors it as a
+ *    content-less `DIFF_UNREVIEWABLE` change; its bytes never reach storage.
+ *
+ * @since File-Change HITL Redesign (Cursor CAS parity — DD-18)
+ */
+/** Sidecar directory name under the session HITL dir. */
+export declare const CAS_OBSERVATIONS_DIRNAME = "cas-observations";
+/** Absolute path of the per-turn cas-observations sidecar dir. */
+export declare function casObservationsDir(hitlDir: string): string;
+/**
+ * Truncate the cas-observations sidecar to empty for a fresh turn, returning its
+ * path. Called every turn alongside {@link resetDenialLedger} so the boundary
+ * only ever reads observations produced by the current run — deterministic across
+ * HITL reinvocations and Temporal activity retries.
+ */
+export declare function resetCasObservations(hitlDir: string): Promise<string>;
+/** One non-secret gitignored path the hook staged this turn. */
+export interface CasObservationCapture {
+    /** Workspace-root-relative path. */
+    readonly path: string;
+    /** Pre-turn bytes; `null` when the file did not exist before (an ADD). */
+    readonly before: Uint8Array | null;
+}
+/** The turn's staged gitignored observations, split by the hook's secret gate. */
+export interface CasObservations {
+    /** Non-secret paths to capture into CAS (before-bytes in hand). */
+    readonly captured: CasObservationCapture[];
+    /** Secret-like paths the hook hard-blocked (path-only; bytes withheld). */
+    readonly secretPaths: string[];
+}
+/**
+ * Read the cas-observations sidecar the hook wrote during the turn. Missing dir →
+ * no observations. Malformed/partial entries are tolerated and skipped (the hook
+ * writes the blob before the metadata marker, so a present marker implies a
+ * complete blob; a marker whose blob is unexpectedly missing is skipped rather
+ * than mis-captured). Entries are returned in a deterministic (sorted) order.
+ */
+export declare function readCasObservations(hitlDir: string): Promise<CasObservations>;
+/**
+ * Build the standalone Node.js script the hook runs to observe a single
+ * gitignored write — the disk-backed mirror of `CasCaptureFilesystemBackend`'s
+ * `recordBefore` plus the DD-E secret gate.
+ *
+ * Invoked as `printf %s "$SALIENT" | node -e '<this>' <workspaceRoot> <obsDir>`
+ * — the (arbitrary) salient path arrives on stdin so no argv escaping is needed;
+ * the two absolute paths ride argv. Prints one token on stdout for the hook:
+ *  - `captured` — non-secret: staged the pre-turn bytes (first-touch-wins), the
+ *    hook then ALLOWS the write to flow;
+ *  - `secret`   — secret-like: recorded a content-less marker, the hook then
+ *    DENIES with the security message (nothing is written);
+ *  - `error`    — the path escaped the workspace or a filesystem error occurred,
+ *    the hook then fails closed (deny).
+ *
+ * The secret classifier is generated from the SAME
+ * {@link SECRET_BASENAME_PATTERNS}/{@link SECRET_PATH_PATTERNS} the boundary
+ * backstop uses, so the hook-side and boundary-side classifications agree by
+ * construction (a table test locks the equivalence). Authored as a
+ * single-quoted-bash string, so the JS must contain no single quotes.
+ */
+export declare function buildObservationStagingScript(): string;

package/dist/activities/execute-cursor/cas-observations.js

@@ -0,0 +1,184 @@
+/**
+ * The Cursor harness's disk-backed observer for gitignored file writes — the
+ * out-of-process analog of the deep-agent `CasCaptureFilesystemBackend`
+ * ({@link ../execute-deep-agent/cas-capture-backend.js}).
+ *
+ * Deep-agent runs the agent in-process, so it records a gitignored file's
+ * pre-turn bytes in an in-memory `CasBeforeMap` at the mutation point (before
+ * `super.write`). Cursor runs the agent as an EXTERNAL CLI subprocess whose only
+ * pre-write interception is the generated preToolUse bash hook — and each hook
+ * invocation is a FRESH, EPHEMERAL process that cannot hold in-memory state
+ * across writes. So Cursor's before-map must be DISK-BACKED: the hook stages each
+ * first-touched gitignored path into a per-turn "cas-observations" sidecar, and
+ * the runner reads it back at the turn boundary.
+ *
+ * The sidecar lives under the session HITL directory
+ * (`~/.stigmer/sessions/{id}/hitl/cas-observations/`), OUTSIDE the user's
+ * workspace — so staged before-bytes and secret markers never land in the repo,
+ * cannot pollute the captured git diff, and are never pushed. It is reset every
+ * turn (alongside the denial ledger) and consumed within the same activity
+ * invocation that produced it; resume reconciles from the durable CAS manifest,
+ * never this scratch. A Temporal retry re-runs the reset and re-observes.
+ *
+ * ONE MODULE OWNS THE ON-DISK FORMAT. Both sides live here so they cannot drift:
+ *  - the READER ({@link readCasObservations}) the runner boundary calls;
+ *  - the WRITER-SCRIPT GENERATOR ({@link buildObservationStagingScript}) whose
+ *    output the hook embeds and runs on the runner's own Node binary. The writer
+ *    classifies secrets from the SAME {@link isSecretLikePath} pattern arrays the
+ *    boundary backstop uses (`shared/filereview/secret-paths.ts`), reconstructed
+ *    as byte-identical `RegExp`s — no bash-regex, no divergence.
+ *
+ * Each observed path becomes one entry:
+ *  - `captured`  — a non-secret gitignored write/edit: `{path, kind, existed}`
+ *    metadata plus a `.blob` of the pre-turn bytes (omitted for an ADD, where the
+ *    file did not exist). First-touch-wins via atomic exclusive-create, so
+ *    repeated edits to one path keep the true pre-turn before.
+ *  - `secret`    — a secret-like gitignored path the hook hard-blocked (denied,
+ *    nothing written): `{path, kind}` only. The boundary authors it as a
+ *    content-less `DIFF_UNREVIEWABLE` change; its bytes never reach storage.
+ *
+ * @since File-Change HITL Redesign (Cursor CAS parity — DD-18)
+ */
+import { readFile, readdir, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { SECRET_BASENAME_PATTERNS, SECRET_PATH_PATTERNS } from "../../shared/filereview/secret-paths.js";
+/** Sidecar directory name under the session HITL dir. */
+export const CAS_OBSERVATIONS_DIRNAME = "cas-observations";
+/** Suffix of the per-path metadata file (also the atomic first-touch marker). */
+const META_SUFFIX = ".meta.json";
+/** Suffix of the per-path pre-turn bytes blob (present only for a MODIFY). */
+const BLOB_SUFFIX = ".blob";
+/** Absolute path of the per-turn cas-observations sidecar dir. */
+export function casObservationsDir(hitlDir) {
+    return join(hitlDir, CAS_OBSERVATIONS_DIRNAME);
+}
+/**
+ * Truncate the cas-observations sidecar to empty for a fresh turn, returning its
+ * path. Called every turn alongside {@link resetDenialLedger} so the boundary
+ * only ever reads observations produced by the current run — deterministic across
+ * HITL reinvocations and Temporal activity retries.
+ */
+export async function resetCasObservations(hitlDir) {
+    const dir = casObservationsDir(hitlDir);
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+/**
+ * Read the cas-observations sidecar the hook wrote during the turn. Missing dir →
+ * no observations. Malformed/partial entries are tolerated and skipped (the hook
+ * writes the blob before the metadata marker, so a present marker implies a
+ * complete blob; a marker whose blob is unexpectedly missing is skipped rather
+ * than mis-captured). Entries are returned in a deterministic (sorted) order.
+ */
+export async function readCasObservations(hitlDir) {
+    const dir = casObservationsDir(hitlDir);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { captured: [], secretPaths: [] };
+    }
+    const captured = [];
+    const secretPaths = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(META_SUFFIX))
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(await readFile(join(dir, name), "utf-8"));
+        }
+        catch {
+            continue; // partial/garbled marker — tolerate
+        }
+        if (!meta || typeof meta.path !== "string" || !meta.path)
+            continue;
+        if (meta.kind === "secret") {
+            secretPaths.push(meta.path);
+            continue;
+        }
+        if (meta.kind === "captured") {
+            let before = null;
+            if (meta.existed === true) {
+                const blobPath = join(dir, name.slice(0, -META_SUFFIX.length) + BLOB_SUFFIX);
+                try {
+                    before = await readFile(blobPath);
+                }
+                catch {
+                    continue; // marker present but blob missing (mid-hook crash) — skip
+                }
+            }
+            captured.push({ path: meta.path, before });
+        }
+    }
+    return { captured, secretPaths };
+}
+/**
+ * Emit a JS `RegExp` constructor byte-identical to a source pattern, safe to
+ * embed inside a single-quoted bash string (JSON.stringify emits double quotes;
+ * these patterns contain no single quotes).
+ */
+function regexLiteral(re) {
+    return `new RegExp(${JSON.stringify(re.source)},${JSON.stringify(re.flags)})`;
+}
+/**
+ * Build the standalone Node.js script the hook runs to observe a single
+ * gitignored write — the disk-backed mirror of `CasCaptureFilesystemBackend`'s
+ * `recordBefore` plus the DD-E secret gate.
+ *
+ * Invoked as `printf %s "$SALIENT" | node -e '<this>' <workspaceRoot> <obsDir>`
+ * — the (arbitrary) salient path arrives on stdin so no argv escaping is needed;
+ * the two absolute paths ride argv. Prints one token on stdout for the hook:
+ *  - `captured` — non-secret: staged the pre-turn bytes (first-touch-wins), the
+ *    hook then ALLOWS the write to flow;
+ *  - `secret`   — secret-like: recorded a content-less marker, the hook then
+ *    DENIES with the security message (nothing is written);
+ *  - `error`    — the path escaped the workspace or a filesystem error occurred,
+ *    the hook then fails closed (deny).
+ *
+ * The secret classifier is generated from the SAME
+ * {@link SECRET_BASENAME_PATTERNS}/{@link SECRET_PATH_PATTERNS} the boundary
+ * backstop uses, so the hook-side and boundary-side classifications agree by
+ * construction (a table test locks the equivalence). Authored as a
+ * single-quoted-bash string, so the JS must contain no single quotes.
+ */
+export function buildObservationStagingScript() {
+    const base = SECRET_BASENAME_PATTERNS.map(regexLiteral).join(",");
+    const pathPatterns = SECRET_PATH_PATTERNS.map(regexLiteral).join(",");
+    const metaSuffix = JSON.stringify(META_SUFFIX);
+    const blobSuffix = JSON.stringify(BLOB_SUFFIX);
+    return [
+        `const fs=require("fs");const path=require("path");const crypto=require("crypto");`,
+        `const wsRoot=process.argv[1]||"";const obsDir=process.argv[2]||"";`,
+        `let salient="";try{salient=fs.readFileSync(0,"utf8");}catch(e){salient="";}`,
+        `if(!salient||!obsDir){process.stdout.write("error");process.exit(0);}`,
+        // Workspace-relative key, git-consistent: an absolute salient stays put, a
+        // relative one resolves against the workspace root. A path that escapes the
+        // workspace is treated as an error (fail closed) — it should never be flagged
+        // gitignored by `git check-ignore -C <root>` in the first place.
+        `const abs=path.resolve(wsRoot,salient);`,
+        `let rel=path.relative(wsRoot,abs).split(path.sep).join("/");`,
+        `if(!rel||rel===".."||rel.startsWith("../")){process.stdout.write("error");process.exit(0);}`,
+        // --- secret classifier: byte-identical mirror of isSecretLikePath ---
+        `const baseName=(p)=>{const n=p.replace(/\\\\/g,"/");const i=n.lastIndexOf("/");return i>=0?n.slice(i+1):n;};`,
+        `const BASE=[${base}];const PATHP=[${pathPatterns}];`,
+        `const isSecret=(p)=>{if(!p)return true;const nm=p.replace(/\\\\/g,"/");const b=baseName(nm).toLowerCase();for(const r of BASE){if(r.test(b))return true;}const lp=nm.toLowerCase();for(const r of PATHP){if(r.test(lp))return true;}return false;};`,
+        `const key=crypto.createHash("sha256").update(rel,"utf8").digest("hex");`,
+        `const metaPath=path.join(obsDir,key+${metaSuffix});const blobPath=path.join(obsDir,key+${blobSuffix});`,
+        `try{fs.mkdirSync(obsDir,{recursive:true});}catch(e){}`,
+        // Secret: record a content-less marker (idempotent) and signal a hard-block.
+        `if(isSecret(rel)){try{fs.writeFileSync(metaPath,JSON.stringify({path:rel,kind:"secret"}),{flag:"wx"});}catch(e){}process.stdout.write("secret");process.exit(0);}`,
+        // Non-secret: first-touch-wins. A prior marker means this path is already
+        // observed (a later edit) — leave the true pre-turn before intact.
+        `if(fs.existsSync(metaPath)){process.stdout.write("captured");process.exit(0);}`,
+        // Read the pre-turn bytes NOW (the write has not applied — this is preToolUse
+        // and the first touch). Missing file = an ADD (before is null).
+        `let existed=false;let before=null;try{before=fs.readFileSync(abs);existed=true;}catch(e){existed=false;}`,
+        // Write the blob BEFORE the marker, so a present marker always implies a
+        // complete blob. The wx marker is the atomic commit + first-touch lock.
+        `try{if(existed){fs.writeFileSync(blobPath,before);}fs.writeFileSync(metaPath,JSON.stringify({path:rel,kind:"captured",existed:existed}),{flag:"wx"});}catch(e){if(e&&e.code==="EEXIST"){process.stdout.write("captured");process.exit(0);}process.stdout.write("error");process.exit(0);}`,
+        `process.stdout.write("captured");`,
+    ].join("");
+}
+//# sourceMappingURL=cas-observations.js.map

package/dist/activities/execute-cursor/cas-observations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cas-observations.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/cas-observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAEzG,yDAAyD;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAE3D,iFAAiF;AACjF,MAAM,WAAW,GAAG,YAAY,CAAC;AACjC,8EAA8E;AAC9E,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,kEAAkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAI,CAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe;IACxD,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC;AAkBD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,MAAM,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,SAAS;QAC1C,IAAI,IAA2D,CAAC;QAChE,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9D,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,oCAAoC;QAChD,CAAC;QACD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEnE,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,IAAI,MAAM,GAAsB,IAAI,CAAC;YACrC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC;gBAC7E,IAAI,CAAC;oBACH,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACpC,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS,CAAC,0DAA0D;gBACtE,CAAC;YACH,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,EAAU;IAC9B,OAAO,cAAc,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,IAAI,GAAG,wBAAwB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC/C,OAAO;QACL,mFAAmF;QACnF,oEAAoE;QACpE,6EAA6E;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,4EAA4E;QAC5E,8EAA8E;QAC9E,iEAAiE;QACjE,yCAAyC;QACzC,8DAA8D;QAC9D,6FAA6F;QAC7F,uEAAuE;QACvE,8GAA8G;QAC9G,eAAe,IAAI,kBAAkB,YAAY,IAAI;QACrD,qPAAqP;QACrP,yEAAyE;QACzE,uCAAuC,UAAU,yCAAyC,UAAU,IAAI;QACxG,uDAAuD;QACvD,6EAA6E;QAC7E,mKAAmK;QACnK,0EAA0E;QAC1E,mEAAmE;QACnE,gFAAgF;QAChF,8EAA8E;QAC9E,gEAAgE;QAChE,0GAA0G;QAC1G,yEAAyE;QACzE,wEAAwE;QACxE,2RAA2R;QAC3R,mCAAmC;KACpC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACb,CAAC"}

package/dist/activities/execute-cursor/command-provenance.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Approved-command turn provenance (DD-28): the runner-owned qualification for
+ * the auto-keep policy.
+ *
+ * A turn whose ONLY mutation source was shell commands the human had already
+ * authorized should not re-gate its file effects at the turn-boundary review —
+ * the user consented to the command, and the command's file effects are the
+ * consented outcome. The server cannot derive this itself (tool calls carry no
+ * turn marker), so the runner — the only component that owns turn scoping —
+ * derives the facts here and attaches them to the CANDIDATE_CAPTURED event as
+ * {@link TurnCommandProvenance}.
+ *
+ * TRUST BOUNDARY. This module asserts turn FACTS (which tools ran this turn),
+ * the same trust level as the captured bytes themselves. It never asserts
+ * CONSENT: `consentToolCallIds` merely POINT at transcript rows whose
+ * `approval_action` was authored by the server's SubmitApproval (and is
+ * preserved against runner writes) — the backend re-verifies every claimed row
+ * against that server-owned record before authoring the policy decision, so a
+ * runner cannot mint authorization it was never given.
+ *
+ * FAIL-CLOSED. Every uncertainty disqualifies (returns undefined → the set
+ * reviews manually, exactly as before DD-28): a file-tool call, an MCP tool, a
+ * sub-agent delegation, an unrecognized tool name, or an executed shell command
+ * with no provable consent source. Being conservative here costs only an extra
+ * review; being permissive would silently waive one.
+ */
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+export interface CommandProvenanceInputs {
+    /**
+     * The full transcript at capture time. Turn scoping is positional: messages
+     * from index {@link turnStartIndex} onward were produced by THIS turn's
+     * stream; everything before was seeded from prior turns. Lease consent rows
+     * (APPROVE_ALL) are looked up across the WHOLE transcript — a lease is
+     * run-lifetime, its granting row usually lives in a prior turn.
+     */
+    readonly messages: readonly AgentMessage[];
+    /** Index of the first message created by this turn's stream. */
+    readonly turnStartIndex: number;
+    /**
+     * Identity tokens the hook denied THIS turn (the denial ledger). A denied
+     * shell row never executed — it is this turn's pending gate, not a mutation
+     * source — so it neither needs consent nor disqualifies.
+     */
+    readonly deniedTokens: ReadonlySet<string>;
+    /**
+     * Grant token → the tool-call id of the approval row that minted the grant
+     * (the row carrying the server-authored approval_action). An executed shell
+     * command whose identity token is a key here was authorized by that
+     * per-command approval.
+     */
+    readonly grantTokenToConsentId: ReadonlyMap<string, string>;
+    /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+    readonly globalBypass: boolean;
+}
+/**
+ * Derive the {@link TurnCommandProvenance} for the turn, or undefined when the
+ * turn does not qualify (any non-shell mutation-capable call, any unknown tool,
+ * any executed command without a provable consent source, or no executed
+ * consented command at all).
+ */
+export declare function deriveTurnCommandProvenance(inputs: CommandProvenanceInputs): TurnCommandProvenance | undefined;