@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/active-workstream-store.cjs

@@ -22,6 +22,15 @@ const WORKSTREAM_SESSION_ENV_KEYS = [
     'GSD_SESSION_KEY',
     'CODEX_THREAD_ID',
     'CLAUDE_SESSION_ID',
+    // #3557 — Claude Code (≥ 2.1.132) exports its session id to Bash-tool
+    // subprocesses as CLAUDE_CODE_SESSION_ID. Without it the probe returned
+    // null on Claude Code, so every concurrent session in a working tree
+    // shared the single .planning/active-workstream pointer and cross-
+    // workstream STATE.md writes landed silently in the wrong file. Inserted
+    // beside the other runtime keys without reordering any existing entry;
+    // ahead of CLAUDE_CODE_SSE_PORT so the canonical id wins when both are
+    // present (runtime identity outranks terminal identity in this list).
+    'CLAUDE_CODE_SESSION_ID',
     'CLAUDE_CODE_SSE_PORT',
     'OPENCODE_SESSION_ID',
     'GEMINI_SESSION_ID',
@@ -183,21 +192,150 @@ function pickActiveWorkstreamAdapter(cwd, opts = {}) {
     }
     return createSharedPointerAdapter(cwd);
 }
-function getActiveWorkstream(cwd, opts = {}) {
-    const adapter = pickActiveWorkstreamAdapter(cwd, opts);
-    if (!adapter)
-        return null;
-    const name = adapter.read();
-    if (!name || !validateWorkstreamName(name)) {
-        adapter.clear();
-        return null;
+/**
+ * Read-resolution chain for getActiveWorkstream/peekActiveWorkstream (#3579).
+ *
+ * pickActiveWorkstreamAdapter (above) picks exactly one adapter and remains
+ * the seam for WRITE paths (set/clear), where "which pointer do I mutate" has
+ * only one right answer: the session pointer when a session key exists,
+ * otherwise the shared marker. Reads are different — a session that has
+ * never called `workstream use` has no opinion of its own, so it should
+ * inherit the repo-wide `.planning/active-workstream` marker rather than
+ * resolve to nothing. This returns an ORDERED chain: [owned, ...fallbacks].
+ * `chain[0]` ("owned") is exactly what pickActiveWorkstreamAdapter would have
+ * returned — resolveFromChain() self-heals only chain[0], never a fallback,
+ * so one session's read can never delete another scope's marker. Fallbacks
+ * are consulted ONLY when chain[0].read() comes back absent/empty; a session
+ * with its own (even stale/invalid) pointer never falls through — that is
+ * the isolation guarantee and it must not be weakened by inheritance.
+ */
+function pickActiveWorkstreamAdapterChain(cwd, opts = {}) {
+    if (opts.activeWorkstreamAdapter) {
+        return [opts.activeWorkstreamAdapter];
     }
-    const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);
-    if (!node_fs_1.default.existsSync(wsDir)) {
-        adapter.clear();
+    // #3579 item 3: when a caller supplies `opts.activeWorkstreamAdapters` at
+    // all, honor ONLY what it provides. The prior `|| createXPointerAdapter(...)`
+    // fallback synthesized a REAL filesystem adapter for whichever half a test
+    // double omitted — so a test injecting only `{ session }` silently touched
+    // the real shared marker file, and one injecting only `{ shared }` silently
+    // touched the real session-scoped tmp file. A missing half now gets a
+    // no-op in-memory adapter (always reads null) instead — this preserves the
+    // chain[0]-is-owned / rest-are-fallback shape resolveFromChain relies on
+    // without ever reaching disk. A caller that wants a real adapter for one
+    // half can still construct and pass it explicitly.
+    const injected = opts.activeWorkstreamAdapters;
+    const sessionKey = getWorkstreamSessionKey();
+    if (!sessionKey) {
+        const shared = injected
+            ? (injected.shared ?? createMemoryPointerAdapter(null))
+            : createSharedPointerAdapter(cwd);
+        return [shared];
+    }
+    const session = injected
+        ? (injected.session ?? createMemoryPointerAdapter(null))
+        : createSessionScopedPointerAdapter(cwd, sessionKey);
+    const shared = injected
+        ? (injected.shared ?? createMemoryPointerAdapter(null))
+        : createSharedPointerAdapter(cwd);
+    return session ? [session, shared] : [shared];
+}
+/**
+ * Shared "does this stored name resolve" predicate — format-valid AND its
+ * workstream directory exists. Factored out so resolveFromChain's owned/
+ * fallback arms (and diagnoseUnresolvedActiveWorkstream, #3579 item 1) share
+ * one definition of "resolvable" instead of re-deriving the same two checks.
+ */
+function resolvesToExistingWorkstream(cwd, name) {
+    if (!name || !validateWorkstreamName(name))
+        return false;
+    return node_fs_1.default.existsSync(node_path_1.default.join(planningRoot(cwd), 'workstreams', name));
+}
+/**
+ * Resolves a stored workstream name by walking an adapter chain.
+ *
+ * chain[0] is "owned" by this resolution: an absent/empty read falls through
+ * to the next adapter, but a present-and-bad read (invalid name, or a name
+ * whose workstream dir no longer exists) is resolved right there — self-
+ * healed via adapter.clear() when `selfHeal` is true, and never consulted
+ * further. Anything after chain[0] is a read-only fallback (the inherited
+ * marker): a bad value there resolves to null WITHOUT ever calling clear(),
+ * so a pointer-less session's read can never delete the shared marker that
+ * other sessions/scopes still depend on.
+ */
+function resolveFromChain(cwd, chain, selfHeal) {
+    if (chain.length === 0)
         return null;
+    const [owned, ...fallbacks] = chain;
+    const ownedName = owned.read();
+    if (ownedName) {
+        if (!resolvesToExistingWorkstream(cwd, ownedName)) {
+            if (selfHeal)
+                owned.clear();
+            return null;
+        }
+        return ownedName;
+    }
+    for (const adapter of fallbacks) {
+        const name = adapter.read();
+        if (resolvesToExistingWorkstream(cwd, name))
+            return name;
+    }
+    return null;
+}
+/**
+ * Diagnostic sibling of resolveFromChain (#3579 item 1). getActiveWorkstream/
+ * peekActiveWorkstream collapse EVERY unresolvable case to `null`, which is
+ * exactly right for routing — but a fail-safe guard reporting "no active
+ * workstream is set" to an operator needs to distinguish two very different
+ * situations that both produce that same `null`:
+ *
+ *   (a) no marker/pointer exists anywhere in the chain at all, vs.
+ *   (b) a marker/pointer EXISTS (names a value) but that value didn't
+ *       resolve — either the name fails validateWorkstreamName, or it's a
+ *       well-formed name whose `workstreams/<name>` directory is missing.
+ *
+ * Walks the same chain resolveFromChain uses and, for the first adapter that
+ * held a non-empty raw value, reports why it didn't resolve. Read-only: never
+ * calls adapter.clear() (mirrors peekActiveWorkstream, not getActiveWorkstream
+ * — a diagnostic read must not have side effects). Reuses
+ * resolvesToExistingWorkstream so this can never disagree with the actual
+ * resolution predicate above.
+ */
+function diagnoseUnresolvedActiveWorkstream(cwd, opts = {}) {
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    for (const adapter of chain) {
+        const raw = adapter.read();
+        if (!raw)
+            continue;
+        if (resolvesToExistingWorkstream(cwd, raw))
+            continue;
+        return {
+            present: true,
+            value: raw,
+            reason: validateWorkstreamName(raw) ? 'missing_workstream_dir' : 'invalid_name',
+        };
     }
-    return name;
+    return { present: false, value: null, reason: null };
+}
+function getActiveWorkstream(cwd, opts = {}) {
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    return resolveFromChain(cwd, chain, true);
+}
+/**
+ * Read-only sibling of getActiveWorkstream (#2850): identical resolution —
+ * adapter -> stored name -> validate format -> workstream dir exists — but
+ * NEVER calls adapter.clear(). getActiveWorkstream's self-heal (deleting a
+ * stale/invalid pointer) is correct for a command that is actively acting on
+ * the active workstream; it is wrong for a read-only consumer invoked on
+ * every render (e.g. the statusline hook), which must never mutate
+ * persistent, possibly cross-session state as a side effect of drawing a
+ * screen. A stale or invalid pointer simply resolves to null here — the
+ * caller decides what "unresolvable" means for its own render, and the
+ * pointer file is left exactly as it was for whatever created it to fix.
+ */
+function peekActiveWorkstream(cwd, opts = {}) {
+    const chain = pickActiveWorkstreamAdapterChain(cwd, opts);
+    return resolveFromChain(cwd, chain, false);
 }
 function setActiveWorkstream(cwd, name, opts = {}) {
     const adapter = pickActiveWorkstreamAdapter(cwd, opts);
@@ -287,7 +425,10 @@ module.exports = {
     createSessionScopedPointerAdapter,
     createMemoryPointerAdapter,
     pickActiveWorkstreamAdapter,
+    pickActiveWorkstreamAdapterChain,
     getActiveWorkstream,
+    peekActiveWorkstream,
+    diagnoseUnresolvedActiveWorkstream,
     setActiveWorkstream,
     clearActiveWorkstream,
     parseCliWorkstream,

package/gsd-core/bin/lib/agent-install-check.cjs

@@ -3,8 +3,8 @@
  * Agent Install Check — moved from core.cts (ADR-857 T0 #1268 phase rehome-core-squatters).
  *
  * Owns:
- *   - getAgentsDir(runtime?): string
- *   - checkAgentsInstalled(runtime?): AgentsInstalledResult
+ *   - getAgentsDir(runtime?, projectRoot?): string
+ *   - checkAgentsInstalled(runtime?, projectRoot?): AgentsInstalledResult
  *
  * The core.cjs re-export spine was retired in epic #1267; callers import
  * these symbols from agent-install-check.cjs directly.
@@ -18,25 +18,103 @@ const node_path_1 = __importDefault(require("node:path"));
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES } = modelProfiles;
 const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+// #3242 — model-catalog is a genuine leaf (only node:path + its own JSON), which is
+// exactly why Phase 1 (#3241) moved isAnthropicFlavoredModel there: this module can
+// consume it without dragging model-resolver's config-loader chain into a
+// pure read/verify surface.
+const model_catalog_cjs_1 = require("./model-catalog.cjs");
+// #3243 — the Codex `.toml` block-range/BOM/scan primitives moved into the typed
+// IR module (Phase 3), which this reader now imports rather than defining
+// locally. Behavior is unchanged: scanTomlLines/stripBOM here are the exact
+// same lenient functions that used to live in this file — see
+// codex-agent-toml.cts's module header for the reader/writer reconciliation.
+const codex_agent_toml_cjs_1 = require("./codex-agent-toml.cjs");
+/**
+ * Frozen reason enum for {@link checkCodexModelPosture}. Per CONTRIBUTING's
+ * typed-IR rule ("Error / status / reason → a frozen enum"): callers and tests
+ * assert on these wire values, never on prose. Adding a member is a deliberate
+ * three-way coordinated change — enum, emitting site, and the enum-lock test.
+ */
+const POSTURE_REASON = Object.freeze({
+    ANTHROPIC_FLAVORED_MODEL: 'anthropic_flavored_model',
+    ORPHANED_REASONING_EFFORT: 'orphaned_reasoning_effort',
+    UNREADABLE: 'unreadable',
+    NOT_CODEX: 'not_codex',
+    AGENTS_DIR_MISSING: 'agents_dir_missing',
+});
+// Matches the value-truncation convention in bin/install.js's
+// _warnCodexModelOverrideDropped: values over 64 chars are capped so an
+// oversized or secret-shaped config value can never reach a report in full.
+function truncatePostureValue(value) {
+    return value.length > 64 ? `${value.slice(0, 64)}…` : value;
+}
 /**
  * Resolve the agents directory for the given runtime.
  *
  * Priority:
  *   1. GSD_AGENTS_DIR env var (explicit override, any runtime)
- *   2. For claude runtime: __dirname-relative path (agents/ sibling of gsd-core/)
- *      This is correct for both repo runs and real installs (the runtime config dir's
- *      agents/ folder) because gsd-tools.cjs lives inside gsd-core/bin/ in both cases.
- *   3. For non-claude runtimes: getGlobalConfigDir(runtime)/agents
+ *   2. For claude runtime: __dirname-relative path (agents/ sibling of
+ *      gsd-core/) — correct for repo runs and runtime-config-dir installs,
+ *      where the sibling agents/ IS the user's agents dir — UNLESS that path
+ *      carries an exact node_modules segment. gsd-tools.cjs lives inside
+ *      gsd-core/bin/ in every install shape, but on an npm-global install
+ *      gsd-core/ sits inside the package (not the runtime config dir) and the
+ *      package ships its own agents/, so the install-relative path resolves
+ *      to the bundled copy and the check validates the package against
+ *      itself — agents_installed can never be false. In that case resolve
+ *      getGlobalConfigDir('claude')/agents (honours CLAUDE_CONFIG_DIR) like
+ *      every other runtime (#3203).
+ *   3. For non-claude runtimes with a manifest-backed project-local install:
+ *      <projectRoot>/<localConfigDir>/agents (or <projectRoot>/agents when
+ *      the runtime's local install targets the project root). Requiring the
+ *      GSD manifest prevents runtime-native project agents from shadowing a
+ *      working global GSD install. Symlinked local agent directories are ignored.
+ *   4. For non-claude runtimes: getGlobalConfigDir(runtime)/agents
  *
  * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
  */
-function getAgentsDir(runtime) {
+function getAgentsDir(runtime, projectRoot) {
     if (process.env['GSD_AGENTS_DIR']) {
         return process.env['GSD_AGENTS_DIR'];
     }
     const resolved = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
     if (resolved === 'claude') {
-        return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+        const installRelative = node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+        // #3203: a lexical guard, not an install-shape test. It targets the
+        // layouts where the sibling agents/ is the package's own bundled copy and
+        // the check would otherwise validate the package against itself; a path
+        // merely carrying a directory of that name resolves the same way, and a
+        // non-empty GSD_AGENTS_DIR overrides both.
+        if (installRelative.split(node_path_1.default.sep).includes('node_modules')) {
+            return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)('claude'), 'agents');
+        }
+        return installRelative;
+    }
+    if (projectRoot) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { runtimes } = require('./capability-registry.cjs');
+        const runtimeConfig = runtimes[resolved]?.runtime;
+        const localConfigDirName = (0, runtime_name_policy_cjs_1.getDirName)(resolved);
+        const localConfigDir = localConfigDirName === runtime_name_policy_cjs_1.NO_LOCAL_CONFIG_DIR_SENTINEL
+            ? undefined
+            : runtimeConfig?.hostBehaviors?.localTargetIsProjectRoot
+                ? projectRoot
+                : node_path_1.default.join(projectRoot, localConfigDirName);
+        if (!localConfigDir) {
+            return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolved), 'agents');
+        }
+        const localAgentsDir = node_path_1.default.join(localConfigDir, 'agents');
+        const manifestPath = node_path_1.default.join(localConfigDir, 'gsd-file-manifest.json');
+        try {
+            if (node_fs_1.default.lstatSync(localAgentsDir).isDirectory() && node_fs_1.default.lstatSync(manifestPath).isFile()) {
+                return localAgentsDir;
+            }
+        }
+        catch {
+            // Local discovery is best-effort; any probe failure preserves global fallback.
+        }
     }
     return node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolved), 'agents');
 }
