@getpipher/armory-fleet 0.11.0 → 0.12.0

package/src/runtime/async-runner.ts

@@ -23,8 +23,8 @@ export interface FakeLifecycleResult {
 
 export interface RunLifecycleOpts {
   runId: string;
-  worktreePath: string;
-  branch: string;
+  worktreePath?: string;
+  branch?: string;
   mode: "auto" | "checkpointed";
 }
 
@@ -49,12 +49,22 @@ export interface RunBackgroundOpts {
   deps: AsyncRunnerDeps;
   lifecycle: string;
   mode: "auto" | "checkpointed";
+  /** v0.11.1: edit isolation for background runs. Default "auto" (worktree when cwd is a git repo, in-place otherwise). */
+  isolation?: Isolation;
 }
 
-export interface RunBackgroundHandle {
-  runId: string;
-  status: "background";
-}
+/** The success shape (back-compat: existing external refs to RunBackgroundHandle still typecheck). */
+export interface RunBackgroundHandle { runId: string; status: "background"; }
+
+/** v0.11.1: a background dispatch either starts (runId + background) or fails synchronously (error, no runId). */
+export type RunBackgroundResult =
+  | { runId: string; status: "background" }
+  | { status: "failed"; error: string };
+
+export type Isolation = "worktree" | "none" | "auto";
+
+/** Per-session dedup flag for the auto-fallback in-place notify (resets on process restart = new session). */
+let inPlaceFallbackWarned = false;
 
 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;
@@ -72,54 +82,98 @@ function sh(cmd: string, cwd: string): void {
   execSync(cmd, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
 }
 
-export function runBackground(task: string, opts: RunBackgroundOpts): RunBackgroundHandle {
+/** The git-agnostic core: pool slot → journal → runLifecycle in ctx.cwd (or a worktree, when `isolated` is set) → inbox + notify.
+ *  Fire-and-forget. When `isolated` is present, journals the worktree field, commits on completion, and removes the worktree. */
+function runBackgroundInPlace(runId: string, task: string, opts: RunBackgroundOpts, isolated?: { worktreePath: string; branch: string }): void {
   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() };
+      const ev0: JournalEvent = isolated
+        ? { type: "run:started", runId, task, lifecycle: opts.lifecycle, worktree: { path: isolated.worktreePath, branch: isolated.branch }, mode: opts.mode, ts: Date.now() }
+        : { type: "run:started", runId, task, lifecycle: opts.lifecycle, 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 });
+      const res = await deps.runLifecycle(task, opts.lifecycle, { runId, worktreePath: isolated?.worktreePath, branch: isolated?.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() });
+        if (isolated) {
+          try { sh("git add -A && git commit -m 'fleet run complete'", isolated.worktreePath); } catch { /* nothing to commit */ }
+        }
+        deps.journal.append(runId, isolated
+          ? { type: "run:completed", runId, branch: isolated.branch, ts: Date.now() }
+          : { type: "run:completed", runId, 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 lastIdx = total;
+        emitProgress(deps, runId, { status: "completed", phase: res.phases[total - 1]?.name ?? "finish", phaseIndex: lastIdx, phaseTotal: total, lifecycle: opts.lifecycle, mode: opts.mode, task, ...(isolated ? { branch: isolated.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(),
+          completedAt: Date.now(),
+          ...(isolated ? { branch: isolated.branch } : {}),
         };
         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);
+        if (isolated) 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);
+        if (isolated) 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);
+      if (isolated) 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 });
     }
   });
+}
 
