@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/install-profiles.cjs

@@ -13,13 +13,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+// #2874 (ADR-58 cleanup phase): route the staging functions' fs calls
+// through the installRuntimeArtifacts call tree's injectable seam — see
+// install-fs-adapter.cts's module doc. Resolves to real `node:fs` unless the
+// top-level installRuntimeArtifacts call injected a `deps.fs`. Only the
+// staging functions reachable FROM that call tree are routed
+// (stageSkillsForProfile / stageAgentsForProfile /
+// stageAgentsForRuntimeWithConverter / stageSkillsForRuntimeAsSkills /
+// stageCommandsForRuntimeFlat / buildNamespaceBundleMap) — the profile-marker
+// and manifest-loading helpers below are not on that call tree and keep
+// using real `fs` directly.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installFsAdapter = require("./install-fs-adapter.cjs");
+const { installFs, mkInstallTempDir } = installFsAdapter;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // #2322: reuse the existing pure path-containment seam (ADR-1239 Phase C-2)
 // instead of hand-rolling a new traversal check for capability skill stems.
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
-const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, } = conversionModule;
+const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, deriveAgentName: _deriveAgentName, applyAgentFrontmatterExtensions: _applyAgentFrontmatterExtensions, } = conversionModule;
 // #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
 // stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
 // `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
