@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/surface.cjs

@@ -13,7 +13,7 @@
  *   readSurface(runtimeConfigDir)
  *   writeSurface(runtimeConfigDir, surfaceState)
  *   resolveSurface(runtimeConfigDir, manifest, clusterMap?, registry?)
- *   applySurface(runtimeConfigDir, layout, manifest, clusterMap?, registry?)
+ *   applySurface(runtimeConfigDir, layout, manifest, clusterMap?, registry?, opts?, deps?)
  *   listSurface(runtimeConfigDir, manifest, clusterMap?, registry?)
  *   pruneSkillDirs(skillsDir, retainedNames, prefix, manifest)
  *
@@ -37,12 +37,19 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const testHomeGuard = require("./real-home-guard.cjs");
 const { readActiveProfile, resolveProfile, loadSkillsManifest, 
 // #2322 HIGH-3: shared marker name — single source of truth with the writer
 // (install-profiles.cts stageSkillsForRuntimeAsSkills) so the prune reader
 // below can never drift from what the stage-time writer actually wrote.
 CAPABILITY_SKILL_MARKER, } = installProfiles;
 const clusters_cjs_1 = require("./clusters.cjs");
+// #2870: `isGlobalScope` centralizes the `scope === 'global'` boolean
+// projection `applySurface` needs at `_computePathPrefix`'s `isGlobal:
+// boolean` boundary (see its doc comment in install-scope.cts for why the
+// projection is centralized rather than eliminated).
+const install_scope_cjs_1 = require("./install-scope.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const { findInstallSourceRoot } = runtimeArtifactLayout;
@@ -298,10 +305,16 @@ function resolveSurface(runtimeConfigDir, manifest, clusterMap, registry) {
  * Re-stage the active surface using the resolved layout.
  * Iterates layout.kinds and syncs each artifact kind to its destination.
  */
-function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry, opts) {
+function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry, opts, deps = {}) {
     if (node_path_1.default.resolve(runtimeConfigDir) !== node_path_1.default.resolve(layout.configDir)) {
         throw new TypeError('applySurface runtimeConfigDir must match layout.configDir');
     }
+    // #3712: the dest selection below prefers `kind.home` over layout.configDir and
+    // then hands it to the destructive _syncGsdDir, so surface apply is a third
+    // escape route into the developer's real home alongside install/uninstall.
+    testHomeGuard.assertTestHomeSandboxed('applySurface', layout.runtime, layout.kinds, {
+        os: deps.os, env: deps.env,
+    });
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
     // Profile toggles must converge retired surfaces too. Once a kind disappears
@@ -316,12 +329,23 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     const _homedirFn = opts?.homedir ?? (() => node_os_1.default.homedir());
     const _resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(layout.configDir));
     const _homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(_homedirFn());
-    const _isGlobal = (layout.scope ?? 'global') === 'global';
+    // #2870: same judgment as createRuntimeArtifactInstallPlan's identical
+    // line — `layout.scope` is already the resolved scope value on the
+    // `Layout` this function received. `layout.scope` is optional, so the
+    // pre-existing `?? 'global'` default is kept ahead of the call: it must
+    // run BEFORE `isGlobalScope`, because `isGlobalScope(undefined)` throws
+    // (unlike the old inline `undefined === 'global'`, which silently
+    // evaluated to `false`) — the default is what makes an undefined scope
+    // resolve to `'global'` here, exactly as it did before. `isGlobalScope`
+    // then projects the defaulted value to the boolean `_computePathPrefix`'s
+    // existing `isGlobal: boolean` API requires.
+    const _isGlobal = (0, install_scope_cjs_1.isGlobalScope)(layout.scope ?? 'global');
     const _isOpencode = layout.runtime === 'opencode';
     const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';
     const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir });
     const _attribution = opts?.resolveAttribution ? opts.resolveAttribution(layout.runtime) : undefined;
-    const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution };
+    // #2875 Part 2 (row I1): layout.configDir is this call's install root.
+    const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution, targetDir: layout.configDir };
     const tempDirsToClean = [];
     // #1575: When the surface has no state modifications AND the base profile is
     // 'full', pass the '*' sentinel for agents staging so ALL agents are staged —
