@stigmer/runner 3.12.1 → 3.12.2

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

@@ -1,5 +1,6 @@
 /**
- * The Cursor harness's disk-backed observer for gitignored file writes — the
+ * The Cursor harness's disk-backed observer for CAS-owned file mutations —
+ * gitignored / non-git writes, and (issue #303) pre-delete byte capture — the
  * out-of-process analog of the deep-agent `CasCaptureFilesystemBackend`
  * ({@link ../execute-deep-agent/cas-capture-backend.js}).
  *
@@ -185,14 +186,19 @@ export function buildSecretClassifyScript(): string {
 
 /**
  * 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.
+ * CAS-owned mutation — the disk-backed mirror of `CasCaptureFilesystemBackend`'s
+ * `recordBefore` plus the DD-E secret gate. Staging is mutation-agnostic: it
+ * records the PRE-mutation bytes, so the hook runs it for a write/edit and —
+ * issue #303 — for a delete (whose before-bytes exist only until the tool runs;
+ * the boundary later reads after=null and authors the DELETE). The hook's
+ * delete arm pre-classifies secrets and never invokes this for a secret-like
+ * delete (a gated delete must not leave a "secret" marker in the sidecar).
  *
  * 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;
+ *    hook then ALLOWS the mutation 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,

package/src/activities/execute-cursor/hook-script.ts

@@ -574,9 +574,8 @@ if echo "$STATE" | grep -q '"captureIgnored":true'; then
 fi
 # gitWorkspace selects the capture substrate (Slice 2c). Default true when the
 # key is absent (older state files). When false the workspace is NOT a git tree:
-# there is no git snapshot, so EVERY file write is CAS-staged below (not only
-# gitignored ones), the git-tracked flow arm is skipped, and a delete stays gated
-# (no CAS delete-capture path, parity with the deep-agent).
+# there is no git snapshot, so EVERY file write/delete is CAS-staged below (not
+# only gitignored ones) and the git-tracked flow arm is skipped.
 GIT_WORKSPACE=true
 if echo "$STATE" | grep -q '"gitWorkspace":false'; then
   GIT_WORKSPACE=false
@@ -597,9 +596,10 @@ fi
 # secret-like one must be hard-blocked in every mode. WHICH writes are CAS-owned
 # depends on the substrate: in a git tree it is only the GITIGNORED writes (git
 # captures the tracked ones); in a NON-GIT workspace it is EVERY write (there is
-# no git snapshot). Only a built-in write/edit (category "write") takes this arm;
-# deletes and shell/MCP stay on the deny-gate below (parity with the deep-agent
-# approval gate). The staging runs on the runner's own Node binary (the
+# no git snapshot). Only a built-in write/edit (category "write") takes THIS arm;
+# deletes take their own staging arm just below (issue #303), shell/MCP stay on
+# the deny-gate (parity with the deep-agent approval gate). The staging runs on
+# the runner's own Node binary (the
 # disk-backed mirror of CasCaptureFilesystemBackend.recordBefore): the salient
 # path rides stdin (no argv escaping), the workspace root and the per-turn
 # cas-observations dir ride argv. "captured" -> allow (apply-then-review);
@@ -629,6 +629,32 @@ if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "write" ] && [ -n "$SALIEN
   fi
 fi
 
+# --- Capture mode: observe CAS-owned deletes for review (issue #303) --------
+# The delete twin of the write arm above — a non-secret CAS-owned delete stages
+# its before-bytes (the one moment they still exist on disk) and flows; the
+# turn boundary then reads after=null and authors a reviewable, restorable
+# DELETE entry. One deliberate difference from the write arm: the path is
+# classified for secret-likeness BEFORE any staging touches the sidecar. A
+# secret-like delete must stay on the deny-gate below where a human may still
+# approve it (its args expose no secret content, unlike a write) — staging it
+# would both persist the secret before-bytes and mark the sidecar "secret",
+# making the boundary author a blocking DIFF_UNREVIEWABLE for a merely-gated
+# delete. Every failure mode (secret, classify error, staging error) falls
+# through to the deny-gate rather than denying here, so grants and leases keep
+# applying to a gated delete exactly as before this arm existed; the eventual
+# resolution records its own ledger kind.
+if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "delete" ] && [ -n "$SALIENT" ] && { [ "$GIT_WORKSPACE" = "false" ] || __stigmer_is_gitignored "$SALIENT"; }; then
+  DELETE_SECRET_RESULT=$(printf '%s' "$SALIENT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${secretClassifyScript}' 2>/dev/null || echo error)
+  if [ "$DELETE_SECRET_RESULT" = "ok" ]; then
+    OBS_DIR="$(dirname "$STATE_FILE")/${CAS_OBSERVATIONS_DIRNAME}"
+    OBS_RESULT=$(printf '%s' "$SALIENT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${observationStagingScript}' "$GIT_ROOT" "$OBS_DIR" 2>/dev/null || echo error)
+    if [ "$OBS_RESULT" = "captured" ]; then
+      echo '{"permission":"allow"}'
+      exit 0
+    fi
+  fi
+fi
+
 # --- 1a. MCP capability manifest: enabled_tools (issue #350) ---
 # Runs BEFORE the auto-approve-all shortcut and every grant check because
 # enabled_tools is a capability manifest, not an approval gate: no bypass may
@@ -700,13 +726,13 @@ if [ -n "$CATEGORY" ]; then
   # Capture mode (GIT tree only): a git-tracked file mutation (write/edit/delete)
   # flows freely — the runner captures the whole change set with git at the turn
   # boundary and gates it per-file for review. A gitignored path is invisible to
-  # that git snapshot: a non-secret gitignored WRITE was already handled above
-  # (staged + allowed, or hard-blocked) when captureIgnored is on; here it only
-  # reaches the deny-gate when captureIgnored is off (no artifact storage) or it is
-  # a gitignored DELETE (no CAS capture path, parity with deep-agent). shell
-  # (category "shell") never takes this branch and stays gated as always. In a
-  # NON-GIT workspace this arm is skipped entirely (there is no git diff): writes
-  # were CAS-staged above and a delete falls through to the deny-gate.
+  # that git snapshot: a non-secret gitignored WRITE or DELETE was already
+  # handled above (staged + allowed, hard-blocked, or left to fall through) when
+  # captureIgnored is on; here it only reaches the deny-gate when captureIgnored
+  # is off (no artifact storage), or it is a secret-like DELETE (approvable, but
+  # never staged — issue #303). shell (category "shell") never takes this branch
+  # and stays gated as always. In a NON-GIT workspace this arm is skipped
+  # entirely (there is no git diff): writes and deletes were CAS-staged above.
   if [ "$CAPTURE_MODE" = "true" ] && [ "$GIT_WORKSPACE" = "true" ] && { [ "$CATEGORY" = "write" ] || [ "$CATEGORY" = "delete" ]; }; then
     if ! __stigmer_is_gitignored "$SALIENT"; then
       echo '{"permission":"allow"}'

package/src/activities/execute-cursor/skill-resolver.ts

@@ -7,9 +7,17 @@
  * - Uses a platform-managed directory outside the workspace
  * - Ensures the workspace `.stigmer` symlink (see stigmer-link.ts)
  * - Returns metadata for prompt injection
+ *
+ * The mount is cached by the skill's content-addressed version hash
+ * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps
+ * latest-version freshness), but the artifact download and file rewrite are
+ * skipped when the mounted content's hash already matches. The session's
+ * platform dir survives across executions, so on an active session every
+ * message after the first pays a metadata read instead of a full artifact
+ * transfer.
  */
 
