agent-nuvira 3.3.1 → 3.3.4

package/dist/tools/worktree.d.ts

@@ -0,0 +1,210 @@
+/**
+ * WS5 (#27) — a turn's own git worktree, and the diff it leaves behind.
+ *
+ * WHY A WORKTREE AT ALL. The ask is "try this and show me what changed". Running
+ * that in the operator's own tree makes the answer inseparable from the damage: a
+ * turn that edits twelve files to test one hypothesis has changed the tree the
+ * operator is working in, and the only record of it is whatever they notice. A
+ * second checkout of the SAME repository (a `git worktree`) gives the turn a real
+ * tree — same code, same test runner, same `node_modules` — that can be thrown
+ * away, and turns "what changed" into a diff against the commit it started from.
+ *
+ * WHY THE BASE IS `HEAD`, AND WHY THE NOTICE SAYS SO. `git worktree add … HEAD`
+ * checks out a commit, so UNCOMMITTED work in the operator's tree is not visible
+ * inside the copy. That is a real trap — a run that "did not see my edit" — so the
+ * number of dirty files in the source tree is MEASURED at creation and reported,
+ * rather than left to be discovered. A clean tree reports nothing.
+ *
+ * WHY IT REFUSES INSTEAD OF DEGRADING. Not every directory can be isolated: not a
+ * repository, no commit yet, no `git` at all. The tempting behaviour — run in the
+ * real tree and report the turn normally — is the one outcome this feature exists
+ * to prevent, because the caller acts on a diff that describes a tree nobody ran
+ * in. So isolation either happens or the turn STOPS, and the refusal says why.
+ *
+ * WHY THE DIFF IS MEASURED BEFORE TEARDOWN. Removing the worktree is what
+ * destroys the evidence, so the order is not a detail: measure, then remove. A
+ * teardown that fails (a git lock, a file handle) is reported as "not removed"
+ * rather than assumed, since the directory is left in the operator's profile with
+ * a branch pointing at it.
+ *
+ * GIT'S OWN STDOUT IS KEPT SEPARATE FROM THE MESSAGE. One helper here returns a
+ * never-empty `out` (git printing nothing is a fact worth a sentence), and a
+ * second field `raw` holding exactly what git wrote. Counting or parsing `out` is
+ * how a PRISTINE repository came to be reported as having one uncommitted change:
+ * `git status --porcelain` prints nothing, the fallback sentence has one line, and
+ * the count was taken from the sentence (see TOOL_TRUTHFULNESS_TRACKER).
+ */
+/** The environment key a deployment asks for isolation through. */
+export declare const WORKTREE_ENABLE_ENV = "NUVIRA_ISOLATE";
+/** The environment keys a forked child reads to learn which worktree it is in. */
+export declare const WORKTREE_DIR_ENV = "NUVIRA_WORKTREE_DIR";
+export declare const WORKTREE_BASE_ENV = "NUVIRA_WORKTREE_BASE";
+/** How long `git worktree add` may take — a big repository is still a checkout. */
+export declare const WORKTREE_CREATE_TIMEOUT_MS = 20000;
+/** Bound on one file's diff body, so a huge change cannot be handed over whole. */
+export declare const WORKTREE_PATCH_CHARS = 120000;
+/** ─── Requests ─────────────────────────────────────────────────────────────── */
+/**
+ * What an isolation request resolved to.
+ *
+ * Exactly two fields, and no more: the parity suite asserts the shape of a
+ * default request (`{asked: false, keep: false}`), so a third field added here
+ * would be a silent change to a documented value. `asked` and `keep` are kept
+ * apart because asking to be isolated and asking to KEEP the result are separate
+ * decisions, and a plain `--worktree` must not leave a directory behind.
+ */
+export interface IsolationRequest {
+    asked: boolean;
+    keep: boolean;
+}
+/**
+ * Resolve an isolation request from a caller's options, with the environment as
+ * the fallback — not the other way round.
+ *
+ * `undefined` means "nobody said anything", and only then does `NUVIRA_ISOLATE`
+ * decide. An explicit `false` is a DECISION (a surface that offers an off switch
+ * must be able to turn a deployment's `NUVIRA_ISOLATE=1` off for one turn), and
+ * it outranks the environment. This is the distinction a commander-style `false`
+ * default destroys: with one, every CLI turn carries an explicit decline and the
+ * documented `NUVIRA_ISOLATE=1` is unreachable from the command line.
+ */
+export declare function resolveIsolationRequest(input: {
+    worktree?: boolean;
+    keepWorktree?: boolean;
+}): IsolationRequest;
+/**
+ * Why `repoCwd` cannot be isolated, or null when it can.
+ *
+ * Shared by the refusal path and by the parity harness, which uses it to assert
+ * that the checkout it is about to drive CAN be isolated — a harness that
+ * silently proved nothing because it ran somewhere unisolatable would be worse
+ * than a failure.
+ */
+export declare function worktreeRefusal(repoCwd: string): string | null;
+/** The refusal, as the operator reads it. A failure, not a degradation. */
+export declare function isolationRefusalText(why: string): string;
+/** ─── The worktree ─────────────────────────────────────────────────────────── */
+/** A live worktree: where it is, and the commit everything is measured against. */
+export interface IsolatedWorktree {
+    /** The checkout the turn runs in. */
+    dir: string;
+    /** The commit the diff is against (full sha). */
+    base: string;
+    /** The branch the worktree is checked out on, created with it. */
+    branch: string;
+    /** The repository it was created from. */
+    repoCwd: string;
+    /** Uncommitted paths in the SOURCE tree, which the copy cannot see. */
+    sourceDirty: number;
+}
+/**
+ * Make a worktree of `repoCwd`, or return null when that is impossible.
+ *
+ * `node_modules` is LINKED rather than installed: a worktree has no dependencies
+ * of its own, and an isolated turn that could not run a test would measure
+ * nothing. The link is best-effort — a filesystem that cannot symlink still gets
+ * an isolated tree, just one without dependencies.
+ */
+export declare function createIsolatedWorktree(input: {
+    repoCwd: string;
+    label: string;
+    timeoutMs?: number;
+}): IsolatedWorktree | null;
+/** ─── The diff ─────────────────────────────────────────────────────────────── */
+/**
+ * What an isolated turn changed.
+ *
+ * NOTE THE TWO HALVES OF `diff`, because they are not the same list and reading
+ * the wrong one renders an empty card: `files` is the changed PATHS (one string
+ * per file — what a reader scans), and `payload.files[].body` is the unified diff
+ * of each. `payload` deliberately has the shape the `git:diff` event already
+ * carries, so an isolated change renders with the diff card that is already
+ * there instead of a second renderer that could drift from it.
+ */
+export interface WorktreeDiff {
+    /** Changed paths, sorted as git reports them. */
+    files: string[];
+    summary: string;
+    /** True when the run changed nothing — a fact, not a failure. */
+    unchanged: boolean;
+    payload: {
+        files: Array<{
+            path: string;
+            body: string;
+        }>;
+        summary: string;
+    };
+}
+/**
+ * Measure the diff against the worktree's base commit.
+ *
+ * UNTRACKED FILES COUNT, and that is why the index is staged first: a run that
+ * CREATES a file has changed the tree, and `git diff` alone would report nothing
+ * for it. Staging inside a worktree that is about to be thrown away is free, and
+ * a worktree that is KEPT has its new files staged — which is what `git diff
+ * --cached` reads on the next measurement.
+ */
+export declare function worktreeDiff(handle: IsolatedWorktree, opts?: {
+    timeoutMs?: number;
+}): WorktreeDiff;
+/**
+ * Remove a worktree and the branch that was made with it.
+ *
+ * Returns whether the directory is GONE, not whether git was happy: a removal
+ * that succeeded but left the directory (a file handle, a lock) has still left a
+ * directory in the operator's profile, and "removed: true" is the claim the
+ * console prints.
+ */
+export declare function discardWorktree(handle: IsolatedWorktree, opts?: {
+    timeoutMs?: number;
+}): boolean;
+/** ─── Lifecycle ────────────────────────────────────────────────────────────── */
+/** A started isolation: the worktree, or the refusal that replaced it. */
+export type IsolationStart = {
+    ok: true;
+    worktree: IsolatedWorktree;
+} | {
+    ok: false;
+    refusal: string;
+};
+/**
+ * Start isolation for a turn, or return null when nobody asked for one.
+ *
+ * Null and a refusal are different answers and both are load-bearing: null means
+ * the turn runs where it always did, and a refusal means the turn DOES NOT RUN.
+ */
+export declare function beginIsolation(input: {
+    request: IsolationRequest;
+    repoCwd: string;
+    label: string;
+}): IsolationStart | null;
+/** The environment a forked child reads, so a tool can say where it is running. */
+export declare function worktreeEnv(handle: IsolatedWorktree): Record<string, string>;
+/**
+ * Where the turn is running, said when it starts.
+ *
+ * The base commit is named as a commit AND as a branch, and the dirty count is
+ * reported when it is non-zero — the two facts that decide whether the diff at
+ * the end describes what the operator expected.
+ */
+export declare function worktreeNotice(handle: IsolatedWorktree): string;
+/** What the turn changed, what happened to the directory, and the diff itself. */
+export interface IsolationOutcome {
+    dir: string;
+    base: string;
+    diff: WorktreeDiff;
+    /** False when the directory was KEPT (`--keep-worktree`). */
+    removed: boolean;
+    /** The operator-facing line (see `worktreeNotice` / this module's `notice`). */
+    notice: string;
+}
+/**
+ * Finish isolation: measure the diff, then tear the worktree down (unless kept).
+ *
+ * Never throws — the caller attaches this to the turn's own result, and a git
+ * error must not replace an answer with a message about a directory.
+ */
+export declare function endIsolation(handle: IsolatedWorktree, opts: {
+    keep: boolean;
+}): IsolationOutcome;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/tools/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AASH,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AACtD,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AACxD,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,mFAAmF;AACnF,eAAO,MAAM,oBAAoB,SAAU,CAAC;AAE5C,mFAAmF;AAEnF;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,gBAAgB,CAMnB;AAoED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS9D;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,mFAAmF;AAEnF,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAoBD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,gBAAgB,GAAG,IAAI,CA0C1B;AAED,mFAAmF;AAEnF;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE;QACP,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAChC,YAAY,CA0Bd;AASD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CA0BpG;AAED,mFAAmF;AAEnF,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,cAAc,GAAG,IAAI,CAUxB;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK5E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAW/D;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,CAqBhG"}

