@stigmer/runner 3.12.4 → 3.12.5

package/dist/shared/skill-mount.js

@@ -0,0 +1,142 @@
+/**
+ * Skill mount mechanics — the ONE cache shape shared by both harnesses.
+ *
+ * A skill "mount" is the on-disk materialization of a skill inside the
+ * session's platform directory: `{platformDir}/skills/{name}/` holding
+ * SKILL.md plus the artifact's supporting files. Both harnesses write to
+ * that same physical location — the Cursor harness directly, the native
+ * (deep-agent) harness through the `.stigmer/` virtual namespace that
+ * LocalWorkspaceBackend routes there — so they MUST share one cache shape
+ * (issues #337/#672). This module owns that shape:
+ *
+ * - The mount is cached by the skill's content-addressed
+ *   `status.version_hash`: metadata is still fetched every execution
+ *   (that keeps latest-version freshness — push a skill update and the
+ *   very next message picks it up), but the artifact download and file
+ *   rewrite are skipped when the mounted content's hash already matches.
+ * - Remounts rebuild the directory from scratch, so files deleted between
+ *   skill versions never linger in the mount.
+ * - Crash-safe by ordering: the marker is stamped 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.
+ *
+ * Extracted from execute-cursor/skill-resolver.ts (PR #682) when the
+ * deep-agent path adopted the same cache (issue #337). Orchestration —
+ * which skills to mount, prompt metadata, degradation logging — stays
+ * with each harness; only the per-skill-directory mechanics live here.
+ */
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { join, dirname, extname, resolve } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
+import { extractZipFileEntries } from "./zip-extract.js";
+/** Subdirectory of the platform dir where skill mounts live. */
+export 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.
+ */
+export const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+/**
+ * File extensions written with the executable bit set. The ZIP layer is
+ * deliberately mode-blind (path + bytes only, see zip-extract.ts), so
+ * extension is the only signal available for `./script.sh`-style
+ * invocation to work out of the mount.
+ */
+const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+/**
+ * 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.
+ */
+export async function mountIsFresh(skillDir, versionHash, wantsArtifact) {
+    try {
+        const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
+        const marker = JSON.parse(raw);
+        return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (the hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ */
+export async function downloadArtifact(client, artifactStorageKey) {
+    let minted;
+    try {
+        minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+    }
+    catch (err) {
+        if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+            const resp = await client.getSkillArtifact(artifactStorageKey);
+            return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+        }
+        throw err;
+    }
+    const resp = await fetch(minted.url);
+    if (!resp.ok) {
+        throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+    }
+    const bytes = new Uint8Array(await resp.arrayBuffer());
+    if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+        throw new Error(`artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`);
+    }
+    return bytes.length > 0 ? bytes : undefined;
+}
+/**
+ * (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, which the push pipeline guarantees is non-empty
+ * (push.go hard-fails a ZIP without an extractable SKILL.md) — 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.
+ *
+ * Every extracted entry must resolve inside `skillDir`. The server already
+ * rejects traversal at push (google/safearchive), but this runner-side
+ * check is kept as defense-in-depth: it is the guard the deep-agent path
+ * used to get from LocalWorkspaceBackend's platform-path routing, preserved
+ * here when skill writes moved to direct fs.
+ */
+export async function writeSkillMount(skill, skillDir, artifactBytes) {
+    await rm(skillDir, { recursive: true, force: true });
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(join(skillDir, "SKILL.md"), skill.spec.skillMd, "utf-8");
+    const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+    if (artifactMounted) {
+        const normalizedSkillDir = resolve(skillDir);
+        const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
+        for (const entry of entries) {
+            const filePath = resolve(normalizedSkillDir, entry.path);
+            if (filePath !== normalizedSkillDir && !filePath.startsWith(normalizedSkillDir + "/")) {
+                throw new Error(`skill artifact entry escapes its mount directory: '${entry.path}'`);
+            }
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, entry.content, {
+                mode: SCRIPT_EXTENSIONS.has(extname(entry.path)) ? 0o755 : 0o644,
+            });
+        }
+    }
+    const versionHash = skill.status?.versionHash ?? "";
+    if (versionHash !== "") {
+        const marker = { versionHash, artifactMounted };
+        await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+    }
+}
+//# sourceMappingURL=skill-mount.js.map

