@getpipher/armory-fleet 0.12.4 → 0.12.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "private": false,
   "description": "The armory suite's subagent orchestrator for the pi coding agent — a cross-harness, superpowers-native fleet where every agent is armory-native from birth.",
   "license": "MIT",

package/src/engine/child-loader.ts

@@ -3,7 +3,9 @@
 // noExtensions (deterministic child, no host-extension leakage), composed
 // systemPromptOverride (rolePrompt + memoryBlock + base), scoped skills.
 import { DefaultResourceLoader, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync as fsExistsSync } from "node:fs";
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { MemoryHydratePort } from "../memory-hydrate/port.ts";
 
@@ -44,6 +46,25 @@ export function memoryScopesFor(cwd: string): { project: string; local: string;
   return { project: cwd, local: dirname(cwd) || cwd, user: USER_PSEUDO_CWD };
 }
 
+/** #40: resolve extra skill dirs to scan for the child, beyond the default `~/.pi/agent/skills`.
+ *
+ *  The parent's pi package-manager scans `~/.agents/skills` (user) + `<cwd>/.agents/skills`
+ *  (project) and feeds them to the loader via `extendResources` — that's how cross-harness skills
+ *  like firecrawl (which live in `~/.agents/skills`, NOT `~/.pi/agent/skills`) reach the parent.
+ *  The child's bare `DefaultResourceLoader` skips that, so a `skills: ["firecrawl-scrape"]` opt-in
+ *  can't resolve. We restore the parent's skill surface by passing these dirs as `additionalSkillPaths`.
+ *
+ *  Returns absolute paths only for dirs that exist (no hard dependency on the `~/.agents` layout —
+ *  machines without it get []). Inject `homedir`/`cwd`/`existsSync` for testability. */
+export function resolveAdditionalSkillPaths(opts: { homedir?: string; cwd: string; existsSync?: (p: string) => boolean }): string[] {
+  const home = opts.homedir ?? homedir();
+  const exists = opts.existsSync ?? ((p: string) => { try { return fsExistsSync(p); } catch { return false; } });
+  const candidates = [join(home, ".agents", "skills"), join(opts.cwd, ".agents", "skills")];
+  const out: string[] = [];
+  for (const p of candidates) if (!out.includes(p) && exists(p)) out.push(p);
+  return out;
+}
+
 export interface ChildLoaderOpts {
   cwd: string;
   agent: AgentDef;
@@ -58,6 +79,9 @@ export function buildChildLoader(opts: ChildLoaderOpts): DefaultResourceLoader {
     cwd: opts.cwd,
     agentDir: getAgentDir(),
     noExtensions: true,
+    // #40: scan the shared `~/.agents/skills` + `<cwd>/.agents/skills` dirs so cross-harness skills
+    //  (firecrawl, etc.) are discoverable by a caller's `skills` opt-in, matching the parent surface.
+    additionalSkillPaths: resolveAdditionalSkillPaths({ cwd: opts.cwd }),
     systemPromptOverride: (base) =>
       composeChildPrompt({ rolePrompt: opts.agent.rolePrompt, memoryBlock, base: base ?? "" }),
     skillsOverride: (cur) => resolveChildSkills(opts.agent, cur),

package/src/engine/concurrency-lock.ts

@@ -1,29 +1,81 @@
 // src/engine/concurrency-lock.ts
-export interface SingleSlotLock {
-  /** true if acquired; false if busy (call .current() for the running id). */
-  tryAcquire(id: string): boolean;
-  release(): void;
-  current(): string | null;
+// #31 tail: the foreground concurrency lock. A cap-based semaphore shared across all
+// foreground subagent dispatches (serializes writes to prevent in-place edit conflicts).
+//
+// - cap=1 (default, backward-compat): FAIL-FAST. A 2nd dispatch while one is running is
+//   rejected with `{ ok: false, busy }` so the orchestrator gets an actionable error (the
+//   held runId is named) instead of blocking. This preserves the pre-#31 behavior exactly.
+// - cap>1 (opt-in via ARMORY_FLEET_FOREGROUND_CONCURRENCY): QUEUE. Up to `cap` write
+//   dispatches run in parallel; the (cap+1)th WAITS for a slot (not rejected).
+//
+// #31 design note: concurrency is SESSION-LEVEL (env/settings), NOT a per-dispatch param.
+// A shared lock serializes across dispatches, so a per-dispatch `concurrency` param can't
+// re-size it per-call (two dispatches requesting different caps have no consistent global
+// cap). The cap is fixed at init. The subagent tool's promptGuidelines surface this to the
+// orchestrator so it understands the behavior + how to change it.
+//
+// readOnly dispatches bypass the lock entirely (#41) — they assert no cwd mutation.
+
+export type AcquireResult =
+  | { ok: true }
+  | { ok: false; busy: string[] };
+
+export interface ForegroundLock {
+  /** The configured cap (1 = fail-fast; >1 = queue). */
+  readonly cap: number;
+  /** Acquire a slot for `runId`. At cap=1: fail-fast if busy (returns the held runIds).
+   *  At cap>1: waits (queues) if at cap, then acquires. */
+  acquire(runId: string): Promise<AcquireResult>;
+  /** Release a held slot. No-op if `runId` isn't held (guard against double-release). */
+  release(runId: string): void;
+  /** RunIds currently holding a slot (for diagnostics + error messages). */
+  holders(): string[];
 }
 
-export class SingleSlotLockImpl implements SingleSlotLock {
-  private holding: string | null = null;
-  tryAcquire(id: string): boolean {
-    if (this.holding !== null) return false;
-    this.holding = id;
-    return true;
-  }
-  release(): void {
-    this.holding = null;
+export class ForegroundLockImpl implements ForegroundLock {
+  private active: string[] = [];
+  private waiters: Array<() => void> = [];
+  constructor(readonly cap = 1) {}
+
+  acquire(runId: string): Promise<AcquireResult> {
+    if (this.active.length >= this.cap) {
+      if (this.cap === 1) {
+        // Backward-compat: fail-fast at cap=1. The orchestrator gets the held runId + the cap
+        // + the env hint, so it can wait/abort or raise the cap.
+        return Promise.resolve({ ok: false, busy: [...this.active] });
+      }
+      // cap>1: queue — resolve when a slot frees (FIFO).
+      return new Promise<AcquireResult>((resolve) => {
+        this.waiters.push(() => { this.active.push(runId); resolve({ ok: true }); });
+      });
+    }
+    this.active.push(runId);
+    return Promise.resolve({ ok: true });
   }
-  current(): string | null {
-    return this.holding;
+
+  release(runId: string): void {
+    const i = this.active.indexOf(runId);
+    if (i < 0) return;   // no-op if not held (don't wake a waiter without freeing a slot)
+    this.active.splice(i, 1);
+    const next = this.waiters.shift();
+    if (next) next();
   }
+
+  holders(): string[] { return [...this.active]; }
 }
 
-/** Alias so tests can `new SingleSlotLock()`. */
-export const SingleSlotLock = SingleSlotLockImpl;
+/** Configurable foreground lock. cap from `ARMORY_FLEET_FOREGROUND_CONCURRENCY` (default 1). */
+export function createForegroundLock(cap = 1): ForegroundLock {
+  return new ForegroundLockImpl(cap);
+}
 
-export function createSingleSlotLock(): SingleSlotLock {
-  return new SingleSlotLock();
+/** Backward-compat factory: a cap=1 fail-fast lock. Existing call sites pass this to
+ *  spawnSubagent; it now returns a ForegroundLock(1) with the same cap=1 semantics. */
+export function createSingleSlotLock(): ForegroundLock {
+  return new ForegroundLockImpl(1);
 }
+
+/** @deprecated alias kept for call sites that construct `new SingleSlotLock()` or type
+ *  `lock: SingleSlotLock` (workflow adapters, fleet-panel). Same as ForegroundLock(1). */
+export type SingleSlotLock = ForegroundLock;
+export const SingleSlotLock = ForegroundLockImpl;

package/src/engine/retry-fallback.ts

@@ -0,0 +1,26 @@
+// src/engine/retry-fallback.ts
+// #39 tail: a reusable retry wrapper for the lifecycle + background spawn sites, where the
+// direct-foreground path's inline retry (subagent.ts) doesn't reach. Mirrors that path's
+// contract: retry ONCE, only on a retryable provider rate-limit / auth failure (stopReason
+// "error" → SpawnResult.retryable), only with a DISTINCT fallback model, only when not aborted.
+// Non-retryable failures (turn budget, agent-not-found, EMPTY_RESULT, abort, lock busy) pass
+// through unchanged. Lifecycle/bg retries are transparent — the retry's SpawnResult (with
+// model = fallback) wins; the direct-foreground path separately surfaces `retriedWithModel`
+// in the tool details, which lifecycle/bg don't need.
+import type { SpawnResult } from "./spawnSubagent.ts";
+import type { SpawnFn } from "../lifecycle/run-lifecycle.ts";
+
+/** Wrap a lifecycle/bg SpawnFn so a retryable failure retries once on `fallback`. `fallback`
+ *  being undefined returns the spawn unchanged (no global default + no per-dispatch param → no
+ *  retry). `signal` optional — background/panel sites have no AbortSignal; the direct path checks
+ *  abort inline. */
+export function withModelFallbackRetry(spawn: SpawnFn, fallback: string | undefined, signal?: AbortSignal): SpawnFn {
+  if (!fallback) return spawn;
+  return async (opts) => {
+    const first = await spawn(opts);
+    if (first.status === "failed" && first.retryable && fallback !== first.model && !signal?.aborted) {
+      return spawn({ ...opts, model: fallback });
+    }
+    return first;
+  };
+}

package/src/engine/spawnSubagent.ts

@@ -6,7 +6,7 @@ import type { VisionPort } from "../vision/port.ts";
 import type { BackendRegistry } from "../backend/port.ts";
 import { genRunId, RunRegistry } from "./run-registry.ts";
 import { createTurnBudget, DEFAULT_MAX_TURNS } from "./turn-budget.ts";
-import type { SingleSlotLock } from "./concurrency-lock.ts";
+import type { ForegroundLock } from "./concurrency-lock.ts";
 import type { RunLog } from "../runtime/run-log.ts";
 import { buildToolEvent } from "../runtime/run-log.ts";
 import { resolveAgentModel, type ModelRegistryLike } from "../tiers/resolve.ts";
@@ -112,7 +112,7 @@ export interface SpawnOptions {
   registry: Map<string, AgentDef>;
   todoSync: TodoSyncPort;
   runRegistry: RunRegistry;
-  lock: SingleSlotLock;
+  lock: ForegroundLock;
   backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory — engine looks up by agentDef.backend
   parentModel: { provider: string; id: string };
   parentCwd: string;
@@ -168,6 +168,47 @@ export interface SpawnResult {
    *  when this is set. Non-retryable failures (turn budget, agent-not-found, EMPTY_RESULT,
    *  abort, lock busy) leave this unset. */
   retryable?: boolean;
+  /** #49: file paths the child mutated before the run ended (edit/write `path`; bash
+   *  redirections/tee best-effort), deduped + sorted. Lets the controller re-inspect only
+   *  what changed after a turn-budget cut, instead of the whole repo. Populated on every
+   *  run (completed runs too); most useful on the turn-budget branch. */
+  filesTouched?: string[];
+  /** #49: did the child emit a trailing assistant message after its last tool (a summary),
+   *  or was it cut mid-tool-work? Surfaced on turn-budget exhaustion so the controller knows
+   *  whether finalText is a partial summary or a mid-thought. Undefined for non-turn-budget paths. */
+  reachedSummary?: boolean;
+}
+
+/** #49: extract file paths a tool event touched, for the structured partial-result report.
+ *  edit/write carry a `path` arg reliably; bash is best-effort (redirections `>`/`>>` + `tee` to a
+ *  path-like token). Reads are NOT mutations and are excluded. */
+function extractTouchedFiles(toolName: string, args: unknown): string[] {
+  if (!args || typeof args !== "object") return [];
+  const a = args as Record<string, unknown>;
+  if (toolName === "edit" || toolName === "write") {
+    const p = typeof a.path === "string" ? a.path : typeof a.file_path === "string" ? a.file_path : undefined;
+    return p ? [p] : [];
+  }
+  if (toolName === "bash") {
+    const cmd = typeof a.command === "string" ? a.command : undefined;
+    if (!cmd) return [];
+    const out: string[] = [];
+    // `> path` / `>> path` / `tee path` — only tokens that look like a path (contain `/` or `.`)
+    // to avoid false positives on bare words ("echo done", "exit 0").
+    const redir = />>?\s+([^\s|;&<>]+)/g;
+    let m: RegExpExecArray | null;
+    while ((m = redir.exec(cmd)) !== null) {
+      const tok = m[1];
+      if (tok && /[/.]/.test(tok)) out.push(tok);
+    }
+    const tee = /\btee\s+(?:-a\s+)?([^\s|;&<>]+)/g;
+    while ((m = tee.exec(cmd)) !== null) {
+      const tok = m[1];
+      if (tok && /[/.]/.test(tok)) out.push(tok);
+    }
+    return out;
+  }
+  return [];
 }
 
 export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
@@ -184,15 +225,17 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
   if (readOnly) {
     runId = genRunId();
   } else {
-    // concurrency=1 (SPEC-1 §9.2) — peek before generating a runId so a rejected
-    // call doesn't mint a discarded id; the held id is named in the message.
-    const busyId = opts.lock.current();
-    if (busyId !== null) {
-      return fail("", startedAt, `a subagent is already running (concurrency=1 in v0.1); wait for ${busyId} to finish or abort it first`, opts.agent);
-    }
+    // #31 tail: foreground concurrency lock. cap=1 (default) is FAIL-FAST (backward-compat — a
+    // 2nd dispatch is rejected with the held runId + the cap + the env hint); cap>1 (opt-in via
+    // ARMORY_FLEET_FOREGROUND_CONCURRENCY) QUEUES — up to `cap` writes run in parallel, the rest wait.
+    // The cap is session-level (a shared lock can't be re-sized per dispatch); see concurrency-lock.ts.
     runId = genRunId();
-    if (!opts.lock.tryAcquire(runId)) {
-      return fail("", startedAt, "concurrency lock unexpectedly unavailable", opts.agent);
+    const acq = await opts.lock.acquire(runId);
+    if (!acq.ok) {
+      const hint = opts.lock.cap === 1
+        ? ` (foreground concurrency=1; ${acq.busy.join(", ")} is running — wait for it to finish or abort it, or raise ARMORY_FLEET_FOREGROUND_CONCURRENCY to allow parallel write dispatches)`
+        : ` (foreground concurrency=${opts.lock.cap}; all ${opts.lock.cap} slots held by ${acq.busy.join(", ")}); wait for one to finish or raise ARMORY_FLEET_FOREGROUND_CONCURRENCY)`;
+      return fail("", startedAt, `a subagent is already running${hint}`, opts.agent);
     }
   }
 
@@ -306,6 +349,10 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     // synchronously inside subscribe() (temporal-dead-zone guard).
     let modelError: string | undefined;   // model-call failure surfaced via stopReason "error"
     let sawAssistantMessage = false;      // #22: did the child emit any assistant message_end at all?
+    // #49: structured partial-result tracking — what the child mutated, and whether it emitted
+    // a trailing assistant message after its last tool (a summary) vs being cut mid-tool-work.
+    const filesTouched = new Set<string>();
+    let sawAssistantAfterLastTool = true;   // no tools yet = trivially "reached a summary"
 
     // #23: liveness — classify events into a short, content-free class string for the widget.
     // Names the tool (safe — tool name is not args/result) so the operator sees "what's happening"
@@ -334,6 +381,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
         if (budget.consume()) void session.abort();
       } else if (e.type === "message_end" && e.message?.role === "assistant") {
         sawAssistantMessage = true;
+        sawAssistantAfterLastTool = true;   // #49: a trailing assistant message = (so far) reached a summary
         const text = e.message.content?.map((c) => (c.type === "text" ? c.text ?? "" : "")).join("") ?? "";
         // #26/#22: a model-call failure (401, provider down, rate limit) surfaces as
         // stopReason "error". The SDK retries internally; if it still ends with an error
@@ -365,6 +413,9 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
           void session.abort();
         }
       } else if (e.type === "tool_execution_end") {
+        // #49: track mutated files for the structured partial-result report.
+        sawAssistantAfterLastTool = false;   // cut mid-tool-work unless a message follows
+        for (const f of extractTouchedFiles((e as { toolName?: string }).toolName ?? "", (e as { args?: unknown }).args)) filesTouched.add(f);
         try {
           opts.runLog?.append(runId, buildToolEvent((e as any).toolName, (e as any).args, (e as any).result, (e as any).isError ?? false, turnIdx));
         } catch { /* best-effort */ }
@@ -394,6 +445,8 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
 
     let status: FleetRunStatus;
     let error: string | undefined;
+    const filesTouchedList = [...filesTouched].sort();   // #49: deduped + sorted
+    let reachedSummary: boolean | undefined;            // #49: only set on the turn-budget branch
     if (aborted) {
       status = "aborted";
       // #23: distinguish TODO-status reversion from filesystem rollback. A foreground run is in-place
@@ -415,7 +468,14 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
         ? finalText.slice(0, PARTIAL_WINDOW) + "\n…(partial truncated — see run log for full output)"
         : finalText;
       status = "failed";
-      error = `hit turn budget (${maxTurns}) mid-task; partial result:\n${partial}`;
+      // #49: surface WHAT was modified + whether the partial is a summary or a mid-thought, so the
+      // controller can re-inspect only the touched files instead of the whole repo, and knows
+      // whether to trust finalText as a partial summary.
+      reachedSummary = sawAssistantAfterLastTool;
+      const filesLine = filesTouchedList.length
+        ? `\n\nFiles modified before the cut: ${filesTouchedList.join(", ")}`
+        : "\n\nFiles modified before the cut: (none detected)";
+      error = `hit turn budget (${maxTurns}) mid-task; partial result:\n${partial}${filesLine}\nReached summary: ${reachedSummary ? "yes" : "no (cut mid-tool-work)"}`;
     } else if (runError) {
       status = "failed";
       error = runError;
@@ -446,11 +506,11 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       status = "completed";
     }
 
-    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal, costTotal, contextTokens, modelError ? true : undefined);
+    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal, costTotal, contextTokens, modelError ? true : undefined, filesTouchedList, reachedSummary);
   } finally {
     // #31: a readOnly dispatch never acquired the lock — don't release what it didn't take
     // (releasing a lock held by another concurrent write dispatch would corrupt serialization).
-    if (!readOnly) opts.lock.release();
+    if (!readOnly) opts.lock.release(runId);
   }
 }
 
@@ -469,6 +529,7 @@ async function finishRun(
   status: FleetRunStatus, finalText: string, todoId: string | null, priorStatus: string | undefined,
   error: string | undefined, agentName: string, model: string, tokenTotal = 0, costTotal = 0, contextTokens = 0,
   retryable?: boolean,
+  filesTouched?: string[], reachedSummary?: boolean,
 ): Promise<SpawnResult> {
   if (finalizedRunIds.has(runId)) {
     // Already finalized — return the existing registry record's result without re-appending.
@@ -478,6 +539,7 @@ async function finishRun(
       runId, todoId, agent: agentName, model,
       durationMs: existing?.endedAt ? existing.endedAt - startedAt : Date.now() - startedAt,
       tokenTotal, costTotal, contextTokens, error, retryable,
+      filesTouched, reachedSummary,
     };
   }
   finalizedRunIds.add(runId);
@@ -512,5 +574,6 @@ async function finishRun(
   return {
     status, finalText, runId, todoId, agent: agentName, model,
     durationMs: endedAt - startedAt, tokenTotal, costTotal, contextTokens, error, retryable,
+    filesTouched, reachedSummary,
   };
 }

package/src/index.ts

@@ -12,11 +12,12 @@ import { createSubagentTool, type SubagentToolDeps } from "./tools/subagent.ts";
 // SPEC-6-3: /fleet uses openWorkflowPanelLoop (Task 12) instead of the raw openFleetPanel factory.
 import { discoverAgents } from "./registry/discovery.ts";
 import { RunRegistry } from "./engine/run-registry.ts";
-import { createSingleSlotLock } from "./engine/concurrency-lock.ts";
+import { createSingleSlotLock, createForegroundLock } from "./engine/concurrency-lock.ts";
 import { ArmoryTodoAdapter } from "./todo-sync/adapter.ts";
 import { ArmoryMemoryAdapter } from "./memory-hydrate/adapter.ts";
 import { ArmoryVisionAdapter } from "./vision/adapter.ts";
 import { buildChildLoader } from "./engine/child-loader.ts";
+import { withModelFallbackRetry } from "./engine/retry-fallback.ts";
 import { createDescribeImageTool } from "./vision/describe-image-tool.ts";
 import type { MemoryHydratePort } from "./memory-hydrate/port.ts";
 import type { VisionPort } from "./vision/port.ts";
@@ -152,12 +153,23 @@ export function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort
   };
 }
 
+/** #31 tail: parse the foreground-concurrency cap from `ARMORY_FLEET_FOREGROUND_CONCURRENCY`.
+ *  Default 1 (fail-fast, backward-compat). >1 enables a queueing pool (up to N parallel write
+ *  dispatches). Clamped to [1, 64]; invalid/empty → 1. */
+function parseForegroundConcurrency(): number {
+  const raw = process.env.ARMORY_FLEET_FOREGROUND_CONCURRENCY;
+  if (!raw) return 1;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) return 1;
+  return Math.min(n, 64);
+}
+
 export default async function (pi: ExtensionAPI): Promise<void> {
   const modelRuntime = await ModelRuntime.create();
   const deps: SubagentToolDeps = {
     registry: new Map(),
     runRegistry: new RunRegistry(),
-    lock: createSingleSlotLock(),
+    lock: createForegroundLock(parseForegroundConcurrency()),
     todoSync: new ArmoryTodoAdapter(),
     backendRegistry: await buildDefaultBackendRegistry(modelRuntime),
     parentModel: { provider: "", id: "" },
@@ -189,6 +201,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // Builtin-only placeholder tier registry so spawn works before session_start rebuilds with merged tiers.
   deps.tierRegistry = new TierRegistry({ tiers: BUILTIN_TIERS, agents: deps.registry });
 
+  // #39 tail: global default fallback model (env-driven for now; a settings.json field is a follow-up).
+  // A retryable provider failure (stopReason "error") retries once on this model even without a
+  // per-dispatch `modelFallback`. Per the AGENTS.md "Ollama primary + OpenRouter fallback" pattern.
+  deps.defaultModelFallback = process.env.ARMORY_FLEET_MODEL_FALLBACK || undefined;
+
+  // #31 tail: foreground concurrency is SESSION-LEVEL (a shared lock can't be re-sized per
+  // dispatch). cap=1 (default) is fail-fast (backward-compat); cap>1 enables a queueing pool so
+  // up to `cap` write dispatches run in parallel. readOnly dispatches bypass the lock (#41).
+
   // SPEC-6-2: gate registry + builtin gate registration.
   const gateRegistry = new GateRegistry();
   registerBuiltinGates(gateRegistry);
@@ -234,14 +255,14 @@ export default async function (pi: ExtensionAPI): Promise<void> {
       ...deps.lifecycleDeps,
       genRunId: () => opts.runId,   // override: use the async runner's runId
       ...(isolated ? { artifactDiscovery: ({ finalText, cwd, baseRef }: { finalText: string; cwd: string; baseRef: string }) => (deps.asyncRunner as AsyncRunnerDeps).diff.diffPhase(cwd, baseRef, finalText) } : {}),
-      spawn: async (o) => spawnSubagent({
+      spawn: withModelFallbackRetry(async (o) => spawnSubagent({
         agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
         skillsOverride: o.skills, backendOverride: o.backend,
         registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: bgLock,
         backendRegistry: deps.backendRegistry, parentModel: deps.parentModel,
         parentCwd: isolated ? opts.worktreePath! : deps.parentCwd,
         runLog: deps.runLog, tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
-      }),
+      }), deps.defaultModelFallback),
     };
     const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: opts.mode, worktreePath: opts.worktreePath, baseRef: "HEAD", onCheckpoint: async (p) => p.status === "failed" ? { action: "abort" } : { action: "continue" } });
     return res as unknown as import("./runtime/async-runner.ts").FakeLifecycleResult;
@@ -508,13 +529,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
           };
       const lifecycleFullDeps: import("./lifecycle/run-lifecycle.ts").LifecycleRunDeps = {
         ...deps.lifecycleDeps,
-        spawn: async (o) => spawnSubagent({
+        spawn: withModelFallbackRetry(async (o) => spawnSubagent({
           agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
             skillsOverride: o.skills, backendOverride: o.backend,
           registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
           backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd,
           tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,  // SPEC-6-1
-        }),
+        }), deps.defaultModelFallback),
       };
       const res = await runLifecycle(parsed.task, lcName, { deps: lifecycleFullDeps, mode: parsed.auto ? "auto" : "checkpointed", onCheckpoint });
       deps.lifecycleRuns.set(res.runId, res);

package/src/tools/subagent.ts

@@ -3,7 +3,7 @@ import { Type, type Static } from "typebox";
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { TodoSyncPort } from "../todo-sync/port.ts";
 import type { RunRegistry } from "../engine/run-registry.ts";
-import type { SingleSlotLock } from "../engine/concurrency-lock.ts";
+import type { ForegroundLock } from "../engine/concurrency-lock.ts";
 import type { SpawnResult } from "../engine/spawnSubagent.ts";
 import { spawnSubagent } from "../engine/spawnSubagent.ts";
 import type { BackendRegistry } from "../backend/port.ts";
@@ -47,7 +47,7 @@ export function mergeLifecycleSkills(phaseSkills: string[] | undefined, callerSk
 export interface SubagentToolDeps {
   registry: Map<string, AgentDef>;
   runRegistry: RunRegistry;
-  lock: SingleSlotLock;
+  lock: ForegroundLock;
   todoSync: TodoSyncPort;
   backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory
   parentModel: { provider: string; id: string };
@@ -74,6 +74,12 @@ export interface SubagentToolDeps {
   reloadTiers?: () => void;
   /** SPEC-6-1: model contextWindow resolver for Runs-tab ctx% (Surface C). Optional — ctx% hidden when absent. */
   getModelContextWindow?: (model: string) => number | undefined;
+  /** #39 tail: a global default fallback model so a retryable provider failure (stopReason "error")
+   *  retries once even without a per-dispatch `modelFallback` param. Wired from the
+   *  `ARMORY_FLEET_MODEL_FALLBACK` env var in index.ts; a settings.json field is a follow-up.
+   *  Per-dispatch `modelFallback` (when passed) takes precedence. Applies to the direct foreground
+   *  path, the foreground lifecycle spawn, and the background/scheduled spawn. */
+  defaultModelFallback?: string;
 }
 
 /** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
@@ -90,6 +96,8 @@ export function createSubagentTool(deps: SubagentToolDeps) {
       "Pass readOnly:true for dispatches that will NOT edit the working directory (review/audit, or research that writes no scratch files). It bypasses the foreground single-slot lock so multiple readOnly dispatches can run in parallel. Only use it when you are certain the child won't mutate cwd — mislabeling risks edit conflicts.",
       "By default a dispatch loads NO skills (lean substrate). If the task needs a skill (e.g. test-driven-development for a TDD task, executing-plans for a plan-execution task), pass its name in the `skills` array to opt in — loading all skills by default wastes ~59% of the context window.",
       "Pass `modelFallback` so a transient provider rate-limit / auth failure (stopReason 'error') auto-retries once on the fallback model instead of failing the dispatch. Per the AGENTS.md 'Ollama primary + OpenRouter fallback' pattern — don't let infra limits break a dispatch chain.",
+      "For web tasks, dispatch with the firecrawl skill the child needs (e.g. skills: [\"firecrawl-scrape\"] / [\"firecrawl-search\"]) — children now discover skills from `~/.agents/skills` + `~/.pi/agent/skills`, matching your surface. Curl stays the right call for raw HTTP probes, smoke tests, and plain JSON/text APIs where JS rendering isn't needed (per the AGENTS.md firecrawl-first/curl-fallback preference).",
+      "Foreground concurrency is SESSION-LEVEL, not per-dispatch: write dispatches serialize through one shared lock sized by ARMORY_FLEET_FOREGROUND_CONCURRENCY. At the default (1) a 2nd write dispatch is rejected fail-fast (the error names the held runId) — dispatch sequentially (await each) or use readOnly:true for parallel read-only work. Raise the env cap only if you accept parallel in-place edits (conflict risk).",
     ],
     parameters: subagentParams,
     async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, _ctx: any) {
@@ -111,9 +119,12 @@ export function createSubagentTool(deps: SubagentToolDeps) {
       }
       if (params.lifecycle) {
         const { runLifecycle } = await import("../lifecycle/run-lifecycle.ts");
+        const { withModelFallbackRetry } = await import("../engine/retry-fallback.ts");
         const lifecycleFullDeps: LifecycleRunDeps = {
           ...deps.lifecycleDeps,
-          spawn: async (o) => spawnSubagent({
+          // #39 tail: wrap the phase spawn so a retryable provider failure retries once on the
+          // fallback (per-dispatch `modelFallback` param OR the global `defaultModelFallback` dep).
+          spawn: withModelFallbackRetry(async (o) => spawnSubagent({
             agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
             skillsOverride: mergeLifecycleSkills(o.skills, params.skills), backendOverride: o.backend,
             registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
@@ -121,7 +132,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
             maxTurns: params.maxTurns,
             tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
             readOnly: params.readOnly,
-          }),
+          }), params.modelFallback ?? deps.defaultModelFallback, signal),
         };
         const res = await runLifecycle(params.task, params.lifecycle, {
           deps: lifecycleFullDeps, mode: "auto",
@@ -161,18 +172,21 @@ export function createSubagentTool(deps: SubagentToolDeps) {
       // retry relinks the SAME todoId to continue the tracked task. Retry ONCE, only on the direct
       // foreground path, only if a distinct fallback model was provided. The retry's runId differs
       // from the primary's (each spawnSubagent call mints its own); details.retriedWithModel marks it.
+      // #39 tail: the fallback comes from the per-dispatch `modelFallback` param OR the global
+      // `defaultModelFallback` dep (wired from ARMORY_FLEET_MODEL_FALLBACK) — per-dispatch wins.
+      const fallback = params.modelFallback ?? deps.defaultModelFallback;
       let retriedWithModel: string | undefined;
       let finalRes = res;
       if (
-        res.status === "failed" && res.retryable && params.modelFallback &&
-        params.modelFallback !== res.model && !signal.aborted
+        res.status === "failed" && res.retryable && fallback &&
+        fallback !== res.model && !signal.aborted
       ) {
         finalRes = await spawnSubagent({
           agent: params.agent,
           task: params.task,
           todoId: res.todoId ?? undefined,
           track: params.track,
-          model: params.modelFallback,
+          model: fallback,
           readOnly: params.readOnly,
           skillsOverride: params.skills,
           registry: deps.registry,
@@ -187,7 +201,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
           maxTurns: params.maxTurns,
           tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
         });
-        retriedWithModel = params.modelFallback;
+        retriedWithModel = fallback;
       }
       const isError = finalRes.status === "failed" || finalRes.status === "aborted";
       return {
@@ -196,6 +210,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
           runId: finalRes.runId, todoId: finalRes.todoId, agent: finalRes.agent, model: finalRes.model,
           status: finalRes.status, durationMs: finalRes.durationMs, tokenTotal: finalRes.tokenTotal,
           retriedWithModel,
+          filesTouched: finalRes.filesTouched, reachedSummary: finalRes.reachedSummary,
         },
         isError,
       };