@getpipher/armory-fleet 0.2.0 → 0.3.0

package/agents/general-purpose-cc.md

@@ -0,0 +1,11 @@
+---
+name: general-purpose-cc
+description: A focused general-purpose CC subagent. Use for any task needing Claude Code as the worker.
+backend: claude
+todoSync: true
+memoryHydrate: true
+vision: true
+---
+You are a focused subagent delegate running under Claude Code. 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

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-fleet",
-  "version": "0.2.0",
+  "version": "0.3.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-detector.ts

@@ -0,0 +1,75 @@
+// src/backend/claude-detector.ts — version + stream-json schema smoke + flag-support probe (SPEC-3 §5).
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mapClaudeEvent } from "./claude-events.ts";
+import type { BackendVersionInfo } from "./registry.ts";
+
+const DEFAULT_BIN = "claude";
+
+export interface DetectOpts {
+  /** Fixture hook: an arg passed to the fake-claude via FLEET_FAKE_CLAUDE_PROBE env to select init-ok/init-drift. */
+  schemaProbeArg?: string;
+}
+
+function run(bin: string, args: string[], env?: NodeJS.ProcessEnv): Promise<{ stdout: string; stderr: string; code: number | null }> {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (d) => { stdout += d.toString(); });
+    child.stderr?.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => resolve({ stdout, stderr, code }));
+    // Capture the spawn error message into stderr so the caller can detect ENOENT (binary missing).
+    child.on("error", (err) => resolve({ stdout: "", stderr: err.message, code: null }));
+  });
+}
+
+function parseVersion(stdout: string): string {
+  const m = stdout.trim().match(/(\d+\.\d+\.\d+)/);
+  return m && m[1] ? m[1] : stdout.trim();
+}
+
+function probeFlags(helpText: string): Record<string, boolean> {
+  const has = (flag: string): boolean => new RegExp(`(^|\\s)${flag.replace(/-/g, "\\-")}(\\s|$)`).test(helpText);
+  return {
+    "--disallowed-tools": has("--disallowed-tools"),
+    "--allowed-tools": has("--allowed-tools"),
+    "--max-turns": has("--max-turns"),
+    "--resume": has("--resume"),
+    "--append-system-prompt": has("--append-system-prompt"),
+    "--output-format": has("--output-format"),
+  };
+}
+
+export async function detectClaude(bin: string = DEFAULT_BIN, opts: DetectOpts = {}): Promise<BackendVersionInfo | null> {
+  // Missing binary check: for an explicit path that doesn't exist, return null;
+  // for the default `claude` on PATH, the version run below resolves ENOENT → null.
+  if (bin !== DEFAULT_BIN && !existsSync(bin)) return null;
+  const versionRun = await run(bin, ["--version"]);
+  if (versionRun.code === null && /ENOENT/i.test(versionRun.stderr)) return null;
+  if (versionRun.code !== 0 && !versionRun.stdout) {
+    return { version: "", schemaOk: false, flagSupport: {}, note: `claude --version failed (code ${versionRun.code})` };
+  }
+  const version = parseVersion(versionRun.stdout);
+
+  // Schema smoke: spawn a throwaway ping in stream-json mode; scan the lines for a `system/init` event with session_id.
+  // (Real CC emits hook_started/hook_response system events before init; first-line-only would false-fail.)
+  const env = opts.schemaProbeArg ? { FLEET_FAKE_CLAUDE_PROBE: opts.schemaProbeArg } : undefined;
+  const smoke = await run(bin, ["-p", "--verbose", "--output-format", "stream-json", "ping"], env);
+  let schemaOk = false;
+  let note: string | undefined;
+  const lines = smoke.stdout.split("\n").filter((l) => l.trim());
+  for (const line of lines) {
+    const ev = mapClaudeEvent(line);
+    if (ev && ev.type === "session_init" && ev.backendSessionId) { schemaOk = true; break; }
+  }
+  if (!schemaOk) {
+    note = lines.length ? `schema drift (no init event with session_id; first line: ${lines[0]!.slice(0, 80)})` : "schema drift (no output emitted)";
+  }
+
+  // Flag-support probe (only meaningful if --help works).
+  const helpRun = await run(bin, ["--help"]);
+  const flagSupport = helpRun.code === 0 ? probeFlags(helpRun.stdout) : {};
+
+  return { version, schemaOk, flagSupport, note };
+}

package/src/backend/claude-events.ts