@@ -557,13 +581,11 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
         // from install and orphaned the installed gsd-*.md files, and the unscoped
         // prune deleted user-owned command files.
         //
-        // NOTE: the destName rule below intentionally mirrors bin/install.js
-        // `_copyStaged` (the `namespacedByDir` decision). Keep them in sync.
-        const destLast = (typeof kind === 'object' && kind !== null && kind.destSubpath)
-            ? node_path_1.default.basename(kind.destSubpath)
-            : '';
-        const prefixStem = kindPrefix ? kindPrefix.replace(/-$/, '') : '';
-        const namespacedByDir = kindName === 'commands' && destLast === prefixStem;
+        // Single source of truth: runtimeArtifactLayout.isNamespacedByDir (#2871
+        // Phase 2 review finding — this rule previously drifted independently
+        // across install-engine.cts / surface.cts / runtime-artifact-layout.cts).
+        const kindDestSubpath = (typeof kind === 'object' && kind !== null && kind.destSubpath) ? kind.destSubpath : '';
+        const namespacedByDir = runtimeArtifactLayout.isNamespacedByDir(kindName, kindDestSubpath, kindPrefix);
         const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
         const stagedDestNames = new Set();
         for (const file of stagedFiles) {

package/gsd-core/bin/lib/task-command-router.cjs

@@ -14,6 +14,14 @@ const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error, ERROR_REASON } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planDocumentMod = require("./plan-document.cjs");
+const { parsePlanDocument } = planDocumentMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityLoaderMod = require("./capability-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const taskContentResolutionMod = require("./task-content-resolution.cjs");
+const { resolveTaskContent, ResolverAmbiguousError, ResolverFailedError, ResolverTimeoutError, ResolverMalformedOutputError, } = taskContentResolutionMod;
 // ─── Implementation ───────────────────────────────────────────────────────────
 function isBehaviorAddingTaskContent(content) {
     const tddTrue = /\btdd\s*=\s*["']true["']/i.test(content);
@@ -52,10 +60,111 @@ function isBehaviorAddingTaskContent(content) {
         reason: isBehaviorAdding ? null : `Not behavior-adding: ${missing.join('; ')}`,
     };
 }
+/**
+ * Default (production) capability loader for `resolve-content`: the merged
+ * first-party + validated-installed-overlay registry (ADR-1244 D2), the
+ * established runtime read path for "installed capabilities including
+ * third-party" — as opposed to `capability-loader.cts`'s heavier build-time
+ * validation entry points or the static `capability-registry.cjs` alone
+ * (first-party only, would miss a third-party capability's
+ * `taskContentResolver` declaration entirely).
+ */
+function defaultLoadCapabilities(cwd) {
+    const registry = capabilityLoaderMod.loadRegistry({ includeInstalled: true, cwd });
+    return Object.values(registry.capabilities ?? {});
+}
+function parseResolveContentArgs(args) {
+    let plan = null;
+    let taskId = null;
+    for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--plan') {
+            plan = args[i + 1] ?? null;
+            i++;
+        }
+        else if (args[i] === '--task-id') {
+            taskId = args[i + 1] ?? null;
+            i++;
+        }
+    }
+    return { plan, taskId };
+}
+/**
+ * `task resolve-content --plan <PLAN.md path> --task-id <tracker-id value> --raw`
+ * (ADR-3646 Decision 2). Resolves one task's content from the external
+ * tracker its `tracker-id` attribute names, via `task-content-resolution.cts`.
+ *
+ * HARD-HALT CONTRACT: a thrown `ResolverAmbiguousError` / `ResolverFailedError`
+ * / `ResolverTimeoutError` / `ResolverMalformedOutputError` from
+ * `resolveTaskContent` is turned into this CLI's own non-zero exit via
+ * `error()` — never swallowed into a `{resolved: false}` JSON answer. Any
+ * other thrown error is not one of the four documented resolver-error
+ * classes and is allowed to propagate uncaught.
+ */
+function routeResolveContent({ args, cwd, raw }, deps = {}) {
+    const usage = 'Usage: task resolve-content --plan <path> --task-id <tracker-id> --raw';
+    const { plan, taskId } = parseResolveContentArgs(args);
+    if (!plan || !taskId) {
+        error(usage, ERROR_REASON.USAGE);
+        return;
+    }
+    const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
+    const resolvedPlanPath = node_path_1.default.resolve(projectRoot, plan);
+    const rel = node_path_1.default.relative(projectRoot, resolvedPlanPath);
+    if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+        error(`Plan file is outside project scope: ${plan}`, ERROR_REASON.USAGE);
+        return;
+    }
+    if (!node_fs_1.default.existsSync(resolvedPlanPath)) {
+        error(`Plan file not found: ${plan}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const planContent = node_fs_1.default.readFileSync(resolvedPlanPath, 'utf-8');
+    const parsedPlan = parsePlanDocument(planContent, resolvedPlanPath);
+    const task = (parsedPlan.tasks ?? []).find((t) => t.trackerId === taskId);
+    if (!task) {
+        error(`No task with tracker-id '${taskId}' found in plan: ${plan}`, ERROR_REASON.USAGE);
+        return;
+    }
+    const loadCapabilities = deps.loadCapabilities ?? defaultLoadCapabilities;
+    const capabilities = loadCapabilities(projectRoot);
+    const resolveFn = deps.resolveTaskContentFn ?? resolveTaskContent;
+    let result;
+    try {
+        result = resolveFn({ trackerId: task.trackerId, capabilities });
+    }
+    catch (err) {
+        if (err instanceof ResolverAmbiguousError ||
+            err instanceof ResolverFailedError ||
+            err instanceof ResolverTimeoutError ||
+            err instanceof ResolverMalformedOutputError) {
+            error(err.message, ERROR_REASON.UNKNOWN);
+            return;
+        }
+        throw err;
+    }
+    switch (result.kind) {
+        case 'not-applicable':
+            output({ resolved: false }, raw, undefined);
+            return;
+        case 'no-resolver':
+            output({ resolved: false, reason: 'no-resolver' }, raw, undefined);
+            return;
+        case 'empty':
+            output({ resolved: false, reason: 'empty' }, raw, undefined);
+            return;
+        case 'resolved':
+            output({ resolved: true, content: result.content }, raw, undefined);
+            return;
+    }
+}
 function routeTaskCommand({ args, cwd, raw }) {
     const subcommand = args[1];
+    if (subcommand === 'resolve-content') {
+        routeResolveContent({ args, cwd, raw });
+        return;
+    }
     if (subcommand !== 'is-behavior-adding') {
-        error('Unknown task subcommand. Available: is-behavior-adding', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        error('Unknown task subcommand. Available: is-behavior-adding, resolve-content', ERROR_REASON.SDK_UNKNOWN_COMMAND);
     }
     let content = null;
     if (args[2] === '--task-content') {
@@ -82,4 +191,5 @@ function routeTaskCommand({ args, cwd, raw }) {
 module.exports = {
     isBehaviorAddingTaskContent,
     routeTaskCommand,
+    routeResolveContent,
 };

package/gsd-core/bin/lib/task-content-resolution.cjs

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * Task Content Resolution Module (ADR-3646 Phase 1, #3970).
+ *
+ * Given a task's `tracker-id` attribute value (parsed verbatim by
+ * `plan-document.cts`, never split there) and the set of installed
+ * capabilities' `taskContentResolver` declarations, resolves the task's
+ * content from the matching external tracker via a bounded subprocess call —
+ * or reports that no resolution applies.
+ *
+ * PURE / IMPURE SPLIT, loosely mirroring `review-lane-invocation.cts`'s
+ * resolve-then-run shape, but deliberately NOT copying its full machinery
+ * (Gall's Law — see `40-design.md`'s "Laws that apply" section): this problem
+ * has no probe/model/effort/prompt-channel axes, just one deterministic
+ * id-lookup. `splitTrackerId`, `findResolver`, and `buildInvocation` are pure
+ * and total (never throw, even on hostile third-party-shaped input — a
+ * capability manifest is third-party-authored, and while `capability-
+ * validator.cjs` validates it at install time, this module re-validates
+ * defensively rather than trusting that boundary). `resolveTaskContent` is
+ * the one impure boundary: it spawns exactly one bounded subprocess, through
+ * an injectable `execFn` so tests never spawn a real process or wait a real
+ * timeout (CLAUDE.md's clock-seam rule).
+ *
+ * HARD-HALT CONTRACT (ADR-3646 Decision 4): an ambiguous resolver match, a
+ * non-zero resolver exit, a timeout, or malformed resolver stdout all THROW.
+ * None of these degrade to a silently-empty or silently-picked result — a
+ * task-content resolution failure must halt the caller (`task-command-
+ * router.cts`'s `resolve-content` subcommand turns each throw into the CLI's
+ * own non-zero exit), never fall back to inline PLAN.md content pretending
+ * nothing happened.
+ *
+ * ADR-457 build-at-publish: source in src/task-content-resolution.cts,
+ * compiled to gsd-core/bin/lib/task-content-resolution.cjs (gitignored).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+// Use non-destructured namespace import so test-time mock.method(childProcess,
+// 'spawnSync') can intercept calls from this seam — destructured imports
+// capture references at load time and become un-mockable (matches the
+// convention documented in shell-command-projection.cts).
+const node_child_process_1 = __importDefault(require("node:child_process"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioMod = require("./io.cjs");
+const { formatDiagnosticToken } = ioMod;
+// ─── Result taxonomy ──────────────────────────────────────────────────────────
+/**
+ * The four non-throwing outcomes of `resolveTaskContent`. Frozen because the
+ * `kind` discriminant is the product — callers (the CLI seam) switch on it
+ * directly rather than string-matching prose.
+ */
+const TASK_CONTENT_RESULT = Object.freeze({
+    NOT_APPLICABLE: 'not-applicable',
+    NO_RESOLVER: 'no-resolver',
+    RESOLVED: 'resolved',
+    EMPTY: 'empty',
+});
+// ─── Throwable error taxonomy ─────────────────────────────────────────────────
+// These four ALWAYS throw — they are configuration/execution defects, never a
+// value `resolveTaskContent` returns. See the module docstring's hard-halt
+// contract.
+/**
+ * Two or more installed capabilities declare a `taskContentResolver` for the
+ * same `trackerPrefix`. Structurally impossible in a correctly-validated
+ * install (`capability-validator.cjs` enforces cross-capability prefix
+ * uniqueness), but `findResolver` must still refuse to silently pick one if a
+ * test harness or a validator bug ever produces this shape.
+ */
+class ResolverAmbiguousError extends Error {
+    prefix;
+    capabilityIds;
+    constructor(prefix, capabilityIds) {
+        super(`tracker prefix '${prefix}' matches ${capabilityIds.length} installed capability resolvers ` +
+            `(${capabilityIds.join(', ')}) — ambiguous resolver registration must never silently pick one`);
+        this.name = 'ResolverAmbiguousError';
+        this.prefix = prefix;
+        this.capabilityIds = capabilityIds;
+    }
+}
+/**
+ * The resolver subprocess exited non-zero (or failed to spawn at all).
+ *
+ * `stderrTail` is UNTRUSTED subprocess-sourced text (the resolver binary is
+ * declared by a capability manifest and invoked with an argv token derived
+ * from a PLAN.md `tracker-id` attribute, which is often LLM/agent-authored —
+ * a hostile or buggy resolver could echo attacker-influenced text back on
+ * its own stderr). `.message` embeds it through `io.cjs`'s
+ * `formatDiagnosticToken()` so every caller of `resolveTaskContent` gets a
+ * `.message` that is already safe to write verbatim to a plain-text
+ * diagnostic — see that function's docstring for why this must happen here,
+ * at the point the untrusted substring is embedded, rather than at each
+ * call site.
+ */
+class ResolverFailedError extends Error {
+    exitCode;
+    stderrTail;
+    constructor(binary, exitCode, stderrTail) {
+        super(`resolver command '${binary}' exited ${exitCode === null ? 'with no exit code (spawn failure)' : exitCode}` +
+            (stderrTail ? `: ${formatDiagnosticToken(stderrTail)}` : ''));
+        this.name = 'ResolverFailedError';
+        this.exitCode = exitCode;
+        this.stderrTail = stderrTail;
+    }
+}
+/** The resolver subprocess exceeded its declared `invoke.timeoutMs` bound. */
+class ResolverTimeoutError extends Error {
+    timeoutMs;
+    constructor(binary, timeoutMs) {
+        super(`resolver command '${binary}' timed out after ${timeoutMs}ms`);
+        this.name = 'ResolverTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * The resolver's stdout was not valid JSON, or was valid JSON that is not a
+ * plain object (a `null`, array, string, number, or boolean top-level value
+ * is rejected — only a plain object can carry the `description`/`verify`/
+ * `acceptance_criteria`/`read_first`/`done` fields this seam reads).
+ */
+class ResolverMalformedOutputError extends Error {
+    stdoutSample;
+    constructor(binary, reason, stdoutSample) {
+        super(`resolver command '${binary}' produced malformed output: ${reason}` +
+            (stdoutSample ? ` (stdout sample: ${formatDiagnosticToken(stdoutSample)})` : ''));
+        this.name = 'ResolverMalformedOutputError';
+        this.stdoutSample = stdoutSample;
+    }
+}
+// ─── Pure functions ────────────────────────────────────────────────────────────
+/**
+ * The SAME kebab-case grammar `capability-validator.cjs`'s `KEBAB_RE`
+ * enforces on `taskContentResolver.trackerPrefix` at install time
+ * (`validateTaskContentResolverFields`). Duplicated as a literal rather than
+ * imported — `.cts` (build-at-publish, ADR-457) and the hand-written
+ * `capability-validator.cjs` are genuinely two different build targets with
+ * no shared-constants module between them today — but `tests/task-content-
+ * resolver-grammar-parity.test.cjs` asserts both regexes agree on a shared
+ * table of inputs, so a future edit to either one that silently diverges from
+ * the other fails a test instead of drifting quietly (CLAUDE.md's Generative
+ * Fix Divergence rule).
+ */
+const TRACKER_PREFIX_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Split a `tracker-id` attribute value into its prefix and id, on the FIRST
+ * `:` only — colons after the first stay in the id verbatim (a tracker whose
+ * native ids contain colons, e.g. `beads:issue:GSD-1` → `{prefix: "beads",
+ * id: "issue:GSD-1"}`).
+ *
+ * PURE. Returns `null` for `null`/empty input, and for a string with no `:`
+ * at all (nothing to split — there is no prefix to match a resolver against).
+ */
+function splitTrackerId(trackerId) {
+    if (typeof trackerId !== 'string' || trackerId.length === 0)
+        return null;
+    const colonIdx = trackerId.indexOf(':');
+    if (colonIdx === -1)
+        return null;
+    const prefix = trackerId.slice(0, colonIdx);
+    const id = trackerId.slice(colonIdx + 1);
+    if (!prefix || !id)
+        return null;
+    return { prefix, id };
+}
+/**
+ * Defensively re-validate a raw `taskContentResolver` declaration's shape.
+ * `capability-validator.cjs` already enforces this at install time, but this
+ * module treats every capability manifest as third-party-authored input and
+ * never trusts a shape it has not itself checked — a malformed declaration is
+ * treated as though it does not exist for matching purposes, never thrown on.
+ */
+function parseResolverDeclaration(capabilityId, raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const body = raw;
+    const trackerPrefix = typeof body.trackerPrefix === 'string' ? body.trackerPrefix.trim() : '';
+    if (!trackerPrefix || !TRACKER_PREFIX_RE.test(trackerPrefix))
+        return null;
+    const inv = body.invoke;
+    if (inv === null || typeof inv !== 'object' || Array.isArray(inv))
+        return null;
+    const invBody = inv;
+    const binary = typeof invBody.binary === 'string' ? invBody.binary.trim() : '';
+    if (!binary)
+        return null;
+    const args = Array.isArray(invBody.args)
+        ? invBody.args.filter((a) => typeof a === 'string')
+        : null;
+    if (args === null || args.length !== invBody.args.length)
+        return null;
+    if (!args.includes('{{id}}'))
+        return null;
+    const timeoutMs = invBody.timeoutMs;
+    if (typeof timeoutMs !== 'number' || !Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        return null;
+    return {
+        capabilityId,
+        trackerPrefix,
+        invoke: { binary, args, timeoutMs },
+    };
+}
+/**
+ * Find the resolver declared for `prefix` among `capabilities`.
+ *
+ * PURE, total. Returns:
+ *   - the single matching declaration when exactly one well-formed resolver
+ *     declares `trackerPrefix === prefix`;
+ *   - `null` when zero capabilities declare a well-formed resolver for it
+ *     (an unrecognized prefix is a data case, not a defect — see design row 11);
+ *   - the literal string `'ambiguous'` when two or more do — this must be
+ *     structurally impossible in a correctly-validated install, but this
+ *     function refuses to silently pick one regardless.
+ */
+function findResolver(prefix, capabilities) {
+    const matches = [];
+    for (const cap of capabilities ?? []) {
+        if (!cap || typeof cap !== 'object')
+            continue;
+        const decl = parseResolverDeclaration(cap.id, cap.taskContentResolver);
+        if (decl && decl.trackerPrefix === prefix)
+            matches.push(decl);
+    }
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1)
+        return 'ambiguous';
+    return matches[0];
+}
+/**
+ * Expand a resolver's `invoke.args` template, replacing every `"{{id}}"`
+ * entry with the literal `id` string. Exact-match token replacement, not
+ * template-string interpolation — mirrors `review-lane-invocation.cts`'s
+ * argv-expansion discipline (a placeholder is a whole array element, not a
+ * substring).
+ *
+ * PURE.
+ */
+function buildInvocation(resolver, id) {
+    return {
+        binary: resolver.invoke.binary,
+        args: resolver.invoke.args.map((a) => (a === '{{id}}' ? id : a)),
+        timeoutMs: resolver.invoke.timeoutMs,
+    };
+}
+/**
+ * Real subprocess execution — the default `execFn`. Uses Node's `spawnSync`
+ * with the `timeout` option so a hung resolver is killed at the bound rather
+ * than hanging the caller (CLAUDE.md's Unbounded Subprocesses gauntlet line).
+ */
+function realExec(binary, args, opts) {
+    const result = node_child_process_1.default.spawnSync(binary, args, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: opts.timeout,
+        windowsHide: true,
+    });
+    return {
+        status: result.status ?? null,
+        stdout: (result.stdout ?? '').toString(),
+        stderr: (result.stderr ?? '').toString(),
+        error: result.error ?? undefined,
+    };
+}
+/**
+ * True when an `ExecResult` indicates the subprocess was killed by the
+ * `timeout` option, i.e. it never completed and reported a real answer. Only
+ * `error.code === 'ETIMEDOUT'` is checked — Node.js guarantees this
+ * cross-platform when `spawnSync`'s `timeout` option fires; pairing it with a
+ * `signal === 'SIGTERM'` check is platform-fragile (Windows does not
+ * necessarily report SIGTERM the same way) and risks a false negative. Same
+ * predicate discipline as `shell-command-projection.cts`'s `isSpawnTimeout`.
+ */
+function isExecTimeout(result) {
+    const err = result.error;
+    return err?.code === 'ETIMEDOUT';
+}
+// ─── Resolver JSON → content mapping ──────────────────────────────────────────
+function coerceStringOrNull(value) {
+    return typeof value === 'string' ? value : null;
+}
+function coerceStringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/**
+ * Map a resolver's validated JSON object onto `ResolvedTaskContent`. Every
+ * field is coerced defensively — the resolver's JSON is a third-party CLI's
+ * output, validated for exit code and JSON-object-shape upstream, but never
+ * trusted field-by-field. A missing or wrong-typed field degrades sanely
+ * (string/null fields fall back to `null`, array fields fall back to `[]`);
+ * only the caller's `description`-emptiness check throws no further errors
+ * here — this function is never the one that decides `resolved` vs `empty`.
+ */
+function mapResolverOutput(body) {
+    return {
+        action: coerceStringOrNull(body['description']),
+        verify: coerceStringOrNull(body['verify']),
+        acceptanceCriteria: coerceStringArray(body['acceptance_criteria']),
+        readFirst: coerceStringArray(body['read_first']),
+        done: coerceStringOrNull(body['done']),
+    };
+}
+/**
+ * Orchestrate one task's content resolution: split the `tracker-id`, find the
+ * matching capability's resolver, invoke it through the bounded subprocess
+ * boundary, and map its JSON output onto the four documented outcomes.
+ *
+ * The only impure boundary is `execFn` (defaults to a real `spawnSync` call).
+ * Injecting a fake `execFn` lets tests assert every outcome — including a
+ * timeout — deterministically, without spawning a real process or waiting a
+ * real `timeoutMs`.
+ */
+function resolveTaskContent(input) {
+    const split = splitTrackerId(input.trackerId);
+    if (split === null)
+        return { kind: TASK_CONTENT_RESULT.NOT_APPLICABLE };
+    const resolver = findResolver(split.prefix, input.capabilities ?? []);
+    if (resolver === null)
+        return { kind: TASK_CONTENT_RESULT.NO_RESOLVER };
+    if (resolver === 'ambiguous') {
+        // findResolver never returns the capability ids for the ambiguous case
+        // (it discards the losing matches) — re-derive them here for the error.
+        const ids = (input.capabilities ?? [])
+            .filter((cap) => {
+            const decl = parseResolverDeclaration(cap?.id, cap?.taskContentResolver);
+            return decl !== null && decl.trackerPrefix === split.prefix;
+        })
+            .map((cap) => cap.id);
+        throw new ResolverAmbiguousError(split.prefix, ids);
+    }
+    const invocation = buildInvocation(resolver, split.id);
+    const timeoutMs = input.timeoutOverrideMs ?? invocation.timeoutMs;
+    const execFn = input.execFn ?? realExec;
+    const result = execFn(invocation.binary, invocation.args, { timeout: timeoutMs });
+    if (isExecTimeout(result)) {
+        throw new ResolverTimeoutError(invocation.binary, timeoutMs);
+    }
+    if (result.error || result.status !== 0) {
+        const stderrTail = (result.stderr ?? '').trim().slice(-2000);
+        throw new ResolverFailedError(invocation.binary, result.status, stderrTail);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ResolverMalformedOutputError(invocation.binary, 'stdout is not valid JSON', result.stdout.slice(0, 200));
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new ResolverMalformedOutputError(invocation.binary, `stdout parsed as valid JSON but is not a plain object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, result.stdout.slice(0, 200));
+    }
+    const content = mapResolverOutput(parsed);
+    const description = typeof content.action === 'string' ? content.action.trim() : '';
+    if (description.length === 0) {
+        return { kind: TASK_CONTENT_RESULT.EMPTY };
+    }
+    return { kind: TASK_CONTENT_RESULT.RESOLVED, content };
+}
+const taskContentResolution = {
+    TASK_CONTENT_RESULT,
+    splitTrackerId,
+    findResolver,
+    buildInvocation,
+    resolveTaskContent,
+    ResolverAmbiguousError,
+    ResolverFailedError,
+    ResolverTimeoutError,
+    ResolverMalformedOutputError,
+};
+module.exports = taskContentResolution;

package/gsd-core/bin/lib/teams-status.cjs

@@ -31,6 +31,9 @@ exports.cmdTeamsStatus = cmdTeamsStatus;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output: coreOutput } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 // ─── Pure core ────────────────────────────────────────────────────────────────
 /**
  * Resolve the agent-teams status from injected runtime and env.
@@ -67,7 +70,7 @@ function cmdTeamsStatus(cwd, opts) {
     const status = resolveTeamsStatus({ runtime, env: process.env });
     if (opts.active) {
         // --active mode: no output, exit code encodes the boolean
-        process.exit(status.active ? 0 : 1);
+        throw new ExitError(status.active ? 0 : 1);
     }
     // Default: emit JSON to stdout via io.output, exit 0
     coreOutput(status, false);