pi-crew 0.9.59 → 0.9.60

package/docs/commands-reference.md

@@ -190,6 +190,11 @@ Keeps the 20 most recent runs and deletes the rest.
 | `runtime.groupJoinAckTimeoutMs` | number | `300000` | Group join ack timeout (ms) |
 | `runtime.requirePlanApproval` | boolean | `false` | Require approving the plan before execution |
 | `runtime.completionMutationGuard` | string | `"warn"` | `off`, `warn`, `fail` |
+| `runtime.modelFallback.maxAutoFallbacks` | number | — | Cap auto-appended fallback models (default: unbounded) |
+| `runtime.modelFallback.order` | string | `"parentFirst"` | `parentFirst` (same provider first) or `asIs` (catalogue order) |
+| `runtime.modelFallback.requireCredentials` | boolean | `false` | Drop models whose provider has no discoverable credential |
+| `runtime.modelFallback.quotaAwareOrdering` | boolean | `true` | Deprioritize providers near rate-limit/quota |
+| `runtime.modelFallback.defaultSubagentModel` | string | — | Default model when neither caller nor agent specifies one |
 | `limits.maxConcurrentWorkers` | number | `1024` | Max workers running in parallel |
 | `limits.maxTaskDepth` | number | `100` | Max task tree depth |
 | `limits.maxChildrenPerTask` | number | — | Max children per task |

package/docs/resource-formats.md

@@ -81,9 +81,15 @@ category: implementation
 Role line:
 
 ```text
-- {role-name}: agent={agent-name} [model={provider/model}] [skills={a,b}|false] [maxConcurrency={n}] optional description
+- {role-name}: agent={agent-name} [model={provider/model}] [fallbackModels={a,b}] [thinking={level}] [skills={a,b}|false] [maxConcurrency={n}] optional description
 ```
 
+- `model` — primary model for this role (e.g. `openai/gpt-5`, `anthropic/claude-sonnet-4-5`)
+- `fallbackModels` — comma-separated fallback models tried in order when the primary fails (e.g. `fallbackModels=openai/gpt-5-mini,anthropic/claude-haiku-4-5`)
+- `thinking` — thinking level override for this role (`high`, `medium`, `low`, `off`)
+- `skills` — additional skills to inject, or `false` to disable role-default skills
+- `maxConcurrency` — max parallel tasks for this role
+
 ## Workflow files
 
 Location:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.59",
+  "version": "0.9.60",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/skills/real-test-pi-crew/REPORT-TEMPLATE.md

@@ -0,0 +1,52 @@
+# real-test-pi-crew — Run Report
+
+<!--
+TEMPLATE — copy this file to docs/real-test/reports/real-test-<YYYY-MM-DD>-<slug>.md
+and fill it in DURING the run (not from memory afterward). Every tier gets a
+row with concrete evidence (counts, md5, runIds, wall-clock). If a tier was
+skipped or incomplete, say so explicitly — do NOT claim "pass" without evidence.
+This artifact exists so past runs are verifiable (see SKILL.md "Output report").
+-->
+
+**Date**: YYYY-MM-DD
+**Trigger**: <what prompted this real-test — e.g. "post subagent-model-routing merge 4148540e", "pre-release v0.9.X">
+**Repo HEAD**: `<sha>`
+**Bundle md5 (disk)**: `<md5>`
+**Pi version**: <from `pi --version` or doctor>
+**Run by**: <agent/user>
+
+## Tier results
+
+| Tier | Status | Evidence |
+|---|---|---|
+| 1 test:critical | ✅/❌/⏭️ | `<pass>/<tests>` pass, `<dur>` |
+| 2 3-path kill-switch | ✅/❌/⏭️ | default + `PI_CREW_BROKER=0` + `=1` all `<n>/<n>` |
+| 3 typecheck + bundle | ✅/❌/⏭️ | tsc exit 0; bundle `<KB>` KB, md5 `<md5>` |
+| 4 bundle md5 sync | ✅/❌/⏭️ | disk = loaded = `<md5>` (or: user must restart) |
+| 5 tmux TUI probe | ✅/❌/⏭️ | `<which slash command reached the screen>` |
+| 6 pty probe | ✅/❌/⏭️ | `<keys reached handleInput / diag lines>` |
+| 7 smoke team run | ✅/❌/⏭️ | runId `<id>`, `<n>/<n>` tasks, verifier `<dur>` (<300s) |
+| 8 final md5 sync | ✅/❌/⏭️ | disk = session = `<md5>` |
+| 9a read-only battery | ✅/❌/⏭️ | list/recommend/health/doctor/status/events/summary/get/explain/worktrees — `<n>/10` |
+| 9b spawn paths | ✅/❌/⏭️ | sync / async / chain / Agent / crew_agent — `<n>/5` |
+| 9c lifecycle | ✅/❌/⏭️ | status-details/cache/checkpoint/steer/retry/resume + live cancel — which ran |
+| 9d destructive | ✅/❌/⏭️ | forget/cleanup/prune — which ran (note data-protection skips) |
+| 9e admin | ✅/❌/⏭️ | team/workflow CRUD round-trip |
+| 9f background | ✅/❌/⏭️ | auto-summarize/anchor/schedule register+remove |
+
+Legend: ✅ pass with evidence · ❌ fail (root cause below) · ⏭️ skipped (justify why)
+
+## Findings (bugs / quirks / non-blocking notes)
+- <finding 1 — file:line, severity, issue link if filed>
+- <finding 2>
+
+## What was NOT run + why
+- <e.g. "prune — protects user run data; handler proven via forget">
+- <e.g. "live mid-run steer race — async tool call blocks; live cancel implicitly verified via …">
+
+## Restart needed?
+- [ ] No — session already on the new bundle
+- [ ] Yes — user must `/quit` + reopen; md5 before/after: `<old>` → `<new>`
+
+## Verdict
+<one line: e.g. "All required tiers pass; feature safe to ship. Issue #NN tracks <quirk>.">

