@getpipher/armory-fleet 0.4.0 → 0.5.1

package/src/runtime/async-runner.ts

@@ -0,0 +1,123 @@
+// src/runtime/async-runner.ts
+// SPEC-5a §2/§6/§7/§8/§10 — the async/bg path. Layers ABOVE the unchanged runLifecycle:
+// creates a worktree, journals events, drives runLifecycle with the worktree cwd, discovers
+// artifacts via DiffService, commits on completion, pushes to the inbox, notifies.
+import type { WorktreeService } from "../worktree/worktree-service.ts";
+import type { DiffService } from "../worktree/diff-service.ts";
+import type { RunJournal, JournalEvent } from "./run-journal.ts";
+import type { ConcurrencyPool } from "./concurrency-pool.ts";
+import type { ResultsInbox, RunResult } from "./results-inbox.ts";
+import { execSync } from "node:child_process";
+
+// Thin shape of the LifecycleRunResult we need (avoids importing the full type here — the
+// real adapter in index.ts maps the full LifecycleRunResult to this shape).
+export interface FakeLifecycleResult {
+  runId: string;
+  lifecycleName: string;
+  task: string;
+  status: "completed" | "failed" | "aborted";
+  phases: Array<{ name: string; status: string; summary: string; paths: string[]; reviseCount: number }>;
+  todoId: string | null;
+  error?: string;
+}
+
+export interface RunLifecycleOpts {
+  runId: string;
+  worktreePath: string;
+  branch: string;
+  mode: "auto" | "checkpointed";
+}
+
+export type RunLifecycleFn = (task: string, lifecycleName: string, opts: RunLifecycleOpts) => Promise<FakeLifecycleResult>;
+
+export interface AsyncRunnerDeps {
+  worktree: WorktreeService;
+  diff: DiffService;
+  journal: RunJournal;
+  pool: ConcurrencyPool;
+  inbox: ResultsInbox;
+  runLifecycle: RunLifecycleFn;
+  notify: (msg: string, level?: "info" | "warning" | "error") => void;
+  genRunId: () => string;
+  /** SPEC-5a: called at each run/phase transition so the host (index.ts) can update the live bgRuns map. */
+  onProgress?: (runId: string, status: import("../panel/rows.ts").BgRunStatus) => void;
+}
+
+export interface RunBackgroundOpts {
+  deps: AsyncRunnerDeps;
+  lifecycle: string;
+  mode: "auto" | "checkpointed";
+}
+
+export interface RunBackgroundHandle {
+  runId: string;
+  status: "background";
+}
+
+function emitProgress(deps: AsyncRunnerDeps, runId: string, partial: Partial<import("../panel/rows.ts").BgRunStatus> & { status: import("../panel/rows.ts").BgStatus; phase: string; phaseIndex: number; phaseTotal: number }): void {
+  if (!deps.onProgress) return;
+  deps.onProgress(runId, {
+    runId,
+    lifecycle: "",
+    mode: "auto",
+    backend: "pi",
+    task: "",
+    ...partial,
+  });
+}
+
+function sh(cmd: string, cwd: string): void {
+  execSync(cmd, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+}
+
+export function runBackground(task: string, opts: RunBackgroundOpts): RunBackgroundHandle {
+  const { deps } = opts;
+  const runId = deps.genRunId();
+  const baseRef = "HEAD";
+
+  // Fire-and-forget: the pool gates concurrency; the journal records the run.
+  void deps.pool.withSlot(async () => {
+    let wt: { path: string; branch: string } | null = null;
+    try {
+      wt = deps.worktree.create(runId, baseRef);
+      const ev0: JournalEvent = { type: "run:started", runId, task, lifecycle: opts.lifecycle, worktree: { path: wt.path, branch: wt.branch }, mode: opts.mode, ts: Date.now() };
+      deps.journal.append(runId, ev0);
+      emitProgress(deps, runId, { status: "running", phase: "", phaseIndex: 0, phaseTotal: 0, lifecycle: opts.lifecycle, mode: opts.mode, task });
+
+      const res = await deps.runLifecycle(task, opts.lifecycle, { runId, worktreePath: wt.path, branch: wt.branch, mode: opts.mode });
+
+      if (res.status === "completed") {
+        // commit the worktree to the branch (lifecycle finish phase or single-delegate completion)
+        try { sh("git add -A && git commit -m 'fleet run complete'", wt.path); } catch { /* nothing to commit */ }
+        deps.journal.append(runId, { type: "run:completed", runId, branch: wt.branch, ts: Date.now() });
+        const total = res.phases.length;
+        const lastIdx = total; // completed = past the last phase
+        emitProgress(deps, runId, { status: "completed", phase: res.phases[total - 1]?.name ?? "finish", phaseIndex: lastIdx, phaseTotal: total, lifecycle: opts.lifecycle, mode: opts.mode, task, branch: wt.branch });
+        const lastPhase = res.phases[res.phases.length - 1];
+        const result: RunResult = {
+          runId, task, status: "completed",
+          summary: lastPhase?.summary ?? "",
+          paths: res.phases.flatMap((p) => p.paths),
+          branch: wt.branch, completedAt: Date.now(),
+        };
+        deps.inbox.push(result);
+        deps.notify(`fleet run ${runId} completed`, "info");
+        // SPEC-5a: the worktree dir is temporary scaffolding; remove it but keep the branch for merge/inspection.
+        deps.worktree.removeWorktree(runId);
+      } else {
+        deps.journal.append(runId, { type: "run:aborted", runId, reason: res.error ?? res.status, ts: Date.now() });
+        deps.worktree.remove(runId);
+        emitProgress(deps, runId, { status: "failed", phase: "", phaseIndex: 0, phaseTotal: res.phases.length, lifecycle: opts.lifecycle, mode: opts.mode, task });
+        deps.notify(`fleet run ${runId} ${res.status}: ${res.error ?? ""}`, "warning");
+      }
+    } catch (e) {
+      const msg = (e as Error).message;
+      deps.journal.append(runId, { type: "run:aborted", runId, reason: msg, ts: Date.now() });
+      if (wt) deps.worktree.remove(runId);
+      deps.notify(`fleet run ${runId} failed: ${msg}`, "error");
+      emitProgress(deps, runId, { status: "failed", phase: "", phaseIndex: 0, phaseTotal: 0, lifecycle: opts.lifecycle, mode: opts.mode, task });
+    }
+  });
+
+  return { runId, status: "background" };
+}

package/src/runtime/concurrency-pool.ts

@@ -0,0 +1,27 @@
+// src/runtime/concurrency-pool.ts
+// SPEC-5a §8 — N-slot semaphore for async/bg runs (Q4=A). Foreground keeps its own
+// single-slot lock (unchanged); this pool is independent.
+
+export class ConcurrencyPool {
+  private active = 0;
+  private waiters: Array<() => void> = [];
+
+  constructor(private readonly cap = 3) {}
+
+  busy(): number { return this.active; }
+  queued(): number { return this.waiters.length; }
+
+  async withSlot<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.active >= this.cap) {
+      await new Promise<void>((resolve) => this.waiters.push(resolve));
+    }
+    this.active++;
+    try {
+      return await fn();
+    } finally {
+      this.active--;
+      const next = this.waiters.shift();
+      if (next) next();
+    }
+  }
+}

