@getpipher/armory-fleet 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RECTOR <rector@rectorspace.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @getpipher/armory-fleet
+
+> The armory suite's subagent orchestrator for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent) — a cross-harness, superpowers-native fleet where every agent is **armory-native from birth**.
+
+`@getpipher/armory-fleet` brings Claude-Code-style autonomous sub-agents to pi, built so that the armory ecosystem ([armory-todo](https://github.com/getpipher/armory-todo), [armory-memory](https://github.com/getpipher/armory-memory), [vision](https://github.com/getpipher/vision), [cursor](https://github.com/getpipher/cursor)) is the *default substrate* agents run on — not a bolt-on.
+
+## Why
+
+The pi-subagent ecosystem is crowded (nicobailon/pi-subagents at 2688⭐, tintinweb at 702⭐, QuintinShaw at 287⭐, and more). Three structural gaps remain open:
+
+1. **Armory-native integration** — no external package can integrate with the armory suite; they don't own it. Agents that sync to armory-todo, hydrate from armory-memory, see via vision, and edit via cursor *by default* are uncopyable.
+2. **Cross-harness peers** — only one attempt (kky42/pi-flow, 66⭐) runs Claude Code + Pi as peer subagent backends, and it's early. A dual-arsenal topology deserves a first-class implementation.
+3. **Superpowers-native lifecycle** — only one attempt (teelicht/pi-superagents, 54⭐) wraps the superpowers skill pipeline, and it's synchronous-only.
+
+`armory-fleet` owns all three, then reaches parity on the rest (fleet TUI, scheduling, worktree isolation, cost accounting, quality patterns, workflows-as-code, event-bus/RPC) — to be the best pi-subagent package in the ecosystem.
+
+## Status
+
+🚧 **Pre-implementation.** The master PRD + 7-SPEC roadmap are written and self-reviewed; SPEC-1 (core engine + armory-todo sync) is the next brainstorm cycle.
+
+- **Master PRD:** [`PRD.md`](./PRD.md)
+- **Landscape research:** [`research/`](./research) (11+ packages mapped, 5 contenders deep-read)
+- **Roadmap:** PRD → SPEC-1 (core+todo-sync) → SPEC-2 (deep armory) → SPEC-3 (cross-harness) → SPEC-4 (superpowers lifecycle) → SPEC-5a (ops) → SPEC-5b (fleet TUI) → SPEC-6 (power-user → v1.0)
+
+## Compatibility
+
+pi `^0.81.1`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/agents/general-purpose.md

@@ -0,0 +1,10 @@
+---
+name: general-purpose
+description: A focused general-purpose subagent delegate. Use for any task needing isolated work.
+todoSync: true
+memoryHydrate: true
+vision: true
+---
+You are a focused subagent delegate. Complete the assigned task thoroughly, work autonomously to completion, and return a concise result summary.
+
+Do not call the `todo` tool — the fleet engine manages todo tracking for you.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@getpipher/armory-fleet",
+  "version": "0.2.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",
+  "type": "module",
+  "author": "RECTOR (https://github.com/rz1989s)",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "subagents",
+    "ai-agents",
+    "multi-agent",
+    "orchestration",
+    "agent-orchestration",
+    "claude-code",
+    "superpowers",
+    "armory",
+    "cross-harness"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getpipher/armory-fleet.git"
+  },
+  "homepage": "https://github.com/getpipher/armory-fleet#readme",
+  "bugs": {
+    "url": "https://github.com/getpipher/armory-fleet/issues"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.81.1",
+    "@earendil-works/pi-tui": "^0.81.1",
+    "@earendil-works/pi-ai": "^0.81.1",
+    "@getpipher/armory-todo": "^0.5.4",
+    "@getpipher/armory-memory": "^0.1.1",
+    "@getpipher/vision": "^0.5.2",
+    "typebox": "^1.1.38",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test:run": "node --import tsx --test test/*.test.mts"
+  }
+}

package/src/engine/child-loader.ts

@@ -0,0 +1,47 @@
+// src/engine/child-loader.ts — the fleet CustomResourceLoader builder.
+// Promotes SPEC-1's DefaultResourceLoader-with-overrides to deliberate control:
+// noExtensions (deterministic child, no host-extension leakage), composed
+// systemPromptOverride (rolePrompt + memoryBlock + base), scoped skills.
+import { DefaultResourceLoader, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { dirname } from "node:path";
+import type { AgentDef } from "../registry/frontmatter.ts";
+import type { MemoryHydratePort } from "../memory-hydrate/port.ts";
+
+/** Fixed pseudo-cwd for the global cross-project user memory scope. */
+export const USER_PSEUDO_CWD = "/__armory-fleet-user__";
+
+/** Compose the child system prompt: rolePrompt → memoryBlock → base (empty memoryBlock omitted). */
+export function composeChildPrompt(args: { rolePrompt: string; memoryBlock: string; base: string }): string {
+  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 };
+}
+
+export interface ChildLoaderOpts {
+  cwd: string;
+  agent: AgentDef;
+  memoryPort: MemoryHydratePort;
+}
+
+/** Build the fleet CustomResourceLoader for a child session. */
+export function buildChildLoader(opts: ChildLoaderOpts): DefaultResourceLoader {
+  const scopes = memoryScopesFor(opts.cwd);
+  const memoryBlock = opts.agent.memoryHydrate ? opts.memoryPort.renderScopes(scopes) : "";
+  return new DefaultResourceLoader({
+    cwd: opts.cwd,
+    agentDir: getAgentDir(),
+    noExtensions: true,
+    systemPromptOverride: (base) =>
+      composeChildPrompt({ rolePrompt: opts.agent.rolePrompt, memoryBlock, base: base ?? "" }),
+    skillsOverride: (cur) => ({
+      skills:
+        opts.agent.skills && opts.agent.skills.length
+          ? cur.skills.filter((s) => opts.agent.skills!.includes(s.name))
+          : cur.skills,
+      diagnostics: cur.diagnostics,
+    }),
+  });
+}

package/src/engine/concurrency-lock.ts

@@ -0,0 +1,24 @@
+// src/engine/concurrency-lock.ts
+export interface SingleSlotLock {
+  /** true if acquired; false if busy (call .current() for the running id). */
+  tryAcquire(id: string): boolean;
+  release(): void;
+  current(): string | null;
+}
+
+export function createSingleSlotLock(): SingleSlotLock {
+  let holding: string | null = null;
+  return {
+    tryAcquire(id): boolean {
+      if (holding !== null) return false;
+      holding = id;
+      return true;
+    },
+    release(): void {
+      holding = null;
+    },
+    current(): string | null {
+      return holding;
+    },
+  };
+}

package/src/engine/run-registry.ts

@@ -0,0 +1,39 @@
+// src/engine/run-registry.ts
+import type { FleetRunStatus } from "../todo-sync/port.ts";
+
+export interface RunRecord {
+  runId: string;
+  agent: string;
+  model: string;
+  task: string;
+  track: boolean;
+  todoId: string | null;
+  status: FleetRunStatus;
+  startedAt: number;
+  endedAt?: number;
+  resultSummary?: string;
+}
+
+/** runId format: fl-<base36 ms>-<6 random> (SPEC-1 §5.1). */
+export function genRunId(): string {
+  return "fl-" + Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 8);
+}
+
+export class RunRegistry {
+  private readonly runs = new Map<string, RunRecord>();
+
+  add(r: RunRecord): void {
+    this.runs.set(r.runId, r);
+  }
+  get(id: string): RunRecord | undefined {
+    return this.runs.get(id);
+  }
+  /** Newest-first (by startedAt desc). */
+  list(): RunRecord[] {
+    return [...this.runs.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+  update(id: string, patch: Partial<Omit<RunRecord, "runId">>): void {
+    const r = this.runs.get(id);
+    if (r) this.runs.set(id, { ...r, ...patch });
+  }
+}

package/src/engine/spawnSubagent.ts

@@ -0,0 +1,234 @@
+// src/engine/spawnSubagent.ts
+import type { AgentDef, ThinkingLevel } from "../registry/frontmatter.ts";
+import type { FleetRunStatus, TodoSyncPort } from "../todo-sync/port.ts";
+import type { MemoryHydratePort } from "../memory-hydrate/port.ts";
+import type { VisionPort } from "../vision/port.ts";
+import { genRunId, RunRegistry } from "./run-registry.ts";
+import { createTurnBudget, DEFAULT_MAX_TURNS } from "./turn-budget.ts";
+import type { SingleSlotLock } from "./concurrency-lock.ts";
+
+const PI_DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
+
+/** No-op ports used when a caller omits them (e.g. SPEC-1 unit tests). Production (index.ts) passes real ports. */
+const NOOP_MEMORY_PORT: MemoryHydratePort = { renderScopes: () => "" };
+const NOOP_VISION_PORT: VisionPort = {
+  isMultimodal: () => false,
+  isConfigured: () => false,
+  delegate: async () => ({ ok: false, error: "no vision port configured" }),
+};
+
+/** Minimal event shape the engine reads from a child session (decoupled from pi's internal event types). */
+export interface ChildSessionEvent {
+  type: string;
+  message?: {
+    role?: string;
+    content?: Array<{ type: string; text?: string }>;
+    usage?: { cost?: { total?: number } };
+  };
+}
+
+export interface ChildSession {
+  prompt(text: string): Promise<void>;
+  subscribe(handler: (event: ChildSessionEvent) => void): () => void;
+  abort(): Promise<void>;
+  dispose(): void;
+}
+
+export interface ChildSessionOpts {
+  cwd: string;
+  model?: string;
+  thinkingLevel?: ThinkingLevel;
+  tools: string[];
+  rolePrompt: string;
+  skills: string[];
+  task: string;
+  agent: AgentDef;
+  memoryPort: MemoryHydratePort;
+  visionPort: VisionPort;
+}
+
+export interface ChildSessionFactory {
+  create(opts: ChildSessionOpts): Promise<{ session: ChildSession; model: string }>;
+}
+
+export interface SpawnOptions {
+  agent: string;
+  task: string;
+  todoId?: string;
+  track?: boolean; // default true
+  model?: string; // override
+  maxTurns?: number; // default 20
+  registry: Map<string, AgentDef>;
+  todoSync: TodoSyncPort;
+  runRegistry: RunRegistry;
+  lock: SingleSlotLock;
+  childFactory: ChildSessionFactory;
+  parentModel: { provider: string; id: string };
+  parentCwd: string;
+  memoryPort?: MemoryHydratePort;
+  visionPort?: VisionPort;
+  signal?: AbortSignal;
+  onEvent?: (e: ChildSessionEvent) => void;
+}
+
+export interface SpawnResult {
+  status: FleetRunStatus;
+  finalText: string;
+  runId: string;
+  todoId: string | null;
+  agent: string;
+  model: string;
+  durationMs: number;
+  tokenTotal: number;
+  error?: string;
+}
+
+export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
+  const track = opts.track ?? true;
+  const maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
+  const startedAt = Date.now();
+
+  // concurrency=1 (SPEC-1 §9.2) — peek before generating a runId so a rejected
+  // call doesn't mint a discarded id; the held id is named in the message.
+  const busyId = opts.lock.current();
+  if (busyId !== null) {
+    return fail("", startedAt, `a subagent is already running (concurrency=1 in v0.1); wait for ${busyId} to finish or abort it first`, opts.agent);
+  }
+  const runId = genRunId();
+  if (!opts.lock.tryAcquire(runId)) {
+    return fail("", startedAt, "concurrency lock unexpectedly unavailable", opts.agent);
+  }
+
+  try {
+    // resolve agent
+    const agentDef = opts.registry.get(opts.agent);
+    if (!agentDef) {
+      const available = [...opts.registry.keys()].sort().join(", ");
+      return fail(runId, startedAt, `agent '${opts.agent}' not in registry; available: ${available}`, opts.agent);
+    }
+
+    // resolve model
+    const model = opts.model ?? agentDef.model ?? `${opts.parentModel.provider}/${opts.parentModel.id}`;
+
+    // child tools pass through UNFILTERED — the single-writer `todo`-exclusion is enforced
+    // downstream by the child factory's `excludeTools: ["todo"]` (SPEC-2 §9.1 hardening).
+    const tools = agentDef.tools ?? PI_DEFAULT_TOOLS;
+    const memoryPort = opts.memoryPort ?? NOOP_MEMORY_PORT;
+    const visionPort = opts.visionPort ?? NOOP_VISION_PORT;
+
+    // run record
+    opts.runRegistry.add({
+      runId, agent: agentDef.name, model, task: opts.task, track,
+      todoId: null, status: "running", startedAt,
+    });
+
+    // todo-sync (before) — only when both caller tracks AND agent allows todoSync
+    let priorStatus: string | undefined;
+    let todoId: string | null = null;
+    try {
+      const link = await opts.todoSync.linkOrCreateRunTodo({
+        runId, agent: agentDef.name, task: opts.task,
+        todoId: opts.todoId, track: track && agentDef.todoSync,
+      });
+      todoId = link.todoId;
+      priorStatus = link.priorStatus;
+      opts.runRegistry.update(runId, { todoId });
+    } catch (e) {
+      return await finishRun(opts, runId, startedAt, "failed", "", todoId, priorStatus, (e as Error).message, agentDef.name, model);
+    }
+
+    // spawn child
+    const { session } = await opts.childFactory.create({
+      cwd: opts.parentCwd,
+      model,
+      thinkingLevel: agentDef.thinkingLevel,
+      tools,
+      rolePrompt: agentDef.rolePrompt,
+      skills: agentDef.skills ?? [],
+      task: opts.task,
+      agent: agentDef,
+      memoryPort,
+      visionPort,
+    });
+
+    const budget = createTurnBudget(maxTurns);
+    let finalText = "";
+    let tokenTotal = 0;
+    let aborted = false;
+
+    const onSignalAbort = (): void => { aborted = true; void session.abort(); };
+    opts.signal?.addEventListener("abort", onSignalAbort);
+
+    const unsub = session.subscribe((e) => {
+      if (e.type === "turn_end") {
+        if (budget.consume()) void session.abort();
+      } else if (e.type === "message_end" && e.message?.role === "assistant") {
+        const text = e.message.content?.map((c) => (c.type === "text" ? c.text ?? "" : "")).join("") ?? "";
+        if (text) finalText = text;
+        const total = e.message.usage?.cost?.total;
+        if (typeof total === "number") tokenTotal += total;
+      }
+      opts.onEvent?.(e);
+    });
+
+    let runError: string | undefined;
+    try {
+      await session.prompt(opts.task);
+    } catch (e) {
+      runError = (e as Error).message;
+    } finally {
+      unsub();
+      opts.signal?.removeEventListener("abort", onSignalAbort);
+      session.dispose();
+    }
+
+    let status: FleetRunStatus;
+    let error: string | undefined;
+    if (aborted) {
+      status = "aborted";
+      error = "aborted by user";
+    } else if (budget.count() >= maxTurns) {
+      status = "failed";
+      error = `hit turn budget (${maxTurns}) mid-task; partial result: ${finalText.slice(0, 200)}`;
+    } else if (runError) {
+      status = "failed";
+      error = runError;
+    } else {
+      status = "completed";
+    }
+
+    return await finishRun(opts, runId, startedAt, status, finalText, todoId, priorStatus, error, agentDef.name, model, tokenTotal);
+  } finally {
+    opts.lock.release();
+  }
+}
+
+function fail(runId: string, startedAt: number, message: string, agent: string): SpawnResult {
+  return {
+    status: "failed", finalText: "", runId, todoId: null, agent,
+    model: "", durationMs: Date.now() - startedAt, tokenTotal: 0, error: message,
+  };
+}
+
+async function finishRun(
+  opts: SpawnOptions, runId: string, startedAt: number,
+  status: FleetRunStatus, finalText: string, todoId: string | null, priorStatus: string | undefined,
+  error: string | undefined, agentName: string, model: string, tokenTotal = 0,
+): Promise<SpawnResult> {
+  const endedAt = Date.now();
+  opts.runRegistry.update(runId, { status, endedAt, resultSummary: finalText.slice(0, 120) });
+  // todo-sync reconciliation must not mask the run result
+  try {
+    if (status === "completed") {
+      await opts.todoSync.markRunTodoDone(todoId, priorStatus, finalText.slice(0, 500));
+    } else {
+      await opts.todoSync.markRunTodoReverted(todoId, priorStatus, error ?? status);
+    }
+  } catch {
+    // swallow — the run result is authoritative; the finally in spawnSubagent releases the lock
+  }
+  return {
+    status, finalText, runId, todoId, agent: agentName, model,
+    durationMs: endedAt - startedAt, tokenTotal, error,
+  };
+}

package/src/engine/turn-budget.ts

@@ -0,0 +1,21 @@
+// src/engine/turn-budget.ts
+export const DEFAULT_MAX_TURNS = 20;
+
+export interface TurnBudget {
+  /** Returns true when the just-consumed turn meets/exceeds the cap. */
+  consume(): boolean;
+  count(): number;
+}
+
+export function createTurnBudget(max: number = DEFAULT_MAX_TURNS): TurnBudget {
+  let n = 0;
+  return {
+    consume(): boolean {
+      n += 1;
+      return n >= max;
+    },
+    count(): number {
+      return n;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+// src/index.ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  createAgentSession,
+  ModelRuntime,
+  ModelRegistry,
+  SessionManager,
+  getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { createSubagentTool, type SubagentToolDeps } from "./tools/subagent.ts";
+import { openFleetPanel } from "./panel/fleet-panel.ts";
+import { discoverAgents } from "./registry/discovery.ts";
+import { RunRegistry } from "./engine/run-registry.ts";
+import { createSingleSlotLock } from "./engine/concurrency-lock.ts";
+import { ArmoryTodoAdapter } from "./todo-sync/adapter.ts";
+import { ArmoryMemoryAdapter } from "./memory-hydrate/adapter.ts";
+import { ArmoryVisionAdapter } from "./vision/adapter.ts";
+import { buildChildLoader } from "./engine/child-loader.ts";
+import { createDescribeImageTool } from "./vision/describe-image-tool.ts";
+import type { MemoryHydratePort } from "./memory-hydrate/port.ts";
+import type { VisionPort } from "./vision/port.ts";
+import type { ChildSessionFactory, ChildSession } from "./engine/spawnSubagent.ts";
+import { join } from "node:path";
+
+/** The package builtin agents/ dir, resolved relative to this module. */
+function builtinAgentsDir(): string {
+  return join(new URL(".", import.meta.url).pathname, "..", "agents");
+}
+
+/** Build the real (SDK-backed) child-session factory. memoryPort is shared (cwd-agnostic);
+ *  the vision adapter is constructed per-spawn (needs the child cwd). */
+function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: MemoryHydratePort): ChildSessionFactory {
+  return {
+    async create(opts) {
+      let model: Model<any> | undefined;
+      if (opts.model) {
+        const slash = opts.model.indexOf("/");
+        if (slash < 0) throw new Error(`agent model '${opts.model}' must be 'provider/id'`);
+        const provider = opts.model.slice(0, slash);
+        const id = opts.model.slice(slash + 1);
+        model = modelRuntime.getModel(provider, id);
+        if (!model) throw new Error(`agent model '${opts.model}' not found in runtime (provider '${provider}', id '${id}')`);
+      }
+      // Fleet CustomResourceLoader: noExtensions + composed systemPromptOverride (rolePrompt + memory + base) + scoped skills.
+      const loader = buildChildLoader({ cwd: opts.cwd, agent: opts.agent, memoryPort });
+      await loader.reload();
+      // Vision adapter built per-spawn (needs the child cwd); ModelRegistry wraps the shared modelRuntime.
+      const visionPort: VisionPort = new ArmoryVisionAdapter({
+        modelRegistry: new ModelRegistry(modelRuntime),
+        cwd: opts.cwd,
+        agentDir: getAgentDir(),
+      });
+      const injectVision = opts.agent.vision && !visionPort.isMultimodal(model);
+      const { session } = await createAgentSession({
+        cwd: opts.cwd,
+        model,
+        thinkingLevel: opts.thinkingLevel,
+        tools: opts.tools,
+        excludeTools: ["todo"],                       // SPEC-2 §9.1 hardened single-writer guard
+        customTools: injectVision ? [createDescribeImageTool(visionPort) as never] : [],
+        resourceLoader: loader,
+        sessionManager: SessionManager.inMemory(),
+        modelRuntime,
+      });
+      return { session: session as unknown as ChildSession, model: opts.model ?? "" };
+    },
+  };
+}
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+  const modelRuntime = await ModelRuntime.create();
+  const deps: SubagentToolDeps = {
+    registry: new Map(),
+    runRegistry: new RunRegistry(),
+    lock: createSingleSlotLock(),
+    todoSync: new ArmoryTodoAdapter(),
+    childFactory: createChildSessionFactory(modelRuntime, new ArmoryMemoryAdapter()),
+    parentModel: { provider: "", id: "" },
+    parentCwd: "",
+  };
+
+  const refresh = (ctx: { cwd: string; ui: { notify: (m: string, t?: "info" | "warning" | "error") => void } }): void => {
+    const r = discoverAgents({
+      projectDir: join(ctx.cwd, ".pi", "agents"),
+      globalDir: join(process.env.HOME ?? "", ".pi", "agent", "agents"),
+      builtinDir: builtinAgentsDir(),
+    });
+    for (const e of r.errors) ctx.ui.notify(e, "error");
+    for (const w of r.warnings) ctx.ui.notify(w, "warning");
+    deps.registry = r.agents;
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    refresh(ctx);
+    const m = ctx.model;
+    deps.parentModel = m ? { provider: m.provider, id: m.id } : { provider: "", id: "" };
+    deps.parentCwd = ctx.cwd;
+  });
+
+  pi.on("resources_discover", (event, ctx) => {
+    if (event.reason === "reload") refresh(ctx);
+    return undefined;
+  });
+
+  pi.registerTool(createSubagentTool(deps) as never);
+
+  pi.registerCommand("fleet", {
+    description: "Open the armory-fleet panel (running + recent subagents + agent registry).",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("fleet panel is TUI-only; use the subagent tool in non-interactive modes.", "info");
+        return;
+      }
+      openFleetPanel(deps, ctx as never);
+    },
+  });
+}

package/src/memory-hydrate/adapter.ts

@@ -0,0 +1,12 @@
+// src/memory-hydrate/adapter.ts — ONLY file importing @getpipher/armory-memory.
+import { renderMemoryBlock, listMemory } from "@getpipher/armory-memory";
+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)
+      .map((cwd) => renderMemoryBlock(cwd))           // armory-memory's existing cwd-keyed primitive
+      .join("\n\n");                                   // → "" when all three empty
+  }
+}

package/src/memory-hydrate/port.ts

@@ -0,0 +1,13 @@
+// src/memory-hydrate/port.ts — fleet-owned port; fleet core depends only on this.
+export interface MemoryScopes {
+  /** The cwd the child works in (= parentCwd in SPEC-2; the project cwd at SPEC-5a worktree). */
+  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;
+}
+export interface MemoryHydratePort {
+  /** Render the three-scope memory block (project → local → user), concatenated. Empty string when all scopes empty. */
+  renderScopes(scopes: MemoryScopes): string;
+}