+/** The worktree wrapper: SYNCHRONOUS pre-flight + worktree create, then core-with-isolation. */
+function runBackgroundIsolated(task: string, opts: RunBackgroundOpts): RunBackgroundResult {
+  const { deps } = opts;
+  if (!deps.worktree.isGitRepo()) {
+    return { status: "failed", error: "isolation: 'worktree' requires a git repo; cwd is not one — use isolation: 'none' or run in a git repo" };
+  }
+  const runId = deps.genRunId();
+  const baseRef = "HEAD";
+  let wt: { path: string; branch: string };
+  try {
+    wt = deps.worktree.create(runId, baseRef);
+  } catch (e) {
+    return { status: "failed", error: (e as Error).message };
+  }
+  runBackgroundInPlace(runId, task, opts, { worktreePath: wt.path, branch: wt.branch });
   return { runId, status: "background" };
+}
+
+/** The auto router: isolated when cwd is a git repo, in-place + one per-session notify when not. */
+function runBackgroundAuto(task: string, opts: RunBackgroundOpts): RunBackgroundResult {
+  const { deps } = opts;
+  if (deps.worktree.isGitRepo()) {
+    return runBackgroundIsolated(task, opts);
+  }
+  if (!inPlaceFallbackWarned) {
+    inPlaceFallbackWarned = true;
+    deps.notify("background run in-place (no worktree isolation — parallel edits may conflict)", "warning");
+  }
+  const runId = deps.genRunId();
+  runBackgroundInPlace(runId, task, opts);
+  return { runId, status: "background" };
+}
+
+/** Public dispatcher (keeps the `runBackground` name + RunBackgroundHandle success shape for back-compat). */
+export function runBackground(task: string, opts: RunBackgroundOpts): RunBackgroundResult {
+  const isolation = opts.isolation ?? "auto";
+  if (isolation === "worktree") return runBackgroundIsolated(task, opts);
+  if (isolation === "none") {
+    const runId = opts.deps.genRunId();
+    runBackgroundInPlace(runId, task, opts);
+    return { runId, status: "background" };
+  }
+  return runBackgroundAuto(task, opts);
 }

package/src/runtime/reconcile.ts

@@ -1,12 +1,7 @@
 // src/runtime/reconcile.ts
-// SPEC-5b-1 — on pi boot, mark orphan RunLog runs (run:meta with no run:ended whose process
-// is gone) as aborted so the Runs tab doesn't show stale "running" rows across restarts.
-// Foreground orphans; bg/lifecycle orphans are already handled by scanResumeCandidates (SPEC-5a).
-//
-// SPEC-6-2: rewritten to be probe-driven — uses `probeRun` (handle/pid/age-fallback) instead of
-// age+grace alone. This catches orphans whose process died but whose startedAt is within grace
-// (e.g. a crash seconds after start), and avoids aborting runs whose process is alive but old
-// (e.g. a long-running build).
+// SPEC-6-3 — restart-recovery: scan workflow journals for non-terminal runs
+// (interrupted workflows become resume candidates in the Workflows view).
+import { WorkflowJournal } from "../workflows/journal.ts";
 import type { RunLog } from "./run-log.ts";
 import type { RunRegistry, RunRecord } from "../engine/run-registry.ts";
 
@@ -52,4 +47,12 @@ export function reconcileRuns(log: RunLog, opts: ReconcileOpts = {}): string[] {
     aborted.push(meta.runId);
   }
   return aborted;
-}
+}
+
+/** SPEC-6-3 — on pi start, scan .pi/fleet/workflows/ for non-terminal workflow journals.
+ *  Returns runIds whose journal has no wf:completed/wf:aborted event — these are
+ *  interrupted workflows that the Workflows view surfaces as resume candidates. */
+export function scanWorkflowResumeCandidates(workflowsDir: string): string[] {
+  const journal = new WorkflowJournal(workflowsDir);
+  return journal.scanNonTerminal();
+}

package/src/runtime/resume.ts

@@ -8,8 +8,10 @@ export interface ResumeCandidate {
   runId: string;
   task: string;
   lifecycle: string;
-  worktreePath: string;
-  branch: string;
+  /** Present only for isolated (worktree) runs. */
+  worktreePath?: string;
+  /** Present only for isolated (worktree) runs. */
+  branch?: string;
   lastPhase: string | null;
   canResume: boolean;
 }
@@ -26,23 +28,27 @@ export function scanResumeCandidates(_projectDir: string, opts: ScanResumeOpts):
   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;