package/src/runtime/results-inbox.ts

@@ -0,0 +1,45 @@
+// src/runtime/results-inbox.ts
+// SPEC-5a §10 — in-memory results inbox for completed bg runs (Q6=C).
+// The durable record is the lifecycle TODO notes + journal; this is the fast in-session
+// pointer the agent pulls via fleet.results().
+
+export interface RunResult {
+  runId: string;
+  task: string;
+  status: "completed" | "failed";
+  summary: string;
+  paths: string[];
+  branch?: string;
+  completedAt: number;
+}
+
+export class ResultsInbox {
+  private ready = new Map<string, RunResult>();
+
+  push(result: RunResult): void {
+    this.ready.set(result.runId, result);
+  }
+
+  readyCount(): number {
+    return this.ready.size;
+  }
+
+  pull(runId?: string): RunResult[] {
+    if (runId) {
+      const r = this.ready.get(runId);
+      if (!r) return [];
+      this.ready.delete(runId);
+      return [r];
+    }
+    const all = [...this.ready.values()];
+    this.ready.clear();
+    return all;
+  }
+
+  /** Bounded hint for the parent agent's context: cap at 5, one line, empty when nothing ready. */
+  renderHint(): string {
+    const n = this.ready.size;
+    if (n === 0) return "";
+    return n > 5 ? "5+ fleet results ready (use fleet.results to pull)" : `${n} fleet result${n > 1 ? "s" : ""} ready (use fleet.results to pull)`;
+  }
+}

