@cruxy/cli 0.23.0 → 0.25.0

package/dist/subagent/semaphore.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A counting semaphore (C.33): bounds how many agent runs execute at once.
+ * FIFO — waiters are served in arrival order, so a fan-out's results stay
+ * dispatch-order-fair — and the permit is handed directly from a releaser to
+ * the next waiter, so the live count never transiently exceeds the cap.
+ *
+ * Used as the ONE shared bound on all concurrent execution: parallel subagent
+ * fan-out (C.33) AND background jobs (C.28) draw permits from the SAME instance,
+ * so `subagent.maxConcurrency` caps their COMBINED live count — never one cap
+ * per subsystem. Parallel dispatch happens at depth 0 only (the `spawn_subagents`
+ * tool is never granted to a child), and a permit is held for a child's whole
+ * lifetime — including any *sequential* nested spawn beneath it, which is
+ * deliberately un-permitted. Because no permit holder ever blocks trying to
+ * acquire a second permit, the semaphore cannot be part of a wait cycle: it is
+ * deadlock-free by construction (see the C.33 design doc's deadlock argument).
+ *
+ * C.28 adds a PRIORITY lane to {@link acquire}. A background job that pauses to
+ * await a human approval RELEASES its permit (JC-D: a job blocked on a human is
+ * not using compute, and holding the slot would deadlock the cap if N jobs all
+ * paused). When the human approves, the job re-acquires with `priority: true` so
+ * it jumps ahead of newly-dispatched work — a resumed job never starves behind a
+ * fresh fan-out that filled the queue while it waited. Normal (non-priority)
+ * waiters keep strict FIFO among themselves, so C.33's dispatch-order fairness is
+ * unchanged for everything that does not pause.
+ */
+export interface AcquireOptions {
+    /**
+     * Serve this waiter ahead of all non-priority waiters (still FIFO among
+     * priority waiters). Used by a resumed background job re-acquiring its slot
+     * after an approval, so it is not starved by work dispatched while it paused.
+     */
+    priority?: boolean;
+}
+export declare class Semaphore {
+    private permits;
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    private readonly priority;
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    private readonly normal;
+    constructor(permits: number);
+    /** Run `fn` while holding one permit; the permit is released even if it throws. */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts?: AcquireOptions): Promise<void>;
+    /** Return one permit — handed straight to the next waiter (priority first). */
+    release(): void;
+    /** Permits currently available (inspection/tests). */
+    get available(): number;
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting(): number;
+}

package/dist/subagent/semaphore.js

@@ -0,0 +1,53 @@
+export class Semaphore {
+    permits;
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    priority = [];
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    normal = [];
+    constructor(permits) {
+        // A non-positive cap would wedge every run; clamp to at least 1.
+        this.permits = Math.max(1, Math.floor(permits));
+    }
+    /** Run `fn` while holding one permit; the permit is released even if it throws. */
+    async run(fn) {
+        await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            this.release();
+        }
+    }
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts = {}) {
+        if (this.permits > 0) {
+            this.permits--;
+            return Promise.resolve();
+        }
+        const lane = opts.priority ? this.priority : this.normal;
+        return new Promise((resolve) => lane.push(resolve));
+    }
+    /** Return one permit — handed straight to the next waiter (priority first). */
+    release() {
+        const next = this.priority.shift() ?? this.normal.shift();
+        // Hand the permit straight to the next waiter (never bump the count above
+        // the cap); only when nobody waits does the count grow back.
+        if (next)
+            next();
+        else
+            this.permits++;
+    }
+    /** Permits currently available (inspection/tests). */
+    get available() {
+        return this.permits;
+    }
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting() {
+        return this.priority.length + this.normal.length;
+    }
+}

package/dist/subagent/spawn-tool.d.ts