package/dist/tools/worktree.js

@@ -0,0 +1,374 @@
+/**
+ * WS5 (#27) — a turn's own git worktree, and the diff it leaves behind.
+ *
+ * WHY A WORKTREE AT ALL. The ask is "try this and show me what changed". Running
+ * that in the operator's own tree makes the answer inseparable from the damage: a
+ * turn that edits twelve files to test one hypothesis has changed the tree the
+ * operator is working in, and the only record of it is whatever they notice. A
+ * second checkout of the SAME repository (a `git worktree`) gives the turn a real
+ * tree — same code, same test runner, same `node_modules` — that can be thrown
+ * away, and turns "what changed" into a diff against the commit it started from.
+ *
+ * WHY THE BASE IS `HEAD`, AND WHY THE NOTICE SAYS SO. `git worktree add … HEAD`
+ * checks out a commit, so UNCOMMITTED work in the operator's tree is not visible
+ * inside the copy. That is a real trap — a run that "did not see my edit" — so the
+ * number of dirty files in the source tree is MEASURED at creation and reported,
+ * rather than left to be discovered. A clean tree reports nothing.
+ *
+ * WHY IT REFUSES INSTEAD OF DEGRADING. Not every directory can be isolated: not a
+ * repository, no commit yet, no `git` at all. The tempting behaviour — run in the
+ * real tree and report the turn normally — is the one outcome this feature exists
+ * to prevent, because the caller acts on a diff that describes a tree nobody ran
+ * in. So isolation either happens or the turn STOPS, and the refusal says why.
+ *
+ * WHY THE DIFF IS MEASURED BEFORE TEARDOWN. Removing the worktree is what
+ * destroys the evidence, so the order is not a detail: measure, then remove. A
+ * teardown that fails (a git lock, a file handle) is reported as "not removed"
+ * rather than assumed, since the directory is left in the operator's profile with
+ * a branch pointing at it.
+ *
+ * GIT'S OWN STDOUT IS KEPT SEPARATE FROM THE MESSAGE. One helper here returns a
+ * never-empty `out` (git printing nothing is a fact worth a sentence), and a
+ * second field `raw` holding exactly what git wrote. Counting or parsing `out` is
+ * how a PRISTINE repository came to be reported as having one uncommitted change:
+ * `git status --porcelain` prints nothing, the fallback sentence has one line, and
+ * the count was taken from the sentence (see TOOL_TRUTHFULNESS_TRACKER).
+ */
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, rmSync, symlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+/** The environment key a deployment asks for isolation through. */
+export const WORKTREE_ENABLE_ENV = 'NUVIRA_ISOLATE';
+/** The environment keys a forked child reads to learn which worktree it is in. */
+export const WORKTREE_DIR_ENV = 'NUVIRA_WORKTREE_DIR';
+export const WORKTREE_BASE_ENV = 'NUVIRA_WORKTREE_BASE';
+/** How long `git worktree add` may take — a big repository is still a checkout. */
+export const WORKTREE_CREATE_TIMEOUT_MS = 20_000;
+/** Bound on one file's diff body, so a huge change cannot be handed over whole. */
+export const WORKTREE_PATCH_CHARS = 120_000;
+/**
+ * Resolve an isolation request from a caller's options, with the environment as
+ * the fallback — not the other way round.
+ *
+ * `undefined` means "nobody said anything", and only then does `NUVIRA_ISOLATE`
+ * decide. An explicit `false` is a DECISION (a surface that offers an off switch
+ * must be able to turn a deployment's `NUVIRA_ISOLATE=1` off for one turn), and
+ * it outranks the environment. This is the distinction a commander-style `false`
+ * default destroys: with one, every CLI turn carries an explicit decline and the
+ * documented `NUVIRA_ISOLATE=1` is unreachable from the command line.
+ */
+export function resolveIsolationRequest(input) {
+    const asked = input.worktree === undefined ? envAsks(WORKTREE_ENABLE_ENV) : input.worktree === true;
+    // `keep` is only meaningful when isolation was asked for; a lever with nothing
+    // to keep would otherwise read as a request in its own right.
+    const keep = asked && input.keepWorktree === true;
+    return { asked, keep };
+}
+/** True when an environment key asks for something (`1`/`true`/`yes`). */
+function envAsks(name) {
+    const raw = envBuff(name.replace(/^NUVIRA_/, ''));
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+}
+function gitRun(dir, args, timeoutMs = WORKTREE_CREATE_TIMEOUT_MS) {
+    try {
+        const r = spawnSync('git', args, {
+            cwd: dir,
+            encoding: 'utf-8',
+            timeout: timeoutMs,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        const raw = (r.stdout ?? '').trim();
+        return {
+            ok: r.status === 0,
+            raw,
+            out: raw || 'git reported no output',
+            err: (r.stderr ?? '').trim(),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, raw: '', out: 'git reported no output', err: message };
+    }
+}
+/**
+ * Files with uncommitted work in `dir`, counted from git's OWN output.
+ *
+ * Counts LINES of `raw`: `git status --porcelain` prints one line per changed or
+ * untracked path, and prints NOTHING for a clean tree — which must count as zero,
+ * not as the one line of a fallback sentence.
+ */
+function dirtyCount(dir) {
+    const status = gitRun(dir, ['status', '--porcelain'], 5_000);
+    if (!status.ok)
+        return 0;
+    return status.raw.split('\n').filter((line) => line.trim() !== '').length;
+}
+/** The commit a turn would start from, or null when there is none. */
+function headOf(dir) {
+    const head = gitRun(dir, ['rev-parse', 'HEAD'], 5_000);
+    const sha = head.raw.trim();
+    return head.ok && /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
+}
+/**
+ * Why `repoCwd` cannot be isolated, or null when it can.
+ *
+ * Shared by the refusal path and by the parity harness, which uses it to assert
+ * that the checkout it is about to drive CAN be isolated — a harness that
+ * silently proved nothing because it ran somewhere unisolatable would be worse
+ * than a failure.
+ */
+export function worktreeRefusal(repoCwd) {
+    const inside = gitRun(repoCwd, ['rev-parse', '--is-inside-work-tree'], 5_000);
+    if (!inside.ok || inside.raw.trim() !== 'true') {
+        return `'${repoCwd}' is not inside a git work tree (git is unavailable, or this is not a repository)`;
+    }
+    if (!headOf(repoCwd)) {
+        return `'${repoCwd}' has no commit to start from — an isolated copy is a checkout of HEAD`;
+    }
+    return null;
+}
+/** The refusal, as the operator reads it. A failure, not a degradation. */
+export function isolationRefusalText(why) {
+    return (`Isolation was requested, but this turn cannot be isolated: ${why}.\n` +
+        'Nothing ran — no model was called and no file was touched.');
+}
+/** Where worktrees live (`~/.nuvira/worktrees`, overridable for tests/CI). */
+function worktreesRoot() {
+    return envBuff('WORKTREES_DIR') || join(resolveNuviraHome(), 'worktrees');
+}
+/** A filesystem- and branch-safe name for this turn, from its label. */
+function worktreeName(label) {
+    const slug = label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32)
+        .replace(/-+$/g, '');
+    const stamp = randomBytes(4).toString('hex').slice(0, 6);
+    const salt = randomBytes(2).toString('hex').slice(0, 4);
+    return `${slug || 'turn'}-${stamp}-${salt}`;
+}
+/**
+ * Make a worktree of `repoCwd`, or return null when that is impossible.
+ *
+ * `node_modules` is LINKED rather than installed: a worktree has no dependencies
+ * of its own, and an isolated turn that could not run a test would measure
+ * nothing. The link is best-effort — a filesystem that cannot symlink still gets
+ * an isolated tree, just one without dependencies.
+ */
+export function createIsolatedWorktree(input) {
+    if (worktreeRefusal(input.repoCwd) !== null)
+        return null;
+    const base = headOf(input.repoCwd);
+    if (!base)
+        return null;
+    const name = worktreeName(input.label);
+    const dir = join(worktreesRoot(), name);
+    const branch = `nuvira/${name}`;
+    try {
+        mkdirSync(worktreesRoot(), { recursive: true });
+    }
+    catch {
+        return null;
+    }
+    const added = gitRun(input.repoCwd, ['worktree', 'add', '-b', branch, dir, 'HEAD'], input.timeoutMs ?? WORKTREE_CREATE_TIMEOUT_MS);
+    if (!added.ok) {
+        // Leave nothing behind: a half-made worktree registers with the parent repo
+        // even when the checkout failed.
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            gitRun(input.repoCwd, ['worktree', 'prune'], 5_000);
+        }
+        catch {
+            /* best-effort */
+        }
+        return null;
+    }
+    const sourceModules = join(input.repoCwd, 'node_modules');
+    const linkedModules = join(dir, 'node_modules');
+    if (existsSync(sourceModules) && !existsSync(linkedModules)) {
+        try {
+            symlinkSync(sourceModules, linkedModules, 'dir');
+        }
+        catch {
+            /* a filesystem that cannot link still gets an isolated tree */
+        }
+    }
+    return { dir, base, branch, repoCwd: input.repoCwd, sourceDirty: dirtyCount(input.repoCwd) };
+}
+/** Split git's own unified diff into one body per file, keyed by path. */
+function payloadOf(patch, files) {
+    const sections = patch.split(/^diff --git /m).filter((section) => section.trim() !== '');
+    const byPath = new Map();
+    for (const section of sections) {
+        // `a/<path> b/<path>` — the path with a space in it is why this reads the
+        // `b/` side rather than splitting the line on whitespace.
+        const match = section.match(/^a\/(.+?) b\//);
+        if (!match)
+            continue;
+        byPath.set(match[1], `diff --git ${section}`.slice(0, WORKTREE_PATCH_CHARS));
+    }
+    return files.map((path) => ({ path, body: byPath.get(path) ?? '' }));
+}
+/**
+ * The pathspec that keeps the linked `node_modules` out of a measurement.
+ *
+ * The repository's own ignore rule is `node_modules/`, which matches a DIRECTORY —
+ * and what a worktree gets is a SYMLINK, which that rule does not match at all. So
+ * a run that changed one file reported two, the second being the dependency link
+ * this module created itself. Excluded by pathspec rather than by writing an
+ * ignore file into the worktree, because the ignore file is the repository's.
+ */
+const MEASURE_SCOPE = ['.', ':(exclude)node_modules'];
+/**
+ * Measure the diff against the worktree's base commit.
+ *
+ * UNTRACKED FILES COUNT, and that is why the index is staged first: a run that
+ * CREATES a file has changed the tree, and `git diff` alone would report nothing
+ * for it. Staging inside a worktree that is about to be thrown away is free, and
+ * a worktree that is KEPT has its new files staged — which is what `git diff
+ * --cached` reads on the next measurement.
+ */
+export function worktreeDiff(handle, opts = {}) {
+    const timeout = opts.timeoutMs ?? WORKTREE_CREATE_TIMEOUT_MS;
+    gitRun(handle.dir, ['add', '-A', '--', ...MEASURE_SCOPE], timeout);
+    const names = gitRun(handle.dir, ['diff', '--cached', '--name-only', handle.base, '--', ...MEASURE_SCOPE], timeout);
+    const files = names.ok
+        ? names.raw.split('\n').map((line) => line.trim()).filter((line) => line !== '')
+        : [];
+    const short = handle.base.slice(0, 7);
+    const summary = files.length === 0
+        ? `nothing changed against ${short}`
+        : `${files.length} file${files.length === 1 ? '' : 's'} changed against ${short}`;
+    const patch = gitRun(handle.dir, ['diff', '--cached', handle.base, '--', ...MEASURE_SCOPE], timeout);
+    return {
+        files,
+        summary,
+        unchanged: files.length === 0,
+        payload: { files: payloadOf(patch.ok ? patch.raw : '', files), summary },
+    };
+}
+/** The honest "nothing is known yet" diff, for a measurement that failed. */
+function unmeasuredDiff(base) {
+    const short = base.slice(0, 7);
+    const summary = `the diff against ${short} could not be measured`;
+    return { files: [], summary, unchanged: false, payload: { files: [], summary } };
+}
+/**
+ * Remove a worktree and the branch that was made with it.
+ *
+ * Returns whether the directory is GONE, not whether git was happy: a removal
+ * that succeeded but left the directory (a file handle, a lock) has still left a
+ * directory in the operator's profile, and "removed: true" is the claim the
+ * console prints.
+ */
+export function discardWorktree(handle, opts = {}) {
+    const timeout = opts.timeoutMs ?? WORKTREE_CREATE_TIMEOUT_MS;
+    let gitSaid = false;
+    try {
+        gitSaid = gitRun(handle.repoCwd, ['worktree', 'remove', '--force', handle.dir], timeout).ok;
+    }
+    catch {
+        gitSaid = false;
+    }
+    if (existsSync(handle.dir)) {
+        try {
+            rmSync(handle.dir, { recursive: true, force: true });
+        }
+        catch {
+            /* fall through — the directory decides */
+        }
+    }
+    try {
+        if (!existsSync(handle.dir))
+            gitRun(handle.repoCwd, ['branch', '-D', handle.branch], 5_000);
+        gitRun(handle.repoCwd, ['worktree', 'prune'], 5_000);
+    }
+    catch {
+        /* best-effort */
+    }
+    return gitSaid || !existsSync(handle.dir);
+}
+/**
+ * Start isolation for a turn, or return null when nobody asked for one.
+ *
+ * Null and a refusal are different answers and both are load-bearing: null means
+ * the turn runs where it always did, and a refusal means the turn DOES NOT RUN.
+ */
+export function beginIsolation(input) {
+    if (!input.request.asked)
+        return null;
+    const why = worktreeRefusal(input.repoCwd);
+    if (why)
+        return { ok: false, refusal: isolationRefusalText(why) };
+    const worktree = createIsolatedWorktree({ repoCwd: input.repoCwd, label: input.label });
+    if (!worktree) {
+        const reason = worktreeRefusal(input.repoCwd) ?? 'the worktree could not be created';
+        return { ok: false, refusal: isolationRefusalText(reason) };
+    }
+    return { ok: true, worktree };
+}
+/** The environment a forked child reads, so a tool can say where it is running. */
+export function worktreeEnv(handle) {
+    return {
+        [WORKTREE_DIR_ENV]: handle.dir,
+        [WORKTREE_BASE_ENV]: handle.base,
+    };
+}
+/**
+ * Where the turn is running, said when it starts.
+ *
+ * The base commit is named as a commit AND as a branch, and the dirty count is
+ * reported when it is non-zero — the two facts that decide whether the diff at
+ * the end describes what the operator expected.
+ */
+export function worktreeNotice(handle) {
+    const lines = [
+        `🌿 isolated in a git worktree: ${handle.dir}`,
+        `   base: ${handle.base.slice(0, 7)} (branch ${handle.branch})`,
+    ];
+    if (handle.sourceDirty > 0) {
+        lines.push(`   note: ${handle.sourceDirty} uncommitted change(s) in the source tree are NOT in this worktree`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Finish isolation: measure the diff, then tear the worktree down (unless kept).
+ *
+ * Never throws — the caller attaches this to the turn's own result, and a git
+ * error must not replace an answer with a message about a directory.
+ */
+export function endIsolation(handle, opts) {
+    let diff;
+    try {
+        diff = worktreeDiff(handle);
+    }
+    catch {
+        diff = unmeasuredDiff(handle.base);
+    }
+    let removed = false;
+    if (!opts.keep) {
+        try {
+            removed = discardWorktree(handle);
+        }
+        catch {
+            removed = false;
+        }
+    }
+    const lines = [`   ${diff.summary}`];
+    for (const file of diff.files)
+        lines.push(`   · ${file}`);
+    if (opts.keep)
+        lines.push(`   (kept: ${handle.dir} — nothing was removed)`);
+    else if (removed)
+        lines.push('   (the worktree was removed — the diff above is what is left of it)');
+    else
+        lines.push(`   (the worktree could NOT be removed: ${handle.dir})`);
+    return { dir: handle.dir, base: handle.base, diff, removed, notice: lines.join('\n') };
+}
+//# sourceMappingURL=worktree.js.map

package/dist/tools/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../../src/tools/worktree.ts"],"names":[],"mappings":"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"}

package/dist/utils/format.d.ts

@@ -0,0 +1,3 @@
+/** Format a count for display: `1048576` → `1,048,576`, on every machine. */
+export declare function formatCount(n: number): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AA4BA,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C"}

package/dist/utils/format.js

@@ -0,0 +1,32 @@
+/**
+ * Number formatting with a PINNED locale.
+ *
+ * WHY THIS EXISTS. `n.toLocaleString()` follows the machine's default locale, so
+ * one build printed `1,048,576` on an en-US box, `10,48,576` on en-IN and
+ * `1.048.576` on de-DE. That is wrong twice over:
+ *
+ *   1. A count in a report, a log line, or a bug report is a FACT, and it must
+ *      read the same on every machine.
+ *   2. A locale-dependent value cannot be asserted deterministically. The
+ *      dashboard chip suite and the long-form progress suite passed in CI and
+ *      failed on a developer machine for exactly this reason, and de-DE renders a
+ *      word count as `35.000`, which reads as a decimal rather than as 35,000.
+ *
+ * THE CONVENTION. Every user-visible number goes through {@link formatCount}.
+ * This is the same choice the codebase already made in the places it pinned a
+ * locale by hand (`toLocaleString('en-US')`, `toLocaleDateString('en-US', …)`) —
+ * it is now made once, here, instead of at each call site.
+ *
+ * SCOPE. Numbers only. Dates still vary by machine in the sites that do not pass
+ * a locale; that is a separate decision and is deliberately not covered here.
+ *
+ * The locale is `en-US` because the grouping is unambiguous: it separates every
+ * three digits and never uses a character (a dot, a space, a narrow no-break
+ * space) that another locale would read as a decimal point.
+ */
+const EN_US = new Intl.NumberFormat('en-US');
+/** Format a count for display: `1048576` → `1,048,576`, on every machine. */
+export function formatCount(n) {
+    return EN_US.format(n);
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC"}