@getpipher/armory-fleet 0.13.0 → 0.14.0

package/README.md

@@ -316,6 +316,16 @@ Every workflow run is **journaled** (`workflows/journal.ts`) and **resumable**.
 - **Panel Run-action:** a 3rd `cwd` input step (task → name → cwd), prefilled with the session cwd; Enter accepts, Escape cancels.
 - **Deferred:** bg/scheduled + worktree cwd-isolation (the `cwd` param is honored by foreground dispatches only for now) — tracked in #62.
 
+## Dogfood reliability (v0.14.0)
+
+Four fixes from dogfooding the fleet on itself (issues #58–#61):
+
+- **`ARMORY_FLEET_MODEL_FALLBACK=auto`** — resolve the global fallback per session from the configured+available model snapshot: a different **provider** than the session model is preferred, else a different model id; unresolvable (single-model setup) stays off with a one-time warning. Non-`auto` env values are used verbatim; per-dispatch `modelFallback` still wins.
+- **No-fallback hint** — a retryable provider failure (stopReason `error`) with neither a per-dispatch `modelFallback` nor the global default surfaces `no modelFallback configured — pass modelFallback or set ARMORY_FLEET_MODEL_FALLBACK` so silent no-retry failures are visible.
+- **Masked primary errors fixed** — when a fallback retry also fails, the surfaced error now names **both** attempts (`primary '<model>' failed: …; fallback '<model>' failed: …`) instead of only the fallback's.
+- **Zero-tool-call flag (#61)** — a run that "completes" without a single executed tool call (the premature-return shape: narrate a plan, end) is prefixed with `[FLEET] zero-tool-call run — likely a premature return` in the tool result; `details.toolCallCount` exposes the count. Verify (git status/log) before trusting such a result.
+- **Richer run journal** — `run:ended` now carries `error` (failure reason), `filesTouched` (#49 parity in the durable journal — real SDK args are captured from `tool_execution_start`; the end event has none), and `toolCallCount`.
+
 ## Roadmap
 
 armory-fleet follows a PRD → SPEC-N (brainstorm → spec → plan → implementation) pipeline. **16/16 phases done through v0.12.0.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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/backend/claude-events.ts

@@ -1,39 +1,58 @@
-// src/backend/claude-events.ts — map one CC stream-json NDJSON line → ChildSessionEvent (SPEC-3 §4.2).
+// src/backend/claude-events.ts — map one CC stream-json NDJSON line → ChildSessionEvent(s) (SPEC-3 §4.2).
 // Returns null for: filtered echoes (our own user writes), unknown types, malformed lines.
 // The caller logs null-but-parseable lines at debug (forward-compat: CC may add types we don't need).
 import type { ChildSessionEvent } from "../engine/spawnSubagent.ts";
 
-interface CCMessage { role?: string; content?: Array<{ type: string; text?: string }>; usage?: Record<string, unknown>; }
+interface CCContentBlock { type: string; text?: string; id?: string; name?: string; input?: Record<string, unknown>; }
+interface CCMessage { role?: string; content?: CCContentBlock[]; usage?: Record<string, unknown>; }
 interface CCEvent { type: string; subtype?: string; session_id?: string; message?: CCMessage; error?: { message?: string }; }
 
-export function mapClaudeEvent(line: string): ChildSessionEvent | null {
+/** Map one line to ALL the ChildSessionEvents it implies. An assistant message carrying tool_use
+ *  blocks yields the message_end PLUS one tool_execution_end per block (#61: the engine's
+ *  zero-tool-call premature-return signal must count claude children too — without this, every
+ *  completed claude run counted 0 tools and was falsely flagged). The per-block end event fires
+ *  at message time, not per-tool completion (CC stream-json gives no finer granularity) — right
+ *  enough for "did the child act", which is what the count is for. */
+export function mapClaudeEvents(line: string): ChildSessionEvent[] {
   let ev: CCEvent;
   try {
     ev = JSON.parse(line) as CCEvent;
   } catch {
-    return null; // malformed line — resilient
+    return []; // malformed line — resilient
   }
   switch (ev.type) {
-    case "system":
+    case "system": {
       if (ev.subtype === "init" && typeof ev.session_id === "string") {
-        return { type: "session_init", backendSessionId: ev.session_id };
+        return [{ type: "session_init", backendSessionId: ev.session_id }];
       }
-      return null;
+      return [];
+    }
     case "assistant": {
       const msg = ev.message;
-      if (!msg) return null;
+      if (!msg) return [];
       const content = (msg.content ?? []).map((c) => ({ type: c.type, text: c.text }));
       const usage = msg.usage as { cost?: { total?: number } } | undefined;
-      return { type: "message_end", message: { role: msg.role ?? "assistant", content, usage } };
+      const events: ChildSessionEvent[] = [{ type: "message_end", message: { role: msg.role ?? "assistant", content, usage } }];
+      for (const block of msg.content ?? []) {
+        if (block.type === "tool_use") {
+          events.push({ type: "tool_execution_end", toolCallId: block.id ?? "", toolName: block.name ?? "unknown", args: block.input, result: "", isError: false });
+        }
+      }
+      return events;
     }
     case "result":
       // turn boundary (success or error_max_turns) → turn_end drives the budget
-      return { type: "turn_end" };
+      return [{ type: "turn_end" }];
     case "error":
-      return { type: "error", message: { role: "error", content: [{ type: "text", text: ev.error?.message ?? "claude error" }] } };
+      return [{ type: "error", message: { role: "error", content: [{ type: "text", text: ev.error?.message ?? "claude error" }] } }];
     case "user":
-      return null; // echo of our own stdin write — filtered
+      return []; // echo of our own stdin write — filtered
     default:
-      return null; // unknown — forward-compat, caller logs at debug
+      return []; // unknown — forward-compat, caller logs at debug
   }
+}
+
+/** Single-event compat wrapper (claude-detector + existing consumers read one event per line). */
+export function mapClaudeEvent(line: string): ChildSessionEvent | null {
+  return mapClaudeEvents(line)[0] ?? null;
 }

package/src/backend/claude-session.ts

@@ -2,7 +2,7 @@
 import type { ChildProcess } from "node:child_process";
 import { createInterface } from "node:readline";
 import type { ChildSession, ChildSessionEvent } from "../engine/spawnSubagent.ts";
-import { mapClaudeEvent } from "./claude-events.ts";
+import { mapClaudeEvents } from "./claude-events.ts";
 import type { ResumeStore } from "./resume-store.ts";
 
 export class ClaudeChildSession implements ChildSession {
@@ -24,16 +24,16 @@ export class ClaudeChildSession implements ChildSession {
   }
 
   private onLine(line: string): void {
-    const ev = mapClaudeEvent(line);
-    if (!ev) return;
-    if (ev.type === "session_init" && ev.backendSessionId && !this.initCaptured) {
-      this.initCaptured = true;
-      this.resumeStore.set("claude", this.sessionKey, ev.backendSessionId);
+    for (const ev of mapClaudeEvents(line)) {
+      if (ev.type === "session_init" && ev.backendSessionId && !this.initCaptured) {
+        this.initCaptured = true;
+        this.resumeStore.set("claude", this.sessionKey, ev.backendSessionId);
+      }
+      if (ev.type === "turn_end" || ev.type === "error") {
+        if (this.turnResolve) { this.turnResolve(); this.turnResolve = null; }
+      }
+      for (const h of this.handlers) h(ev);
     }
-    if (ev.type === "turn_end" || ev.type === "error") {
-      if (this.turnResolve) { const r = this.turnResolve; this.turnResolve = null; r(); }
-    }
-    for (const h of this.handlers) h(ev);
   }
 
   async prompt(text: string): Promise<void> {

package/src/engine/auto-fallback.ts

@@ -0,0 +1,19 @@
+// src/engine/auto-fallback.ts
+// #58: resolve the ARMORY_FLEET_MODEL_FALLBACK=auto sentinel — pick a fallback model from the
+// runtime's configured+available snapshot without the operator naming one. Prefers a model from
+// a DIFFERENT provider than the session model (a real fallback family, per the "Ollama primary +
+// OpenRouter fallback" pattern the feature was named for); if every available model shares the
+// session's provider, a different model id on that provider. undefined when nothing differs
+// (single-model setups) — the caller keeps auto-retry off and surfaces why.
+
+export function resolveAutoFallback(
+  available: ReadonlyArray<{ provider: string; id: string }>,
+  parentModel: { provider: string; id: string },
+): string | undefined {
+  const parentProvider = parentModel.provider || "";
+  const parentKey = `${parentModel.provider}/${parentModel.id}`;
+  const differentProvider = available.filter((m) => m.provider !== parentProvider);
+  const pool = differentProvider.length > 0 ? differentProvider : available;
+  const pick = pool.find((m) => `${m.provider}/${m.id}` !== parentKey);
+  return pick ? `${pick.provider}/${pick.id}` : undefined;
+}

package/src/engine/retry-fallback.ts

@@ -19,7 +19,14 @@ export function withModelFallbackRetry(spawn: SpawnFn, fallback: string | undefi
   return async (opts) => {
     const first = await spawn(opts);
     if (first.status === "failed" && first.retryable && fallback !== first.model && !signal?.aborted) {
-      return spawn({ ...opts, model: fallback });
+      const second = await spawn({ ...opts, model: fallback });
+      // #59: when the fallback also fails, compose the primary's failure into the surfaced error
+      // (same contract as the direct-foreground path in tools/subagent.ts) — the fallback's error
+      // alone masks why the primary failed.
+      if (second.status === "failed" && first.error && first.error !== second.error) {
+        second.error = `primary '${first.model}' failed: ${first.error}; fallback '${fallback}' failed: ${second.error ?? second.status}`;
+      }
+      return second;
     }
     return first;
   };

package/src/engine/spawnSubagent.ts

@@ -44,6 +44,13 @@ export interface ChildSessionEvent {
   };
   /** Emitted by a backend on session init (SPEC-3). Drives runRecord.backendSessionId. */
   backendSessionId?: string;
+  /** tool_execution_end fields (pi SDK native; claude mapper synthesizes from tool_use blocks, #61).
+   *  Consumers currently cast — these make the real shape type-visible. */
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: unknown;
+  isError?: boolean;
 }
 
 export interface ChildSession {
@@ -182,6 +189,9 @@ export interface SpawnResult {
    *  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;
+  /** #61: number of executed tool calls. A "completed" run with 0 is the premature-return
+   *  shape (the child narrated and ended without acting) — the tool flags it in the result. */
+  toolCallCount?: number;
 }
 
 /** #49: extract file paths a tool event touched, for the structured partial-result report.
@@ -190,11 +200,13 @@ export interface SpawnResult {
 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") {
+  // Case-insensitive: pi tools are lowercase ("edit"), claude's are capitalized ("Edit").
+  const name = toolName.toLowerCase();
+  if (name === "edit" || name === "write") {
     const p = typeof a.path === "string" ? a.path : typeof a.file_path === "string" ? a.file_path : undefined;
     return p ? [p] : [];
   }
-  if (toolName === "bash") {
+  if (name === "bash") {
     const cmd = typeof a.command === "string" ? a.command : undefined;
     if (!cmd) return [];
     const out: string[] = [];
@@ -363,6 +375,12 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     // 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"
+    // #61: executed-tool count — a "completed" run with zero tool calls is the premature-return
+    // shape (read/narrate/end without acting); the tool flags it so the controller verifies.
+    let toolCallCount = 0;
+    // #60: args live on tool_execution_start (the SDK's end event carries none) — capture per
+    // toolCallId so extractTouchedFiles + the journal see the real args on real runs.
+    const pendingToolArgs = new Map<string, unknown>();
 
     // #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"
@@ -430,12 +448,20 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
           aborted = true;
           void session.abort();
         }
+      } else if (e.type === "tool_execution_start") {
+        pendingToolArgs.set((e as { toolCallId?: string }).toolCallId ?? "", (e as { args?: unknown }).args);   // #60
       } else if (e.type === "tool_execution_end") {
         // #49: track mutated files for the structured partial-result report.
+        toolCallCount += 1;   // #61
+        const toolCallId = (e as { toolCallId?: string }).toolCallId ?? "";
+        // #60: real args from the start event; `?? e.args` keeps hand-rolled fakes that put args
+        // on the end event working (the SDK never does).
+        const args = pendingToolArgs.get(toolCallId) ?? (e as { args?: unknown }).args;
+        pendingToolArgs.delete(toolCallId);
         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);
+        for (const f of extractTouchedFiles((e as { toolName?: string }).toolName ?? "", 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));
+          opts.runLog?.append(runId, buildToolEvent((e as any).toolName, args, (e as any).result, (e as any).isError ?? false, turnIdx));
         } catch { /* best-effort */ }
       }
       // #23: liveness heartbeat — update the run record on meaningful events so the fleet widget
@@ -524,7 +550,7 @@ 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, filesTouchedList, reachedSummary);
+    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal, costTotal, contextTokens, modelError ? true : undefined, filesTouchedList, reachedSummary, toolCallCount);
   } 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).
@@ -547,7 +573,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,
+  filesTouched?: string[], reachedSummary?: boolean, toolCallCount = 0,
 ): Promise<SpawnResult> {
   if (finalizedRunIds.has(runId)) {
     // Already finalized — return the existing registry record's result without re-appending.
@@ -557,7 +583,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,
+      filesTouched, reachedSummary, toolCallCount,
     };
   }
   finalizedRunIds.add(runId);
@@ -574,6 +600,13 @@ async function finishRun(
       type: "run:ended", runId, status, endedAt,
       resultSummary: finalText.slice(0, 120), tokenTotal, costTotal, contextTokens,
       resumedFrom: opts.resumeLink, forkedFrom: opts.forkLink,
+      // #59: journal the failure reason — the archived failing runs had run:ended with an empty
+      // resultSummary and no error field, making post-hoc diagnosis from the journal impossible.
+      error,
+      // #61: executed-tool count (the zero-work premature-return signal, post-hoc too).
+      toolCallCount,
+      // #60: what the run mutated (was only on the SpawnResult; the durable journal lacked it).
+      filesTouched,
     });
   } catch { /* best-effort: journal is the index, not the product */ }
   // SPEC-4: lifecycle phase children skip the per-run todo reconciliation — the lifecycle
@@ -592,6 +625,6 @@ async function finishRun(
   return {
     status, finalText, runId, todoId, agent: agentName, model,
     durationMs: endedAt - startedAt, tokenTotal, costTotal, contextTokens, error, retryable,
-    filesTouched, reachedSummary,
+    filesTouched, reachedSummary, toolCallCount,
   };
 }

package/src/index.ts

@@ -18,6 +18,7 @@ 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 { resolveAutoFallback } from "./engine/auto-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";
@@ -204,7 +205,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // #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;
+  // #39 tail + #58: the global default fallback. Non-"auto" env values are used verbatim;
+  // "auto" is resolved per-session in session_start (it needs the session model to differ from).
+  const rawModelFallback = process.env.ARMORY_FLEET_MODEL_FALLBACK || undefined;
+  deps.defaultModelFallback = rawModelFallback === "auto" ? undefined : rawModelFallback;
   // SPEC-6-5: cross-cwd dispatch notify hook (wired per-session in session_start below).
   // Placeholder; the real wiring happens in session_start where ctx is in scope.
 
@@ -309,6 +313,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     refreshLifecycles(ctx);
     const m = ctx.model;
     deps.parentModel = m ? { provider: m.provider, id: m.id } : { provider: "", id: "" };
+    // #58: ARMORY_FLEET_MODEL_FALLBACK=auto — pick a fallback from the configured+available
+    // snapshot that differs from the session model (different provider preferred). Unresolvable
+    // (single-model setup) → stay off + say why once per session.
+    if (rawModelFallback === "auto") {
+      deps.defaultModelFallback = resolveAutoFallback(modelRuntime.getAvailableSnapshot(), deps.parentModel);
+      if (!deps.defaultModelFallback) {
+        ctx.ui.notify("ARMORY_FLEET_MODEL_FALLBACK=auto, but no alternative configured model is available — auto-retry stays off", "warning");
+      }
+    }
     deps.parentCwd = ctx.cwd;
     deps.onNotify = (m, k) => ctx.ui.notify(m, k ?? "info");
     // SPEC-5a: build the per-session async runner + scheduler, start firing, scan for interrupted runs.