@@ -26,4 +26,61 @@ declare const parameters: z.ZodObject<{
 }>;
 /** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
 export declare function makeSpawnSubagentTool(orchestrator: SubagentOrchestrator, depth: number): Tool<typeof parameters>;
+declare const batchParameters: z.ZodObject<{
+    tasks: z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+        root: z.ZodOptional<z.ZodString>;
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, {
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }>, "atleastone">;
+}, "strip", z.ZodTypeAny, {
+    tasks: [{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, ...{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }[]];
+}, {
+    tasks: [{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }, ...{
+        task: string;
+        root?: string | undefined;
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        tools?: [string, ...string[]] | undefined;
+    }[]];
+}>;
+/**
+ * Build the `spawn_subagents` tool (C.33) — the PARALLEL fan-out seam, bound to
+ * `depth`. One tool call dispatches N independent, internally-sequential children
+ * concurrently (JC-A) under the shared concurrency semaphore, and returns their
+ * results IN REQUEST ORDER. A DEPTH-0 capability: it is never granted to a child,
+ * so fan-out never nests (which keeps the semaphore deadlock-free).
+ */
+export declare function makeSpawnSubagentsTool(orchestrator: SubagentOrchestrator, depth: number): Tool<typeof batchParameters>;
 export {};

package/dist/subagent/spawn-tool.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { CruxyError, ErrorCode } from "../errors/index.js";
-import { SPAWN_SUBAGENT_TOOL_NAME } from "./registry-scope.js";
+import { SPAWN_SUBAGENT_TOOL_NAME, SPAWN_SUBAGENTS_TOOL_NAME, } from "./registry-scope.js";
 /**
  * The `spawn_subagent` tool (C.14): the parent-facing seam for delegation. A
  * normal tool on the same loop as everything else — no hidden control flow.
@@ -34,9 +34,9 @@ const parameters = z.object({
         .optional()
         .describe("Cap on the subagent's total tokens (clamped to the configured ceiling)."),
 });
-/** The compact wire shape fed back to the parent model. */
-function renderResult(result) {
-    return JSON.stringify({
+/** The compact, transcript-free object fed back to the parent model. */
+function resultPayload(result) {
+    return {
         status: result.status,
         summary: result.summary,
         ...(result.artifacts ? { artifacts: result.artifacts } : {}),
@@ -46,7 +46,18 @@ function renderResult(result) {
             input: result.usage.input_tokens,
             output: result.usage.output_tokens,
         },
-    });
+    };
+}
+/** The compact wire shape fed back to the parent model. */
+function renderResult(result) {
+    return JSON.stringify(resultPayload(result));
+}
+/** A coded, actionable tool-error string for an error the MODEL should correct
+ * (scope overlap, depth exceeded, tool scoping) — never the raw stack. */
+function toolErrorMessage(err) {
+    return CruxyError.is(err)
+        ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+        : err.message;
 }
 /** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
 export function makeSpawnSubagentTool(orchestrator, depth) {
@@ -79,10 +90,7 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
                 }
                 // Depth-exceed and scope violations are the model's to correct: feed
                 // the coded, actionable message back as a tool error.
-                const message = CruxyError.is(err)
-                    ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
-                    : err.message;
-                return { ok: false, error: message };
+                return { ok: false, error: toolErrorMessage(err) };
             }
             // A failed child is an is_error result (strong signal), still structured;
             // budget-exceeded is informational — a partial result, not an error.
@@ -92,3 +100,90 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
         },
     };
 }
+// ── parallel fan-out (C.33) ───────────────────────────────────────────────────
+/** One child's spec inside a `spawn_subagents` batch. Mirrors the singular
+ * tool's shape plus `root` — the C.33 disjoint-scope unit. */
+const batchChild = z.object({
+    task: z
+        .string()
+        .min(1)
+        .describe("The complete, self-contained subtask. The subagent starts with NO context " +
+        "beyond this text — include every path, constraint, and expected output."),
+    tools: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Tool names to grant this child — a subset of your own. Omit for read-only. " +
+        "Two children that both hold write/shell tools MUST target different `root`s."),
+    root: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Workspace root name (from your Environment) to scope this child to: its " +
+        "writes are confined there. Required to make two writing children disjoint; " +
+        "omit for read-only children or a single-root workspace."),
+    maxIterations: z.number().int().positive().optional(),
+    maxTokens: z.number().int().positive().optional(),
+});
+const batchParameters = z.object({
+    tasks: z
+        .array(batchChild)
+        .nonempty()
+        .describe("The independent subtasks to run CONCURRENTLY. Results come back in this " +
+        "same order. Bounded by subagent.maxConcurrency; excess children queue."),
+});
+/** Map a validated batch child to a {@link SubagentSpec}. */
+function toSpec(child) {
+    const budget = {
+        ...(child.maxIterations !== undefined
+            ? { maxIterations: child.maxIterations }
+            : {}),
+        ...(child.maxTokens !== undefined ? { maxTokens: child.maxTokens } : {}),
+    };
+    return {
+        task: child.task,
+        ...(child.tools ? { tools: child.tools } : {}),
+        ...(child.root !== undefined ? { root: child.root } : {}),
+        budget,
+    };
+}
+/**
+ * Build the `spawn_subagents` tool (C.33) — the PARALLEL fan-out seam, bound to
+ * `depth`. One tool call dispatches N independent, internally-sequential children
+ * concurrently (JC-A) under the shared concurrency semaphore, and returns their
+ * results IN REQUEST ORDER. A DEPTH-0 capability: it is never granted to a child,
+ * so fan-out never nests (which keeps the semaphore deadlock-free).
+ */
+export function makeSpawnSubagentsTool(orchestrator, depth) {
+    return {
+        name: SPAWN_SUBAGENTS_TOOL_NAME,
+        description: "Delegate SEVERAL independent subtasks to scoped subagents that run in PARALLEL, " +
+            "each with its own fresh context, restricted toolset, and hard budget. Returns a " +
+            "structured result per child, in the same order as `tasks` — transcripts discarded. " +
+            "Use when subtasks don't depend on each other (e.g. investigate N areas at once). " +
+            "For children that WRITE, give each a distinct `root`; overlapping write scope is " +
+            "refused. For a single subtask, use spawn_subagent instead.",
+        parameters: batchParameters,
+        async execute(input) {
+            let results;
+            try {
+                results = await orchestrator.spawnMany(input.tasks.map(toSpec), depth);
+            }
+            catch (err) {
+                // Non-interactive default-deny propagates to the boundary (U.3).
+                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                    throw err;
+                }
+                // Scope overlap / depth-exceed are the model's to correct — coded error.
+                return { ok: false, error: toolErrorMessage(err) };
+            }
+            // Partial results are honest, not an error: the array carries each child's
+            // own status (done / failed / budget-exceeded / cancelled). The batch call
+            // succeeds as long as it was dispatched — the parent reasons over the mix.
+            return {
+                ok: true,
+                output: JSON.stringify(results.map(resultPayload)),
+            };
+        },
+    };
+}

