@stigmer/runner 3.12.3 → 3.12.5

package/src/shared/__tests__/vertex-seam.test.ts

@@ -4,13 +4,13 @@
  *
  * This is NOT a unit test of our code (there is no production vertex code
  * yet). It pins the exact cross-package behavior production will rely on:
- * the REAL `ChatAnthropic` (@langchain/anthropic, bundling @anthropic-ai/sdk
- * 0.95.x) driving the REAL `AnthropicVertex` client (@anthropic-ai/vertex-sdk,
- * bundling its own nested @anthropic-ai/sdk >=0.115). If a future bump of
+ * the REAL `ChatAnthropic` (@langchain/anthropic) driving the REAL
+ * `AnthropicVertex` client (@anthropic-ai/vertex-sdk), both resolving the
+ * single override-pinned @anthropic-ai/sdk copy. If a future bump of
  * either side changes request shaping, streaming event handling, tool-call
  * assembly, or usage accounting across this seam, this suite fails in CI
- * instead of production. See scripts/check-langchain-deps.sh for why two
- * @anthropic-ai/sdk copies coexist and when they collapse to one.
+ * instead of production. See scripts/check-langchain-deps.sh for the
+ * override rationale and the single-copy invariant it guards.
  *
  * Determinism: zero credentials, zero network. Google auth is bypassed by
  * injecting a fake `authClient` (the SDK's supported constructor option —

package/src/shared/__tests__/worker-shutdown.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import {
+  classifyTurnInterruption,
+  getShutdownSignalForQueue,
+  registerWorkerShutdownSignal,
+  signalWorkerShutdown,
+  unregisterWorkerShutdownSignal,
+} from "../worker-shutdown.js";
+
+describe("worker-shutdown signal registry", () => {
+  it("registers a live signal an activity can resolve by queue name", () => {
+    const controller = registerWorkerShutdownSignal("session:reg-1");
+    const signal = getShutdownSignalForQueue("session:reg-1");
+    expect(signal).toBe(controller.signal);
+    expect(signal?.aborted).toBe(false);
+    unregisterWorkerShutdownSignal("session:reg-1");
+  });
+
+  it("aborting via signalWorkerShutdown marks the queue's signal (idempotent, unknown queues are no-ops)", () => {
+    registerWorkerShutdownSignal("session:abort-1");
+    signalWorkerShutdown("session:abort-1");
+    signalWorkerShutdown("session:abort-1");
+    expect(getShutdownSignalForQueue("session:abort-1")?.aborted).toBe(true);
+    expect(() => signalWorkerShutdown("session:never-registered")).not.toThrow();
+    unregisterWorkerShutdownSignal("session:abort-1");
+  });
+
+  it("re-registering a reused queue replaces an aborted signal with a fresh one", () => {
+    // A re-created worker on a reused queue (desktop re-opens a session) must
+    // not observe the previous worker's aborted signal as its own shutdown.
+    const first = registerWorkerShutdownSignal("session:reuse-1");
+    first.abort();
+    const second = registerWorkerShutdownSignal("session:reuse-1");
+    expect(getShutdownSignalForQueue("session:reuse-1")).toBe(second.signal);
+    expect(getShutdownSignalForQueue("session:reuse-1")?.aborted).toBe(false);
+    unregisterWorkerShutdownSignal("session:reuse-1");
+  });
+
+  it("unregistering removes the signal", () => {
+    registerWorkerShutdownSignal("session:gone-1");
+    unregisterWorkerShutdownSignal("session:gone-1");
+    expect(getShutdownSignalForQueue("session:gone-1")).toBeUndefined();
+  });
+});
+
+describe("classifyTurnInterruption", () => {
+  const none = {
+    heartbeatCancelled: false,
+    heartbeatWorkerShutdown: false,
+    cancellationSignalAborted: false,
+    shutdownSignalAborted: false,
+  };
+
+  it("an uninterrupted turn is none", () => {
+    expect(classifyTurnInterruption(none)).toBe("none");
+  });
+
+  it("GRACE-WINDOW GUARD (#776): an aborted shutdown signal alone stays none — a run that completed inside the drain grace window must not be failed", () => {
+    expect(
+      classifyTurnInterruption({ ...none, shutdownSignalAborted: true }),
+    ).toBe("none");
+  });
+
+  it("heartbeat cancellation without a shutdown signal is the orchestrator's pause", () => {
+    expect(
+      classifyTurnInterruption({ ...none, heartbeatCancelled: true }),
+    ).toBe("pause");
+  });
+
+  it("heartbeat cancellation WITH the shutdown signal aborted is a worker shutdown, not a pause (the #776 misclassification)", () => {
+    expect(
+      classifyTurnInterruption({
+        ...none,
+        heartbeatCancelled: true,
+        shutdownSignalAborted: true,
+      }),
+    ).toBe("worker-shutdown");
+  });
+
+  it("the heartbeat's own workerShutdown flag classifies directly", () => {
+    expect(
+      classifyTurnInterruption({ ...none, heartbeatWorkerShutdown: true }),
+    ).toBe("worker-shutdown");
+  });
+
+  it("a delivered cancellation with the shutdown signal aborted is a worker shutdown (signal races the heartbeat tick)", () => {
+    expect(
+      classifyTurnInterruption({
+        ...none,
+        cancellationSignalAborted: true,
+        shutdownSignalAborted: true,
+      }),
+    ).toBe("worker-shutdown");
+  });
+
+  it("a delivered cancellation alone (heartbeat timeout / infra cancel) is neither shutdown nor pause", () => {
+    expect(
+      classifyTurnInterruption({ ...none, cancellationSignalAborted: true }),
+    ).toBe("none");
+  });
+});

package/src/shared/__tests__/zip-extract.test.ts

@@ -1,7 +1,16 @@
 import { describe, it, expect } from "vitest";
-import { extractZipFileEntries } from "../zip-extract.js";
+import { extractZipFileEntries, type ZipFileEntry } from "../zip-extract.js";
 import { buildZip } from "../../__test-utils__/zip-fixtures.js";
 
+/**
+ * Decode entries for text-content assertions. The production contract is
+ * bytes (issue #683); decoding belongs to the tests that want to assert on
+ * human-readable fixtures, not to the module under test.
+ */
+function decoded(entries: ZipFileEntry[]): { path: string; content: string }[] {
+  return entries.map((e) => ({ path: e.path, content: new TextDecoder().decode(e.content) }));
+}
+
 // ─── extractZipFileEntries ───────────────────────────────────────────────
 
 describe("extractZipFileEntries", () => {
@@ -12,9 +21,10 @@ describe("extractZipFileEntries", () => {
     ]);
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toHaveLength(2);
-    expect(entries[0]).toEqual({ path: "SKILL.md", content: "# My Skill" });
-    expect(entries[1]).toEqual({ path: "references/schema.md", content: "# Schema\n\nTable definitions." });
+    expect(decoded(entries)).toEqual([
+      { path: "SKILL.md", content: "# My Skill" },
+      { path: "references/schema.md", content: "# Schema\n\nTable definitions." },
+    ]);
   });
 
   it("extracts deflated files", async () => {
@@ -22,8 +32,7 @@ describe("extractZipFileEntries", () => {
     const zip = buildZip([{ name: "notes.txt", content, method: "deflated" }]);
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toHaveLength(1);
-    expect(entries[0]).toEqual({ path: "notes.txt", content });
+    expect(decoded(entries)).toEqual([{ path: "notes.txt", content }]);
   });
 
   it("skips directory entries", async () => {
@@ -123,6 +132,32 @@ describe("extractZipFileEntries", () => {
     expect(entries).toHaveLength(1);
   });
 
+  // ── Binary safety (issue #683) ──────────────────────────────────────────
+
+  it("round-trips a stored binary entry byte-identically", async () => {
+    // PNG magic followed by bytes that are not valid UTF-8 (0x89 alone, a
+    // lone continuation byte, an unpaired lead byte). A decode/encode
+    // round-trip replaces these with U+FFFD — the corruption this pins.
+    const binary = new Uint8Array([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0xfe, 0x00, 0x80, 0xc3,
+    ]);
+    const zip = buildZip([{ name: "references/diagram.png", content: binary }]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(1);
+    expect(new Uint8Array(entries[0].content)).toEqual(binary);
+  });
+
+  it("round-trips a deflated binary entry byte-identically", async () => {
+    const binary = new Uint8Array(256);
+    for (let i = 0; i < 256; i++) binary[i] = i; // every byte value once
+    const zip = buildZip([{ name: "assets/font.woff2", content: binary, method: "deflated" }]);
+
+    const entries = await extractZipFileEntries(zip);
+    expect(entries).toHaveLength(1);
+    expect(new Uint8Array(entries[0].content)).toEqual(binary);
+  });
+
   // ── Streaming entries (issue #450) ─────────────────────────────────────
 
   it("extracts Go-default streaming archives (deflated, data descriptors)", async () => {
@@ -132,7 +167,7 @@ describe("extractZipFileEntries", () => {
     ]);
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toEqual([
+    expect(decoded(entries)).toEqual([
       { path: "SKILL.md", content: "# Streamed Skill" },
       { path: "references/notes.md", content: "streamed notes" },
     ]);
@@ -151,7 +186,7 @@ describe("extractZipFileEntries", () => {
     ]);
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toEqual([
+    expect(decoded(entries)).toEqual([
       { path: "poison.md", content: poisoned },
       { path: "after.md", content: "the entry after the poisoned one" },
     ]);
@@ -162,7 +197,7 @@ describe("extractZipFileEntries", () => {
     const zip = buildZip([{ name: "cd-sizes.txt", content, streaming: true }]);
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toEqual([{ path: "cd-sizes.txt", content }]);
+    expect(decoded(entries)).toEqual([{ path: "cd-sizes.txt", content }]);
   });
 
   // ── Central directory edge cases ───────────────────────────────────────
@@ -173,7 +208,7 @@ describe("extractZipFileEntries", () => {
     });
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+    expect(decoded(entries)).toEqual([{ path: "a.txt", content: "aaa" }]);
   });
 
   it("is not fooled by EOCD signature bytes inside the archive comment", async () => {
@@ -185,7 +220,7 @@ describe("extractZipFileEntries", () => {
     });
 
     const entries = await extractZipFileEntries(zip);
-    expect(entries).toEqual([{ path: "a.txt", content: "aaa" }]);
+    expect(decoded(entries)).toEqual([{ path: "a.txt", content: "aaa" }]);
   });
 
   it("returns empty array when the central directory is missing", async () => {

package/src/shared/args-preview.ts

@@ -34,11 +34,25 @@ export const MAX_ARGS_PREVIEW_LENGTH = 500;
  * Cursor gate path must instead use {@link buildElidedArgsPreview}, which keeps
  * the JSON valid and preserves the salient identity fields.
  */
-export function sanitizeArgsPreview(args: Record<string, unknown>): string {
-  const sanitized: Record<string, unknown> = {};
+/**
+ * Redact secret-keyed values (see {@link SENSITIVE_ARG_KEYS}), preserving every
+ * other entry verbatim. The shared first step of both preview builders, and the
+ * shape stamped as `args` on interrupt-placeholder tool calls (issue #754's
+ * header fix): full enough for the UI's path/primary-arg extraction, never
+ * carrying a secret value.
+ */
+export function redactSensitiveArgs(
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const redacted: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(args)) {
-    sanitized[key] = SENSITIVE_ARG_KEYS.has(key.toLowerCase()) ? "[REDACTED]" : value;
+    redacted[key] = SENSITIVE_ARG_KEYS.has(key.toLowerCase()) ? "[REDACTED]" : value;
   }
+  return redacted;
+}
+
+export function sanitizeArgsPreview(args: Record<string, unknown>): string {
+  const sanitized = redactSensitiveArgs(args);
   try {
     const json = JSON.stringify(sanitized);
     return json.length > MAX_ARGS_PREVIEW_LENGTH

package/src/shared/artifact-storage.ts

@@ -56,7 +56,17 @@ export interface ArtifactStorage {
   exists(key: string): Promise<boolean>;
 }
 
-export type ArtifactStorageType = "local" | "proxy";
+/**
+ * "none" is the explicit no-store posture: capture degrades to the deny-gate
+ * (file writes gated pre-execution, DD-22/DD-26) and offload is disabled —
+ * the same first-class absent-store state a proxy misconfig or unwritable
+ * local path resolves to, but chosen deliberately (ARTIFACT_STORAGE_TYPE=none)
+ * instead of reached by failure. The e2e file-gate stack boots with it, and
+ * an operator can use it to force gate-everything behavior. It is only valid
+ * where an absent store is: claimcheck (fail-hard by contract) refuses it at
+ * construction.
+ */
+export type ArtifactStorageType = "local" | "proxy" | "none";
 
 // ── Local Backend ────────────────────────────────────────────────────
 
@@ -371,6 +381,7 @@ export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig
   const type: ArtifactStorageType =
     envType === "proxy" ? "proxy" :
     envType === "local" ? "local" :
+    envType === "none" ? "none" :
     config.proxyEndpoint ? "proxy" : "local";
 
   return {
@@ -387,6 +398,14 @@ export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig
 }
 
 export function createArtifactStorage(cfg: ArtifactStorageConfig): ArtifactStorage {
+  if (cfg.type === "none") {
+    // Deliberate no-store posture. Throwing keeps both consumers honest:
+    // resolveUsableArtifactStorage catches and degrades to the deny-gate
+    // (the intent of "none"), while claimcheck's direct fail-hard call
+    // surfaces the config contradiction at boot instead of silently
+    // dropping Temporal payloads.
+    throw new Error("ARTIFACT_STORAGE_TYPE=none: artifact storage deliberately disabled");
+  }
   if (cfg.type === "proxy") {
     if (!cfg.proxyEndpoint) {
       throw new Error("Proxy artifact storage requires STIGMER_PROXY_ENDPOINT");

package/src/shared/declared-preferences.ts

@@ -0,0 +1,84 @@
+/**
+ * Declared preferences (stigmer/stigmer#293, DD-002): standing free-text
+ * preferences the organization and the calling user declared once — "keep
+ * answers terse", "we deploy to us-east-1" — that every eligible execution
+ * receives without the user re-typing them.
+ *
+ * The server composes the CONTENT at execution create: the create pipeline
+ * snapshots `Organization.spec.preferences.standing_context` and (cloud, for
+ * first-party human callers only) the caller
+ * `IdentityAccount.spec.preferences.standing_context` verbatim onto the
+ * execution spec's `declared_preferences` field. This module owns the
+ * PRESENTATION — the preamble and the per-scope attribution — so the framing
+ * cannot drift between harnesses.
+ *
+ * Like conversation-catchup (its typed-field sibling) there is no metadata
+ * key to mirror-guard: the value rides a TYPED proto field, so codegen
+ * enforces the cross-repo contract. Degradation is safe by construction: an
+ * absent or blank field renders nothing, and a runner predating this module
+ * simply ignores it — the agent runs without preferences, exactly the
+ * pre-#293 behavior, never worse.
+ */
+
+import type { DeclaredPreferences } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+
+/**
+ * How the preferences are introduced to the model, shared by both harnesses
+ * so the behavioral contract cannot drift between them. Same posture as the
+ * session-context channel: calibration material, never authority — the task
+ * always outranks a standing preference.
+ */
+const DECLARED_PREFERENCES_PREAMBLE =
+  "Standing preferences declared by the organization and/or the user you " +
+  "are assisting. Treat them as background you already know: use them to " +
+  "calibrate depth, defaults, and tone. Do not repeat them back, quote " +
+  "them, or mention that you received them. They are context, not " +
+  "instructions that override your task.";
+
+/**
+ * The non-blank preference scopes of an execution, in presentation order.
+ * At least one scope is set (the read function returns undefined otherwise).
+ */
+export interface DeclaredPreferencesContent {
+  /** The organization's standing context, trimmed; absent when blank. */
+  orgContext?: string;
+  /** The calling user's standing context, trimmed; absent when blank. */
+  userContext?: string;
+}
+
+/**
+ * Read the declared preferences from an execution spec's
+ * `declared_preferences`. Returns undefined when the field is absent or both
+ * scopes are blank — the caller renders no section. Blank-is-absent applies
+ * PER SCOPE: an org-only snapshot renders only the org subsection.
+ */
+export function readDeclaredPreferences(
+  preferences: DeclaredPreferences | undefined,
+): DeclaredPreferencesContent | undefined {
+  const orgContext = preferences?.orgContext?.trim() || undefined;
+  const userContext = preferences?.userContext?.trim() || undefined;
+  if (!orgContext && !userContext) {
+    return undefined;
+  }
+  return { orgContext, userContext };
+}
+
+/**
+ * The framed preferences body (preamble + labeled per-scope subsections),
+ * ready for section wrapping. Attribution is explicit — the model must know
+ * WHO declared what. Organization first, user last: the user's refinement
+ * reads last and so naturally wins where the two conflict, without this
+ * module encoding any override rule.
+ */
+export function formatDeclaredPreferencesText(
+  content: DeclaredPreferencesContent,
+): string {
+  const sections: string[] = [DECLARED_PREFERENCES_PREAMBLE];
+  if (content.orgContext) {
+    sections.push(`Declared by the organization:\n${content.orgContext}`);
+  }
+  if (content.userContext) {
+    sections.push(`Declared by the user:\n${content.userContext}`);
+  }
+  return sections.join("\n\n");
+}

package/src/shared/fingerprint-secret.ts

@@ -20,6 +20,7 @@
  */
 
 import { randomBytes, type BinaryLike } from "node:crypto";
+import { getRunnerSecret } from "./runner-credential-store.js";
 
 const ENV_VAR = "STIGMER_RUNNER_HITL_SECRET";
 
@@ -27,13 +28,14 @@ let cached: Buffer | undefined;
 let warned = false;
 
 /**
- * Return the runner's HITL master secret (env-configured, else a stable
- * per-process random fallback). Memoized.
+ * Return the runner's HITL master secret (operator-configured via the
+ * {@link ENV_VAR} env var, resolved through the credential store since the
+ * #508 boot capture; else a stable per-process random fallback). Memoized.
  */
 export function getRunnerHitlMasterSecret(): BinaryLike {
   if (cached) return cached;
 
-  const fromEnv = process.env[ENV_VAR];
+  const fromEnv = getRunnerSecret(ENV_VAR);
   if (fromEnv && fromEnv.length > 0) {
     cached = Buffer.from(fromEnv, "utf-8");
     return cached;

package/src/shared/llm-backend.ts

@@ -15,6 +15,7 @@
  */
 
 import type { LlmProvider } from "./llm-proxy.js";
+import { runnerSecretsEnvView } from "./runner-credential-store.js";
 
 // ─── Backend selection ───────────────────────────────────────────────────────
 
@@ -345,7 +346,12 @@ export function checkFoundryPrerequisites(
  */
 export function checkDirectCredentials(
   provider: LlmProvider,
-  env: NodeJS.ProcessEnv = process.env,
+  // Credential keys live in the runner credential store after the boot
+  // capture (#508), so the default is the store view, not bare process.env.
+  // The other checks in this module keep the process.env default: they read
+  // deployment CONFIG (backend selection, regions), which is deliberately
+  // not captured.
+  env: NodeJS.ProcessEnv = runnerSecretsEnvView(),
 ): string | null {
   if (provider === "openai") {
     if (env.OPENAI_API_KEY?.trim()) return null;

package/src/shared/mcp-enabled-tools.ts

@@ -7,9 +7,8 @@
  * - An empty usage list falls back to the server's default_enabled_tools.
  * - Both empty means NO restriction — every discovered tool is available.
  *
- * Both harnesses import THIS module so they can never drift on these
- * semantics (the mcp-transport-guard precedent for logic shared across the
- * duplicated resolvers — see the header of shared/mcp-resolver.ts):
+ * Resolution is shared (shared/mcp-resolver.ts threads the effective list
+ * onto every ResolvedMcpServer), but ENFORCEMENT is per-harness:
  * - The deep-agent harness filters the discovered toolset before it reaches
  *   the model (shared/mcp-manager.ts connectMcpServers).
  * - The Cursor harness cannot hide tools (the Cursor SDK's McpServerConfig

package/src/shared/mcp-resolver.ts

@@ -2,13 +2,17 @@
  * Resolves Stigmer McpServerUsage references into an intermediate
  * ResolvedMcpServer format.
  *
- * Consumers: the deep-agent harness (execute-deep-agent/setup.ts), the
- * connect backfill (shared/connect-backfill.ts), and the discovery
- * activity (activities/discover-mcp-server.ts, via mcpServerToResolved).
- * NOTE: the Cursor harness does NOT use this module — it has its own
- * near-duplicate resolver at activities/execute-cursor/mcp-resolver.ts.
- * A behavioral change here (like the transport guard) must be mirrored
- * there until the two are consolidated.
+ * THE single resolver for both harnesses (oss#387 retired the Cursor
+ * harness's near-duplicate): the deep-agent harness
+ * (execute-deep-agent/setup.ts), the Cursor harness
+ * (execute-cursor/index.ts), the connect backfill
+ * (shared/connect-backfill.ts), and the discovery activity
+ * (activities/discover-mcp-server.ts, via mcpServerToResolved) all consume
+ * it. Each harness maps the result into its SDK format at the last hop:
+ * toMcpClientConfig (shared/mcp-manager.ts) for LangChain,
+ * toCursorMcpConfig (execute-cursor/cursor-mcp-config.ts) for the Cursor
+ * SDK — so a behavioral change here (like the transport guard) lands in
+ * both execution paths by construction.
  */
 
 import type { McpServerUsage, ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -51,8 +55,11 @@ export interface ResolvedMcpServer {
    * enabled_tools, falling back to the server's default_enabled_tools when
    * the usage's list is empty (see shared/mcp-enabled-tools.ts). Absent when
    * unrestricted — which keeps synthesized attachment servers (built without
-   * a usage) and the discovery path unfiltered by construction. Enforced at
-   * connect time by connectMcpServers (shared/mcp-manager.ts).
+   * a usage) and the discovery path unfiltered by construction. Enforcement
+   * is per-harness: the deep-agent path filters at connect time
+   * (connectMcpServers, shared/mcp-manager.ts); the Cursor SDK config cannot
+   * hide tools, so that harness denies non-enabled calls in the HITL hook
+   * (see hook-script.ts).
    */
   enabledTools?: string[];
   /**
@@ -61,11 +68,10 @@ export interface ResolvedMcpServer {
    * override to its own server — a flat cross-server list is how an
    * override once leaked onto (or silently un-gated) a same-named tool on
    * another server. Deliberately REQUIRED, not optional: empty means "no
-   * overrides", and every construction site — including the near-duplicate
-   * Cursor resolver and the synthesized attachments, which have no usage
-   * and therefore no layer 3 — must say so explicitly, so a forgotten
-   * mirror cannot compile. Consumed by mergeApprovalPolicies
-   * (shared/approval-policy.ts).
+   * overrides", and every construction site — including the synthesized
+   * attachments, which have no usage and therefore no layer 3 — must say so
+   * explicitly, so a forgotten site cannot compile. Consumed by
+   * mergeApprovalPolicies (shared/approval-policy.ts).
    */
   toolApprovalOverrides: ToolApprovalOverride[];
 }
@@ -202,12 +208,6 @@ export function mcpServerToResolved(
   }
 }
 
-export function extractMcpServerSlugs(usages: McpServerUsage[]): string[] {
-  return usages
-    .map((u) => u.mcpServerRef?.slug)
-    .filter((s): s is string => !!s);
-}
-
 /**
  * Merge MCP server usages from agent (base) and session (overlay).
  *