@stigmer/runner 3.12.4 → 3.12.6

package/dist/shared/plan-mode-permissions.js

@@ -2,26 +2,25 @@
  * The Plan-mode filesystem permission rules — the enforcement twin of
  * `plan-mode-prompt.ts` (which carries the instruction half of the contract).
  *
- * Plan mode is contained BY CONSTRUCTION on the native harness: these rules
- * deny every filesystem write everywhere AND scope reads to the session
- * workspace (issue #528 — owner ruling: the workspace is plan mode's read
- * boundary on cloud and desktop runners alike). Without the read boundary,
- * model-provided absolute paths reached anywhere the process account could
- * read — the pod filesystem (including /proc/self/environ) on cloud runners,
- * the user's whole home directory on desktop — while plan mode still carries
- * exfiltration-capable tools (web_fetch, MCP). Rules are first-match-wins
- * with a permissive default (deepagents' decidePathAccess), so order is
- * load-bearing: the workspace read-allow must precede the read-deny.
+ * Plan mode's policy is: reads anywhere in the workspace, writes nowhere.
+ * Only the write half needs a RULE. The read boundary that issue #528 built
+ * out of rules (workspace read-allow + read-deny, glob-escaped real root) is
+ * now STRUCTURAL: every native-harness backend is virtual-rooted
+ * (`virtualMode: true` — see cas-capture-backend.ts, issue #754), so every
+ * path a tool can express resolves inside the workspace root and traversal
+ * is rejected at resolution. A rule cannot widen that, and no workspace-root
+ * glob is needed to narrow it — which also retires the whole
+ * special-characters-in-the-root hazard (`escapeGlobLiteral` and its
+ * end-to-end matcher suite) that the real-path rules carried.
  *
- * The workspace-root pattern is matched as a STRING against the raw tool-call
- * path (micromatch, dot:true), before the backend touches disk. That is
- * exactly why the legitimate out-of-workspace reads keep working: skills,
- * attachments, and the approved plan live in the platform dir but are
- * addressed through the `{workspace}/.stigmer` symlink (see
- * shared/workspace/stigmer-link.ts), so their path strings are in-root even
- * though the bytes are not. The same holds for multi-workspace local entries
- * (`{workspace}/{name}` symlinks). A realpath-based boundary would break
- * both; do not "harden" this into one.
+ * Paths in these rules are VIRTUAL: "/" is the workspace root, matched by
+ * micromatch against the raw tool-call path (dot:true) after the
+ * path-normalization middleware has canonicalized it (relative → "/"-rooted;
+ * see middleware/path-normalization.ts). The legitimate platform-dir reads
+ * (skills, attachments, the approved plan) keep working exactly as before:
+ * they are addressed through the `{workspace}/.stigmer` symlink
+ * (shared/workspace/stigmer-link.ts), an in-root path string in either
+ * dialect.
  *
  * Applied in execute-deep-agent/setup.ts to the parent graph AND threaded
  * into every compiled sub-agent graph: deepagents' parent-permission
@@ -30,50 +29,23 @@
  * (issue #255). Kept as its own side-effect-free module so tests can pin the
  * production rules without dragging in setup.ts's import graph.
  *
- * Rules travel with a companion: every graph that carries them also installs
- * the path-normalization middleware (middleware/path-normalization.ts,
- * issues #429/#528), because deepagents' rule validation refuses
- * workspace-relative paths outright and its `ls`/`glob`/`grep` schema default
- * of "/" would deny the bare first listing. Both are derived from the same
- * expression at each composition site so they cannot drift apart.
- *
  * Invariant: never combine these rules with a shell-capable (sandbox)
  * backend — deepagents rejects that pairing at graph construction (see the
  * cas-capture-backend.ts header). Plan mode guarantees it by construction:
  * it is the mode that clears `shellEnv`, and `shellEnv` is the single switch
  * for shell capability on both the parent and sub-agent backends.
  */
-import { resolve } from "node:path";
-/**
- * Backslash-escape every character micromatch/picomatch treats as glob
- * syntax, so the result matches the input literally. micromatch exports no
- * escape API of its own, and this is correctness, not caution: an unescaped
- * `(` in a desktop project path would make the workspace read-allow rule
- * silently never match — bricking every plan-mode read for that workspace.
- * Semantics are pinned end-to-end through deepagents' own matcher by the
- * special-character workspace suite in plan-mode-path-normalization.test.ts.
- */
-export function escapeGlobLiteral(literal) {
-    return literal.replace(/[\\*?()[\]{}!+@]/g, "\\$&");
-}
 /**
- * Build the plan-mode rule set for a graph whose filesystem backend is
- * rooted at `workspaceRootDir`. The three rules read as the policy:
- * reads allowed in the workspace, reads denied everywhere else, writes
- * denied everywhere.
+ * Build the plan-mode rule set. One rule IS the policy: writes denied
+ * everywhere ("/**" is every virtual path; deepagents evaluates
+ * first-match-wins with a permissive default, so reads stay allowed —
+ * workspace-confined structurally, not by rule).
  *
- * `{root}/**` matches the root itself as well as its subtree (verified
- * against the installed micromatch), so one allow pattern suffices. The
- * root is `path.resolve`d first because enforcement canonicalizes incoming
- * paths (collapsed slashes, no trailing separator) before matching — a
- * trailing slash in the pattern would silently match nothing.
+ * Deliberately parameterless: the pre-#754 signature took the workspace root
+ * to build a real-path read fence; resurrecting a root-derived rule would
+ * silently mismatch the virtual dialect the enforcement now sees.
  */
-export function buildPlanModePermissions(workspaceRootDir) {
-    const canonicalRoot = resolve(workspaceRootDir);
-    return [
-        { operations: ["read"], paths: [`${escapeGlobLiteral(canonicalRoot)}/**`] },
-        { operations: ["read"], paths: ["/**"], mode: "deny" },
-        { operations: ["write"], paths: ["/**"], mode: "deny" },
-    ];
+export function buildPlanModePermissions() {
+    return [{ operations: ["write"], paths: ["/**"], mode: "deny" }];
 }
 //# sourceMappingURL=plan-mode-permissions.js.map

package/dist/shared/plan-mode-permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan-mode-permissions.js","sourceRoot":"","sources":["../../src/shared/plan-mode-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,gBAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAChD,OAAO;QACL,EAAE,UAAU,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,iBAAiB,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE;QAC3E,EAAE,UAAU,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE;QACtD,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE;KACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"plan-mode-permissions.js","sourceRoot":"","sources":["../../src/shared/plan-mode-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC"}

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

@@ -0,0 +1,89 @@
+/**
+ * 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 type { StigmerClient } from "../client/stigmer-client.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+/** Subdirectory of the platform dir where skill mounts live. */
+export declare 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 declare const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+export interface MountMarker {
+    /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
+    versionHash: string;
+    /**
+     * Whether the artifact's files are part of the mount. `false` when the
+     * skill has no artifact OR when the download failed and the mount fell
+     * back to SKILL.md only — the latter makes the next execution retry the
+     * download rather than cache the degraded mount.
+     */
+    artifactMounted: boolean;
+}
+/**
+ * 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 declare function mountIsFresh(skillDir: string, versionHash: string, wantsArtifact: boolean): Promise<boolean>;
+/**
+ * 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 declare function downloadArtifact(client: StigmerClient, artifactStorageKey: string): Promise<Uint8Array | 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 declare function writeSkillMount(skill: Skill, skillDir: string, artifactBytes: Uint8Array | undefined): Promise<void>;

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,gEAAgE;AAChE,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAcvD;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,WAAmB,EACnB,aAAsB;IAEtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,OAAO,MAAM,CAAC,WAAW,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,eAAe,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC;IACnG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,kBAA0B;IAE1B,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,kBAAkB,CAAC,CAAC;IACxE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,aAAa,EAAE,CAAC;YACnE,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/E,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,MAAM,SAAS,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,SAAS,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CACb,iCAAiC,KAAK,CAAC,MAAM,oBAAoB,MAAM,CAAC,SAAS,EAAE,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAY,EACZ,QAAgB,EAChB,aAAqC;IAErC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE3C,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,IAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAE1E,MAAM,eAAe,GAAG,aAAa,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IAChF,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,CAAC,UAAU,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAC;QACzG,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,QAAQ,KAAK,kBAAkB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,kBAAkB,GAAG,GAAG,CAAC,EAAE,CAAC;gBACtF,MAAM,IAAI,KAAK,CACb,sDAAsD,KAAK,CAAC,IAAI,GAAG,CACpE,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE;gBACvC,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK;aACjE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,IAAI,EAAE,CAAC;IACpD,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACvB,MAAM,MAAM,GAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC;QAC7D,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

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>>;