package/skills/real-test-pi-crew/SKILL.md

@@ -17,7 +17,6 @@ triggers:
   - "worker timeout"
   - "verifier hangs"
   - "rebuild and retry"
-  - "unknown type" tool error
   - "validation failed for tool"
   - "team tool broken"
   - "schema fix"
@@ -448,7 +447,7 @@ If the two md5s match → session is on the latest code. If not → user must `/
 2. **9b. Spawn paths** (cost tokens — one probe each is enough):
    - `team action='run'` sync (fast-fix, trivial goal) — proves sync run + child-pi spawn + provider-extension loading
    - `team action='run' async=true` — proves background dispatch
-   - `team action='run' chain='"A" -> "B"'` — proves sequential handoff (chain runner)
+   - `team action='run' chain='"A" -> "B"'` — proves sequential handoff (chain runner). **Omit `workflow`** — passing `workflow:'chain'` forwards it to each step and fails fast (~58ms silent; issue #44).
    - `Agent` direct subagent — proves the direct-subagent tool
    - `crew_agent` `run_in_background=true` then `get_subagent_result` — proves background subagent lifecycle
 3. **Acceptance**: every action returns without `Unknown type` / `Validation failed for tool team` / empty error text; every spawn path completes with `consistency=1` and the expected probe token in the agent output.
@@ -511,6 +510,8 @@ If the two md5s match → session is on the latest code. If not → user must `/
 | Trusting a team-run agent not to edit the repo under test | Agents spawned by `team`/`Agent`/`crew_agent` inherit the session cwd and have `edit`/`write` tools — a proactive LLM (observed with deepseek) will make **unauthorized source edits** to pi-crew during a trivial smoke run (e.g. "improving" `chain-runner.ts` while parsing a chain string). The edit can be correct + green-tested yet still be unintended scope creep that silently lands in your commit. | n/a (permanent) | After EVERY team/subagent run: `git status` and verify each changed file was authored by you. Diff + review any surprise change before staging. Consider `workspaceMode: 'worktree'` for parallel/risky runs to isolate mutations. |
 | `Type.Unsafe({ anyOf/type })` schema field **without** `[TypeBox.Kind]` symbol | `Value.Check` throws `Unknown type` the first time a model emits that field (e.g. `skill`, `config`) — every team action returns `isError:true` text `"Unknown type"`. Tier 1-8 stay green because unit tests never send the offending field. | v0.9.57 | `src/schema/team-tool-schema.ts` — `SkillOverride`/`FreeformConfig` switched from `Type.Unsafe` to TypeBox-native `Type.Union`/`Type.Record`. See Tier 9. |
 | Schema too strict for model-emitted empty strings (`runId:""`, `workspaceMode:""`, `budgetTotal:0`) | pi-ai `validateToolArguments` runs BEFORE the pi-crew handler and rejects `""` against Literal unions / patterns → `Validation failed for tool team` → model loops. | v0.9.57 | `src/schema/team-tool-schema.ts` — added `Literal("")` to unions, `^$|` pattern for runId, `""` to action enum, `0`/Boolean allowances. Handler-side `normalizeTeamParams` drops the empties. |