-import { mkdir, writeFile, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -21,6 +29,25 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 
 const SKILLS_SUBDIR = "skills";
 
+/**
+ * Marker recording what a skill's mount directory currently holds. Written
+ * LAST, after every file of the mount landed — a crash mid-write leaves no
+ * marker, so the next execution remounts instead of trusting a partial tree.
+ */
+const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+
+interface MountMarker {
+  /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
+  versionHash: string;
+  /**
+   * Whether the artifact's files are part of the mount. `false` when the
+   * skill has no artifact OR when the download failed and the mount fell
+   * back to SKILL.md only — the latter makes the next execution retry the
+   * download rather than cache the degraded mount.
+   */
+  artifactMounted: boolean;
+}
+
 export interface SkillResolverOptions {
   sessionId: string;
   primaryWorkspaceDir: string;
@@ -61,11 +88,34 @@ export async function resolveSkills(
   for (const ref of skillRefs) {
     try {
       const skill = await client.getSkillByReference(ref);
+      const spec = skill.spec;
+      if (!spec?.skillMd) {
+        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
+        continue;
+      }
+
+      const name = spec.name || skill.metadata?.slug || "unknown";
+      const skillDir = join(skillsDir, name);
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
+      const meta: SkillMetadata = {
+        name,
+        description: spec.description || `Skill: ${name}`,
+        path: join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md"),
+      };
+
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        results.push(meta);
+        console.log(
+          `[resolveSkills] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        continue;
+      }
 
       let artifactBytes: Uint8Array | undefined;
-      if (skill.status?.artifactStorageKey) {
+      if (wantsArtifact) {
         try {
-          const resp = await client.getSkillArtifact(skill.status.artifactStorageKey);
+          const resp = await client.getSkillArtifact(skill.status!.artifactStorageKey);
           if (resp.artifact && resp.artifact.length > 0) {
             artifactBytes = resp.artifact;
           }
@@ -77,13 +127,9 @@ export async function resolveSkills(
         }
       }
 
-      const meta = await writeSkill(skill, skillsDir, options.primaryWorkspaceDir, artifactBytes);
-      if (meta) {
-        results.push(meta);
-        console.log(`[resolveSkills] wrote skill: ${meta.name} -> ${meta.path}`);
-      } else {
-        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
-      }
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      results.push(meta);
+      console.log(`[resolveSkills] wrote skill: ${name} -> ${meta.path}`);
     } catch (err) {
       console.warn(
         `[resolveSkills] failed to resolve skill ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
@@ -98,24 +144,47 @@ export async function resolveSkills(
   return results;
 }
 
-async function writeSkill(
+/**
+ * Whether the mount at `skillDir` already holds this version's content.
+ *
+ * Fresh means: the marker's hash matches AND the mount isn't a degraded
+ * SKILL.md-only fallback when the skill does carry an artifact. Any read or
+ * parse failure counts as stale — the remount is the safe default.
+ */
+async function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact: boolean): Promise<boolean> {
+  try {
+    const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
+    const marker = JSON.parse(raw) as Partial<MountMarker>;
+    return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * (Re)write a skill's mount directory from scratch.
+ *
+ * The directory is removed first so files deleted between versions don't
+ * linger in the mount, then SKILL.md and the artifact files are written, and
+ * the marker is stamped LAST (see MOUNT_MARKER_FILE for the crash-safety
+ * contract). SKILL.md always comes from `spec.skillMd` — the server's
+ * authoritative copy — never from the zip; both the zip's SKILL.md and any
+ * stray marker-named entry are excluded from extraction so the mount's
+ * ownership of those two files is unconditional.
+ */
+async function writeSkillMount(
   skill: Skill,
-  skillsDir: string,
-  workspaceDir: string,
-  artifactBytes?: Uint8Array,
-): Promise<SkillMetadata | null> {
-  const spec = skill.spec;
-  if (!spec?.skillMd) return null;
-
-  const name = spec.name || skill.metadata?.slug || "unknown";
-  const skillDir = join(skillsDir, name);
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await rm(skillDir, { recursive: true, force: true });
   await mkdir(skillDir, { recursive: true });
 
-  const skillMdPath = join(skillDir, "SKILL.md");
-  await writeFile(skillMdPath, spec.skillMd, "utf-8");
+  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
 
-  if (artifactBytes && artifactBytes.length > 0) {
-    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md"] });
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
     for (const entry of entries) {
       const filePath = join(skillDir, entry.path);
       await mkdir(dirname(filePath), { recursive: true });
@@ -123,13 +192,11 @@ async function writeSkill(
     }
   }
 
-  const relativePath = join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md");
-
-  return {
-    name,
-    description: spec.description || `Skill: ${name}`,
-    path: relativePath,
-  };
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+  }
 }
 
 /**

package/src/activities/execute-deep-agent/cas-capture-backend.ts

@@ -21,7 +21,9 @@
  *
  * deepagents mutates only via `write` (create/overwrite) and `edit` (modify);
  * there is no backend delete/rename, so this observes CREATE and MODIFY. A
- * gitignored delete can only arrive via shell, which stays on the approval gate.
+ * delete-category tool consequently cannot be observed here — the approval gate
+ * records its before-bytes at authorization time instead (`captureDeleteBefore`,
+ * issue #303). A delete via shell (`rm`) stays on the approval gate as always.
  *
  * @since File-Change HITL Redesign (Phase 3 — CAS deep-agent wiring); sub-agent
  * gitignored capture parity (Session 26, DD-19); shell restore (issue #248)

package/src/activities/execute-deep-agent/setup.ts

@@ -676,6 +676,14 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
           isCapturablePath,
           captureIgnored: captureMode && !!artifactStorage,
           recordBlockedSecret: (rawPath: string) => casObserver.recordBlockedSecret(rawPath),
+          // Pre-delete byte capture (issue #303): deepagents has no backend
+          // delete method for the CAS backend to observe, so a flowing delete's
+          // before-bytes are recorded by the gate at authorization time, through
+          // the SAME shared observer — the turn boundary then reads after=null
+          // and authors a reviewable, restorable DELETE. recordBefore's own
+          // ownership predicate (gitignored-only in a git tree, everything in
+          // non-git) agrees with the gate's not-capturable condition.
+          captureDeleteBefore: (rawPath: string) => casObserver.recordBefore(rawPath),
           unattended,
           unattendedSkips,
         }

package/src/activities/execute-deep-agent/subagent-wiring.ts

@@ -110,19 +110,26 @@ export function buildSubAgentMiddleware(
   stack.push(createToolTruncationMiddleware(options.toolTruncation));
 
   if (options.approvalGate) {
-    // captureIgnored (DD-19): a sub-agent flows gitignored writes into CAS iff a
-    // CAS observer backs its filesystem backend (compileSubagents passes this as
+    // captureIgnored (DD-19): a sub-agent flows gitignored writes — and, since
+    // issue #303, non-secret CAS-owned deletes — into CAS iff a CAS observer
+    // backs its filesystem backend (compileSubagents passes this as
     // `!!casObserver`). When true, inherit the parent gate verbatim so its
-    // captureIgnored + recordBlockedSecret feed the SAME shared observer that
-    // backs the sub-agent's writes. When false (default; non-capture mode, or no
-    // observer), force CAS routing off and drop the blocked-secret sink so
-    // gitignored paths stay on the interrupt gate — a flowed gitignored edit on an
-    // unobserved backend would apply unobserved, unreviewable bytes. Sub-agent
-    // git-tracked edits are always captured by the backend-agnostic boundary diff.
+    // captureIgnored + recordBlockedSecret + captureDeleteBefore feed the SAME
+    // shared observer that backs the sub-agent's writes. When false (default;
+    // non-capture mode, or no observer), force CAS routing off and drop both
+    // observer sinks so gitignored paths stay on the interrupt gate — a flowed
+    // gitignored edit on an unobserved backend would apply unobserved,
+    // unreviewable bytes. Sub-agent git-tracked edits are always captured by
+    // the backend-agnostic boundary diff.
     stack.push(createApprovalGateMiddleware(
       options.captureIgnored
         ? options.approvalGate
-        : { ...options.approvalGate, captureIgnored: false, recordBlockedSecret: undefined },
+        : {
+            ...options.approvalGate,
+            captureIgnored: false,
+            recordBlockedSecret: undefined,
+            captureDeleteBefore: undefined,
+          },
     ));
   }