@cursor/july 0.1.68 → 0.1.73

package/dist/internal/shallow-clone.js

@@ -12,7 +12,38 @@ import { mkdirSync, rmSync } from "node:fs";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 /**
- * Default clone credential: the serve host's Cursor-account GitHub lease.
+ * Resolve a PR URL to its clone target, or `undefined` when the SCM has no
+ * shallow-clone support (callers then review on their fallback checkout —
+ * e.g. Origin PRs, where the host checkout already is the reviewed repo).
+ */
+export function resolveScmCloneTarget(prUrl) {
+    let url;
+    try {
+        url = new URL(prUrl);
+    }
+    catch (_a) {
+        return undefined;
+    }
+    const parts = url.pathname.split("/").filter(Boolean);
+    if (url.hostname === "github.com" &&
+        parts.length >= 4 &&
+        parts[2] === "pull" &&
+        Number.isInteger(Number(parts[3]))) {
+        const repo = `${parts[0]}/${parts[1]}`;
+        const prNumber = Number(parts[3]);
+        return {
+            provider: "github",
+            repo,
+            prNumber,
+            remoteUrl: `https://github.com/${repo}.git`,
+            credentialUsername: "x-access-token",
+            prHeadRef: `refs/pull/${prNumber}/head`,
+        };
+    }
+    return undefined;
+}
+/**
+ * Default GitHub clone credential: the serve host's Cursor-account lease.
  * `CursorGithubCredentialProvider` mints it repo-scoped from the backend and
  * keeps `GH_TOKEN` refreshed for child processes; `GITHUB_TOKEN` covers
  * local/CI runs that export the conventional variable instead.
@@ -22,6 +53,107 @@ export function serveHostGithubAuth(env = process.env) {
     const token = ((_b = (_a = env.GH_TOKEN) !== null && _a !== void 0 ? _a : env.GITHUB_TOKEN) !== null && _b !== void 0 ? _b : "").trim();
     return token === "" ? undefined : { token };
 }
+/** Pair the provider's git-over-HTTPS username with the bearer token. */
+function cloneCredential(target, auth) {
+    return auth === undefined
+        ? undefined
+        : { username: target.credentialUsername, token: auth.token };
+}
+/** Default clone credential source per provider. */
+function defaultCloneAuth(target) {
+    switch (target.provider) {
+        case "github":
+            return serveHostGithubAuth();
+    }
+}
+/** Cap on diff text handed to a model; beyond this it is truncated. */
+const DIFF_MAX_CHARS = 80000;
+/**
+ * Diff two commits inside an existing shallow PR checkout, fetching either
+ * end on demand when the shallow history does not already contain it.
+ *
+ * Lives here because it needs the same authenticated git the clone uses —
+ * a `--depth=1` checkout usually lacks the older commit, so reading a range
+ * means another credentialed fetch. Never throws: every failure becomes an
+ * `unavailable` reason the caller can act on or surface.
+ */
+export function tryDiffCommitRange(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (!isFullCommitSha(args.from) || !isFullCommitSha(args.to)) {
+            return {
+                status: "unavailable",
+                reason: "Could not compute a reliable diff because a commit SHA was not a full 40-character SHA.",
+            };
+        }
+        const credential = cloneCredential(args.target, (_a = args.auth) !== null && _a !== void 0 ? _a : defaultCloneAuth(args.target));
+        for (const sha of [args.from, args.to]) {
+            if (!(yield ensureCommitFetched(args.checkoutDir, sha, args.target, credential))) {
+                return {
+                    status: "unavailable",
+                    reason: "Could not compute a reliable diff because a commit was unavailable in the checkout.",
+                };
+            }
+        }
+        try {
+            const diff = yield git(args.checkoutDir, [
+                "diff",
+                "--no-ext-diff",
+                "--unified=80",
+                `${args.from}..${args.to}`,
+                ...(args.file === undefined ? [] : ["--", args.file]),
+            ]);
+            return {
+                status: "ok",
+                diff: diff.length <= DIFF_MAX_CHARS
+                    ? diff
+                    : `${diff.slice(0, DIFF_MAX_CHARS)}\n\n[diff truncated at ${DIFF_MAX_CHARS} characters]`,
+            };
+        }
+        catch (_b) {
+            return {
+                status: "unavailable",
+                reason: "Could not compute a reliable diff because git diff failed.",
+            };
+        }
+    });
+}
+function isFullCommitSha(value) {
+    return /^[0-9a-f]{40}$/i.test(value);
+}
+/** Present already, or fetchable by SHA, or reachable from the PR head ref. */
+function ensureCommitFetched(checkoutDir, sha, target, credential) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if ((yield revParse(checkoutDir, sha)) !== undefined) {
+            return true;
+        }
+        const attempts = [
+            [...FETCH_ARGS, sha],
+            // Deeper history on the PR head ref: the older end of an inter-run range
+            // is usually an ancestor of the tip rather than the tip itself.
+            [
+                "fetch",
+                "--depth=200",
+                "--no-tags",
+                "--quiet",
+                "origin",
+                target.prHeadRef,
+            ],
+        ];
+        for (const attempt of attempts) {
+            try {
+                yield git(checkoutDir, attempt, credential);
+                if ((yield revParse(checkoutDir, sha)) !== undefined) {
+                    return true;
+                }
+            }
+            catch (_a) {
+                // Try the next strategy; the caller fails closed if none work.
+            }
+        }
+        return false;
+    });
+}
 function logShallowClone(message, fields = {}) {
     const suffix = Object.entries(fields)
         .filter(([, value]) => value !== undefined)
@@ -55,12 +187,12 @@ function gitError(args, error) {
     return new Error(`git ${args.join(" ")} failed — ${detail}`);
 }
 /**
- * The one credential helper git may use: serve the caller-provided token
- * from the child process env at request time. The shell reads
- * `$SHALLOW_CLONE_GIT_TOKEN` when git asks, keeping the token out of argv.
+ * The one credential helper git may use: serve the caller-provided
+ * credential from the child process env at request time. The shell reads
+ * the values when git asks, keeping the token out of argv.
  */
-const TOKEN_CREDENTIAL_HELPER = '!f() { test "$1" = get && printf "username=x-access-token\\npassword=$SHALLOW_CLONE_GIT_TOKEN\\n"; }; f';
-function git(cwd, args, auth) {
+const CREDENTIAL_HELPER = '!f() { test "$1" = get && printf "username=$SHALLOW_CLONE_GIT_USERNAME\\npassword=$SHALLOW_CLONE_GIT_TOKEN\\n"; }; f';
+function git(cwd, args, credential) {
     return __awaiter(this, void 0, void 0, function* () {
         // Async on purpose: fetches/checkouts of large repos take minutes, and the
         // serve host runs the clone in-process. A synchronous git call blocks the
@@ -68,9 +200,9 @@ function git(cwd, args, auth) {
         // long enough for the platform's probe budget to replace the engine.
         try {
             const { stdout } = yield execFileAsync("git", [
-                ...(auth === undefined
+                ...(credential === undefined
                     ? []
-                    : ["-c", `credential.helper=${TOKEN_CREDENTIAL_HELPER}`]),
+                    : ["-c", `credential.helper=${CREDENTIAL_HELPER}`]),
                 ...args,
             ], {
                 cwd,
@@ -82,9 +214,12 @@ function git(cwd, args, auth) {
                     // .com/.insteadOf` entries scoped to a *different* repo, as cloud
                     // VMs bake in) cannot hijack auth away from the explicit token,
                     // and no ambient credential helpers run against PR-author input.
-                    GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null", GIT_TERMINAL_PROMPT: "0" }), (auth === undefined
+                    GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_SYSTEM: "/dev/null", GIT_TERMINAL_PROMPT: "0" }), (credential === undefined
                     ? {}
-                    : { SHALLOW_CLONE_GIT_TOKEN: auth.token })),
+                    : {
+                        SHALLOW_CLONE_GIT_USERNAME: credential.username,
+                        SHALLOW_CLONE_GIT_TOKEN: credential.token,
+                    })),
             });
             return stdout;
         }
@@ -105,14 +240,16 @@ function revParse(cwd, rev) {
     });
 }
 const FETCH_ARGS = ["fetch", "--depth=1", "--no-tags", "--quiet", "origin"];