+      | (JournalEvent & { type: "run:started"; worktree?: { path: string; branch: string } }) | 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() });
+
+    if (started.worktree) {
+      // isolated run: resume iff the worktree still exists
+      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,
+      });
+    } else {
+      // v0.11.1: in-place interrupted run — no worktree to clean; abort (partial edits may remain in cwd).
+      journal.append(runId, { type: "run:aborted", runId, reason: "in-place interrupted (partial edits may remain in cwd)", ts: Date.now() });
+      cands.push({ runId, task: started.task, lifecycle: started.lifecycle, lastPhase, canResume: false });
     }
-    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

@@ -4,12 +4,12 @@
 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 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 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 =

package/src/scheduling/scheduler.ts

@@ -11,6 +11,8 @@ export interface ScheduleSpec {
   expression: string;
   lifecycle?: string; // default "default"
   auto?: boolean;
+  /** v0.11.1: edit isolation for the background run on fire. Default "auto". */
+  isolation?: "worktree" | "none" | "auto";
 }
 
 export interface Schedule extends ScheduleSpec {
@@ -71,6 +73,7 @@ export class Scheduler {
       expression: spec.expression,
       lifecycle: spec.lifecycle ?? "default",
       auto: spec.auto ?? true,
+      isolation: spec.isolation,
       paused: false,
     };
     this.schedules.set(id, { spec: stored, expr, timer: null });
@@ -86,6 +89,7 @@ export class Scheduler {
       expression: e.spec.expression,
       lifecycle: e.spec.lifecycle,
       auto: e.spec.auto,
+      isolation: e.spec.isolation,
       paused: e.spec.paused,
       nextFire: e.spec.paused ? null : e.expr.nextFire(new Date()),
     }));

package/src/tools/fleet.ts

