@cruxy/cli 0.22.0 → 0.23.0

package/dist/tools/git-status.js

@@ -1,26 +1,58 @@
 import { z } from "zod";
 import { getGitStatus } from "../utils/git.js";
+import { contextWorkspace, resolveReadRoots } from "./file/paths.js";
 /**
  * Report the current git branch and working-tree status (`git status
  * --porcelain`) for the project root. Read-only — no approval, like read_file
  * and glob.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, it fans every
+ * root — each `getGitStatus(root.absPath)` spawns git with that root as its cwd,
+ * so a section reports exactly the working tree its label names. A non-git root
+ * is NAMED (not fatal), and a `root` argument scopes to one root.
  */
 export const gitStatusTool = {
     name: "git_status",
     description: "Show the current git branch and the working-tree status (porcelain format: ' M file' modified, '?? file' untracked, etc.). Read-only and requires no approval.",
-    parameters: z.object({}),
-    async execute(_input, ctx) {
-        const info = getGitStatus(ctx.cwd);
-        if (info === null) {
+    parameters: z.object({
+        root: z
+            .string()
+            .optional()
+            .describe("In a multi-repo session, restrict the report to a single declared root by name. Omit to report every root."),
+    }),
+    async execute(input, ctx) {
+        const ws = contextWorkspace(ctx);
+        let roots;
+        try {
+            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) {
+            const info = getGitStatus(roots[0].absPath);
+            if (info === null) {
+                return {
+                    ok: false,
+                    error: "not a git repository (or git is unavailable)",
+                };
+            }
+            const body = info.status.trim();
             return {
-                ok: false,
-                error: "not a git repository (or git is unavailable)",
+                ok: true,
+                output: `branch ${info.branch}\n${body === "" ? "working tree clean" : body}`,
             };
         }
-        const body = info.status.trim();
-        return {
-            ok: true,
-            output: `branch ${info.branch}\n${body === "" ? "working tree clean" : body}`,
-        };
+        // Multi-root: one section per root; a non-git root is named, never fatal.
+        const sections = roots.map((root) => {
+            const info = getGitStatus(root.absPath);
+            if (info === null) {
+                return `${root.name}: not a git repository`;
+            }
+            const body = info.status.trim();
+            return `${root.name}: branch ${info.branch}\n${body === "" ? "working tree clean" : body}`;
+        });
+        return { ok: true, output: sections.join("\n\n") };
     },
 };

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 };
     }

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,16 @@ 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. 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`
+     * 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 +187,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

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;

package/dist/vcs/service.js

@@ -1,4 +1,5 @@
-import { usageError } from "../errors/index.js";
+import path from "node:path";
+import { usageError, vcsRemoteChanged } from "../errors/index.js";
 import { commit, currentBranch, diffAgainst, ensureFeatureBranch, hasChanges, isProtectedBranch, push, stageAll, } from "./git.js";
 /** Build a PR service from its dependencies. */
 export function createPrService(deps) {
@@ -8,6 +9,7 @@ export function createPrService(deps) {
 }
 async function openPullRequest(deps, opts) {
     const { cwd, config, forge, generate, requestApproval } = deps;
+    const rootName = deps.rootName ?? path.basename(cwd);
     const protectedExtra = config.git.protectedBranches;
     const branchNow = currentBranch(cwd);
     if (branchNow === null) {
@@ -36,8 +38,14 @@ async function openPullRequest(deps, opts) {
         body: opts.body,
     });
     // ── the one gate: show the whole publish plan before anything mutates ──────────
+    // `repo` is the target parsed from `origin` NOW; it is both shown to the human
+    // (⚖︎JC-4 — root name AND resolved owner/repo) and captured as the approved
+    // target that the wrong-repo guard re-checks before the API call.
     const decision = await requestApproval({
         kind: "vcs",
+        // C.26 Step 4: the acting root, named exactly as the caller selected it — the
+        // checkpoint gate attributes the run's git side effects to this root.
+        root: rootName,
         preview: {
             type: "pr",
             branch: content.branchName,
@@ -46,6 +54,7 @@ async function openPullRequest(deps, opts) {
             commitBody: content.commitBody,
             prTitle: content.prTitle,
             prBody: content.prBody,
+            target: { host: repo.host, owner: repo.owner, repo: repo.repo },
         },
     });
     if (!decision.allow) {
@@ -61,6 +70,18 @@ async function openPullRequest(deps, opts) {
         commit(cwd, content.commitSubject, content.commitBody, protectedExtra);
     }
     push(cwd, head, protectedExtra);
+    // ── wrong-repo guard (⚖︎JC-2 take A): re-resolve the origin identity LOCALLY and
+    // compare it to what the human approved, immediately before the API call. A
+    // concurrent `git remote set-url` on the mutable .git/config would otherwise open
+    // the PR against a repo the user never saw. Mismatch → refuse (never open); we do
+    // NOT re-gate or warn-and-proceed. The tiny window between this re-check and the
+    // HTTP send is an unclosable residual without a lock — named, not chased. (Git
+    // pushed to `origin` by name above; the guarded surface here is the API's
+    // owner/repo target, which is the value the human actually approved.)
+    const current = forge.resolveRepoIdentity(cwd);
+    if (!sameIdentity(repo, current)) {
+        throw vcsRemoteChanged(repo, current, rootName);
+    }
     const pr = await forge.createPullRequest(repo, {
         title: content.prTitle,
         body: content.prBody,
@@ -77,3 +98,14 @@ async function openPullRequest(deps, opts) {
         alreadyExists: pr.alreadyExists,
     };
 }
+/**
+ * Are two forge identities the same repository? Host/owner/repo compared
+ * case-insensitively, because GitHub treats them so — a case-only remote rewrite
+ * is the same repo and must not trip the wrong-repo guard with a false positive.
+ */
+function sameIdentity(a, b) {
+    const norm = (s) => s.toLowerCase();
+    return (norm(a.host) === norm(b.host) &&
+        norm(a.owner) === norm(b.owner) &&
+        norm(a.repo) === norm(b.repo));
+}