@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/teams/pr-watch.js

@@ -0,0 +1,371 @@
+/**
+ * Autonomous PR lifecycle for teams (issue #338).
+ *
+ * A team's teammates open PRs. This module watches those PRs and reacts:
+ *   - RED CI  -> spawn a fresh fix wave (a teammate --after the one that failed,
+ *                with the CI failure logs injected) that pushes a follow-up commit.
+ *   - NEW REVIEW COMMENT -> route it to a `bugfix` teammate (--after the source),
+ *                with the comment body injected.
+ *
+ * The DECISION logic here is a pure function (`decidePrActions`) over a snapshot
+ * of check results + review comments + a set of already-handled ids. It never
+ * touches the network — the poll-based collector (`pollPrSnapshot`, backed by the
+ * `gh` CLI) and the orchestrator (`runPrWatch`) sit on top and feed it data. That
+ * split keeps the spawn-or-not-spawn logic fully unit-testable (see
+ * pr-watch.test.ts) and dedupe-correct.
+ *
+ * Follow-up (deferred, not required here): replace the poll loop with the
+ * event-driven webhook receiver from #331 — `pollPrSnapshot` is the seam where a
+ * `check_run` / `pull_request_review_comment` webhook payload would plug in,
+ * producing the same PrSnapshot the pure decider already consumes.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+/**
+ * Default cap on how many fix/bugfix waves pr-watch spawns for a single PR before
+ * it gives up and escalates to a human. A persistently-RED PR re-runs CI on every
+ * follow-up commit; without a cap the loop would spawn teammates without bound
+ * (issue #338). Configurable via `--max-waves`.
+ */
+export const DEFAULT_MAX_WAVES = 3;
+/**
+ * Check states that count as a RED CI failure worth spawning a fix wave for.
+ * PENDING / SUCCESS / SKIPPING / NEUTRAL are deliberately excluded — a fix wave
+ * only fires on a genuine, terminal failure.
+ */
+const FAILED_STATES = new Set([
+    'FAILURE',
+    'ERROR',
+    'CANCELLED',
+    'TIMED_OUT',
+    'ACTION_REQUIRED',
+    'STARTUP_FAILURE',
+]);
+/** True when a check is in a terminal failing state. */
+export function isFailedCheck(check) {
+    return FAILED_STATES.has((check.state || '').trim().toUpperCase());
+}
+/**
+ * Idempotency key for a failed check on a PR — dedupe by check NAME.
+ *
+ * The name is the ONLY identity that's stable across re-runs: when a fixer pushes
+ * a follow-up commit, GitHub creates a fresh workflow run with a new `link` URL but
+ * the SAME check name. Keying off `link` (as an earlier draft did) would treat every
+ * re-run as a brand-new failure and spawn an unbounded chain of fixers (issue #338).
+ * Keying off the name means a re-run of the same check is recognised as the same
+ * logical failure; the per-PR wave counter then bounds how many times we retry it.
+ */
+export function checkDedupeKey(prUrl, check) {
+    return `ci:${prUrl}:${check.name}`;
+}
+/** Idempotency key for a review comment on a PR — dedupe by comment id. */
+export function commentDedupeKey(prUrl, comment) {
+    return `review:${prUrl}:${comment.id}`;
+}
+/** Idempotency key for the one-shot "needs human" escalation on a PR. */
+export function needsHumanKey(prUrl) {
+    return `needs-human:${prUrl}`;
+}
+/**
+ * The pure heart of pr-watch: given a PR snapshot, the set of dedupe keys already
+ * acted on, and how many fix waves each PR has already spent, decide which
+ * follow-up teammates to spawn. Emits:
+ *   - one `ci-fix` action per NEW failed check (dedup by check NAME)
+ *   - one `review-fix` action per NEW review comment (dedup by comment id)
+ *   - a single `needs-human` action (per PR) once the wave budget is exhausted,
+ *     INSTEAD of spawning — so a persistently-failing PR escalates rather than
+ *     spawning teammates without bound (issue #338).
+ *
+ * `waves` maps a PR URL to the number of fix/bugfix teammates already spawned for
+ * it; once that reaches `maxWaves`, no further spawns are emitted for that PR.
+ * Both the CI-fix and comment-routing paths draw from the SAME per-PR budget, so
+ * neither can loop unboundedly.
+ *
+ * No network, no side effects, no reference to state beyond the passed
+ * `handled` / `waves` — so the same failure never spawns twice and the caller
+ * stays in control of when a wave is "spent".
+ */
+export function decidePrActions(snapshot, handled, waves = new Map(), maxWaves = DEFAULT_MAX_WAVES) {
+    const actions = [];
+    const { prUrl } = snapshot;
+    // Waves already spent, plus the ones we're about to emit in THIS pass — so a
+    // single pass with several fresh failures can't blow past the budget.
+    let projected = waves.get(prUrl) ?? 0;
+    let escalated = false;
+    const escalate = (subject) => {
+        if (escalated)
+            return;
+        const dedupeKey = needsHumanKey(prUrl);
+        if (handled.has(dedupeKey))
+            return; // already escalated this PR — stay silent
+        escalated = true;
+        actions.push({
+            kind: 'needs-human',
+            prUrl,
+            sourceTeammate: snapshot.sourceTeammate,
+            subject,
+            waves: projected,
+            dedupeKey,
+        });
+    };
+    for (const check of snapshot.checks) {
+        if (!isFailedCheck(check))
+            continue;
+        const dedupeKey = checkDedupeKey(prUrl, check);
+        if (handled.has(dedupeKey))
+            continue;
+        if (projected >= maxWaves) {
+            escalate(`CI check "${check.name}"`);
+            continue;
+        }
+        projected++;
+        actions.push({
+            kind: 'ci-fix',
+            prUrl,
+            sourceTeammate: snapshot.sourceTeammate,
+            check,
+            dedupeKey,
+            wave: projected,
+        });
+    }
+    for (const comment of snapshot.comments) {
+        const dedupeKey = commentDedupeKey(prUrl, comment);
+        if (handled.has(dedupeKey))
+            continue;
+        if (projected >= maxWaves) {
+            escalate(`review comment #${comment.id}`);
+            continue;
+        }
+        projected++;
+        actions.push({
+            kind: 'review-fix',
+            prUrl,
+            sourceTeammate: snapshot.sourceTeammate,
+            comment,
+            dedupeKey,
+            wave: projected,
+        });
+    }
+    return actions;
+}
+/**
+ * Build the task prompt for a CI-fix teammate. Pure so it's unit-testable: the
+ * failing check + the fetched logs are injected as data.
+ */
+export function buildCiFixPrompt(action, logs) {
+    const logsBlock = logs.trim()
+        ? `\n\nCI failure logs:\n\`\`\`\n${logs.trim()}\n\`\`\``
+        : `\n\n(No CI logs could be fetched — inspect the run at ${action.check.link ?? action.prUrl}.)`;
+    return (`CI is RED on PR ${action.prUrl}. The check "${action.check.name}"` +
+        (action.check.workflow ? ` (workflow: ${action.check.workflow})` : '') +
+        ` failed with state ${action.check.state}. ` +
+        `Diagnose the failure from the logs below, fix it, and push a follow-up commit to the SAME PR branch ` +
+        `(check out the PR branch with \`gh pr checkout ${action.prUrl}\`, make the fix, commit, and push). ` +
+        `Do not open a new PR — push to the existing branch so this PR goes green.` +
+        logsBlock);
+}
+/**
+ * Build the task prompt for a review-comment bugfix teammate. Pure so it's
+ * unit-testable: the review comment is injected as data.
+ */
+export function buildReviewFixPrompt(action) {
+    const c = action.comment;
+    const where = c.path ? ` on \`${c.path}\`` : '';
+    const who = c.user ? `@${c.user}` : 'A reviewer';
+    return (`${who} left a review comment${where} on PR ${action.prUrl}. ` +
+        `Address it and push a follow-up commit to the SAME PR branch ` +
+        `(check out the PR branch with \`gh pr checkout ${action.prUrl}\`, make the change, commit, and push). ` +
+        `Do not open a new PR.\n\n` +
+        `Review comment:\n${c.body}` +
+        (c.html_url ? `\n\n(thread: ${c.html_url})` : ''));
+}
+/** Parse an owner/repo/number triple out of a GitHub PR URL. Returns null when it doesn't match. */
+export function parsePrUrl(prUrl) {
+    const m = prUrl.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2], number: Number(m[3]) };
+}
+// ---------------------------------------------------------------------------
+// Impure collectors — thin `gh` CLI wrappers. Kept out of the pure decider so
+// tests never hit the network. These are the seam the #331 webhook receiver
+// would replace: a webhook payload can synthesize the same PrCheck /
+// PrReviewComment shapes and hand them straight to decidePrActions.
+// ---------------------------------------------------------------------------
+/** Fetch the current CI checks for a PR via `gh pr checks`. Returns [] on any gh error. */
+export async function fetchPrChecks(prUrl) {
+    try {
+        const { stdout } = await execFileAsync('gh', ['pr', 'checks', prUrl, '--json', 'name,state,link,workflow'], { maxBuffer: 8 * 1024 * 1024 });
+        const raw = JSON.parse(stdout);
+        return raw.map((r) => ({
+            name: String(r.name ?? ''),
+            state: String(r.state ?? ''),
+            link: r.link ? String(r.link) : undefined,
+            workflow: r.workflow ? String(r.workflow) : undefined,
+        }));
+    }
+    catch {
+        // `gh pr checks` exits non-zero when checks are failing OR when none are
+        // configured. Both surface as a throw here; treat "can't read" as "nothing
+        // to act on" rather than crashing the watch loop.
+        return [];
+    }
+}
+/** Fetch review comments for a PR via `gh api`. Returns [] on any gh error. */
+export async function fetchPrReviewComments(prUrl) {
+    const parsed = parsePrUrl(prUrl);
+    if (!parsed)
+        return [];
+    try {
+        const { stdout } = await execFileAsync('gh', [
+            'api',
+            `repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}/comments`,
+            '--paginate',
+        ], { maxBuffer: 16 * 1024 * 1024 });
+        const raw = JSON.parse(stdout);
+        return raw.map((r) => ({
+            id: Number(r.id),
+            body: String(r.body ?? ''),
+            user: r.user && typeof r.user === 'object'
+                ? String(r.user.login ?? '')
+                : undefined,
+            path: r.path ? String(r.path) : undefined,
+            html_url: r.html_url ? String(r.html_url) : undefined,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/** Fetch the failing-run logs for a check via `gh run view --log-failed`. Best-effort, truncated. */
+export async function fetchCiFailureLogs(check, maxChars = 8000) {
+    const runId = check.link?.match(/\/runs\/(\d+)/)?.[1] ?? check.link?.match(/\/actions\/runs\/(\d+)/)?.[1];
+    if (!runId)
+        return '';
+    try {
+        const { stdout } = await execFileAsync('gh', ['run', 'view', runId, '--log-failed'], { maxBuffer: 32 * 1024 * 1024 });
+        if (stdout.length <= maxChars)
+            return stdout;
+        // Keep the tail — the actual error is almost always at the end of the log.
+        return `... (truncated ${stdout.length - maxChars} chars) ...\n` + stdout.slice(-maxChars);
+    }
+    catch {
+        return '';
+    }
+}
+/** Collect a live PR snapshot from `gh`. The poll-mode seam for `runPrWatch`. */
+export async function pollPrSnapshot(prUrl, sourceTeammate) {
+    const [checks, comments] = await Promise.all([
+        fetchPrChecks(prUrl),
+        fetchPrReviewComments(prUrl),
+    ]);
+    return { prUrl, sourceTeammate, checks, comments };
+}
+/**
+ * Run the pr-watch poll loop. Each pass: retire the dedupe guards of any fixers
+ * that have finished (so a still-red check can spawn its next wave), resolve watch
+ * targets, snapshot each PR, decide actions against the running `handled` set and
+ * per-PR `waves` budget, then react — spawning fresh fixers, or emitting a
+ * one-shot `needs-human` event once a PR's wave budget is spent. Every acted-on
+ * dedupe key is recorded so a failure/comment never spawns twice within a wave,
+ * and `waves` hard-caps the total spawns per PR (issue #338).
+ */
+export async function runPrWatch(deps, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 15000;
+    const maxPolls = opts.maxPolls ?? 0;
+    const maxWaves = opts.maxWaves ?? DEFAULT_MAX_WAVES;
+    const handled = opts.handled ?? new Set();
+    const waves = opts.waves ?? new Map();
+    const pollSnapshot = deps.pollSnapshot ?? pollPrSnapshot;
+    const fetchLogs = deps.fetchLogs ?? fetchCiFailureLogs;
+    const emit = deps.onEvent ?? (() => { });
+    // dedupeKey -> spawned teammate label, for the settle sweep. When a fixer
+    // finishes, its guard clears so the next wave (if still warranted) can fire.
+    const inFlight = new Map();
+    let polls = 0;
+    let spawned = 0;
+    let neededHuman = 0;
+    for (;;) {
+        if (opts.shouldStop?.()) {
+            return { polls, spawned, neededHuman, handled, waves, stoppedBy: 'signal' };
+        }
+        // Retire guards for finished fixers so a check that's STILL red after a fix
+        // can spawn its next wave (bounded by `waves`). Skipped when no settle probe
+        // is wired — then a check gets one wave until pr-watch restarts.
+        if (deps.reactionSettled && inFlight.size > 0) {
+            for (const [key, label] of [...inFlight]) {
+                let done = false;
+                try {
+                    done = await deps.reactionSettled(label);
+                }
+                catch {
+                    done = false;
+                }
+                if (done) {
+                    handled.delete(key);
+                    inFlight.delete(key);
+                }
+            }
+        }
+        const targets = await deps.resolveTargets();
+        polls++;
+        emit({ type: 'poll', targets: targets.length, timestamp: new Date().toISOString() });
+        for (const target of targets) {
+            let snap;
+            try {
+                snap = await pollSnapshot(target.prUrl, target.sourceTeammate);
+            }
+            catch (err) {
+                emit({
+                    type: 'error',
+                    prUrl: target.prUrl,
+                    message: err.message,
+                    timestamp: new Date().toISOString(),
+                });
+                continue;
+            }
+            const actions = decidePrActions(snap, handled, waves, maxWaves);
+            for (const action of actions) {
+                // Record the key BEFORE reacting so a spawn failure can't loop-spam the
+                // same failure — a bad action is dropped, not retried forever.
+                handled.add(action.dedupeKey);
+                if (action.kind === 'needs-human') {
+                    neededHuman++;
+                    emit({
+                        type: 'needs-human',
+                        prUrl: action.prUrl,
+                        subject: action.subject,
+                        waves: action.waves,
+                        timestamp: new Date().toISOString(),
+                    });
+                    continue;
+                }
+                // Spend a wave from this PR's budget for the spawn we're about to make.
+                waves.set(action.prUrl, (waves.get(action.prUrl) ?? 0) + 1);
+                const prompt = action.kind === 'ci-fix'
+                    ? buildCiFixPrompt(action, await fetchLogs(action.check))
+                    : buildReviewFixPrompt(action);
+                try {
+                    const label = await deps.react(action, prompt);
+                    spawned++;
+                    if (label)
+                        inFlight.set(action.dedupeKey, label);
+                    emit({ type: 'spawned', action, label, timestamp: new Date().toISOString() });
+                }
+                catch (err) {
+                    emit({
+                        type: 'error',
+                        prUrl: action.prUrl,
+                        message: err.message,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+            }
+        }
+        if (maxPolls > 0 && polls >= maxPolls) {
+            return { polls, spawned, neededHuman, handled, waves, stoppedBy: 'max-polls' };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}

package/dist/lib/teams/supervisor.d.ts

@@ -18,6 +18,8 @@
  * terminal output, json-per-wave output, or a TUI.
  */
 import type { AgentManager, AgentProcess } from './agents.js';
+import type { TeamBudgetWatcher } from '../budget/live-team.js';
+import type { BreachInfo } from '../budget/enforce.js';
 export interface WaveSummary {
     wave: number;
     timestamp: string;
@@ -35,11 +37,22 @@ export interface SupervisorOptions {
     maxWaves?: number;
     /** Called once per wave. Return false to stop the loop gracefully. */
     onWave: (summary: WaveSummary) => void | Promise<void> | boolean | Promise<boolean>;
+    /**
+     * Optional live-spend watcher (issue #399). Polled once per wave; on first
+     * breach the supervisor calls `manager.stopByTask(team)` and exits with
+     * `stoppedBy: 'budget'`. Dormant when null — supervisor behavior is unchanged
+     * for teams that never opt into budget enforcement.
+     */
+    budgetWatcher?: TeamBudgetWatcher | null;
+    /** Called with the breach details when the budget watcher trips. */
+    onBudgetBreach?: (breach: BreachInfo) => void;
 }
 export interface SupervisorResult {
     waves: number;
-    stoppedBy: 'drained' | 'max-waves' | 'signal' | 'callback';
+    stoppedBy: 'drained' | 'max-waves' | 'signal' | 'callback' | 'budget';
     elapsed_ms: number;
+    /** Set when `stoppedBy === 'budget'` — the breach that terminated the team. */
+    budgetBreach?: BreachInfo;
 }
 /**
  * Run the continuous DAG dispatcher until the team drains, the caller

package/dist/lib/teams/supervisor.js

@@ -45,6 +45,25 @@ export async function runSupervisor(mgr, opts) {
             if (keepGoing === false) {
                 return { waves: wave, stoppedBy: 'callback', elapsed_ms: Date.now() - startedAt };
             }
+            // Live budget kill (issue #399). Poll AFTER the wave's callback so the
+            // most recent teammate stdout is already flushed to disk. On breach we
+            // stop every RUNNING teammate — the DAG effectively drains this wave.
+            if (opts.budgetWatcher) {
+                await opts.budgetWatcher.poll();
+                if (opts.budgetWatcher.breached()) {
+                    const breach = opts.budgetWatcher.breach();
+                    await mgr.stopByTask(team);
+                    if (breach && opts.onBudgetBreach)
+                        opts.onBudgetBreach(breach);
+                    opts.budgetWatcher.dispose();
+                    return {
+                        waves: wave,
+                        stoppedBy: 'budget',
+                        elapsed_ms: Date.now() - startedAt,
+                        budgetBreach: breach ?? undefined,
+                    };
+                }
+            }
             // Re-check drain AFTER the callback. The callback may have added new
             // teammates mid-flight (that's the whole point of the dynamic DAG), so
             // trusting the pre-callback snapshot would drain prematurely. Rescan

package/dist/lib/teams/worktree.d.ts

@@ -4,6 +4,15 @@ export declare function getGitRoot(dir: string): Promise<string>;
  * Check if a worktree directory has uncommitted changes.
  */
 export declare function hasUncommittedChanges(worktreePath: string): Promise<boolean>;
+/** Default cap on diff text so one giant worktree can't blow up the serve dashboard. */
+export declare const DEFAULT_DIFF_MAX_BYTES = 200000;
+/**
+ * Return the uncommitted working-tree diff for a worktree (staged + unstaged,
+ * relative to HEAD), capped so a huge diff can't overwhelm the read-only serve
+ * dashboard. Read-only: shells out to `git diff HEAD` and never mutates state.
+ * Returns '' when the path isn't a git worktree or has no pending changes.
+ */
+export declare function gitDiff(worktreePath: string, maxBytes?: number): Promise<string>;
 /**
  * Create a new git worktree for a teammate.
  *

package/dist/lib/teams/worktree.js

@@ -36,6 +36,38 @@ export async function hasUncommittedChanges(worktreePath) {
         return false;
     }
 }
+/** Default cap on diff text so one giant worktree can't blow up the serve dashboard. */
+export const DEFAULT_DIFF_MAX_BYTES = 200_000;
+/**
+ * Return the uncommitted working-tree diff for a worktree (staged + unstaged,
+ * relative to HEAD), capped so a huge diff can't overwhelm the read-only serve
+ * dashboard. Read-only: shells out to `git diff HEAD` and never mutates state.
+ * Returns '' when the path isn't a git worktree or has no pending changes.
+ */
+export async function gitDiff(worktreePath, maxBytes = DEFAULT_DIFF_MAX_BYTES) {
+    // Size the capture buffer off the cap (not an arbitrary 1MB floor) so a diff
+    // that overshoots gets TRUNCATED, never silently dropped. A diff larger than
+    // the buffer overflows maxBuffer, but Node still hands us the captured prefix
+    // on the rejection — we truncate that below rather than losing it to ''.
+    const maxBuffer = maxBytes * 4;
+    const truncate = (s) => s.slice(0, maxBytes) + `\n… [diff truncated at ${maxBytes} bytes]`;
+    try {
+        const { stdout } = await execFileAsync('git', ['diff', 'HEAD'], {
+            cwd: worktreePath,
+            maxBuffer,
+        });
+        return stdout.length > maxBytes ? truncate(stdout) : stdout;
+    }
+    catch (err) {
+        // ENOBUFS on an oversized diff still carries the partial capture; truncate
+        // it so the dashboard shows "[diff truncated]" instead of "no changes".
+        // A genuine non-git-worktree error has no stdout → fall through to ''.
+        const partial = err?.stdout;
+        if (typeof partial === 'string' && partial.length > 0)
+            return truncate(partial);
+        return '';
+    }
+}
 /**
  * Create a new git worktree for a teammate.
  *

package/dist/lib/terminal/backends/index.d.ts

@@ -5,6 +5,7 @@ import type { Backend, EngineContext, TerminalBackend } from '../types.js';
 import { itermBackend } from './iterm.js';
 import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
+import { vscodiumAgentBackend } from './vscodium-agent.js';
 /** All known interactive backends, keyed by id. */
 export declare const BACKENDS: Record<Backend, TerminalBackend>;
 /**
@@ -15,4 +16,4 @@ export declare const BACKENDS: Record<Backend, TerminalBackend>;
 export declare function detectCurrentBackend(ctx: EngineContext): Backend | null;
 /** Backends that can actually be driven in this context. */
 export declare function availableBackends(ctx: EngineContext): TerminalBackend[];
-export { itermBackend, ghosttyBackend, tmuxBackend };
+export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend };

package/dist/lib/terminal/backends/index.js

@@ -1,11 +1,13 @@
 import { itermBackend } from './iterm.js';
 import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
+import { vscodiumAgentBackend } from './vscodium-agent.js';
 /** All known interactive backends, keyed by id. */
 export const BACKENDS = {
     iterm: itermBackend,
     ghostty: ghosttyBackend,
     tmux: tmuxBackend,
+    'vscodium-agent': vscodiumAgentBackend,
 };
 /**
  * The backend for the terminal the CLI is currently running in, or null if we
@@ -26,4 +28,4 @@ export function detectCurrentBackend(ctx) {
 export function availableBackends(ctx) {
     return Object.values(BACKENDS).filter((b) => b.isAvailable(ctx));
 }
-export { itermBackend, ghosttyBackend, tmuxBackend };
+export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend };

package/dist/lib/terminal/backends/vscodium-agent.d.ts

@@ -0,0 +1,31 @@
+import type { TerminalBackend, SplitDirection } from '../types.js';
+/** An editor flavour that speaks the swarm-ext URI protocol. */
+export interface EditorVariant {
+    /** CLI on PATH, invoked with `--open-url`. */
+    cli: string;
+    /** URL scheme the product registers (must match the CLI's product). */
+    scheme: string;
+    /** macOS app bundle, for local availability detection. */
+    app: string;
+    label: string;
+}
+/**
+ * Known editors, in preference order. VSCodium first — the backend is named for
+ * it and is the user's editor; Cursor and VS Code also ship the extension and
+ * are wired here for `makeVscodiumAgentBackend` / future registration.
+ */
+export declare const EDITOR_VARIANTS: EditorVariant[];
+/**
+ * The `<scheme>://swarmify.swarm-ext/spawn?p=<payload>` URL the extension handles.
+ *
+ * The payload is base64url-encoded JSON in a single `p` param — NOT one param per
+ * field. VS Code percent-*decodes* `uri.query` once before the extension parses
+ * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
+ * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
+ * `/`), so it survives that decode untouched and round-trips exactly.
+ */
+export declare function spawnUri(scheme: string, cwd: string, command: string[], direction?: SplitDirection): string;
+/** Build a backend bound to one editor variant. */
+export declare function makeVscodiumAgentBackend(variant: EditorVariant): TerminalBackend;
+/** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */
+export declare const vscodiumAgentBackend: TerminalBackend;

package/dist/lib/terminal/backends/vscodium-agent.js

@@ -0,0 +1,72 @@
+/**
+ * VSCodium agent-terminal backend — opens an agent terminal in a VSCodium /
+ * Cursor / VS Code window via the swarmify `swarm-ext` extension's URI handler.
+ *
+ * Unlike iTerm/Ghostty (GUI terminal apps driven by AppleScript), the editor is
+ * already running; we hand it a `<scheme>://swarmify.swarm-ext/spawn?…` URL via
+ * the editor CLI's `--open-url` flag. The extension opens an editor-tab terminal
+ * in `cwd`, runs `command`, and its shell-adoption promotes a resume command
+ * (e.g. `claude --resume <id>`) to the matching agent chip. Driving the editor
+ * CLI (not macOS `open`) means this works over `--host` SSH and on Linux, needs
+ * no OS URL-scheme handler registration, and sends the command into an
+ * already-interactive login shell — so no `zsh -ilc` wrap (the other backends'
+ * wrapper) is applied here.
+ */
+import * as fs from 'fs';
+/** The swarmify extension identifier that owns the `/spawn` URI verb. */
+const EXTENSION_AUTHORITY = 'swarmify.swarm-ext';
+/**
+ * Known editors, in preference order. VSCodium first — the backend is named for
+ * it and is the user's editor; Cursor and VS Code also ship the extension and
+ * are wired here for `makeVscodiumAgentBackend` / future registration.
+ */
+export const EDITOR_VARIANTS = [
+    { cli: 'codium', scheme: 'vscodium', app: '/Applications/VSCodium.app', label: 'VSCodium' },
+    { cli: 'cursor', scheme: 'cursor', app: '/Applications/Cursor.app', label: 'Cursor' },
+    { cli: 'code', scheme: 'vscode', app: '/Applications/Visual Studio Code.app', label: 'VS Code' },
+];
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The `<scheme>://swarmify.swarm-ext/spawn?p=<payload>` URL the extension handles.
+ *
+ * The payload is base64url-encoded JSON in a single `p` param — NOT one param per
+ * field. VS Code percent-*decodes* `uri.query` once before the extension parses
+ * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
+ * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
+ * `/`), so it survives that decode untouched and round-trips exactly.
+ */
+export function spawnUri(scheme, cwd, command, direction) {
+    const payload = {
+        command: command.join(' '),
+        cwd,
+    };
+    if (direction)
+        payload.split = direction;
+    const p = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+    return `${scheme}://${EXTENSION_AUTHORITY}/spawn?p=${p}`;
+}
+/** Build a backend bound to one editor variant. */
+export function makeVscodiumAgentBackend(variant) {
+    return {
+        id: 'vscodium-agent',
+        label: `${variant.label} agent`,
+        isAvailable(ctx) {
+            return ctx.platform === 'darwin' && appExists(variant.app);
+        },
+        buildTab(cwd, command) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command)] };
+        },
+        buildSplit(cwd, command, direction) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command, direction)] };
+        },
+    };
+}
+/** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */
+export const vscodiumAgentBackend = makeVscodiumAgentBackend(EDITOR_VARIANTS[0]);

package/dist/lib/terminal/index.d.ts

@@ -8,7 +8,10 @@
  */
 export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
 export { currentContext } from './types.js';
-export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend } from './backends/index.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend } from './backends/index.js';
+export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS, type EditorVariant } from './backends/vscodium-agent.js';
 export { planLayouts, type Packing } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOptions, type OpenManyOptions, type BuildRequestsOptions, type SurfaceItem, } from './engine.js';
 export { runLocal, runRemote, runSpec, remoteCommand, type HostResolver, type RunResult } from './transport.js';
+export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, type InjectTarget, type InjectBackend, type InjectOptions, type InjectResult, } from './inject.js';
+export { resolveInjectTarget, resolveInjectTargetForSession, type InjectResolution, type InjectRail, type ResolveOptions, } from './resolve.js';

package/dist/lib/terminal/index.js

@@ -1,5 +1,8 @@
 export { currentContext } from './types.js';
-export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend } from './backends/index.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend } from './backends/index.js';
+export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS } from './backends/vscodium-agent.js';
 export { planLayouts } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';
 export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';
+export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, } from './inject.js';
+export { resolveInjectTarget, resolveInjectTargetForSession, } from './resolve.js';