@cruxy/cli 0.22.1 → 0.24.0

package/dist/tools/list-files.d.ts

@@ -1,7 +1,13 @@
 import { z } from "zod";
 import type { Tool } from "./types.js";
 /**
- * Proof-of-concept tool: list the entries of `ctx.cwd`, marking each as a
- * directory or a file. Takes no arguments.
+ * List the entries of a workspace root, marking each as a directory or a file.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
+ * root — each `fs.readdir(root.absPath)` reads exactly the root its section
+ * header names. A per-root read error is NAMED (not fatal), and a `root` argument
+ * scopes to one root.
  */
-export declare const listFilesTool: Tool<z.ZodObject<Record<string, never>>>;
+export declare const listFilesTool: Tool<z.ZodObject<{
+    root: z.ZodOptional<z.ZodString>;
+}>>;

package/dist/tools/list-files.js

@@ -1,27 +1,62 @@
 import { promises as fs } from "node:fs";
 import { z } from "zod";
+import { contextWorkspace, resolveReadRoots } from "./file/paths.js";
+/** Render one directory's entries (sorted, dir/file marked) or an empty note. */
+async function listDir(absDir) {
+    const entries = await fs.readdir(absDir, { withFileTypes: true });
+    if (entries.length === 0) {
+        return "(empty directory)";
+    }
+    return entries
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((entry) => `${entry.isDirectory() ? "dir " : "file"}  ${entry.name}`)
+        .join("\n");
+}
 /**
- * Proof-of-concept tool: list the entries of `ctx.cwd`, marking each as a
- * directory or a file. Takes no arguments.
+ * List the entries of a workspace root, marking each as a directory or a file.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
+ * root — each `fs.readdir(root.absPath)` reads exactly the root its section
+ * header names. A per-root read error is NAMED (not fatal), and a `root` argument
+ * scopes to one root.
  */
 export const listFilesTool = {
     name: "list_files",
     description: "List the files and directories in the current working directory.",
-    parameters: z.object({}),
-    async execute(_input, ctx) {
+    parameters: z.object({
+        root: z
+            .string()
+            .optional()
+            .describe("In a multi-repo session, restrict the listing to a single declared root by name. Omit to list every root."),
+    }),
+    async execute(input, ctx) {
+        const ws = contextWorkspace(ctx);
+        let roots;
         try {
-            const entries = await fs.readdir(ctx.cwd, { withFileTypes: true });
-            if (entries.length === 0) {
-                return { ok: true, output: "(empty directory)" };
-            }
-            const lines = entries
-                .slice()
-                .sort((a, b) => a.name.localeCompare(b.name))
-                .map((entry) => `${entry.isDirectory() ? "dir " : "file"}  ${entry.name}`);
-            return { ok: true, output: lines.join("\n") };
+            roots = resolveReadRoots(ctx, { root: input.root });
         }
         catch (err) {
             return { ok: false, error: err.message };
         }
+        // Single-root: byte-identical with the pre-C.26 tool.
+        if (!ws.isMultiRoot) {
+            try {
+                return { ok: true, output: await listDir(roots[0].absPath) };
+            }
+            catch (err) {
+                return { ok: false, error: err.message };
+            }
+        }
+        // Multi-root: one section per root; a per-root read error is named, not fatal.
+        const sections = await Promise.all(roots.map(async (root) => {
+            try {
+                return `${root.name}:\n${await listDir(root.absPath)}`;
+            }
+            catch (err) {
+                return `${root.name}: ${err.message}`;
+            }
+        }));
+        return { ok: true, output: sections.join("\n\n") };
     },
 };

package/dist/tools/search-codebase.d.ts

@@ -4,12 +4,15 @@ declare const parameters: z.ZodObject<{
     query: z.ZodString;
     k: z.ZodOptional<z.ZodNumber>;
     pathGlob: z.ZodOptional<z.ZodString>;
+    root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     query: string;
+    root?: string | undefined;
     k?: number | undefined;
     pathGlob?: string | undefined;
 }, {
     query: string;
+    root?: string | undefined;
     k?: number | undefined;
     pathGlob?: string | undefined;
 }>;
@@ -18,6 +21,13 @@ declare const parameters: z.ZodObject<{
  * approval — like read_file and grep_files. The index is built/refreshed lazily
  * on first use; results are ranked by cosine similarity and token-budgeted.
  *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, the search fans
+ * every root, gets each root's own index (`getIndexService(root.absPath)` — the
+ * per-cwd cache is the per-root map), and merges into one globally-ranked list.
+ * Each hit is labelled with its source root, `k` and the token budget are applied
+ * AFTER the merge (global rank, ⚖︎JC-I), and any root whose index failed — or whose
+ * matches the cap dropped — is NAMED, never silently implied to have no matches.
+ *
  * Complements `grep_files`: prefer this for conceptual "where / how does X work"
  * questions, and grep for exact strings or symbols.
  */

package/dist/tools/search-codebase.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { getIndexService } from "../indexing/index.js";
+import { getIndexService, mergeRankedHits } from "../indexing/index.js";
+import { contextWorkspace, labelName, resolveReadRoots } from "./file/paths.js";
 /** Hard cap on `k`, mirroring the retriever. */
 const MAX_K = 50;
 const parameters = z.object({
@@ -18,12 +19,23 @@ const parameters = z.object({
         .string()
         .optional()
         .describe("Optional glob to restrict results by path, e.g. 'src/**/*.ts' or 'packages/cli/**'."),
+    root: z
+        .string()
+        .optional()
+        .describe("In a multi-repo session, restrict the search to a single declared root by name. Omit to search every root and label each hit with the root it came from."),
 });
 /**
  * Semantic search over the project's local code index (C.17). Read-only — no
  * approval — like read_file and grep_files. The index is built/refreshed lazily
  * on first use; results are ranked by cosine similarity and token-budgeted.
  *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, the search fans
+ * every root, gets each root's own index (`getIndexService(root.absPath)` — the
+ * per-cwd cache is the per-root map), and merges into one globally-ranked list.
+ * Each hit is labelled with its source root, `k` and the token budget are applied
+ * AFTER the merge (global rank, ⚖︎JC-I), and any root whose index failed — or whose
+ * matches the cap dropped — is NAMED, never silently implied to have no matches.
+ *
  * Complements `grep_files`: prefer this for conceptual "where / how does X work"
  * questions, and grep for exact strings or symbols.
  */
@@ -38,28 +50,79 @@ export const searchCodebaseTool = {
                 error: "codebase indexing is disabled (set index.enabled = true to use search_codebase)",
             };
         }
+        const ws = contextWorkspace(ctx);
+        let roots;
         try {
-            const service = await getIndexService(ctx.cwd, ctx.config, ctx.logger);
-            const hits = await service.search({
-                query: input.query,
-                k: input.k,
-                pathGlob: input.pathGlob,
-            });
-            if (hits.length === 0) {
-                return { ok: true, output: "(no matches in the codebase index)" };
-            }
-            return { ok: true, output: formatHits(hits) };
+            roots = resolveReadRoots(ctx, { root: input.root });
         }
         catch (err) {
+            // Unknown root name (R1) — fail loud rather than silently searching primary.
             return { ok: false, error: err.message };
         }
+        // Single-root: byte-identical with the pre-C.26 tool (no label, no footer).
+        if (!ws.isMultiRoot) {
+            try {
+                const only = roots[0];
+                const service = await getIndexService(only.absPath, ctx.config, ctx.logger);
+                const hits = await service.search({
+                    query: input.query,
+                    k: input.k,
+                    pathGlob: input.pathGlob,
+                    root: only.name,
+                });
+                if (hits.length === 0) {
+                    return { ok: true, output: "(no matches in the codebase index)" };
+                }
+                return { ok: true, output: formatHits(hits, false) };
+            }
+            catch (err) {
+                return { ok: false, error: err.message };
+            }
+        }
+        // Multi-root fan: one independent search per root, per-root failures isolated
+        // (one root's broken index must not blank the others — but it IS named).
+        const perRoot = [];
+        const rawByRoot = new Map();
+        const searched = [];
+        const failed = [];
+        for (const root of roots) {
+            try {
+                const service = await getIndexService(root.absPath, ctx.config, ctx.logger);
+                const hits = await service.search({
+                    query: input.query,
+                    k: input.k,
+                    pathGlob: input.pathGlob,
+                    root: root.name,
+                    // Unbudgeted per root; the real budget is applied once after the merge.
+                    tokenBudget: Number.POSITIVE_INFINITY,
+                });
+                perRoot.push(hits);
+                rawByRoot.set(root.name, hits.length);
+                searched.push(root.name);
+            }
+            catch (err) {
+                failed.push({ name: root.name, reason: err.message });
+            }
+        }
+        // Global rank + budget + cap AFTER the merge (⚖︎JC-I): a strong hit in one root
+        // is never crowded out by a per-root cap in another, and the token budget is
+        // honoured once for the whole result.
+        const merged = mergeRankedHits(perRoot, {
+            k: input.k ?? ctx.config.index.search.defaultK,
+            tokenBudget: ctx.config.index.search.tokenBudget,
+        });
+        return {
+            ok: true,
+            output: renderFanned(merged, { searched, failed, rawByRoot }),
+        };
     },
 };
-/** Render hits as a compact, model-readable block. */
-function formatHits(hits) {
+/** Render hits as a compact, model-readable block; label by root when multi-root. */
+function formatHits(hits, multiRoot) {
     return hits
         .map((hit) => {
-        const header = `${hit.path}:${hit.startLine}-${hit.endLine}  (score ${hit.score.toFixed(3)})`;
+        const loc = multiRoot ? labelName(hit.root, hit.path) : hit.path;
+        const header = `${loc}:${hit.startLine}-${hit.endLine}  (score ${hit.score.toFixed(3)})`;
         const body = hit.snippet
             .split("\n")
             .map((line) => `    ${line}`)
@@ -68,3 +131,43 @@ function formatHits(hits) {
     })
         .join("\n\n");
 }
+/**
+ * Render a fanned multi-root result with an honest footer: which roots were
+ * searched, which had matches dropped by the global cap, and which roots' indexes
+ * were unavailable — the last kept DISTINCT from "no matches" so an unsearched
+ * root is never read as an empty one (⚖︎6/JC-I).
+ */
+function renderFanned(merged, ctx) {
+    const shownByRoot = new Map();
+    for (const hit of merged) {
+        shownByRoot.set(hit.root, (shownByRoot.get(hit.root) ?? 0) + 1);
+    }
+    const notes = [];
+    // Truncation: a root returned matches that the global cap/budget dropped.
+    for (const name of ctx.searched) {
+        const raw = ctx.rawByRoot.get(name) ?? 0;
+        const shown = shownByRoot.get(name) ?? 0;
+        if (raw > shown) {
+            const n = raw - shown;
+            notes.push(`${name}: ${n} more match${n === 1 ? "" : "es"} not shown (result cap)`);
+        }
+    }
+    // Per-root index failures — named, and never conflated with "no matches".
+    for (const f of ctx.failed) {
+        notes.push(`${f.name}: index unavailable — ${f.reason}`);
+    }
+    const scope = ctx.searched.length
+        ? `searched ${ctx.searched.length} root${ctx.searched.length === 1 ? "" : "s"}: ${ctx.searched.join(", ")}`
+        : "no roots could be searched";
+    const lines = [];
+    if (merged.length) {
+        lines.push(formatHits(merged, true), "");
+    }
+    else if (ctx.searched.length) {
+        lines.push("(no matches in the codebase index)", "");
+    }
+    lines.push(scope);
+    for (const note of notes)
+        lines.push(`— ${note}`);
+    return lines.join("\n");
+}

package/dist/tools/shell/exec.js

@@ -7,7 +7,14 @@ import { spawn } from "node:child_process";
  * sandbox that can't run throws its coded error (fail loud, no host fallback).
  */
 export async function runGatedShell(command, ctx) {
-    const decision = await ctx.requestApproval({ kind: "shell", command });
+    // `root` is the C.26 attribution seam (JC-β): populated with the primary root
+    // name for Steps 4/5. Shell is primary-only this release, so the checkpoint gate
+    // hard-attributes it to the primary regardless of this value.
+    const decision = await ctx.requestApproval({
+        kind: "shell",
+        command,
+        root: ctx.workspace.primary().name,
+    });
     if (!decision.allow) {
         return { approved: false, rejection: decision.feedback };
     }
@@ -67,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,
@@ -82,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,
@@ -96,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

@@ -2,6 +2,7 @@ import type { z, ZodTypeAny } from "zod";
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/types.js";
 import type { SandboxService } from "../sandbox/index.js";
+import type { Workspace } from "../workspace/index.js";
 import type { logger } from "../utils/logger.js";
 /** The leveled logger instance shared across the CLI. */
 type Logger = typeof logger;
@@ -67,7 +68,11 @@ export type ActionPreview =
 /**
  * The whole publish plan for a `vcs` action (C.15): the feature branch, the
  * conventional commit, and the PR title/body — shown as one block so the user
- * approves the entire branch → commit → push → open-PR sequence at once.
+ * approves the entire branch → commit → push → open-PR sequence at once. C.26
+ * Step 4 adds `target` (the resolved `host/owner/repo` the PR will open against)
+ * so the human sees the real API destination — not just the root name — before
+ * approving (⚖︎JC-4); it is re-resolved and re-checked immediately before the API
+ * call, so what is shown here is what the guard holds them to.
  */
  | {
     type: "pr";
@@ -77,6 +82,12 @@ export type ActionPreview =
     commitBody: string;
     prTitle: string;
     prBody: string;
+    /** The resolved forge target parsed from `origin` at approval time. */
+    target: {
+        host: string;
+        owner: string;
+        repo: string;
+    };
 }
 /**
  * The full blast radius of a checkpoint restore (C.32): every file rollback
@@ -95,6 +106,25 @@ export type ActionPreview =
     externalPaths: string[];
     /** The run executed shell commands, so per-file attribution is impossible. */
     attributionUnknown: boolean;
+}
+/**
+ * A multi-root rollback set (C.26 step 3): one combined preview grouped by root,
+ * each root carrying its own file diffs and external-change warnings, so a single
+ * U.3 approval covers restoring every touched root of a run at once (⚖︎JC-ι). One
+ * `roots` entry per member of the run's `CheckpointSet`.
+ */
+ | {
+    type: "rollback-set";
+    runId: string;
+    createdAt: string;
+    runSummary: string;
+    roots: {
+        rootName: string;
+        checkpointId: string;
+        files: PatchFilePreview[];
+        externalPaths: string[];
+        attributionUnknown: boolean;
+    }[];
 };
 /**
  * A side-effecting action a tool wants to take, passed to `ctx.approve`. The
@@ -112,6 +142,16 @@ export interface ApproveAction {
      * covers another — and a server can never mark its own tool low-risk. */
     server?: string;
     tool?: string;
+    /**
+     * The declared workspace root this action acts in (C.26). `vcs` sets it to the
+     * root a pull request was selected for (C.26 Step 4): it may be non-primary, and
+     * the checkpoint gate attributes the vcs checkpoint to exactly this root. `shell`/
+     * `test` still set it to the primary as an attribution seam — their non-primary
+     * support is Step 5 (JC-β residual), so the gate hard-attributes them to the
+     * primary regardless of this value. File actions carry their root in the resolved
+     * absolute `path`/preview instead, so they leave this unset.
+     */
+    root?: string;
     /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;
 }
@@ -123,6 +163,18 @@ export interface ApproveAction {
 export interface ToolContext {
     /** Absolute path the tool should treat as its working root. */
     cwd: string;
+    /**
+     * 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. **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;
     /** Fully-resolved CLI configuration. */
     config: CruxyConfig;
     /** Shared leveled logger (diagnostics to stderr, `print` to stdout). */
@@ -137,6 +189,18 @@ export interface ToolContext {
      * tools never call this.
      */
     requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    /**
+     * Whether per-root checkpointing is active for this session (C.26 step 3). It is
+     * the single fact that lifts the JC-1 non-primary-write refusal: a write to a
+     * non-primary root is permitted **iff** this is true, because a true value means
+     * a per-root checkpoint gate is wired that captures the write (get-or-creates the
+     * root's service and snapshots it) before it reaches disk. False/absent → a
+     * non-primary write is still refused with `CRUXY_E_MULTIROOT_WRITE_DEFERRED`, so
+     * a checkpoints-disabled session never widens un-restorable writes to siblings.
+     * Set together with `requestApproval` (the gate), so permit and capture are one
+     * decision — never lift-then-verify.
+     */
+    checkpointsActive?: boolean;
     /**
      * Isolation substrate for the shell + test tools (C.16). Present ONLY when
      * the sandbox is enabled; when set, `run_command`/`run_tests` execute the
@@ -146,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/vcs/git.d.ts

@@ -6,6 +6,14 @@ export interface GitResult {
 }
 /** Run `git <args>` in `cwd`, capturing stdout/stderr/exit. Never throws. */
 export declare function runGitCapture(args: string[], cwd: string): GitResult;
+/**
+ * The absolute path of the git working tree that contains `cwd` (its
+ * `--show-toplevel`), or `null` when `cwd` is not inside a git repository. Git
+ * returns a canonical (symlink-resolved) path. Used by the C.26 cross-root guard
+ * to detect two declared roots that share one repository (a commit for one would
+ * `git add -A` the other's changes too).
+ */
+export declare function gitToplevel(cwd: string): string | null;
 /** The current branch name, or `null` when detached / not a repo. */
 export declare function currentBranch(cwd: string): string | null;
 /** The default set of branch names cruxy will never write to directly. */

package/dist/vcs/git.js

@@ -35,6 +35,20 @@ export function runGitCapture(args, cwd) {
     }
     return { ok: res.status === 0, stdout, stderr, code: res.status };
 }
+/**
+ * The absolute path of the git working tree that contains `cwd` (its
+ * `--show-toplevel`), or `null` when `cwd` is not inside a git repository. Git
+ * returns a canonical (symlink-resolved) path. Used by the C.26 cross-root guard
+ * to detect two declared roots that share one repository (a commit for one would
+ * `git add -A` the other's changes too).
+ */
+export function gitToplevel(cwd) {
+    const res = runGitCapture(["rev-parse", "--show-toplevel"], cwd);
+    if (!res.ok)
+        return null;
+    const top = res.stdout.trim();
+    return top === "" ? null : top;
+}
 /** The current branch name, or `null` when detached / not a repo. */
 export function currentBranch(cwd) {
     const res = runGitCapture(["rev-parse", "--abbrev-ref", "HEAD"], cwd);

package/dist/vcs/github.d.ts

@@ -1,4 +1,4 @@
-import type { ForgeProvider, PullRequestResult, PullRequestSpec, RepoInfo } from "./types.js";
+import type { ForgeProvider, PullRequestResult, PullRequestSpec, RepoIdentity, RepoInfo } from "./types.js";
 /**
  * GitHub implementation of {@link ForgeProvider} (C.15) — the only forge that
  * ships today. It talks to the REST API directly (no octokit dependency) and
@@ -16,6 +16,12 @@ export declare class GitHubProvider implements ForgeProvider {
     private readonly token;
     private readonly fetchImpl;
     constructor(opts: GitHubProviderOptions);
+    /**
+     * The LOCAL half of {@link getRepoInfo}: read `origin` and parse it, no network.
+     * Shared by the full lookup and by the Step-4 wrong-repo re-check so both derive
+     * the target from the exact same rule.
+     */
+    resolveRepoIdentity(cwd: string): RepoIdentity;
     getRepoInfo(cwd: string): Promise<RepoInfo>;
     createPullRequest(repo: RepoInfo, spec: PullRequestSpec): Promise<PullRequestResult>;
     /** Look up an open PR for `owner:head`, or `null` if there isn't one. */

package/dist/vcs/github.js

@@ -8,7 +8,12 @@ export class GitHubProvider {
         this.token = opts.token;
         this.fetchImpl = opts.fetchImpl ?? fetch;
     }
-    async getRepoInfo(cwd) {
+    /**
+     * The LOCAL half of {@link getRepoInfo}: read `origin` and parse it, no network.
+     * Shared by the full lookup and by the Step-4 wrong-repo re-check so both derive
+     * the target from the exact same rule.
+     */
+    resolveRepoIdentity(cwd) {
         const remote = runGitCapture(["remote", "get-url", "origin"], cwd);
         if (!remote.ok || remote.stdout.trim() === "") {
             throw usageError("no `origin` remote is configured for this repository", [
@@ -20,6 +25,10 @@ export class GitHubProvider {
         if (!parsed) {
             throw usageError(`could not parse the origin remote as a GitHub repository: ${remote.stdout.trim()}`, ["ensure `origin` points at a github.com (or GitHub Enterprise) repo"]);
         }
+        return parsed;
+    }
+    async getRepoInfo(cwd) {
+        const parsed = this.resolveRepoIdentity(cwd);
         // Best-effort: resolve the default branch so the PR base can default to it.
         const defaultBranch = await this.fetchDefaultBranch(parsed).catch(() => undefined);
         return { ...parsed, defaultBranch };

package/dist/vcs/service.d.ts

@@ -21,6 +21,14 @@ export type GenerateContent = (input: {
 }) => Promise<GeneratedContent>;
 export interface PrServiceDeps {
     cwd: string;
+    /**
+     * The name of the declared workspace root this PR acts in (C.26 Step 4). It is
+     * the exact root the caller selected — the U.3 attribution and the wrong-repo
+     * error name it verbatim, rather than re-deriving a basename from `cwd`. Defaults
+     * to `basename(cwd)` for callers that don't select a root (the single-root `cruxy
+     * pr` command), which is byte-identical to the pre-Step-4 attribution.
+     */
+    rootName?: string;
     config: CruxyConfig;
     forge: ForgeProvider;
     generate: GenerateContent;