@cruxy/cli 0.24.0 → 0.25.0

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/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/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]);
     });
 }

package/dist/cli/commands/run.js

@@ -193,6 +193,14 @@ export function runCommand() {
                 await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
             }
             finally {
+                // Background jobs (C.28): cancel every live job on session exit —
+                // kill-tree'ing each job's process group (no orphan) and reporting an
+                // honest "N job(s) cancelled". A paused job is cancelled too, but any
+                // checkpoint it took survives for review/rollback.
+                const cancelled = (await session.jobs?.cancelAll("session exit")) ?? 0;
+                if (cancelled > 0) {
+                    logger.print(t.muted(`${cancelled} background job${cancelled === 1 ? "" : "s"} cancelled on exit`));
+                }
                 // LSP (C.12) + MCP (C.27): gracefully shut down any external server
                 // processes spawned during the session (the shared process-exit
                 // kill-tree is the fail-safe for a hard kill).
@@ -216,6 +224,10 @@ export function runCommand() {
         }
         finally {
             renderer.close();
+            // Background jobs (C.28): a one-shot run has no between-turns servicing
+            // loop, so cancel every live job on exit (kill-tree, no orphan) rather
+            // than leave one paused forever. Checkpoints taken survive for rollback.
+            await session.jobs?.cancelAll("session exit");
             // LSP (C.12) + MCP (C.27): gracefully shut down any external server
             // processes spawned during the run (the shared process-exit kill-tree
             // is the fail-safe for a hard kill).

package/dist/cli/repl.d.ts

@@ -7,7 +7,7 @@ import { type StreamRenderer } from "../render/index.js";
  * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
  * sync with the dispatch below and the HELP text.
  */
-export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/exit", "/quit"];
+export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/jobs", "/logs", "/cancel", "/exit", "/quit"];
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;

package/dist/cli/repl.js

@@ -20,6 +20,9 @@ export const REPL_COMMANDS = [
     "/compact",
     "/reload",
     "/plan",
+    "/jobs",
+    "/logs",
+    "/cancel",
     "/exit",
     "/quit",
 ];
@@ -29,6 +32,9 @@ const HELP = `Commands:
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
   /plan          toggle plan mode (propose a plan before executing)
+  /jobs          list background jobs and their status
+  /logs <id>     show a background job's log
+  /cancel <id>   cancel a background job
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -148,6 +154,89 @@ async function handleAddRoot(input, session) {
         printReplError(err);
     }
 }
+/**
+ * Service any background-job approvals that piled up (C.28) — the auto-surface
+ * point. Called when the foreground is idle (between turns), so a paused job's
+ * gated action is decided through the SAME U.3 prompt as a foreground one, one at
+ * a time. No pending → a no-op (nothing printed). The job resumes on approval.
+ */
+async function drainJobApprovals(session) {
+    const jobs = session.jobs;
+    if (!jobs || !jobs.hasPendingApprovals())
+        return;
+    logger.print(theme.muted(`\n${theme.glyph.bullet} a background job needs your approval:`));
+    await jobs.serviceApprovals();
+}
+/** Render the background-job list (`/jobs`). */
+function handleJobsList(session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled — enable with `cruxy config set jobs.enabled true`"));
+        return;
+    }
+    const list = jobs.list();
+    if (list.length === 0) {
+        logger.print(theme.muted("no background jobs this session"));
+        return;
+    }
+    for (const j of list) {
+        const status = j.status === "failed" ? theme.danger(j.status) : theme.accent(j.status);
+        const pending = j.pendingApproval
+            ? theme.muted(` — needs approval: ${j.pendingApproval}`)
+            : "";
+        const err = j.error ? theme.muted(` (${j.error})`) : "";
+        logger.print(`${theme.strong(j.id)}  ${status}  ${j.label}${pending}${err}`);
+    }
+}
+/** Print one job's log (`/logs <id>`). */
+function handleJobLogs(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/logs".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /logs <id>"));
+        return;
+    }
+    try {
+        const log = jobs.logs(id);
+        if (log.dropped > 0) {
+            logger.print(theme.muted(`… ${log.dropped} earlier line(s) rolled off`));
+        }
+        for (const line of log.lines) {
+            const text = line.stream === "err" ? theme.danger(line.text) : line.text;
+            logger.print(text);
+        }
+        logger.print(theme.muted(`(${log.status})`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
+/** Cancel a job (`/cancel <id>`). */
+async function handleJobCancel(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/cancel".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /cancel <id>"));
+        return;
+    }
+    try {
+        const cancelled = jobs.cancel(id);
+        logger.print(theme.muted(cancelled
+            ? `cancelling ${id} (its process tree is killed; any checkpoint survives for rollback)`
+            : `${id} is already finished`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text and tool-call progress stream
@@ -170,6 +259,11 @@ export async function runInteractive(session, io = defaultIO(), renderer = creat
 }
 async function replLoop(session, io, renderer, checkpoints, slashCommands = []) {
     for (;;) {
+        // Auto-surface (C.28): before prompting, service any background-job approvals
+        // that piled up while the last turn ran — one at a time, through the same U.3
+        // prompt. Done here (foreground idle, no readline interface live) so a job's
+        // prompt never contends with the line reader.
+        await drainJobApprovals(session);
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
         if (line === null) {
@@ -217,6 +311,18 @@ async function replLoop(session, io, renderer, checkpoints, slashCommands = [])
             logger.print(HELP);
             continue;
         }
+        if (trimmed === "/jobs") {
+            handleJobsList(session);
+            continue;
+        }
+        if (trimmed === "/logs" || trimmed.startsWith("/logs ")) {
+            handleJobLogs(trimmed, session);
+            continue;
+        }
+        if (trimmed === "/cancel" || trimmed.startsWith("/cancel ")) {
+            await handleJobCancel(trimmed, session);
+            continue;
+        }
         if (trimmed === "/add-root" || trimmed.startsWith("/add-root ")) {
             await handleAddRoot(trimmed, session);
             continue;

package/dist/cli/session-factory.d.ts

@@ -1,21 +1,12 @@
 import type { CruxyConfig } from "../config/index.js";
-import type { ApprovalDecision } from "../approval/index.js";
+import { withCheckpointGate } from "../checkpoint/index.js";
 import type { CheckpointGate } from "../checkpoint/index.js";
+export { withCheckpointGate };
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
-import { ToolRegistry, type ApproveAction, type Tool } from "../tools/index.js";
+import { ToolRegistry, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
 import type { Workspace } from "../workspace/index.js";
-/**
- * Wrap the 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.
- */
-export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
 /**
  * Register every CONDITIONALLY-enabled runtime tool onto `registry`, in the fixed
  * order the model sees them: `remember` (memory), the four LSP tools, the two web
@@ -37,6 +28,7 @@ export declare function registerRuntimeTools(registry: ToolRegistry, config: Cru
     mcpTools?: Tool[];
     spawnTool?: Tool;
     spawnManyTool?: Tool;
+    jobTool?: Tool;
 }): void;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring