@phnx-labs/agents-cli 1.20.34 → 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/registry.js

@@ -13,6 +13,7 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getTeamsRegistryPath } from '../state.js';
+import { emit } from '../events.js';
 async function registryPath() {
     return getTeamsRegistryPath();
 }
@@ -98,39 +99,50 @@ export async function createTeam(name, options) {
         throw new Error('Cannot use both --enable-worktrees and --use-worktree. Pick one.');
     }
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    const meta = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (reg[name]) {
             throw new Error(`Team '${name}' already exists`);
         }
-        const meta = {
+        const m = {
             created_at: new Date().toISOString(),
             ...(options?.description ? { description: options.description } : {}),
             ...(options?.enableWorktrees ? { enable_worktrees: true } : {}),
             ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
         };
-        reg[name] = meta;
+        reg[name] = m;
         await saveTeams(reg);
-        return meta;
+        return m;
     });
+    // Audit the lifecycle boundary, not the CLI shell — captures every creation
+    // path (create + ensure) with team metadata the generic command log lacks.
+    emit('teams.create', { module: 'teams', team: name, worktrees: Boolean(options?.enableWorktrees || options?.useWorktree) });
+    return meta;
 }
 /** Return existing team metadata or create a new team if it does not exist. */
 export async function ensureTeam(name) {
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    let created = false;
+    const meta = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (reg[name])
             return reg[name];
-        const meta = { created_at: new Date().toISOString() };
-        reg[name] = meta;
+        const m = { created_at: new Date().toISOString() };
+        reg[name] = m;
         await saveTeams(reg);
-        return meta;
+        created = true;
+        return m;
     });
+    // `teams add` auto-creates the team on first teammate — audit that creation
+    // too, but only when it actually happened (not the get-existing path).
+    if (created)
+        emit('teams.create', { module: 'teams', team: name, worktrees: false });
+    return meta;
 }
 /** Remove a team from the registry. Returns false if the team did not exist. */
 export async function removeTeam(name) {
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    const existed = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (!reg[name])
             return false;
@@ -138,6 +150,10 @@ export async function removeTeam(name) {
         await saveTeams(reg);
         return true;
     });
+    // "Disband" — only fires when a real team was removed, not a no-op.
+    if (existed)
+        emit('teams.disband', { module: 'teams', team: name });
+    return existed;
 }
 /** Check whether a team with the given name exists in the registry. */
 export async function teamExists(name) {

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/ghostty.d.ts

@@ -0,0 +1,6 @@
+import type { TerminalBackend, SplitDirection } from '../types.js';
+/** AppleScript that opens a Ghostty tab (a window if none is open). */
+export declare function ghosttyTabScript(cwd: string, command: string[]): string;
+/** AppleScript that splits the current Ghostty surface (a window if none is open). */
+export declare function ghosttySplitScript(cwd: string, command: string[], direction: SplitDirection): string;
+export declare const ghosttyBackend: TerminalBackend;

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

@@ -0,0 +1,69 @@
+/**
+ * Ghostty backend — drives Ghostty (>= 1.3) via AppleScript (`osascript`).
+ *
+ * Ghostty's `new surface configuration` record carries the working directory and
+ * command natively, so no `cd` wrapper is needed. Tab: `new tab` (or a window
+ * when none is open). Split: `split <surface> direction right|down`, where the
+ * current surface is `focused terminal of selected tab of front window`
+ * (verified against Ghostty 1.3.1 — a surface is a "terminal" in its AS model).
+ */
+import * as fs from 'fs';
+import { appleScriptStr } from '../quote.js';
+import { execOnly, iLoginShell } from '../shell.js';
+const GHOSTTY_APP = '/Applications/Ghostty.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** Shared prologue: activate + a surface configuration carrying cwd + command. */
+function configPrologue(cwd, command) {
+    const cmd = appleScriptStr(iLoginShell(execOnly(command)));
+    return [
+        'tell application "Ghostty"',
+        '  activate',
+        '  set cfg to new surface configuration',
+        `  set initial working directory of cfg to ${appleScriptStr(cwd)}`,
+        `  set command of cfg to ${cmd}`,
+    ];
+}
+/** AppleScript that opens a Ghostty tab (a window if none is open). */
+export function ghosttyTabScript(cwd, command) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        '    new tab in front window with configuration cfg',
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+/** AppleScript that splits the current Ghostty surface (a window if none is open). */
+export function ghosttySplitScript(cwd, command, direction) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        `    split (focused terminal of selected tab of front window) direction ${direction} with configuration cfg`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const ghosttyBackend = {
+    id: 'ghostty',
+    label: 'Ghostty',
+    isAvailable(ctx) {
+        return ctx.platform === 'darwin' && appExists(GHOSTTY_APP);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', ghosttyTabScript(cwd, command)] };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: ['osascript', '-e', ghosttySplitScript(cwd, command, direction)] };
+    },
+};

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

@@ -0,0 +1,19 @@
+/**
+ * Backend registry + current-terminal detection.
+ */
+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>;
+/**
+ * The backend for the terminal the CLI is currently running in, or null if we
+ * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
+ * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
+ */
+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, vscodiumAgentBackend };