@@ -44,10 +122,11 @@ function getAgentsDir(runtime) {
  * Check which GSD agents are installed on disk.
  *
  * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
  */
-function checkAgentsInstalled(runtime) {
+function checkAgentsInstalled(runtime, projectRoot) {
     const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
-    const agentsDir = getAgentsDir(resolvedRuntime);
+    const agentsDir = getAgentsDir(resolvedRuntime, projectRoot);
     const expectedAgents = Object.keys(MODEL_PROFILES);
     const installed = [];
     const missing = [];
@@ -62,18 +141,7 @@ function checkAgentsInstalled(runtime) {
         };
     }
     for (const agent of expectedAgents) {
-        const agentFile = node_path_1.default.join(agentsDir, `${agent}.md`);
-        const agentFileCopilot = node_path_1.default.join(agentsDir, `${agent}.agent.md`);
-        const agentFileCodex = node_path_1.default.join(agentsDir, `${agent}.toml`);
-        const agentFileKimiYaml = node_path_1.default.join(agentsDir, 'subagents', `${agent}.yaml`);
-        const agentFileKimiPrompt = node_path_1.default.join(agentsDir, 'subagents', `${agent}.md`);
-        const kimiAgentInstalled = resolvedRuntime === 'kimi' &&
-            node_fs_1.default.existsSync(agentFileKimiYaml) &&
-            node_fs_1.default.existsSync(agentFileKimiPrompt);
-        if (node_fs_1.default.existsSync(agentFile) ||
-            node_fs_1.default.existsSync(agentFileCopilot) ||
-            node_fs_1.default.existsSync(agentFileCodex) ||
-            kimiAgentInstalled) {
+        if (agentFileExists(agentsDir, agent, resolvedRuntime)) {
             installed.push(agent);
         }
         else {
@@ -87,22 +155,13 @@ function checkAgentsInstalled(runtime) {
     // when the plain presence check above passed (e.g. .md present, .toml absent).
     // If no manifest is found the check is a no-op (graceful for claude/bundled).
     const incomplete = [];
-    const manifestPath = node_path_1.default.join(node_path_1.default.dirname(agentsDir), 'gsd-file-manifest.json');
-    let manifestFiles = {};
-    try {
-        const raw = node_fs_1.default.readFileSync(manifestPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (parsed !== null &&
-            typeof parsed === 'object' &&
-            'files' in parsed &&
-            typeof parsed['files'] === 'object' &&
-            parsed['files'] !== null) {
-            manifestFiles = parsed['files'];
-        }
-    }
-    catch {
-        // No manifest or unreadable — completeness check is skipped
-    }
+    // #2872: the manifest read is the Installer Migration Module's, not a
+    // fourth private copy of it. Lazily required — matching this file's own
+    // capability-registry idiom — so a pure read/verify surface on the
+    // init/verify hot path takes no new static dependency.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { readInstallManifest } = require('./installer-migrations.cjs');
+    const manifestFiles = readInstallManifest(node_path_1.default.dirname(agentsDir)).files;
     if (Object.keys(manifestFiles).length > 0) {
         for (const agent of expectedAgents) {
             // Find all manifest keys that belong to this agent:
@@ -137,7 +196,178 @@ function checkAgentsInstalled(runtime) {
         agent_runtime: resolvedRuntime,
     };
 }
+/**
+ * Validate Codex `.toml` agent files for Anthropic-flavored `model` pins and
+ * orphaned `model_reasoning_effort` values (ADR-2313 D6, #3242).
+ *
+ * A new sibling export to {@link checkAgentsInstalled}, deliberately — that
+ * function carries 33 upstream dependents and cyclomatic complexity 25, so this
+ * posture check gets zero new branches there (see 40-design.md "Rejected" #1).
+ * Presence is `checkAgentsInstalled`'s job; this function's job starts only once
+ * the runtime is confirmed `codex` and only inspects posture, never presence.
+ *
+ * Read-only: detects, never repairs (repair is Phase 3, #3243).
+ *
+ * @param runtime - the active runtime name; defaults to GSD_RUNTIME env, then 'claude'
+ * @param projectRoot - canonical project root for local-install discovery
+ */
+function checkCodexModelPosture(runtime, projectRoot) {
+    // Short-circuit BEFORE any filesystem access: a non-codex runtime must never
+    // have its agents directory resolved or a stray .toml inspected, however
+    // violating that file's contents would be if it were ever read (#3242 row 25).
+    const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
+    if (resolvedRuntime !== 'codex') {
+        return {
+            ok: true,
+            violations: [],
+            checked: [],
+            agents_dir: '',
+            agent_runtime: resolvedRuntime,
+            reason: POSTURE_REASON.NOT_CODEX,
+        };
+    }
+    const agentsDir = getAgentsDir(resolvedRuntime, projectRoot);
+    if (!node_fs_1.default.existsSync(agentsDir)) {
+        // Presence is checkAgentsInstalled's job — an absent agents dir here is a
+        // distinct, non-violating outcome, not a failure of this check.
+        return {
+            ok: true,
+            violations: [],
+            checked: [],
+            agents_dir: agentsDir,
+            agent_runtime: resolvedRuntime,
+            reason: POSTURE_REASON.AGENTS_DIR_MISSING,
+        };
+    }
+    // Skip symlinks — matches cmdEffortSync's existing idiom in commands.cts
+    // ("Skip symlinks — only write regular files..."). Here the risk is reading
+    // (not writing) through a symlink: readFileSync follows symlinks, so an
+    // agents-dir symlink pointing at an arbitrary file would let that target's
+    // contents be echoed into this function's `value` field. A symlinked agent
+    // file is a structural install choice (checkAgentsInstalled's territory),
+    // not a model-content posture defect, so it is silently excluded from
+    // `checked` rather than reported as a distinct violation — same shape as
+    // cmdEffortSync, which silently drops symlinks from its file list rather
+    // than inventing a new skip/violation reason.
+    const tomlFiles = node_fs_1.default
+        .readdirSync(agentsDir)
+        .filter((entry) => {
+        if (!entry.endsWith('.toml'))
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(node_path_1.default.join(agentsDir, entry)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+    const checked = [];
+    const violations = [];
+    for (const entry of tomlFiles) {
+        const agentName = entry.slice(0, -'.toml'.length);
+        const filePath = node_path_1.default.join(agentsDir, entry);
+        checked.push(agentName);
+        let raw;
+        try {
+            raw = node_fs_1.default.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            // Never throws, never silently skips — an unreadable file is reported and
+            // the loop continues checking the rest (40-design.md "Rejected" #5).
+            violations.push({ agent: agentName, file: filePath, reason: POSTURE_REASON.UNREADABLE });
+            continue;
+        }
+        const { model, hasReasoningEffort } = (0, codex_agent_toml_cjs_1.scanTomlLines)((0, codex_agent_toml_cjs_1.stripBOM)(raw));
+        if (model !== null && (0, model_catalog_cjs_1.isAnthropicFlavoredModel)(model)) {
+            violations.push({
+                agent: agentName,
+                file: filePath,
+                reason: POSTURE_REASON.ANTHROPIC_FLAVORED_MODEL,
+                value: truncatePostureValue(model),
+            });
+        }
+        else if (model === null && hasReasoningEffort) {
+            // #838 coupling: a reasoning-effort pin with no model pin means Codex
+            // inherits the session model while the effort pin silently disagrees.
+            violations.push({
+                agent: agentName,
+                file: filePath,
+                reason: POSTURE_REASON.ORPHANED_REASONING_EFFORT,
+            });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        violations,
+        checked,
+        agents_dir: agentsDir,
+        agent_runtime: resolvedRuntime,
+    };
+}
+/**
+ * Probe a single agents dir for `<name>` across runtime filename variants.
+ * Mirrors {@link checkAgentsInstalled}'s probe (`.md`, `.agent.md`, `.toml`,
+ * and the kimi `subagents/<name>.{yaml,md}` pair) so the two can never disagree
+ * about which on-disk shapes count as "installed". Not exported — internal to
+ * {@link resolveAgentHint}.
+ */
+function agentFileExists(agentsDir, name, runtime) {
+    const base = node_path_1.default.join(agentsDir, `${name}.md`);
+    const copilot = node_path_1.default.join(agentsDir, `${name}.agent.md`);
+    const codex = node_path_1.default.join(agentsDir, `${name}.toml`);
+    if (node_fs_1.default.existsSync(base) || node_fs_1.default.existsSync(copilot) || node_fs_1.default.existsSync(codex)) {
+        return true;
+    }
+    // kimi requires BOTH the persona yaml and the prompt md (same as checkAgentsInstalled).
+    const kimiYaml = node_path_1.default.join(agentsDir, 'subagents', `${name}.yaml`);
+    const kimiPrompt = node_path_1.default.join(agentsDir, 'subagents', `${name}.md`);
+    return runtime === 'kimi' && node_fs_1.default.existsSync(kimiYaml) && node_fs_1.default.existsSync(kimiPrompt);
+}
+/**
+ * Resolve a per-plan `agent_hint` specialist name to a dispatchable subagent
+ * type on the active runtime (#1689). Unlike {@link checkAgentsInstalled},
+ * which validates the fixed GSD roster, this answers "does an agent file for
+ * this ARBITRARY name exist in the active runtime's agent dir(s)?" — so a plan
+ * can opt into a domain specialist (e.g. a Flutter engineer) that shares the
+ * gsd-executor contract without being part of the built-in roster.
+ *
+ * Probes BOTH the runtime-canonical agents dir ({@link getAgentsDir}, which
+ * honors `GSD_AGENTS_DIR`, project-local manifest-backed installs, and the
+ * claude install-relative path) AND the runtime's global config agents dir, so
+ * a specialist installed at either level is recognized. The decision in #1689
+ * explicitly requires consulting the active runtime's agent dir rather than
+ * only the Claude runtime's user-global and project-local agent dirs.
+ *
+ * @returns the name when a matching agent file exists; `null` when it does not
+ *   (the caller falls back to `gsd-executor`). An empty/whitespace name always
+ *   returns `null`.
+ */
+function resolveAgentHint(name, runtime, projectRoot) {
+    const trimmed = String(name ?? '').trim();
+    if (trimmed === '')
+        return null;
+    // A hint is a bare agent name. Reject path separators and `..` so a value
+    // like `../../README` cannot path-traverse out of the agents dir via
+    // path.join and match an unrelated file — that would echo an invalid
+    // subagent_type and block the wave, defeating fail-closed resolution.
+    if (trimmed.includes('/') || trimmed.includes('\\') || trimmed.includes('..'))
+        return null;
+    const resolvedRuntime = runtime ?? (process.env['GSD_RUNTIME'] || 'claude');
+    const candidateDirs = new Set();
+    candidateDirs.add(getAgentsDir(resolvedRuntime, projectRoot));
+    candidateDirs.add(node_path_1.default.join((0, runtime_homes_cjs_1.getGlobalConfigDir)(resolvedRuntime), 'agents'));
+    for (const dir of candidateDirs) {
+        if (agentFileExists(dir, trimmed, resolvedRuntime)) {
+            return trimmed;
+        }
+    }
+    return null;
+}
 module.exports = {
     getAgentsDir,
     checkAgentsInstalled,
+    checkCodexModelPosture,
+    POSTURE_REASON,
+    resolveAgentHint,
 };