@@ -124,9 +137,79 @@ function parseCallsAgents(content) {
  * Also derives calls_agents for each skill by scanning the body text for
  * `gsd-*` agent name references. Agent stems are stored under the special
  * key `_calls_agents_<stem>` so they don't conflict with skill stems.
+ *
+ * #3798: command bodies are thin delegators — the actual `subagent_type=`
+ * spawns live in the workflow files each command references
+ * (`@…/workflows/<name>.md`). The agent derivation therefore ALSO reads every
+ * workflow file the command references (plus the workflow's steps/ fragments
+ * when it is split per the progressive-disclosure pattern) and unions their
+ * `gsd-*` tokens into the same `_calls_agents_<stem>` set. Without this,
+ * tiered profiles omitted agents their own installed skills spawn
+ * (gsd-verifier at execute-phase's verify_phase_goal was the filed repro).
+ * Over-inclusion fails safe: a tiered profile installing one extra agent
+ * costs bytes, never a broken spawn.
  */
 const DEFAULT_COMMANDS_DIR = node_path_1.default.resolve(__dirname, '..', '..', '..', 'commands', 'gsd');
-function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
+const DEFAULT_WORKFLOWS_DIR = node_path_1.default.resolve(__dirname, '..', '..', 'workflows');
+/**
+ * Collect the `gsd-*` agent tokens from every workflow file a command body
+ * references. References are the `workflows/<name>.md` path suffixes the
+ * delegating commands embed (`@…/gsd-core/workflows/<name>.md`). A
+ * split workflow (workflows/<name>/steps/*.md) contributes its fragments as
+ * well, because the parent dispatches into them and the spawns live there.
+ */
+function workflowAgentRefs(content, workflowsDir) {
+    const refs = content.match(/workflows\/([a-z0-9][a-z0-9-]*)\.md/g) || [];
+    const names = [...new Set(refs.map((r) => r.slice('workflows/'.length)))];
+    const tokens = new Set();
+    for (const name of names) {
+        const direct = node_path_1.default.join(workflowsDir, name);
+        let body = null;
+        try {
+            body = node_fs_1.default.readFileSync(direct, 'utf8');
+        }
+        catch {
+            body = null;
+        }
+        if (body === null)
+            continue;
+        for (const tok of parseCallsAgents(body))
+            tokens.add(tok);
+        // Split workflow: union EVERY fragment under the workflow's directory
+        // (steps/, modes/, templates/…) — the parent dispatches into these per
+        // the progressive-disclosure pattern, and spawns live in all of them
+        // (#3798 review: modes/ carried gsd-advisor-researcher's spawn while the
+        // parent only named it incidentally in prose).
+        const fragDir = node_path_1.default.join(workflowsDir, name.slice(0, -3));
+        const walk = (dir) => {
+            let frags;
+            try {
+                frags = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const frag of frags) {
+                const full = node_path_1.default.join(dir, frag.name);
+                if (frag.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!frag.isFile() || !frag.name.endsWith('.md'))
+                    continue;
+                try {
+                    const fragBody = node_fs_1.default.readFileSync(full, 'utf8');
+                    for (const tok of parseCallsAgents(fragBody))
+                        tokens.add(tok);
+                }
+                catch { /* unreadable fragment — skip */ }
+            }
+        };
+        walk(fragDir);
+    }
+    return [...tokens];
+}
+function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR, workflowsDir = DEFAULT_WORKFLOWS_DIR) {
     const manifest = new Map();
     if (!node_fs_1.default.existsSync(commandsDir))
         return manifest;
@@ -140,9 +223,12 @@ function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
         try {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(commandsDir, entry.name), 'utf8');
             manifest.set(stem, parseRequires(content));
-            // Derive agent references from body text
-            const agentRefs = parseCallsAgents(content);
-            manifest.set(`_calls_agents_${stem}`, agentRefs);
+            // Derive agent references from body text + the workflows it delegates to
+            const agentRefs = [
+                ...parseCallsAgents(content),
+                ...workflowAgentRefs(content, workflowsDir),
+            ];
+            manifest.set(`_calls_agents_${stem}`, [...new Set(agentRefs)]);
         }
         catch {
             manifest.set(stem, []);
@@ -264,10 +350,41 @@ function resolveProfile({ modes, manifest, _profilesOverride, registry } = {}) {
 // site to track its own cleanup handle.
 const STAGED_DIRS = new Set();
 let exitHandlerRegistered = false;
+// #2874 leak-fix: `cleanupStagedSkills` runs at process exit — AFTER
+// `withInstallFs` has already restored `current` back to the real adapter
+// (install-fs-adapter.cts's module doc, "SYNCHRONOUS-ONLY / RE-ENTRANCY
+// ASSUMPTION" — extended there to reference this map). A dir staged during a
+// fake-adapter call must be cleaned up with THAT SAME fake adapter, not with
+// whatever is ambiently active later, or an exit handler would perform real
+// filesystem IO on a path that only ever existed in the fake's in-memory
+// store. Capturing the adapter OBJECT `installFs()` returns at registration
+// time (not the ambient `current` variable, which changes) means cleanup
+// always replays the exact adapter that created the path. Dirs added to
+// STAGED_DIRS without going through `registerStagedDir` (the deprecated
+// `stageSkillsForMode`, which creates its stage dir via raw `fs.mkdtempSync`
+// and was never on the injectable seam) have no entry here and fall back to
+// real `fs.rmSync` below — the same real fs it always used to create them.
+const STAGED_DIR_ADAPTERS = new Map();
+/**
+ * Register a dir just staged through the injectable seam (`installFs()`) for
+ * exit-time cleanup, capturing the adapter that staged it alongside the path.
+ * See `STAGED_DIR_ADAPTERS`'s comment for why the capture matters.
+ */
+function registerStagedDir(dir) {
+    STAGED_DIRS.add(dir);
+    STAGED_DIR_ADAPTERS.set(dir, installFs());
+    ensureExitCleanup();
+}
 function cleanupStagedSkills() {
     for (const dir of STAGED_DIRS) {
+        const adapter = STAGED_DIR_ADAPTERS.get(dir);
         try {
-            node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+            if (adapter) {
+                adapter.rmSync(dir, { recursive: true, force: true });
+            }
+            else {
+                node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+            }
         }
         catch {
             // Best-effort: missing dir or permission error shouldn't crash a
@@ -275,6 +392,7 @@ function cleanupStagedSkills() {
         }
     }
     STAGED_DIRS.clear();
+    STAGED_DIR_ADAPTERS.clear();
 }
 // Signals we register a cleanup handler for in addition to the natural
 // 'exit' event. `process.on('exit')` does NOT fire on these — an installer
@@ -303,11 +421,11 @@ function ensureExitCleanup() {
 function stageSkillsForProfile(srcDir, resolvedProfile) {
     if (resolvedProfile.skills === '*')
         return srcDir;
-    if (!node_fs_1.default.existsSync(srcDir))
+    if (!installFs().existsSync(srcDir))
         return srcDir;
-    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-skills-'));
+    const stageDir = mkInstallTempDir('gsd-profile-skills-');
     try {
-        const entries = node_fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+        const entries = installFs().readdirSync(srcDir, { withFileTypes: true });
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -316,18 +434,17 @@ function stageSkillsForProfile(srcDir, resolvedProfile) {
             const stem = entry.name.slice(0, -3);
             if (!(resolvedProfile.skills).has(stem))
                 continue;
-            node_fs_1.default.copyFileSync(node_path_1.default.join(srcDir, entry.name), node_path_1.default.join(stageDir, entry.name));
+            installFs().copyFileSync(node_path_1.default.join(srcDir, entry.name), node_path_1.default.join(stageDir, entry.name));
         }
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+            installFs().rmSync(stageDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
-    STAGED_DIRS.add(stageDir);
-    ensureExitCleanup();
+    registerStagedDir(stageDir);
     return stageDir;
 }
 /**
@@ -353,12 +470,12 @@ function stageSkillsForProfile(srcDir, resolvedProfile) {
 function stageAgentsForProfile(srcAgentsDir, resolvedProfile) {
     if (resolvedProfile.skills === '*')
         return srcAgentsDir;
-    if (!node_fs_1.default.existsSync(srcAgentsDir))
+    if (!installFs().existsSync(srcAgentsDir))
         return srcAgentsDir;
-    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-agents-'));
+    const stageDir = mkInstallTempDir('gsd-profile-agents-');
     try {
         if (resolvedProfile.agents instanceof Set && resolvedProfile.agents.size > 0) {
-            const entries = node_fs_1.default.readdirSync(srcAgentsDir, { withFileTypes: true });
+            const entries = installFs().readdirSync(srcAgentsDir, { withFileTypes: true });
             for (const entry of entries) {
                 if (!entry.isFile())
                     continue;
@@ -368,20 +485,19 @@ function stageAgentsForProfile(srcAgentsDir, resolvedProfile) {
                 const stem = entry.name.slice(0, -3);
                 if (!resolvedProfile.agents.has(stem))
                     continue;
-                node_fs_1.default.copyFileSync(node_path_1.default.join(srcAgentsDir, entry.name), node_path_1.default.join(stageDir, entry.name));
+                installFs().copyFileSync(node_path_1.default.join(srcAgentsDir, entry.name), node_path_1.default.join(stageDir, entry.name));
             }
         }
         // If agents is empty Set, we produce an empty stageDir (no agents for this profile)
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+            installFs().rmSync(stageDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
-    STAGED_DIRS.add(stageDir);
-    ensureExitCleanup();
+    registerStagedDir(stageDir);
     return stageDir;
 }
 /**
@@ -395,10 +511,10 @@ function buildNamespaceBundleMap(srcCommandsDir) {
     const routerStems = new Set();
     const routerChildren = new Map();
     const childToRouters = new Map();
-    if (!node_fs_1.default.existsSync(srcCommandsDir)) {
+    if (!installFs().existsSync(srcCommandsDir)) {
         return { routerStems, routerChildren, childToRouters };
     }
-    for (const entry of node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true })) {
+    for (const entry of installFs().readdirSync(srcCommandsDir, { withFileTypes: true })) {
         if (!entry.isFile() || !entry.name.endsWith('.md'))
             continue;
         if (!entry.name.startsWith('ns-'))
@@ -406,7 +522,7 @@ function buildNamespaceBundleMap(srcCommandsDir) {
         const stem = entry.name.slice(0, -3);
         let children = [];
         try {
-            children = parseRequires(node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8'));
+            children = parseRequires(installFs().readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8'));
         }
         catch {
             children = [];
@@ -637,7 +753,7 @@ function readInstalledCapabilitySkill(stem, registry) {
  *   When absent, NOTHING third-party is staged (fail closed).
  */
 function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix, nested = false, registry) {
-    if (!node_fs_1.default.existsSync(srcCommandsDir))
+    if (!installFs().existsSync(srcCommandsDir))
         return srcCommandsDir;
     // Nesting applies to the `full` install AND to any surface whose skill set
     // still contains every namespace router (a full/reset surface). It must NOT
@@ -660,9 +776,9 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
     // this call, so the third-party fill-in pass below can enforce "first-party
     // ALWAYS wins on collision" without re-deriving membership.
     const firstPartyStems = new Set();
-    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-skills-'));
+    const stageDir = mkInstallTempDir('gsd-profile-runtime-skills-');
     try {
-        const entries = node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true });
+        const entries = installFs().readdirSync(srcCommandsDir, { withFileTypes: true });
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -672,15 +788,15 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
             if (resolvedProfile.skills !== '*' && !(resolvedProfile.skills).has(stem))
                 continue;
             firstPartyStems.add(stem);
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
+            const content = installFs().readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
             const skillName = `${prefix}${stem}`;
             const converted = converter(content, skillName);
             if (doNest && bundles.routerStems.has(stem)) {
                 // Router skill: rewrite its routing table to the nested Read pattern and
                 // emit it as the single top-level bundle entry.
                 const destDir = node_path_1.default.join(stageDir, skillName);
-                node_fs_1.default.mkdirSync(destDir, { recursive: true });
-                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), transformRouterBodyToNested(converted));
+                installFs().mkdirSync(destDir, { recursive: true });
+                installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), transformRouterBodyToNested(converted));
                 continue;
             }
             if (doNest && bundles.childToRouters.has(stem)) {
@@ -689,16 +805,16 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
                 // top-level eager listing while staying readable by file path (#69).
                 for (const routerStem of bundles.childToRouters.get(stem)) {
                     const destDir = node_path_1.default.join(stageDir, `${prefix}${routerStem}`, 'skills', stem);
-                    node_fs_1.default.mkdirSync(destDir, { recursive: true });
-                    node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
+                    installFs().mkdirSync(destDir, { recursive: true });
+                    installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
                 }
                 continue;
             }
             // Flat top-level skill (default behaviour; also the unrouted fallback when
             // nesting is active).
             const destDir = node_path_1.default.join(stageDir, skillName);
-            node_fs_1.default.mkdirSync(destDir, { recursive: true });
-            node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
+            installFs().mkdirSync(destDir, { recursive: true });
+            installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
         }
         // #2322: materialize installed THIRD-PARTY capability skills, bound to
         // their DECLARING capability via the registry's capabilityClusters view
@@ -740,25 +856,24 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
                 if (!(0, external_descriptor_trust_cjs_1.isPathConfined)(skillName, stageDir))
                     continue; // defense-in-depth
                 const destDir = node_path_1.default.join(stageDir, skillName);
-                node_fs_1.default.mkdirSync(destDir, { recursive: true });
-                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), found.content);
+                installFs().mkdirSync(destDir, { recursive: true });
+                installFs().writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), found.content);
                 // #2322 HIGH-3: persist the capability-owned marker so a later prune
                 // pass (surface.cts pruneSkillDirs) can identify — and remove — this
                 // directory even once the owning capability is uninstalled/unsurfaced
                 // and no longer appears in any registry view.