@@ -0,0 +1,179 @@
+// SPEC-6-3 §9 — the model-callable fleet tool surface for workflows.
+// Thin delegation to WorkflowController via a getter (prevents duplicate registration).
+import { Type, type Static } from "typebox"
+
+import type { WorkflowController } from "../workflows/runtime/controller.ts"
+import type { WorkflowStartInput, WorkflowRunState, WorkflowStartReceipt } from "../workflows/runtime/types.ts"
+import type { WorkflowRunResult } from "../workflows/runner.ts"
+
+export interface FleetToolDeps {
+  getController: () => WorkflowController
+}
+
+export const fleetParams = Type.Object({
+  action: Type.Union([Type.Literal("workflow"), Type.Literal("workflow_control")], { description: "The fleet workflow action." }),
+  // workflow action
+  script: Type.Optional(Type.String({ description: "The JS workflow script (for action: 'workflow')." })),
+  name: Type.Optional(Type.String({ description: "Save-as name (for action: 'workflow')." })),
+  workflowName: Type.Optional(Type.String({ description: "Run a saved workflow by name." })),
+  overwrite: Type.Optional(Type.Boolean({ description: "Overwrite an existing saved workflow." })),
+  args: Type.Optional(Type.Unknown({ description: "Args passed to the script as `args`." })),
+  background: Type.Optional(Type.Boolean({ description: "Non-blocking (default true)." })),
+  resumeFromRunId: Type.Optional(Type.String({ description: "Edit-and-resume: replay the unchanged prefix, re-run the edited suffix." })),
+  maxAgents: Type.Optional(Type.Number({ description: "Hard cap on total agent() calls." })),
+  concurrency: Type.Optional(Type.Number({ description: "Parallel agent() concurrency." })),
+  agentRetries: Type.Optional(Type.Number({ description: "Default per-agent retries." })),
+  agentTimeoutMs: Type.Optional(Type.Number({ description: "Default per-agent timeoutMs." })),
+  tokenBudget: Type.Optional(Type.Number({ description: "Run-level token budget." })),
+  // workflow_control action
+  control: Type.Optional(Type.Union([Type.Literal("list"), Type.Literal("status"), Type.Literal("pause"), Type.Literal("resume"), Type.Literal("stop")], { description: "The control operation." })),
+  runId: Type.Optional(Type.String({ description: "The workflow runId (for status/pause/resume/stop)." })),
+})
+
+export type FleetInput = Static<typeof fleetParams>
+
+export function createFleetTool(deps: FleetToolDeps) {
+  return {
+    name: "fleet",
+    label: "Fleet",
+    description: "Run + control armory-fleet workflows (JS orchestration with agent/parallel/pipeline/phase + journaled resume).",
+    promptSnippet: "Run or control a fleet workflow",
+    promptGuidelines: [
+      "Use action 'workflow' to run a JS workflow script or a saved workflow by name.",
+      "Use action 'workflow_control' with control 'list'/'status'/'pause'/'resume'/'stop' to manage a running workflow by runId.",
+      "Pass resumeFromRunId to edit-and-resume: the unchanged agent() prefix replays from cache; edited + new calls re-run.",
+    ],
+    parameters: fleetParams,
+    async execute(_id: string, params: FleetInput, signal: AbortSignal | null, _onUpdate: unknown, _ctx: unknown) {
+      let controller: WorkflowController
+      try {
+        controller = deps.getController()
+      } catch {
+        return { isError: true, content: [{ type: "text" as const, text: "workflow runtime not initialized for this session" }] }
+      }
+
+      try {
+        if (params.action === "workflow") {
+          return await handleWorkflowAction(controller, params, signal)
+        }
+        return await handleControlAction(controller, params)
+      } catch (e) {
+        return { isError: true, content: [{ type: "text" as const, text: (e as Error).message }] }
+      }
+    },
+  }
+}
+
+async function handleWorkflowAction(controller: WorkflowController, params: FleetInput, signal: AbortSignal | null) {
+  const hasScript = params.script !== undefined
+  const hasName = params.workflowName !== undefined
+
+  if (hasScript && hasName) {
+    return { isError: true, content: [{ type: "text" as const, text: "provide exactly one of script or workflowName" }] }
+  }
+  if (!hasScript && !hasName) {
+    return { isError: true, content: [{ type: "text" as const, text: "action 'workflow' requires `script` or `workflowName`" }] }
+  }
+
+  // resumeFromRunId → editAndResume
+  if (params.resumeFromRunId) {
+    const result = await controller.editAndResume(params.resumeFromRunId, params.script ?? "")
+    return serializeRunResult(result)
+  }
+
+  // Build the delegated WorkflowStartInput with conditional spreads (exact deepEqual match).
+  const input: WorkflowStartInput = {
+    mode: "auto",
+    ...(params.script !== undefined ? { script: params.script } : {}),
+    ...(params.workflowName !== undefined ? { workflowName: params.workflowName } : {}),
+    ...(params.name !== undefined ? { name: params.name } : {}),
+    ...(params.overwrite !== undefined ? { overwrite: params.overwrite } : {}),
+    ...(params.args !== undefined ? { args: params.args } : {}),
+    ...(params.background !== undefined ? { background: params.background } : {}),
+    ...(params.concurrency !== undefined ? { concurrency: params.concurrency } : {}),
+    ...(params.agentRetries !== undefined ? { agentRetries: params.agentRetries } : {}),
+    ...(params.agentTimeoutMs !== undefined ? { agentTimeoutMs: params.agentTimeoutMs } : {}),
+    ...(params.tokenBudget !== undefined ? { tokenBudget: params.tokenBudget } : {}),
+    ...(params.maxAgents !== undefined ? { maxAgents: params.maxAgents } : {}),
+  }
+
+  // Foreground: forward the tool signal. Background: detach (no signal).
+  const isForeground = params.background === false
+  const ctx = isForeground && signal ? { signal } : undefined
+
+  const result = await controller.start(input, ctx)
+  return serializeRunResult(result)
+}
+
+async function handleControlAction(controller: WorkflowController, params: FleetInput) {
+  const control = params.control ?? "list"
+
+  if (control === "list") {
+    const runs = controller.runs()
+    return {
+      content: [{ type: "text" as const, text: `workflows: ${runs.length ? runs.map((r) => r.runId).join(", ") : "(none running)"}` }],
+      details: { runs: runs.map(summarizeRun) },
+    }
+  }
+
+  if (!params.runId) {
+    return { isError: true, content: [{ type: "text" as const, text: `control '${control}' requires \`runId\`` }] }
+  }
+
+  if (control === "status") {
+    const run = controller.getRun(params.runId)
+    if (!run) {
+      return { isError: true, content: [{ type: "text" as const, text: `workflow '${params.runId}' not found` }] }
+    }
+    return { content: [{ type: "text" as const, text: `workflow ${run.runId}: ${run.status}` }], details: { run: summarizeRun(run) } }
+  }
+
+  if (control === "pause") {
+    controller.pause(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: paused` }], details: { runId: params.runId, status: "paused" } }
+  }
+
+  if (control === "resume") {
+    const receipt = await controller.resume(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: resumed` }], details: { receipt } }
+  }
+
+  if (control === "stop") {
+    await controller.stop(params.runId)
+    return { content: [{ type: "text" as const, text: `workflow ${params.runId}: stopped` }], details: { runId: params.runId, status: "aborted" } }
+  }
+
+  return { isError: true, content: [{ type: "text" as const, text: `unknown control '${control}'` }] }
+}
+
+function summarizeRun(run: WorkflowRunState): Record<string, unknown> {
+  return {
+    runId: run.runId,
+    name: run.name,
+    status: run.status,
+    startedAt: run.startedAt,
+    ...(run.endedAt !== undefined ? { endedAt: run.endedAt } : {}),
+    currentPhase: run.currentPhase,
+    phases: run.phases,
+    childRunIds: run.childRunIds,
+    tokenTotal: run.tokenTotal,
+    costTotal: run.costTotal,
+    ...(run.error ? { error: run.error } : {}),
+  }
+}
+
+function serializeRunResult(result: WorkflowStartReceipt | WorkflowRunResult) {
+  if ("status" in result && result.status === "background") {
+    return {
+      content: [{ type: "text" as const, text: `workflow ${result.runId}: background` }],
+      details: { runId: result.runId, status: "background" },
+    }
+  }
+  const r = result as WorkflowRunResult
+  const isError = r.status === "aborted" || r.status === "failed"
+  return {
+    content: [{ type: "text" as const, text: isError ? (r.error ?? r.status) : `workflow ${r.runId}: ${r.status}` }],
+    details: { runId: r.runId, status: r.status },
+    isError: isError || undefined,
+  }
+}

