@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.1

package/src/activities/execute-cursor/capture-flow.ts

@@ -0,0 +1,323 @@
+/**
+ * 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 type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { FileChangeSet, TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+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,
+  type CaptureResumeResult,
+} from "../../shared/filereview/capture.js";
+import { hasCandidateCaptured } from "../../shared/filereview/events.js";
+import { partitionIgnoredPathsBySecret } from "../../shared/filereview/secret-paths.js";
+import { casBlobReader, type CasPathCapture } from "../../shared/filereview/cas-substrate.js";
+import type { GitSubstrateChange as GitCapturedChange } from "../../shared/filereview/git-substrate.js";
+import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+
+export type { CaptureResumeResult };
+
+/** 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: readonly string[] = [
+  ".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: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSetId: string;
+  /** True (default) for a git work tree; false for a CAS-only non-git workspace. */
+  readonly gitWorkspace?: boolean;
+}): Promise<string> {
+  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: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSetId: string;
+  readonly baselineTree: string;
+  readonly messages: AgentMessage[];
+  readonly deniedTokens: ReadonlySet<string>;
+  readonly hitlDir?: string;
+  readonly storage?: ArtifactStorage;
+  /**
+   * Sub-agent tool-call ids that existed BEFORE this turn's stream (the seeded
+   * prior sub-agents). Sub-agent edit rows created this turn are stamped with the
+   * parent change set id; rows in this set are skipped so a resume never
+   * re-stamps a prior turn's sub-agent rows. Omit when there are no prior
+   * sub-agents.
+   */
+  readonly priorSubAgentToolCallIds?: ReadonlySet<string>;
+  /**
+   * True (default) for a git work tree — the candidate is the git diff composed
+   * with the gitignored CAS captures (`GIT_IGNORED_CAPTURED`). False for a non-git
+   * workspace (Slice 2c): there is no git diff, so the whole change set is the CAS
+   * captures the hook staged for EVERY touched path (`NON_GIT_CAS`).
+   */
+  readonly gitWorkspace?: boolean;
+  /**
+   * The approved-command turn facts (DD-28), derived by the caller from the
+   * turn's tool calls ({@link ../command-provenance.js}). Present only when the
+   * turn qualifies; carried verbatim to the CANDIDATE event.
+   */
+  readonly commandProvenance?: TurnCommandProvenance;
+}): Promise<readonly GitCapturedChange[]> {
+  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: string,
+  hitlDir: string | undefined,
+  storage: ArtifactStorage | undefined,
+  captureClass: FileCaptureClass,
+): Promise<{ casCaptures: CasPathCapture[]; unreviewablePaths: string[] }> {
+  if (!hitlDir || !storage) return { casCaptures: [], unreviewablePaths: [] };
+
+  const { captured, secretPaths } = await readCasObservations(hitlDir);
+  const beforeByPath = new Map(captured.map((c) => [c.path, c.before] as const));
+  const { capturablePaths, unreviewablePaths } = partitionIgnoredPathsBySecret(
+    beforeByPath.keys(),
+    new Set(secretPaths),
+  );
+
+  const casCaptures: CasPathCapture[] = [];
+  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: string): Promise<Uint8Array | null> {
+  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: {
+  readonly status: AgentExecutionStatus;
+  readonly gitRoot: string;
+  readonly executionId: string;
+  readonly changeSet: FileChangeSet;
+  readonly storage?: ArtifactStorage;
+  /**
+   * True (default) for a git work tree; false for a CAS-only non-git workspace
+   * (Slice 2c). When false the reconcile never consults git refs — it is driven
+   * entirely by the durable CAS manifest.
+   */
+  readonly gitWorkspace?: boolean;
+}): Promise<CaptureResumeResult> {
+  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: readonly AgentMessage[],
+  deniedTokens: ReadonlySet<string>,
+  changeSetId: string,
+  skipToolCallIds?: ReadonlySet<string>,
+): void {
+  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 ?? {}) as Record<string, unknown>;
+      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);
+    }
+  }
+}

package/src/activities/execute-cursor/cas-observations.ts

@@ -0,0 +1,204 @@
+/**
+ * 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: string): string {
+  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: string): Promise<string> {
+  const dir = casObservationsDir(hitlDir);
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+/** 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 async function readCasObservations(hitlDir: string): Promise<CasObservations> {
+  const dir = casObservationsDir(hitlDir);
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return { captured: [], secretPaths: [] };
+  }
+
+  const captured: CasObservationCapture[] = [];
+  const secretPaths: string[] = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith(META_SUFFIX)) continue;
+    let meta: { path?: unknown; kind?: unknown; existed?: unknown };
+    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: Uint8Array | null = 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: RegExp): string {
+  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(): string {
+  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("");
+}