package/dist/shared/skill-mount.js.map

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

package/dist/shared/skill-writer.d.ts

@@ -1,5 +1,5 @@
 /**
- * Skill writing and prompt generation for the deep-agent execution path.
+ * Skill mounting and prompt generation for the deep-agent execution path.
  *
  * Follows the Agent Skills specification progressive disclosure model:
  *
@@ -10,11 +10,18 @@
  * 3. Resources (on demand) — scripts, references, and assets are
  *    loaded by the agent only when required.
  *
- * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
- * Returned paths are workspace-relative so that the agent's sandbox backend
- * resolves them correctly regardless of mount strategy.
+ * Skills physically live in the session's platform directory
+ * (`{platformDir}/skills/{name}/` — the SAME location the Cursor harness
+ * mounts into), and the agent sees them as `.stigmer/skills/{name}/`
+ * through the per-turn workspace symlink (see workspace/stigmer-link.ts).
+ * Returned paths are the agent-visible `.stigmer/…` form.
+ *
+ * Mounts are cached by the skill's content-addressed version hash via the
+ * shared skill-mount mechanics (issue #337, mirroring the Cursor harness's
+ * #672 fix): metadata is fetched every execution — a pushed skill update
+ * still lands on the very next message — but an unchanged skill skips the
+ * artifact download and rewrite entirely.
  */