package/src/runtime/resume.ts

@@ -0,0 +1,48 @@
+// src/runtime/resume.ts
+// SPEC-5a §5.3 — on pi start, scan .pi/fleet/runs/ for non-terminal journals and offer resume.
+// If the worktree is gone, mark the journal run:aborted (worktree-missing).
+import { RunJournal, type JournalEvent } from "./run-journal.ts";
+import type { WorktreeService } from "../worktree/worktree-service.ts";
+
+export interface ResumeCandidate {
+  runId: string;
+  task: string;
+  lifecycle: string;
+  worktreePath: string;
+  branch: string;
+  lastPhase: string | null;
+  canResume: boolean;
+}
+
+export interface ScanResumeOpts {
+  runsDir: string;
+  worktree: WorktreeService;
+}
+
+export function scanResumeCandidates(_projectDir: string, opts: ScanResumeOpts): ResumeCandidate[] {
+  const journal = new RunJournal(opts.runsDir);
+  const ids = journal.scanNonTerminal();
+  const cands: ResumeCandidate[] = [];
+  for (const runId of ids) {
+    const events = journal.replay(runId);
+    const started = events.find((e) => e.type === "run:started") as
+      | (JournalEvent & { type: "run:started" }) | undefined;
+    if (!started) continue;
+    const phaseEvents = events.filter((e) => e.type === "phase:completed" || e.type === "phase:started" || e.type === "phase:failed") as Array<{ phase: string }>;
+    const lastPhase = phaseEvents.length > 0 ? phaseEvents[phaseEvents.length - 1]!.phase : null;
+    const wtExists = opts.worktree.exists(runId);
+    if (!wtExists) {
+      journal.append(runId, { type: "run:aborted", runId, reason: "worktree-missing", ts: Date.now() });
+    }
+    cands.push({
+      runId,
+      task: started.task,
+      lifecycle: started.lifecycle,
+      worktreePath: started.worktree.path,
+      branch: started.worktree.branch,
+      lastPhase,
+      canResume: wtExists,
+    });
+  }
+  return cands;
+}

package/src/runtime/run-journal.ts

@@ -0,0 +1,61 @@
+// src/runtime/run-journal.ts
+// SPEC-5a §5 — JSONL run journal. Append-only (crash-safe: a partial last line is discarded).
+// The event log IS the i:Info timeline + the resume source of truth.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface RunStartedEvent { type: "run:started"; runId: string; task: string; lifecycle: string; worktree: { path: string; branch: string }; mode: "auto" | "checkpointed"; ts: number; }
+export interface PhaseStartedEvent { type: "phase:started"; phase: string; ts: number; }
+export interface PhaseCompletedEvent { type: "phase:completed"; phase: string; summary: string; paths: string[]; ts: number; }
+export interface PhaseFailedEvent { type: "phase:failed"; phase: string; error: string; ts: number; }
+export interface CheckpointEvent { type: "checkpoint"; phase: string; decision: "continue" | "revise" | "abort"; ts: number; }
+export interface RunCompletedEvent { type: "run:completed"; runId: string; branch: string; ts: number; }
+export interface RunAbortedEvent { type: "run:aborted"; runId: string; reason: string; ts: number; }
+
+export type JournalEvent =
+  | RunStartedEvent | PhaseStartedEvent | PhaseCompletedEvent | PhaseFailedEvent
+  | CheckpointEvent | RunCompletedEvent | RunAbortedEvent;
+
+const TERMINAL = new Set<JournalEvent["type"]>(["run:completed", "run:aborted"]);
+
+export class RunJournal {
+  constructor(private readonly dir: string) {}
+
+  private file(runId: string): string {
+    return join(this.dir, `${runId}.jsonl`);
+  }
+
+  append(runId: string, event: JournalEvent): void {
+    mkdirSync(this.dir, { recursive: true });
+    appendFileSync(this.file(runId), JSON.stringify(event) + "\n", "utf8");
+  }
+
+  replay(runId: string): JournalEvent[] {
+    const f = this.file(runId);
+    if (!existsSync(f)) return [];
+    const lines = readFileSync(f, "utf8").split("\n");
+    const events: JournalEvent[] = [];
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        events.push(JSON.parse(line) as JournalEvent);
+      } catch {
+        // partial last line (crash mid-append) — discard
+      }
+    }
+    return events;
+  }
+
+  scanNonTerminal(): string[] {
+    if (!existsSync(this.dir)) return [];
+    const ids: string[] = [];
+    for (const f of readdirSync(this.dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const runId = f.slice(0, -".jsonl".length);
+      const events = this.replay(runId);
+      const last = events[events.length - 1];
+      if (last && !TERMINAL.has(last.type)) ids.push(runId);
+    }
+    return ids;
+  }
+}

