@getpipher/armory-fleet 0.2.0 → 0.4.0

package/src/panel/fleet-panel.ts

@@ -11,22 +11,30 @@ 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, lifecycleRow, lifecyclePhaseTimeline } 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";
+import type { LifecycleDef, LifecycleRunRecord, CheckpointDecision, PhaseRecord } from "../lifecycle/lifecycle-types.ts";
+import type { LifecycleRunDeps, CheckpointFn } from "../lifecycle/run-lifecycle.ts";
+import { runLifecycle } from "../lifecycle/run-lifecycle.ts";
 
-type View = "fleet" | "agents";
+type View = "fleet" | "lifecycle" | "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;
+  /** SPEC-4: lifecycle registry + active/recent run records + deps to drive checkpoints. */
+  lifecycleRegistry: Map<string, LifecycleDef>;
+  lifecycleRuns: Map<string, LifecycleRunRecord>;
+  lifecycleDeps: Omit<LifecycleRunDeps, "spawn">;
 }
 
 export interface FleetPanelOpts {
@@ -48,6 +56,17 @@ 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
+  private selectedLifecycle: LifecycleRunRecord | null = null;   // SPEC-4: Lifecycle view i:Info
+  // SPEC-4: Run-lifecycle inline input state
+  private lcRunMode = false;
+  private lcTaskInput: Input | null = null;
+  private lcNameInput: Input | null = null;
+  private lcPhase: "task" | "name" = "task";
+  // SPEC-4: pending checkpoint (interactive Continue/Revise/Abort)
+  private pendingCheckpoint: { phase: PhaseRecord; resolve: (d: CheckpointDecision) => void } | null = null;
+  private lcReviseInput: Input | null = null;
+  private lcRevising = false;
 
   constructor(opts: FleetPanelOpts) {
     super();
@@ -67,7 +86,11 @@ 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 === "lifecycle"
+          ? [...this.deps.lifecycleRuns.values()].map((l: LifecycleRunRecord) => ({ value: l.runId, label: lifecycleRow(l) }))
+          : 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 +108,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", "lifecycle", "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 +124,53 @@ 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 if (this.selectedLifecycle) {
+      // SPEC-4: i:Info detail pane (lifecycle view) — phase timeline
+      this.addChild(new Text(this.theme.fg("dim", "  ── lifecycle phases ──"), 0, 0));
+      for (const line of lifecyclePhaseTimeline(this.selectedLifecycle).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 if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput)) {
+      const prompt = this.lcPhase === "task" ? "  task> " : "  lifecycle name (blank=default)> ";
+      this.addChild(new Text(this.theme.fg("accent", prompt), 0, 0));
+      this.addChild(this.lcPhase === "task" ? this.lcTaskInput! : this.lcNameInput!);
+      this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
+    } else if (this.pendingCheckpoint && !this.lcRevising) {
+      const pc = this.pendingCheckpoint;
+      this.addChild(new Text(this.theme.fg("dim", `  ── checkpoint: phase '${pc.phase.name}' (${pc.phase.status}) ──`), 0, 0));
+      this.addChild(new Text(this.theme.fg("text", `  ${pc.phase.summary.slice(0, 200)}`), 0, 0));
+      this.addChild(new Text(this.theme.fg("dim", "  c:Continue  v:Revise  a:Abort"), 0, 0));
+    } else if (this.lcRevising && this.lcReviseInput) {
+      this.addChild(new Text(this.theme.fg("accent", "  revise feedback> "), 0, 0));
+      this.addChild(this.lcReviseInput);
+      this.addChild(new Text(this.theme.fg("dim", "  enter submit • esc cancel"), 0, 0));
     } else {
       this.addChild(this.list);
     }
 
     this.addChild(new Spacer(1));
     const hint =
-      this.infoAgent
+      this.infoAgent || this.selectedBackend || this.selectedLifecycle
         ? "  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.pendingCheckpoint
+          ? "  c:Continue  v:Revise  a:Abort"
+          : this.lcRevising
+            ? "  enter:Submit-feedback  esc:Cancel"
+            : this.view === "fleet"
+              ? "  r:Run-new  s:Stop  o:Open-todo  tab:Lifecycle  q:Quit"
+              : this.view === "lifecycle"
+                ? "  r:Run-lifecycle  i:Info  tab:Agents  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 +210,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 +236,11 @@ export class FleetPanel extends Container {
   }
 
   private switchView(): void {
-    this.view = this.view === "fleet" ? "agents" : "fleet";
+    this.view = this.view === "fleet" ? "lifecycle"
+      : this.view === "lifecycle" ? "agents"
+      : this.view === "agents" ? "backends" : "fleet";
+    this.selectedBackend = null;
+    this.selectedLifecycle = null;
     this.list = this.buildList();
     this.renderShell();
   }
@@ -187,13 +250,36 @@ 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.selectedLifecycle) {
+      if (matchesKey(data, "escape")) { this.selectedLifecycle = null; this.renderShell(); }
+      return;
+    }
+    if (this.lcRunMode && (this.lcTaskInput || this.lcNameInput)) {
+      if (matchesKey(data, "escape")) { this.cancelLifecycleRun(); return; }
+      (this.lcPhase === "task" ? this.lcTaskInput! : this.lcNameInput!).handleInput(data);
+      this.invalidate();
+      return;
+    }
     if (this.runMode && (this.taskInput || this.linkInput)) {
       if (matchesKey(data, "escape")) { this.cancelRun(); return; }
       (this.linkPhase === "task" ? this.taskInput! : this.linkInput!).handleInput(data);
       this.invalidate();
       return;
     }