+/** Local tracking ref the PR head ref is fetched into. */
+const LOCAL_PR_HEAD_REF = "refs/remotes/origin/shallow-clone-pr-head";
 /**
- * Create a fresh shallow checkout of a GitHub PR head at `checkoutDir`.
+ * Create a fresh shallow checkout of a PR head at `checkoutDir`.
  *
  * Fetch order (both single depth-1 round-trips):
  * 1. Fetch `headSha` (and `baseSha` when known) directly — GitHub advertises
  *    `allow-reachable-sha1-in-want`, and this pins the exact reviewed commit
  *    the way Bugbot's `shallow_fetch` does.
- * 2. Fall back to `refs/pull/<n>/head`, verifying it still resolves to
+ * 2. Fall back to the target's PR head ref, verifying it still resolves to
  *    `headSha` so the working tree cannot silently drift from the pinned
  *    patch in the review bundle.
  *
@@ -121,23 +258,19 @@ const FETCH_ARGS = ["fetch", "--depth=1", "--no-tags", "--quiet", "origin"];
  */
 export function createShallowPrCheckout(args) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
-        const { repo, prNumber, headSha, baseSha, checkoutDir, auth } = args;
+        const { target, headSha, baseSha, checkoutDir, auth } = args;
+        const { repo, prNumber } = target;
+        const credential = cloneCredential(target, auth);
         const startedAt = Date.now();
         logShallowClone("cloning PR head", { repo, prNumber, headSha, baseSha });
         rmSync(checkoutDir, { recursive: true, force: true });
         mkdirSync(checkoutDir, { recursive: true });
         yield git(checkoutDir, ["init", "--quiet"]);
