@stigmer/runner 3.0.8-dev.20260612082024 → 3.0.8-dev.20260612122433

package/dist/activities/execute-cursor/workspace-setup.js

@@ -1,61 +1,181 @@
 /**
- * Writes Cursor hooks configuration and scripts to the workspace.
- *
- * Before creating or resuming a Cursor Agent, the cursor-runner writes:
- * 1. .cursor/hooks.json — declares the preToolUse hook
- * 2. .cursor/hooks/stigmer-approval.sh — the hook script
- * 3. .cursor/hooks/stigmer-approval-state.json — approval state for the hook
- * 4. .cursor/hooks/stigmer-denials.jsonl — per-turn denial ledger (reset here,
- *    appended by the hook on each deny, read back by the activity)
- *
- * This setup enables the durable HITL model: the hook denies tools that need
- * approval and records each denial to the ledger; the activity reads the ledger,
- * marks the gated tool calls WAITING_APPROVAL (the backend then projects
- * pending_approvals from that status), and returns to the workflow. On
- * reinvocation the state file is updated with the approved tools so the hook
- * allows them.
- */
-import { writeFile, mkdir, chmod } from "node:fs/promises";
+ * Installs and tears down the Cursor HITL approval gate around an agent turn.
+ *
+ * The gate has two surfaces, kept deliberately separate (issue #173):
+ *
+ * 1. Runner-owned artifacts — the hook script, approval-state file, and denial
+ *    ledger — live in the session's HITL directory OUTSIDE the user's workspace
+ *    (`~/.stigmer/sessions/{id}/hitl/`). They never touch the attached repo.
+ *
+ * 2. Workspace surface — a single `.cursor/hooks.json` written into the
+ *    workspace, because the Cursor SDK only loads project hooks from that
+ *    hard-coded path. It is kept minimal, MERGED with any pre-existing user
+ *    hooks.json, points at the hook script by ABSOLUTE path (so multi-root IDE
+ *    windows can always find it instead of failing closed), and is RESTORED to
+ *    its original content when the turn ends.
+ *
+ * Why this shape. The previous design wrote all four files into the workspace
+ * with a repo-relative hook command and never cleaned up. For a local-folder
+ * workspace (the user's real repo, often open in their Cursor IDE) that gated
+ * the user's own IDE, ingested the IDE's tool calls into the denial ledger,
+ * failed closed in multi-root windows (relative path → exit 127), and left the
+ * gate behind after the session. Relocating the artifacts, scoping the hook to
+ * the runner's own process (see hook-script.ts), and restoring hooks.json after
+ * every turn together leave the user's repo and tooling untouched.
+ *
+ * Durability model: the install runs before every agent create/resume (and on
+ * every HITL reinvocation / Temporal activity retry); the teardown runs in the
+ * activity's finally. Each turn snapshots and restores independently, so the
+ * repo is byte-identical between turns. If a crash skips teardown, the leftover
+ * hooks.json is inert: the scope guard allows every invocation once the runner
+ * PID is gone, and the relocated artifacts are not in the repo.
+ */
+import { writeFile, readFile, mkdir, chmod, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { generateHookScript } from "./hook-script.js";
 import { writeApprovalStateFile, resetDenialLedger } from "./approval-state.js";
-const HOOKS_DIR = ".cursor";
-const HOOKS_SCRIPTS_DIR = ".cursor/hooks";
+const CURSOR_DIR = ".cursor";
 const HOOKS_CONFIG_FILE = "hooks.json";
 const HOOK_SCRIPT_FILE = "stigmer-approval.sh";
+/** preToolUse hook timeout (seconds) — the script is a quick local decision. */
+const HOOK_TIMEOUT_SECONDS = 10;
 /**
- * Write the complete hooks setup to the workspace directory.
- *
- * Creates or overwrites:
- * - .cursor/hooks.json (hooks configuration)
- * - .cursor/hooks/stigmer-approval.sh (hook script, executable)
- * - .cursor/hooks/stigmer-approval-state.json (approval state)
- */
-export async function writeHooksToWorkspace(workspaceRoot, approvalState) {
-    const hooksDir = join(workspaceRoot, HOOKS_DIR);
-    const scriptsDir = join(workspaceRoot, HOOKS_SCRIPTS_DIR);
-    await mkdir(hooksDir, { recursive: true });
-    await mkdir(scriptsDir, { recursive: true });
-    const stateFilePath = await writeApprovalStateFile(workspaceRoot, approvalState);
-    // Reset the denial ledger for this turn (co-located with the state-file write
-    // so the runner only reads denials produced by the current run, even across
-    // HITL reinvocations on the durable workspace and Temporal activity retries).
-    const ledgerFilePath = await resetDenialLedger(workspaceRoot);
-    const hookScriptPath = join(scriptsDir, HOOK_SCRIPT_FILE);
-    await writeFile(hookScriptPath, generateHookScript(stateFilePath, ledgerFilePath), "utf-8");
+ * Install the HITL approval gate for one agent turn.
+ *
+ * Writes the runner-owned artifacts into {@link hitlDir} and installs the merged
+ * `.cursor/hooks.json` into {@link workspaceRoot}, returning a handle that
+ * {@link removeHitlGate} uses to restore the workspace afterward.
+ */
+export async function installHitlGate(params) {
+    const { workspaceRoot, hitlDir, approvalState, runnerPid } = params;
+    const scriptPath = await writeHitlArtifacts(hitlDir, approvalState, runnerPid);
+    return installWorkspaceHook(workspaceRoot, scriptPath);
+}
+/**
+ * Restore the workspace to its pre-turn state.
+ *
+ * Best-effort and never throws: a teardown failure must not fail the execution,
+ * and a leftover hooks.json is inert anyway (see the module doc).
+ */
+export async function removeHitlGate(handle) {
+    try {
+        if (handle.restoreTo === null) {
+            await rm(handle.hooksJsonPath, { force: true });
+        }
+        else {
+            await writeFile(handle.hooksJsonPath, handle.restoreTo, "utf-8");
+        }
+    }
+    catch (err) {
+        console.warn(`removeHitlGate: failed to restore ${handle.hooksJsonPath} (non-fatal): ` +
+            `${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Write the runner-owned gate artifacts (approval-state file, fresh denial
+ * ledger, hook script) into the session HITL directory and return the absolute
+ * hook-script path. The script is regenerated every turn so the current runner
+ * PID and the current state-file/ledger paths are always baked in.
+ */
+async function writeHitlArtifacts(hitlDir, approvalState, runnerPid) {
+    await mkdir(hitlDir, { recursive: true });
+    const stateFilePath = await writeApprovalStateFile(hitlDir, approvalState);
+    // Reset the denial ledger for this turn so the runner only reads denials
+    // produced by the current run, even across HITL reinvocations on the durable
+    // HITL directory and Temporal activity retries.
+    const ledgerFilePath = await resetDenialLedger(hitlDir);
+    const hookScriptPath = join(hitlDir, HOOK_SCRIPT_FILE);
+    await writeFile(hookScriptPath, generateHookScript(stateFilePath, ledgerFilePath, runnerPid), "utf-8");
     await chmod(hookScriptPath, 0o755);
-    const hooksConfig = {
-        version: 1,
-        hooks: {
-            preToolUse: [
-                {
-                    command: `.cursor/hooks/${HOOK_SCRIPT_FILE}`,
-                    timeout: 10,
-                    failClosed: true,
-                },
-            ],
-        },
-    };
-    await writeFile(join(hooksDir, HOOKS_CONFIG_FILE), JSON.stringify(hooksConfig, null, 2), "utf-8");
+    return hookScriptPath;
+}
+/**
+ * Snapshot the workspace's existing `.cursor/hooks.json`, write a merged config
+ * that adds our preToolUse entry (absolute script path) while preserving the
+ * user's own hooks, and return the handle for restoration.
+ */
+async function installWorkspaceHook(workspaceRoot, scriptPath) {
+    const cursorDir = join(workspaceRoot, CURSOR_DIR);
+    const hooksJsonPath = join(cursorDir, HOOKS_CONFIG_FILE);
+    let originalRaw = null;
+    try {
+        originalRaw = await readFile(hooksJsonPath, "utf-8");
+    }
+    catch {
+        originalRaw = null;
+    }
+    const { merged, restoreTo } = buildMergedConfig(originalRaw, scriptPath);
+    await mkdir(cursorDir, { recursive: true });
+    await writeFile(hooksJsonPath, merged, "utf-8");
+    return { hooksJsonPath, restoreTo };
+}
+/**
+ * The preToolUse entry the gate installs. Absolute `command` so the hook is
+ * found regardless of which workspace root a multi-root IDE resolves against.
+ */
+function buildHookEntry(scriptPath) {
+    return { command: scriptPath, timeout: HOOK_TIMEOUT_SECONDS, failClosed: true };
+}
+/**
+ * Identify a preToolUse entry the gate itself wrote (in this or a prior,
+ * crash-leftover turn) so a re-install never duplicates it and a restore strips
+ * it. Matched by the unmistakable HITL script path, never by a user's own hook.
+ */
+function isStigmerHookEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const command = entry.command;
+    return (typeof command === "string" &&
+        command.includes("/.stigmer/sessions/") &&
+        command.endsWith(`/${HOOK_SCRIPT_FILE}`));
+}
+const STANDALONE_CONFIG = (scriptPath) => JSON.stringify({ version: 1, hooks: { preToolUse: [buildHookEntry(scriptPath)] } }, null, 2);
+/**
+ * Compute the merged hooks.json to write for this turn and the content to
+ * restore afterward.
+ *
+ * - No existing file → write our standalone config; restore by deleting (null).
+ * - Existing, parseable file → append our entry to `hooks.preToolUse`,
+ *   preserving every other hook type and field; restore the user's original
+ *   bytes. Any stale Stigmer entry from a prior crashed turn is stripped from
+ *   BOTH the merged config (no duplicate) and the restore target (self-healing).
+ * - Existing, unparseable file → replace for the turn with our standalone
+ *   config; restore the user's exact original bytes (we never "fix" their file).
+ *
+ * Exported for unit testing — this is the load-bearing data transformation.
+ */
+export function buildMergedConfig(originalRaw, scriptPath) {
+    if (originalRaw === null) {
+        return { merged: STANDALONE_CONFIG(scriptPath), restoreTo: null };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(originalRaw);
+    }
+    catch {
+        return { merged: STANDALONE_CONFIG(scriptPath), restoreTo: originalRaw };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { merged: STANDALONE_CONFIG(scriptPath), restoreTo: originalRaw };
+    }
+    const root = parsed;
+    const hooks = root.hooks && typeof root.hooks === "object" && !Array.isArray(root.hooks)
+        ? root.hooks
+        : {};
+    const existingPreToolUse = Array.isArray(hooks.preToolUse) ? hooks.preToolUse : [];
+    const userEntries = existingPreToolUse.filter((e) => !isStigmerHookEntry(e));
+    const strippedStale = userEntries.length !== existingPreToolUse.length;
+    const version = typeof root.version === "number" ? root.version : 1;
+    const merged = JSON.stringify({
+        ...root,
+        version,
+        hooks: { ...hooks, preToolUse: [...userEntries, buildHookEntry(scriptPath)] },
+    }, null, 2);
+    // Restore the user's exact original bytes — unless we stripped a stale Stigmer
+    // entry, in which case restore the cleaned form so our leftover never lingers.
+    const restoreTo = strippedStale
+        ? JSON.stringify({ ...root, version, hooks: { ...hooks, preToolUse: userEntries } }, null, 2)
+        : originalRaw;
+    return { merged, restoreTo };
 }
 //# sourceMappingURL=workspace-setup.js.map

package/dist/activities/execute-cursor/workspace-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-setup.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/workspace-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA0B,MAAM,qBAAqB,CAAC;AAExG,MAAM,SAAS,GAAG,SAAS,CAAC;AAC5B,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAC1C,MAAM,iBAAiB,GAAG,YAAY,CAAC;AACvC,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,aAAqB,EACrB,aAAgC;IAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;IAC1D,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C,MAAM,aAAa,GAAG,MAAM,sBAAsB,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAEjF,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,cAAc,GAAG,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAE9D,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IAC1D,MAAM,SAAS,CAAC,cAAc,EAAE,kBAAkB,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5F,MAAM,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IAEnC,MAAM,WAAW,GAAG;QAClB,OAAO,EAAE,CAAC;QACV,KAAK,EAAE;YACL,UAAU,EAAE;gBACV;oBACE,OAAO,EAAE,iBAAiB,gBAAgB,EAAE;oBAC5C,OAAO,EAAE,EAAE;oBACX,UAAU,EAAE,IAAI;iBACjB;aACF;SACF;KACF,CAAC;IAEF,MAAM,SAAS,CACb,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,EACjC,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,EACpC,OAAO,CACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"workspace-setup.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/workspace-setup.ts"],"names":[],"mappings":"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"}

package/dist/shared/workspace/platform-dir.d.ts

@@ -1,11 +1,15 @@
 /**
  * Session-scoped platform directory management.
  *
- * Each agent execution session gets a dedicated platform directory at
- * `~/.stigmer/sessions/{sessionId}/platform/` for storing skills,
- * attachments, and other platform-managed files. This directory is
- * separate from the user's workspace — the agent sees it via the
- * `.stigmer/` virtual namespace through WorkspaceBackend routing.
+ * Each agent execution session gets a dedicated directory tree under
+ * `~/.stigmer/sessions/{sessionId}/`:
+ * - `platform/` — skills, attachments, and other platform-managed files the
+ *   agent sees via the `.stigmer/` virtual namespace (WorkspaceBackend routing).
+ * - `hitl/` — the HITL approval gate's runtime artifacts (hook script, approval
+ *   state, denial ledger). These live OUTSIDE the user's workspace so attaching
+ *   a real repo never leaves Stigmer files behind in it (see issue #173); only
+ *   a minimal, transient `.cursor/hooks.json` referencing the absolute script
+ *   path is written into the workspace itself.
  *
  * This module replaces the duplicated `getPlatformDir` helpers in
  * execute-cursor/skill-resolver.ts and execute-cursor/attachment-resolver.ts.
@@ -23,3 +27,20 @@ export declare function getPlatformDir(sessionId: string): string;
  * safe to call multiple times for the same session.
  */
 export declare function ensurePlatformDir(sessionId: string): Promise<string>;
+/**
+ * Compute the HITL directory path for a session — the runner-owned home for the
+ * approval gate's hook script, approval-state file, and denial ledger.
+ *
+ * Kept separate from the workspace so the gate's machinery never pollutes the
+ * user's repo: the workspace only ever holds a transient `.cursor/hooks.json`
+ * that points here by absolute path. Pure function — performs no I/O.
+ */
+export declare function getHitlDir(sessionId: string): string;
+/**
+ * Ensure the HITL directory exists and return its path.
+ *
+ * Creates the full directory tree if it does not exist. Idempotent —
+ * safe to call multiple times for the same session (including across HITL
+ * reinvocations and Temporal activity retries).
+ */
+export declare function ensureHitlDir(sessionId: string): Promise<string>;

package/dist/shared/workspace/platform-dir.js

@@ -1,11 +1,15 @@
 /**
  * Session-scoped platform directory management.
  *
- * Each agent execution session gets a dedicated platform directory at
- * `~/.stigmer/sessions/{sessionId}/platform/` for storing skills,
- * attachments, and other platform-managed files. This directory is
- * separate from the user's workspace — the agent sees it via the
- * `.stigmer/` virtual namespace through WorkspaceBackend routing.
+ * Each agent execution session gets a dedicated directory tree under
+ * `~/.stigmer/sessions/{sessionId}/`:
+ * - `platform/` — skills, attachments, and other platform-managed files the
+ *   agent sees via the `.stigmer/` virtual namespace (WorkspaceBackend routing).
+ * - `hitl/` — the HITL approval gate's runtime artifacts (hook script, approval
+ *   state, denial ledger). These live OUTSIDE the user's workspace so attaching
+ *   a real repo never leaves Stigmer files behind in it (see issue #173); only
+ *   a minimal, transient `.cursor/hooks.json` referencing the absolute script
+ *   path is written into the workspace itself.
  *
  * This module replaces the duplicated `getPlatformDir` helpers in
  * execute-cursor/skill-resolver.ts and execute-cursor/attachment-resolver.ts.
@@ -13,14 +17,18 @@
 import { join } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
+/** Root of a session's runner-owned directory tree (outside the workspace). */
+function getSessionDir(sessionId) {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    return join(home, ".stigmer", "sessions", sessionId);
+}
 /**
  * Compute the platform directory path for a session.
  *
  * Pure function — does not create the directory or perform I/O.
  */
 export function getPlatformDir(sessionId) {
-    const home = process.env.HOME || process.env.USERPROFILE || homedir();
-    return join(home, ".stigmer", "sessions", sessionId, "platform");
+    return join(getSessionDir(sessionId), "platform");
 }
 /**
  * Ensure the platform directory exists and return its path.
@@ -33,4 +41,27 @@ export async function ensurePlatformDir(sessionId) {
     await mkdir(dir, { recursive: true });
     return dir;
 }
+/**
+ * Compute the HITL directory path for a session — the runner-owned home for the
+ * approval gate's hook script, approval-state file, and denial ledger.
+ *
+ * Kept separate from the workspace so the gate's machinery never pollutes the
+ * user's repo: the workspace only ever holds a transient `.cursor/hooks.json`
+ * that points here by absolute path. Pure function — performs no I/O.
+ */
+export function getHitlDir(sessionId) {
+    return join(getSessionDir(sessionId), "hitl");
+}
+/**
+ * Ensure the HITL directory exists and return its path.
+ *
+ * Creates the full directory tree if it does not exist. Idempotent —
+ * safe to call multiple times for the same session (including across HITL
+ * reinvocations and Temporal activity retries).
+ */
+export async function ensureHitlDir(sessionId) {
+    const dir = getHitlDir(sessionId);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
 //# sourceMappingURL=platform-dir.js.map

package/dist/shared/workspace/platform-dir.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-dir.js","sourceRoot":"","sources":["../../../src/shared/workspace/platform-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IACvD,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"platform-dir.js","sourceRoot":"","sources":["../../../src/shared/workspace/platform-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,+EAA+E;AAC/E,SAAS,aAAa,CAAC,SAAiB;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB;IACvD,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAAiB;IACnD,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.0.8-dev.20260612082024",
+  "version": "3.0.8-dev.20260612122433",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -86,7 +86,7 @@
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.0.8-dev.20260612082024",
+    "@stigmer/protos": "3.0.8-dev.20260612122433",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",

package/src/activities/execute-cursor/__tests__/hitl-ledger.test.ts

@@ -299,11 +299,12 @@ describe("reconstructAdjudicatedApprovals", () => {
 describe("generateHookScript ledger wiring", () => {
   it("wires the ledger path and records denials in both deny branches", () => {
     const script = generateHookScript(
-      "/ws/.cursor/hooks/stigmer-approval-state.json",
-      "/ws/.cursor/hooks/stigmer-denials.jsonl",
+      "/hitl/approval-state.json",
+      "/hitl/denials.jsonl",
+      process.pid,
     );
 
-    expect(script).toContain('LEDGER_FILE="/ws/.cursor/hooks/stigmer-denials.jsonl"');
+    expect(script).toContain('LEDGER_FILE="/hitl/denials.jsonl"');
     expect(script).toContain("record_denial()");
     // One definition + a call in the gated-built-in branch + a call in the MCP
     // branch = 3 occurrences.

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

@@ -47,6 +47,11 @@ function setup(opts: {
   grants?: ApprovalGrant[];
   mcpPolicies?: Record<string, McpToolPolicyEntry>;
   noStateFile?: boolean;
+  // Process the hook treats as "the runner". Defaults to this test process,
+  // which is an ancestor of the bash child execFileSync spawns — so the scope
+  // guard sees the call as the runner's own agent and applies the gate. Pass a
+  // non-ancestor PID to exercise the foreign-client path (issue #173).
+  runnerPid?: number;
 }): Harness {
   const ws = mkdtempSync(join(tmpdir(), "hook-script-"));
   tempDirs.push(ws);
@@ -55,7 +60,7 @@ function setup(opts: {
   const statePath = join(dir, "state.json");
   const ledgerPath = join(dir, "denials.jsonl");
   const scriptPath = join(dir, "hook.sh");
-  writeFileSync(scriptPath, generateHookScript(statePath, ledgerPath), "utf-8");
+  writeFileSync(scriptPath, generateHookScript(statePath, ledgerPath, opts.runnerPid ?? process.pid), "utf-8");
 
   if (!opts.noStateFile) {
     const policies = new Map(
@@ -179,6 +184,50 @@ d("generated preToolUse hook", () => {
     expect(h.decide(hookShell('rm -rf "/x"')).permission).toBe("deny");
   });
 
+  // Issue #173: the hook ships on the workspace's shared .cursor/hooks.json, so
+  // the user's own Cursor IDE (a DIFFERENT process tree) would load and run it
+  // too. The scope guard must allow any invocation that does not descend from
+  // the runner process — without gating it and without writing the denial ledger
+  // (a foreign denial would surface as a phantom approval card in the session).
+  describe("scope guard (issue #173): foreign invocations are not gated", () => {
+    // A PID that cannot be an ancestor of the test's bash child. macOS pid_max is
+    // 99998; this is comfortably above it and above a freshly-booted Linux
+    // pid range, so get_ppid yields nothing and the walk reports "not own".
+    const FOREIGN_PID = 2_147_483_600;
+
+    it("allows a gated built-in when the invocation is not the runner's own agent", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      // The IDE would have this DENIED if the gate applied — it must be allowed.
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.decide(hookShell("rm -rf build")).permission).toBe("allow");
+    });
+
+    it("never writes the denial ledger for a foreign invocation (no phantom approvals)", () => {
+      const h = setup({ runnerPid: FOREIGN_PID });
+      h.resetLedger();
+      h.decide(hookWrite("/x/a.txt"));
+      h.decide(hookShell("gh issue view 173"));
+      // The IDE's tool calls must NOT leak into the ledger the runner reads back.
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("allows a foreign invocation even when the state file is missing", () => {
+      // Fail-closed is for the runner's OWN agent; a foreign client must never be
+      // blocked by a missing state file (that was the multi-root exit-127 lockup).
+      const h = setup({ runnerPid: FOREIGN_PID, noStateFile: true });
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("still gates the runner's own agent (control: gate applies in-process)", () => {
+      // Same inputs, but runnerPid defaults to this process (an ancestor of the
+      // bash child) — the gate must apply, proving the guard discriminates.
+      const h = setup({});
+      expect(h.decide(hookWrite("/x/a.txt")).permission).toBe("deny");
+      expect(h.ledger()).toHaveLength(1);
+    });
+  });
+
   it("still denies gated tools via the bash fallback when the Node binary is unavailable", () => {
     const ws = mkdtempSync(join(tmpdir(), "hook-script-fallback-"));
     tempDirs.push(ws);
@@ -188,7 +237,7 @@ d("generated preToolUse hook", () => {
     const ledgerPath = join(dir, "denials.jsonl");
     const scriptPath = join(dir, "hook.sh");
     // Break the baked Node path to force the grep/cut fallback.
-    const script = generateHookScript(statePath, ledgerPath)
+    const script = generateHookScript(statePath, ledgerPath, process.pid)
       .replace(`NODE_BIN="${process.execPath}"`, 'NODE_BIN="/nonexistent/node"');
     writeFileSync(scriptPath, script, "utf-8");
     writeFileSync(statePath, JSON.stringify(buildApprovalState(new Map(), false)), "utf-8");

package/src/activities/execute-cursor/__tests__/http2-interceptor.test.ts

@@ -337,6 +337,15 @@ describe("http2-interceptor", () => {
     // factories. Here we cover the two deterministic contracts: it is a no-op
     // when unconfigured (no import, so it never freezes the facade), and it
     // throws when the frozen facade is out of sync with the patched connect.
+    //
+    // This guard does double duty as a BUNDLER regression detector. The
+    // load-order contract is also defeatable at build time: an ESM esbuild
+    // bundle hoists every external `import` (including the node:http2 pulled in
+    // by connect-node) to the top of the output, freezing the facade before any
+    // install() runs. That is exactly stigmer/stigmer#170's second failure — the
+    // slim bundle is therefore emitted as CJS (scripts/bundle-slim.mjs) and
+    // verified on the authenticated boot path (scripts/verify-slim-artifact.mjs).
+    // The "out of sync" case below is the unit-level analog of that bundle bug.
 
     it("resolves without throwing (and without importing node:http2) when unconfigured", async () => {
       uninstallHttp2Interceptor();