-    if (matchesKey(data, "escape")) { this.onDone(); return; }
+    if (matchesKey(data, "escape")) {
+      // SPEC-4: if a lifecycle checkpoint is pending, resolve it as abort so runLifecycle
+      // doesn't hang + the lifecycle TODO is reverted (not orphaned) when the panel closes.
+      if (this.pendingCheckpoint) {
+        this.pendingCheckpoint.resolve({ action: "abort" });
+        this.pendingCheckpoint = null;
+      }
+      this.onDone();
+      return;
+    }
     if (matchesKey(data, "tab")) { this.switchView(); return; }
     if (matchesKey(data, "q")) { this.onDone(); return; }
     if (matchesKey(data, "r") && this.view === "agents") {
@@ -206,9 +292,115 @@ 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;
+    }
+    // SPEC-4: Lifecycle view — i:Info + r:Run-lifecycle
+    if (matchesKey(data, "i") && this.view === "lifecycle") {
+      const sel = this.list.getSelectedItem();
+      if (sel) { this.selectedLifecycle = this.deps.lifecycleRuns.get(sel.value) ?? null; this.renderShell(); }
+      return;
+    }
+    if (matchesKey(data, "r") && this.view === "lifecycle") {
+      this.startLifecycleRun();
+      return;
+    }
+    // SPEC-4: pending checkpoint keys (c/v/a)
+    if (this.pendingCheckpoint && !this.lcRevising) {
+      if (matchesKey(data, "c")) { this.pendingCheckpoint.resolve({ action: "continue" }); this.pendingCheckpoint = null; this.renderShell(); return; }
+      if (matchesKey(data, "a")) { this.pendingCheckpoint!.resolve({ action: "abort" }); this.pendingCheckpoint = null; this.renderShell(); return; }
+      if (matchesKey(data, "v")) {
+        this.lcRevising = true;
+        this.lcReviseInput = new Input();
+        this.lcReviseInput.onSubmit = (fb: string) => {
+          this.lcRevising = false;
+          this.lcReviseInput = null;
+          this.pendingCheckpoint!.resolve({ action: "revise", feedback: fb });
+          this.pendingCheckpoint = null;
+          this.renderShell();
+        };
+        this.lcReviseInput.onEscape = () => { this.lcRevising = false; this.lcReviseInput = null; this.renderShell(); };
+        this.renderShell();
+        return;
+      }
+    }
+    if (this.lcRevising && this.lcReviseInput) {
+      if (matchesKey(data, "escape")) { this.lcRevising = false; this.lcReviseInput = null; this.renderShell(); return; }
+      this.lcReviseInput.handleInput(data);
+      this.invalidate();
+      return;
+    }
     this.list.handleInput(data);
     this.invalidate();
   }
+
+  /** SPEC-4: open the Run-lifecycle inline inputs (task → lifecycle name → start runLifecycle). */
+  private startLifecycleRun(): void {
+    this.lcPhase = "task";
+    this.lcTaskInput = new Input();
+    this.lcTaskInput.onSubmit = (task: string) => {
+      if (!task.trim()) { this.cancelLifecycleRun(); return; }
+      this.lcPhase = "name";
+      this.lcNameInput = new Input();
+      this.lcNameInput.onSubmit = (name: string) => {
+        const lcName = name.trim() || "default";
+        void this.executeLifecycleRun(task.trim(), lcName);
+      };
+      this.lcNameInput.onEscape = () => { void this.executeLifecycleRun(task.trim(), "default"); };
+      this.renderShell();
+    };
+    this.lcTaskInput.onEscape = () => this.cancelLifecycleRun();
+    this.lcRunMode = true;
+    this.renderShell();
+  }
+
+  private cancelLifecycleRun(): void {
+    this.lcRunMode = false;
+    this.lcTaskInput = null;
+    this.lcNameInput = null;
+    this.renderShell();
+  }
+
+  private async executeLifecycleRun(task: string, lifecycleName: string): Promise<void> {
+    this.lcRunMode = false;
+    this.lcTaskInput = null;
+    this.lcNameInput = null;
+    this.renderShell();
+    if (!this.deps.lifecycleRegistry.has(lifecycleName)) {
+      this.onNotify(`lifecycle '${lifecycleName}' not found; available: ${[...this.deps.lifecycleRegistry.keys()].sort().join(", ")}`, "error");
+      return;
+    }
+    const onCheckpoint: CheckpointFn = (phase) => new Promise<CheckpointDecision>((resolve) => {
+      this.pendingCheckpoint = { phase, resolve };
+      this.renderShell();
+    });
+    const lifecycleFullDeps: LifecycleRunDeps = {
+      ...this.deps.lifecycleDeps,
+      spawn: async (o) => {
+        const { spawnSubagent } = await import("../engine/spawnSubagent.ts");
+        return spawnSubagent({
+          agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+            skillsOverride: o.skills, backendOverride: o.backend,
+          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,
+        });
+      },
+    };
+    const res = await runLifecycle(task, lifecycleName, { deps: lifecycleFullDeps, mode: "checkpointed", onCheckpoint });
+    this.pendingCheckpoint = null;
+    // record the run so the Lifecycle view shows it
+    this.deps.lifecycleRuns.set(res.runId, res);
+    this.list = this.buildList();
+    this.renderShell();
+    this.onNotify(`lifecycle ${res.status}: ${res.runId}${res.error ? " — " + res.error : ""}`, res.status === "completed" ? "info" : "warning");
+  }
 }
 
 /** Factory used by src/index.ts to open the panel via ctx.ui.custom. */

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,68 @@ 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");
+}
+
+import type { LifecycleRunRecord, LifecycleStatus } from "../lifecycle/lifecycle-types.ts";
+
+const LC_GLYPH: Record<LifecycleStatus, string> = {
+  running: "▶", checkpoint: "⏸", completed: "✓", failed: "✗", aborted: "✗",
+};
+
+export function lifecycleRow(r: LifecycleRunRecord): string {
+  const dur = r.endedAt ? fmtDuration(r.endedAt - r.startedAt) : "—";
+  const curIdx = r.phases.findIndex((p) => p.status === "running");
+  const cur = curIdx >= 0 ? r.phases[curIdx] : r.phases[r.phases.length - 1];
+  const curName = cur ? `●${cur.name}` : "—";
+  // N/M = current phase position / total (1-indexed); falls back to last phase when none running.
+  const counts = `${(curIdx >= 0 ? curIdx + 1 : r.phases.length)}/${r.phases.length}`;
+  return `${LC_GLYPH[r.status]} ${r.runId}  ${r.lifecycleName}  ${curName} ${counts}  ${r.mode}  ${dur}  ${r.backend}  "${r.task}"`;
+}
+
+export function lifecyclePhaseTimeline(r: LifecycleRunRecord): string {
+  const lines: string[] = [
+    `Lifecycle ${r.runId} — ${r.lifecycleName} — "${r.task}"`,
+    `Backend: ${r.backend} · Mode: ${r.mode} · Status: ${r.status}`,
+    "",
+    "Phases:",
+  ];
+  for (const p of r.phases) {
+    const mark = p.reviseCount > 0 ? "[~]" : p.status === "completed" ? "[x]" : "[ ]";
+    const art = p.paths.length ? ` → ${p.paths.join(", ")}` : "";
+    lines.push(`  ${mark} ${p.name}  ${p.status}${art}${p.paths.length ? "  [Open]" : ""}`);
+  }
+  if (r.status === "checkpoint") {
+    lines.push("", "── Checkpoint ──", "[Continue]  [Revise]  [Abort]");
+  }
+  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/todo-sync/adapter.ts

@@ -81,4 +81,10 @@ export class ArmoryTodoAdapter implements TodoSyncPort {
     }
     appendNote(todoId, `fleet-run reverted: ${reason}`);
   }
+
+  async updateLifecycleProgress(todoId: string, progressBlock: string): Promise<void> {
+    if (!todoId) return;
+    // single-writer: replace notes wholesale with the progress block (the lifecycle owns it)
+    updateTodo(todoId, { notes: progressBlock });
+  }
 }

package/src/todo-sync/port.ts