+| Claiming "all 9 tiers pass" while 9c–9f were never run | Overclaim — once reported "9 tiers pass" when only 9a (8/10) + 9b (4/5) had actually run; 9c–9f were skipped. Past runs then become unverifiable ("did it really pass 9 tiers?"). | n/a (process) | Fill `REPORT-TEMPLATE.md` per-tier DURING the run. "Tier 9 pass" = 9a AND 9b AND the applicable 9c–9f, each with evidence. Round-up-to-pass is the anti-pattern this row exists to prevent. |
+| chain run with `workflow:"chain"` forwarded to steps | Every chain step fails in ~58ms with an EMPTY error string — looks like a parse failure but isn't. `chain-dispatch` forwards `params.workflow` ("chain") into executor overrides; each step then runs the "chain" workflow via the normal `executeTeamRun` path and fails fast + silently. | Open (issue #44) | Omit `workflow` when invoking `action:'run' chain=...` — chain then runs 2/2 success (~308s). See `docs/bugs/chain-workflow-forward-quirk.md`. |
 
 ---
 
@@ -686,7 +687,7 @@ md5sum "$(npm root -g)"/pi-crew/dist/index.mjs 2>/dev/null \
 
 Before claiming "tested":
 
-- [ ] Tier 1: `test:critical` fresh-run, 97/97 pass, ~21s
+- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, 101 after the model-routing merge; record the actual count in the report.
 - [ ] Tier 2: 3-path proof all pass — **required if you touched `src/config/defaults.ts` or `src/extension/registration/lifecycle-handlers.ts`**
 - [ ] Tier 3: `npm run typecheck` exit 0, `npm run build:bundle` exit 0
 - [ ] Tier 4: bundle md5 matches what the session loaded (or user has `/quit`-ed + reopened)
@@ -694,8 +695,9 @@ Before claiming "tested":
 - [ ] Tier 7: smoke team run for any `src/runtime/plan-templates.ts` or `workflows/*.workflow.md` change — completed, no hang, verifier output under 60s
 - [ ] Tier 8: final md5 sync check passed
 - [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, or any `Type.Unsafe({...})` schema**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
+- [ ] **Output report**: save `docs/real-test/reports/real-test-<YYYY-MM-DD>-<slug>.md` from `skills/real-test-pi-crew/REPORT-TEMPLATE.md`, filled DURING the run with per-tier evidence (counts/md5/runId) — not reconstructed from memory afterward. This is what makes past runs verifiable instead of trust-the-summary.
 
-If any required item is unchecked, the answer to "is it tested?" is **no**.
+**"All 9 tiers pass" is a claim that needs per-row evidence.** Tier 9 means 9a **and** 9b **and** whichever of 9c–9f applies to the change — not "9a passed, therefore 9 passed". If any required item above is unchecked or lacks concrete evidence (a number, an md5, a runId), the answer to "is it tested?" is **no** — say so explicitly instead of rounding up to "pass".
 
 ---
 

package/src/config/types.ts

@@ -85,6 +85,35 @@ export interface CrewRuntimeConfig {
 	};
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens. Default: false */
 	excludeContextBash?: boolean;
+	/** Subagent model fallback policy: auto-tail ordering, cap, credential filtering, default model. */
+	modelFallback?: CrewModelFallbackConfig;
+}
+
+/**
+ * Model fallback policy for subagent model chains. Controls how the auto-tail
+ * (models appended from the registry/pi-config that nobody explicitly declared)
+ * is ordered, capped, and filtered. Explicit declarations (tool override, step
+ * model, team role, agent model, declared fallbackModels) are never affected.
+ */
+export interface CrewModelFallbackConfig {
+	/** Cap on auto-appended models. undefined = keep all (legacy). */
+	maxAutoFallbacks?: number;
+	/** "parentFirst" keeps the auto tail on the same provider as the running model when a policy is configured or quota data enriches it. "asIs" = catalogue order. Without explicit configuration, auto tail stays catalogue order. */
+	order?: "parentFirst" | "asIs";
+	/** Drop pi-config models whose provider has no discoverable credential. Default: false. */
+	requireCredentials?: boolean;
+	/**
+	 * Opt-in quota-aware ordering. When true, provider quota data (when available)
+	 * influences the auto-tail order — providers near their quota limit are deprioritized.
+	 * Default: true (default-on with cache, per user preference).
+	 */
+	quotaAwareOrdering?: boolean;
+	/**
+	 * Default model for subagents when neither the caller (--model) nor the agent
+	 * frontmatter specifies one. Accepts "provider/id" or bare id. Overrides
+	 * parent-model inheritance; the inherited parent model becomes the first fallback.
+	 */
+	defaultSubagentModel?: string;
 }
 
 export interface CrewControlConfig {

package/src/extension/registration/lifecycle-handlers.ts

@@ -25,7 +25,10 @@ import { CrewBroker } from "../../runtime/broker/crew-broker.ts";
 import { terminateActiveChildPiProcesses } from "../../runtime/child-pi/child-pi.ts";
 import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
+import { providerOfModelRef } from "../../runtime/model/model-fallback.ts";
 import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth } from "../../runtime/model/pi-args.ts";
