@getpipher/armory-fleet 0.12.1 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "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

@@ -7,6 +7,30 @@ import { dirname } from "node:path";
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { MemoryHydratePort } from "../memory-hydrate/port.ts";
 
+/** Shape of the pi resource-loader's current-skills context (the `cur` arg of skillsOverride).
+ *  Generic over the skill + diagnostics types so the pi SDK's full `Skill`/`ResourceDiagnostic`
+ *  types flow through unchanged. */
+export interface InstalledSkills<S = { name: string }, D = unknown> {
+  skills: S[];
+  diagnostics: D;
+}
+
+/** #32: resolve the child's skill bundle from the agent's declared skills + the installed arsenal.
+ *
+ *  - Agent declares specific skills → load only those (filtered from the installed arsenal).
+ *  - Agent declares NO skills → load NO skills (lean substrate). This is the #32 fix: previously
+ *    an agent with no `skills` field loaded ALL installed skills (~42 → ~570K substrate on every
+ *    `general-purpose` dispatch, ~59% of a 976K context window from turn 1). Callers opt in to
+ *    skills via the `subagent` tool's `skills` param (threaded as `skillsOverride`, which clones
+ *    `agent.skills` before this runs).
+ *  - Returning `[]` (not `cur.skills`) is the deliberate behavior change. */
+export function resolveChildSkills<S extends { name: string }, D>(agent: Pick<AgentDef, "skills">, cur: InstalledSkills<S, D>): InstalledSkills<S, D> {
+  const selected = agent.skills && agent.skills.length
+    ? cur.skills.filter((s) => agent.skills!.includes(s.name))
+    : [];
+  return { skills: selected, diagnostics: cur.diagnostics };
+}
+
 /** Fixed pseudo-cwd for the global cross-project user memory scope. */
 export const USER_PSEUDO_CWD = "/__armory-fleet-user__";
 
@@ -36,12 +60,6 @@ export function buildChildLoader(opts: ChildLoaderOpts): DefaultResourceLoader {
     noExtensions: true,
     systemPromptOverride: (base) =>
       composeChildPrompt({ rolePrompt: opts.agent.rolePrompt, memoryBlock, base: base ?? "" }),
-    skillsOverride: (cur) => ({
-      skills:
-        opts.agent.skills && opts.agent.skills.length
-          ? cur.skills.filter((s) => opts.agent.skills!.includes(s.name))
-          : cur.skills,
-      diagnostics: cur.diagnostics,
-    }),
+    skillsOverride: (cur) => resolveChildSkills(opts.agent, cur),
   });
-}
+}

package/src/engine/spawnSubagent.ts

@@ -142,6 +142,11 @@ export interface SpawnOptions {
   modelRegistry?: ModelRegistryLike;
   /** SPEC-6-3: workflow adapter tier override — replaces agent.tier before model resolution. */
   tierOverride?: string;
+  /** #31: when true, the caller asserts this dispatch will NOT mutate the working directory
+   *  (review/audit/research). Read-only dispatches bypass the foreground single-slot lock so
+   *  multiple readOnly dispatches — and/or a readOnly dispatch alongside a write dispatch — can
+   *  run in parallel. Mislabeling a write dispatch as readOnly risks in-place edit conflicts. */
+  readOnly?: boolean;
 }
 
 export interface SpawnResult {
@@ -158,6 +163,11 @@ export interface SpawnResult {
   /** SPEC-6-1: final context tokens (calcContextTokens of the last usage). */
   contextTokens?: number;
   error?: string;
+  /** #39: true when the failure is a retryable provider rate-limit / auth failure
+   *  (stopReason "error"). The subagent tool retries once with the configured `modelFallback`
+   *  when this is set. Non-retryable failures (turn budget, agent-not-found, EMPTY_RESULT,
+   *  abort, lock busy) leave this unset. */
+  retryable?: boolean;
 }
 
 export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
@@ -165,15 +175,25 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
   const maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
   const startedAt = Date.now();
 
-  // 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);
-  }
-  const runId = genRunId();
-  if (!opts.lock.tryAcquire(runId)) {
-    return fail("", startedAt, "concurrency lock unexpectedly unavailable", opts.agent);
+  // #31: read-only dispatches (review/audit/research) bypass the foreground single-slot lock —
+  // the caller asserts no cwd mutation, so the in-place edit-conflict guard doesn't apply and
+  // multiple readOnly dispatches (and/or a readOnly alongside a write dispatch) may run in
+  // parallel. The lock is still acquired for write dispatches (default), preserving concurrency=1.
+  const readOnly = opts.readOnly ?? false;
+  let runId: string;
+  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);
+    }
+    runId = genRunId();
+    if (!opts.lock.tryAcquire(runId)) {
+      return fail("", startedAt, "concurrency lock unexpectedly unavailable", opts.agent);
+    }
   }
 
   try {
@@ -399,9 +419,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);
+    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal, costTotal, contextTokens, modelError ? true : undefined);
   } finally {
-    opts.lock.release();
+    // #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();
   }
 }
 
@@ -419,6 +441,7 @@ async function finishRun(
   opts: SpawnOptions, runId: string, startedAt: number,
   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,
 ): Promise<SpawnResult> {
   if (finalizedRunIds.has(runId)) {
     // Already finalized — return the existing registry record's result without re-appending.
@@ -427,7 +450,7 @@ async function finishRun(
       status: existing?.status ?? status, finalText: existing?.resultSummary ?? finalText,
       runId, todoId, agent: agentName, model,
       durationMs: existing?.endedAt ? existing.endedAt - startedAt : Date.now() - startedAt,
-      tokenTotal, costTotal, contextTokens, error,
+      tokenTotal, costTotal, contextTokens, error, retryable,
     };
   }
   finalizedRunIds.add(runId);
@@ -461,6 +484,6 @@ async function finishRun(
   }
   return {
     status, finalText, runId, todoId, agent: agentName, model,
-    durationMs: endedAt - startedAt, tokenTotal, costTotal, contextTokens, error,
+    durationMs: endedAt - startedAt, tokenTotal, costTotal, contextTokens, error, retryable,
   };
 }

package/src/tools/subagent.ts

@@ -29,10 +29,21 @@ export const subagentParams = Type.Object({
   ], { description: "Edit isolation for background runs. 'worktree' = git worktree (requires a git repo; fails sync if not). 'none' = in-place in cwd (no isolation; parallel edits may conflict). 'auto' (default) = worktree when cwd is a git repo, in-place otherwise." })),
   schedule: Type.Optional(Type.String({ description: 'Schedule the run instead of firing now: a cron string ("0 9 * * 1-5"), an interval ("30m"/"2h"), or a one-shot ISO datetime ("2026-07-25T14:00"). Returns { scheduleId, nextFire }. Session-scoped (fires only while pi is open); no catch-up.' })),
   maxTurns: Type.Optional(Type.Number({ description: 'Per-run turn budget (default 20). Raise for complex multi-step tasks (e.g. 40) so the subagent doesn\'t hit the budget mid-task; lower for trivial lookups.' })),
+  readOnly: Type.Optional(Type.Boolean({ description: 'Default false. Pass true ONLY for dispatches that will NOT mutate the working directory (review/audit, or research that writes no scratch files). A readOnly dispatch bypasses the foreground single-slot lock so multiple readOnly dispatches — and/or a readOnly alongside a write dispatch — can run in parallel. The caller is responsible for the assertion: mislabeling a dispatch that edits as readOnly risks in-place edit conflicts. Has no effect on background/scheduled runs (they use their own locks).' })),
+  skills: Type.Optional(Type.Array(Type.String(), { description: 'Skills to load for this dispatch (opt-in). By default a dispatch loads NO skills (#32 — lean substrate; previously an agent with no skills field loaded ALL ~42 installed skills, ~570K tokens / ~59% of context). Pass skill names from the installed arsenal (e.g. ["executing-plans", "test-driven-development"]) to opt in. For a direct dispatch, this replaces the agent\'s frontmatter skills (pass [] to load zero). For a lifecycle dispatch, this is ADDITIVE — the phase\'s designed skill bundle always loads and these are merged on top (a caller cannot strip a phase\'s required skills).' })),
+  modelFallback: Type.Optional(Type.String({ description: 'Model to retry with if the primary dispatch fails with a retryable provider rate-limit / auth failure (stopReason "error"). The fleet retries ONCE on this model and relinks the same tracked todo. Surface the model that served the retry in the result details (retriedWithModel). Per the AGENTS.md "Ollama primary + OpenRouter fallback" pattern. No effect on non-retryable failures (turn budget, agent-not-found, abort). Direct foreground dispatches only — background/scheduled/lifecycle retries are a follow-up.' })),
 });
 
 export type SubagentInput = Static<typeof subagentParams>;
 
+/** #32: merge a lifecycle phase's skill bundle with the caller's `skills` param.
+ *  Additive + deduped — the phase's designed skills always load; the caller can add extras but
+ *  cannot strip phase skills (avoids the footgun where a caller passing `skills: ["tdd"]` with
+ *  `lifecycle: "default"` would silently drop `brainstorming` from the brainstorm phase). */
+export function mergeLifecycleSkills(phaseSkills: string[] | undefined, callerSkills: string[] | undefined): string[] {
+  return [...new Set([...(phaseSkills ?? []), ...(callerSkills ?? [])])];
+}
+
 export interface SubagentToolDeps {
   registry: Map<string, AgentDef>;
   runRegistry: RunRegistry;
@@ -76,6 +87,9 @@ export function createSubagentTool(deps: SubagentToolDeps) {
       "Use subagent to delegate an isolated, well-scoped task to a named agent; it runs in the foreground and returns the result + a runId.",
       "Pass todoId to link the run to an existing open todo you see in the Open TODOs block; otherwise fleet creates a tracked fleet task.",
       "Pass track:false only for trivial throwaway lookups that don't represent real work.",
+      "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.",
     ],
     parameters: subagentParams,
     async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, _ctx: any) {
@@ -101,11 +115,12 @@ export function createSubagentTool(deps: SubagentToolDeps) {
           ...deps.lifecycleDeps,
           spawn: async (o) => spawnSubagent({
             agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
-            skillsOverride: o.skills, backendOverride: o.backend,
+            skillsOverride: mergeLifecycleSkills(o.skills, params.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, runLog: deps.runLog, signal,
             maxTurns: params.maxTurns,
             tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
+            readOnly: params.readOnly,
           }),
         };
         const res = await runLifecycle(params.task, params.lifecycle, {
@@ -127,6 +142,8 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         todoId: params.todoId,
         track: params.track,
         model: params.model,
+        readOnly: params.readOnly,
+        skillsOverride: params.skills,
         registry: deps.registry,
         todoSync: deps.todoSync,
         runRegistry: deps.runRegistry,
@@ -139,15 +156,49 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         maxTurns: params.maxTurns,
         tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
       });
-      const isError = res.status === "failed" || res.status === "aborted";
+      // #39: auto-retry on a retryable provider rate-limit / auth failure (stopReason "error").
+      // The primary run reverted its linked todo to open (finishRun -> markRunTodoReverted), so the
+      // 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.
+      let retriedWithModel: string | undefined;
+      let finalRes = res;
+      if (
+        res.status === "failed" && res.retryable && params.modelFallback &&
+        params.modelFallback !== res.model && !signal.aborted
+      ) {
+        finalRes = await spawnSubagent({
+          agent: params.agent,
+          task: params.task,
+          todoId: res.todoId ?? undefined,
+          track: params.track,
+          model: params.modelFallback,
+          readOnly: params.readOnly,
+          skillsOverride: params.skills,
+          registry: deps.registry,
+          todoSync: deps.todoSync,
+          runRegistry: deps.runRegistry,
+          lock: deps.lock,
+          backendRegistry: deps.backendRegistry,
+          parentModel: deps.parentModel,
+          parentCwd: deps.parentCwd,
+          runLog: deps.runLog,
+          signal,
+          maxTurns: params.maxTurns,
+          tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
+        });
+        retriedWithModel = params.modelFallback;
+      }
+      const isError = finalRes.status === "failed" || finalRes.status === "aborted";
       return {
-        content: [{ type: "text" as const, text: isError ? (res.error ?? res.status) : res.finalText }],
+        content: [{ type: "text" as const, text: isError ? (finalRes.error ?? finalRes.status) : finalRes.finalText }],
         details: {
-          runId: res.runId, todoId: res.todoId, agent: res.agent, model: res.model,
-          status: res.status, durationMs: res.durationMs, tokenTotal: res.tokenTotal,
+          runId: finalRes.runId, todoId: finalRes.todoId, agent: finalRes.agent, model: finalRes.model,
+          status: finalRes.status, durationMs: finalRes.durationMs, tokenTotal: finalRes.tokenTotal,
+          retriedWithModel,
         },
         isError,
       };
     },
   };
-}
+}