package/dist/subagent/types.d.ts

@@ -7,8 +7,13 @@ import type { TaskClass } from "../routing/index.js";
  * result and discards its transcript. The parent reasons over the result only;
  * context isolation is the whole point.
  */
-/** Why a subagent run ended. Every path returns a result — never a hang. */
-export type SubagentStatus = "done" | "budget-exceeded" | "failed";
+/**
+ * Why a subagent run ended. Every path returns a result — never a hang.
+ * `cancelled` (C.33) is a parallel-fan-out outcome: a fatal sibling failure or
+ * Ctrl-C aborted this child before it finished — recorded honestly, never
+ * dressed up as `done`.
+ */
+export type SubagentStatus = "done" | "budget-exceeded" | "failed" | "cancelled";
 /**
  * Hard caps a subagent runs under. `maxIterations` and `maxTokens` are always
  * finite — a subagent is bounded by construction; `timeoutMs` is an optional
@@ -41,6 +46,16 @@ export interface SubagentSpec {
      * declaration at the spawn call site — not something the router guesses.
      */
     taskClass?: TaskClass;
+    /**
+     * The workspace root (by exact name, C.26) this child is scoped to (C.33).
+     * When set, the child's cwd and confinement narrow to that ONE root, so its
+     * writes land there and nowhere else — the unit of the parallel fan-out's
+     * disjoint-scope guarantee: two writing children must name distinct roots or
+     * the batch is refused pre-dispatch. Omitted → the child inherits the full
+     * session workspace (read-only fan-out, or a single-root session), unchanged
+     * from C.14.
+     */
+    root?: string;
 }
 /**
  * What the parent gets back — compact structured data, never the transcript.

package/dist/testing/run-tests-tool.js

@@ -99,7 +99,7 @@ export function makeRunTestsTool(deps = {}) {
                 command: resolved.command,
                 // C.26 attribution seam (JC-β): primary root name for Steps 4/5. Tests are
                 // primary-only this release; the gate hard-attributes to the primary.
-                root: ctx.workspace?.primary().name,
+                root: ctx.workspace.primary().name,
             });
             if (!decision.allow) {
                 return {

package/dist/tools/file/paths.d.ts

@@ -9,12 +9,11 @@ import type { ToolContext } from "../types.js";
  */
 export { PathEscapeError };
 /**
- * The workspace this context acts in. Runtime always sets `ctx.workspace`; the
- * fallback to a trivial single-root workspace over `ctx.cwd` exists only for the
- * many test contexts (and any not-yet-migrated caller) that don't set one. The
- * fallback is byte-identical to the legacy single-root behaviour by construction:
- * its one root's `absPath` is `path.resolve(ctx.cwd)`, the same root the old
- * `resolveInRoot` confined to.
+ * The workspace this context acts in. `ctx.workspace` is a required field (C.26
+ * Step 6), so this is a plain accessor — there is no single-root fallback to
+ * synthesize, because no code path can reach a path-taking tool without a
+ * workspace (the type forbids the omission; the `no-split-brain` guard forbids a
+ * mid-subsystem synthesis). Kept as the one named seam every funnel calls.
  */
 export declare function contextWorkspace(ctx: ToolContext): Workspace;
 /**

package/dist/tools/file/paths.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { multirootWriteDeferred, rootAmbiguous } from "../../errors/index.js";
-import { confineToRoot, PathEscapeError, selectRoot, singleRootWorkspace, } from "../../workspace/index.js";
+import { confineToRoot, PathEscapeError, selectRoot, } from "../../workspace/index.js";
 /**
  * Path confinement for file tools (C.26). The confinement kernel itself lives in
  * `src/workspace` ({@link confineToRoot}); this module is the tool-facing funnel
@@ -10,15 +10,14 @@ import { confineToRoot, PathEscapeError, selectRoot, singleRootWorkspace, } from
  */
 export { PathEscapeError };
 /**
- * The workspace this context acts in. Runtime always sets `ctx.workspace`; the
- * fallback to a trivial single-root workspace over `ctx.cwd` exists only for the
- * many test contexts (and any not-yet-migrated caller) that don't set one. The
- * fallback is byte-identical to the legacy single-root behaviour by construction:
- * its one root's `absPath` is `path.resolve(ctx.cwd)`, the same root the old
- * `resolveInRoot` confined to.
+ * The workspace this context acts in. `ctx.workspace` is a required field (C.26
+ * Step 6), so this is a plain accessor — there is no single-root fallback to
+ * synthesize, because no code path can reach a path-taking tool without a
+ * workspace (the type forbids the omission; the `no-split-brain` guard forbids a
+ * mid-subsystem synthesis). Kept as the one named seam every funnel calls.
  */
 export function contextWorkspace(ctx) {
-    return ctx.workspace ?? singleRootWorkspace(ctx.cwd);
+    return ctx.workspace;
 }
 /**
  * Resolve a tool-supplied path against the workspace and prove it stays inside the

package/dist/tools/shell/exec.js

@@ -13,7 +13,7 @@ export async function runGatedShell(command, ctx) {
     const decision = await ctx.requestApproval({
         kind: "shell",
         command,
-        root: ctx.workspace?.primary().name,
+        root: ctx.workspace.primary().name,
     });
     if (!decision.allow) {
         return { approved: false, rejection: decision.feedback };
@@ -74,12 +74,17 @@ function runBounded(command, ctx) {
         };
         child.stdout?.on("data", capture);
         child.stderr?.on("data", capture);
-        // A single guard so the timeout-kill and the natural close can't both fire.
+        // A single guard so the timeout-kill, an external abort, and the natural
+        // close can't all fire. `cleanup` deregisters the abort listener on every
+        // settle path so a resolved command never holds a dangling subscription.
         let settled = false;
+        const abortSignal = ctx.signal;
+        const cleanup = () => abortSignal?.removeEventListener("abort", onAbort);
         const timer = setTimeout(() => {
             if (settled)
                 return;
             settled = true;
+            cleanup();
             killTree(child.pid);
             resolve({
                 timedOut: true,
@@ -89,11 +94,37 @@ function runBounded(command, ctx) {
                 truncated,
             });
         }, timeoutMs);
+        // External cancellation (C.33): a cancelled sibling's in-flight command is
+        // kill-tree'd here instead of orphaned. Reports as a `SIGKILL` termination
+        // (not a timeout) so the caller can tell cancel apart from a real timeout.
+        function onAbort() {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            cleanup();
+            killTree(child.pid);
+            resolve({
+                timedOut: false,
+                exitCode: null,
+                signal: "SIGKILL",
+                output: Buffer.concat(chunks).toString("utf8"),
+                truncated,
+            });
+        }
+        if (abortSignal?.aborted) {
+            // Already cancelled before the child got going — reap it immediately.
+            queueMicrotask(onAbort);
+        }
+        else {
+            abortSignal?.addEventListener("abort", onAbort, { once: true });
+        }
         child.on("error", (err) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            cleanup();
             resolve({
                 timedOut: false,
                 exitCode: null,
@@ -103,15 +134,16 @@ function runBounded(command, ctx) {
                 spawnError: err.message,
             });
         });
-        child.on("close", (code, signal) => {
+        child.on("close", (code, closeSignal) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            cleanup();
             resolve({
                 timedOut: false,
                 exitCode: code,
-                signal: signal ?? null,
+                signal: closeSignal ?? null,
                 output: Buffer.concat(chunks).toString("utf8"),
                 truncated,
             });

package/dist/tools/types.d.ts

@@ -166,13 +166,15 @@ export interface ToolContext {
     /**
      * The declared workspace root set for this session (C.26). Path-taking tools
      * resolve *through* this rather than through `cwd`, so a multi-root session
-     * confines each call to the one root it selects. Optional only so the many test
-     * contexts that predate multi-root stay valid: the runtime always populates it,
-     * and when absent the file resolver falls back to a trivial single-root
-     * workspace over `cwd` (byte-identical to legacy single-root behaviour). `cwd`
+     * confines each call to the one root it selects. **Required** (C.26 Step 6): a
+     * construction site that fails to thread it is a *compile error*, not a runtime
+     * primary-default — closing the omission hole the old optional field left. The
+     * runtime always sets it; a single-root caller builds one with `sessionWorkspace`.
+     * (The type catches *omission*; it cannot catch a *fabricated* workspace threaded
+     * through — the `no-split-brain` grep guard covers that. See its header.) `cwd`
      * remains equal to `workspace.primary().absPath`.
      */