-                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, CAPABILITY_SKILL_MARKER), found.capId + '\n', 'utf8');
+                installFs().writeFileSync(node_path_1.default.join(destDir, CAPABILITY_SKILL_MARKER), found.capId + '\n', 'utf8');
             }
         }
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+            installFs().rmSync(stageDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
-    STAGED_DIRS.add(stageDir);
-    ensureExitCleanup();
+    registerStagedDir(stageDir);
     return stageDir;
 }
 /**
@@ -782,26 +897,57 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  *   1. applyAgentPathRewrites   (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
  *   2. processAttribution       (Co-Authored-By policy)
  *   3. converter                (runtime-specific frontmatter/body transform)
- *   4. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
+ *   4. applyAgentFrontmatterExtensions (#2875 Part 2: effort/disallowedTools,
+ *      gated by hostBehaviors.agentFrontmatterExtensions — no-op for a runtime
+ *      that declares nothing, e.g. every non-Claude runtime today)
+ *   5. normalizeAgentBodyForRuntime (colon→hyphen refs; no-op for trivial group)
  * When `agentCtx` is absent, only the converter is applied (backward-compat for
  * the feat-1173 synthetic-descriptor tests and the copilot/antigravity paths
  * that handle cross-cutting inside their converters).
  *
  * @param srcAgentsDir    source agents directory (e.g. agents/)
  * @param resolvedProfile profile filter from resolveProfile()
- * @param converter       (content: string, isGlobal?: boolean) → string per-file
- *                        converter; scope-aware converters (copilot/antigravity)
- *                        read isGlobal, single-arg converters ignore it (#1173)
+ * @param converter       (content: string, isGlobal?: boolean, meta?: {agentName: string}) → string
+ *                        per-file converter; scope-aware converters (copilot/antigravity)
+ *                        read isGlobal, single-arg converters ignore both extra args (#1173).
+ *                        `meta.agentName` (#2875 Part 2) is passed ONLY when `agentCtx` is
+ *                        present, letting a converter close over per-agent config
+ *                        (e.g. kilo/opencode model-override resolution in
+ *                        runtime-artifact-layout.cts's convertedAgentsKind) without widening
+ *                        every OTHER converter's contract — converters that don't declare a
+ *                        3rd parameter simply never read it.
  * @param isGlobal        install scope passed through to the converter
  * @param agentCtx        optional cross-cutting context (ADR-1235 §1); when absent,
  *                        only the converter is applied (backward compat)
  */
 function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx) {
-    if (!node_fs_1.default.existsSync(srcAgentsDir))
+    if (!installFs().existsSync(srcAgentsDir))
         return srcAgentsDir;
-    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-agents-'));
+    const stageDir = mkInstallTempDir('gsd-profile-runtime-agents-');
+    let entries;
+    try {
+        // #2284/#2875: readdirSync-ing the shipped agents/ source is isolated in
+        // its own try/catch so an unreadable source directory (permissions, a
+        // corrupted install, or — as the #2284 test suite demonstrates — the
+        // fail-closed injection harness) produces the SAME "refusing to install"
+        // fail-closed wording every other agents-dir-unreadable path in this
+        // codebase uses (bin/install.js's `_resolveAvailableGsdRoles` /
+        // `_assertRoleResolvable`), instead of an unrelated raw fs error message
+        // escaping uncaught. Hermes's role-dispatch validation depends on the
+        // SAME shipped agents/ directory being readable; before this runtime also
+        // declared an `agents` kind, this function was never reached on a Hermes
+        // install, so an unreadable source here silently surfaced as a raw error
+        // rather than the deliberate fail-closed contract #2284 established.
+        entries = installFs().readdirSync(srcAgentsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        try {
+            installFs().rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw new Error(`stageAgentsForRuntimeWithConverter: could not resolve the shipped agents/ directory "${srcAgentsDir}" to stage — refusing to install (fail-closed, #2284/#2875): ${err.message}`);
+    }
     try {
-        const entries = node_fs_1.default.readdirSync(srcAgentsDir, { withFileTypes: true });
         // Resolve cmdNames once per staging call (not per file) for performance.
         const cmdNames = agentCtx ? _readGsdCommandNames() : [];
         for (const entry of entries) {
@@ -817,39 +963,44 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                 }
             }
             const agentSourcePath = node_path_1.default.join(srcAgentsDir, entry.name);
-            let content = node_fs_1.default.readFileSync(agentSourcePath, 'utf8');
+            let content = installFs().readFileSync(agentSourcePath, 'utf8');
             // #2995: strip gsd:section markers FIRST — before path rewrites, attribution,
             // and the per-runtime converter. Byte-identical (no-op) for an unmarked agent;
             // throws loudly naming the file for a malformed marker, never emitting a
             // half-composed agent.
             content = _composeWorkflow(content, { sourcePath: agentSourcePath });
             if (agentCtx) {
+                // #2875 Part 2 / row I3: derived exactly as the inline loop does —
+                // single-sourced via deriveAgentName (runtime-artifact-conversion.cts).
+                const agentName = _deriveAgentName(entry.name);
                 // ADR-1235 §1: pre-converter cross-cutting (matches inline loop order exactly)
                 // Step 1: path rewrites (4 base ~/.claude/ regexes; skipped for copilot/antigravity)
                 content = _applyAgentPathRewrites(content, agentCtx.runtime, agentCtx.pathPrefix);
                 // Step 2: attribution
                 content = _processAttribution(content, agentCtx.attribution);
                 // Step 3: converter (runtime-specific frontmatter/body transform)
-                content = converter(content, isGlobal);
-                // Step 4: normalize colon→hyphen refs (no-op for trivial group)
+                content = converter(content, isGlobal, { agentName });
+                // Step 4: frontmatter extensions (effort/disallowedTools; no-op unless
+                // the runtime declares hostBehaviors.agentFrontmatterExtensions)
+                content = _applyAgentFrontmatterExtensions(content, { runtime: agentCtx.runtime, agentName, targetDir: agentCtx.targetDir });
+                // Step 5: normalize colon→hyphen refs (no-op for trivial group)
                 content = _normalizeAgentBodyForRuntime(content, agentCtx.runtime, cmdNames);
             }
             else {
                 // Backward-compat: only apply the converter (no cross-cutting)
                 content = converter(content, isGlobal);
             }
-            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, entry.name), content, 'utf8');
+            installFs().writeFileSync(node_path_1.default.join(stageDir, entry.name), content, 'utf8');
         }
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+            installFs().rmSync(stageDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
-    STAGED_DIRS.add(stageDir);
-    ensureExitCleanup();
+    registerStagedDir(stageDir);
     return stageDir;
 }
 /**
@@ -876,11 +1027,11 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
  * @param prefix          command name prefix (for converter arg), e.g. 'gsd-'
  */
 function stageCommandsForRuntimeFlat(srcCommandsDir, resolvedProfile, converter, prefix) {
-    if (!node_fs_1.default.existsSync(srcCommandsDir))
+    if (!installFs().existsSync(srcCommandsDir))
         return srcCommandsDir;
-    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-commands-'));
+    const stageDir = mkInstallTempDir('gsd-profile-runtime-commands-');
     try {
-        const entries = node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true });
+        const entries = installFs().readdirSync(srcCommandsDir, { withFileTypes: true });
         for (const entry of entries) {
             if (!entry.isFile())
                 continue;
@@ -889,24 +1040,23 @@ function stageCommandsForRuntimeFlat(srcCommandsDir, resolvedProfile, converter,
             const stem = entry.name.slice(0, -3);
             if (resolvedProfile.skills !== '*' && !(resolvedProfile.skills).has(stem))
                 continue;
-            const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
+            const content = installFs().readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
             // Pass the full command name (with prefix) to the converter so it can
             // reference the installed command name in the body (e.g. for descriptions).
             // The staged file itself is named without the prefix; _copyStaged adds it.
             const commandName = `${prefix}${stem}`;
             const converted = converter(content, commandName);
-            node_fs_1.default.writeFileSync(node_path_1.default.join(stageDir, `${stem}.md`), converted);
+            installFs().writeFileSync(node_path_1.default.join(stageDir, `${stem}.md`), converted);
         }
     }
     catch (err) {
         try {
-            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+            installFs().rmSync(stageDir, { recursive: true, force: true });
         }
         catch { /* best-effort */ }
         throw err;
     }
-    STAGED_DIRS.add(stageDir);
-    ensureExitCleanup();
+    registerStagedDir(stageDir);
     return stageDir;
 }
 // ---------------------------------------------------------------------------
@@ -1079,6 +1229,7 @@ module.exports = {
     // Shared internals
     parseRequires,
     parseCallsAgents,
+    workflowAgentRefs,
     cleanupStagedSkills,
     // #2322: capability-skill security seams — exported for direct unit-testing
     // and for surface.cts's prune pass (CAPABILITY_SKILL_MARKER parity).