package/src/scheduling/expressions.ts

@@ -0,0 +1,60 @@
+// src/scheduling/expressions.ts
+// SPEC-5a §9 — schedule expressions: cron (vendored) + interval + one-shot (Q5=A).
+// The vendored cron-parser lib (v1.1.1) is CommonJS — use createRequire for CJS-in-ESM interop.
+// v1.1.1 has no `tz` option; it uses the process local timezone (the right default for a dev tool).
+import { createRequire } from "node:module";
+
+const cronRequire = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const cronParser = cronRequire("../vendor/cron-parser/lib/parser.js") as {
+  parseExpression(expr: string, opts?: { currentDate?: Date; endDate?: Date }): { next(): Date; prev(): Date; hasNext(): boolean };
+};
+
+export type ScheduleType = "cron" | "interval" | "once";
+
+export interface ScheduleExpression {
+  type: ScheduleType;
+  /** Next fire after `prev` (or from now if prev is null). Returns null when a one-shot has already fired. */
+  nextFire(prev: Date | null): Date | null;
+}
+
+const INTERVAL_RE = /^(\d+)([smhd])$/;
+const INTERVAL_MS: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+export function parseScheduleExpr(expr: string): ScheduleExpression {
+  const s = expr.trim();
+  if (INTERVAL_RE.test(s)) {
+    const m = s.match(INTERVAL_RE)!;
+    const unit = m[2] as "s" | "m" | "h" | "d";
+    const ms = Number(m[1]) * (INTERVAL_MS[unit] ?? 0);
+    return {
+      type: "interval",
+      nextFire: (prev) => new Date((prev ?? new Date()).getTime() + ms),
+    };
+  }
+  // one-shot ISO datetime (contains a 'T' and parses as a single Date)
+  if (s.includes("T") && /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(s)) {
+    const fire = new Date(s);
+    if (isNaN(fire.getTime())) throw new Error(`invalid schedule expression (one-shot datetime): ${expr}`);
+    let fired = false;
+    return {
+      type: "once",
+      nextFire: (prev) => {
+        if (fired) return null;
+        if (prev && fire.getTime() <= prev.getTime()) { fired = true; return null; }
+        fired = true;
+        return fire;
+      },
+    };
+  }
+  // cron (5-field) — validate immediately (resolve-time error, not fire-time)
+  try {
+    cronParser.parseExpression(s, { currentDate: new Date() });
+  } catch (e) {
+    throw new Error(`invalid schedule expression (not cron/interval/once): ${expr} — ${(e as Error).message}`);
+  }
+  return {
+    type: "cron",
+    nextFire: (prev) => cronParser.parseExpression(s, { currentDate: prev ?? new Date() }).next(),
+  };
+}

package/src/scheduling/pid-lock.ts