package/src/tools/subagent.ts

@@ -22,6 +22,11 @@ export const subagentParams = Type.Object({
   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." })),
+  isolation: Type.Optional(Type.Union([
+    Type.Literal("worktree"),
+    Type.Literal("none"),
+    Type.Literal("auto"),
+  ], { description: "Edit isolation for background runs. 'worktree' = git worktree (requires a git repo; fails sync if not). 'none' = in-place in cwd (no isolation; parallel edits may conflict). 'auto' (default) = worktree when cwd is a git repo, in-place otherwise." })),
   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.' })),
   maxTurns: Type.Optional(Type.Number({ description: 'Per-run turn budget (default 20). Raise for complex multi-step tasks (e.g. 40) so the subagent doesn\'t hit the budget mid-task; lower for trivial lookups.' })),
 });
@@ -80,13 +85,14 @@ export function createSubagentTool(deps: SubagentToolDeps) {
       }
       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 id = deps.scheduler.register({ task: params.task, expression: params.schedule, lifecycle: params.lifecycle ?? "default", auto: params.auto ?? true, isolation: params.isolation });
         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" });
+        const handle = runBackground(params.task, { deps: deps.asyncRunner, lifecycle: params.lifecycle ?? "default", mode: "auto", isolation: params.isolation });
+        if (handle.status === "failed") return { isError: true, content: [{ type: "text" as const, text: handle.error }] };
         return { content: [{ type: "text" as const, text: `background run: ${handle.runId}` }], details: handle };
       }
       if (params.lifecycle) {

package/src/workflows/builtin/adversarial-review.js

@@ -0,0 +1,19 @@
+export const meta = {
+  name: 'adversarial-review',
+  description: 'Red-team + blue-team review with judge panel',
+  phases: [{ title: 'Attack' }, { title: 'Defend' }, { title: 'Judge' }],
+}
+
+phase('Attack')
+const vulns = await parallel([
+  () => agent('Find injection vulnerabilities in this code.', { tier: 'medium' }),
+  () => agent('Find logic errors and race conditions.', { tier: 'medium' }),
+  () => agent('Find authentication bypass vectors.', { tier: 'medium' }),
+])
+
+phase('Defend')
+const defenses = await parallel(vulns.map((v) => () => agent(`Propose a fix for: ${v}`, { tier: 'low' })))
+
+phase('Judge')
+const winner = await judgePanel([...vulns, ...defenses], { judges: 3, rubric: 'severity and fixability' })
+return { vulnerabilities: vulns, defenses, verdict: winner }

package/src/workflows/builtin/code-review.js

@@ -0,0 +1,13 @@
+export const meta = {
+  name: 'code-review',
+  description: '7 parallel review angles plus verification',
+  phases: [{ title: 'Review' }, { title: 'Verify' }],
+}
+
+phase('Review')
+const angles = ['security', 'correctness', 'performance', 'readability', 'edge-cases', 'tests', 'api-design']
+const findings = await parallel(angles.map((angle) => () => agent(`Review this diff for ${angle} issues. Report concrete findings only.`, { tier: 'medium' })))
+
+phase('Verify')
+const verified = await verify(findings.join('\n---\n'), { reviewers: 2, lens: 'false positives' })
+return { findings, verified }

package/src/workflows/builtin/codebase-audit.js

@@ -0,0 +1,16 @@
+export const meta = {
+  name: 'codebase-audit',
+  description: 'File-tree scan with completeness check',
+  phases: [{ title: 'Scan' }, { title: 'Audit' }],
+}
+
+phase('Scan')
+const files = await loopUntilDry({
+  round: (n) => n < 4 ? agent(`List files in dir ${n}. Return a JSON array of file path strings.`, { tier: 'low', schema: { type: 'array' }, retries: 1 }) : [],
+  consecutiveEmpty: 2,
+  maxRounds: 6,
+})
+
+phase('Audit')
+const checked = await verify(`Found ${files.length} files.`, { reviewers: 1, lens: 'missing test coverage' })
+return { files, checked }

package/src/workflows/builtin/deep-research.js

@@ -0,0 +1,12 @@
+export const meta = {
+  name: 'deep-research',
+  description: '3-round discovery loop with de-duplication',
+  phases: [{ title: 'Discover' }, { title: 'Synthesize' }],
+}
+
+phase('Discover')
+const topics = await loopUntilDry({ round: (n) => n < 3 ? agent(`Find unique sources for round ${n}. Return a JSON array of source strings.`, { tier: 'low', schema: { type: 'array' }, retries: 1 }) : [], consecutiveEmpty: 2, maxRounds: 5 })
+
+phase('Synthesize')
+const summary = await agent(`Synthesize these ${topics.length} sources into a coherent report.`, { tier: 'medium' })
+return { sources: topics, summary }

package/src/workflows/builtin/multi-perspective.js

@@ -0,0 +1,17 @@
+export const meta = {
+  name: 'multi-perspective',
+  description: '4 personas review the same artifact',
+  phases: [{ title: 'Review' }, { title: 'Merge' }],
+}
+
+phase('Review')
+const personas = ['product manager', 'security engineer', 'UX designer', 'dev-ops lead']
+const reviews = await parallel(personas.map((p) => () => agent(`Review this artifact as a ${p}. Focus on your domain only.`, { tier: 'medium' })))
+
+phase('Merge')
+const merged = await gate(
+  async (feedback, n) => n === 0 ? agent(`Initial synthesis of ${reviews.length} reviews.`, { tier: 'low' }) : agent(`Revise synthesis: ${feedback}`, { tier: 'low' }),
+  (v) => typeof v === 'string' && v.length > 100 ? { ok: true } : { ok: false, feedback: 'more detail needed' },
+  { attempts: 3 },
+)
+return { reviews, synthesis: merged }

package/src/workflows/helpers/checkpoint.ts

@@ -0,0 +1,15 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — script-level human gate. Standalone (NOT CheckpointFn reuse).
+ *  Interactive: resolves via ctx.onCheckpoint. Headless: returns opts.default (or aborts). */
+export async function checkpoint(
+  prompt: string,
+  opts: { kind?: "confirm" | "input" | "select"; choices?: string[]; default?: unknown; headless?: "default" | "abort"; timeoutMs?: number } = {},
+  ctx: HelperCtx,
+): Promise<unknown> {
+  // Interactive bridge present → use it (the Workflows view resolves the pending checkpoint).
+  if (ctx.onCheckpoint) return ctx.onCheckpoint(prompt, opts as Record<string, unknown>);
+  const headless = opts.headless ?? "default";
+  if (headless === "abort") throw new Error("checkpoint abort: headless mode with no UI");
+  return opts.default ?? true;
+}

package/src/workflows/helpers/completeness-check.ts

@@ -0,0 +1,18 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — judge whether results fully satisfy taskArgs via one agent. Returns null if agent can't judge. */
+export async function completenessCheck(
+  taskArgs: unknown,
+  results: unknown,
+  ctx: HelperCtx,
+  opts: { tier?: string; model?: string; skills?: string[]; backend?: "pi" | "claude"; retries?: number; timeoutMs?: number } = {},
+): Promise<{ complete: boolean; missing?: string[] } | null> {
+  const prompt = `You are a completeness judge. Given the task args and the results, decide if the results fully satisfy the task.\nTask args: ${JSON.stringify(taskArgs)}\nResults: ${JSON.stringify(results)}\nRespond as JSON: {"complete": boolean, "missing": string[]}`;
+  const res = await ctx.spawn(prompt, { agent: "reviewer", ...(opts.tier ? { tier: opts.tier } : {}), ...(opts.model ? { model: opts.model } : {}), ...(opts.skills ? { skills: opts.skills } : {}), ...(opts.backend ? { backend: opts.backend } : {}), ...(opts.retries ? { retries: opts.retries } : {}), ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+  if (!res || res.status !== "completed") return null;
+  try {
+    const parsed = JSON.parse(res.finalText) as { complete?: boolean; missing?: string[] };
+    if (typeof parsed.complete !== "boolean") return null;
+    return { complete: parsed.complete, ...(Array.isArray(parsed.missing) ? { missing: parsed.missing } : {}) };
+  } catch { return null; }
+}

package/src/workflows/helpers/gate.ts

@@ -0,0 +1,22 @@
+import type { HelperCtx } from "./types.ts";
+
+/** SPEC-6-3 §3.3 — run thunk, validate; on fail re-run with feedback up to `attempts`. */
+export async function gate(
+  thunk: (feedback: string | undefined, attempt: number) => unknown | Promise<unknown>,
+  validator: (value: unknown) => { ok: boolean; feedback?: string } | Promise<{ ok: boolean; feedback?: string }>,
+  opts: { attempts?: number } = {},
+  ctx: HelperCtx,
+): Promise<{ ok: boolean; value: unknown; attempts: number }> {
+  const attempts = opts.attempts ?? 3;
+  let feedback: string | undefined;
+  let lastValue: unknown;
+  for (let n = 0; n < attempts; n++) {
+    const value = await thunk(feedback, n);
+    lastValue = value;
+    const verdict = await validator(value);
+    if (verdict.ok) return { ok: true, value, attempts: n + 1 };
+    feedback = verdict.feedback;
+  }
+  // exhausted: return the last value from within the attempts budget (no extra run).
+  return { ok: false, value: lastValue, attempts };
+}

package/src/workflows/helpers/index.ts

@@ -0,0 +1,8 @@
+export type { HelperCtx, HelperSpawnResult } from "./types.ts";
+export { retry } from "./retry.ts";
+export { gate } from "./gate.ts";
+export { completenessCheck } from "./completeness-check.ts";
+export { loopUntilDry } from "./loop-until-dry.ts";
+export { verify } from "./verify.ts";
+export { judgePanel } from "./judge-panel.ts";
+export { checkpoint } from "./checkpoint.ts";