@getpipher/armory-fleet 0.12.5 → 0.13.0

package/README.md

@@ -308,6 +308,14 @@ 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.
+
 ## 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.13.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-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/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/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";
@@ -116,6 +117,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;
@@ -215,6 +220,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 +293,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 +317,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 +351,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"
@@ -373,7 +383,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 +413,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 */ }

package/src/index.ts

@@ -205,6 +205,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   // 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;
+  // 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
@@ -308,6 +310,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     const m = ctx.model;
     deps.parentModel = m ? { provider: m.provider, id: m.id } : { provider: "", id: "" };
     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;
@@ -49,6 +51,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 +108,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,6 +227,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
           signal,
           maxTurns: params.maxTurns,
           tierRegistry: deps.tierRegistry, modelRegistry: deps.modelRegistry,
+          cwd: resolvedCwd,
         });
         retriedWithModel = fallback;
       }