@@ -38,4 +38,6 @@ export interface TodoSyncPort {
   markRunTodoDone(todoId: string | null, priorStatus: string | undefined, result: string): Promise<void>;
   /** After a failed/aborted run: fleet-created -> open; linked -> restore prior. + reason note. */
   markRunTodoReverted(todoId: string | null, priorStatus: string | undefined, reason: string): Promise<void>;
+  /** SPEC-4: replace a lifecycle todo's notes with the phase-progress block (single source of truth). */
+  updateLifecycleProgress(todoId: string, progressBlock: string): Promise<void>;
 }

package/src/tools/subagent.ts

@@ -4,8 +4,11 @@ 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";
+import type { LifecycleRunDeps } from "../lifecycle/run-lifecycle.ts";
+import type { LifecycleDef } from "../lifecycle/lifecycle-types.ts";
 
 export const subagentParams = Type.Object({
   agent: Type.String({ description: "Agent name from the registry (builtin, project, or global)." }),
@@ -13,6 +16,8 @@ export const subagentParams = Type.Object({
   todoId: Type.Optional(Type.String({ description: "Explicit link to an existing open/in_progress armory-todo todo. Omit to create a fleet task." })),
   track: Type.Optional(Type.Boolean({ description: "Default true. Pass false only for throwaway lookups that don't represent real work." })),
   model: Type.Optional(Type.String({ description: 'Override the agent model, e.g. "anthropic/claude-sonnet-4".' })),
+  lifecycle: Type.Optional(Type.String({ description: "Run a multi-phase superpowers lifecycle by name (e.g. 'default') instead of a single delegate. Tool-driven lifecycles run end-to-end (auto) — checkpoints are a /fleet panel feature." })),
+  auto: Type.Optional(Type.Boolean({ description: "Only relevant with `lifecycle`. Tool-driven is always auto; this flag is forward-compat. Panel-driven uses --auto on /fleet-implement." })),
 });
 
 export type SubagentInput = Static<typeof subagentParams>;
@@ -22,9 +27,13 @@ export interface SubagentToolDeps {
   runRegistry: RunRegistry;
   lock: SingleSlotLock;
   todoSync: TodoSyncPort;
-  childFactory: ChildSessionFactory;
+  backendRegistry: BackendRegistry;   // SPEC-3: replaces childFactory
   parentModel: { provider: string; id: string };
   parentCwd: string;
+  /** SPEC-4: lifecycle registry + spawn adapter (tool-driven = auto). */
+  lifecycleRegistry: Map<string, LifecycleDef>;
+  lifecycleRuns: Map<string, import("../lifecycle/lifecycle-types.ts").LifecycleRunRecord>;
+  lifecycleDeps: Omit<LifecycleRunDeps, "spawn">;
 }
 
 /** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
@@ -41,6 +50,30 @@ export function createSubagentTool(deps: SubagentToolDeps) {
     ],
     parameters: subagentParams,
     async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      if (params.lifecycle) {
+        const { runLifecycle } = await import("../lifecycle/run-lifecycle.ts");
+        const lifecycleFullDeps: LifecycleRunDeps = {
+          ...deps.lifecycleDeps,
+          spawn: async (o) => spawnSubagent({
+            agent: o.agent, task: o.task, lifecycleTodoId: o.lifecycleTodoId, model: o.model,
+            skillsOverride: o.skills, backendOverride: o.backend,
+            registry: deps.registry, todoSync: deps.todoSync, runRegistry: deps.runRegistry, lock: deps.lock,
+            backendRegistry: deps.backendRegistry, parentModel: deps.parentModel, parentCwd: deps.parentCwd, signal,
+          }),
+        };
+        const res = await runLifecycle(params.task, params.lifecycle, {
+          deps: lifecycleFullDeps, mode: "auto",
+          onCheckpoint: async (phase) => phase.status === "failed" ? { action: "abort" } : { action: "continue" },
+        });
+        const isError = res.status === "failed" || res.status === "aborted";
+        const summary = `lifecycle ${res.lifecycleName}: ${res.status} (${res.phases.length} phases)\n` +
+          res.phases.map((p) => `  ${p.name}: ${p.status}${p.paths.length ? " → " + p.paths.join(", ") : ""}`).join("\n");
+        return {
+          content: [{ type: "text" as const, text: isError ? (res.error ?? res.status) : summary }],
+          details: { runId: res.runId, todoId: res.todoId, lifecycle: res.lifecycleName, status: res.status, phases: res.phases.length },
+          isError,
+        };
+      }
       const res: SpawnResult = await spawnSubagent({
         agent: params.agent,
         task: params.task,
@@ -51,7 +84,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,