@cruxy/cli 0.23.0 → 0.25.0

package/dist/agent/loop.d.ts

@@ -5,11 +5,19 @@ import type { StreamRenderer } from "../render/index.js";
 import { type Router, type TaskClass } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
+/** Optional per-fire context (C.26 step 5). For tool-scoped events the loop
+ * passes the raw tool-call `input` so a multi-root {@link HookRouter} can resolve
+ * the ONE acting root and fire only that root's hooks. Session lifecycle events
+ * (`before-run`/`after-run`) carry no hint — they have no acting root and fan
+ * every trusted root. Ignored by the single-root runner. */
+export interface HookFireHint {
+    input?: unknown;
+}
 /** The lifecycle-hook firing seam (C.19). Structural so the loop stays
  * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
  * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
 export interface LifecycleHookRunner {
-    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+    fire(event: HookEvent, ctx: ToolContext, hint?: HookFireHint): Promise<void>;
 }
 export interface RunAgentArgs {
     /**
@@ -84,6 +92,17 @@ export interface RunAgentArgs {
         tier?: string;
         usage?: Usage;
     }) => void;
+    /**
+     * Cooperative cancellation (C.33). When the signal aborts, the loop stops at
+     * the NEXT turn boundary and returns `stop: "aborted"` with the coherent
+     * partial history — the in-flight turn (model call + its tool executions)
+     * always completes first, exactly like a tripped {@link budget}, so overshoot
+     * is bounded by one turn. Used by the parallel orchestrator to cancel sibling
+     * subagents on a fatal failure or Ctrl-C; omitted → no cancellation (unchanged).
+     * The same signal reaches tools via `ctx.signal`, so an in-flight shell child
+     * is kill-tree'd rather than orphaned.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps
@@ -107,7 +126,7 @@ export interface AgentResult {
     /** Number of model turns consumed. */
     iterations: number;
     /** Why the loop ended. */
-    stop: "completed" | "max_iterations" | "budget";
+    stop: "completed" | "max_iterations" | "budget" | "aborted";
     /** Which cap tripped, when `stop === "budget"` (from {@link LoopBudget}). */
     stopReason?: string;
     /** Accumulated token usage (stashed for cost tracking in C.22). */

package/dist/agent/loop.js