@@ -0,0 +1,43 @@
+// src/scheduling/pid-lock.ts
+// SPEC-5a §9 — PID lock so only one pi session fires schedules (Q5=A).
+// A stale PID (dead process) is reclaimed.
+import { existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // signal 0 = existence check
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export class PidLock {
+  private lockPath: string | null = null;
+
+  acquire(lockPath: string): boolean {
+    if (existsSync(lockPath)) {
+      const raw = readFileSync(lockPath, "utf8").trim();
+      const ownerPid = Number(raw);
+      if (Number.isFinite(ownerPid) && ownerPid !== process.pid && isPidAlive(ownerPid)) {
+        // a different live process owns it
+        return false;
+      }
+      // stale pid (dead) or already us → reclaim/keep
+    }
+    writeFileSync(lockPath, String(process.pid), "utf8");
+    this.lockPath = lockPath;
+    return true;
+  }
+
+  isOwner(): boolean {
+    return this.lockPath !== null;
+  }
+
+  release(): void {
+    if (this.lockPath && existsSync(this.lockPath)) {
+      try { unlinkSync(this.lockPath); } catch { /* already gone */ }
+    }
+    this.lockPath = null;
+  }
+}

package/src/scheduling/scheduler.ts

@@ -0,0 +1,150 @@
+// src/scheduling/scheduler.ts
+// SPEC-5a §9 — in-process scheduler. Session-scoped (fires only while pi open, no daemon).
+// PID-locked so two open pi sessions on the same project don't double-fire. No catch-up.
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseScheduleExpr, type ScheduleExpression } from "./expressions.ts";
+import { PidLock } from "./pid-lock.ts";
+
+export interface ScheduleSpec {
+  task: string;
+  expression: string;
+  lifecycle?: string; // default "default"
+  auto?: boolean;
+}
+
+export interface Schedule extends ScheduleSpec {
+  id: string;
+  nextFire: Date | null;
+  paused: boolean;
+}
+
+interface StoredSchedule extends ScheduleSpec {
+  id: string;
+  paused: boolean;
+}
+
+export interface SchedulerOpts {
+  storePath: string;
+  lockPath: string;
+  onFire: (spec: ScheduleSpec) => void;
+}
+
+interface Entry { spec: StoredSchedule; expr: ScheduleExpression; timer: NodeJS.Timeout | null }
+
+export class Scheduler {
+  private schedules = new Map<string, Entry>();
+  private pidLock = new PidLock();
+  private running = false;
+
+  constructor(private readonly opts: SchedulerOpts) {
+    this.load();
+  }
+
+  private load(): void {
+    if (!existsSync(this.opts.storePath)) return;
+    try {
+      const arr = JSON.parse(readFileSync(this.opts.storePath, "utf8")) as StoredSchedule[];
+      for (const s of arr) {
+        try {
+          const expr = parseScheduleExpr(s.expression);
+          this.schedules.set(s.id, { spec: s, expr, timer: null });
+        } catch {
+          // skip a schedule whose expression no longer parses
+        }
+      }
+    } catch { /* corrupt store — start empty */ }
+  }
+
+  private persist(): void {
+    mkdirSync(dirname(this.opts.storePath), { recursive: true });
+    const arr = [...this.schedules.values()].map((e) => e.spec);
+    writeFileSync(this.opts.storePath, JSON.stringify(arr, null, 2), "utf8");
+  }
+
+  register(spec: ScheduleSpec): string {
+    const expr = parseScheduleExpr(spec.expression); // throws on invalid → resolve-time error
+    const id = "sch-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    const stored: StoredSchedule = {
+      id,
+      task: spec.task,
+      expression: spec.expression,
+      lifecycle: spec.lifecycle ?? "default",
+      auto: spec.auto ?? true,
+      paused: false,
+    };
+    this.schedules.set(id, { spec: stored, expr, timer: null });
+    this.persist();
+    if (this.running) this.arm(id);
+    return id;
+  }
+
+  list(): Schedule[] {
+    return [...this.schedules.values()].map((e) => ({
+      id: e.spec.id,
+      task: e.spec.task,
+      expression: e.spec.expression,
+      lifecycle: e.spec.lifecycle,
+      auto: e.spec.auto,
+      paused: e.spec.paused,
+      nextFire: e.spec.paused ? null : e.expr.nextFire(new Date()),
+    }));
+  }
+
+  pause(id: string): void {
+    const e = this.schedules.get(id);
+    if (!e) return;
+    e.spec.paused = true;
+    if (e.timer) { clearTimeout(e.timer); e.timer = null; }
+    this.persist();
+  }
+
+  resume(id: string): void {
+    const e = this.schedules.get(id);
+    if (!e) return;
+    e.spec.paused = false;
+    if (this.running) this.arm(id);
+    this.persist();
+  }
+
+  delete(id: string): void {
+    const e = this.schedules.get(id);
+    if (!e) return;
+    if (e.timer) clearTimeout(e.timer);
+    this.schedules.delete(id);
+    this.persist();
+  }
+
+  start(): boolean {
+    if (this.running) return true;
+    // Ensure the lock file's parent dir exists (fresh projects have no `.pi/fleet/` yet;
+    // persist() only runs on register(), so start() must self-sufficient the dir first).
+    mkdirSync(dirname(this.opts.lockPath), { recursive: true });
+    if (!this.pidLock.acquire(this.opts.lockPath)) return false;
+    this.running = true;
+    for (const id of this.schedules.keys()) this.arm(id);
+    return true;
+  }
+
+  stop(): void {
+    if (!this.running) return;
+    for (const e of this.schedules.values()) if (e.timer) { clearTimeout(e.timer); e.timer = null; }
+    this.pidLock.release();
+    this.running = false;
+  }
+
+  private arm(id: string): void {
+    const e = this.schedules.get(id);
+    if (!e || e.spec.paused) return;
+    const now = new Date();
+    const next = e.expr.nextFire(now);
+    if (!next) { this.delete(id); return; } // one-shot exhausted
+    const delay = Math.max(0, next.getTime() - now.getTime());
+    e.timer = setTimeout(() => {
+      this.opts.onFire(e.spec);
+      const nx = e.expr.nextFire(new Date());
+      if (!nx) { this.delete(id); return; }
+      this.arm(id);
+    }, delay);
+  }
+}