-    workspace?: Workspace;
+    workspace: Workspace;
     /** Fully-resolved CLI configuration. */
     config: CruxyConfig;
     /** Shared leveled logger (diagnostics to stderr, `print` to stdout). */
@@ -208,6 +210,15 @@ export interface ToolContext {
      * populated). Absent → host execution, unchanged.
      */
     sandbox?: SandboxService;
+    /**
+     * Cooperative cancellation for in-flight tool work (C.33). Set on a subagent's
+     * ctx when it runs inside a parallel fan-out: when a fatal sibling failure or
+     * Ctrl-C aborts the batch, this signal fires, and a long-running `run_command`
+     * kills its whole process tree instead of leaving it orphaned — the C.12/C.16
+     * kill-tree discipline extended to N concurrent children. Absent → no external
+     * cancellation (the tool's own timeout still applies), unchanged behaviour.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The one interface every tool implements. `parameters` is a zod schema; it both

package/dist/workspace/add-root.d.ts

@@ -0,0 +1,27 @@
+import type { RootSpec } from "./types.js";
+import { Workspace } from "./workspace.js";
+/**
+ * The interactive add-root path (C.26 step 5). Adding a workspace root is an
+ * EXPLICIT HUMAN act — it grows the trust surface (a new root can carry its own
+ * hooks / MCP / project memory), so it is:
+ *
+ *   - reachable ONLY from the REPL command and the CLI, never as a model tool.
+ *     The model can act only through the tool registry (`registry.get(name)`),
+ *     and no tool is registered for this — the allowlist argument is unchanged.
+ *   - TTY-only: refused (coded) when there is no interactive human to vouch.
+ *   - held to the SAME validation as `--root`: the new root must exist, be a
+ *     directory, have a unique name, and NOT nest/overlap an existing root
+ *     (CRUXY_E_ROOT_OVERLAP) — reusing {@link buildWorkspace}, the single
+ *     Workspace constructor from user input.
+ *
+ * Returns the NEW immutable Workspace (the root set only ever grows by
+ * constructing a new one). A freshly added root starts UNTRUSTED; its hooks and
+ * project memory stay inert until explicitly trusted.
+ */
+export interface AddRootOptions {
+    /** Base dir for resolving a relative `path` (the session's primary root). */
+    cwd: string;
+    /** Whether stdin is a TTY — add-root is refused without an interactive human. */
+    tty: boolean;
+}
+export declare function addRootToWorkspace(current: Workspace, spec: RootSpec, opts: AddRootOptions): Promise<Workspace>;