@@ -62,6 +62,19 @@ async function driveLoop(args, renderer, routed) {
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {
+        // Cancellation check (C.33), before committing to another model turn: a
+        // signalled abort returns the history as it stands, at a clean turn boundary
+        // (the prior iteration fully resolved its tool calls). Checked ahead of the
+        // budget so a cancelled fan-out never spends one more turn's tokens.
+        if (args.signal?.aborted) {
+            return {
+                messages,
+                iterations,
+                stop: "aborted",
+                stopReason: "cancelled",
+                usage,
+            };
+        }
         // Budget check before committing to another model turn (C.14): a tripped
         // cap returns the history as it stands — always at a clean turn boundary,
         // because the previous iteration fully resolved its tool calls.
@@ -184,7 +197,10 @@ async function driveLoop(args, renderer, routed) {
             // fail-closed — the tool never runs; the model is told via an error
             // result. The hook command itself went through the U.3 gate + C.16 sandbox
             // (same path as run_command), so a hook is never an approval bypass.
-            const blocked = await fireBeforeTool(args.hooks, ctx, call.id);
+            // The raw input lets a multi-root HookRouter resolve the ONE acting root
+            // (same precedence the tool uses) and fire only that root's hooks.
+            const hint = { input: call.input };
+            const blocked = await fireBeforeTool(args.hooks, ctx, call.id, hint);
             if (blocked) {
                 renderer?.toolLifecycle({ event: "end", label, ok: false });
                 toolResults.push(blocked);
@@ -196,9 +212,9 @@ async function driveLoop(args, renderer, routed) {
             // after-tool + on-file-change (C.19): fire once the action is done.
             // Advisory by default (report, don't rewrite history); a hook explicitly
             // marked blocking here throws and aborts the run.
-            await args.hooks?.fire("after-tool", ctx);
+            await args.hooks?.fire("after-tool", ctx, hint);
             if (!result.is_error && FILE_MUTATING_TOOLS.has(call.name)) {
-                await args.hooks?.fire("on-file-change", ctx);
+                await args.hooks?.fire("on-file-change", ctx, hint);
             }
         }
         messages.push({ role: "user", content: toolResults });
@@ -250,11 +266,11 @@ function describeToolCall(call) {
  * the failure is greppable. A non-blocking (advisory) hook failure never reaches
  * here — the runner reports it and resolves normally.
  */
-async function fireBeforeTool(hooks, ctx, toolUseId) {
+async function fireBeforeTool(hooks, ctx, toolUseId, hint) {
     if (!hooks)
         return null;
     try {
-        await hooks.fire("before-tool", ctx);
+        await hooks.fire("before-tool", ctx, hint);
         return null;
     }
     catch (err) {

package/dist/agent/session.d.ts

@@ -4,6 +4,7 @@ import type { StreamRenderer } from "../render/index.js";
 import { type Router } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
+import type { JobManager } from "../jobs/index.js";
 import { type RequestUsage, type UsageRecord } from "../usage/index.js";
 import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 /**
@@ -67,6 +68,14 @@ export interface SessionArgs {
      * persists it locally — it never transmits. Omitted → no persistence.
      */
     onRunUsage?: (record: UsageRecord) => void;
+    /**
+     * Session-scoped background jobs (C.28): the manager the `run_in_background`
+     * tool dispatches onto. Exposed on the session so the REPL can service pending
+     * job approvals between turns and drive `/jobs`/`/logs`/`/cancel`, and so
+     * `cruxy run` can cancel every live job on session exit. Present only when
+     * `jobs.enabled`; omitted → no background jobs (unchanged behaviour).
+     */
+    jobs?: JobManager;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -106,6 +115,10 @@ export declare class Session {
     /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
      * shell-bound custom slash command (C.19) runs through the SAME gated path. */
     get toolContext(): ToolContext;
+    /** The background-job manager (C.28), or undefined when jobs are disabled.
+     * The REPL uses it to service paused-job approvals and drive `/jobs`; `cruxy
+     * run` uses it to cancel every live job on exit. */
+    get jobs(): JobManager | undefined;
     /** Whether plan mode is currently on. */
     getPlanMode(): boolean;
     /**

package/dist/agent/session.js

@@ -72,6 +72,12 @@ export class Session {
     get toolContext() {
         return this.args.ctx;
     }
+    /** The background-job manager (C.28), or undefined when jobs are disabled.
+     * The REPL uses it to service paused-job approvals and drive `/jobs`; `cruxy
+     * run` uses it to cancel every live job on exit. */
+    get jobs() {
+        return this.args.jobs;
+    }
     /** Whether plan mode is currently on. */
     getPlanMode() {
         return this.planMode;

package/dist/approval/index.d.ts

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/index.js

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/mutex.d.ts

@@ -0,0 +1,45 @@
+import type { ApprovalDecision } from "./types.js";
+import type { ApproveAction } from "../tools/types.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export declare class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    private tail;
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export declare function serializeGate(gate: (action: ApproveAction) => Promise<ApprovalDecision>, mutex: ApprovalMutex, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;

package/dist/approval/mutex.js

@@ -0,0 +1,57 @@
+import { classify } from "./classify.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    tail = Promise.resolve();
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive(fn) {
+        const result = this.tail.then(fn);
+        // Advance the chain on a branch that swallows the outcome, so the caller
+        // still observes `fn`'s rejection while the next waiter is not poisoned.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export function serializeGate(gate, mutex, cwd) {
+    return (action) => {
+        // Same classifier the gate uses; read tier contends for nothing → no lock.
+        if (classify(action, cwd).tier === "read")
+            return gate(action);
+        return mutex.runExclusive(() => gate(action));
+    };
+}

package/dist/checkpoint/gate-hook.d.ts

@@ -0,0 +1,28 @@
+import type { ApprovalDecision } from "../approval/types.js";
+import type { ApproveAction } from "../tools/types.js";
+import type { Workspace } from "../workspace/index.js";
+import type { CheckpointGate } from "./gate.js";
+/**
+ * Wrap an approval gate with the C.32 auto-checkpoint hook. Ordering is the whole
+ * point: a tool mutates only *after* `requestApproval` resolves, so snapshotting
+ * after an `allow` decision but before returning it means the checkpoint always
+ * lands before the run's first mutation — and a denied action never creates one.
+ * The same seam records which paths the run touched (file actions) or that
+ * attribution is lost (shell), for rollback's external-change detection.
+ *
+ * Lives in the checkpoint package (not the CLI wiring) so the SAME hook can be
+ * composed by the session factory, the subagent orchestrator, AND the C.28 job
+ * approval path without any of them importing the others.
+ */
+export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
+/**
+ * Group a file action's resolved absolute targets by the root that contains each
+ * (JC-G). write/edit carry an already-absolute `path`; patch preview paths are
+ * relative to the PRIMARY cwd (`path.relative(ctx.cwd, abs)` in apply_patch), so
+ * we reconstruct the absolute path from the primary root rather than trusting
+ * classify's `targets` — which also correctly handles a patch spanning roots.
+ */
+export declare function attributeFileTargets(action: ApproveAction, ws: Workspace): Map<string, {
+    rootAbsPath: string;
+    paths: string[];
+}>;

package/dist/checkpoint/gate-hook.js

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { classify } from "../approval/classify.js";
+/**
+ * Wrap an approval gate with the C.32 auto-checkpoint hook. Ordering is the whole
+ * point: a tool mutates only *after* `requestApproval` resolves, so snapshotting
+ * after an `allow` decision but before returning it means the checkpoint always
+ * lands before the run's first mutation — and a denied action never creates one.
+ * The same seam records which paths the run touched (file actions) or that
+ * attribution is lost (shell), for rollback's external-change detection.
+ *
+ * Lives in the checkpoint package (not the CLI wiring) so the SAME hook can be
+ * composed by the session factory, the subagent orchestrator, AND the C.28 job
+ * approval path without any of them importing the others.
+ */
+export function withCheckpointGate(requestApproval, gate, ws) {
+    if (!gate)
+        return requestApproval;
+    return async (action) => {
+        const decision = await requestApproval(action);
+        if (!decision.allow)
+            return decision;
+        const request = classify(action, ws.primary().absPath);
+        if (request.tier === "read")
+            return decision;
+        if (action.kind === "shell" || action.kind === "test") {
+            // JC-β residual: non-primary shell/test are Step 5, so they are still
+            // hard-attributed to the primary root regardless of `action.root` (which
+            // those tools populate as the seam). They can mutate files we cannot
+            // attribute (scripts, snapshot writers) — record the lost attribution.
+            const root = ws.primary();
+            const svc = gate.serviceFor(root.name, root.absPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordShellMutation();
+            if (checkpoint) {
+                await gate.recordMember(root.name, root.absPath, checkpoint.id);
+            }
+            return decision;
+        }
+        if (action.kind === "vcs") {
+            // C.26 Step 4: a PR now names its root (⚖︎#11), so the checkpoint is
+            // attributed to THAT selected root — its git commit stages/lands in that
+            // root's working tree, never the primary's. `recordShellMutation` because a
+            // `git add -A` + commit mutates the tree opaquely (no per-file attribution).
+            // Fall back to the primary only if a root name is somehow absent (defensive).
+            const root = (action.root ? ws.tryRootByName(action.root) : undefined) ??
+                ws.primary();
+            const svc = gate.serviceFor(root.name, root.absPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordShellMutation();
+            if (checkpoint) {
+                await gate.recordMember(root.name, root.absPath, checkpoint.id);
+            }
+            return decision;
+        }
+        // File actions (write/edit/patch): attribute each RESOLVED target to its root
+        // (JC-G — post-confinement truth) and checkpoint every touched root. A patch
+        // may span roots; each root gets its own checkpoint + set member.
+        for (const [rootName, group] of attributeFileTargets(action, ws)) {
+            const svc = gate.serviceFor(rootName, group.rootAbsPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordTouched(group.paths);
+            if (checkpoint) {
+                await gate.recordMember(rootName, group.rootAbsPath, checkpoint.id);
+            }
+        }
+        return decision;
+    };
+}
+/**
+ * Group a file action's resolved absolute targets by the root that contains each
+ * (JC-G). write/edit carry an already-absolute `path`; patch preview paths are
+ * relative to the PRIMARY cwd (`path.relative(ctx.cwd, abs)` in apply_patch), so
+ * we reconstruct the absolute path from the primary root rather than trusting
+ * classify's `targets` — which also correctly handles a patch spanning roots.
+ */
+export function attributeFileTargets(action, ws) {
+    const abs = [];
+    if (action.kind === "write" || action.kind === "edit") {
+        if (action.path)
+            abs.push(action.path);
+    }
+    else if (action.kind === "patch" && action.preview?.type === "patch") {
+        for (const file of action.preview.files) {
+            abs.push(path.resolve(ws.primary().absPath, file.path));
+        }
+    }
+    const byRoot = new Map();
+    for (const target of abs) {
+        const root = ws.rootContaining(target);
+        const group = byRoot.get(root.name) ?? {
+            rootAbsPath: root.absPath,
+            paths: [],
+        };
+        group.paths.push(target);
+        byRoot.set(root.name, group);
+    }
+    return byRoot;
+}

package/dist/checkpoint/gate.d.ts

@@ -44,8 +44,14 @@ export declare class CheckpointGate {
      * mutation begins a fresh run. The set is materialized lazily on the first member
      * (so its `createdAt` marks the run's first mutation, and a no-mutation run
      * writes no manifest).
+     *
+     * `runId` may be supplied to key the set manifest by a caller-chosen id (C.28: a
+     * background job passes its OWN id, so `cruxy rollback <jobId>` maps straight to
+     * that job's set and reverts exactly the job — pre- AND post-pause mutations,
+     * because a job calls this ONCE at start and never again on resume). Omitted → a
+     * fresh generated `run-…` id, unchanged from C.26.
      */
-    beginRun(summary: string): void;
+    beginRun(summary: string, runId?: string): void;
     /**
      * Get-or-create the per-root service. The first time a root is touched this
      * process, its service is constructed and joined to the current run; an untouched

package/dist/checkpoint/gate.js

@@ -28,10 +28,16 @@ export class CheckpointGate {
      * mutation begins a fresh run. The set is materialized lazily on the first member
      * (so its `createdAt` marks the run's first mutation, and a no-mutation run
      * writes no manifest).
+     *
+     * `runId` may be supplied to key the set manifest by a caller-chosen id (C.28: a
+     * background job passes its OWN id, so `cruxy rollback <jobId>` maps straight to
+     * that job's set and reverts exactly the job — pre- AND post-pause mutations,
+     * because a job calls this ONCE at start and never again on resume). Omitted → a
+     * fresh generated `run-…` id, unchanged from C.26.
      */
-    beginRun(summary) {
+    beginRun(summary, runId) {
         this.summary = summary;
-        this.runId = newRunId();
+        this.runId = runId ?? newRunId();
         this.set = null;
         for (const svc of this.services.values())
             svc.beginRun(summary);

package/dist/checkpoint/index.d.ts

@@ -7,3 +7,4 @@ export * from "./service.js";
 export * from "./set.js";
 export * from "./set-rollback.js";
 export * from "./gate.js";
+export * from "./gate-hook.js";

package/dist/checkpoint/index.js

@@ -7,3 +7,4 @@ export * from "./service.js";
 export * from "./set.js";
 export * from "./set-rollback.js";
 export * from "./gate.js";
+export * from "./gate-hook.js";

package/dist/checkpoint/service.d.ts

@@ -48,6 +48,14 @@ export declare class CheckpointService {
     private readonly pinnedStore?;
     private runSummary;
     private active;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    private pending;
     constructor(opts: CheckpointServiceOptions);
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary: string): void;
@@ -59,6 +67,7 @@ export declare class CheckpointService {
      * either substrate, the run must not mutate without its undo protection.
      */
     ensureCheckpoint(): Promise<Checkpoint | null>;
+    private buildCheckpoint;
     /** Attribute mutated paths to the current run (persisted for later rollback). */
     recordTouched(absPaths: string[]): Promise<void>;
     /** The run ran a shell command: per-path attribution is no longer possible. */

package/dist/checkpoint/service.js

@@ -36,6 +36,14 @@ export class CheckpointService {
     pinnedStore;
     runSummary = "agent run";
     active = null;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    pending = null;
     constructor(opts) {
         this.root = path.resolve(opts.root);
         this.config = opts.config;
@@ -44,6 +52,7 @@ export class CheckpointService {
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary) {
         this.active = null;
+        this.pending = null;
         const firstLine = summary.split("\n", 1)[0].trim();
         this.runSummary =
             firstLine.length > 80
@@ -62,6 +71,17 @@ export class CheckpointService {
             return null;
         if (this.active)
             return this.active;
+        // Coalesce concurrent first-use: a second caller awaits the first's snapshot
+        // rather than starting a second one. Cleared on settle so a FAILED attempt
+        // (which leaves `this.active` null) lets the next call retry.
+        if (this.pending)
+            return this.pending;
+        this.pending = this.buildCheckpoint().finally(() => {
+            this.pending = null;
+        });
+        return this.pending;
+    }
+    async buildCheckpoint() {
         const gitWorkTree = this.pinnedStore
             ? this.pinnedStore.kind === "git"
             : isGitWorkTree(this.root);

package/dist/cli/commands/rollback.d.ts

@@ -8,7 +8,10 @@ import { Command } from "commander";
  * PRs made during the run are not undone.
  *
  * Routing:
- *   • an explicit `<id>` → single-root rollback of that checkpoint (escape hatch);
+ *   • an explicit `<id>` that names a run/JOB set (C.28: a background job's id) →
+ *     set-based rollback of exactly that run, restoring every root it touched;
+ *   • an explicit `<id>` that is a checkpoint id → single-root rollback (escape
+ *     hatch; also the recovery route if the primary root's set index was removed);
  *   • no id, a set manifest exists → set-based rollback of the latest run;
  *   • no id, no set manifest → JC-F fallback to legacy single-root, logged.
  */

package/dist/cli/commands/rollback.js

@@ -81,9 +81,7 @@ async function legacyRollback(root, config, approval, interactive, id, t) {
  * one U.3 approval, then a sequential apply that stops on first failure
  * (`CHECKPOINT_SET_PARTIAL`, R3). Both coded errors propagate to the boundary.
  */
-async function setRollback(primaryRoot, config, approval, t) {
-    const sets = await listSets(primaryRoot); // newest first
-    const set = sets[0];
+async function setRollback(config, approval, t, set) {
     // Validate-all BEFORE any apply — a missing/corrupt member throws here.
     const members = await validateSet(set, config);
     if (setIsNoop(members)) {
@@ -116,14 +114,17 @@ async function setRollback(primaryRoot, config, approval, t) {
  * PRs made during the run are not undone.
  *
  * Routing:
- *   • an explicit `<id>` → single-root rollback of that checkpoint (escape hatch);
+ *   • an explicit `<id>` that names a run/JOB set (C.28: a background job's id) →
+ *     set-based rollback of exactly that run, restoring every root it touched;
+ *   • an explicit `<id>` that is a checkpoint id → single-root rollback (escape
+ *     hatch; also the recovery route if the primary root's set index was removed);
  *   • no id, a set manifest exists → set-based rollback of the latest run;
  *   • no id, no set manifest → JC-F fallback to legacy single-root, logged.
  */
 export function rollbackCommand() {
     return new Command("rollback")
         .description("restore the working tree to a checkpoint, undoing a run's file changes")
-        .argument("[id]", "checkpoint id (defaults to the most recent run)")
+        .argument("[id]", "run/job id or checkpoint id (defaults to the most recent run)")
         .action(async (id) => {
         const interactive = Boolean(process.stdin.isTTY);
         // Refuse before touching anything: rollback is a deliberate, interactive
@@ -138,20 +139,26 @@ export function rollbackCommand() {
             interactive,
             io: defaultPromptIO(shouldUseColor()),
         });
-        // Explicit id → single-root path (the per-member escape hatch; also the
-        // recovery route if the primary root — and its set index — was removed).
+        const sets = await listSets(primaryRoot); // newest first
         if (id !== undefined) {
+            // A job/run id first: if `<id>` names a set manifest (a background job's
+            // id IS its set's runId, C.28), roll back that whole run. Otherwise treat
+            // it as a single checkpoint id (the per-member escape hatch).
+            const jobSet = sets.find((s) => s.runId === id);
+            if (jobSet) {
+                await setRollback(config, approval, t, jobSet);
+                return;
+            }
             await legacyRollback(primaryRoot, config, approval, interactive, id, t);
             return;
         }
         // No set manifest → JC-F: fall back to legacy single-root, logged (never
         // silent). The primary root name matches single-root workspace naming.
-        const sets = await listSets(primaryRoot);
         if (sets.length === 0) {
             logger.info(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`);
             await legacyRollback(primaryRoot, config, approval, interactive, undefined, t);
             return;
         }
-        await setRollback(primaryRoot, config, approval, t);
+        await setRollback(config, approval, t, sets[0]);
     });
 }