package/src/runtime/run-log.ts

@@ -33,6 +33,12 @@ export interface RunEndedEvent {
   costTotal?: number;
   /** SPEC-6-1: latest context-token snapshot at run end. */
   contextTokens?: number;
+  /** #59: the failure reason on failed runs (post-hoc diagnosability from the journal). */
+  error?: string;
+  /** #61: executed-tool count (the zero-work premature-return signal, post-hoc too). */
+  toolCallCount?: number;
+  /** #60: file paths the run mutated (post-hoc — was previously SpawnResult-only). */
+  filesTouched?: string[];
 }
 export type RunLogEvent = RunMetaEvent | MessageEvent | ToolEvent | RunEndedEvent;
 

package/src/tools/subagent.ts

@@ -231,14 +231,43 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         });
         retriedWithModel = fallback;
       }
+      // #59: when the fallback retry ALSO fails, surface the PRIMARY's failure too — returning
+      // only the fallback's error masked why the primary (e.g. an explicit model string) failed
+      // at all, making provider diagnosis impossible from the controller's seat.
+      if (retriedWithModel && finalRes.status === "failed" && res.error && res.error !== finalRes.error) {
+        finalRes = {
+          ...finalRes,
+          error: `primary '${res.model}' failed: ${res.error}; fallback '${retriedWithModel}' failed: ${finalRes.error ?? finalRes.status}`,
+        };
+      }
+      // #58: a retryable failure with NO fallback configured (neither per-dispatch nor global)
+      // means the auto-retry silently didn't fire — surface that, and how to enable it, exactly
+      // when it matters. Mutually exclusive with the #59 composition above (a retry implies a
+      // fallback was configured).
+      if (finalRes.status === "failed" && finalRes.retryable && !fallback) {
+        finalRes = {
+          ...finalRes,
+          error: `${finalRes.error ?? finalRes.status}\n(no modelFallback configured — pass modelFallback or set ARMORY_FLEET_MODEL_FALLBACK to enable one-shot auto-retry)`,
+        };
+      }
       const isError = finalRes.status === "failed" || finalRes.status === "aborted";
+      // #61: a run that "completed" without a single tool call is usually a premature return
+      // (the child narrated a plan and ended without acting) — flag it in-band so the controller
+      // verifies (git status/log) instead of trusting a terse planning statement as a completion.
+      const zeroToolRun = !isError && (finalRes.toolCallCount ?? 0) === 0;
+      const resultText = isError
+        ? (finalRes.error ?? finalRes.status)
+        : zeroToolRun
+          ? `[FLEET] zero-tool-call run — likely a premature return (#61); verify with git status/log before trusting this result.\n\n${finalRes.finalText}`
+          : finalRes.finalText;
       return {
-        content: [{ type: "text" as const, text: isError ? (finalRes.error ?? finalRes.status) : finalRes.finalText }],
+        content: [{ type: "text" as const, text: resultText }],
         details: {
           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,
+          toolCallCount: finalRes.toolCallCount,   // #61: zero = the premature-return signal
         },
         isError,
       };