+import { clearProviderQuotaCache, noteProviderResponse } from "../../runtime/model/provider-quota.ts";
+import { currentSessionModel, noteSessionModel, noteSessionThinking } from "../../runtime/model/session-model.ts";
 import { cleanupOrphanWorkers } from "../../runtime/orphan-worker-registry.ts";
 import { reconcileAllStaleRuns } from "../../runtime/recovery/crash-recovery.ts";
 import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduling/scheduler.ts";
@@ -68,6 +71,32 @@ export function installSessionLifecycleHandlers(pi: ExtensionAPI, ctx: Registrat
 	installSessionShutdownHandler(pi, ctx);
 	installSessionStartHandler(pi, ctx);
 	installSessionBeforeSwitchHandler(pi, ctx);
+	installModelTrackingHandlers(pi);
+}
+
+/**
+ * model_select / thinking_level_select:
+ *   Track what the MAIN session is *actually* running so subagents that
+ *   inherit the parent model (`model: false` — every builtin agent) follow it.
+ *   `ctx.model` alone is the session's saved model and can point at whatever a
+ *   previous session persisted, which made inherited models jump around.
+ */
+function installModelTrackingHandlers(pi: ExtensionAPI): void {
+	pi.on("model_select", (event) => {
+		noteSessionModel(event.model);
+	});
+	pi.on("thinking_level_select", (event) => {
+		noteSessionThinking(event.level);
+	});
+	// Quota-aware routing: capture rate-limit headers from the main session's
+	// provider responses so the fallback chain can deprioritize exhausted
+	// providers. The event doesn't carry a provider field, so we attribute it
+	// to the currently tracked session model's provider.
+	pi.on("after_provider_response", (event) => {
+		const model = currentSessionModel();
+		const provider = model ? providerOfModelRef(model) : undefined;
+		if (provider) noteProviderResponse(provider, event.status, event.headers);
+	});
 }
 
 /**
@@ -117,6 +146,7 @@ function installSessionBeforeSwitchHandler(pi: ExtensionAPI, ctx: RegistrationCo
 		ctx.lifecycleState.deliveryCoordinator?.deactivate();
 		resetPowerbarDedupState();
 		stopAsyncRunNotifier(ctx.notifierState);
+		clearProviderQuotaCache();
 		ctx.stopSessionBoundSubagents();
 	});
 }
@@ -160,6 +190,9 @@ function installSessionStartHandler(pi: ExtensionAPI, ctx: RegistrationContext):
 		ctx.sessionGeneration++;
 		const ownerGeneration = ctx.sessionGeneration;
 		ctx.currentCtx = extensionCtx;
+		// Seed the live-model tracker; a later model_select overrides it.
+		noteSessionModel(extensionCtx.model, "session_start");
+		noteSessionThinking(extensionCtx.thinkingLevel);
 		// Round 13 UX: register the crew natural-language autocomplete provider
 		// once we have a UI context. Guarded so repeated session_start events
 		// don't stack wrappers (each wrapper delegates, but stacking wastes

package/src/extension/team-tool/chain-dispatch.ts

@@ -36,6 +36,18 @@ export async function handleChainRun(params: TeamToolParamsValue, ctx: TeamConte
 		return result("Chain expression is empty.", { action: "run", status: "error" }, true);
 	}
 
+	// BUG-44 (github #44): reject an explicit `workflow: "chain"` on a chain run with a
+	// clear message. `chain` is a dispatcher-only workflow; forwarding it to steps made
+	// every step fail fast (~58 ms) with a confusing empty error. Chain runs have no
+	// per-step workflow — omit `workflow` (or rely on the step's @team ref) instead.
+	if (params.workflow === "chain") {
+		return result(
+			"Workflow 'chain' cannot be combined with a chain run: the chain runner owns step execution and has no per-step workflow. Omit `workflow` (steps use the team's defaultWorkflow) or use @team references in the chain expression.",
+			{ action: "run", status: "error" },
+			true,
+		);
+	}
+
 	const spec = parseChainString(chainString);
 	if (spec.steps.length === 0) {
 		return result(
@@ -47,13 +59,19 @@ export async function handleChainRun(params: TeamToolParamsValue, ctx: TeamConte
 
 	// Construct the concrete executor with per-step overrides forwarded from the
 	// chain invocation (overridden by any step that parsed to a @team reference).
+	//
+	// BUG-44 (github #44): `workflow` is INTENTIONALLY NOT forwarded. The chain
+	// runner owns step execution — a chain has no per-step workflow. Forwarding
+	// params.workflow (e.g. "chain") made every step execute the `chain` workflow
+	// via the normal executeTeamRun path, which fails fast (~58 ms) with a
+	// confusing empty error. Steps use the team's defaultWorkflow instead.
 	const executor = new ChainTeamRunExecutor({
 		handleRun,
 		ctx,
 		overrides: {
 			team: params.team,
-			workflow: params.workflow,
-			model: params.model,
+			// workflow intentionally omitted — chain runner owns step execution (bug-44)
+			...(params.model ? { model: params.model } : {}),
 		},
 	});
 

package/src/extension/team-tool/chain-executor.ts

@@ -238,8 +238,13 @@ export class ChainTeamRunExecutor implements ChainTaskRunner {
 		const enrichedGoal = historyPrefix ? `${historyPrefix}\n\n---\n# Current Chain Step\n${packet.goal}` : packet.goal;
 
 		// 2. Resolve team/workflow/model: step config (set by executeStep) → overrides → default.
+		//    BUG-44 (github #44): a workflow override of "chain" is a dispatcher-only marker
+		//    (the chain runner owns step execution). If it leaks through here (e.g. an older
+		//    caller forwarded params.workflow), drop it so each step runs the team's
+		//    defaultWorkflow instead of re-entering the un-runnable `chain` workflow.
 		const stepTeam = (context.__chainStepTeam as string | undefined) ?? this.overrides.team ?? "default";
-		const stepWorkflow = (context.__chainStepWorkflow as string | undefined) ?? this.overrides.workflow;
+		const rawWorkflow = (context.__chainStepWorkflow as string | undefined) ?? this.overrides.workflow;
+		const stepWorkflow = rawWorkflow === "chain" ? undefined : rawWorkflow;
 		const stepModel = (context.__chainStepModel as string | undefined) ?? this.overrides.model;
 
 		// 3. Call handleRun for the heavy lifting. async:false forces each step to

package/src/extension/team-tool/doctor.ts

@@ -5,7 +5,9 @@ import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
 import { loadConfig } from "../../config/config.ts";
 import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import { type DriftReport, detectDrift, formatDriftReport } from "../../config/drift-detector.ts";
+import { buildConfiguredModelRouting, resolveModelFallbackPolicy } from "../../runtime/model/model-fallback.ts";
 import { getRuntimeWarmupStatus } from "../../runtime/model/runtime-warmup.ts";
+import { currentSessionModel, sessionModelSnapshot } from "../../runtime/model/session-model.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
 import { formatZombieReport, scanZombieSubagents } from "../../runtime/process/zombie-scanner.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
@@ -235,6 +237,47 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 				},
 			];
 		}),
+		section("Model Routing", () => {
+			const snapshot = sessionModelSnapshot();
+			const liveModel = currentSessionModel();
+			const policy = resolveModelFallbackPolicy(loadConfig(input.cwd).config.runtime?.modelFallback);
+			// Build a sample chain for a generic agent (no explicit model) to show
+			// what the auto tail looks like with the current config.
+			const sampleRouting = buildConfiguredModelRouting({
+				parentModel: liveModel,
+				cwd: input.cwd,
+				policy,
+			});
+			return [
+				{
+					label: "session model (live)",
+					ok: true,
+					detail: liveModel ?? "not tracked yet",
+				},
+				{
+					label: "session model (source)",
+					ok: true,
+					detail: `${snapshot.source}${snapshot.updatedAt ? ` @ ${new Date(snapshot.updatedAt).toISOString()}` : ""}`,
+				},
+				{
+					label: "fallback policy",
+					ok: true,
+					detail: policy
+						? `maxAuto=${policy.maxAutoFallbacks ?? "∞"} order=${policy.order ?? "parentFirst"} creds=${policy.requireCredentials ?? false} quota=${policy.quotaAwareOrdering ?? true}`
+						: "legacy (unbounded, unordered)",
+				},
+				{
+					label: "sample chain (no explicit model)",
+					ok: true,
+					detail: sampleRouting.candidates.length > 0 ? sampleRouting.candidates.join(" → ") : "(empty)",
+				},
+				{
+					label: "auto tail size",
+					ok: true,
+					detail: `${sampleRouting.autoFallbackCount ?? 0} models`,
+				},
+			];
+		}),
 		section("Discovery", () => {
 			const agentModelHints = discoveredAgentsAll.filter((agent) => agent.model || agent.fallbackModels?.length).length;
 			return [

package/src/extension/team-tool/run.ts

@@ -32,6 +32,7 @@ async function executeTeamRun(...args: Parameters<typeof ExecuteTeamRunFn>): Pro
 
 import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
 import { resolveCrewRuntime, runtimeResolutionState } from "../../runtime/model/runtime-resolver.ts";
+import { captureRunModelContext, resolveParentModel } from "../../runtime/model/session-model.ts";
 import { appendEventAsync, readEventsCursor } from "../../state/event-log/event-log.ts";
 import type { RunMetrics } from "../../state/stores/run-metrics.ts";
 import type { RuntimeResolutionState, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
@@ -478,7 +479,18 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 			}
 		: teams.find((item) => item.name === teamName);
 	if (!team) return result(`Team '${teamName}' not found.`, { action: "run", status: "error" }, true);
-	const workflowName = directAgent ? "direct-agent" : (params.workflow ?? team.defaultWorkflow ?? "default");
+	// BUG-44 (github #44): `chain` is a dispatcher-only workflow — the chain runner owns
+	// step execution, so it is never runnable via the normal executeTeamRun path (its
+	// .workflow.md parses to doc headings, and validation fails fast with a confusing
+	// error). If a caller (or a chain step forwarding params.workflow) asks for
+	// workflow='chain' WITHOUT a chain param, fall back to the team's default workflow
+	// instead of failing. Chain steps are the only realistic producers of this state;
+	// handleChainRun itself routes via params.chain before reaching here.
+	const workflowName = directAgent
+		? "direct-agent"
+		: params.workflow === "chain" && !params.chain
+			? (team.defaultWorkflow ?? "default")
+			: (params.workflow ?? team.defaultWorkflow ?? "default");
 	const baseWorkflow = directAgent
 		? {
 				name: "direct-agent",
@@ -752,6 +764,10 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		...updatedManifest,
 		runtimeResolution,
 		runConfig: executedConfig,
+		// Background/async runs re-enter through background-runner in a detached
+		// process with no ExtensionContext. Snapshot the model routing inputs so
+		// they survive the hand-off instead of being rediscovered from models.json.
+		modelContext: captureRunModelContext(ctx, params.model),
 		// Persist budget config on the manifest so it's observable post-run
 		// (events.jsonl, status reads, audits). The team-runner reads these
 		// from the input, but persisting them means consumers can verify
@@ -975,7 +991,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 					runtimeConfig: executedConfig.runtime,
 					parentContext: buildParentContext(ctx),
 
-					parentModel: ctx.model,
+					parentModel: resolveParentModel(ctx.model),
 					modelRegistry: ctx.modelRegistry,
 					modelOverride: params.model,
 					skillOverride,
@@ -1048,7 +1064,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 			runtime,
 			runtimeConfig: executedConfig.runtime,
 			parentContext: buildParentContext(ctx),
-			parentModel: ctx.model,
+			parentModel: resolveParentModel(ctx.model),
 			modelRegistry: ctx.modelRegistry,
 			modelOverride: params.model,
 			skillOverride,

package/src/extension/team-tool.ts

@@ -33,6 +33,7 @@ async function executeTeamRun(...args: Parameters<ExecuteTeamRunFn>): Promise<Aw
 
 import { directTeamAndWorkflowFromRun } from "../runtime/direct-run.ts";
 import { resolveCrewRuntime, runtimeResolutionState } from "../runtime/model/runtime-resolver.ts";
+import { resolveParentModel } from "../runtime/model/session-model.ts";
 import { parsePiJsonOutput } from "../runtime/output/pi-json-output.ts";
 import { effectiveRunConfig } from "./team-tool/config-patch.ts";
 import { buildParentContext, formatScoped, result, type TeamContext } from "./team-tool/context.ts";
@@ -497,7 +498,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		runtime: decision.runtime,
 		runtimeConfig: decision.executedConfig.runtime,
 		parentContext: buildParentContext(ctx),
-		parentModel: ctx.model,
+		parentModel: resolveParentModel(ctx.model),
 		modelRegistry: ctx.modelRegistry,
 		modelOverride: params.model,
 		skillOverride: decision.resumeSkillOverride,

package/src/runtime/background-runner.ts

@@ -48,6 +48,7 @@ import { writeAsyncStartMarker } from "./async-marker.ts";
 import { terminateActiveChildPiProcesses } from "./child-pi/child-pi.ts";
 import { directTeamAndWorkflowFromRun } from "./direct-run.ts";
 import { resolveCrewRuntime, runtimeResolutionState } from "./model/runtime-resolver.ts";
+import { registryFromModelContext } from "./model/session-model.ts";
 import { unregisterWorker } from "./orphan-worker-registry.ts";
 import { startParentGuard, stopParentGuard } from "./parent-guard.ts";
 import { expandParallelResearchWorkflow } from "./scheduling/parallel-research.ts";
@@ -61,6 +62,26 @@ function debugLog(message: string): void {
 	if (process.env.PI_CREW_DEBUG) console.log(message);
 }
 
+/**
+ * Re-hydrate the model routing inputs a detached background run cannot obtain
+ * from an ExtensionContext. Absent `modelContext` (older manifests) yields an
+ * empty object, preserving previous behaviour exactly.
+ */
+function restoredModelRouting(manifest: TeamRunManifest): {
+	modelOverride?: string;
+	parentModel?: string;
+	modelRegistry?: { getAvailable: () => unknown[] };
+} {
+	const context = manifest.modelContext;
+	if (!context) return {};
+	const modelRegistry = registryFromModelContext(context);
+	return {
+		...(context.override ? { modelOverride: context.override } : {}),
+		...(context.parentModel ? { parentModel: context.parentModel } : {}),
+		...(modelRegistry ? { modelRegistry } : {}),
+	};
+}
+
 /**
  * Heartbeat mechanism: periodically write a heartbeat file so the stale reconciler
  * can distinguish "process died" from "process still alive but quiet".
@@ -825,6 +846,11 @@ async function main(): Promise<void> {
 							runtime,
 							runtimeConfig: runConfig.runtime,
 							skillOverride: manifest.skillOverride,
+							// Restore the caller's model routing inputs (see RunModelContext):
+							// this process has no ExtensionContext, so without these the
+							// `model=` override and the inherited session model are lost and
+							// every worker falls back to the first models.json entry.
+							...restoredModelRouting(manifest),
 							reliability: runConfig.reliability,
 							workspaceId: manifest.ownerSessionId ?? manifest.cwd,
 							signal: abortController.signal,

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -252,6 +252,7 @@ export function prepareSpawnContext(
 		maxDepth: input.maxDepth,
 		skillPaths: input.skillPaths,
 		role: input.role,
+		thinkingOverride: input.thinkingOverride,
 	});
 	// Pass steering file path to child for real-time steer injection
 	if (input.steeringFile) built.env.PI_CREW_STEERING_FILE = input.steeringFile;

package/src/runtime/child-pi/child-pi.ts

@@ -143,6 +143,8 @@ export interface ChildPiRunInput {
 	agentId?: string;
 	/** Role for tool restrictions (from role-tools.ts) */
 	role?: string;
+	/** Team-role thinking override (takes precedence over agent.thinking). */
+	thinkingOverride?: string;
 	/** Root directory for artifacts (used to validate transcriptPath). */
 	artifactsRoot?: string;
 	/**