@getpipher/armory-fleet 0.3.0 → 0.5.0

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,147 @@
+// 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;
+    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/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/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

@@ -7,6 +7,11 @@ import type { SingleSlotLock } from "../engine/concurrency-lock.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";
+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)." }),
@@ -14,6 +19,10 @@ 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." })),
+  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>;
@@ -26,6 +35,16 @@ export interface SubagentToolDeps {
   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">;
+  /** 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. */
@@ -42,6 +61,45 @@ 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 = {
+          ...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,

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)
+- **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.
+
+## 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).

package/src/vendor/cron-parser/lib/date.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Date class extension methods
+ */
+var extensions = {
+  addYear: function addYear() {
+    this.setFullYear(this.getFullYear() + 1);
+  },
+
+  addMonth: function addMonth() {
+    this.setDate(1);
+    this.setHours(0);
+    this.setMinutes(0);
+    this.setSeconds(0);
+    this.setMonth(this.getMonth() + 1);
+  },
+
+  addDay: function addDay() {
+    var day = this.getDate();
+    this.setDate(day + 1);
+
+    this.setHours(0);
+    this.setMinutes(0);
+    this.setSeconds(0);
+
+    if (this.getDate() === day) {
+      this.setDate(day + 2);
+    }
+  },
+
+  addHour: function addHour() {
+    var hours = this.getHours();
+    this.setHours(hours + 1);
+
+    if (this.getHours() === hours) {
+      this.setHours(hours + 2);
+    }
+
+    this.setMinutes(0);
+    this.setSeconds(0);
+  },
+
+  addMinute: function addMinute() {
+    this.setMinutes(this.getMinutes() + 1);
+    this.setSeconds(0);
+  },
+
+  addSecond: function addSecond() {
+    this.setSeconds(this.getSeconds() + 1);
+  },
+
+  toUTC: function toUTC() {
+    var to = new CronDate(this);
+    var ms = to.getTime() + (to.getTimezoneOffset() * 60000);
+    to.setTime(ms);
+    return to;
+  }
+};
+
+/**
+ * Extends Javascript Date class by adding
+ * utility methods for basic date incrementation
+ */
+
+function CronDate (timestamp) {
+  var date = timestamp ? new Date(timestamp) : new Date();
+
+  // Attach extensions
+  var methods = Object.keys(extensions);
+  for (var i = 0, c = methods.length; i < c; i++) {
+    var method = methods[i];
+    date[method] = extensions[method].bind(date);
+  }
+
+  return date;
+}
+
+module.exports = CronDate;