-        yield git(checkoutDir, [
-            "remote",
-            "add",
-            "origin",
-            (_a = args.remoteUrl) !== null && _a !== void 0 ? _a : `https://github.com/${repo}.git`,
-        ]);
+        yield git(checkoutDir, ["remote", "add", "origin", target.remoteUrl]);
         const shaFetch = () => __awaiter(this, void 0, void 0, function* () {
             const extraBase = baseSha === undefined || baseSha === headSha ? [] : [baseSha];
             try {
-                yield git(checkoutDir, [...FETCH_ARGS, headSha, ...extraBase], auth);
+                yield git(checkoutDir, [...FETCH_ARGS, headSha, ...extraBase], credential);
             }
             catch (error) {
                 if (extraBase.length === 0) {
@@ -151,29 +284,24 @@ export function createShallowPrCheckout(args) {
                     baseSha,
                     error: errorSummary(error),
                 });
-                yield git(checkoutDir, [...FETCH_ARGS, headSha], auth);
+                yield git(checkoutDir, [...FETCH_ARGS, headSha], credential);
             }
         });
         let headSource;
-        let shaFetchError;
         try {
             yield shaFetch();
             headSource = "sha_fetch";
         }
         catch (error) {
-            shaFetchError = errorSummary(error);
-            if (prNumber === undefined) {
-                throw new Error(`Shallow SHA fetch failed for ${repo}@${headSha} and no PR number is available for a ref fallback: ${shaFetchError}`);
-            }
+            const shaFetchError = errorSummary(error);
             logShallowClone("sha fetch failed; falling back to PR head ref", {
                 repo,
                 prNumber,
                 headSha,
                 error: shaFetchError,
             });
-            const prRef = `refs/pull/${prNumber}/head`;
-            yield git(checkoutDir, [...FETCH_ARGS, `+${prRef}:refs/remotes/origin/pr/${prNumber}/head`], auth);
-            const fetchedSha = yield revParse(checkoutDir, `refs/remotes/origin/pr/${prNumber}/head`);
+            yield git(checkoutDir, [...FETCH_ARGS, `+${target.prHeadRef}:${LOCAL_PR_HEAD_REF}`], credential);
+            const fetchedSha = yield revParse(checkoutDir, LOCAL_PR_HEAD_REF);
             if (fetchedSha !== headSha) {
                 throw new Error(`Shallow PR ref fetch for ${repo}#${prNumber} resolved to ${fetchedSha !== null && fetchedSha !== void 0 ? fetchedSha : "nothing"}, expected pinned head ${headSha} (sha fetch error: ${shaFetchError})`);
             }
@@ -194,7 +322,7 @@ export function createShallowPrCheckout(args) {
             // Best-effort: local diffs are nice-to-have, the pinned patch in the
             // prompt is the authoritative delta either way.
             try {
-                yield git(checkoutDir, [...FETCH_ARGS, baseSha], auth);
+                yield git(checkoutDir, [...FETCH_ARGS, baseSha], credential);
                 baseFetched = (yield revParse(checkoutDir, baseSha)) !== undefined;
             }
             catch (error) {
@@ -218,71 +346,63 @@ export function createShallowPrCheckout(args) {
         return { checkoutDir, headSha, baseFetched, headSource };
     });
 }
-/** True for `https://github.com/<owner>/<repo>/pull/<n>` URLs. */
-export function isGithubPrUrl(prUrl) {
-    try {
-        const url = new URL(prUrl);
-        const parts = url.pathname.split("/").filter(Boolean);
-        return (url.hostname === "github.com" &&
-            parts.length >= 4 &&
-            parts[2] === "pull" &&
-            Number.isInteger(Number(parts[3])));
-    }
-    catch (_a) {
-        return false;
-    }
-}
 /**
  * Best-effort shallow PR checkout for hosts whose SDK agents should read the
  * reviewed repo instead of the host's own checkout.
  *
  * Returns no checkout — leaving the caller on its fallback working
- * directory — when the PR is not on GitHub (e.g. Origin PRs, where the host
- * checkout is the reviewed repo), when no head SHA is pinned, when no clone
- * credential is available, or when the clone fails; `fallbackReason` says
- * which. Failures are logged, never thrown: agents still have the pinned
- * patch in their prompts, so a missing checkout degrades quality rather
- * than the run.
+ * directory — when the PR's SCM has no clone support (e.g. Origin PRs,
+ * where the host checkout is the reviewed repo), when no head SHA is
+ * pinned, when no clone credential is available, or when the clone fails;
+ * `fallbackReason` says which. Failures are logged, never thrown: agents
+ * still have the pinned patch in their prompts, so a missing checkout
+ * degrades quality rather than the run.
  */
 export function tryCreateShallowPrCheckout(options) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a;
-        const { prUrl, repo, prNumber, headSha, baseSha, checkoutDir, remoteUrl } = options;
-        if (remoteUrl === undefined && !isGithubPrUrl(prUrl)) {
-            logShallowClone("skipped: not a GitHub PR URL", { prUrl });
-            return { fallbackReason: "skipped: not a GitHub PR URL" };
+        var _a, _b;
+        const { prUrl, headSha, baseSha, checkoutDir } = options;
+        const target = (_a = options.target) !== null && _a !== void 0 ? _a : resolveScmCloneTarget(prUrl);
+        if (target === undefined) {
+            logShallowClone("skipped: unsupported SCM for shallow clone", { prUrl });
+            return { fallbackReason: "skipped: unsupported SCM for shallow clone" };
         }
         if (headSha === undefined) {
-            logShallowClone("skipped: no pinned head SHA", { repo, prUrl });
+            logShallowClone("skipped: no pinned head SHA", {
+                repo: target.repo,
+                prUrl,
+            });
             return { fallbackReason: "skipped: no pinned head SHA" };
         }
-        const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : serveHostGithubAuth();
-        if (remoteUrl === undefined && auth === undefined) {
-            // Fail fast instead of letting an unauthenticated fetch 404/hang: real
-            // GitHub clones need the serve host's lease (or an explicit token).
-            logShallowClone("skipped: no GitHub clone credential", { repo, prUrl });
+        const auth = (_b = options.auth) !== null && _b !== void 0 ? _b : defaultCloneAuth(target);
+        if (auth === undefined && target.remoteUrl.startsWith("https://")) {
+            // Fail fast instead of letting an unauthenticated fetch 404/hang: HTTPS
+            // clones need the provider's credential (or an explicit token).
+            logShallowClone("skipped: no clone credential", {
+                repo: target.repo,
+                provider: target.provider,
+                prUrl,
+            });
             return {
-                fallbackReason: "skipped: no GitHub clone credential (serve host GH_TOKEN lease not installed)",
+                fallbackReason: `skipped: no ${target.provider} clone credential (serve host token lease not installed)`,
             };
         }
         try {
             return {
                 checkout: yield createShallowPrCheckout({
-                    repo,
-                    prNumber,
+                    target,
                     headSha,
                     baseSha,
                     checkoutDir,
                     auth,
-                    remoteUrl,
                 }),
             };
         }
         catch (error) {
             const reason = errorSummary(error);
             logShallowClone("failed; caller falls back to host checkout", {
-                repo,
-                prNumber,
+                repo: target.repo,
+                prNumber: target.prNumber,
                 headSha,
                 error: reason,
             });

package/dist/internal/terminal-style.d.ts

@@ -17,6 +17,24 @@ export declare function makePalette(enabled: boolean): TerminalPalette;
 export declare function stdoutPalette(): TerminalPalette;
 /** Palette for human-facing stderr (login progress, warnings). */
 export declare function stderrPalette(): TerminalPalette;
+/** Visible column count, ignoring CSI color/style and OSC 8 hyperlinks. */
+export declare function visibleWidth(text: string): number;
+/** True when `text` already carries CSI styling or OSC 8 (do not wrap again). */
+export declare function hasAnsiStyling(text: string): boolean;
+/**
+ * Clickable terminal hyperlink (OSC 8). The URI is the click target; `label`
+ * is what the user sees. `visibleWidth` ignores the OSC wrapper.
+ */
+export declare function terminalHyperlink(url: string, label: string, enabled?: boolean): string;
+/**
+ * Unicode box around `lines`. `color` wraps the whole box (borders + body)
+ * so a warning panel can be yellow without per-line prefixes.
+ */
+export declare function formatTerminalBox(lines: readonly string[], options?: {
+    color?: (s: string) => string;
+    minWidth?: number;
+    padding?: number;
+}): string;
 /** Wipe the terminal before a `dev` Enter-to-restart cycle. */
 export declare function clearTerminal(stream?: NodeJS.WriteStream): void;
 //# sourceMappingURL=terminal-style.d.ts.map

package/dist/internal/terminal-style.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-style.d.ts","sourceRoot":"","sources":["../../src/internal/terminal-style.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAcD,wBAAgB,eAAe,CAC7B,MAAM,GAAE,MAAM,CAAC,WAA4B,GAC1C,OAAO,CAET;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAiB7D;AAED,oEAAoE;AACpE,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAC3B,MAAM,GAAE,MAAM,CAAC,WAA4B,GAC1C,IAAI,CAMN"}
+{"version":3,"file":"terminal-style.d.ts","sourceRoot":"","sources":["../../src/internal/terminal-style.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/B;AAsBD,wBAAgB,eAAe,CAC7B,MAAM,GAAE,MAAM,CAAC,WAA4B,GAC1C,OAAO,CAET;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAiB7D;AAED,oEAAoE;AACpE,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,kEAAkE;AAClE,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,OAA2B,GACnC,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,MAAM,CAoBR;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAC3B,MAAM,GAAE,MAAM,CAAC,WAA4B,GAC1C,IAAI,CAMN"}

package/dist/internal/terminal-style.js

@@ -4,6 +4,11 @@
  */
 import { clearScreenDown, cursorTo } from "node:readline";
 const IDENTITY = (s) => s;
+const ESC = "\u001b";
+const BEL = "\u0007";
+const ANSI_CSI = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+/** OSC 8 hyperlinks: `ESC ] 8 ; params ; uri BEL` (or ST). */
+const OSC_8 = new RegExp(`${ESC}\\]8;[^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "g");
 const PLAIN = {
     dim: IDENTITY,
     bold: IDENTITY,
@@ -22,7 +27,7 @@ export function makePalette(enabled) {
     }
     const wrap = (code) => (s) => `\u001b[${code}m${s}\u001b[0m`;
     return {
-        dim: wrap("2"),
+        dim: (s) => (hasAnsiStyling(s) ? s : wrap("2")(s)),
         bold: wrap("1"),
         cyan: wrap("36"),
         green: wrap("32"),
@@ -39,6 +44,46 @@ export function stdoutPalette() {
 export function stderrPalette() {
     return makePalette(colorEnabledFor(process.stderr));
 }
+/** Visible column count, ignoring CSI color/style and OSC 8 hyperlinks. */
+export function visibleWidth(text) {
+    return text.replace(OSC_8, "").replace(ANSI_CSI, "").length;
+}
+/** True when `text` already carries CSI styling or OSC 8 (do not wrap again). */
+export function hasAnsiStyling(text) {
+    return text.includes("\u001b[") || text.includes("\u001b]");
+}
+/**
+ * Clickable terminal hyperlink (OSC 8). The URI is the click target; `label`
+ * is what the user sees. `visibleWidth` ignores the OSC wrapper.
+ */
+export function terminalHyperlink(url, label, enabled = colorEnabledFor()) {
+    if (!enabled) {
+        return label;
+    }
+    return `\u001b]8;;${url}\u0007\u001b[4m${label}\u001b[24m\u001b]8;;\u0007`;
+}
+/**
+ * Unicode box around `lines`. `color` wraps the whole box (borders + body)
+ * so a warning panel can be yellow without per-line prefixes.
+ */
+export function formatTerminalBox(lines, options) {
+    var _a, _b, _c;
+    const color = (_a = options === null || options === void 0 ? void 0 : options.color) !== null && _a !== void 0 ? _a : IDENTITY;
+    const padding = (_b = options === null || options === void 0 ? void 0 : options.padding) !== null && _b !== void 0 ? _b : 1;
+    const contentWidth = Math.max((_c = options === null || options === void 0 ? void 0 : options.minWidth) !== null && _c !== void 0 ? _c : 0, ...lines.map((line) => visibleWidth(line)), 1);
+    const inner = contentWidth + padding * 2;
+    const padLine = (line) => {
+        const extra = contentWidth - visibleWidth(line);
+        return `│${" ".repeat(padding)}${line}${" ".repeat(padding + extra)}│`;
+    };
+    const paint = (line) => color(line);
+    const box = [
+        paint(`╭${"─".repeat(inner)}╮`),
+        ...lines.map((line) => paint(padLine(line))),
+        paint(`╰${"─".repeat(inner)}╯`),
+    ].join("\n");
+    return box;
+}
 /** Wipe the terminal before a `dev` Enter-to-restart cycle. */
 export function clearTerminal(stream = process.stdout) {
     if (stream.isTTY !== true) {

package/dist/internal/workspace.d.ts

@@ -99,6 +99,8 @@ export declare function buildAgentsMdContent(agent: ResolvedAgent, options: {
  * are skipped by nested rule discovery.
  */
 export declare function isNestedInGitRepo(dir: string): Promise<boolean>;
+/** Default harness parent for a nested-git agent project. */
+export declare function defaultLocalHarnessCwd(dirName: string): string;
 /**
  * Give a session workspace its own git root so the harness roots *there*
  * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA8CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUpE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CACX,MAAM,EACN,MAAM,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CACjE,GACA,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/internal/workspace.js

@@ -17,6 +17,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { execFile } from "node:child_process";
 import { chmod, copyFile, lstat, mkdir, readlink, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join, parse, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
@@ -222,6 +223,10 @@ export function isNestedInGitRepo(dir) {
         return false;
     });
 }
+/** Default harness parent for a nested-git agent project. */
+export function defaultLocalHarnessCwd(dirName) {
+    return join(homedir(), ".cache", "agent-serve", dirName);
+}
 /**
  * Give a session workspace its own git root so the harness roots *there*
  * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without