agy-mcp-bridge 0.1.19 → 0.1.21

package/config/workspaces.example.json

@@ -13,5 +13,9 @@
   "agents": {
     "priority": ["antigravity", "codex"],
     "enabled": ["antigravity", "codex"]
+  },
+  "tree_watch": {
+    "enabled": true,
+    "delays_ms": [500, 1000, 2000, 4000, 10000]
   }
 }

package/dist/src/agents/antigravity.js

@@ -58,6 +58,6 @@ export function legacyAntigravityAgent(runtime, transport) {
         version: null, executable: runtime.executable || null, capabilities: CAPABILITIES,
         warnings: runtime.supported ? [] : ['Requires agy 1.4.x and all required print/output/timeout flags']
     };
-    return { adapter: antigravityAdapter(runtime.executable, transport), status, enabled: true, launch: runtime.launch };
+    return { adapter: antigravityAdapter(runtime.executable, transport), status, enabled: true, prefixArgs: runtime.prefixArgs, launch: runtime.launch };
 }
 //# sourceMappingURL=antigravity.js.map

package/dist/src/agents/registry.js

@@ -23,7 +23,7 @@ export async function createAgentRegistry(config, antigravity) {
     };
     agents.push({
         adapter: antigravityAdapter(antigravity.executable, config.prompt_transport),
-        status: antigravityStatus, enabled: antigravityEnabled
+        status: antigravityStatus, enabled: antigravityEnabled, prefixArgs: antigravity.prefixArgs
     });
     const codexEnabled = enabled.includes('codex');
     let codexStatus = {

package/dist/src/antigravity/process.js

@@ -129,9 +129,11 @@ async function terminate(child) {
         }
     }
 }
-export async function inspectCli(executable, cwd, run = startProcess, requireStdin = false) {
+/** Probes a resolved command. The whole command goes in, not just its executable: a Windows shim runs as
+ * `node <script>` and asking `node --version` would report Node's version instead of the CLI's. */
+export async function inspectCli(command, cwd, run = startProcess, requireStdin = false) {
     const capture = (args) => new Promise((resolve, reject) => {
-        const child = run(executable, args, cwd);
+        const child = run(command.executable, [...command.prefixArgs, ...args], cwd);
         let text = '';
         let exceeded = false;
         const timer = setTimeout(() => { exceeded = true; void terminateOwned(child).catch(reject); }, 10000);
@@ -150,6 +152,6 @@ export async function inspectCli(executable, cwd, run = startProcess, requireStd
         ['--print', '--output-format', '--print-timeout', '--disable-slash-commands', ...(requireStdin ? ['--input-format'] : [])].every(flag => new RegExp(`(?:^|\\s)${flag}(?=\\s|$)`).test(help.text));
     const verified = VERIFIED_AGY_VERSIONS.includes(actual);
     const warnings = supported && !verified ? [`agy ${actual} is compatible by 1.4.x version/help checks, but only ${VERIFIED_AGY_VERSIONS.join(' and ')} have been verified with real agent execution`] : [];
-    return { version: actual, supported, executable, warnings };
+    return { version: actual, supported, executable: command.executable, prefixArgs: command.prefixArgs, warnings };
 }
 //# sourceMappingURL=process.js.map

package/dist/src/config.js

@@ -19,6 +19,15 @@ const schema = z.object({
     max_parallel_worktrees: z.number().int().min(1).max(8).optional(),
     default_autonomy: z.enum(['suggest', 'auto', 'full']).optional(),
     agents: agentsSchema.optional(),
+    /**
+     * The process-tree watcher that runs while a task is live. One poll costs a full process-table query (about half a
+     * second on the reference machine), so the cadence is owner-tunable and the whole watch can be turned off; without
+     * it, a subtree whose intermediate shell exited before the agent did becomes invisible to the release.
+     */
+    tree_watch: z.object({
+        enabled: z.boolean().optional(),
+        delays_ms: z.array(z.number().int().min(100).max(60000)).min(1).max(20).optional()
+    }).strict().optional(),
     extra_env_passthrough: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).max(100).default([]),
     prompt_transport: z.enum(['stdin', 'argv']).default('argv'),
     /** Longest single antigravity_task_wait call (default 55). Keep it below the MCP client's tool timeout. */

package/dist/src/isolation/orphans.js

@@ -0,0 +1,281 @@
+import { spawn } from 'node:child_process';
+import { TERMINATION_GRACE_MS } from '../antigravity/process.js';
+/**
+ * OS singletons that must never be reaped even if a recycled pid claims them as children of our exited agent.
+ * `cmd.exe` and `powershell.exe` are absent on purpose: they are genuine members of a real agent tree.
+ */
+export const PROTECTED_IMAGES = [
+    'system', 'registry', 'smss.exe', 'csrss.exe', 'wininit.exe', 'winlogon.exe', 'services.exe', 'lsass.exe',
+    'svchost.exe', 'fontdrvhost.exe', 'dwm.exe', 'explorer.exe', 'taskhostw.exe', 'sihost.exe', 'ctfmon.exe'
+];
+/** Clock granularity plus scheduling slack, so a child started microseconds before the recorded start is still ours. */
+const CREATION_SLACK_MS = 5000;
+/** Pure so the safety rules are testable without touching the process table. */
+export function reapGuard(child, guard, protectedImages = PROTECTED_IMAGES) {
+    if (!Number.isInteger(child.pid) || child.pid <= 1)
+        return 'pid is not a reapable process id';
+    if (child.pid === (guard.self_pid ?? process.pid))
+        return 'pid is this bridge process';
+    const name = child.name.toLowerCase();
+    if (protectedImages.includes(name))
+        return `${child.name} is a protected system process`;
+    if (child.created_ms !== null && child.created_ms < guard.started_at_ms - CREATION_SLACK_MS)
+        return 'process existed before this task started';
+    return null;
+}
+function powershell(command, timeout = 8000) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+        let text = '';
+        const timer = setTimeout(() => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* already gone */ } }, timeout);
+        child.stdout.on('data', (data) => { if (text.length < 262144)
+            text += data.toString('utf8'); });
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', () => { clearTimeout(timer); resolve(text); });
+    });
+}
+/**
+ * Tab-separated so a name containing spaces cannot be mis-split. The whole process table is cheaper than one
+ * query per pid, and CommandLine is left out because it roughly doubles the cost of a query that repeats.
+ */
+function tableQuery() {
+    return 'Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,Name,CreationDate | ForEach-Object { ' +
+        '$d = if ($_.CreationDate) { [int64]([System.DateTimeOffset]::new([System.TimeZoneInfo]::ToUniversalTime($_.CreationDate)).ToUnixTimeMilliseconds()) } else { -1 }; ' +
+        '"{0}`t{1}`t{2}`t{3}" -f $_.ProcessId, $_.ParentProcessId, $_.Name, $d }';
+}
+function parseTable(text) {
+    const rows = [];
+    for (const line of text.split(/\r?\n/)) {
+        const columns = line.split('\t');
+        if (columns.length < 3)
+            continue;
+        const pid = Number.parseInt(columns[0], 10);
+        const parent_pid = Number.parseInt(columns[1], 10);
+        if (!Number.isInteger(pid) || !Number.isInteger(parent_pid))
+            continue;
+        const created = Number.parseInt(columns[3] ?? '', 10);
+        rows.push({ pid, parent_pid, name: columns[2] ?? '',
+            created_ms: Number.isInteger(created) && created >= 0 ? created : null });
+    }
+    return rows;
+}
+export async function listProcesses() {
+    return parseTable(await powershell(tableQuery()));
+}
+/**
+ * The same rows, but only for the pids about to be killed. Every id is validated first because it is spliced into a
+ * WQL filter string.
+ */
+export async function listProcessesById(pids) {
+    if (!pids.length)
+        return [];
+    if (!pids.every(pid => Number.isInteger(pid) && pid > 1))
+        throw new Error('A process id to verify must be a positive integer');
+    const filter = pids.map(pid => `ProcessId=${pid}`).join(' OR ');
+    return parseTable(await powershell(tableQuery().replace('Win32_Process -Property', `Win32_Process -Filter '${filter}' -Property`)));
+}
+/** Every row below `root`, nearest first, without the root itself. */
+export function descendants(table, root) {
+    const childrenOf = new Map();
+    for (const row of table) {
+        const siblings = childrenOf.get(row.parent_pid);
+        if (siblings)
+            siblings.push(row);
+        else
+            childrenOf.set(row.parent_pid, [row]);
+    }
+    const found = [];
+    const seen = new Set([root]);
+    for (let frontier = [root]; frontier.length;) {
+        const next = [];
+        for (const pid of frontier) {
+            for (const child of childrenOf.get(pid) ?? []) {
+                if (seen.has(child.pid))
+                    continue;
+                seen.add(child.pid);
+                found.push(child);
+                next.push(child.pid);
+            }
+        }
+        frontier = next;
+    }
+    return found;
+}
+/**
+ * Denser while the CLI is booting its servers, then steady: a missed short-lived shell loses a whole subtree.
+ * Each gap is measured after the previous query finished, and one query costs about half a second, so the tail
+ * stays long on purpose to keep the watcher well under a tenth of a core.
+ */
+export const WATCH_DELAYS_MS = [500, 1000, 2000, 4000, 10000];
+/**
+ * Records the agent's descendant tree while it runs, because the shells that hold the deepest children exit before
+ * the agent does. Best effort on every axis: a failed query is skipped, the next tick can still see the tree.
+ */
+export function startTreeWatch(pid, options = {}) {
+    const delays = options.delays ?? WATCH_DELAYS_MS;
+    if ((options.platform ?? process.platform) !== 'win32' || !Number.isInteger(pid) || pid <= 1)
+        return { stop: () => [] };
+    const list = options.list ?? listProcesses;
+    const observed = new Map();
+    let stopped = false;
+    let cancel = null;
+    const poll = async (index) => {
+        try {
+            for (const info of descendants(await list(), pid))
+                observed.set(info.pid, info);
+        }
+        catch { /* the next tick gets another chance; the release is a convenience, not a guarantee */ }
+        if (!stopped)
+            wait(index + 1);
+    };
+    const wait = (index) => {
+        const at = Math.min(index, delays.length - 1);
+        const schedule = options.schedule ?? ((callback, ms) => { const timer = setTimeout(callback, ms); timer.unref(); return () => { clearTimeout(timer); }; });
+        cancel = schedule(() => poll(at), delays[at]);
+    };
+    wait(0);
+    return {
+        async stop() {
+            stopped = true;
+            cancel?.();
+            try {
+                for (const info of descendants(await list(), pid))
+                    observed.set(info.pid, info);
+            }
+            catch { /* the release still has everything the polls recorded */ }
+            return [...observed.values()];
+        }
+    };
+}
+async function killTree(pid) {
+    await new Promise((resolve, reject) => {
+        const systemRoot = process.env.SystemRoot ?? 'C:\\Windows';
+        const killer = spawn(`${systemRoot}\\System32\\taskkill.exe`, ['/PID', String(pid), '/T', '/F'], { shell: false, windowsHide: true, stdio: 'ignore' });
+        killer.once('error', reject);
+        killer.once('close', code => code === 0 ? resolve() : reject(new Error(`taskkill exited ${code}`)));
+    });
+}
+const groupAlive = (pid) => {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Releases whatever the agent left behind after it exited. Candidates are the processes still hanging below the
+ * agent or below any process the watch recorded while it ran, and each subtree root must pass reapGuard, so this
+ * cannot wander into an unrelated tree. `taskkill /T` covers the children of a root, so only roots are killed.
+ */
+export async function reapOwnedTree(pid, options) {
+    const platform = options.platform ?? process.platform;
+    if (!Number.isInteger(pid) || pid <= 1)
+        return { checked: false, reason: 'No usable process id was recorded for this task', reaped: [], skipped: [] };
+    const alive = options.isAlive ?? (value => {
+        try {
+            process.kill(value, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== 'ESRCH';
+        }
+    });
+    if (alive(pid))
+        return { checked: false, reason: 'Owned process is still running; its tree is terminated by cancel or timeout instead', reaped: [], skipped: [] };
+    if (platform !== 'win32') {
+        // POSIX spawns the agent detached, so it led its own group and every descendant inherited that group id.
+        const inGroup = options.group_alive ?? groupAlive;
+        const signal = options.signal_group ?? ((target, value) => { process.kill(-target, value); });
+        if (!inGroup(pid))
+            return { checked: true, reaped: [], skipped: [], group_signalled: false };
+        try {
+            signal(pid, 'SIGTERM');
+        }
+        catch {
+            return { checked: true, reaped: [], skipped: [], group_signalled: false };
+        }
+        const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+        const deadline = Date.now() + TERMINATION_GRACE_MS;
+        while (inGroup(pid)) {
+            if (Date.now() >= deadline) {
+                try {
+                    signal(pid, 'SIGKILL');
+                }
+                catch { /* the group exited in the race */ }
+                break;
+            }
+            await sleep(50);
+        }
+        return { checked: true, reaped: [], skipped: [], group_signalled: true };
+    }
+    const observed = new Map(options.observed?.map(info => [info.pid, info]) ?? []);
+    let table;
+    try {
+        table = await (options.list ?? listProcesses)();
+    }
+    catch (error) {
+        return { checked: false, reason: `Could not enumerate the agent process tree: ${error instanceof Error ? error.message : 'query failed'}`, reaped: [], skipped: [], tracked: observed.size };
+    }
+    const tableByPid = new Map(table.map(row => [row.pid, row]));
+    const recycled = (info, current) => info.name.toLowerCase() !== current.name.toLowerCase()
+        || (info.created_ms !== null && current.created_ms !== null && info.created_ms !== current.created_ms);
+    // A recorded parent that is gone still names its children, which is exactly what a child query cannot recover.
+    // A recorded parent that is alive again under the same number but is a different process is not a parent of ours.
+    const roots = new Set([pid]);
+    for (const [recorded, info] of observed) {
+        const current = tableByPid.get(recorded);
+        if (!current || !recycled(info, current))
+            roots.add(recorded);
+    }
+    const candidates = table.filter(row => row.pid !== pid && roots.has(row.parent_pid));
+    const tops = candidates.filter(row => !candidates.some(other => other.pid === row.parent_pid));
+    const reaped = [];
+    const skipped = [];
+    const kill = options.kill ?? killTree;
+    // Enumeration and termination are not one atomic act: every kill is awaited, so a pid can be reissued while the
+    // loop runs. Re-reading just the targets costs one filtered query instead of a second full table.
+    let targets = tops;
+    if (tops.length) {
+        try {
+            const fresh = new Map((await (options.verify ?? listProcessesById)(tops.map(row => row.pid))).map(row => [row.pid, row]));
+            targets = [];
+            for (const candidate of tops) {
+                const now = fresh.get(candidate.pid);
+                if (!now)
+                    continue;
+                if (recycled(candidate, now))
+                    skipped.push({ pid: candidate.pid, name: candidate.name, guard: 'pid was reissued to another process after the tree query' });
+                else
+                    targets.push(now);
+            }
+        }
+        catch { /* the second read is an extra guard; the checks already made against the tree query still stand */ }
+    }
+    for (const child of targets) {
+        const info = observed.get(child.pid);
+        if (info && recycled(info, child)) {
+            skipped.push({ pid: child.pid, name: child.name, guard: 'pid was recycled for an unrelated process after the task ended' });
+            continue;
+        }
+        const guard = reapGuard(child, { started_at_ms: options.started_at_ms, self_pid: options.self_pid });
+        if (guard) {
+            if (child.pid !== (options.self_pid ?? process.pid))
+                skipped.push({ pid: child.pid, name: child.name, guard });
+            continue;
+        }
+        try {
+            await kill(child.pid);
+            reaped.push(child.pid);
+        }
+        catch {
+            skipped.push({ pid: child.pid, name: child.name, guard: 'termination request failed (it may have exited on its own)' });
+        }
+    }
+    return { checked: true, reaped, skipped, tracked: observed.size };
+}
+//# sourceMappingURL=orphans.js.map

package/dist/src/isolation/worktree.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { mkdir, realpath } from 'node:fs/promises';
+import { mkdir, readFile, readdir, realpath, rmdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { workspaceChanges } from '../changes.js';
 import { inside } from '../security/workspace.js';
@@ -52,10 +52,200 @@ export async function createWorktree(options) {
         throw new Error('Worktree workspace resolves outside the worktree');
     return { root: realRoot, workspace: realWorkspace, toplevel, branch, prefix, base };
 }
-/** Best effort and only for a launch that never started a process: no files were touched by the agent. */
-export async function removeWorktree(worktree) {
-    await git(worktree.toplevel, ['worktree', 'remove', '--force', worktree.root]).catch(() => { });
-    await git(worktree.toplevel, ['branch', '-D', worktree.branch]).catch(() => { });
+/**
+ * Best effort and only for a launch that never started a process: no files were touched by the agent.
+ * A Windows process that still holds the directory makes `git worktree remove` fail, so the attempt is retried
+ * briefly and the outcome is returned instead of dropped.
+ */
+export async function removeWorktree(worktree, options = {}) {
+    const delays = options.retryDelayMs ?? [0, 200, 600];
+    let reason = '';
+    for (const delay of delays) {
+        if (delay)
+            await sleep(delay);
+        try {
+            await git(worktree.toplevel, ['worktree', 'remove', '--force', worktree.root]);
+        }
+        catch (error) {
+            reason = error instanceof Error ? error.message : 'git worktree remove failed';
+        }
+        if (!await exists(worktree.root)) {
+            await git(worktree.toplevel, ['branch', '-D', worktree.branch]).catch(() => { });
+            return { removed: true };
+        }
+        reason = `The worktree directory is still held by a running process${reason ? ` (last error: ${reason})` : ''}`;
+    }
+    return { removed: false, reason };
+}
+const exists = async (target) => {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const TASK_ID = /^[0-9a-f]{8}-[0-9a-f-]+$/;
+const TASK_RECORD = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.json$/;
+/**
+ * Drops worktree directories that a previous run could not remove because a process the bridge no longer owned
+ * was holding them open. Only genuinely empty directories go: anything with content is a diff someone may still
+ * be reviewing, and stale locks on real work are left for a human.
+ */
+export async function sweepStaleWorktrees(stateDirectory, options = {}) {
+    const directory = path.join(stateDirectory, 'worktrees');
+    const report = { scanned: 0, removed: [], retained: [], prunable: [] };
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch {
+        return report;
+    }
+    const readRecord = options.readRecord ?? (async (taskId) => {
+        try {
+            const parsed = JSON.parse(await readFile(path.join(stateDirectory, 'tasks', `${taskId}.json`), 'utf8'));
+            return { status: parsed.task?.status ?? parsed.status ?? null, repo: parsed.task?.worktree_toplevel ?? null, worktree: parsed.task?.worktree ?? null };
+        }
+        catch {
+            return { status: null, repo: null, worktree: null };
+        }
+    });
+    const queuePrune = (repo) => { if (!report.prunable.includes(repo))
+        report.prunable.push(repo); };
+    // Removing through git also drops the admin record under <repo>/.git/worktrees, which a plain rmdir leaves behind as
+    // a stale entry that then makes every later `git worktree` command in that repository complain.
+    const remove = options.remove ?? (async (target, repo) => {
+        if (repo) {
+            try {
+                await git(repo, ['worktree', 'remove', '--force', target]);
+                return 'git';
+            }
+            catch { /* the directory may be gone already */ }
+        }
+        await rmdir(target);
+        return 'rmdir';
+    });
+    for (const name of names) {
+        const candidate = path.join(directory, name);
+        report.scanned += 1;
+        if (!TASK_ID.test(name)) {
+            report.retained.push({ path: candidate, reason: 'not a task worktree directory' });
+            continue;
+        }
+        let record;
+        try {
+            record = await readRecord(name);
+        }
+        catch {
+            report.retained.push({ path: candidate, reason: 'its task record could not be read' });
+            continue;
+        }
+        if (record.status === 'queued' || record.status === 'running') {
+            report.retained.push({ path: candidate, reason: `task is ${record.status}` });
+            continue;
+        }
+        let entries;
+        try {
+            entries = await readdir(candidate);
+        }
+        catch (error) {
+            // The directory is already gone — deleted without git, which is exactly what leaves a stale admin record behind.
+            if (error.code === 'ENOENT') {
+                if (record.repo)
+                    queuePrune(record.repo);
+                continue;
+            }
+            report.retained.push({ path: candidate, reason: error instanceof Error ? error.message : 'directory could not be read' });
+            continue;
+        }
+        if (entries.length) {
+            report.retained.push({ path: candidate, reason: 'it still holds files for review' });
+            continue;
+        }
+        let reason = '';
+        let how = 'rmdir';
+        for (const delay of options.retryDelayMs ?? [0, 200, 600]) {
+            if (delay)
+                await sleep(delay);
+            try {
+                how = await remove(candidate, record.repo);
+                reason = '';
+                break;
+            }
+            catch (error) {
+                reason = error instanceof Error ? error.message : 'directory could not be removed';
+            }
+        }
+        if (reason)
+            report.retained.push({ path: candidate, reason });
+        else {
+            report.removed.push(candidate);
+            // A git removal took the admin record with it; anything else that cleared the directory left the record behind.
+            if (how === 'rmdir' && record.repo)
+                queuePrune(record.repo);
+        }
+    }
+    // A directory deleted by hand never shows up in the listing above, so the task records are read as well: a finished
+    // task naming a worktree that is no longer on disk is the other way a repository ends up holding a dead entry.
+    let records;
+    try {
+        records = await readdir(path.join(stateDirectory, 'tasks'));
+    }
+    catch {
+        return report;
+    }
+    for (const file of records) {
+        if (!TASK_RECORD.test(file))
+            continue;
+        let record;
+        try {
+            record = await readRecord(file.slice(0, -'.json'.length));
+        }
+        catch {
+            continue;
+        }
+        if (record.status === 'queued' || record.status === 'running')
+            continue;
+        if (!record.repo || !record.worktree || await exists(record.worktree))
+            continue;
+        queuePrune(record.repo);
+    }
+    return report;
+}
+/** Worktree paths the repository still has a record for, including the ones whose directory is already gone. */
+async function listedWorktrees(repo) {
+    const text = await git(repo, ['worktree', 'list', '--porcelain']);
+    return text.split('\n').filter(line => line.startsWith('worktree ')).map(line => line.slice('worktree '.length).trim()).filter(Boolean);
+}
+/**
+ * Clears the `<repo>/.git/worktrees/<name>` entries left behind when a worktree directory went away without git.
+ * Git only prunes records whose directory is already missing, so this is called for the repositories whose
+ * directories the sweep itself deleted — a worktree someone is still using is never in scope. `--expire=now` is
+ * required because the default grace is three months, which would leave a record the bridge just orphaned in place.
+ * Any other missing-directory record in that repository goes with it; that costs an admin entry, not files, and a
+ * checkout that is merely unmounted is restored with `git worktree repair`.
+ */
+export async function pruneWorktrees(repo) {
+    try {
+        const missing = [];
+        for (const target of await listedWorktrees(repo)) {
+            if (!await exists(target))
+                missing.push(target);
+        }
+        if (!missing.length)
+            return { pruned: 0, reason: '' };
+        // The count comes from the record list, not from what `prune -v` prints: that goes to stderr, and a report of
+        // "0 pruned" after a record was in fact cleared would be the worse kind of wrong.
+        await git(repo, ['worktree', 'prune', '-v', '--expire=now']);
+        const remaining = new Set(await listedWorktrees(repo));
+        return { pruned: missing.filter(target => !remaining.has(target)).length, reason: '' };
+    }
+    catch (error) {
+        return { pruned: 0, reason: error instanceof Error ? error.message : 'git worktree prune failed' };
+    }
 }
 function normalizeOwn(own) {
     return path.posix.normalize(own.replace(/\\/g, '/')).replace(/^\.\//, '').replace(/\/+$/, '');

package/dist/src/models.js

@@ -21,9 +21,9 @@ export function parseModels(text) {
     return models;
 }
 /** Runs `agy models`; rejects when the command fails, times out or prints nothing recognizable. */
-export function listModels(executable, cwd, extraEnvPassthrough = []) {
+export function listModels(executable, cwd, extraEnvPassthrough = [], prefixArgs = []) {
     return new Promise((resolve, reject) => {
-        const child = startProcess(executable, ['models'], cwd, { extraEnvPassthrough });
+        const child = startProcess(executable, [...prefixArgs, 'models'], cwd, { extraEnvPassthrough });
         let text = '';
         let errors = '';
         let timedOut = false;

package/dist/src/runtime.js

@@ -3,14 +3,16 @@ import { helperDirectory, paths } from './paths.js';
 import { inspectCli, resolveCommand, startProcess, VERIFIED_AGY_VERSIONS } from './antigravity/process.js';
 import { createAgentRegistry, publicAgents } from './agents/registry.js';
 import { TaskManager } from './tasks/manager.js';
+import { sweepStaleWorktrees, pruneWorktrees } from './isolation/worktree.js';
+import { startTreeWatch } from './isolation/orphans.js';
 import { recoverExecutionLock } from './tasks/execution-lock.js';
 export async function createRuntime() {
     const config = await loadConfig();
-    let cli = { version: 'unavailable', executable: '', supported: false, warnings: [] };
+    let cli = { version: 'unavailable', executable: '', prefixArgs: [], supported: false, warnings: [] };
     let antigravity = { version: 'unavailable', executable: '', supported: false, warnings: [] };
     try {
         const command = await resolveCommand(config.executable);
-        cli = await inspectCli(command.executable, helperDirectory(), (executable, args, cwd) => startProcess(executable, args, cwd, { extraEnvPassthrough: config.extra_env_passthrough }), config.prompt_transport === 'stdin');
+        cli = await inspectCli(command, helperDirectory(), (executable, args, cwd) => startProcess(executable, args, cwd, { extraEnvPassthrough: config.extra_env_passthrough }), config.prompt_transport === 'stdin');
         antigravity = { ...cli, executable: cli.executable || command.source };
     }
     catch {
@@ -27,11 +29,30 @@ export async function createRuntime() {
         console.error(`[bridge] Agent ${agent.adapter.id}: ${state}`);
     }
     const maxParallelWorktrees = config.max_parallel_worktrees ?? 2;
+    const treeWatch = config.tree_watch ?? {};
+    const treeWatchEnabled = treeWatch.enabled !== false;
+    if (!treeWatchEnabled)
+        console.error('[bridge] WARNING: tree_watch is off; a process tree the agent leaves behind will not be released');
     const manager = new TaskManager(config, {
-        executable: antigravity.executable, supported: antigravity.supported, stateDirectory: paths.stateDirectory,
-        agents: registry.agents, defaultAgent: registry.defaultAgent
+        executable: antigravity.executable, prefixArgs: antigravity.prefixArgs, supported: antigravity.supported, stateDirectory: paths.stateDirectory,
+        agents: registry.agents, defaultAgent: registry.defaultAgent,
+        // Without the watch the release can only name the processes that still hang below the agent at the moment it
+        // exits, which is exactly the case that left the worktree pinned in a live run.
+        watchTree: treeWatchEnabled ? pid => startTreeWatch(pid, { delays: treeWatch.delays_ms }) : undefined
     });
     await recoverExecutionLock(paths.stateDirectory);
+    const sweep = await sweepStaleWorktrees(paths.stateDirectory);
+    for (const removed of sweep.removed)
+        console.error(`[bridge] Removed a stale empty worktree directory: ${removed}`);
+    for (const kept of sweep.retained)
+        console.error(`[bridge] Kept worktree directory ${kept.path}: ${kept.reason}`);
+    for (const repo of sweep.prunable) {
+        const prune = await pruneWorktrees(repo);
+        if (prune.pruned)
+            console.error(`[bridge] Pruned ${prune.pruned} stale worktree record(s) in ${repo}`);
+        else if (prune.reason)
+            console.error(`[bridge] WARNING: stale worktree records in ${repo} could not be pruned: ${prune.reason}`);
+    }
     const restored = await manager.restore();
     if (restored)
         console.error(`[bridge] Restored ${restored} finished task record(s) from .bridge-state/tasks`);
@@ -64,7 +85,8 @@ export async function createRuntime() {
             'Existing agent permissions, hooks, MCP and credential access remain governed by each CLI configuration.',
             'Antigravity permission flags are off unless the bridge owner raises the level in the web UI (a client cannot change it). At the default level, actions that need approval are denied (see denied_actions).',
             'No permission bypass flags. Dangerous actions require separate interactive approval.',
-            'Windows uses taskkill on the live owned child tree; abrupt server termination may orphan processes.',
+            `After an agent process exits, the bridge releases the process trees it left behind (Windows: taskkill on every subtree still hanging below the agent or below a process recorded while it ran, after re-checking that each pid still names the same process; POSIX: the exited process group). The outcome is published as the task's cleanup field, and a graceful shutdown waits for it. A bridge killed abruptly, or tree_watch disabled in config, can still orphan processes.`,
+            'Worktree directories of finished tasks are kept for review. Only empty leftovers are removed at startup, a directory a live process still holds is reported instead of forced, and a repository left holding a record whose directory is gone is pruned.',
             'Redaction recognizes known patterns only. Never include credentials in task data.'
         ]
     };