fix(#2939): honor the declared depth budget in shouldFlattenDispatch (#3063)

* test(#2939): prove shouldFlattenDispatch ignores the depth budget

Failing-first regression for #2939. shouldFlattenDispatch checks only
background+backgroundDispatch, never nested/subagentToolkit/maxDepth, so a
maxDepth:1 descriptor (no room for a bg orchestrator plus a leaf) is told it
may background. Row 1 (codex-like, maxDepth:1) asserts true (flatten) and
fails today; rows 2/3 guard the unchanged depth-sufficient cases.

* fix(#2939): honor the declared depth budget in shouldFlattenDispatch

shouldFlattenDispatch checked only background+backgroundDispatch, never
nested/subagentToolkit/maxDepth, so a maxDepth:1 descriptor (no room for a
backgrounded orchestrator plus a delegated leaf) was told it may background —
producing a depth-2 tree (Codex MultiAgent V2) the declared contract cannot
support.

canBackground now ALSO requires nested:true + subagentToolkit:"full" + a depth
budget > 1 (or unbounded -1), reusing the exact predicate shape from
bin/install.js _normalizeDispatchCallSpan and matching degradationFor's
treatment of maxDepth===1 as flat. Non-finite/missing maxDepth fails closed to
flatten. Correct the two existing pins that asserted the buggy output (bare
{bg,bgDispatch} now fail-closes on missing depth; the codex-like maxDepth:1 pin
flips to flatten) and add a maxDepth:2 negative-space row.

* fix(#2939): propagate depth-aware flatten to all pinned descriptors + tests

The isolated adversarial review found the depth-aware predicate reclassifies
codex/kimi/kimi-code (previously background-eligible under the two-field rule)
to flatten — the correct behavior, since each lacks what a backgrounded nesting
orchestrator needs:

  - codex: maxDepth:1 (no room for a depth-2 leaf)
  - kimi: nested:false (cannot host a nesting orchestrator)
  - kimi-code: subagentToolkit:'built-in-only' (cannot delegate to full subagents)

Only cursor (maxDepth:2) remains background-eligible. Update the three test
files that pinned the old contract (host-integration-descriptors EXPECTED_FLATTEN,
kimi-upgrades UPGRADE 2, trae-imperative-reference), and align the unbounded
convention to maxDepth < 0 (matching degradationFor/negotiateHostCapabilities)
with an accurate docstring noting the deliberate nested-check addition over
_normalizeDispatchCallSpan.

* fix(#2939): update dispatch-should-flatten CLI query pins for codex

The depth-aware rule (a0ad0f680) reclassifies codex (maxDepth:1) to flatten, but
command-routing-hub.test.cjs exercises the contract through the CLI query route
(runGsdTools query dispatch-should-flatten), not a direct shouldFlattenDispatch
call — so neither the reviewer's caller-search nor a grep for the symbol found
it; only the full gsd-test matrix did. Update the codex query assertions to
shouldFlatten=true (maxDepth:1 insufficient), preserving cursor (maxDepth:2 →
false) and the backgroundDispatch:true descriptor field.

* chore(#2939): add changeset fragment

pr:0 placeholder backfilled with the real PR number once the PR exists.

* fix(#2939): rephrase changeset for product-name-purity + opencode flatten pin

Two failures from the full gsd-test matrix on the prior sha:

1. product-name-purity: changeset fragments must not include parenthetical product
   descriptions (they render verbatim into CHANGELOG.md). 'Codex (and kimi/kimi-code)'
   tripped it — rephrase to lead with the behavior, naming runtimes inline without
   the parenthetical. lint:ci changeset-lint does not catch this; only the test does.

2. opencode-imperative-reference: the #2087-retraction pin flipped only the two
   background booleans and asserted shouldFlatten:false. Under #2939 that is no
   longer sufficient (opencode lacks nested + full toolkit + depth budget), so the
   retracted axes now correctly flatten — update the pin to true with rationale.

* chore(#2939): backfill changeset PR number 3063

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-04 20:33:50 -04:00
committed by GitHub
parent c547e73a71
commit 83a26ed1dc
9 changed files with 256 additions and 45 deletions

View File

@@ -1693,23 +1693,25 @@ describe('bug-853 — manager/autonomous gate background dispatch by runtime', (
describe('dispatch-should-flatten query — behavioral', () => {
// #853 / #1708: The typed query replaces prose-level RUNTIME===codex checks.
// shouldFlattenDispatch returns false only when both dispatch.background AND
// dispatch.backgroundDispatch are true in the capability registry.
// #2939: shouldFlattenDispatch is now DEPTH-AWARE — a host may background only if it can
// background AND host a nesting orchestrator with a depth budget > 1 (nested:true +
// subagentToolkit:"full" + maxDepth > 1 or unbounded). The two-field background rule is the
// first gate, not the whole decision.
//
// Registry values (from host-integration-capability-matrix.md):
// codex: background=true, backgroundDispatch=true → shouldFlatten=false (may background)
// claude: background=true, backgroundDispatch=false → shouldFlatten=true (must inline)
// cursor: background=true, backgroundDispatch=true → shouldFlatten=false (may background)
// unknown: no entry → fail-closed → shouldFlatten=true (must inline)
// codex: background=true, backgroundDispatch=true, BUT maxDepth:1 → shouldFlatten=true (must inline — #2939: depth budget insufficient for a bg orchestrator + leaf)
// claude: background=true, backgroundDispatch=false → shouldFlatten=true (must inline)
// cursor: background=true, backgroundDispatch=true, maxDepth:2 → shouldFlatten=false (may background — the one shipped host with a sufficient depth budget)
// unknown: no entry → fail-closed → shouldFlatten=true (must inline)
test('runtime=codex → shouldFlatten=false (background dispatch safe)', () => {
test('runtime=codex → shouldFlatten=true (#2939: maxDepth:1 cannot host a bg orchestrator + leaf)', () => {
const tmpDir = createTempProject();
try {
const result = runGsdTools(['query', 'dispatch-should-flatten', '--raw'], tmpDir, {
GSD_RUNTIME: 'codex',
});
assert.ok(result.success, `Expected success, got error: ${result.error}`);
assert.strictEqual(result.output, 'false', `codex should return false (may background), got: ${result.output}`);
assert.strictEqual(result.output, 'true', `#2939: codex maxDepth:1 should return true (must inline), got: ${result.output}`);
} finally {
cleanupDir(tmpDir);
}
@@ -1770,7 +1772,10 @@ describe('dispatch-should-flatten query — behavioral', () => {
assert.fail(`Expected valid JSON output, got: ${result.output}`);
}
assert.strictEqual(parsed.runtime, 'codex');
assert.strictEqual(parsed.shouldFlatten, false);
// #2939: codex maxDepth:1 → shouldFlatten:true (depth budget insufficient). backgroundDispatch
// stays true on the descriptor (codex CAN background a single agent); only the flatten
// consequence changes.
assert.strictEqual(parsed.shouldFlatten, true);
assert.ok(parsed.dispatch !== null && typeof parsed.dispatch === 'object', 'dispatch should be an object');
assert.strictEqual(parsed.dispatch.backgroundDispatch, true);
} finally {
@@ -1797,9 +1802,9 @@ describe('dispatch-should-flatten query — behavioral', () => {
const result = runGsdTools(['query', 'dispatch-should-flatten', '--raw'], tmpDir, {
GSD_RUNTIME: '',
});
// config.runtime=codex with GSD_RUNTIME cleared → codex backgrounds → shouldFlatten=false
// #2939: config.runtime=codex with GSD_RUNTIME cleared → codex maxDepth:1 → shouldFlatten=true (must inline)
assert.ok(result.success, `Expected success, got error: ${result.error}`);
assert.strictEqual(result.output, 'false', `config.runtime=codex (GSD_RUNTIME cleared) should return false (may background), got: ${result.output}`);
assert.strictEqual(result.output, 'true', `#2939: config.runtime=codex (GSD_RUNTIME cleared) should return true (must inline, maxDepth:1), got: ${result.output}`);
} finally {
cleanupDir(tmpDir);
}