@getpipher/armory-fleet 0.12.5 → 0.14.0

package/README.md

@@ -308,6 +308,24 @@ Every workflow run is **journaled** (`workflows/journal.ts`) and **resumable**.
 
 ---
 
+## Migration (v0.13.0 — SPEC-6-5 cwd isolation)
+
+- **`cwd` param on the `subagent` tool** (default = the session cwd, backward-compat). Pass it to scope a child's working dir + context (AGENTS.md cascade, skills, memory) to a dispatch target outside the session cwd — the #20 confabulation fix. Cross-cwd dispatches surface a `↗<basename>` glyph in the fleet widget + a spawn-time notify.
+- **`userMemory` default flip:** the global cross-project user memory scope (`/__armory-fleet-user__`) is no longer hydrated by default. If you populated that dir + relied on it, add `userMemory: true` to the agent frontmatter (only meaningful with `memoryHydrate: true`). TS consumers constructing `AgentDef` literals must now include `userMemory: boolean` (required field; use `false` for the old default behavior).
+- **Lifecycle `cwd` field:** lifecycles accept an optional `cwd` frontmatter field to pin a target repo; absent → the entry-point cwd (the panel's chosen cwd, or the dispatching `subagent` tool's cwd/session cwd). When present, it overrides the entry-point cwd for all phases.
+- **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.12.5",
+  "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-factory.ts