@@ -0,0 +1,39 @@
+// src/backend/claude-events.ts — map one CC stream-json NDJSON line → ChildSessionEvent (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 CCEvent { type: string; subtype?: string; session_id?: string; message?: CCMessage; error?: { message?: string }; }
+
+export function mapClaudeEvent(line: string): ChildSessionEvent | null {
+  let ev: CCEvent;
+  try {
+    ev = JSON.parse(line) as CCEvent;
+  } catch {
+    return null; // malformed line — resilient
+  }
+  switch (ev.type) {
+    case "system":
+      if (ev.subtype === "init" && typeof ev.session_id === "string") {
+        return { type: "session_init", backendSessionId: ev.session_id };
+      }
+      return null;
+    case "assistant": {
+      const msg = ev.message;
+      if (!msg) return null;
+      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 } };
+    }
+    case "result":
+      // turn boundary (success or error_max_turns) → turn_end drives the budget
+      return { type: "turn_end" };
+    case "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
+    default:
+      return null; // unknown — forward-compat, caller logs at debug
+  }
+}

package/src/backend/claude-factory.ts

@@ -0,0 +1,50 @@
+// src/backend/claude-factory.ts — createClaudeChildFactory (SPEC-3 §4.1, §4.5, §4.6, §9.1).
+import { spawn, type ChildProcess } from "node:child_process";
+import type { ChildSessionFactory, ChildSessionOpts } from "../engine/spawnSubagent.ts";
+import type { BackendVersionInfo } from "./registry.ts";
+import type { ResumeStore } from "./resume-store.ts";
+import { ClaudeChildSession } from "./claude-session.ts";
+import { memoryScopesFor } from "../engine/child-loader.ts";
+
+export interface ClaudeFactoryOverrides {
+  /** Test hook: called instead of `spawn` to inspect args. Returns a ChildProcess-shaped stub. */
+  spawnOverride?: (args: string[]) => ChildProcess;
+}
+
+export function createClaudeChildFactory(
+  detector: BackendVersionInfo | null,
+  resumeStore: ResumeStore,
+  bin: string = "claude",
+  overrides: ClaudeFactoryOverrides = {},
+): ChildSessionFactory {
+  return {
+    async create(opts: ChildSessionOpts): Promise<{ session: ClaudeChildSession; model: string }> {
+      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 sys = memoryBlock ? `${opts.rolePrompt}\n\n${memoryBlock}` : opts.rolePrompt;
+      const resumeId = resumeStore.get("claude", opts.agent.sessionKey);
+
+      const args: string[] = ["-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose"];
+      if (opts.model) args.push("--model", opts.model);
+      args.push("--append-system-prompt", sys);
+      // todo exclusion: prefer --disallowed-tools; fall back to --allowed-tools allow-list when the agent pins tools.
+      if (detector.flagSupport["--disallowed-tools"]) {
+        args.push("--disallowed-tools", "todo");
+      } else if (detector.flagSupport["--allowed-tools"] && opts.tools.length) {
+        const allowed = opts.tools.filter((t) => t !== "todo").join(",");
+        args.push("--allowed-tools", allowed);
+      }
+      // v0.3 leaves maxTurns to the engine's turn_end belt (no --max-turns flag; avoids double-enforcement).
+      if (resumeId && detector.flagSupport["--resume"]) args.push("--resume", resumeId);
+      args.push(opts.task);
+
+      const proc = overrides.spawnOverride
+        ? overrides.spawnOverride(args)
+        : spawn(bin, args, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+      const session = new ClaudeChildSession(proc, opts.agent.sessionKey, resumeStore);
+      return { session, model: opts.model ?? "" };
+    },
+  };
+}

package/src/backend/claude-session.ts

@@ -0,0 +1,75 @@
+// src/backend/claude-session.ts — ChildSession over a claude -p child process (SPEC-3 §4.4, §4.3).
+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 type { ResumeStore } from "./resume-store.ts";
+
+export class ClaudeChildSession implements ChildSession {
+  private readonly proc: ChildProcess;
+  private readonly sessionKey: string;
+  private readonly resumeStore: ResumeStore;
+  private readonly handlers: Array<(e: ChildSessionEvent) => void> = [];
+  private disposed = false;
+  private initCaptured = false;
+  private turnResolve: (() => void) | null = null;
+
+  constructor(proc: ChildProcess, sessionKey: string, resumeStore: ResumeStore) {
+    this.proc = proc;
+    this.sessionKey = sessionKey;
+    this.resumeStore = resumeStore;
+    const rl = createInterface({ input: proc.stdout! });
+    rl.on("line", (line) => this.onLine(line));
+    proc.on("close", () => { if (this.turnResolve) { const r = this.turnResolve; this.turnResolve = null; r(); } });
+  }
+
+  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);
+    }
+    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> {
+    if (this.disposed) throw new Error("session disposed");
+    if (!this.proc.stdin) throw new Error("claude child has no stdin pipe");
+    const msg = JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } }) + "\n";
+    return new Promise<void>((resolve) => {
+      this.turnResolve = resolve;
+      this.proc.stdin!.write(msg, () => { /* fire-and-forget; resolved on turn_end/close */ });
+    });
+  }
+
+  subscribe(handler: (e: ChildSessionEvent) => void): () => void {
+    this.handlers.push(handler);
+    return () => {
+      const i = this.handlers.indexOf(handler);
+      if (i >= 0) this.handlers.splice(i, 1);
+    };
+  }
+
+  async abort(): Promise<void> {
+    if (this.disposed) return;
+    try { this.proc.kill("SIGTERM"); } catch { /* already dead */ }
+    this.disposed = true;   // SIGTERM kills the child process; the session is irrecoverable
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    try { this.proc.kill("SIGKILL"); } catch { /* already dead */ }
+    this.proc.stdout?.destroy();
+    try { this.proc.stdin?.end(); } catch { /* already closed */ }
+    this.proc.removeAllListeners();
+  }
+
+  isDisposed(): boolean {
+    return this.disposed;
+  }
+}

package/src/backend/hook-parity.ts

@@ -0,0 +1,19 @@
+// src/backend/hook-parity.ts — declared per-backend hook parity (SPEC-3 §2.3, §4.6).
+// The chip is a static backend property, never inferred at spawn time.
+
+export type HookState = "✓" | "~";
+
+export interface BackendHookParity {
+  /** `todo` tool excluded from the child. */
+  todo: HookState;
+  /** memory-hydrate (3-scope) active in the child. */
+  memory: HookState;
+  /** vision: capability-aware. `✓` = full (describe_image fallback); `~` = pass-through only. */
+  vision: HookState;
+}
+
+/** Pi backend: full moat via loader injection + customTools (SPEC-2). */
+export const PI_HOOK_PARITY: BackendHookParity = { todo: "✓", memory: "✓", vision: "✓" };
+
+/** CC backend: moat via prompt/flag translation. Vision has no describe_image fallback (`~`). */
+export const CLAUDE_HOOK_PARITY: BackendHookParity = { todo: "✓", memory: "✓", vision: "~" };

package/src/backend/port.ts

@@ -0,0 +1,5 @@
+// src/backend/port.ts — single import surface for engine + views (SPEC-3 §3).
+export type { BackendHookParity, HookState } from "./hook-parity.ts";
+export { PI_HOOK_PARITY, CLAUDE_HOOK_PARITY } from "./hook-parity.ts";
+export type { Backend, BackendVersionInfo } from "./registry.ts";
+export { BackendRegistry } from "./registry.ts";

package/src/backend/registry.ts

@@ -0,0 +1,36 @@
+// src/backend/registry.ts — BackendRegistry + Backend descriptor (SPEC-3 §2.1).
+import type { ChildSessionFactory } from "../engine/spawnSubagent.ts";
+import type { BackendHookParity } from "./hook-parity.ts";
+
+export interface BackendVersionInfo {
+  version: string;
+  schemaOk: boolean;
+  /** Flag support matrix probed at detect time (kebab-case flag → supported?). */
+  flagSupport: Record<string, boolean>;
+  note?: string;
+}
+
+export interface Backend {
+  id: "pi" | "claude";
+  factory: ChildSessionFactory;
+  available: () => boolean;
+  versionInfo: () => BackendVersionInfo | null;
+  hookParity: BackendHookParity;
+}
+
+export class BackendRegistry {
+  private readonly backends = new Map<string, Backend>();
+  private readonly order: string[] = [];
+
+  register(b: Backend): void {
+    if (!this.backends.has(b.id)) this.order.push(b.id);
+    this.backends.set(b.id, b);
+  }
+  get(id: string): Backend | undefined {
+    return this.backends.get(id);
+  }
+  /** Registration-order list — the data source for the Backends view + engine lookup. */
+  list(): Backend[] {
+    return this.order.map((id) => this.backends.get(id)!).filter(Boolean);
+  }
+}

