@opengsd/gsd-core 1.7.0 → 1.9.0

package/gsd-core/bin/lib/capability-writer.cjs

@@ -255,8 +255,13 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const runtimeArtifactLayout = require('./runtime-artifact-layout.cjs');
+            // #2322: thread the SAME composed registry (loaded above, includeInstalled:true)
+            // into layout resolution so the skills kind's stage() closure can bind a
+            // third-party capability skill to its declaring capId at staging time —
+            // required for BOTH the '*' (full-profile) fill-in and the ownership binding
+            // (see resolveRuntimeArtifactLayout's #2322 doc comment).
             // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-            const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope);
+            const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, resolvedConfigDir, scope, registry);
             const commandsGsdDir = _resolveCommandsGsdDir();
             const manifest = _resolveManifest(commandsGsdDir, resolvedConfigDir);
             // #1575: applySurface now accepts opts.resolveAttribution so surface-path

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

@@ -134,7 +134,26 @@ function loadPlanContents(phaseDir) {
     }
 }
 const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
-const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]{0,1000})?>((?:(?!<(?:objective|tasks?|action)[\s>])[\s\S])*?)<\/(?:objective|tasks?|action)>/gi;
+// #2372: scanned-tag set must match the planner-canonical surfaces where a D-NN citation
+// is meaningful. `<objective>`/`<tasks>`/`<task>`/`<action>` are the historical core. The
+// planner is also explicitly told (plan-phase.md) to cite decisions in `<read_first>`,
+// `<behavior>`, `<verify>`, `<acceptance_criteria>`, and `<done>` — those are now scanned too,
+// so the gate no longer reports a false coverage gap when a decision is cited in any of them.
+//
+// Implementation: per-tag matching, NOT a single wide alternation. A single alternation
+// like `<(?:a|b|c)>...<\/(?:a|b|c)>` halts the outer tag's body capture at any inner tag
+// in the set, dropping any citation in the outer tag's prefix prose — e.g.
+// `<action>per D-05 <verify>npm test</verify></action>` would lose D-05 because `<verify>`
+// halts the `<action>` body before the citation. Per-tag matching avoids this: each tag's
+// body terminates only at its OWN closing tag, so `<verify>` inside `<action>` is absorbed
+// into `<action>`'s body (D-05 caught) AND `<verify>` is matched separately on its own pass.
+// Each per-tag regex keeps the ReDoS-safe negative-lookahead tempering (#2128).
+const XML_DECISION_TAG_NAMES = ['objective', 'tasks', 'task', 'action', 'read_first', 'behavior', 'verify', 'acceptance_criteria', 'done'];
+function buildXmlDecisionTagRegex(tagName) {
+    // Per-tag: body tempering stops only at the SAME tag's reopening or closing — other
+    // scanned tags pass through as text into this body. Non-greedy `*?` to first close.
+    return new RegExp(`<${tagName}(?:\\s[^>]{0,1000})?>((?:(?!<${tagName}[\\s>])[\\s\\S])*?)<\\/${tagName}>`, 'gi');
+}
 function stripCommentsAndFences(text) {
     // HTML-comment stripping stays caller-side (the seam does not strip HTML comments).
     // Stop-at-next-open body (ReDoS-safe, #2128); an UNCLOSED `<!--` does not match,
@@ -162,9 +181,12 @@ function extractYamlBlock(frontmatter, key) {
 }
 function extractXmlTagBodies(text) {
     const parts = [];
-    for (const match of text.matchAll(XML_DECISION_TAGS_RE)) {
-        if (match[1])
-            parts.push(match[1]);
+    for (const tagName of XML_DECISION_TAG_NAMES) {
+        const re = buildXmlDecisionTagRegex(tagName);
+        for (const match of text.matchAll(re)) {
+            if (match[1])
+                parts.push(match[1]);
+        }
     }
     return parts.join('\n');
 }
@@ -209,7 +231,10 @@ function buildPlanMessage(uncovered) {
         '',
         ...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
         '',
-        'Resolve by citing `D-NN:` in a relevant plan\'s `must_haves`/`truths` (or body),',
+        'Resolve by citing `D-NN:` in any of the scanned plan surfaces: front-matter',
+        '`must_haves`/`truths`/`objective`, a `## must_haves`/`truths`/`tasks`/`objective`',
+        'heading, or an `<objective>`/`<tasks>`/`<task>`/`<action>`/`<read_first>`/`<behavior>`/`<verify>`/`<acceptance_criteria>`/`<done>`',
+        'tag body. Other locations (prose outside those headings, comments, other XML tags) are not scanned.',
         'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
     ].join('\n');
 }
@@ -235,12 +260,22 @@ function loadDecisionExtraction(contextPath) {
 }
 function cmdDecisionCoveragePlan(projectDir, args, raw) {
     const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
-    const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
+    const contextArg = args[3];
+    const contextPath = contextArg ? resolvePath(contextArg, projectDir) : '';
     if (!gateEnabled(projectDir)) {
         output({ passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' }, raw, undefined);
         return;
     }
-    if (!contextPath || !node_fs_1.default.existsSync(contextPath)) {
+    // #2770: an EMPTY/MISSING contextPath argument is a CALLER ERROR (the workflow
+    // forgot to pass the path — e.g. a shell variable lost between Bash blocks), not
+    // evidence the phase has no CONTEXT.md. Fail closed (mirrors #1365 fail-loud) so a
+    // blocking gate cannot silently certify success on a caller mistake.
+    if (!contextArg || contextArg === '') {
+        output({ passed: false, skipped: false, reason: 'missing context path argument', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate called without a context path argument — the caller (e.g. the plan-phase workflow) must pass the CONTEXT.md path. An empty argument is a caller error, not evidence there is nothing to check (#2770).' }, raw, undefined);
+        return;
+    }
+    // A REAL path whose file genuinely does not exist is the LEGITIMATE green skip.
+    if (!node_fs_1.default.existsSync(contextPath)) {
         output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw, undefined);
         return;
     }
@@ -645,7 +680,11 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
                 const planPath = node_path_1.default.join(phaseDir, file);
                 const content = readIfExists(planPath);
                 // Check frontmatter for type: tdd
-                const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+                // CRLF-tolerant: a PLAN.md written with Windows line endings (---\r\n...---)
+                // must still match. The same CRLF-tolerant form is already used at line 205
+                // (extractPlanDesignatedSections); this is the same canonical pattern, applied
+                // here for the tdd-classification path. Fixes #2449.
+                const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
                 if (frontmatterMatch) {
                     const fm = frontmatterMatch[1];
                     if (/^type:\s*tdd\s*$/m.test(fm)) {
@@ -1010,6 +1049,38 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         }
         const v = validateCoverageMatrix(matrixText);
         if (v.valid) {
+            if (v.none_declared) {
+                // The declaration is the human override for the detector — it PASSES
+                // even when detection fires (that is acceptance #5's point: the
+                // detector is fallible and the declaration is the reasoned overrule).
+                // But a contradiction must be VISIBLE, not silent: re-run detection
+                // over the phase scope and surface any signals it still finds
+                // (#2365 review S-1).
+                const declScope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+                const declDetection = detectApiIntegration(declScope.text);
+                const declSignals = declDetection.signals.map((s) => ({ verb: s.verb, noun: s.noun }));
+                // The declaration legitimately wins even over a read error (it is the
+                // human overrule), but if scope was incomplete we say so — the contract
+                // is that contradictions stay visible, not silent (#2365 review).
+                const baseMsg = declDetection.detected
+                    ? `api-coverage: COVERAGE.md declares no external API integration, overriding ${declSignals.length} detected signal(s) — confirm the declaration is accurate`
+                    : 'api-coverage: COVERAGE.md declares no external API integration — matrix not required';
+                output({
+                    block: false,
+                    passed: true,
+                    coverage_present: true,
+                    matrix: coverageFile,
+                    counts: v.counts,
+                    none_declared: true,
+                    detected: declDetection.detected,
+                    ...(declDetection.detected ? { signals: declSignals } : {}),
+                    ...(declScope.readError ? { scope_read_error: declScope.readError } : {}),
+                    message: declScope.readError
+                        ? `${baseMsg} (note: phase scope was incompletely read — ${declScope.readError})`
+                        : baseMsg,
+                }, raw, undefined);
+                return;
+            }
             output({
                 block: false,
                 passed: true,
@@ -1044,8 +1115,22 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         return;
     }
     // (2) no matrix — detect whether this phase integrates an external API.
-    const scopeText = readPhaseScope(projectDir, resolvedDir, phaseNumber);
-    const detection = detectApiIntegration(scopeText);
+    const scope = readPhaseScope(projectDir, resolvedDir, phaseNumber);
+    if (scope.readError) {
+        // Fail-closed: an unreadable plan could be the one describing the
+        // integration, so we cannot certify "no integration" — block and surface it.
+        output({
+            block: true,
+            passed: false,
+            coverage_present: false,
+            detected: false,
+            message: `api-coverage: could not read the phase scope (${scope.readError}); ` +
+                'refusing to certify no external-API integration from incomplete scope. ' +
+                'Fix the unreadable plan file, or add a COVERAGE.md declaration.',
+        }, raw, undefined);
+        return;
+    }
+    const detection = detectApiIntegration(scope.text);
     if (detection.detected) {
         // Surface only verb/noun (typed, bounded) — NOT raw prose snippets — so the
         // gate output cannot relay injected PLAN.md instructions to the orchestrator.
@@ -1070,15 +1155,16 @@ function cmdApiCoverageVerifyPre(projectDir, args, raw) {
         message: 'api-coverage: no external-API integration detected; coverage matrix not required',
     }, raw, undefined);
 }
-/**
- * Read the phase-scope text used for API-integration detection. Uses the
- * resolved plan files (PLAN.md bodies — the planner's own words about what the
- * phase does) and, as a fallback, ONLY THIS PHASE'S ROADMAP section (not the
- * whole roadmap, which would cross-contaminate sibling phases). Strips nothing
- * here — detectApiIntegration strips fenced code itself.
- */
+/** A filesystem error that is NOT "does not exist" — i.e. a real read failure
+ *  (EACCES/EIO/…) the gate must not swallow. `ENOENT` is a legitimate "not
+ *  there yet" and is treated as absence, not error. */
+function isRealReadFailure(err) {
+    const code = err?.code;
+    return err != null && code !== 'ENOENT';
+}
 function readPhaseScope(projectDir, phaseDir, phaseNumber) {
     const chunks = [];
+    let readError = null;
     try {
         const entries = node_fs_1.default.readdirSync(phaseDir, { withFileTypes: true });
         const plans = entries
@@ -1086,28 +1172,52 @@ function readPhaseScope(projectDir, phaseDir, phaseNumber) {
             .map((e) => e.name)
             .sort();
         for (const p of plans) {
-            chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+            try {
+                chunks.push(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, p), 'utf8'));
+            }
+            catch (err) {
+                // A plan file that exists but cannot be read — record it and keep
+                // reading the rest so the message names the first failure.
+                if (!readError) {
+                    readError = `could not read ${p}: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
         }
     }
-    catch {
-        // ignore — fall through to roadmap
+    catch (err) {
+        // A MISSING phase directory is fine (no plans yet → fall through to the
+        // roadmap). A directory that exists but cannot be enumerated (EACCES/EIO)
+        // is a real read failure the gate must not silently pass (#2365 review).
+        if (isRealReadFailure(err)) {
+            return {
+                text: '',
+                readError: `could not read the phase directory: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
     }
+    if (readError)
+        return { text: chunks.join('\n\n'), readError };
     if (chunks.join('').trim().length > 0)
-        return chunks.join('\n\n');
+        return { text: chunks.join('\n\n'), readError: null };
     // Fallback: ONLY this phase's ROADMAP section (not the whole file, which
-    // would pollute detection with sibling-phase prose). Best-effort; absence or
-    // an unresolvable section is non-fatal (detector returns not-detected).
+    // would pollute detection with sibling-phase prose). A MISSING roadmap/section
+    // is non-fatal; a roadmap that exists but cannot be read is a real failure.
     if (phaseNumber) {
         try {
             const section = getRoadmapPhaseWithFallback(projectDir, phaseNumber);
             if (section)
-                return section;
+                return { text: section, readError: null };
         }
-        catch {
-            // ignore
+        catch (err) {
+            if (isRealReadFailure(err)) {
+                return {
+                    text: '',
+                    readError: `could not read the roadmap fallback: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
         }
     }
-    return '';
+    return { text: '', readError: null };
 }
 function routeCheckCommand({ args, cwd, raw }) {
     // Normalize dots to hyphens in the subcommand so both forms are accepted.
@@ -1197,4 +1307,7 @@ module.exports = {
     cmdCheckPredicate,
     buildPredicateDeps,
     parsePredicateFlags,
+    // Fail-closed phase-scope reader for the api-coverage gate — exported for
+    // in-process failure-injection tests (#2365 review).
+    readPhaseScope,
 };

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

@@ -13,6 +13,17 @@
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const commandRoutingHub = require("./command-routing-hub.cjs");
 const { createHub, ERROR_KINDS } = commandRoutingHub;
+// #2620 (ADR-0174 §6): the Hub defaults to a no-op logger and the live CLI
+// dispatch path never injected the reference DispatchLogger, so GSD_AUDIT and
+// config.audit.enabled were inert. Inject the reference logger ONLY when
+// observability is opt-in enabled; when off, inject nothing so the Hub stays
+// byte-for-byte silent (preserving the default dispatch output contract, incl.
+// --json-errors). Enabling stderr-on-error unconditionally by default is a
+// separate, blast-radius-bearing change (it adds a second stderr line to the
+// --json-errors envelope) — deferred as its own follow-up.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const observabilityLogger = require("./observability/logger.cjs");
+const { createDefaultLogger, isAuditEnabled } = observabilityLogger;
 // Phase 2 (#1646): import ERROR_REASON so the UnknownCommand translation can
 // pass `sdk_unknown_command` as the second arg to error(), preserving the
 // JSON-error envelope contract that capability routers' tests assert on.
@@ -73,6 +84,10 @@ function routeHubCommandFamily({ family, args, subcommands, handlers, defaultSub
     const hub = createHub({
         cjsRegistry: { [family]: registryHandlers },
         manifest: { [family]: available },
+        // #2620: wire the reference logger onto the live dispatch path (ADR-0174 §6),
+        // but only when observability is opt-in enabled — otherwise leave it unset
+        // so the Hub falls back to the no-op logger and stays byte-for-byte silent.
+        logger: isAuditEnabled() ? createDefaultLogger({ cwd }) : undefined,
     });
     const result = hub.dispatch({
         family,

package/gsd-core/bin/lib/claude-orchestration-command-router.cjs

@@ -14,15 +14,31 @@
  *
  * Subcommands:
  *   detect-backend [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch]
- *       Resolves whether the Workflow backend should activate. `--runtime`
- *       defaults to the GSD_RUNTIME env var (or 'unknown'). Reads the
+ *       Resolves whether the Workflow backend should activate. Both flags are
+ *       OPTIONAL (#2590): `--runtime` falls back to the canonical
+ *       `GSD_RUNTIME > config.runtime > 'claude'` chain, and
+ *       `--agent-sdk-version` to `GSD_AGENT_SDK_VERSION` then the installed
+ *       @anthropic-ai/claude-agent-sdk version. Reads the
  *       `claude_orchestration.*` keys from .planning/config.json. Emits
  *       { available, backend, reason }.
  *
- *   emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>]
+ *   emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>] [--executor-model <id>]
  *       Reads a wave/plan manifest JSON file and emits the generated Workflow
  *       script + summary. The manifest shape matches emitWorkflowScript's input:
- *       { waves: [{ id, plans: [{ id, brief, files_modified: string[] }] }] }.
+ *       { waves: [{ id, plans: [{ id, brief, files_modified: string[], use_worktree?: boolean }] }] }.
+ *       `use_worktree` defaults to true; pass `false` for a plan the inline path
+ *       (execute-phase.md step 2.5) would also keep out of worktree isolation
+ *       (submodule-touching plans — #2772 / #2285 finding 1).
+ *
+ *   resolve-wave-dispatch --waves <path> --run-id <id> [--runtime <id>]
+ *       [--agent-sdk-version <ver>] [--no-nested-dispatch] [--phase-dir <dir>]
+ *       [--budget <n>] [--executor-model <id>]
+ *       #2285 — the single composed seam a PRE-wave dispatch-backend selector
+ *       (`execute:wave:pre`) uses: resolves detect-backend + emit-workflow in
+ *       ONE call. Emits { backend: 'inline'|'workflow', reason, script?, summary? }.
+ *       Fail-closed identically to detect-backend/emit-workflow individually —
+ *       any gate miss, or an emit failure on a malformed --waves manifest,
+ *       resolves to 'inline' with no script.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -35,31 +51,31 @@ const io = require("./io.cjs");
 const core = require("./claude-orchestration.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeSlash = require("./runtime-slash.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
+const modelResolver = require("./model-resolver.cjs");
 const { output } = io;
-const { detectWorkflowBackend, emitWorkflowScript } = core;
+const { detectWorkflowBackend, emitWorkflowScript, resolveWaveDispatch } = core;
 const CAPABLE_HOST = { dispatch: { nested: true, background: true } };
 function usage(error) {
-    error('Usage: gsd-tools claude-orchestration <detect-backend|emit-workflow> [...]\n' +
+    error('Usage: gsd-tools claude-orchestration <detect-backend|emit-workflow|resolve-wave-dispatch> [...]\n' +
         '  detect-backend [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch]\n' +
-        '  emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>]');
+        '  emit-workflow --waves <path> --run-id <id> [--phase-dir <dir>] [--budget <n>] [--executor-model <id>]\n' +
+        '  resolve-wave-dispatch --waves <path> --run-id <id> [--runtime <id>] [--agent-sdk-version <ver>] [--no-nested-dispatch] [--phase-dir <dir>] [--budget <n>] [--executor-model <id>]');
 }
 function argValue(args, flag) {
     const i = args.indexOf(flag);
     return i !== -1 && i + 1 < args.length ? args[i + 1] : undefined;
 }
 /**
- * Detect whether the Workflow backend should activate for the current/given
- * runtime. Reads `claude_orchestration.*` from the project config; runtime and
- * SDK version come from flags (the orchestrator already knows these) or env.
+ * Resolve the `claude_orchestration.*` config slice from the project config
+ * (federated keys are merged by loadConfig as a nested object), flattened into
+ * the dotted-key shape `detectWorkflowBackend`/`resolveWaveDispatch` expect. A
+ * config read failure degrades to an empty slice — it must not break the core
+ * loop. Shared by `detect-backend` and `resolve-wave-dispatch`.
  */
-function cmdDetectBackend(args, cwd, raw) {
-    const runtimeId = argValue(args, '--runtime') || process.env['GSD_RUNTIME'] || 'unknown';
-    const agentSdkVersion = argValue(args, '--agent-sdk-version');
-    const noNested = args.includes('--no-nested-dispatch');
-    const hostIntegration = noNested ? { dispatch: { nested: false, background: true } } : CAPABLE_HOST;
-    // Resolve the claude_orchestration.* slice from the project config (federated
-    // keys are merged by loadConfig as a nested object). A config read failure
-    // degrades to inline — it must not break the core loop.
+function resolveFlatClaudeOrchestrationConfig(cwd) {
     let claudeSlice = {};
     try {
         const loaded = configLoader.loadConfig(cwd);
@@ -71,18 +87,144 @@ function cmdDetectBackend(args, cwd, raw) {
     catch {
         claudeSlice = {};
     }
-    // Flatten the nested slice into the dotted-key shape detectWorkflowBackend expects.
     const flatConfig = {};
     for (const k of Object.keys(claudeSlice)) {
         flatConfig['claude_orchestration.' + k] = claudeSlice[k];
     }
+    return flatConfig;
+}
+/**
+ * Resolve the installed Agent SDK version (#2590).
+ *
+ * The `execute:wave:pre` fragment claimed the orchestrator "has no scriptable
+ * way to introspect the live Agent SDK version" and told callers to omit the
+ * flag — so gate 5 returned `agent_sdk_version_unknown` on every automated run
+ * and the Workflow backend never activated, while `capability state` still
+ * reported it `active: true`. That claim is true for BASH, but this router runs
+ * in Node: the installed package's own package.json is authoritative and
+ * requires no flag at all.
+ *
+ * Resolution is side-effect-free and fails closed to undefined (gate 5 then
+ * declines, exactly as before) rather than guessing a version.
+ */
+const AGENT_SDK_PKG = node_path_1.default.join('@anthropic-ai', 'claude-agent-sdk', 'package.json');
+function resolveInstalledAgentSdkVersion(cwd) {
+    // Walk node_modules up the tree by hand rather than require.resolve: the SDK's
+    // `exports` map does not expose './package.json', so require.resolve throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED. Reading the file directly is exports-map
+    // independent and cannot execute package code.
+    for (const start of [cwd, __dirname]) {
+        let dir;
+        try {
+            dir = node_path_1.default.resolve(start);
+        }
+        catch {
+            continue;
+        }
+        for (;;) {
+            try {
+                const pkgPath = node_path_1.default.join(dir, 'node_modules', AGENT_SDK_PKG);
+                if (node_fs_1.default.existsSync(pkgPath)) {
+                    const parsed = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf8'));
+                    if (typeof parsed.version === 'string' && parsed.version.length > 0)
+                        return parsed.version;
+                }
+            }
+            catch { /* unreadable/malformed — keep walking */ }
+            const parent = node_path_1.default.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve `--runtime`/`--agent-sdk-version`/`--no-nested-dispatch` into the
+ * `{ runtimeId, hostIntegration, agentSdkVersion }` triple both `detect-backend`
+ * and `resolve-wave-dispatch` pass to the pure detection seam.
+ */
+function resolveDetectionArgs(args, cwd) {
+    // #2590: the old fallback chain was `--runtime > GSD_RUNTIME > 'unknown'`,
+    // diverging from the canonical `GSD_RUNTIME > config.runtime > 'claude'` used
+    // by runtime-slash.resolveRuntime — so ANY manual invocation without
+    // --runtime reported `runtime_not_claude` on a perfectly ordinary Claude
+    // project. Delegate to the canonical resolver instead of re-deriving it.
+    const runtimeId = argValue(args, '--runtime') || runtimeSlash.resolveRuntime(cwd || null);
+    // Explicit flag wins (lets a caller pin a version); then the environment;
+    // then the actually-installed SDK.
+    const agentSdkVersion = argValue(args, '--agent-sdk-version')
+        || process.env['GSD_AGENT_SDK_VERSION']
+        || resolveInstalledAgentSdkVersion(cwd || process.cwd());
+    const noNested = args.includes('--no-nested-dispatch');
+    const hostIntegration = noNested ? { dispatch: { nested: false, background: true } } : CAPABLE_HOST;
+    return { runtimeId, hostIntegration, agentSdkVersion };
+}
+/**
+ * #2686 — resolve the `gsd-executor` model this dispatch should carry.
+ *
+ * Defaults from the project config rather than requiring a flag. The Workflow
+ * backend previously emitted no model at all, so `model_overrides` /
+ * `model_policy` / `model_profile` were silently inert on that path while the
+ * inline path honored them. Reading the same source the inline path reads is
+ * what makes the two backends agree by construction: an orchestrator that never
+ * learns about a new flag would otherwise silently keep the old bug.
+ *
+ * `--executor-model` exists only to pin/override. Resolution is side-effect-free
+ * and fails closed to `undefined` (emission then omits the key, i.e. exactly the
+ * pre-#2686 output) rather than guessing a model.
+ */
+function resolveExecutorModel(args, cwd) {
+    const pinned = argValue(args, '--executor-model');
+    if (pinned !== undefined)
+        return pinned;
+    try {
+        const resolved = modelResolver.resolveModelInternal(cwd, 'gsd-executor');
+        return typeof resolved === 'string' ? resolved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read and parse a `--waves <path>` manifest file.
+ *
+ * #2285 finding 2: a real read/parse failure (`ok:false`) is DISTINCT from a
+ * manifest that parsed fine but has no top-level `waves` key (`ok:true, waves:
+ * undefined`) — collapsing both into the same sentinel made the missing-key
+ * case exit 0 with ZERO output (fail-silent), breaking the "exit 0 => parseable
+ * JSON verdict" contract callers rely on. Only the `ok:false` (read/parse threw)
+ * case calls `error(...)` and should short-circuit the caller; `ok:true` with a
+ * missing/malformed `waves` value must flow through to `emitWorkflowScript`'s
+ * own validation (matching how `{"waves": null}` already behaves) so the caller
+ * emits an explicit, non-empty verdict instead of silently doing nothing.
+ */
+function readWavesManifest(wavesPath, error) {
+    try {
+        const content = node_fs_1.default.readFileSync(node_path_1.default.resolve(wavesPath), 'utf8');
+        const parsed = JSON.parse(content);
+        return { ok: true, waves: parsed['waves'] };
+    }
+    catch (e) {
+        error('could not read/parse --waves file "' + wavesPath + '": ' + (e instanceof Error ? e.message : String(e)));
+        return { ok: false };
+    }
+}
+/**
+ * Detect whether the Workflow backend should activate for the current/given
+ * runtime. Reads `claude_orchestration.*` from the project config; runtime and
+ * SDK version come from flags (the orchestrator already knows these) or env.
+ */
+function cmdDetectBackend(args, cwd, raw) {
+    const { runtimeId, hostIntegration, agentSdkVersion } = resolveDetectionArgs(args, cwd);
+    const flatConfig = resolveFlatClaudeOrchestrationConfig(cwd);
     const result = detectWorkflowBackend({ runtimeId, hostIntegration, config: flatConfig, agentSdkVersion });
     output(result, raw);
 }
 /**
  * Emit a Workflow script from a wave/plan manifest file.
  */
-function cmdEmitWorkflow(args, _cwd, raw, error) {
+function cmdEmitWorkflow(args, cwd, raw, error) {
     const wavesPath = argValue(args, '--waves');
     const runId = argValue(args, '--run-id');
     const phaseDir = argValue(args, '--phase-dir') || '.planning/phases/current';
@@ -95,23 +237,17 @@ function cmdEmitWorkflow(args, _cwd, raw, error) {
         error('emit-workflow requires --run-id <id>');
         return;
     }
-    let waves;
-    try {
-        const content = node_fs_1.default.readFileSync(node_path_1.default.resolve(wavesPath), 'utf8');
-        const parsed = JSON.parse(content);
-        waves = parsed['waves'];
-    }
-    catch (e) {
-        error('emit-workflow: could not read/parse --waves file "' + wavesPath + '": ' + (e instanceof Error ? e.message : String(e)));
-        return;
-    }
+    const read = readWavesManifest(wavesPath, (msg) => error('emit-workflow: ' + msg));
+    if (!read.ok)
+        return; // read/parse failure — error() already surfaced it loudly above
     const budgetTokens = budgetRaw !== undefined ? parseInt(budgetRaw, 10) : undefined;
     const budget = (typeof budgetTokens === 'number' && !Number.isNaN(budgetTokens)) ? budgetTokens : undefined;
     const result = emitWorkflowScript({
         phaseDir,
         runId,
-        waves: waves,
+        waves: read.waves,
         budgetTokens: budget,
+        executorModel: resolveExecutorModel(args, cwd),
     });
     if (!result.ok) {
         error('emit-workflow: ' + result.reason);
@@ -119,6 +255,45 @@ function cmdEmitWorkflow(args, _cwd, raw, error) {
     }
     output({ script: result.script, summary: result.summary }, raw);
 }
+/**
+ * #2285 — the single composed seam a PRE-wave dispatch-backend selector
+ * (`execute:wave:pre`) uses: resolves `detect-backend` + `emit-workflow` in
+ * ONE call via `resolveWaveDispatch`. Emits
+ * `{ backend: 'inline'|'workflow', reason, script?, summary? }`.
+ */
+function cmdResolveWaveDispatch(args, cwd, raw, error) {
+    const wavesPath = argValue(args, '--waves');
+    const runId = argValue(args, '--run-id');
+    const phaseDir = argValue(args, '--phase-dir') || '.planning/phases/current';
+    const budgetRaw = argValue(args, '--budget');
+    if (!wavesPath) {
+        error('resolve-wave-dispatch requires --waves <path>');
+        return;
+    }
+    if (!runId) {
+        error('resolve-wave-dispatch requires --run-id <id>');
+        return;
+    }
+    const read = readWavesManifest(wavesPath, (msg) => error('resolve-wave-dispatch: ' + msg));
+    if (!read.ok)
+        return; // read/parse failure — error() already surfaced it loudly above
+    const { runtimeId, hostIntegration, agentSdkVersion } = resolveDetectionArgs(args, cwd);
+    const flatConfig = resolveFlatClaudeOrchestrationConfig(cwd);
+    const budgetTokens = budgetRaw !== undefined ? parseInt(budgetRaw, 10) : undefined;
+    const budget = (typeof budgetTokens === 'number' && !Number.isNaN(budgetTokens)) ? budgetTokens : undefined;
+    const result = resolveWaveDispatch({
+        runtimeId,
+        hostIntegration,
+        config: flatConfig,
+        agentSdkVersion,
+        phaseDir,
+        runId,
+        waves: read.waves,
+        budgetTokens: budget,
+        executorModel: resolveExecutorModel(args, cwd),
+    });
+    output(result, raw);
+}
 function routeClaudeOrchestrationCommand(opts) {
     const { args, cwd, raw, error } = opts;
     // args[0] is the family ('claude-orchestration'); the subcommand is args[1].
@@ -129,6 +304,9 @@ function routeClaudeOrchestrationCommand(opts) {
     else if (subcommand === 'emit-workflow') {
         cmdEmitWorkflow(args, cwd, raw, error);
     }
+    else if (subcommand === 'resolve-wave-dispatch') {
+        cmdResolveWaveDispatch(args, cwd, raw, error);
+    }
     else {
         usage(error);
     }