package/src/tools/fleet-results.ts

@@ -0,0 +1,35 @@
+// src/tools/fleet-results.ts
+// SPEC-5a §10/§12.2 — the agent pulls completed bg-run results from the inbox (Q6=C).
+import { Type, type Static } from "typebox";
+import type { ResultsInbox } from "../runtime/results-inbox.ts";
+
+export const fleetResultsParams = Type.Object({
+  runId: Type.Optional(Type.String({ description: "Pull a specific run's result. Omit to pull all ready (undelivered) results." })),
+});
+
+export type FleetResultsInput = Static<typeof fleetResultsParams>;
+
+export interface FleetResultsToolDeps {
+  inbox: ResultsInbox;
+}
+
+export function createFleetResultsTool(deps: FleetResultsToolDeps) {
+  return {
+    name: "fleet_results",
+    label: "Fleet results",
+    description: "Pull completed background fleet-run results from the inbox. With a runId, returns that run's result. Without, returns all ready (undelivered) results. Pulling marks them delivered. The durable record also lives in the lifecycle TODO notes + the /fleet panel.",
+    promptSnippet: "Pull completed background fleet-run results",
+    promptGuidelines: [
+      "Use fleet_results to pull completed background runs when the 'N fleet results ready' hint appears.",
+      "Without a runId, returns all ready results and marks them delivered.",
+    ],
+    parameters: fleetResultsParams,
+    async execute(_toolCallId: string, input: FleetResultsInput) {
+      const results = deps.inbox.pull(input.runId);
+      return {
+        content: [{ type: "text" as const, text: results.length === 0 ? "no results ready" : results.map((r) => `${r.runId}: ${r.status} — ${r.summary}`).join("\n") }],
+        details: { results },
+      };
+    },
+  };
+}

package/src/tools/subagent.ts

