@njeybe/nativ 2.7.0 → 2.9.0

package/dist/core/setup/gitignore-block.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { buildDesiredConfig, isObject } from './config-merger.js';
+import { AGENT_FILES, MCP_SERVER_NAME, managedState } from './types.js';
+export const BLOCK_START = '# >>> nativ (managed) >>>';
+export const BLOCK_END = '# <<< nativ (managed) <<<';
+/** Secret and machine-local paths: ignored even when the team shares nativ's files. */
+export const SHARED_PATHS = [
+    '/.nativ/*.local.json',
+    '/.nativ/logs/',
+    '/.nativ/*.log',
+    '/.nativ/notify-state.json',
+    '/.worktrees/',
+];
+const read = (root, rel) => {
+    try {
+        return fs.readFileSync(path.join(root, rel), 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/** Exactly what older nativ versions wrote for CLAUDE.md / GEMINI.md. */
+function isOldPointer(text) {
+    const lf = text.replace(/\r\n/g, '\n');
+    return ['Claude Code', 'Gemini / Antigravity'].some((t) => lf === `# ${t} directive\n\n@AGENTS.md\n`);
+}
+function isNativOwnedFile(text, allowPointer) {
+    if (text === null)
+        return false;
+    if (managedState(text) !== 'unmanaged')
+        return true;
+    return allowPointer && isOldPointer(text);
+}
+const parseObject = (text) => {
+    if (text === null)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return isObject(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** nativ's own server entry, for whatever command setup was configured to use. */
+function ownedServer(entry) {
+    if (!isObject(entry) || typeof entry.command !== 'string')
+        return false;
+    if (Object.keys(entry).some((k) => k !== 'command' && k !== 'args'))
+        return false;
+    const args = entry.args;
+    if (!Array.isArray(args) || args.length === 0 || !args.every((a) => typeof a === 'string'))
+        return false;
+    const invocation = { command: entry.command, prefixArgs: args.slice(0, -1), portable: true };
+    const want = buildDesiredConfig(invocation).mcpServer;
+    return sameJson(entry, { command: want.command, args: want.args });
+}
+function onlyNativMcp(root) {
+    const json = parseObject(read(root, '.mcp.json'));
+    if (!json)
+        return false;
+    const keys = Object.keys(json).filter((k) => k !== 'mcpServers');
+    if (keys.length || !isObject(json.mcpServers))
+        return false;
+    const servers = json.mcpServers;
+    const names = Object.keys(servers);
+    return names.length > 0 && names.every((n) => n === MCP_SERVER_NAME && ownedServer(servers[n]));
+}
+/** CLI strings that setup wrote into hook commands; `nativ` is always a candidate. */
+function clisFromHooks(hooks) {
+    const found = new Set(['nativ']);
+    if (!isObject(hooks))
+        return [...found];
+    for (const groups of Object.values(hooks)) {
+        for (const g of Array.isArray(groups) ? groups : []) {
+            for (const h of isObject(g) && Array.isArray(g.hooks) ? g.hooks : []) {
+                const m = isObject(h) ? /^(.+) hook (check|context)$/.exec(String(h.command)) : null;
+                if (m)
+                    found.add(m[1]);
+            }
+        }
+    }
+    return [...found];
+}
+/** The generated config for an already-rendered CLI string (it may hold spaces or quotes). */
+function desiredFor(cli) {
+    const mark = 'CLIMARK';
+    const text = JSON.stringify(buildDesiredConfig({ command: mark, prefixArgs: [], portable: true }));
+    return JSON.parse(text.split(mark).join(JSON.stringify(cli).slice(1, -1)));
+}
+function ownedHooks(hooks, wants) {
+    if (!isObject(hooks))
+        return false;
+    const groupOk = (event, g) => wants.some((want) => {
+        const w = event === 'PreToolUse' ? want.preToolUse : event === 'SessionStart' ? want.sessionStart : null;
+        const hook = w && { type: 'command', command: w.command, timeout: w.timeout };
+        return w !== null && sameJson(g, { matcher: w.matcher, hooks: [hook] });
+    });
+    return Object.entries(hooks).every(([event, groups]) => Array.isArray(groups) && groups.every((g) => groupOk(event, g)));
+}
+// Setup unions entries, so a file may hold those of an older invocation too.
+function ownedPermissions(perms, wants) {
+    if (!isObject(perms))
+        return false;
+    const keys = ['allow', 'deny', 'ask'];
+    return Object.entries(perms).every(([k, v]) => {
+        const key = keys.find((x) => x === k);
+        return key !== undefined && Array.isArray(v) &&
+            v.every((e) => typeof e === 'string' && wants.some((w) => w[key].includes(e)));
+    });
+}
+function onlyNativSettings(root) {
+    const json = parseObject(read(root, '.claude/settings.json'));
+    if (!json)
+        return false;
+    const allowed = new Set(['permissions', 'hooks', 'enabledMcpjsonServers']);
+    if (Object.keys(json).some((k) => !allowed.has(k)))
+        return false;
+    const wants = clisFromHooks(json.hooks).map(desiredFor);
+    if (json.permissions !== undefined && !ownedPermissions(json.permissions, wants))
+        return false;
+    if (json.hooks !== undefined && !ownedHooks(json.hooks, wants))
+        return false;
+    const enabled = json.enabledMcpjsonServers;
+    return enabled === undefined || (Array.isArray(enabled) && enabled.every((s) => s === MCP_SERVER_NAME));
+}
+/** Root-anchored paths nativ generated in this project, per the git-visibility choice. */
+export function listGeneratedPaths(root, visibility = 'hidden') {
+    if (visibility === 'shared')
+        return [...SHARED_PATHS];
+    const paths = ['/.ai/', '/.nativ/', '/.worktrees/'];
+    for (const file of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+        if (isNativOwnedFile(read(root, file), true))
+            paths.push(`/${file}`);
+    }
+    for (const file of AGENT_FILES) {
+        const rel = `.claude/agents/${file}`;
+        if (isNativOwnedFile(read(root, rel), false))
+            paths.push(`/${rel}`);
+    }
+    if (onlyNativMcp(root))
+        paths.push('/.mcp.json');
+    if (onlyNativSettings(root))
+        paths.push('/.claude/settings.json');
+    return paths;
+}
+export function renderBlock(paths, eol = '\n') {
+    return [BLOCK_START, ...paths, BLOCK_END].join(eol);
+}
+/** Inserts or replaces the managed block; text outside it and its line endings stay as they were. */
+export function applyBlock(existing, paths) {
+    const text = existing ?? '';
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const block = renderBlock(paths, eol);
+    const start = text.indexOf(BLOCK_START);
+    const endAt = start === -1 ? -1 : text.indexOf(BLOCK_END, start);
+    if (start !== -1 && endAt !== -1) {
+        return text.slice(0, start) + block + text.slice(endAt + BLOCK_END.length);
+    }
+    if (text.trim() === '')
+        return block + eol;
+    const sep = text.endsWith('\n') ? eol : eol + eol;
+    return text + sep + block + eol;
+}
+/** Lists generated paths that git already tracks. Non-git folders give an empty list. */
+export function trackedNativPaths(root, paths) {
+    const none = { tracked: [], command: '' };
+    const specs = paths.map((p) => p.replace(/^\//, '')).filter((p) => !p.includes('*'));
+    if (!specs.length)
+        return none;
+    const out = spawnSync('git', ['ls-files', '-z', '--', ...specs], { cwd: root, encoding: 'utf8' });
+    if (out.status !== 0 || !out.stdout)
+        return none;
+    const files = out.stdout.split('\0').filter(Boolean);
+    const tracked = specs.filter((s) => files.some((f) => f === s || f.startsWith(s.endsWith('/') ? s : `${s}/`)));
+    if (!tracked.length)
+        return none;
+    return { tracked, command: `git rm --cached -r -- ${tracked.join(' ')}` };
+}

package/dist/core/setup/pm-playbook.d.ts

@@ -2,4 +2,4 @@
  * The project manager's playbook. The SessionStart hook prints it into the main session only:
  * subagents load CLAUDE.md and AGENTS.md on every turn, so anything kept there is paid for by every worker.
  */
-export declare const PM_PLAYBOOK = "## Working as Project Manager\n\n- Start each session with `nativ task next --json` (or the `nativ_task_next` MCP tool).\n- Delegate, do not implement. Hand each task to the `worker` agent by task id, passing the task's `recommendedModel` (haiku, sonnet or opus) as the Agent tool's `model`; with none, the worker's default applies. Ask the `verifier` agent for an independent check before you mark a milestone done. Ask the `architect` agent for anything that changes a contract.\n- Before the architect designs on existing code, run the `explorer` when `.ai/codebase_map.md` is missing or its commit is well behind `HEAD`, and pass its report to the architect. Give the explorer the current commit (`git rev-parse --short HEAD`); it cannot look it up. Pass `model: haiku` for a single lookup such as \"where is the auth middleware?\".\n- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass `haiku` for mechanical tasks (wording, docs, renames) and `sonnet` for the verifier at the end of a milestone. Never pass a model the human did not choose.\n- Independent tasks can run in parallel in worktrees (`nativ worktree create <taskId>`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.\n- You may not edit `.ai/`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with `nativ task escalate`, do not edit around it.\n- `nativ doctor` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.\n\n## Autonomous execution\n\nWhen told to run autonomously (\"run the queue\", \"execute milestone\", AFK mode):\n1. `nativ_task_next`, then `nativ_task_start`.\n2. Delegate to the `worker` agent with the task id and recommended model.\n3. The worker completes the task itself; `nativ task complete` already ran the check. Do not run `nativ_verify` or `nativ_task_complete` again for it.\n4. Loop to the next task immediately, without asking the human.\n5. Stop only when the milestone is done (ask the `verifier` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).\n\n## Talking to the human\n\nThe human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked `(Recommended)`, then one direct question. Say \"the app tried to link a record to an item that does not exist yet\", not \"foreign key constraint violation\". Never paste stack traces; put raw output in a collapsed `<details>` block.";
+export declare const PM_PLAYBOOK = "## Working as Project Manager\n\n- Start each session with `nativ task next --json` (or the `nativ_task_next` MCP tool).\n- Delegate, do not implement. Hand each task to the `worker` agent by task id, passing the task's `recommendedModel` (haiku, sonnet or opus) as the Agent tool's `model`; with none, the worker's default applies. Ask the `verifier` agent for an independent check before you mark a milestone done. Ask the `architect` agent for anything that changes a contract.\n- Before the architect designs on existing code, run the `explorer` when `.ai/codebase_map.md` is missing or its commit is well behind `HEAD`, and pass its report to the architect. Give the explorer the current commit (`git rev-parse --short HEAD`); it cannot look it up. Pass `model: haiku` for a single lookup such as \"where is the auth middleware?\".\n- Keep usage low. Run this session on Sonnet. Agent defaults: architect Opus, worker Sonnet, verifier Haiku. Pass `haiku` for mechanical tasks (wording, docs, renames) and `sonnet` for the verifier at the end of a milestone. Never pass a model the human did not choose.\n- Independent tasks can run in parallel in worktrees (`nativ worktree create <taskId>`). On a Claude subscription every agent draws from the same usage limit, so run two or three at a time, not ten.\n- You may not edit `.ai/`. If the enforcement hook warns about a file, that is a scope or contract gap: escalate with `nativ task escalate`, do not edit around it.\n- `nativ doctor` confirms the integration is intact. Run it after updating Claude Code or nativ, and whenever hooks or MCP tools seem to be missing.\n\n## Autonomous execution\n\nWhen told to run autonomously (\"run the queue\", \"execute milestone\", AFK mode):\n1. `nativ_task_next`, then `nativ_task_start`.\n2. Delegate to the `worker` agent with the task id and recommended model.\n3. The worker completes the task itself; `nativ task complete` already ran the check. Do not run `nativ_verify` or `nativ_task_complete` again for it.\n4. Loop to the next task immediately, without asking the human.\n5. Stop only when the milestone is done (ask the `verifier` for a milestone check, then tell the human) or when a task is blocked or escalated (present the four-part summary).\n\n## Talking to the human\n\nThe human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked `(Recommended)`, plus one line on when the other option would be the better choice, then one direct question. Say \"the app tried to link a record to an item that does not exist yet\", not \"foreign key constraint violation\". Never paste stack traces; put raw output in a collapsed `<details>` block.";

package/dist/core/setup/pm-playbook.js

@@ -23,4 +23,4 @@ When told to run autonomously ("run the queue", "execute milestone", AFK mode):
 
 ## Talking to the human
 
-The human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked \`(Recommended)\`, then one direct question. Say "the app tried to link a record to an item that does not exist yet", not "foreign key constraint violation". Never paste stack traces; put raw output in a collapsed \`<details>\` block.`;
+The human is the product owner, not a log reader. For a blocker, trade-off or escalation use four parts in plain words: what the user would see; why it happens, as simple cause and effect; what is affected and what is safe; two or three options with the best marked \`(Recommended)\`, plus one line on when the other option would be the better choice, then one direct question. Say "the app tried to link a record to an item that does not exist yet", not "foreign key constraint violation". Never paste stack traces; put raw output in a collapsed \`<details>\` block.`;

package/dist/core/setup/setup-planner.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MCP_SERVER_NAME, AGENT_FILES, resolveCliInvocation, isMachineBoundPath, stampManaged, managedState, } from './types.js';
 import { buildDesiredConfig, mergeClaudeSettings, mergeMcpConfig, isObject, } from './config-merger.js';
+import { applyBlock, listGeneratedPaths, trackedNativPaths } from './gitignore-block.js';
 import { loadEnforcementMode, parseJsonLoose } from '../enforcement.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export function getTemplatesDir() {
@@ -44,6 +45,18 @@ export function configuredInvocation(root) {
         return null;
     }
 }
+/** Disk-derived paths plus files this run creates, in a fixed order so reruns match. */
+function blockPaths(root, visibility, changes) {
+    const disk = listGeneratedPaths(root, visibility);
+    if (visibility === 'shared')
+        return disk;
+    const created = new Set(changes.filter((c) => c.action === 'created').map((c) => `/${c.path}`));
+    const canonical = [
+        '/.ai/', '/.nativ/', '/.worktrees/', '/AGENTS.md', '/CLAUDE.md', '/GEMINI.md',
+        ...AGENT_FILES.map((f) => `/.claude/agents/${f}`), '/.mcp.json', '/.claude/settings.json',
+    ];
+    return canonical.filter((p) => disk.includes(p) || created.has(p));
+}
 /** Computes what `nativ setup` would do, without touching disk. */
 export function planSetup(rootArg, options = {}) {
     const root = path.resolve(rootArg);
@@ -55,6 +68,7 @@ export function planSetup(rootArg, options = {}) {
     const changes = [];
     const warnings = [];
     const writes = new Map();
+    let visibility = options.gitVisibility ?? 'hidden';
     if (!invocation.portable) {
         warnings.push('nativ is not on PATH, so the generated config points at this machine\'s install. ' +
             'Install it globally (npm i -g @njeybe/nativ) or pass --command "npx -y @njeybe/nativ" so the config works for your team.');
@@ -143,7 +157,7 @@ export function planSetup(rootArg, options = {}) {
     for (const [file, title] of [['CLAUDE.md', 'Claude Code'], ['GEMINI.md', 'Gemini / Antigravity']]) {
         const existing = readText(path.join(root, file));
         if (existing === null)
-            record(file, null, `# ${title} directive\n\n@AGENTS.md\n`);
+            record(file, null, stampManaged(`# ${title} directive\n\n@AGENTS.md\n`));
         else
             changes.push({ path: file, action: 'unchanged', detail: /AGENTS\.md/.test(existing) ? undefined : 'exists; does not reference AGENTS.md' });
     }
@@ -160,9 +174,21 @@ export function planSetup(rootArg, options = {}) {
             next.enforcement = loadEnforcementMode(root);
             detail = `enforcement=${String(next.enforcement)}`;
         }
+        if (options.gitVisibility && next.gitVisibility !== options.gitVisibility) {
+            next.gitVisibility = options.gitVisibility;
+            detail = [detail, `gitVisibility=${options.gitVisibility}`].filter(Boolean).join(', ');
+        }
         record('.nativ/config.json', config.text, detail || config.text === null ? serializeJson(next) : (config.text ?? ''), detail);
+        visibility = options.gitVisibility ?? (next.gitVisibility === 'shared' ? 'shared' : 'hidden');
     }
-    return { root, invocation, changes, warnings, writes };
+    // .gitignore: the managed block, from what is on disk plus what this run creates
+    const paths = blockPaths(root, visibility, changes);
+    const ignore = readText(path.join(root, '.gitignore'));
+    record('.gitignore', ignore, applyBlock(ignore, paths), 'nativ block');
+    const gitRmCommand = trackedNativPaths(root, paths).command;
+    if (gitRmCommand)
+        warnings.push(`nativ files are already tracked by git. To stop tracking them, run: ${gitRmCommand}`);
+    return { root, invocation, changes, warnings, writes, gitRmCommand: gitRmCommand || undefined };
 }
 /** Writes the planned differences. Idempotent: applying twice changes nothing the second time. */
 export function applySetup(rootArg, options = {}) {
@@ -176,5 +202,12 @@ export function applySetup(rootArg, options = {}) {
             fs.renameSync(tmp, file);
         }
     }
-    return { root: plan.root, dryRun: options.dryRun === true, invocation: plan.invocation, changes: plan.changes, warnings: plan.warnings };
+    return {
+        root: plan.root,
+        dryRun: options.dryRun === true,
+        invocation: plan.invocation,
+        changes: plan.changes,
+        warnings: plan.warnings,
+        gitRmCommand: plan.gitRmCommand,
+    };
 }

package/dist/core/setup/types.d.ts

@@ -1,4 +1,5 @@
 import type { EnforcementMode } from '../enforcement.js';
+import type { GitVisibility } from './gitignore-block.js';
 export declare const MCP_SERVER_NAME = "nativ";
 export declare const AGENT_FILES: readonly ["architect.md", "worker.md", "verifier.md", "explorer.md"];
 export declare const MANAGED_PREFIX = "<!-- nativ:managed sha256=";
@@ -27,6 +28,8 @@ export interface SetupOptions {
     enforcement?: EnforcementMode;
     /** Also overwrite agent files that were edited by hand or are not nativ's. */
     force?: boolean;
+    /** Whether nativ's files stay out of git (hidden, the default) or are shared with the team. */
+    gitVisibility?: GitVisibility;
     hasBinary?: (name: string) => boolean;
     templatesDir?: string;
 }
@@ -37,6 +40,8 @@ export interface SetupPlan {
     warnings: string[];
     /** Full new content per changed path, keyed by the same relative path. */
     writes: Map<string, string>;
+    /** `git rm --cached` command for nativ files git already tracks; never run by nativ. */
+    gitRmCommand?: string;
 }
 export interface SetupResult {
     root: string;
@@ -44,6 +49,7 @@ export interface SetupResult {
     invocation: CliInvocation;
     changes: AssetChange[];
     warnings: string[];
+    gitRmCommand?: string;
 }
 export interface TemplateFilePlan {
     action: AssetAction;

package/dist/core/verifier/clean-tree.d.ts

@@ -0,0 +1,14 @@
+export declare const CLEAN_TREE_PREFIX = "nativ-verify-";
+export type CleanTree = {
+    ok: true;
+    dir: string;
+    dispose: () => Promise<void>;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function disposeTree(root: string, dir: string, names: string[], unlink?: (dir: string, name: string) => boolean): Promise<void>;
+export declare function createCleanTree(root: string, opts?: {
+    links?: string[];
+}): Promise<CleanTree>;
+export declare function sweepStaleCleanTrees(root: string): Promise<number>;

package/dist/core/verifier/clean-tree.js

@@ -0,0 +1,151 @@
+import { execFile } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { linkWorktreeDir, safeUnlinkWorktreeDir } from '../root-resolver.js';
+export const CLEAN_TREE_PREFIX = 'nativ-verify-';
+const STALE_MS = 60 * 60 * 1000;
+function git(cwd, args) {
+    const opts = { cwd, maxBuffer: 64 * 1024 * 1024, windowsHide: true };
+    return new Promise((resolve) => {
+        execFile('git', args, opts, (err, stdout) => {
+            const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+            resolve({ code, out: String(stdout ?? '') });
+        });
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function removeDir(dir) {
+    for (let i = 0; i < 6; i++) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            if (!fs.existsSync(dir))
+                return;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'EBUSY' && code !== 'EPERM' && code !== 'ENOTEMPTY')
+                return;
+        }
+        await sleep(150 * (i + 1));
+    }
+}
+// Links go first: removing a tree can follow a junction into the real folder.
+function linkRemains(dir, names) {
+    return names.some((n) => {
+        try {
+            return fs.lstatSync(path.join(dir, n)).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+// unlink is injectable so tests can simulate a link that refuses to go away.
+export async function disposeTree(root, dir, names, unlink = safeUnlinkWorktreeDir) {
+    try {
+        for (const n of names)
+            unlink(dir, n);
+        // A surviving link means a recursive delete could reach the real folder: leave it for the sweep.
+        if (linkRemains(dir, names))
+            return;
+        for (let i = 0; i < 4; i++) {
+            const r = await git(root, ['worktree', 'remove', '--force', dir]);
+            if (r.code === 0 || !fs.existsSync(dir))
+                break;
+            await sleep(150 * (i + 1));
+        }
+        await removeDir(dir);
+        await git(root, ['worktree', 'prune']);
+    }
+    catch {
+        // Cleanup never throws.
+    }
+}
+async function copyUntracked(root, dir) {
+    const r = await git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    for (const rel of r.out.split('\0').filter(Boolean)) {
+        const from = path.join(root, rel);
+        const to = path.join(dir, rel);
+        try {
+            if (!fs.statSync(from).isFile())
+                continue;
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(from, to);
+        }
+        catch {
+            // A file that vanished mid-copy is not worth failing the tree.
+        }
+    }
+}
+export async function createCleanTree(root, opts = {}) {
+    const inRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
+    if (inRepo.code !== 0)
+        return { ok: false, reason: 'clean isolation needs a git repository' };
+    const head = await git(root, ['rev-parse', '--verify', 'HEAD']);
+    if (head.code !== 0)
+        return { ok: false, reason: 'clean isolation needs at least one commit' };
+    const stash = await git(root, ['stash', 'create']);
+    const commit = stash.code === 0 && stash.out.trim() ? stash.out.trim() : head.out.trim();
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), CLEAN_TREE_PREFIX));
+    fs.rmdirSync(dir);
+    const args = ['-c', 'core.autocrlf=false', 'worktree', 'add', '--detach', dir, commit];
+    const add = await git(root, args);
+    if (add.code !== 0) {
+        await removeDir(dir);
+        return { ok: false, reason: 'could not create the clean tree' };
+    }
+    await copyUntracked(root, dir);
+    const linked = (opts.links ?? []).filter((n) => linkWorktreeDir(dir, root, n));
+    return { ok: true, dir, dispose: () => disposeTree(root, dir, linked) };
+}
+function ownedBy(root, dir) {
+    try {
+        const text = fs.readFileSync(path.join(dir, '.git'), 'utf8');
+        const gitdir = text.replace(/^gitdir:\s*/, '').trim();
+        const main = realOf(path.resolve(root, '.git')).toLowerCase();
+        return realOf(path.resolve(gitdir)).toLowerCase().startsWith(main);
+    }
+    catch {
+        return false;
+    }
+}
+// Real paths make Windows short (8.3) and aliased paths compare equal.
+function realOf(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+function linkNames(dir) {
+    return fs.readdirSync(dir).filter((n) => fs.lstatSync(path.join(dir, n)).isSymbolicLink());
+}
+export async function sweepStaleCleanTrees(root) {
+    let removed = 0;
+    try {
+        const tmp = os.tmpdir();
+        for (const name of fs.readdirSync(tmp)) {
+            if (!name.startsWith(CLEAN_TREE_PREFIX))
+                continue;
+            const dir = path.join(tmp, name);
+            try {
+                if (Date.now() - fs.statSync(dir).mtimeMs < STALE_MS)
+                    continue;
+                if (!ownedBy(root, dir))
+                    continue;
+                await disposeTree(root, dir, linkNames(dir));
+                if (!fs.existsSync(dir))
+                    removed++;
+            }
+            catch {
+                // Skip entries we cannot read.
+            }
+        }
+    }
+    catch {
+        // Nothing to sweep.
+    }
+    return removed;
+}

package/dist/core/verifier/executor.d.ts

@@ -2,4 +2,6 @@ import type { VerificationResult } from './types.js';
 /**
  * Execute a verification command in the workspace directory with timeout and output capture.
  */
-export declare function executeVerification(command: string, cwd: string, timeoutMs?: number): Promise<VerificationResult>;
+export declare function executeVerification(command: string, cwd: string, timeoutMs?: number, options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<VerificationResult>;

package/dist/core/verifier/executor.js

@@ -1,8 +1,9 @@
-import { exec } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
+const MAX_OUTPUT = 10 * 1024 * 1024;
 /**
  * Execute a verification command in the workspace directory with timeout and output capture.
  */
-export async function executeVerification(command, cwd, timeoutMs = 120_000) {
+export async function executeVerification(command, cwd, timeoutMs = 120_000, options = {}) {
     const trimmed = (command || '').trim();
     // Treat empty, 'none', or 'skip' as an informational pass
     if (!trimmed || trimmed.toLowerCase() === 'none' || trimmed.toLowerCase() === 'skip') {
@@ -26,37 +27,59 @@ export async function executeVerification(command, cwd, timeoutMs = 120_000) {
     }
     const start = Date.now();
     return new Promise((resolve) => {
-        exec(finalCommand, {
+        let timedOut = false;
+        let out = '';
+        let errOut = '';
+        const child = spawn(finalCommand, {
             cwd,
-            timeout: timeoutMs,
-            maxBuffer: 10 * 1024 * 1024,
-            env: process.env,
-        }, (err, stdout, stderr) => {
+            shell: true,
+            env: options.env ?? { ...process.env, NATIV_VERIFY_SANDBOX: '1' },
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+        });
+        const cap = (cur, chunk) => cur.length < MAX_OUTPUT ? cur + chunk.toString() : cur;
+        child.stdout?.on('data', (c) => (out = cap(out, c)));
+        child.stderr?.on('data', (c) => (errOut = cap(errOut, c)));
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+        }, timeoutMs);
+        const finish = (code, message) => {
+            clearTimeout(timer);
             const durationMs = Date.now() - start;
-            const out = (stdout || '').toString();
-            const errOut = (stderr || '').toString();
-            if (err) {
-                const exitCode = typeof err.code === 'number' ? err.code : 1;
-                resolve({
-                    success: false,
-                    exitCode,
-                    command: trimmed,
-                    stdout: out,
-                    stderr: errOut || err.message,
-                    durationMs,
-                    error: err.killed ? `Command timed out after ${timeoutMs}ms` : err.message,
-                });
-            }
-            else {
-                resolve({
-                    success: true,
-                    exitCode: 0,
-                    command: trimmed,
-                    stdout: out,
-                    stderr: errOut,
-                    durationMs,
-                });
+            if (code === 0 && !message && !timedOut) {
+                resolve({ success: true, exitCode: 0, command: trimmed, stdout: out, stderr: errOut, durationMs });
+                return;
             }
-        });
+            const error = timedOut
+                ? `Command timed out after ${timeoutMs}ms`
+                : message ?? `Command failed: ${trimmed}`;
+            resolve({
+                success: false,
+                exitCode: typeof code === 'number' && code !== 0 ? code : 1,
+                command: trimmed,
+                stdout: out,
+                stderr: errOut || error,
+                durationMs,
+                error,
+            });
+        };
+        child.on('error', (e) => finish(null, e.message));
+        child.on('close', (code) => finish(code));
     });
 }
+/** Kills the process and all its descendants. */
+function killTree(pid) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        execFile('taskkill', ['/pid', String(pid), '/T', '/F'], () => { });
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // Group already gone
+    }
+}

package/dist/core/verifier/isolation.d.ts

@@ -0,0 +1,25 @@
+import { MasterPlanTask } from '../../scanner/types.js';
+import type { PhasesOutcome, VerificationResult } from './types.js';
+/** Where a verification runs: the real tree, or a disposable clean copy. */
+export interface IsolationPlan {
+    mode: 'none' | 'clean';
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+    warnings: string[];
+    dispose?: () => Promise<void>;
+}
+export declare const NO_ISOLATION: IsolationPlan;
+export declare function needsRun(commands: string[], configDir: string, sharedPhases: boolean): boolean;
+export declare function openIsolation(cwd: string, configDir: string, wanted: 'none' | 'clean'): Promise<IsolationPlan>;
+/** Like runVerifyPhases, but with an explicit environment for each phase. */
+export declare function runPhasesIn(dir: string, configDir: string, timeout: number | undefined, env?: NodeJS.ProcessEnv): Promise<PhasesOutcome>;
+export interface RunOptions {
+    cwd: string;
+    configDir?: string;
+    timeout?: number;
+    phases?: PhasesOutcome;
+    isolation?: 'none' | 'clean';
+    plan?: IsolationPlan;
+}
+export declare function runInPlan(task: MasterPlanTask, o: RunOptions, plan: IsolationPlan): Promise<VerificationResult>;
+export declare function diagnose(task: MasterPlanTask, o: RunOptions, failed: VerificationResult, failure: 'warn' | 'block'): Promise<VerificationResult>;