@@ -22,7 +22,7 @@ export function createClaudeChildFactory(
       if (!detector?.schemaOk) {
         throw new Error(`claude backend unavailable: ${detector?.note ?? "schema not ok"}`);
       }
-      const memoryBlock = opts.agent.memoryHydrate ? opts.memoryPort.renderScopes(memoryScopesFor(opts.cwd)) : "";
+      const memoryBlock = opts.agent.memoryHydrate ? opts.memoryPort.renderScopes(memoryScopesFor(opts.cwd, { includeUser: opts.agent.userMemory ?? false })) : "";
       const sys = memoryBlock ? `${opts.rolePrompt}\n\n${memoryBlock}` : opts.rolePrompt;
       const resumeId = resumeStore.get("claude", opts.agent.sessionKey);
 

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/child-loader.ts

@@ -41,9 +41,11 @@ export function composeChildPrompt(args: { rolePrompt: string; memoryBlock: stri
   return [args.rolePrompt, args.memoryBlock, args.base].filter((s) => s && s.trim().length > 0).join("\n\n");
 }
 
-/** Build the three memory scopes for a child: project=cwd, local=parent dir, user=sentinel. */
-export function memoryScopesFor(cwd: string): { project: string; local: string; user: string } {
-  return { project: cwd, local: dirname(cwd) || cwd, user: USER_PSEUDO_CWD };
+/** Build the memory scopes for a child: project=cwd, local=parent dir; user only when opted in.
+ *  #20/SPEC-6-5: the user pseudo-scope (`/__armory-fleet-user__`) is a cross-project bleed by
+ *  construction — omit it unless the agent declares `userMemory: true`. */
+export function memoryScopesFor(cwd: string, opts?: { includeUser?: boolean }): { project: string; local: string; user?: string } {
+  return { project: cwd, local: dirname(cwd) || cwd, ...(opts?.includeUser ? { user: USER_PSEUDO_CWD } : {}) };
 }
 
 /** #40: resolve extra skill dirs to scan for the child, beyond the default `~/.pi/agent/skills`.
@@ -73,7 +75,7 @@ export interface ChildLoaderOpts {
 
 /** Build the fleet CustomResourceLoader for a child session. */
 export function buildChildLoader(opts: ChildLoaderOpts): DefaultResourceLoader {
-  const scopes = memoryScopesFor(opts.cwd);
+  const scopes = memoryScopesFor(opts.cwd, { includeUser: opts.agent.userMemory ?? false });
   const memoryBlock = opts.agent.memoryHydrate ? opts.memoryPort.renderScopes(scopes) : "";
   return new DefaultResourceLoader({
     cwd: opts.cwd,

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/run-registry.ts

@@ -28,10 +28,19 @@ export interface RunRecord {
   costTotal?: number;
   /** SPEC-6-1: latest context tokens (calcContextTokens(usage)) — live snapshot. */
   contextTokens?: number;
+  /** #32: context-token snapshot at the end of turn 1 (the armory substrate baseline).
+   *  Set once on the first assistant message_end; live-only (not journaled). The widget
+   *  compares current contextTokens against this to label the tok/ctx% segment as
+   *  "substrate" (flat across turns) vs "work" (growing) — see src/panel/widget-rows.ts. */
+  substrateBaseline?: number;
   /** SPEC-6-1: the tier name this run used (for Tiers-view "used by" + per-tier spend). */
   tier?: string;
   /** SPEC-6-2: the cwd this run belongs to (widget cross-cwd filter + reconcile ownership). */
   cwd: string;
+  /** SPEC-6-5: the session cwd the dispatch originated from (live; = parentCwd). Set at spawn.
+   *  Lets the widget compute cross-cwd (`cwd !== sessionCwd`) for the ↗ glyph without re-reading
+   *  the journal. Live-only counterpart to RunMetaEvent.sessionCwd. */
+  sessionCwd?: string;
   /** SPEC-6-2: the backend (probe dispatch: pi→handle, claude→pid). */
   backend: BackendId;
   /** SPEC-6-2: claude-backend child PID (cross-process liveness probe). */

package/src/engine/spawnSubagent.ts

@@ -5,6 +5,7 @@ import type { MemoryHydratePort } from "../memory-hydrate/port.ts";
 import type { VisionPort } from "../vision/port.ts";
 import type { BackendRegistry } from "../backend/port.ts";
 import { genRunId, RunRegistry } from "./run-registry.ts";
+import type { RunRecord } from "./run-registry.ts";
 import { createTurnBudget, DEFAULT_MAX_TURNS } from "./turn-budget.ts";
 import type { ForegroundLock } from "./concurrency-lock.ts";
 import type { RunLog } from "../runtime/run-log.ts";
@@ -43,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 {
@@ -116,6 +124,10 @@ export interface SpawnOptions {
   backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory — engine looks up by agentDef.backend
   parentModel: { provider: string; id: string };
   parentCwd: string;
+  /** SPEC-6-5: the dispatch target's working directory. Default = parentCwd (the session cwd, backward-compat).
+   *  When set, all child-scoped sites use this cwd (factory.create, RunRecord.cwd, run:meta cwd);
+   *  session-scoped audit (`sessionCwd`) keeps parentCwd. */
+  cwd?: string;
   memoryPort?: MemoryHydratePort;
   visionPort?: VisionPort;
   signal?: AbortSignal;
@@ -177,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.
@@ -185,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[] = [];
@@ -215,6 +232,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
   const track = opts.track ?? true;
   const maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
   const startedAt = Date.now();
+  const childCwd = opts.cwd ?? opts.parentCwd;
 
   // #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
@@ -287,7 +305,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       runId, agent: agentDef.name, model, task: opts.task, track,
       todoId: null, status: "running", startedAt,
       tier: tier?.name, costTotal: 0, contextTokens: 0,
-      cwd: opts.parentCwd, backend: backendId,
+      cwd: childCwd, sessionCwd: opts.parentCwd, backend: backendId,
     });
 
     // todo-sync (before) — only when both caller tracks AND agent allows todoSync
@@ -311,7 +329,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     for (const cand of candidates) {
       try {
         const result = await backend.factory.create({
-          cwd: opts.parentCwd,
+          cwd: childCwd,
           model: cand,
           thinkingLevel: childAgent.thinkingLevel,
           tools,
@@ -345,6 +363,10 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     let costTotal = 0;
     let contextTokens = 0;
     let turnIdx = -1;
+    // #32: substrate baseline — the turn-1 context-token snapshot (armory substrate overhead).
+    // Captured once on the first assistant message_end (turnIdx === 0); threaded to the RunRecord
+    // so the widget can classify the tok/ctx% segment as "substrate" (flat) vs "work" (growing).
+    let substrateBaseline: number | undefined;
     // #26/#22: declared before subscribe() because some child sessions emit events
     // synchronously inside subscribe() (temporal-dead-zone guard).
     let modelError: string | undefined;   // model-call failure surfaced via stopReason "error"
@@ -353,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"
@@ -373,7 +401,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       if (e.type === "session_init" && e.backendSessionId) {
         opts.runRegistry.update(runId, { backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey });
         try {
-          opts.runLog?.append(runId, { type: "run:meta", runId, agent: agentDef.name, model, task: opts.task, startedAt, track, todoId, backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey, cwd: opts.parentCwd, pid: (session as { proc?: { pid?: number } }).proc?.pid });
+          opts.runLog?.append(runId, { type: "run:meta", runId, agent: agentDef.name, model, task: opts.task, startedAt, track, todoId, backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey, cwd: childCwd, sessionCwd: opts.parentCwd, pid: (session as { proc?: { pid?: number } }).proc?.pid });
         } catch { /* best-effort */ }
       } else if (e.type === "turn_start") {
         turnIdx++;
@@ -403,7 +431,15 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
         const cost = u?.cost?.total ?? 0;
         costTotal += cost;
         contextTokens = calcContextTokens(u ?? {});
-        opts.runRegistry.update(runId, { costTotal, contextTokens, tokenTotal });
+        // #32: capture the substrate baseline at the end of turn 1 (the first assistant
+        // message_end). The turn-1 context is dominated by the armory substrate (system prompt +
+        // skills + memory); subsequent turns barely grow it unless real work adds tool results.
+        const patch: Partial<RunRecord> = { costTotal, contextTokens, tokenTotal };
+        if (substrateBaseline === undefined && turnIdx === 0 && contextTokens > 0) {
+          substrateBaseline = contextTokens;
+          patch.substrateBaseline = substrateBaseline;
+        }
+        opts.runRegistry.update(runId, patch);
         try {
           opts.runLog?.append(runId, { type: "message", role: "assistant", text, usage: { total: turnTokens, input: u?.input, output: u?.output, cacheRead: u?.cacheRead, cacheWrite: u?.cacheWrite, cost: u?.cost }, turnIndex: turnIdx });
         } catch { /* best-effort */ }
@@ -412,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
@@ -506,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).
@@ -529,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.
@@ -539,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);
@@ -556,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
@@ -574,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,12 @@ 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.
 
   // #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
@@ -307,7 +313,17 @@ 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.
     const dir = fleetDir(ctx.cwd);
     // SPEC-5b-1: per-session RunLog at .pi/fleet/conversations/ (separate from the

package/src/lifecycle/lifecycle-types.ts

@@ -34,6 +34,10 @@ export interface LifecycleDef {
   description: string;
   /** Lifecycle-wide default backend; absent → "pi". */
   backend: BackendId;
+  /** SPEC-6-5: pin this lifecycle to a target working directory. Absent → the entry-point cwd
+   *  (the panel's chosen cwd, or the dispatching `subagent` tool's cwd/session cwd). When present,
+   *  overrides the entry-point cwd for all phases. */
+  cwd?: string;
   phases: PhaseDef[];
   source: AgentSource;
   filePath: string;

package/src/lifecycle/registry.ts

@@ -38,6 +38,7 @@ export function parseLifecycleFile(content: string, filePath: string, source: Ag
     throw new LifecycleParseError(`${filePath}: invalid backend '${rawBackend}' (must be 'pi' | 'claude')`);
   }
   const backend = rawBackend as BackendId;
+  const cwd = typeof raw.cwd === "string" && raw.cwd.trim() ? raw.cwd.trim() : undefined;
 
   if (!Array.isArray(raw.phases) || raw.phases.length === 0) {
     throw new LifecycleParseError(`${filePath}: phases must be a non-empty array`);
@@ -100,7 +101,7 @@ export function parseLifecycleFile(content: string, filePath: string, source: Ag
   // The terminal phase never checkpoints after it (the lifecycle is done) — §5.4.
   if (phases.length > 0) phases[phases.length - 1]!.checkpoint = false;
 
-  return { name, description, backend, phases, source, filePath };
+  return { name, description, backend, phases, source, filePath, ...(cwd ? { cwd } : {}) };
 }
 
 /** Split the markdown body into a map of phase-name → prompt-template, by `## <name>` H2 headings. */

package/src/lifecycle/run-lifecycle.ts

@@ -25,6 +25,8 @@ export interface PhaseSpawnOpts {
   skills: string[];
   /** The resolved backend for this phase (phase.backend → lifecycle.backend → "pi"). */
   backend: BackendId;
+  /** SPEC-6-5: the resolved lifecycle cwd (lifecycle.cwd ?? entryCwd) the phase child runs in. */
+  cwd?: string;
   model?: string;
 }
 export type SpawnFn = (opts: PhaseSpawnOpts) => Promise<SpawnResult>;
@@ -57,6 +59,9 @@ export interface LifecycleRunOpts {
   worktreePath?: string;
   /** SPEC-5a: the base ref to diff against (default "HEAD"). */
   baseRef?: string;
+  /** SPEC-6-5: the entry-point cwd (the panel's chosen cwd, or the dispatching subagent tool's
+   *  cwd/session cwd). The lifecycle's `cwd` field, if present, overrides this. */
+  entryCwd?: string;
 }
 
 export interface LifecycleRunResult {
@@ -86,6 +91,8 @@ export async function runLifecycle(task: string, lifecycleName: string, opts: Li
     const available = [...deps.registry.keys()].sort().join(", ");
     return failResult("", startedAt, `lifecycle '${lifecycleName}' not found; available: ${available}`, lifecycleName, task, opts.mode, [], null);
   }
+  // SPEC-6-5: lifecycle cwd field overrides the entry-point cwd (entryCwd).
+  const lifecycleCwd = lifecycle.cwd ?? opts.entryCwd;
 
   const runId = deps.genRunId();
   const lifecycleBackend = lifecycle.backend;
@@ -151,7 +158,7 @@ export async function runLifecycle(task: string, lifecycleName: string, opts: Li
       // phase's skills (Q1=B) and routes to the phase's backend (Q4=C) — not the agent's defaults.
       let spawnRes: import("../engine/spawnSubagent.ts").SpawnResult;
       try {
-        spawnRes = await deps.spawn({ agent: agentName, task: prompt, lifecycleTodoId: todoId, skills, backend });
+        spawnRes = await deps.spawn({ agent: agentName, task: prompt, lifecycleTodoId: todoId, skills, backend, cwd: lifecycleCwd });
       } catch (e) {
         // spawn should return a failed result, not throw — but guard anyway so a throwing spawn
         // can't orphan the lifecycle (treat as a phase failure).

package/src/memory-hydrate/adapter.ts

@@ -5,7 +5,7 @@ import type { MemoryHydratePort, MemoryScopes } from "./port.ts";
 export class ArmoryMemoryAdapter implements MemoryHydratePort {
   renderScopes(scopes: MemoryScopes): string {
     return [scopes.project, scopes.local, scopes.user]
-      .filter((cwd) => listMemory(cwd).length > 0)   // skip empty scopes cleanly (no placeholder to render)
+      .filter((cwd): cwd is string => cwd != null && listMemory(cwd).length > 0)   // skip empty scopes cleanly (no placeholder to render)
       .map((cwd) => renderMemoryBlock(cwd))           // armory-memory's existing cwd-keyed primitive
       .join("\n\n");                                   // → "" when all three empty
   }

package/src/memory-hydrate/port.ts

@@ -4,8 +4,9 @@ export interface MemoryScopes {
   project: string;
   /** Immediate parent directory of the project cwd (workspace/org level). */
   local: string;
-  /** Fixed pseudo-cwd for global cross-project user memory. */
-  user: string;
+  /** Optional — only present when the agent opted in via `userMemory: true` (SPEC-6-5).
+   *  The user scope is a cross-project memory bleed by construction; omitted unless explicitly enabled. */
+  user?: string;
 }
 export interface MemoryHydratePort {
   /** Render the three-scope memory block (project → local → user), concatenated. Empty string when all scopes empty. */

package/src/panel/fleet-panel.ts

@@ -96,7 +96,8 @@ export class FleetPanel extends Container {
   private lcRunMode = false;
   private lcTaskInput: Input | null = null;
   private lcNameInput: Input | null = null;
-  private lcPhase: "task" | "name" = "task";
+  private lcCwdInput: Input | null = null;
+  private lcPhase: "task" | "name" | "cwd" = "task";
   // SPEC-4: pending checkpoint (interactive Continue/Revise/Abort)
   private pendingCheckpoint: { phase: PhaseRecord; resolve: (d: CheckpointDecision) => void } | null = null;
   private lcReviseInput: Input | null = null;
@@ -359,10 +360,10 @@ export class FleetPanel extends Container {
       this.addChild(new Text(this.theme.fg("accent", prompt), 0, 0));
       this.addChild(this.schedPhase === "task" ? this.schedTaskInput! : this.schedPhase === "expr" ? this.schedExprInput! : this.schedNameInput!);
       this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
-    } else if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput)) {
-      const prompt = this.lcPhase === "task" ? "  task> " : "  lifecycle name (blank=default)> ";
+    } else if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput || this.lcCwdInput)) {
+      const prompt = this.lcPhase === "task" ? "  task> " : this.lcPhase === "name" ? "  lifecycle name (blank=default)> " : "  cwd (blank=session cwd)> ";
       this.addChild(new Text(this.theme.fg("accent", prompt), 0, 0));
-      this.addChild(this.lcPhase === "task" ? this.lcTaskInput! : this.lcNameInput!);
+      this.addChild(this.lcPhase === "task" ? this.lcTaskInput! : this.lcPhase === "name" ? this.lcNameInput! : this.lcCwdInput!);
       this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
     } else if (this.pendingCheckpoint && !this.lcRevising) {
       const pc = this.pendingCheckpoint;
@@ -586,9 +587,9 @@ export class FleetPanel extends Container {
       this.invalidate();
       return;
     }
-    if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput)) {
+    if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput || this.lcCwdInput)) {
       if (matchesKey(data, "escape")) { this.cancelLifecycleRun(); return; }
-      (this.lcPhase === "task" ? this.lcTaskInput! : this.lcNameInput!).handleInput(data);
+      (this.lcPhase === "task" ? this.lcTaskInput! : this.lcPhase === "name" ? this.lcNameInput! : this.lcCwdInput!).handleInput(data);
       this.invalidate();
       return;
     }
@@ -1131,9 +1132,18 @@ export class FleetPanel extends Container {
       this.lcNameInput = new Input();
       this.lcNameInput.onSubmit = (name: string) => {
         const lcName = name.trim() || "default";
-        void this.executeLifecycleRun(task.trim(), lcName);
+        this.lcPhase = "cwd";
+        this.lcCwdInput = new Input();
+        // SPEC-6-5: 3rd input step — the dispatch cwd. Prefilled with the session cwd; Enter
+        //  accepts it, Escape accepts the default (mirrors the name step's Escape-accepts-default).
+        this.lcCwdInput.onSubmit = (cwd: string) => {
+          const picked = cwd.trim() || this.deps.parentCwd;
+          void this.executeLifecycleRun(task.trim(), lcName, picked);
+        };
+        this.lcCwdInput.onEscape = () => { void this.executeLifecycleRun(task.trim(), lcName, this.deps.parentCwd); };
+        this.renderShell();
       };
-      this.lcNameInput.onEscape = () => { void this.executeLifecycleRun(task.trim(), "default"); };
+      this.lcNameInput.onEscape = () => { void this.executeLifecycleRun(task.trim(), "default", this.deps.parentCwd); };
       this.renderShell();
     };
     this.lcTaskInput.onEscape = () => this.cancelLifecycleRun();
@@ -1145,18 +1155,27 @@ export class FleetPanel extends Container {
     this.lcRunMode = false;
     this.lcTaskInput = null;
     this.lcNameInput = null;
+    this.lcCwdInput = null;
     this.renderShell();
   }
 
-  private async executeLifecycleRun(task: string, lifecycleName: string): Promise<void> {
+  private async executeLifecycleRun(task: string, lifecycleName: string, cwd: string): Promise<void> {
     this.lcRunMode = false;
     this.lcTaskInput = null;
     this.lcNameInput = null;
+    this.lcCwdInput = null;
     this.renderShell();
     if (!this.deps.lifecycleRegistry.has(lifecycleName)) {
       this.onNotify(`lifecycle '${lifecycleName}' not found; available: ${[...this.deps.lifecycleRegistry.keys()].sort().join(", ")}`, "error");
       return;
     }
+    // SPEC-6-5: validate the chosen cwd (exists + is a dir) before spawning; surface cross-cwd.
+    const { resolveDispatchCwd } = await import("../tools/subagent.ts");
+    const { cwd: resolvedCwd, error: cwdErr } = resolveDispatchCwd(cwd, this.deps.parentCwd);
+    if (cwdErr) { this.onNotify(cwdErr, "error"); return; }
+    if (resolvedCwd && resolvedCwd !== this.deps.parentCwd) {
+      this.onNotify("scoped to " + resolvedCwd + " (≠ session " + this.deps.parentCwd + ")", "info");
+    }
     const onCheckpoint: CheckpointFn = (phase) => new Promise<CheckpointDecision>((resolve) => {
       this.pendingCheckpoint = { phase, resolve };
       this.renderShell();
@@ -1171,10 +1190,11 @@ export class FleetPanel extends Container {
           registry: this.deps.registry, todoSync: this.deps.todoSync, runRegistry: this.deps.runRegistry, lock: this.deps.lock,
           backendRegistry: this.deps.backendRegistry, parentModel: this.deps.parentModel, parentCwd: this.deps.parentCwd,
           runLog: this.deps.runLog,
+          cwd: o.cwd,
         });
       },
     };
-    const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: "checkpointed", onCheckpoint });
+    const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: "checkpointed", onCheckpoint, entryCwd: resolvedCwd });
     this.pendingCheckpoint = null;
     // record the run so the Lifecycle view shows it
     this.deps.lifecycleRuns.set(res.runId, res);

package/src/panel/widget-rows.ts

@@ -8,6 +8,7 @@
 // list below editor" intent was never achievable via pi widgets (editor keeps keyboard focus).
 // `/fleet` is the navigable action surface; this one above-editor widget is the glance surface.
 import { fmtDuration, fmtTokens } from "./rows.ts";
+import { basename } from "node:path";
 import type { RunRecord } from "../engine/run-registry.ts";
 import type { BgRunStatus } from "./rows.ts";
 
@@ -16,6 +17,11 @@ import type { BgRunStatus } from "./rows.ts";
 export const LIVENESS_THRESHOLD_MS = 30_000;
 /** #23: a run whose last event is older than this is flagged stale ("are events still arriving?"). */
 export const STALE_THRESHOLD_MS = 60_000;
+/** #32: once past turn 1, if contextTokens has grown by less than this fraction of the
+ *  turn-1 substrate baseline, the tok/ctx% segment is labeled "substrate" (flat overhead)
+ *  rather than "work" (growing from tool results). 5% — the dogfood evidence showed ~0.2%/turn
+ *  growth on a substrate-dominated run vs tens-of-K (multi-%) once real tool output lands. */
+export const SUBSTRATE_GROWTH_THRESHOLD = 0.05;
 
 export interface WidgetRun {
   runId: string;
@@ -34,6 +40,10 @@ export interface WidgetRun {
   task?: string;
   /** SPEC-6-1: latest context-token snapshot (for ctx% segment). */
   contextTokens?: number;
+  /** #32: context-token baseline at end of turn 1 (armory substrate overhead). When the
+   *  current contextTokens has grown little beyond this baseline across turns, the tok/ctx%
+   *  segment is labeled "substrate" (flat overhead) vs "work" (growing from tool results). */
+  substrateBaseline?: number;
   /** SPEC-6-1: max context window for the resolved model (set by controller — Task 7). */
   maxContext?: number;
   /** SPEC-6-1: cumulative $ (for the $ segment). */
@@ -46,6 +56,10 @@ export interface WidgetRun {
   lastEventClass?: string;
   /** #23: liveness — timestamp (ms) of the last event ("events still arriving?"). */
   lastEventAt?: number;
+  /** SPEC-6-5: the run's (child) cwd — from RunRecord.cwd. */
+  cwd?: string;
+  /** SPEC-6-5: the session cwd (parentCwd) — from RunRecord.sessionCwd. When cwd !== sessionCwd the widget shows a ↗ glyph. */
+  sessionCwd?: string;
 }
 
 export function toWidgetRun(r: RunRecord): WidgetRun {
@@ -53,8 +67,9 @@ export function toWidgetRun(r: RunRecord): WidgetRun {
     runId: r.runId, agent: r.agent, status: r.status,
     startedAt: r.startedAt, endedAt: r.endedAt, tokenTotal: r.tokenTotal,
     kind: "fg",
-    task: r.task, costTotal: r.costTotal, contextTokens: r.contextTokens,
+    task: r.task, costTotal: r.costTotal, contextTokens: r.contextTokens, substrateBaseline: r.substrateBaseline,
     turnCount: r.turnCount, turnMax: r.turnMax, lastEventClass: r.lastEventClass, lastEventAt: r.lastEventAt,
+    cwd: r.cwd, sessionCwd: r.sessionCwd,
   };
 }
 
@@ -102,6 +117,9 @@ function widgetLine(r: WidgetRun, now: number): string {
 
   // fg: task excerpt as primary label (fallback to runId if no task)
   const label = r.task ? `"${r.task.slice(0, 40)}"` : r.runId;
+  // SPEC-6-5: cross-cwd glyph — when the run's cwd differs from the session cwd, mark it so the
+  // operator sees "this run is scoped to a different project" at a glance. Same-cwd → no glyph.
+  const crossCwd = (r.cwd && r.sessionCwd && r.cwd !== r.sessionCwd) ? `  ↗${basename(r.cwd)}` : "";
   const agentSeg = r.agent && r.agent !== "general-purpose" ? `  · ${r.agent}` : "";
   // #23: liveness — only after LIVENESS_THRESHOLD_MS, to keep short runs concise (per acceptance).
   // turn N/max + last-event class (no prompt content, no args/results — only the tool name)
@@ -114,7 +132,17 @@ function widgetLine(r: WidgetRun, now: number): string {
     const stale = (r.lastEventAt != null && now - r.lastEventAt > STALE_THRESHOLD_MS) ? "  ⏰stale" : "";
     liveness = `${turn}${ev}${stale}`;
   }
-  return `${glyph} ${label}${agentSeg}${dur}${liveness}${tok}${ctx}${cost}`;
+  // #32: substrate vs work — once past turn 1, classify the tok/ctx% segment. The armory substrate
+  // (system prompt + skills + memory) dominates turn-1 context; on substrate-dominated runs the
+  // ctx% barely moves across turns and reads as "frozen". Label it "substrate" (flat overhead) so
+  // that's distinguishable from "work" (context growing from tool results). Needs ≥2 turns of
+  // data (a baseline + a current snapshot); before that there's nothing to compare.
+  let substrate = "";
+  if ((r.turnCount ?? 0) >= 2 && r.substrateBaseline != null && r.contextTokens != null && r.substrateBaseline > 0) {
+    const growth = (r.contextTokens - r.substrateBaseline) / r.substrateBaseline;
+    substrate = growth <= SUBSTRATE_GROWTH_THRESHOLD ? "  substrate" : "  work";
+  }
+  return `${glyph} ${label}${crossCwd}${agentSeg}${dur}${liveness}${tok}${ctx}${substrate}${cost}`;
 }
 
 /** Above-editor widget: one line per active run, cap 5, overflow → "+N more in /fleet".

package/src/registry/frontmatter.ts

@@ -16,6 +16,10 @@ export interface AgentDef {
   todoSync: boolean;
   memoryHydrate: boolean;
   vision: boolean;
+  /** #20/SPEC-6-5: opt in to the global cross-project user memory scope (`/__armory-fleet-user__`).
+   *  Default false — the user scope is a cross-project bleed by construction; hydrate it only when
+   *  an agent explicitly declares `userMemory: true`. Only meaningful when `memoryHydrate: true`. */
+  userMemory: boolean;
   /** Cross-harness backend routing (SPEC-3). Invalid value → FrontmatterError. */
   backend: "pi" | "claude";
   /** Stable id for backend-native resume (SPEC-3). Defaults to name. */
@@ -57,6 +61,7 @@ export function parseAgentFile(content: string, filePath: string, source: AgentS
   const todoSync = raw.todoSync === undefined ? true : Boolean(raw.todoSync);
   const memoryHydrate = raw.memoryHydrate === undefined ? true : Boolean(raw.memoryHydrate);
   const vision = raw.vision === undefined ? true : Boolean(raw.vision);
+  const userMemory = raw.userMemory === undefined ? false : Boolean(raw.userMemory);
 
   const rawBackend = typeof raw.backend === "string" ? raw.backend.trim() : "pi";
   if (rawBackend !== "pi" && rawBackend !== "claude") {
@@ -77,6 +82,7 @@ export function parseAgentFile(content: string, filePath: string, source: AgentS
     todoSync,
     memoryHydrate,
     vision,
+    userMemory,
     backend,
     sessionKey,
     source,

package/src/runtime/run-log.ts

@@ -15,6 +15,8 @@ export interface RunMetaEvent {
   pid?: number;
   /** SPEC-6-2: the cwd this run belongs to. */
   cwd?: string;
+  /** SPEC-6-5: the session cwd the dispatch originated from (= parentCwd). */
+  sessionCwd?: string;
 }
 export interface MessageEvent {
   type: "message"; role: string; text: string;
@@ -31,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;
 
@@ -49,6 +57,8 @@ export interface RunMeta {
   pid?: number;
   /** SPEC-6-2: the cwd this run belongs to. */
   cwd?: string;
+  /** SPEC-6-5: the session cwd the dispatch originated from (= parentCwd). */
+  sessionCwd?: string;
 }
 
 const ARGS_LIMIT = 200;
@@ -104,7 +114,7 @@ export class RunLog {
           if (!meta) {
             meta = { runId: e.runId, agent: e.agent, model: e.model, task: e.task, startedAt: e.startedAt,
               track: e.track, todoId: e.todoId, backendSessionId: e.backendSessionId, sessionKey: e.sessionKey,
-              status: "running", tokenTotal: 0, pid: e.pid, cwd: e.cwd };
+              status: "running", tokenTotal: 0, pid: e.pid, cwd: e.cwd, sessionCwd: e.sessionCwd };
           } else {
             // latest binding wins
             if (e.backendSessionId) meta.backendSessionId = e.backendSessionId;

package/src/tools/subagent.ts

@@ -1,4 +1,6 @@
 // src/tools/subagent.ts
+import { resolve } from "node:path";
+import { statSync } from "node:fs";
 import { Type, type Static } from "typebox";
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { TodoSyncPort } from "../todo-sync/port.ts";
@@ -32,6 +34,7 @@ export const subagentParams = Type.Object({
   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.' })),
+  cwd: Type.Optional(Type.String({ description: 'The dispatch target\'s working directory. Default: the session cwd (backward-compat). Scoped to this path: the child\'s working dir, context-file cascade, skill discovery, and memory scopes. Accepts paths OUTSIDE the session cwd (a sibling repo) — that\'s the #20 fix. Relative paths resolve against the session cwd.' })),
 });
 
 export type SubagentInput = Static<typeof subagentParams>;
@@ -44,6 +47,19 @@ export function mergeLifecycleSkills(phaseSkills: string[] | undefined, callerSk
   return [...new Set([...(phaseSkills ?? []), ...(callerSkills ?? [])])];
 }
 
+/** SPEC-6-5: validate + resolve a dispatch cwd. Returns { cwd } on success or { error } on failure. */
+export function resolveDispatchCwd(raw: string | undefined, parentCwd: string): { cwd?: string; error?: string } {
+  if (raw === undefined || raw === "") return { cwd: undefined };   // default → parentCwd (handled by spawnSubagent)
+  const abs = resolve(parentCwd, raw);
+  try {
+    const st = statSync(abs);
+    if (!st.isDirectory()) return { error: `cwd is not a directory: ${abs}` };
+    return { cwd: abs };
+  } catch {
+    return { error: `cwd does not exist: ${abs}` };
+  }
+}
+
 export interface SubagentToolDeps {
   registry: Map<string, AgentDef>;
   runRegistry: RunRegistry;
@@ -80,6 +96,8 @@ export interface SubagentToolDeps {
    *  Per-dispatch `modelFallback` (when passed) takes precedence. Applies to the direct foreground
    *  path, the foreground lifecycle spawn, and the background/scheduled spawn. */
   defaultModelFallback?: string;
+  /** SPEC-6-5: notify hook for cross-cwd dispatch surfacing. Wired from ctx.ui.notify in index.ts. */
+  onNotify?: (message: string, kind?: "info" | "warning" | "error") => void;
 }
 
 /** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
@@ -101,6 +119,12 @@ export function createSubagentTool(deps: SubagentToolDeps) {
     ],
     parameters: subagentParams,
     async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, _ctx: any) {
+      // SPEC-6-5: validate + resolve the dispatch cwd before any routing.
+      const { cwd: resolvedCwd, error: cwdErr } = resolveDispatchCwd(params.cwd, deps.parentCwd);
+      if (cwdErr) return { isError: true, content: [{ type: "text" as const, text: cwdErr }] };
+      if (resolvedCwd && resolvedCwd !== deps.parentCwd) {
+        deps.onNotify?.(`scoped to ${resolvedCwd} (≠ session ${deps.parentCwd})`, "info");
+      }
       // SPEC-5a: background + schedule routing (Q1/Q2/Q5).
       if (params.background && params.schedule) {
         return { isError: true, content: [{ type: "text" as const, text: "A scheduled run is inherently background — pass only one of `background` or `schedule`, not both." }] };
@@ -132,10 +156,12 @@ export function createSubagentTool(deps: SubagentToolDeps) {
             maxTurns: params.maxTurns,
             tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
             readOnly: params.readOnly,
+            cwd: o.cwd,
           }), params.modelFallback ?? deps.defaultModelFallback, signal),
         };
         const res = await runLifecycle(params.task, params.lifecycle, {
           deps: lifecycleFullDeps, mode: "auto",
+          entryCwd: resolvedCwd,
           onCheckpoint: async (phase) => phase.status === "failed" ? { action: "abort" } : { action: "continue" },
         });
         const isError = res.status === "failed" || res.status === "aborted";
@@ -166,6 +192,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         signal,
         maxTurns: params.maxTurns,
         tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
+        cwd: resolvedCwd,
       });
       // #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
@@ -200,17 +227,47 @@ export function createSubagentTool(deps: SubagentToolDeps) {
           signal,
           maxTurns: params.maxTurns,
           tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
+          cwd: resolvedCwd,
         });
         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,
       };