@@ -9,6 +9,9 @@ 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";
+import type { AsyncRunnerDeps } from "../runtime/async-runner.ts";
+import { runBackground } from "../runtime/async-runner.ts";
+import type { Scheduler } from "../scheduling/scheduler.ts";
 
 export const subagentParams = Type.Object({
   agent: Type.String({ description: "Agent name from the registry (builtin, project, or global)." }),
@@ -18,6 +21,8 @@ export const subagentParams = Type.Object({
   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." })),
+  background: Type.Optional(Type.Boolean({ description: "Fire without awaiting. The run goes to the async/bg pool on an isolated git worktree; this returns { runId, status: 'background' } immediately. Foreground (default) awaits the result." })),
+  schedule: Type.Optional(Type.String({ description: 'Schedule the run instead of firing now: a cron string ("0 9 * * 1-5"), an interval ("30m"/"2h"), or a one-shot ISO datetime ("2026-07-25T14:00"). Returns { scheduleId, nextFire }. Session-scoped (fires only while pi is open); no catch-up.' })),
 });
 
 export type SubagentInput = Static<typeof subagentParams>;
@@ -34,6 +39,12 @@ export interface SubagentToolDeps {
   lifecycleRegistry: Map<string, LifecycleDef>;
   lifecycleRuns: Map<string, import("../lifecycle/lifecycle-types.ts").LifecycleRunRecord>;
   lifecycleDeps: Omit<LifecycleRunDeps, "spawn">;
+  /** SPEC-5a: async/bg runtime deps. Present when the extension wires the operational runtime. */
+  asyncRunner?: AsyncRunnerDeps;
+  /** SPEC-5a: scheduler. Present when the extension wires scheduling. */
+  scheduler?: Scheduler;
+  /** SPEC-5a: live bg run status rows for the /fleet panel. Optional. */
+  bgRuns?: import("../panel/bg-runs-store.ts").BgRunsStore;
 }
 
 /** Build the pi.registerTool definition. Thin wrapper over spawnSubagent. */
@@ -50,6 +61,21 @@ export function createSubagentTool(deps: SubagentToolDeps) {
     ],
     parameters: subagentParams,
     async execute(_toolCallId: string, params: SubagentInput, signal: AbortSignal, _onUpdate: unknown, ctx: any) {
+      // 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." }] };
+      }
+      if (params.schedule) {
+        if (!deps.scheduler) return { isError: true, content: [{ type: "text" as const, text: "scheduling not configured (scheduler missing)" }] };
+        const id = deps.scheduler.register({ task: params.task, expression: params.schedule, lifecycle: params.lifecycle ?? "default", auto: params.auto ?? true });
+        const entry = deps.scheduler.list().find((s) => s.id === id);
+        return { content: [{ type: "text" as const, text: `scheduled: ${id} · next fire: ${entry?.nextFire?.toISOString() ?? "(paused)"}` }], details: { scheduleId: id, nextFire: entry?.nextFire ?? null } };
+      }
+      if (params.background) {
+        if (!deps.asyncRunner) return { isError: true, content: [{ type: "text" as const, text: "background runs not configured (asyncRunner missing)" }] };
+        const handle = runBackground(params.task, { deps: deps.asyncRunner, lifecycle: params.lifecycle ?? "default", mode: "auto" });
+        return { content: [{ type: "text" as const, text: `background run: ${handle.runId}` }], details: handle };
+      }
       if (params.lifecycle) {
         const { runLifecycle } = await import("../lifecycle/run-lifecycle.ts");
         const lifecycleFullDeps: LifecycleRunDeps = {

package/src/vendor/cron-parser/NOTICE.md

@@ -0,0 +1,23 @@
+# cron-parser (vendored)
+
+- **Origin:** https://github.com/harrisi/cron-parser
+- **npm:** `cron-parser`
+- **Version:** 1.1.1 (latest 1.x — dependency-free; later versions pull in `luxon`)
+- **License:** MIT (see upstream LICENSE)
+- **Vendored on:** 2026-07-24
+- **Vendored surface:** `lib/` (4 files: `parser.js`, `expression.js`, `date.js`, `number.js` — CommonJS, all-relative `require()`s, zero runtime deps) + `package.json` (`{"type":"commonjs"}`) scoping the dir as CJS so Node's loader treats the `.js` files as CommonJS despite the package root's `"type": "module"`.
+- **Frozen:** do NOT edit files under `lib/`. To upgrade, replace `lib/` + update this NOTICE (version + date). Note: v2+ adds `luxon` as a runtime dep — vendoring those would require also vendoring luxon; v1.1.1 is intentionally dep-free. The `package.json` scope file is NOT part of the upstream lib — it's our CJS-in-ESM interop shim; keep it across upgrades.
+
+## Why vendored (per SPEC-5a §9, Q9=A)
+cron expression parsing is commodity plumbing (DST, month-length, DOW/DOM OR-semantics, Feb 29).
+We freeze a battle-tested MIT copy rather than reinvent it. The worktree lifecycle, by contrast,
+is greenfield (thin git shell-outs) — see `src/worktree/`.
+
+## API used (v1.1.1)
+```js
+const cp = require("./lib/parser.js");
+const expr = cp.parseExpression("0 9 * * 1-5", { currentDate: new Date() });
+const nextDate = expr.next();  // CronDate (extends Date) — a real Date instance
+```
+Note: v1.1.1 has no `tz` option — it uses the process local timezone, which is the right default
+for a dev tool ("9am" means 9am the user's time).