package/dist/workspace/add-root.js

@@ -0,0 +1,16 @@
+import { usageError } from "../errors/index.js";
+import { buildWorkspace } from "./workspace.js";
+export async function addRootToWorkspace(current, spec, opts) {
+    if (!opts.tty) {
+        throw usageError("adding a workspace root is an interactive action and needs a TTY", ["declare it up front with `--root name=path` instead"]);
+    }
+    // Rebuild from the existing roots (as specs) + the new one, so EVERY
+    // buildWorkspace guard — existence, directory, name uniqueness, and the
+    // nested/overlap refusal — applies to the addition. Existing roots keep their
+    // names, absolute paths, and order (the primary stays first).
+    const specs = [
+        ...current.roots().map((r) => ({ name: r.name, path: r.absPath })),
+        spec,
+    ];
+    return buildWorkspace(specs, { cwd: opts.cwd });
+}

package/dist/workspace/index.d.ts

@@ -1,5 +1,6 @@
 export type { DeclaredRoot, RootSpec } from "./types.js";
-export { Workspace, buildWorkspace, singleRootWorkspace } from "./workspace.js";
+export { Workspace, buildWorkspace, sessionWorkspace } from "./workspace.js";
 export { PathEscapeError, confineToRoot, isInside, resolveInWorkspace, } from "./resolve.js";
 export { selectRoot } from "./select.js";
 export type { RootRef, SelectedRoot } from "./select.js";
