@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/dist/shared/approval-policy.js

@@ -5,76 +5,246 @@
  * 1. McpServerStatus.tool_approvals — system-generated defaults
  * 2. McpServerSpec.pinned_tool_approvals — manual overrides
  * 3. McpServerUsage.tool_approval_overrides — per-agent customization
- * 4. AgentExecutionSpec.auto_approve_all — runtime bypass
+ * 4. Active approval leases — the runtime bypass, now SCOPED: the pre-armed
+ *    spec.auto_approve_all is a whole-run global bypass, while an interactive
+ *    APPROVE_ALL ("approve all of this kind") grants a run-lifetime lease for
+ *    only that action's scope (its built-in category, or its MCP server). See
+ *    {@link ActiveLeases}.
  *
  * Used by both ExecuteCursor (hook-deny model) and ExecuteDeepAgent
  * (middleware interruptOn model) to determine which tools need approval.
  */
-import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { toolApprovalCategory } from "./tool-kind.js";
 /**
- * Returns true if any tool call in the execution history (root or sub-agent)
- * carries an APPROVE_ALL decision.
+ * Reduce a single tool call to the scope its APPROVE_ALL would lease — the core
+ * of {@link deriveActiveLeases}, extracted so the cross-edition lease-scope
+ * corpus (apis/testdata/hitl/lease-scope) can exercise it directly.
  *
- * This is the runner-side realization of the APPROVE_ALL contract (see the
- * ApprovalAction doc in enum.proto): once a user has chosen "approve and don't
- * ask again" at any gate, the rest of THIS execution runs un-gated — exactly as
- * if spec.auto_approve_all were true. Both harnesses (native deepagents and
- * cursor) call this so the behavior is defined in exactly one place.
+ * The MCP server slug takes precedence over the built-in category and is used
+ * RAW (the server's identity, not case-folded), matching the Go
+ * {@link DeriveLeaseScope} and Java {@link LeaseScope.deriveKey} byte-for-byte.
+ * The category lookup reuses {@link toolApprovalCategory}, the shared oracle, so
+ * a built-in resolves to write/delete/shell (read-only built-ins are ungated and
+ * return `undefined`).
  */
-export function hasApproveAllDecision(execution) {
+export function deriveLeaseScope(toolName, mcpServerSlug) {
+    if (mcpServerSlug) {
+        return { kind: "server", server: mcpServerSlug };
+    }
+    const category = toolApprovalCategory(toolName);
+    if (category) {
+        return { kind: "category", category };
+    }
+    return undefined;
+}
+/**
+ * Derive the active approval leases for an execution.
+ *
+ * The scoped successor to the former all-or-nothing hasApproveAllDecision:
+ * instead of "any APPROVE_ALL anywhere disables the whole gate", each
+ * APPROVE_ALL decision is reduced (via {@link deriveLeaseScope}) to the SCOPE of
+ * the tool it was made on — the built-in category for a built-in tool (read-only
+ * tools are never gated, so a built-in lease is always write/delete/shell), or
+ * the MCP server slug for an MCP tool — and only that scope is auto-approved for
+ * the rest of the run.
+ *
+ * Scans root and sub-agent tool calls so a lease granted anywhere applies
+ * execution-wide (matching the prior cross-sub-agent behavior, now bounded by
+ * scope). Both harnesses call this so the contract is defined in exactly one
+ * place. The scope derivation reuses {@link toolApprovalCategory}, the same
+ * corpus-tested oracle the Go and Java editions mirror, so the backend's
+ * scope-aware bulk-approve and this runner-side evaluation can never disagree.
+ */
+export function deriveActiveLeases(execution) {
+    const categories = new Set();
+    const servers = new Set();
+    const addLease = (tc) => {
+        if (tc.approvalAction !== ApprovalAction.APPROVE_ALL)
+            return;
+        const scope = deriveLeaseScope(tc.name, tc.mcpServerSlug);
+        if (!scope)
+            return;
+        if (scope.kind === "server") {
+            servers.add(scope.server);
+        }
+        else {
+            categories.add(scope.category);
+        }
+    };
     const status = execution.status;
-    if (!status)
-        return false;
-    for (const message of status.messages) {
-        for (const tc of message.toolCalls) {
-            if (tc.approvalAction === ApprovalAction.APPROVE_ALL)
-                return true;
+    if (status) {
+        for (const message of status.messages) {
+            for (const tc of message.toolCalls)
+                addLease(tc);
         }
-    }
-    for (const sa of status.subAgentExecutions) {
-        for (const message of sa.messages) {
-            for (const tc of message.toolCalls) {
-                if (tc.approvalAction === ApprovalAction.APPROVE_ALL)
-                    return true;
+        for (const sa of status.subAgentExecutions) {
+            for (const message of sa.messages) {
+                for (const tc of message.toolCalls)
+                    addLease(tc);
             }
         }
     }
-    return false;
+    return {
+        global: execution.spec?.autoApproveAll ?? false,
+        categories,
+        servers,
+    };
+}
+/**
+ * Monotonic identifier of the policy-engine logic that produced a decision,
+ * persisted on `ToolCall.policy_engine_version`. Bumped when the
+ * merge/classification semantics change so decisions made by different engine
+ * versions remain distinguishable in audits. Phase 7 made
+ * `annotation_destructive_tighten` a distinct, persisted source.
+ */
+export const POLICY_ENGINE_VERSION = "phase-7";
+/**
+ * Map the runner-internal {@link PolicySource} to the persisted proto
+ * {@link ApprovalPolicySource}. `undefined` (a tool no policy layer governs —
+ * e.g. a read-only built-in) maps to UNSPECIFIED, so the persisted field is left
+ * at its default exactly as an unclassified `tool_kind` is. The 1:1 mapping keeps
+ * the runner's union and the proto enum from drifting (asserted by the
+ * cross-edition corpus).
+ */
+export function toProtoPolicySource(source) {
+    switch (source) {
+        case "classifier_default":
+            return ApprovalPolicySource.CLASSIFIER_DEFAULT;
+        case "pinned_override":
+            return ApprovalPolicySource.PINNED_OVERRIDE;
+        case "agent_override":
+            return ApprovalPolicySource.AGENT_OVERRIDE;
+        case "auto_approve_all":
+            return ApprovalPolicySource.AUTO_APPROVE_ALL;
+        case "approval_lease":
+            return ApprovalPolicySource.APPROVAL_LEASE;
+        case "builtin_category":
+            return ApprovalPolicySource.BUILTIN_CATEGORY;
+        case "annotation_destructive_tighten":
+            return ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN;
+        case "file_capture":
+            // Capture-mode flow is never persisted on a gated tool call (the file tool
+            // is not gated — it has no WAITING_APPROVAL row); it exists only on the
+            // audit receipt. Map to UNSPECIFIED for the proto-persisted field.
+            return ApprovalPolicySource.UNSPECIFIED;
+        case undefined:
+            return ApprovalPolicySource.UNSPECIFIED;
+    }
+}
+/**
+ * Derive the authorization provenance — which policy layer governs this tool —
+ * for persisting on `ToolCall.approval_policy_source`.
+ *
+ * This is the read-side twin of the gate's decision logic: same layered
+ * precedence, but it answers "which layer governs this call?" for EVERY tool
+ * (gated or auto-approved), so the StatusBuilders can stamp provenance on the
+ * tool call exactly where they stamp `tool_kind`. It returns `undefined` for a
+ * plain read-only built-in that no policy layer touches (the proto's
+ * APPROVAL_POLICY_SOURCE_UNSPECIFIED).
+ *
+ * Precedence:
+ * 1. Whole-run global bypass (pre-armed auto_approve_all) governs everything —
+ *    it is *why* anything ran ungated, so it wins.
+ * 2. MCP tool: the merged policy carries the responsible layer when gated; an
+ *    absent entry means the four-level chain cleared it (classifier base). A
+ *    server-scoped lease also surfaces as an absent entry — distinguishing it
+ *    would need the lease set threaded here and is deferred with the rest of the
+ *    per-server lease provenance, so a lease-cleared MCP tool reads
+ *    classifier_default (matching the gate).
+ * 3. Built-in: a mutating category is governed (leased → approval_lease, else
+ *    builtin_category); a read-only built-in is governed by no layer → undefined.
+ */
+export function resolveApprovalProvenance(toolName, serverSlug, policies, leasedCategories, globalBypass) {
+    if (globalBypass)
+        return "auto_approve_all";
+    if (serverSlug) {
+        const policy = policies.get(`${serverSlug}/${toolName}`);
+        if (policy)
+            return policy.source;
+        return "classifier_default";
+    }
+    const category = toolApprovalCategory(toolName);
+    if (!category)
+        return undefined;
+    if (leasedCategories.has(category))
+        return "approval_lease";
+    return "builtin_category";
 }
 /**
  * Merge approval policies from all four levels into a single lookup map.
  *
- * Keys are "serverSlug/toolName" to avoid collisions between servers.
- * When autoApproveAll is true, the returned map is empty.
+ * Each MCP server contributes its own set of policies, so the map is keyed by
+ * "serverSlug/toolName" to avoid collisions between servers.
+ *
+ * Policy chain (each level overrides the previous):
+ * 1. status.toolApprovals — system-generated defaults; presence = requires approval
+ * 2. spec.pinnedToolApprovals — manual overrides; presence = requires approval
+ * 3. agent tool_approval_overrides — explicit boolean per tool (enable OR disable)
+ * 4. active leases — runtime bypass (highest priority), now scoped
+ *
+ * The map carries ONLY the tools that require approval — a tool's absence means
+ * "auto-approved". Leases shape that absence:
+ * - On a global pre-arm ({@link ActiveLeases.global}) the map is empty.
+ * - A server-scoped lease drops that server's tools from the map entirely. This
+ *   single omission makes EVERY substrate treat the server as auto-approved with
+ *   no extra code — the deep-agent gate and StatusBuilder read the map, and the
+ *   Cursor hook's mcpToolPolicies is built from it (the hook is not itself
+ *   server-aware, so omission is the only way to lease an MCP server there).
+ * Built-in CATEGORY leases are NOT applied here — built-ins are not in this map;
+ * they are cleared at the gate (deep-agent) and the hook (Cursor) instead.
+ *
+ * Used by both ExecuteCursor (hook-deny model) and ExecuteDeepAgent (middleware
+ * interruptOn model), so the four-level semantics are defined in exactly one
+ * place.
  */
-export function mergeApprovalPolicies(resolvedServers, agentOverrides, autoApproveAll) {
+export function mergeApprovalPolicies(resolvedServers, agentOverrides, leases) {
     const merged = new Map();
-    if (autoApproveAll)
+    if (leases.global)
         return merged;
     for (const server of resolvedServers) {
+        // Server-scoped lease: a prior APPROVE_ALL on one of this server's tools
+        // auto-approves the whole server for the run, so none of its tools enter the
+        // require-approval map (identical to how an already-auto-approved tool is
+        // absent — every consumer treats it as cleared).
+        if (leases.servers.has(server.slug))
+            continue;
         const serverPolicies = new Map();
+        // Layer 1: system-generated defaults (presence = requires approval). A tool
+        // the connect-time tightener force-gated from its destructiveHint annotation
+        // carries that provenance (from_destructive_hint) so it is attributed to the
+        // annotation rather than the classifier — the only sub-case within layer 1.
         for (const policy of server.toolApprovals) {
             if (!policy.toolName)
                 continue;
             serverPolicies.set(policy.toolName, {
                 requiresApproval: true,
                 message: policy.message || `Execute tool: ${policy.toolName}`,
+                source: policy.fromDestructiveHint
+                    ? "annotation_destructive_tighten"
+                    : "classifier_default",
             });
         }
+        // Layer 2: manual overrides (presence = requires approval, overrides layer 1).
         for (const pinned of server.pinnedToolApprovals) {
             if (!pinned.toolName)
                 continue;
             serverPolicies.set(pinned.toolName, {
                 requiresApproval: true,
                 message: pinned.message || serverPolicies.get(pinned.toolName)?.message || `Execute tool: ${pinned.toolName}`,
+                source: "pinned_override",
             });
         }
+        // Layer 3: per-agent overrides (explicit boolean, can enable or disable).
+        // Touching a tool here makes the per-agent layer the responsible source,
+        // whether it enables, disables, or re-messages the gate.
         for (const override of agentOverrides) {
             if (!override.toolName)
                 continue;
             const existing = serverPolicies.get(override.toolName);
             if (existing) {
                 existing.requiresApproval = override.requiresApproval;
+                existing.source = "agent_override";
                 if (override.message) {
                     existing.message = override.message;
                 }
@@ -83,9 +253,11 @@ export function mergeApprovalPolicies(resolvedServers, agentOverrides, autoAppro
                 serverPolicies.set(override.toolName, {
                     requiresApproval: true,
                     message: override.message || `Execute tool: ${override.toolName}`,
+                    source: "agent_override",
                 });
             }
         }
+        // Emit only the tools that still require approval after all layers.
         for (const [toolName, policy] of serverPolicies) {
             if (!policy.requiresApproval)
                 continue;
@@ -95,17 +267,31 @@ export function mergeApprovalPolicies(resolvedServers, agentOverrides, autoAppro
                 mcpServerSlug: server.slug,
                 requiresApproval: true,
                 approvalMessage: policy.message,
+                source: policy.source,
             });
         }
     }
     return merged;
 }
+/**
+ * Look up whether an MCP tool requires approval.
+ *
+ * @param toolName - The actual MCP tool name (e.g., "apply_cloud_resource")
+ * @param mcpServerSlug - The MCP server slug (e.g., "planton")
+ * @param policies - The merged policy map from {@link mergeApprovalPolicies}
+ * @returns The policy if approval is required, undefined if auto-approved
+ */
 export function lookupMcpToolPolicy(toolName, mcpServerSlug, policies) {
     return policies.get(`${mcpServerSlug}/${toolName}`);
 }
 /**
  * Resolve {{args.field}} placeholders in an approval message using the
  * tool's actual arguments.
+ *
+ * Placeholder syntax matches the proto-documented format:
+ * - {{args.field_name}} — replaced with the argument value
+ * - {{tool_name}} — replaced with the tool name
+ * - Missing fields are replaced with "<unknown>"
  */
 export function resolveApprovalMessage(template, toolName, args) {
     return template

package/dist/shared/approval-policy.js.map

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

package/dist/shared/args-preview.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Harness-agnostic sanitization of tool arguments for the `args_preview` field.
+ *
+ * `args_preview` is the human-readable, UI-facing projection of a tool call's
+ * arguments. It is surfaced on the approval card, the CLI, and the web console,
+ * and — for the Cursor harness — it is the field a resumed turn parses to rebuild
+ * an approval grant's salient identity. So it must always be SMALL and VALID
+ * JSON: the per-tool offload does not touch it, and the aggregate size backstop
+ * would replace an oversized preview with an unparseable marker.
+ *
+ * This module is the single home for arg sanitization shared by both harnesses
+ * (native re-exports {@link sanitizeArgsPreview} from its status builders; the
+ * Cursor gate path uses {@link buildElidedArgsPreview}).
+ */
+/**
+ * Argument keys whose values are secrets and must never appear in a preview.
+ * Matched case-insensitively against the top-level key name.
+ */
+export declare const SENSITIVE_ARG_KEYS: ReadonlySet<string>;
+/** Whole-preview length cap for {@link sanitizeArgsPreview} (native). */
+export declare const MAX_ARGS_PREVIEW_LENGTH = 500;
+/**
+ * Sanitize args into a compact preview string (native harness behavior).
+ *
+ * Redacts sensitive keys, then truncates the whole JSON to a fixed length. The
+ * truncation can yield invalid JSON, which is acceptable for the native harness
+ * (its resume model keys on `tool_call_id`, never on a re-parsed preview). The
+ * Cursor gate path must instead use {@link buildElidedArgsPreview}, which keeps
+ * the JSON valid and preserves the salient identity fields.
+ */
+export declare function sanitizeArgsPreview(args: Record<string, unknown>): string;
+/**
+ * Build a compact, ALWAYS-VALID `args_preview` from a tool call's full,
+ * authoritative arguments.
+ *
+ * Unlike {@link sanitizeArgsPreview} (which truncates the whole string, possibly
+ * to invalid JSON), this elides oversized string *values* in place — preserving
+ * every key and the JSON structure. Two invariants make it safe for the Cursor
+ * gate path:
+ *  - It NEVER elides a salient field (the resume grant's identity — the file
+ *    path or shell command — is parsed back out of this preview, so it must
+ *    survive verbatim).
+ *  - It redacts secret keys.
+ *
+ * The heavy content (a whole-file body, a large diff) lives on `file_changes`
+ * (offloaded to a ref when large) and `args` (bounded by the size backstop), so
+ * the preview itself stays small even for a multi-MB write.
+ *
+ * @param args the full tool arguments
+ * @param salientFields keys whose values must be preserved verbatim (identity)
+ */
+export declare function buildElidedArgsPreview(args: Record<string, unknown>, salientFields: readonly string[]): string;

package/dist/shared/args-preview.js

@@ -0,0 +1,93 @@
+/**
+ * Harness-agnostic sanitization of tool arguments for the `args_preview` field.
+ *
+ * `args_preview` is the human-readable, UI-facing projection of a tool call's
+ * arguments. It is surfaced on the approval card, the CLI, and the web console,
+ * and — for the Cursor harness — it is the field a resumed turn parses to rebuild
+ * an approval grant's salient identity. So it must always be SMALL and VALID
+ * JSON: the per-tool offload does not touch it, and the aggregate size backstop
+ * would replace an oversized preview with an unparseable marker.
+ *
+ * This module is the single home for arg sanitization shared by both harnesses
+ * (native re-exports {@link sanitizeArgsPreview} from its status builders; the
+ * Cursor gate path uses {@link buildElidedArgsPreview}).
+ */
+/**
+ * Argument keys whose values are secrets and must never appear in a preview.
+ * Matched case-insensitively against the top-level key name.
+ */
+export const SENSITIVE_ARG_KEYS = new Set([
+    "password", "token", "secret", "api_key", "apikey",
+    "credentials", "auth", "authorization",
+]);
+/** Whole-preview length cap for {@link sanitizeArgsPreview} (native). */
+export const MAX_ARGS_PREVIEW_LENGTH = 500;
+/**
+ * Sanitize args into a compact preview string (native harness behavior).
+ *
+ * Redacts sensitive keys, then truncates the whole JSON to a fixed length. The
+ * truncation can yield invalid JSON, which is acceptable for the native harness
+ * (its resume model keys on `tool_call_id`, never on a re-parsed preview). The
+ * Cursor gate path must instead use {@link buildElidedArgsPreview}, which keeps
+ * the JSON valid and preserves the salient identity fields.
+ */
+export function sanitizeArgsPreview(args) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(args)) {
+        sanitized[key] = SENSITIVE_ARG_KEYS.has(key.toLowerCase()) ? "[REDACTED]" : value;
+    }
+    try {
+        const json = JSON.stringify(sanitized);
+        return json.length > MAX_ARGS_PREVIEW_LENGTH
+            ? json.slice(0, MAX_ARGS_PREVIEW_LENGTH) + "…"
+            : json;
+    }
+    catch {
+        return "";
+    }
+}
+/** Per-string-value cap for {@link buildElidedArgsPreview}. */
+const MAX_PREVIEW_VALUE_LENGTH = 200;
+/**
+ * Build a compact, ALWAYS-VALID `args_preview` from a tool call's full,
+ * authoritative arguments.
+ *
+ * Unlike {@link sanitizeArgsPreview} (which truncates the whole string, possibly
+ * to invalid JSON), this elides oversized string *values* in place — preserving
+ * every key and the JSON structure. Two invariants make it safe for the Cursor
+ * gate path:
+ *  - It NEVER elides a salient field (the resume grant's identity — the file
+ *    path or shell command — is parsed back out of this preview, so it must
+ *    survive verbatim).
+ *  - It redacts secret keys.
+ *
+ * The heavy content (a whole-file body, a large diff) lives on `file_changes`
+ * (offloaded to a ref when large) and `args` (bounded by the size backstop), so
+ * the preview itself stays small even for a multi-MB write.
+ *
+ * @param args the full tool arguments
+ * @param salientFields keys whose values must be preserved verbatim (identity)
+ */
+export function buildElidedArgsPreview(args, salientFields) {
+    const out = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (SENSITIVE_ARG_KEYS.has(key.toLowerCase())) {
+            out[key] = "[REDACTED]";
+        }
+        else if (!salientFields.includes(key) &&
+            typeof value === "string" &&
+            value.length > MAX_PREVIEW_VALUE_LENGTH) {
+            out[key] = `[${value.length} chars]`;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    try {
+        return JSON.stringify(out);
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=args-preview.js.map

package/dist/shared/args-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args-preview.js","sourceRoot":"","sources":["../../src/shared/args-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IAC7D,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ;IAClD,aAAa,EAAE,MAAM,EAAE,eAAe;CACvC,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,SAAS,GAA4B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,SAAS,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC;IACpF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,MAAM,GAAG,uBAAuB;YAC1C,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,GAAG,GAAG;YAC9C,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAA6B,EAC7B,aAAgC;IAEhC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC;QAC1B,CAAC;aAAM,IACL,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC;YAC5B,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,CAAC,MAAM,GAAG,wBAAwB,EACvC,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM,SAAS,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/shared/artifact-storage.d.ts

@@ -2,8 +2,13 @@
  * Artifact storage abstraction for the unified runner.
  *
  * Two backends:
- * - Local: writes to the filesystem, served by stigmer-server (OSS mode).
+ * - Local: writes to the filesystem (OSS mode). The runner reads its own
+ *   artifacts straight back off disk via {@link ArtifactStorage.download} — the
+ *   exact inverse of {@link ArtifactStorage.upload}. `getDownloadUrl` still
+ *   returns the stigmer-server serve URL, but that is for OTHER consumers (the
+ *   web console fetching an artifact for display), not the runner's own reads.
  * - Proxy: uses presigned URLs from the Stigmer Side-Channel Proxy (cloud mode).
+ *   Here `download` resolves a presigned URL and fetches it over HTTPS.
  *
  * The runner never holds R2/S3 credentials — in cloud mode it calls the proxy
  * to obtain a presigned upload URL, then PUTs content over plain HTTPS.
@@ -14,6 +19,17 @@ import type { Config } from "../config.js";
 export interface ArtifactStorage {
     upload(key: string, content: Buffer, contentType?: string): Promise<string>;
     getDownloadUrl(key: string): Promise<string>;
+    /**
+     * Read an artifact's raw bytes by key — the inverse of {@link upload} and the
+     * single read path for all runner read-back (CAS reconcile, exact-apply,
+     * claimcheck decode, attachment injection).
+     *
+     * Returns the exact stored bytes, or throws a descriptive, key-scoped `Error`
+     * when the object is missing or the transport fails. Per-backend semantics:
+     * local reads directly off disk; proxy resolves a presigned URL and fetches
+     * it. Callers own their own error-wrapping / degradation policy.
+     */
+    download(key: string): Promise<Buffer>;
     exists(key: string): Promise<boolean>;
 }
 export type ArtifactStorageType = "local" | "proxy";
@@ -23,6 +39,7 @@ export declare class LocalArtifactStorage implements ArtifactStorage {
     constructor(basePath: string, serveUrlBase: string);
     upload(key: string, content: Buffer, _contentType?: string): Promise<string>;
     getDownloadUrl(key: string): Promise<string>;
+    download(key: string): Promise<Buffer>;
     exists(key: string): Promise<boolean>;
 }
 export declare class ProxyArtifactStorage implements ArtifactStorage {
@@ -31,6 +48,7 @@ export declare class ProxyArtifactStorage implements ArtifactStorage {
     constructor(proxyEndpoint: string, authToken: string);
     upload(key: string, content: Buffer, contentType?: string): Promise<string>;
     getDownloadUrl(key: string): Promise<string>;
+    download(key: string): Promise<Buffer>;
     exists(key: string): Promise<boolean>;
 }
 export interface ArtifactStorageConfig {

package/dist/shared/artifact-storage.js

@@ -2,15 +2,20 @@
  * Artifact storage abstraction for the unified runner.
  *
  * Two backends:
- * - Local: writes to the filesystem, served by stigmer-server (OSS mode).
+ * - Local: writes to the filesystem (OSS mode). The runner reads its own
+ *   artifacts straight back off disk via {@link ArtifactStorage.download} — the
+ *   exact inverse of {@link ArtifactStorage.upload}. `getDownloadUrl` still
+ *   returns the stigmer-server serve URL, but that is for OTHER consumers (the
+ *   web console fetching an artifact for display), not the runner's own reads.
  * - Proxy: uses presigned URLs from the Stigmer Side-Channel Proxy (cloud mode).
+ *   Here `download` resolves a presigned URL and fetches it over HTTPS.
  *
  * The runner never holds R2/S3 credentials — in cloud mode it calls the proxy
  * to obtain a presigned upload URL, then PUTs content over plain HTTPS.
  *
  * DD-6: No direct R2 backend. Local + Proxy only.
  */
-import { mkdir, writeFile, access } from "node:fs/promises";
+import { mkdir, writeFile, readFile, access } from "node:fs/promises";
 import { dirname, join } from "node:path";
 // ── Local Backend ────────────────────────────────────────────────────
 export class LocalArtifactStorage {
@@ -29,6 +34,18 @@ export class LocalArtifactStorage {
     async getDownloadUrl(key) {
         return `${this.serveUrlBase}/${key}`;
     }
+    async download(key) {
+        // Direct disk read — the exact inverse of `upload`. The runner wrote these
+        // bytes to `basePath`, so it reads them back without a self-HTTP round-trip
+        // and without depending on the serve URL being set or reachable.
+        try {
+            return await readFile(join(this.basePath, key));
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new Error(`Artifact not found for key '${key}': ${reason}`);
+        }
+    }
     async exists(key) {
         try {
             await access(join(this.basePath, key));
@@ -112,21 +129,41 @@ export class ProxyArtifactStorage {
         const data = await resp.json();
         return data.url;
     }
+    async download(key) {
+        const url = await this.getDownloadUrl(key);
+        const resp = await fetch(url);
+        if (!resp.ok) {
+            throw new Error(`Artifact download failed (HTTP ${resp.status}) for key '${key}': ` +
+                await resp.text());
+        }
+        return Buffer.from(await resp.arrayBuffer());
+    }
     async exists(key) {
+        // A presigned URL is minted for ANY key — the presign endpoint does not check
+        // the object — so "did presign succeed?" is NOT existence (that bug turned a
+        // git-only file-review reconcile into a doomed manifest download + 404 crash).
+        // Probe the object itself with a 1-byte ranged GET: the presigned URL is
+        // SigV4-signed for GET (a HEAD would break the signature), and `Range:
+        // bytes=0-0` transfers at most one byte. Missing => 404; present => 200/206
+        // (or 416 for a 0-byte object, whose range is unsatisfiable yet it exists).
+        let url;
         try {
-            const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
-                method: "POST",
-                headers: {
-                    "Authorization": `Bearer ${this.authToken}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({ key }),
-            });
-            return resp.ok;
+            url = await this.getDownloadUrl(key);
         }
         catch {
+            // Presign endpoint unreachable: report absent. The sole caller (content-
+            // addressed CAS blob dedup) then re-uploads, which is idempotent.
             return false;
         }
+        const resp = await fetch(url, { headers: { Range: "bytes=0-0" } });
+        await resp.arrayBuffer().catch(() => undefined); // drain the <=1-byte body
+        if (resp.status === 404)
+            return false;
+        if (resp.status === 200 || resp.status === 206 || resp.status === 416)
+            return true;
+        // Any other status (e.g. 403 expired/misconfigured, 5xx) is a real fault, not
+        // an existence answer — surface it rather than silently mis-reporting.
+        throw new Error(`Artifact existence check failed (HTTP ${resp.status}) for key '${key}'`);
     }
 }
 export function loadArtifactStorageConfig(config) {