package/src/backend/resume-store.ts

@@ -0,0 +1,44 @@
+// src/backend/resume-store.ts — file-backed sessionKey → backendSessionId, per backend (SPEC-3 §2.4, §4.3).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+function rootDir(): string {
+  return process.env.FLEET_RESUME_ROOT ?? join(process.env.HOME ?? "/tmp", ".pi", "agent", "cache", "fleet-resume");
+}
+
+/** Per-backend JSON map: { [sessionKey]: backendSessionId }. */
+function fileFor(backendId: string): string {
+  return join(rootDir(), `${backendId}.json`);
+}
+
+function readMap(backendId: string): Record<string, string> {
+  const f = fileFor(backendId);
+  if (!existsSync(f)) return {};
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+function writeMap(backendId: string, m: Record<string, string>): void {
+  const dir = rootDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(fileFor(backendId), JSON.stringify(m, null, 2));
+}
+
+export class ResumeStore {
+  get(backendId: string, sessionKey: string): string | null {
+    return readMap(backendId)[sessionKey] ?? null;
+  }
+  set(backendId: string, sessionKey: string, backendSessionId: string): void {
+    const m = readMap(backendId);
+    m[sessionKey] = backendSessionId;
+    writeMap(backendId, m);
+  }
+  clear(backendId: string, sessionKey: string): void {
+    const m = readMap(backendId);
+    delete m[sessionKey];
+    writeMap(backendId, m);
+  }
+}

package/src/engine/run-registry.ts

@@ -12,6 +12,10 @@ export interface RunRecord {
   startedAt: number;
   endedAt?: number;
   resultSummary?: string;
+  /** Backend-native session id for resume (SPEC-3). */
+  backendSessionId?: string | null;
+  /** The sessionKey whose resume this run belongs to (SPEC-3). */
+  sessionKey?: string | null;
 }
 
 /** runId format: fl-<base36 ms>-<6 random> (SPEC-1 §5.1). */

package/src/engine/spawnSubagent.ts

@@ -3,6 +3,7 @@ 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 type { BackendRegistry } from "../backend/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";
@@ -25,6 +26,8 @@ export interface ChildSessionEvent {
     content?: Array<{ type: string; text?: string }>;
     usage?: { cost?: { total?: number } };
   };
+  /** Emitted by a backend on session init (SPEC-3). Drives runRecord.backendSessionId. */
+  backendSessionId?: string;
 }
 
 export interface ChildSession {
@@ -62,7 +65,7 @@ export interface SpawnOptions {
   todoSync: TodoSyncPort;
   runRegistry: RunRegistry;
   lock: SingleSlotLock;
-  childFactory: ChildSessionFactory;
+  backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory — engine looks up by agentDef.backend
   parentModel: { provider: string; id: string };
   parentCwd: string;
   memoryPort?: MemoryHydratePort;
@@ -107,6 +110,13 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
       return fail(runId, startedAt, `agent '${opts.agent}' not in registry; available: ${available}`, opts.agent);
     }
 
+    // SPEC-3: route via the backend registry; fail fast if the backend is missing/unavailable.
+    const backend = opts.backendRegistry.get(agentDef.backend);
+    if (!backend || !backend.available()) {
+      const note = backend?.versionInfo()?.note ?? "not registered";
+      return fail(runId, startedAt, `backend '${agentDef.backend}' unavailable: ${note}`, opts.agent);
+    }
+
     // resolve model
     const model = opts.model ?? agentDef.model ?? `${opts.parentModel.provider}/${opts.parentModel.id}`;
 
@@ -138,7 +148,7 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     }
 
     // spawn child
