fix(server): select an available provider for delegated tasks

[saphid]

Summary

A driver-only delegation target (target.driverKind without providerInstanceId) could fail on an unavailable inherited provider instance even when another instance of that driver was healthy: resolveTarget preferred the parent's instance whenever it was registered and orchestration-capable, and the constraint check then rejected it.

The fix requires the inherited candidate to pass the same providerConstraints availability check as any other candidate before it can win; otherwise the first constraint-free instance of the requested driver is selected. When no healthy candidate exists, resolution falls through to the parent instance id so the constraint check reports why the inherited instance cannot serve. Explicit providerInstanceId selection is unchanged and stays strict — an unavailable explicit target fails instead of silently rerouting.

Adapted from @kiiwee's earlier proposal in #11154 (closed unmerged) onto the live adapter-registry capability lookup from #11578. Credit to kiiwee for identifying the defect and the original fix shape.

Test plan

• Focused regression: vp test run apps/server/src/mcp/OrchestratorMcpService.test.ts — the new table-driven test proves healthy inheritance (parent model selection including options preserved verbatim), unavailable parent + healthy peer fallback, no-available-peer rejection, explicit-unavailable rejection without rerouting, and explicit healthy selection. The fallback case failed before the fix (Provider codex cannot run a child task: Provider instance is disabled.).
• vp test run apps/server/src/mcp/ — all 170 MCP tests pass, including the cross-provider delegation integration test.
• Targeted vp lint, vp fmt --check, and tsc --noEmit clean for the changed scope.

Independent cross-provider review: attempted codex exec -m gpt-6-astra -c model_reasoning_effort="xhigh" --sandbox read-only on the frozen diff; the reviewer account was at its usage limit (reported retry Sep 19), so the review was skipped — disclosed, not substituted.

Targets Orchestrator V2 in #2829.

Engineering: SWE-2 Max through the Devin/T3 harness.
Coordination: T3 thread 3aa91588-f393-4df8-9d47-c8c769d27899, campaign saphid/t3code-personal#298.

[macroscopeapp]

Approvability

Verdict: Approved at 46353a3

Macroscope's review found this PR approvable — This is a narrowly scoped provider-resolution bug fix: unavailable inherited instances now fall back to healthy peers, with explicit targets remaining strict. The production change is small and covered by focused regression tests, while the documentation is updated consistently.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate bcf5ec8

Dismissing prior approval to re-evaluate f13b647

[macroscopeapp]

This returned MCP failure now concatenates every provider constraint, including raw provider.unavailableReason / provider.message, without any length bound. Those strings may contain arbitrary provider diagnostics or sensitive data. Keep the caller-visible error normalized and bounded; the provider details can remain available through a separately sanitized diagnostic path.

Suggested change

	if (instanceId === undefined) {
	const reasons = candidates.flatMap((candidate) =>
	providerConstraints(candidate, true).map(
	(constraint) => `${candidate.instanceId}: ${constraint}`,
	),
	);
	return yield* failure(
	"provider_unavailable",
	`No available V2 provider instance for driver ${requestedDriver}: ${reasons.join(" ")}`,
	);
	}
	if (instanceId === undefined) {
	return yield* failure(
	"provider_unavailable",
	`No available V2 provider instance for driver ${requestedDriver}.`,
	);
	}

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Effect Service Conventions found 1 issue: the new provider-unavailable failure exposes unbounded, potentially sensitive provider diagnostics. See the inline review comment for the suggested fix.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

All clear

^{Posted via Macroscope — Effect Service Conventions}

[juliusmarminge]

Rebased onto t3code/codex-turn-mapping at 9d6feae1ff. All seven commits applied cleanly with no conflicts.

One follow-up commit on top (46353a3d7c):

• Dropped the replay-fixture worktreePath plumbing. The three fixture commits (declare replay fixture workspaces as thread worktrees, the exactOptionalPropertyTypes fix, and declare fixture worktrees only for rollback scenarios) worked around a rollback rejection that v2 has since fixed at the source with restoreFiles: false in testkit/fixtures/shared.ts. OrchestratorReplayFixtures.integration.test.ts and fixtures/shared.ts are back to their v2 versions; the net diff is now the 13-line change in OrchestratorMcpService.ts, its test, and the doc paragraph.
• Test fix. The new delegation test mocked ThreadManagementService.getThreadProjection, but OrchestratorMcpService.loadProjection on v2 calls getThreadRecords, so it failed with UnimplementedError. Pointed the mock at the right method, matching the other cases in that file.
• The test was already one table-driven loop over six scenarios, so there was nothing to fold.

Verified in apps/server: vp test run src/mcp/OrchestratorMcpService.test.ts (9 passed), vp test run src/orchestration-v2/testkit/OrchestratorReplayFixtures.integration.test.ts (73 passed, no hangs without the fixture worktree branch), and vpr typecheck (clean).

Rebased and touched up by a maintainer's agent; a human will re-review.