-import type { WorkspaceBackend } from "./workspace/types.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
@@ -33,24 +40,24 @@ export declare function mergeSkillRefs(agentRefs: readonly ApiResourceReference[
  */
 export declare function fetchSkillsByRefs(client: StigmerClient, refs: readonly ApiResourceReference[]): Promise<Skill[]>;
 /**
- * Write skill artifacts to the workspace. Returns a map of
- * skill-id -> workspace-relative directory path.
+ * Mount skills into the session's platform directory, downloading each
+ * skill's artifact only on a version-hash cache miss (see skill-mount.ts
+ * for the marker mechanics). Returns a map of skill-id -> agent-visible
+ * directory path.
  *
- * For each skill:
- * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
- * - Otherwise, write just the SKILL.md from the spec
- * - Make scripts executable
- */
-export declare function writeSkills(skills: readonly Skill[], workspaceBackend: WorkspaceBackend, artifacts: ReadonlyMap<string, Uint8Array>): Promise<SkillPathMap>;
-/**
- * Compute skill paths without writing anything (for resume integrity checks).
- */
-export declare function computeSkillPaths(skills: readonly Skill[]): Map<string, string>;
-/**
- * Check workspace integrity for resume fast-path.
- * Returns true if the sentinel SKILL.md file exists for the first skill.
+ * The returned map is a NAMING function, not a success record: every skill
+ * gets its path entry so prompt generation stays total, while mount
+ * failures degrade that one skill (loud log, no throw) — one broken skill
+ * must never kill the run.
+ *
+ * Skills mount in parallel (each owns an independent directory), EXCEPT
+ * when two skills resolve to the same directory name (same `spec.name`
+ * from different orgs): concurrent remove-and-rewrite passes on one
+ * directory would corrupt the mount, so only the first claimant mounts and
+ * the collision is logged loudly. (The sequential code this replaced
+ * silently let the last writer win — no better, just quieter.)
  */
-export declare function checkSkillIntegrity(skills: readonly Skill[], workspaceBackend: WorkspaceBackend): Promise<boolean>;
+export declare function mountSkills(client: StigmerClient, skills: readonly Skill[], platformDir: string): Promise<SkillPathMap>;
 /**
  * Generate the system prompt section following the Agent Skills spec
  * progressive disclosure model.
@@ -66,8 +73,3 @@ export declare function generatePromptSection(skills: readonly Skill[], skillPat
  * they are needed mid-conversation.
  */
 export declare function generateAlsoAvailableSection(excludedNames: readonly string[]): string;
-/**
- * Download skill artifacts for all skills that have a storage key.
- * Returns a map from skill ID to artifact bytes.
- */
-export declare function fetchSkillArtifacts(client: StigmerClient, skills: readonly Skill[]): Promise<Map<string, Uint8Array>>;

package/dist/shared/skill-writer.js

@@ -1,5 +1,5 @@
 /**
- * Skill writing and prompt generation for the deep-agent execution path.
+ * Skill mounting and prompt generation for the deep-agent execution path.
  *
  * Follows the Agent Skills specification progressive disclosure model:
  *
@@ -10,13 +10,23 @@
  * 3. Resources (on demand) — scripts, references, and assets are
  *    loaded by the agent only when required.
  *
- * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
- * Returned paths are workspace-relative so that the agent's sandbox backend
- * resolves them correctly regardless of mount strategy.
+ * Skills physically live in the session's platform directory
+ * (`{platformDir}/skills/{name}/` — the SAME location the Cursor harness
+ * mounts into), and the agent sees them as `.stigmer/skills/{name}/`
+ * through the per-turn workspace symlink (see workspace/stigmer-link.ts).
+ * Returned paths are the agent-visible `.stigmer/…` form.
+ *
+ * Mounts are cached by the skill's content-addressed version hash via the
+ * shared skill-mount mechanics (issue #337, mirroring the Cursor harness's
+ * #672 fix): metadata is fetched every execution — a pushed skill update
+ * still lands on the very next message — but an unchanged skill skips the
+ * artifact download and rewrite entirely.
  */
-import { extractZipFileEntries } from "./zip-extract.js";
-const SKILLS_RELATIVE_BASE = ".stigmer/skills";
-const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+import { join } from "node:path";
+import { SKILLS_SUBDIR, mountIsFresh, downloadArtifact, writeSkillMount, } from "./skill-mount.js";
+import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
+/** Agent-visible base of the skills tree (via the workspace `.stigmer` symlink). */
+const SKILLS_RELATIVE_BASE = `${STIGMER_LOCAL_STATE_DIR}/${SKILLS_SUBDIR}`;
 // ─── Fetch ───────────────────────────────────────────────────────────────
 /**
  * Merge skill refs from agent and session specs (union, dedup by slug,
@@ -59,87 +69,80 @@ export async function fetchSkillsByRefs(client, refs) {
     }
     return results;
 }
-// ─── Write ───────────────────────────────────────────────────────────────
+// ─── Mount ───────────────────────────────────────────────────────────────
 /**
- * Write skill artifacts to the workspace. Returns a map of
- * skill-id -> workspace-relative directory path.
+ * Mount skills into the session's platform directory, downloading each
+ * skill's artifact only on a version-hash cache miss (see skill-mount.ts
+ * for the marker mechanics). Returns a map of skill-id -> agent-visible
+ * directory path.
+ *
+ * The returned map is a NAMING function, not a success record: every skill
+ * gets its path entry so prompt generation stays total, while mount
+ * failures degrade that one skill (loud log, no throw) — one broken skill
+ * must never kill the run.
  *
- * For each skill:
- * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
- * - Otherwise, write just the SKILL.md from the spec
- * - Make scripts executable
+ * Skills mount in parallel (each owns an independent directory), EXCEPT
+ * when two skills resolve to the same directory name (same `spec.name`
+ * from different orgs): concurrent remove-and-rewrite passes on one
+ * directory would corrupt the mount, so only the first claimant mounts and
+ * the collision is logged loudly. (The sequential code this replaced
+ * silently let the last writer win — no better, just quieter.)
  */
-export async function writeSkills(skills, workspaceBackend, artifacts) {
+export async function mountSkills(client, skills, platformDir) {
     const paths = new Map();
+    const claims = new Map();
     for (const skill of skills) {
         const name = skill.spec?.name || skill.metadata?.slug || "unknown";
         const skillId = skill.metadata?.id ?? name;
-        const relativeDir = `${SKILLS_RELATIVE_BASE}/${name}`;
-        paths.set(skillId, relativeDir);
-        const artifactBytes = artifacts.get(skillId);
-        if (skill.spec?.skillMd) {
-            const skillMdPath = `${relativeDir}/SKILL.md`;
-            await workspaceBackend.writeFile(skillMdPath, skill.spec.skillMd);
-            if (artifactBytes && artifactBytes.length > 0) {
-                await extractZipToWorkspaceExcluding(artifactBytes, "SKILL.md", relativeDir, workspaceBackend);
-            }
+        paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
+        // Impossible through the push pipeline (push.go hard-fails a ZIP
+        // without an extractable SKILL.md and always populates spec.skill_md),
+        // so an empty skillMd means a broken resource — skip, same as Cursor.
+        if (!skill.spec?.skillMd) {
+            console.warn(`[skill-writer] skill ${name} (${skillId}) has no skillMd content — skipping mount`);
+            continue;
         }
-        else if (artifactBytes && artifactBytes.length > 0) {
-            await extractZipToWorkspace(artifactBytes, relativeDir, workspaceBackend);
+        const prev = claims.get(name);
+        if (prev) {
+            console.warn(`[skill-writer] mount directory collision on '${name}': ` +
+                `${prev.metadata?.org}/${prev.metadata?.slug} already claims it, ` +
+                `skipping ${skill.metadata?.org}/${skill.metadata?.slug}`);
+            continue;
         }
-        await makeScriptsExecutable(relativeDir, workspaceBackend);
+        claims.set(name, skill);
     }
+    await Promise.all([...claims.entries()].map(async ([name, skill]) => {
+        const skillDir = join(platformDir, SKILLS_SUBDIR, name);
+        try {
+            const versionHash = skill.status?.versionHash ?? "";
+            const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
+            if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+                console.log(`[skill-writer] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`);
+                return;
+            }
+            let artifactBytes;
+            if (wantsArtifact) {
+                try {
+                    artifactBytes = await downloadArtifact(client, skill.status.artifactStorageKey);
+                }
+                catch (err) {
+                    // Deliberate degradation, but LOUD (#675): the run still gets
+                    // SKILL.md, and the marker records artifactMounted=false so the
+                    // next execution retries the download.
+                    console.error(`[skill-writer] artifact download FAILED for ${name} ` +
+                        `(key=${skill.status.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+                        `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            await writeSkillMount(skill, skillDir, artifactBytes);
+            console.log(`[skill-writer] wrote skill mount: ${name}`);
+        }
+        catch (err) {
+            console.warn(`[skill-writer] failed to mount skill ${name}: ${err instanceof Error ? err.message : err}`);
+        }
+    }));
     return { paths };
 }
-/**
- * Compute skill paths without writing anything (for resume integrity checks).
- */
-export function computeSkillPaths(skills) {
-    const paths = new Map();
-    for (const skill of skills) {
-        const name = skill.spec?.name || skill.metadata?.slug || "unknown";
-        const skillId = skill.metadata?.id ?? name;
-        paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
-    }
-    return paths;
-}
-/**
- * Check workspace integrity for resume fast-path.
- * Returns true if the sentinel SKILL.md file exists for the first skill.
- */
-export async function checkSkillIntegrity(skills, workspaceBackend) {
-    if (skills.length === 0)
-        return true;
-    const paths = computeSkillPaths(skills);
-    const firstPath = paths.values().next().value;
-    if (!firstPath)
-        return true;
-    const sentinel = `${firstPath}/SKILL.md`;
-    return workspaceBackend.exists(sentinel);
-}
-// ─── ZIP extraction ──────────────────────────────────────────────────────
-async function extractZipToWorkspace(zipBytes, targetDir, backend) {
-    const entries = await extractZipFileEntries(zipBytes);
-    for (const entry of entries) {
-        await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-    }
-}
-async function extractZipToWorkspaceExcluding(zipBytes, excludeName, targetDir, backend) {
-    const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
-    for (const entry of entries) {
-        await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-    }
-}
-async function makeScriptsExecutable(relativeDir, backend) {
-    const extensions = [...SCRIPT_EXTENSIONS].map(ext => `-name '*${ext}'`).join(" -o ");
-    const cmd = `find ${relativeDir} -type f \\( ${extensions} \\) -exec chmod +x {} \\; 2>/dev/null || true`;
-    try {
-        await backend.execute(cmd);
-    }
-    catch {
-        // Non-fatal: scripts may not be executable in all environments
-    }
-}
 // ─── Prompt generation ───────────────────────────────────────────────────
 /**
  * Generate the system prompt section following the Agent Skills spec
@@ -201,30 +204,4 @@ export function generateAlsoAvailableSection(excludedNames) {
         "If you determine one of them is relevant to your task, " +
         "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n");
 }
-// ─── Artifact fetching ───────────────────────────────────────────────────
-/**
- * Download skill artifacts for all skills that have a storage key.
- * Returns a map from skill ID to artifact bytes.
- */
-export async function fetchSkillArtifacts(client, skills) {
-    const artifacts = new Map();
-    const fetches = skills
-        .filter(s => s.status?.artifactStorageKey)
-        .map(async (skill) => {
-        const key = skill.status.artifactStorageKey;
-        const skillId = skill.metadata?.id ?? skill.spec?.name ?? "unknown";
-        try {
-            const response = await client.getSkillArtifact(key);
-            if (response.artifact && response.artifact.length > 0) {
-                artifacts.set(skillId, response.artifact);
-            }
-        }
-        catch (err) {
-            console.warn(`[skill-writer] Failed to download artifact for ${skill.spec?.name}: ` +
-                `${err instanceof Error ? err.message : String(err)}. Falling back to SKILL.md only.`);
-        }
-    });
-    await Promise.all(fetches);
-    return artifacts;
-}
 //# sourceMappingURL=skill-writer.js.map

package/dist/shared/skill-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-writer.js","sourceRoot":"","sources":["../../src/shared/skill-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill-writer.js","sourceRoot":"","sources":["../../src/shared/skill-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,OAAO,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,oFAAoF;AACpF,MAAM,oBAAoB,GAAG,GAAG,uBAAuB,IAAI,aAAa,EAAE,CAAC;AAS3E,4EAA4E;AAE5E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA0C,EAC1C,WAA4C;IAE5C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;IACvD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,GAAG,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAqB,EACrB,IAAqC;IAErC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAY,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACrC,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,wCAAwC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,IAAI;gBAC/D,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACtD,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4EAA4E;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAqB,EACrB,MAAwB,EACxB,WAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAExC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,SAAS,CAAC;QACnE,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAI,CAAC;QAC3C,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,oBAAoB,IAAI,IAAI,EAAE,CAAC,CAAC;QAEtD,iEAAiE;QACjE,uEAAuE;QACvE,sEAAsE;QACtE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,CACV,wBAAwB,IAAI,KAAK,OAAO,2CAA2C,CACpF,CAAC;YACF,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,IAAI,CACV,gDAAgD,IAAI,KAAK;gBACzD,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,IAAI,sBAAsB;gBAClE,YAAY,KAAK,CAAC,QAAQ,EAAE,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAC1D,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC;YACpD,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;YAEhE,IAAI,WAAW,KAAK,EAAE,IAAI,CAAC,MAAM,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;gBACrF,OAAO,CAAC,GAAG,CACT,mCAAmC,IAAI,aAAa,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,gCAAgC,CAC7G,CAAC;gBACF,OAAO;YACT,CAAC;YAED,IAAI,aAAqC,CAAC;YAC1C,IAAI,aAAa,EAAE,CAAC;gBAClB,IAAI,CAAC;oBACH,aAAa,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAO,CAAC,kBAAkB,CAAC,CAAC;gBACnF,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,8DAA8D;oBAC9D,gEAAgE;oBAChE,uCAAuC;oBACvC,OAAO,CAAC,KAAK,CACX,+CAA+C,IAAI,GAAG;wBACtD,QAAQ,KAAK,CAAC,MAAO,CAAC,kBAAkB,4CAA4C;wBACpF,0DAA0D,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CACrG,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,MAAM,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;YACtD,OAAO,CAAC,GAAG,CAAC,qCAAqC,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CACV,wCAAwC,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAC5F,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC,CAAC;IAEJ,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,4EAA4E;AAE5E;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAwB,EACxB,UAAuC;IAEvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,KAAK,GAAa;QACtB,EAAE;QACF,EAAE;QACF,WAAW;QACX,EAAE;QACF,2EAA2E;YAC3E,4BAA4B;QAC5B,EAAE;QACF,kEAAkE;YAClE,sEAAsE;YACtE,sCAAsC;QACtC,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,8DAA8D;QAC9D,qDAAqD;QACrD,8CAA8C;QAC9C,EAAE;QACF,wCAAwC;QACxC,gDAAgD;QAChD,EAAE;KACH,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,SAAS,CAAC;QACnE,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,EAAE,IAAI,IAAI,CAAC;QAC3C,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,oBAAoB,IAAI,IAAI,EAAE,CAAC;QAC9E,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,WAAW,IAAI,kBAAkB,CAAC;QAElE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAC;QAC9C,KAAK,CAAC,IAAI,CAAC,mBAAmB,QAAQ,KAAK,CAAC,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,wBAAwB,QAAQ,aAAa,CAAC,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,aAAgC;IAEhC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,CACL,0BAA0B;QAC1B,8DAA8D,QAAQ,IAAI;QAC1E,yDAAyD;QACzD,0EAA0E,CAC3E,CAAC;AACJ,CAAC"}

package/dist/shared/worker-shutdown.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-task-queue worker-shutdown signals — the classification channel that
+ * lets an in-flight activity distinguish "my worker is shutting down" from
+ * "the orchestrator cancelled me" (a user pause).
+ *
+ * The signal carries NO lifecycle authority: aborting it never stops a
+ * worker or an activity (Temporal's own drain does that). It exists purely
+ * so the activity's cancellation handling can classify the interruption
+ * honestly — a shutdown is not a pause, and must surface as the
+ * worker-shutdown failure shape the control planes recognize (issue #776).
+ *
+ * Ownership contract:
+ *   - whoever creates a Worker registers a signal for its queue BEFORE the
+ *     worker starts polling;
+ *   - whoever initiates a full shutdown (SIGTERM handler, desktop quit)
+ *     aborts the signal BEFORE calling worker.shutdown(), so activities
+ *     cancelled by the drain observe it already aborted;
+ *   - a graceful single-worker teardown (view close, deferred teardown in
+ *     the runner-manager) must NOT abort — those paths only run once no
+ *     activity is in flight, and aborting earlier is exactly the regression
+ *     that killed running activities on a view close.
+ *
+ * Module-level (not per-manager) because activities resolve their signal by
+ * task-queue name via {@link getShutdownSignalForQueue} without a handle to
+ * the runner/manager instance that created their worker.
+ */
+/**
+ * Register a fresh shutdown signal for a task queue, replacing any previous
+ * registration (a re-created worker on a reused queue must not observe the
+ * old worker's aborted signal). Returns the controller so the worker's owner
+ * can abort it at shutdown.
+ */
+export declare function registerWorkerShutdownSignal(taskQueue: string): AbortController;
+/** The signal an activity on `taskQueue` should observe, if one is registered. */
+export declare function getShutdownSignalForQueue(taskQueue: string): AbortSignal | undefined;
+/**
+ * Abort the queue's signal, marking any in-flight activity's imminent
+ * cancellation as a worker shutdown. Idempotent; no-op for an unknown queue.
+ */
+export declare function signalWorkerShutdown(taskQueue: string): void;
+/** Drop the registration once the queue's worker is fully torn down. */
+export declare function unregisterWorkerShutdownSignal(taskQueue: string): void;
+/** The evidence a turn's post-stream classification weighs (see below). */
+export interface TurnInterruptionEvidence {
+    /** The periodic heartbeat threw CancelledFailure with no shutdown signal. */
+    heartbeatCancelled: boolean;
+    /** The periodic heartbeat threw CancelledFailure with the signal aborted. */
+    heartbeatWorkerShutdown: boolean;
+    /** Temporal delivered cancellation to the activity. */
+    cancellationSignalAborted: boolean;
+    /** This queue's worker-shutdown signal is aborted. */
+    shutdownSignalAborted: boolean;
+}
+/**
+ * Classify how (whether) a turn's stream was interrupted, from the evidence
+ * available after the stream ends. Pure so the decision table is directly
+ * testable — the activities feed it their heartbeat flags and signals.
+ *
+ * The load-bearing rule is the grace-window guard (#776): an aborted
+ * shutdown signal ALONE is "none", because a run that completes normally
+ * inside the drain grace window reaches the classification with the signal
+ * already aborted and nothing actually interrupted. Shutdown requires
+ * interruption evidence (a heartbeat CancelledFailure or a delivered
+ * cancellation) alongside the signal; a heartbeat cancellation with no
+ * shutdown signal is the orchestrator's pause.
+ */
+export declare function classifyTurnInterruption(evidence: TurnInterruptionEvidence): "worker-shutdown" | "pause" | "none";

package/dist/shared/worker-shutdown.js

@@ -0,0 +1,79 @@
+/**
+ * Per-task-queue worker-shutdown signals — the classification channel that
+ * lets an in-flight activity distinguish "my worker is shutting down" from
+ * "the orchestrator cancelled me" (a user pause).
+ *
+ * The signal carries NO lifecycle authority: aborting it never stops a
+ * worker or an activity (Temporal's own drain does that). It exists purely
+ * so the activity's cancellation handling can classify the interruption
+ * honestly — a shutdown is not a pause, and must surface as the
+ * worker-shutdown failure shape the control planes recognize (issue #776).
+ *
+ * Ownership contract:
+ *   - whoever creates a Worker registers a signal for its queue BEFORE the
+ *     worker starts polling;
+ *   - whoever initiates a full shutdown (SIGTERM handler, desktop quit)
+ *     aborts the signal BEFORE calling worker.shutdown(), so activities
+ *     cancelled by the drain observe it already aborted;
+ *   - a graceful single-worker teardown (view close, deferred teardown in
+ *     the runner-manager) must NOT abort — those paths only run once no
+ *     activity is in flight, and aborting earlier is exactly the regression
+ *     that killed running activities on a view close.
+ *
+ * Module-level (not per-manager) because activities resolve their signal by
+ * task-queue name via {@link getShutdownSignalForQueue} without a handle to
+ * the runner/manager instance that created their worker.
+ */
+const registry = new Map();
+/**
+ * Register a fresh shutdown signal for a task queue, replacing any previous
+ * registration (a re-created worker on a reused queue must not observe the
+ * old worker's aborted signal). Returns the controller so the worker's owner
+ * can abort it at shutdown.
+ */
+export function registerWorkerShutdownSignal(taskQueue) {
+    const controller = new AbortController();
+    registry.set(taskQueue, controller);
+    return controller;
+}
+/** The signal an activity on `taskQueue` should observe, if one is registered. */
+export function getShutdownSignalForQueue(taskQueue) {
+    return registry.get(taskQueue)?.signal;
+}
+/**
+ * Abort the queue's signal, marking any in-flight activity's imminent
+ * cancellation as a worker shutdown. Idempotent; no-op for an unknown queue.
+ */
+export function signalWorkerShutdown(taskQueue) {
+    registry.get(taskQueue)?.abort();
+}
+/** Drop the registration once the queue's worker is fully torn down. */
+export function unregisterWorkerShutdownSignal(taskQueue) {
+    registry.delete(taskQueue);
+}
+/**
+ * Classify how (whether) a turn's stream was interrupted, from the evidence
+ * available after the stream ends. Pure so the decision table is directly
+ * testable — the activities feed it their heartbeat flags and signals.
+ *
+ * The load-bearing rule is the grace-window guard (#776): an aborted
+ * shutdown signal ALONE is "none", because a run that completes normally
+ * inside the drain grace window reaches the classification with the signal
+ * already aborted and nothing actually interrupted. Shutdown requires
+ * interruption evidence (a heartbeat CancelledFailure or a delivered
+ * cancellation) alongside the signal; a heartbeat cancellation with no
+ * shutdown signal is the orchestrator's pause.
+ */
+export function classifyTurnInterruption(evidence) {
+    const interrupted = evidence.heartbeatCancelled ||
+        evidence.heartbeatWorkerShutdown ||
+        evidence.cancellationSignalAborted;
+    if (!interrupted) {
+        return "none";
+    }
+    if (evidence.heartbeatWorkerShutdown || evidence.shutdownSignalAborted) {
+        return "worker-shutdown";
+    }
+    return evidence.heartbeatCancelled ? "pause" : "none";
+}
+//# sourceMappingURL=worker-shutdown.js.map

package/dist/shared/worker-shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-shutdown.js","sourceRoot":"","sources":["../../src/shared/worker-shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,SAAiB;IAC5D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACpC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,OAAO,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,8BAA8B,CAAC,SAAiB;IAC9D,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC;AAcD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAkC;IAElC,MAAM,WAAW,GACf,QAAQ,CAAC,kBAAkB;QAC3B,QAAQ,CAAC,uBAAuB;QAChC,QAAQ,CAAC,yBAAyB,CAAC;IACrC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,QAAQ,CAAC,uBAAuB,IAAI,QAAQ,CAAC,qBAAqB,EAAE,CAAC;QACvE,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IACD,OAAO,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}