-    const { session } = await opts.childFactory.create({
+    const { session } = await backend.factory.create({
       cwd: opts.parentCwd,
       model,
       thinkingLevel: agentDef.thinkingLevel,
@@ -160,7 +170,9 @@ export async function spawnSubagent(opts: SpawnOptions): Promise<SpawnResult> {
     opts.signal?.addEventListener("abort", onSignalAbort);
 
     const unsub = session.subscribe((e) => {
-      if (e.type === "turn_end") {
+      if (e.type === "session_init" && e.backendSessionId) {
+        opts.runRegistry.update(runId, { backendSessionId: e.backendSessionId, sessionKey: agentDef.sessionKey });
+      } else 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("") ?? "";

package/src/index.ts

@@ -21,6 +21,10 @@ 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 { BackendRegistry, PI_HOOK_PARITY, CLAUDE_HOOK_PARITY, type Backend } from "./backend/port.ts";
+import { ResumeStore } from "./backend/resume-store.ts";
+import { detectClaude } from "./backend/claude-detector.ts";
+import { createClaudeChildFactory } from "./backend/claude-factory.ts";
 import { join } from "node:path";
 
 /** The package builtin agents/ dir, resolved relative to this module. */
@@ -30,7 +34,44 @@ function builtinAgentsDir(): string {
 
 /** 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 {
+/** SPEC-3: wrap a pi SDK session so it emits session_init on subscribe + forwards the rest. */
+function wrapPiSession(inner: ChildSession, backendSessionId: string): ChildSession {
+  return {
+    prompt: (t) => inner.prompt(t),
+    abort: () => inner.abort(),
+    dispose: () => inner.dispose(),
+    subscribe: (handler) => {
+      handler({ type: "session_init", backendSessionId });
+      return inner.subscribe(handler);
+    },
+  };
+}
+
+/** SPEC-3: build the BackendRegistry — pi always; claude registered with availability reflecting detectClaude(). */
+async function buildDefaultBackendRegistry(modelRuntime: ModelRuntime): Promise<BackendRegistry> {
+  const resumeStore = new ResumeStore();
+  const claudeInfo = await detectClaude();
+  const reg = new BackendRegistry();
+  const pi: Backend = {
+    id: "pi",
+    factory: createChildSessionFactory(modelRuntime, new ArmoryMemoryAdapter(), resumeStore),
+    available: () => true,
+    versionInfo: () => null,
+    hookParity: PI_HOOK_PARITY,
+  };
+  reg.register(pi);
+  // claude is registered regardless of availability so the Backends view can show it; available reflects detection.
+  reg.register({
+    id: "claude",
+    factory: createClaudeChildFactory(claudeInfo, resumeStore),
+    available: () => claudeInfo?.schemaOk === true,
+    versionInfo: () => claudeInfo,
+    hookParity: CLAUDE_HOOK_PARITY,
+  });
+  return reg;
+}
+
+export function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: MemoryHydratePort, resumeStore: ResumeStore): ChildSessionFactory {
   return {
     async create(opts) {
       let model: Model<any> | undefined;
@@ -52,7 +93,10 @@ function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: Memor
         agentDir: getAgentDir(),
       });
       const injectVision = opts.agent.vision && !visionPort.isMultimodal(model);
-      const { session } = await createAgentSession({
+      // SPEC-3 §3.1: file-backed SessionManager so resume works. Resume a prior session when the store has a path.
+      const resumePath = resumeStore.get("pi", opts.agent.sessionKey);
+      const sessionManager = resumePath ? SessionManager.open(resumePath) : SessionManager.create(opts.cwd);
+      const { session: piSession } = await createAgentSession({
         cwd: opts.cwd,
         model,
         thinkingLevel: opts.thinkingLevel,
@@ -60,10 +104,14 @@ function createChildSessionFactory(modelRuntime: ModelRuntime, memoryPort: Memor
         excludeTools: ["todo"],                       // SPEC-2 §9.1 hardened single-writer guard
         customTools: injectVision ? [createDescribeImageTool(visionPort) as never] : [],
         resourceLoader: loader,
-        sessionManager: SessionManager.inMemory(),
+        sessionManager,
         modelRuntime,
       });
-      return { session: session as unknown as ChildSession, model: opts.model ?? "" };
+      // SPEC-3 §4.3: wrap + emit session_init + persist the session file path for resume.
+      const backendSessionId = piSession.sessionFile ?? piSession.sessionId;
+      if (piSession.sessionFile) resumeStore.set("pi", opts.agent.sessionKey, piSession.sessionFile);
+      const session: ChildSession = wrapPiSession(piSession as unknown as ChildSession, backendSessionId);
+      return { session, model: opts.model ?? "" };
     },
   };
 }
@@ -75,7 +123,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     runRegistry: new RunRegistry(),
     lock: createSingleSlotLock(),
     todoSync: new ArmoryTodoAdapter(),
-    childFactory: createChildSessionFactory(modelRuntime, new ArmoryMemoryAdapter()),
+    backendRegistry: await buildDefaultBackendRegistry(modelRuntime),
     parentModel: { provider: "", id: "" },
     parentCwd: "",
   };

package/src/panel/fleet-panel.ts

@@ -11,20 +11,21 @@ import {
 } from "@earendil-works/pi-tui";
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { RunRecord } from "../engine/run-registry.ts";
-import { fleetRow, agentsRow, agentInfo } from "./rows.ts";
-import { spawnSubagent, type ChildSessionFactory, type SpawnResult } from "../engine/spawnSubagent.ts";
+import { fleetRow, agentsRow, agentInfo, backendsRow, backendInfo } from "./rows.ts";
+import { spawnSubagent, type SpawnResult } from "../engine/spawnSubagent.ts";
+import type { Backend, BackendRegistry } from "../backend/port.ts";
 import type { RunRegistry } from "../engine/run-registry.ts";
 import type { SingleSlotLock } from "../engine/concurrency-lock.ts";
 import type { TodoSyncPort } from "../todo-sync/port.ts";
 
-type View = "fleet" | "agents";
+type View = "fleet" | "agents" | "backends";
 
 export interface FleetPanelDeps {
   registry: Map<string, AgentDef>;
   runRegistry: RunRegistry;
   lock: SingleSlotLock;
   todoSync: TodoSyncPort;
-  childFactory: ChildSessionFactory;
+  backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory
   parentModel: { provider: string; id: string };
   parentCwd: string;
 }
@@ -48,6 +49,7 @@ export class FleetPanel extends Container {
   private linkInput: Input | null = null;
   private linkPhase: "task" | "link" = "task";
   private infoAgent: AgentDef | null = null;
+  private selectedBackend: Backend | null = null;   // SPEC-3: Backends view i:Info
 
   constructor(opts: FleetPanelOpts) {
     super();
@@ -67,7 +69,9 @@ export class FleetPanel extends Container {
     const items: SelectItem[] =
       this.view === "fleet"
         ? this.deps.runRegistry.list().map((r: RunRecord) => ({ value: r.runId, label: fleetRow(r) }))
-        : [...this.deps.registry.values()].map((a: AgentDef) => ({ value: a.name, label: agentsRow(a) }));
+        : this.view === "agents"
+          ? [...this.deps.registry.values()].map((a: AgentDef) => ({ value: a.name, label: agentsRow(a) }))
+          : this.deps.backendRegistry.list().map((b: Backend) => ({ value: b.id, label: backendsRow(b) }));
     const fresh = new SelectList(items, 12, {
       selectedPrefix: (s: string) => this.theme.fg("accent", s),
       selectedText: (s: string) => this.theme.fg("accent", s),
@@ -85,7 +89,7 @@ export class FleetPanel extends Container {
     this.children.length = 0;
     this.children.push(...keep);
     const accent = (s: string): string => this.theme.fg("accent", s);
-    const tabs = (["fleet", "agents"] as View[])
+    const tabs = (["fleet", "agents", "backends"] as View[])
       .map((v) => (v === this.view ? this.theme.fg("accent", this.theme.bold(`[${v}]`)) : this.theme.fg("dim", v)))
       .join("  ");
     this.addChild(new Text(accent(this.theme.bold("  FLEET")) + "  " + tabs, 0, 0));
@@ -101,17 +105,26 @@ export class FleetPanel extends Container {
       for (const line of agentInfo(this.infoAgent).split("\n")) {
         this.addChild(new Text(this.theme.fg("text", line), 0, 0));
       }
+    } else if (this.selectedBackend) {
+      // SPEC-3: i:Info detail pane (backends view)
+      this.addChild(new Text(this.theme.fg("dim", "  ── backend info ──"), 0, 0));
+      for (const line of backendInfo(this.selectedBackend).split("\n")) {
+        this.addChild(new Text(this.theme.fg("text", line), 0, 0));
+      }
+      this.addChild(new Text(this.theme.fg("dim", "  esc:Back"), 0, 0));
     } else {
       this.addChild(this.list);
     }
 
     this.addChild(new Spacer(1));
     const hint =
-      this.infoAgent
+      this.infoAgent || this.selectedBackend
         ? "  esc:Back"
         : this.view === "fleet"
           ? "  r:Run-new  s:Stop  o:Open-todo  tab:Agents  q:Quit"
-          : "  r:Run  e:Edit  i:Info  d:Reload  tab:Fleet  q:Quit";
+          : this.view === "agents"
+            ? "  r:Run  e:Edit  i:Info  d:Reload  tab:Backends  q:Quit"
+            : "  r:Refresh  i:Info  tab:Fleet  q:Quit";
     this.addChild(new Text(this.theme.fg("dim", hint), 0, 0));
     this.addChild(new Spacer(1));
     this.addChild(new DynamicBorder(accent));
@@ -151,7 +164,7 @@ export class FleetPanel extends Container {
       agent, task, todoId, track: true,
       registry: this.deps.registry, todoSync: this.deps.todoSync,
       runRegistry: this.deps.runRegistry, lock: this.deps.lock,
-      childFactory: this.deps.childFactory,
+      backendRegistry: this.deps.backendRegistry,
       parentModel: this.deps.parentModel, parentCwd: this.deps.parentCwd,
       // live Fleet row during the run (SPEC-1 §4c) — re-render on each turn_end
       onEvent: (e) => {
@@ -177,7 +190,8 @@ export class FleetPanel extends Container {
   }
 
   private switchView(): void {
-    this.view = this.view === "fleet" ? "agents" : "fleet";
+    this.view = this.view === "fleet" ? "agents" : this.view === "agents" ? "backends" : "fleet";
+    this.selectedBackend = null;
     this.list = this.buildList();
     this.renderShell();
   }
@@ -187,6 +201,10 @@ export class FleetPanel extends Container {
       if (matchesKey(data, "escape")) { this.infoAgent = null; this.renderShell(); }
       return;
     }
+    if (this.selectedBackend) {
+      if (matchesKey(data, "escape")) { this.selectedBackend = null; this.renderShell(); }
+      return;
+    }
     if (this.runMode && (this.taskInput || this.linkInput)) {
       if (matchesKey(data, "escape")) { this.cancelRun(); return; }
       (this.linkPhase === "task" ? this.taskInput! : this.linkInput!).handleInput(data);
@@ -206,6 +224,16 @@ export class FleetPanel extends Container {
       if (sel) { this.infoAgent = this.deps.registry.get(sel.value) ?? null; this.renderShell(); }
       return;
     }
+    if (matchesKey(data, "i") && this.view === "backends") {
+      const sel = this.list.getSelectedItem();
+      if (sel) { this.selectedBackend = this.deps.backendRegistry.list().find((x) => x.id === sel.value) ?? null; this.renderShell(); }
+      return;
+    }
+    if (matchesKey(data, "r") && this.view === "backends") {
+      this.onNotify("Backends reflect init-time detection; restart pi to re-detect.", "info");
+      this.renderShell();
+      return;
+    }
     this.list.handleInput(data);
     this.invalidate();
   }

package/src/panel/rows.ts

@@ -2,6 +2,7 @@
 import type { AgentDef } from "../registry/frontmatter.ts";
 import type { FleetRunStatus } from "../todo-sync/port.ts";
 import type { RunRecord } from "../engine/run-registry.ts";
+import type { Backend, BackendHookParity } from "../backend/port.ts";
 
 export function fmtDuration(ms: number): string {
   const s = Math.floor(ms / 1000);
@@ -30,7 +31,7 @@ export function agentsRow(agent: AgentDef): string {
   const chip = `armory:[t${agent.todoSync ? "✓" : "✗"} m${agent.memoryHydrate ? "✓" : "✗"} v${agent.vision ? "✓" : "✗"}]`;
   const skills = agent.skills?.length ? `  skills: ${agent.skills.join(",")}` : "";
   const tools = agent.tools?.length ? `  tools: ${agent.tools.join(",")}` : "";
-  return `${agent.name}  [${agent.source}]  ${model}${tools}${skills}  ${chip}`;
+  return `${agent.name}  [${agent.backend}]  [${agent.source}]  ${model}${tools}${skills}  ${chip}`;
 }
 
 export function agentInfo(agent: AgentDef): string {
@@ -50,4 +51,34 @@ export function agentInfo(agent: AgentDef): string {
     agent.rolePrompt.trim(),
   ];
   return lines.join("\n");
-}
+}
+function chipStr(p: BackendHookParity): string {
+  return `t${p.todo} m${p.memory} v${p.vision}`;
+}
+
+export function backendsRow(b: Backend): string {
+  const avail = b.available() ? "✓" : "✗";
+  const vi = b.versionInfo();
+  const version = vi?.version ? vi.version : "—";
+  const schema = vi ? (vi.schemaOk ? "✓" : "✗") : "—";
+  const note = vi && !vi.schemaOk && vi.note ? `  ${vi.note}` : "";
+  return `${b.id}  ${avail}  ${version}  schema:${schema}  armory:[${chipStr(b.hookParity)}]${note}`;
+}
+
+export function backendInfo(b: Backend): string {
+  const vi = b.versionInfo();
+  const lines = [
+    `id: ${b.id}`,
+    `available: ${b.available() ? "✓" : "✗"}`,
+    `version: ${vi?.version ?? "—"}`,
+    `schemaOk: ${vi ? vi.schemaOk : "—"}`,
+  ];
+  if (vi?.note) lines.push(`note: ${vi.note}`);
+  lines.push("flagSupport:");
+  for (const [flag, ok] of Object.entries(vi?.flagSupport ?? {})) lines.push(`  ${flag}: ${ok ? "✓" : "✗"}`);
+  lines.push("hookParity:");
+  lines.push(`  todo: ${b.hookParity.todo}  (excluded via ${b.id === "pi" ? "excludeTools+noExtensions" : "--disallowed-tools/prompt-nudge"})`);
+  lines.push(`  memory: ${b.hookParity.memory}  (${b.id === "pi" ? "CustomResourceLoader systemPromptOverride" : "--append-system-prompt"})`);
+  lines.push(`  vision: ${b.hookParity.vision}  (${b.hookParity.vision === "✓" ? "describe_image fallback injected" : "pass-through only; no describe_image fallback — customTools not injectable into claude -p"})`);
+  return lines.join("\n");
+}

package/src/registry/frontmatter.ts

@@ -16,6 +16,10 @@ export interface AgentDef {
   todoSync: boolean;
   memoryHydrate: boolean;
   vision: boolean;
+  /** Cross-harness backend routing (SPEC-3). Invalid value → FrontmatterError. */
+  backend: "pi" | "claude";
+  /** Stable id for backend-native resume (SPEC-3). Defaults to name. */
+  sessionKey: string;
   source: AgentSource;
   filePath: string;
 }
@@ -52,6 +56,13 @@ export function parseAgentFile(content: string, filePath: string, source: AgentS
   const memoryHydrate = raw.memoryHydrate === undefined ? true : Boolean(raw.memoryHydrate);
   const vision = raw.vision === undefined ? true : Boolean(raw.vision);
 
+  const rawBackend = typeof raw.backend === "string" ? raw.backend.trim() : "pi";
+  if (rawBackend !== "pi" && rawBackend !== "claude") {
+    throw new FrontmatterError(`${filePath}: invalid backend '${rawBackend}' (must be 'pi' | 'claude')`);
+  }
+  const backend = rawBackend as "pi" | "claude";
+  const sessionKey = typeof raw.sessionKey === "string" && raw.sessionKey.trim() ? raw.sessionKey.trim() : name;
+
   return {
     name,
     description,
@@ -63,6 +74,8 @@ export function parseAgentFile(content: string, filePath: string, source: AgentS
     todoSync,
     memoryHydrate,
     vision,
+    backend,
+    sessionKey,
     source,
     filePath,
   };

package/src/tools/subagent.ts

@@ -4,8 +4,9 @@ import type { AgentDef } from "../registry/frontmatter.ts";
 import type { TodoSyncPort } from "../todo-sync/port.ts";
 import type { RunRegistry } from "../engine/run-registry.ts";
 import type { SingleSlotLock } from "../engine/concurrency-lock.ts";
-import type { ChildSessionFactory, SpawnResult } from "../engine/spawnSubagent.ts";
+import type { SpawnResult } from "../engine/spawnSubagent.ts";
 import { spawnSubagent } from "../engine/spawnSubagent.ts";
+import type { BackendRegistry } from "../backend/port.ts";
 
 export const subagentParams = Type.Object({
   agent: Type.String({ description: "Agent name from the registry (builtin, project, or global)." }),
@@ -22,7 +23,7 @@ export interface SubagentToolDeps {
   runRegistry: RunRegistry;
   lock: SingleSlotLock;
   todoSync: TodoSyncPort;
-  childFactory: ChildSessionFactory;
+  backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory
   parentModel: { provider: string; id: string };
   parentCwd: string;
 }
@@ -51,7 +52,7 @@ export function createSubagentTool(deps: SubagentToolDeps) {
         todoSync: deps.todoSync,
         runRegistry: deps.runRegistry,
         lock: deps.lock,
-        childFactory: deps.childFactory,
+        backendRegistry: deps.backendRegistry,
         parentModel: deps.parentModel,
         parentCwd: deps.parentCwd,
         signal,