+export { addRootToWorkspace, type AddRootOptions } from "./add-root.js";

package/dist/workspace/index.js

@@ -1,3 +1,4 @@
-export { Workspace, buildWorkspace, singleRootWorkspace } from "./workspace.js";
+export { Workspace, buildWorkspace, sessionWorkspace } from "./workspace.js";
 export { PathEscapeError, confineToRoot, isInside, resolveInWorkspace, } from "./resolve.js";
 export { selectRoot } from "./select.js";
+export { addRootToWorkspace } from "./add-root.js";

package/dist/workspace/workspace.d.ts

@@ -49,8 +49,13 @@ export declare function buildWorkspace(specs: readonly RootSpec[], opts?: {
     cwd?: string;
 }): Promise<Workspace>;
 /**
- * Build a trivial single-root workspace from one absolute path — the back-compat
- * bridge for the many call sites that still pass a single `cwd`. The one root is
- * primary and named by its basename.
+ * Build THE session's workspace from a single absolute path — the trivial
+ * single-root case. This is a *session construction* primitive, not a per-call
+ * fallback: after C.26 Step 6 it is called ONLY at the two CLI entry points that
+ * turn argv into a session (`cli/commands/run.ts`, `cli/onboard.ts`), never in the
+ * middle of a subsystem. Synthesizing one elsewhere would silently scope that
+ * subsystem to its own cwd while the fan tools see N roots (a split-brain) — the
+ * `no-split-brain` guard fails on any `sessionWorkspace(` outside those two files.
+ * The one root is primary and named by its basename.
  */
-export declare function singleRootWorkspace(absPath: string): Workspace;
+export declare function sessionWorkspace(absPath: string): Workspace;

package/dist/workspace/workspace.js

@@ -168,11 +168,16 @@ export async function buildWorkspace(specs, opts = {}) {
     return new Workspace(declared);
 }
 /**
- * Build a trivial single-root workspace from one absolute path — the back-compat
- * bridge for the many call sites that still pass a single `cwd`. The one root is
- * primary and named by its basename.
+ * Build THE session's workspace from a single absolute path — the trivial
+ * single-root case. This is a *session construction* primitive, not a per-call
+ * fallback: after C.26 Step 6 it is called ONLY at the two CLI entry points that
+ * turn argv into a session (`cli/commands/run.ts`, `cli/onboard.ts`), never in the
+ * middle of a subsystem. Synthesizing one elsewhere would silently scope that
+ * subsystem to its own cwd while the fan tools see N roots (a split-brain) — the
+ * `no-split-brain` guard fails on any `sessionWorkspace(` outside those two files.
+ * The one root is primary and named by its basename.
  */
-export function singleRootWorkspace(absPath) {
+export function sessionWorkspace(absPath) {
     const abs = path.resolve(absPath);
     return new Workspace([
         { name: path.basename(abs) || "root", absPath: abs, primary: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {