@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/browser/service.js

@@ -11,7 +11,7 @@ import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime } from './runtime-state.js';
 import { resolveDomainSkill } from './domain-skills.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
-import { getRefs, resolveRefToCoords } from './refs.js';
+import { getRefs, resolveRefToCoords, describeRefs, healRef } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
@@ -412,12 +412,23 @@ export class BrowserService {
         return this.stop(taskName);
     }
     async stopProfile(profileName) {
-        const conn = this.connections.get(profileName);
-        if (conn) {
+        // Connections are keyed by the composite `<profile>@<endpoint>` (see start()),
+        // but callers pass the bare profile name (or, occasionally, an exact composite).
+        // A plain `connections.get(profileName)` therefore missed every real remote
+        // connection, so `cleanup()` never ran — leaving the SSH tunnel and, on
+        // Windows, the WMI-spawned browser orphaned on the remote host after every
+        // `browser stop --profile` (#559). Match the exact key AND every
+        // `<profileName>@<endpoint>` composite so all of a profile's live connections
+        // are torn down.
+        const keys = [...this.connections.keys()].filter((k) => k === profileName || k.startsWith(`${profileName}@`));
+        for (const key of keys) {
+            const conn = this.connections.get(key);
+            if (!conn)
+                continue;
             conn.cdp.close();
             killChrome(conn.pid);
             conn.cleanup?.();
-            this.connections.delete(profileName);
+            this.connections.delete(key);
         }
         const runtimeDir = getProfileRuntimeDir(profileName);
         const pidFile = path.join(runtimeDir, 'pid');
@@ -661,6 +672,31 @@ export class BrowserService {
             { width: 0, height: 0 };
         return { path: finalPath, bytes: buffer.length, width: dims.width, height: dims.height };
     }
+    /**
+     * Export the current tab as a PDF via CDP `Page.printToPDF`. Reuses the
+     * screenshot session + tab resolution so `--tab`, path sandboxing, and the
+     * auto-path (`sessions/<task>/<ts>.pdf`) all behave identically to
+     * `screenshot`. `printBackground: true` matches Chrome's default print flow
+     * — without it, dark-mode pages render on a blank sheet.
+     */
+    async printToPdf(taskId, tabHint, outputPath) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target) {
+            throw new Error(`Tab ${shortId} not found`);
+        }
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { data } = (await conn.cdp.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true }, sessionId));
+        const buffer = Buffer.from(data, 'base64');
+        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const automaticPath = path.join(sessionsDir, `${Date.now()}.pdf`);
+        const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
+        await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
+        await fs.promises.writeFile(finalPath, buffer);
+        return { path: finalPath, bytes: buffer.length };
+    }
     // ─── Recording ──────────────────────────────────────────────────────────────
     //
     // CDP `Page.startScreencast` emits a JPEG frame per `everyNthFrame`. We pipe
@@ -693,17 +729,25 @@ export class BrowserService {
         const outputPath = path.join(recordingsDir, `${Date.now()}.webm`);
         // Resolve ffmpeg lazily so non-recording paths don't pay the import cost.
         const { spawn } = await import('child_process');
+        // CDP `Page.startScreencast` delivers frames at a VARIABLE cadence (paints
+        // are event-driven, not clocked). Feeding those into a fixed `-framerate`
+        // input made ffmpeg assume every frame was 1/fps apart, so a page that
+        // painted slower/faster than `fps` played back at the wrong speed. Instead
+        // stamp each frame with its wall-clock arrival time
+        // (`-use_wallclock_as_timestamps 1`) and keep those timings on output
+        // (`-vsync vfr`), so playback duration matches the real capture.
         const ffmpeg = spawn('ffmpeg', [
             '-loglevel', 'error',
             '-f', 'image2pipe',
-            '-framerate', String(fps),
+            '-use_wallclock_as_timestamps', '1',
             '-i', '-',
             '-c:v', 'libvpx-vp9',
             '-b:v', '1M',
             '-pix_fmt', 'yuv420p',
+            '-vsync', 'vfr',
             '-y',
             outputPath,
-        ], { stdio: ['pipe', 'ignore', 'pipe'] });
+        ], { stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true });
         // Wait for the spawn to confirm (or fail) before we wire CDP frames into a
         // dead pipe. ENOENT from a missing ffmpeg surfaces here as a real error
         // instead of a silently empty .webm.
@@ -724,9 +768,16 @@ export class BrowserService {
             ffmpeg.once('error', onError);
             ffmpeg.once('spawn', onSpawn);
         });
-        // Surface ffmpeg's own diagnostics (encoder error, etc.) in case stderr
-        // arrives after spawn.
-        ffmpeg.stderr?.on('data', () => { });
+        // Capture ffmpeg's own diagnostics (encoder error, bad codec, etc.) so a
+        // failing encode is DIAGNOSABLE at recordStop instead of being discarded.
+        // Cap the buffer so a chatty ffmpeg can't grow it unbounded.
+        let stderrBuf = '';
+        ffmpeg.stderr?.on('data', (d) => {
+            stderrBuf += d.toString();
+            if (stderrBuf.length > 64 * 1024)
+                stderrBuf = stderrBuf.slice(-64 * 1024);
+        });
+        const ffmpegStderr = () => stderrBuf;
         ffmpeg.on('error', () => { });
         // 30 fps is CDP's screencast cap; everyNthFrame = round(30/fps).
         const everyNthFrame = Math.max(1, Math.round(30 / fps));
@@ -752,6 +803,7 @@ export class BrowserService {
             durationMs,
             maxBytes,
             ffmpeg,
+            ffmpegStderr,
             sessionId,
             conn,
             frameHandler,
@@ -795,27 +847,56 @@ export class BrowserService {
         catch {
             // session may already be gone
         }
-        // Close ffmpeg stdin so it flushes the output file cleanly.
-        await new Promise((resolve) => {
-            rec.ffmpeg.on('exit', () => resolve());
+        // Close ffmpeg stdin so it flushes the output file cleanly, and observe how
+        // it exits. A non-zero exit means the encode failed — the recording must
+        // NOT be reported as success. If ffmpeg hangs, KILL it (don't just abandon
+        // the promise, which leaked the process) and treat the recording as failed.
+        const finalize = await new Promise((resolve) => {
+            let done = false;
+            const settle = (r) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve(r);
+            };
+            const timer = setTimeout(() => {
+                try {
+                    rec.ffmpeg.kill('SIGKILL');
+                }
+                catch { /* already gone */ }
+                settle({ code: null, timedOut: true });
+            }, 5000);
+            rec.ffmpeg.once('exit', (code) => settle({ code, timedOut: false }));
             try {
                 rec.ffmpeg.stdin?.end();
             }
             catch {
-                resolve();
+                // stdin already closed; wait for exit or the hard timeout above.
             }
-            setTimeout(resolve, 5000); // Hard timeout if ffmpeg hangs
         });
+        const durationMs = Date.now() - rec.startedAt;
+        // Drop the recording from the map before any throw, so a failed stop
+        // doesn't wedge the task in a permanent "already recording" state.
+        this.recordings.delete(taskId);
+        if (finalize.timedOut) {
+            throw new Error(`ffmpeg did not exit within 5s while finalizing the recording; killed it. ` +
+                `The recording at ${rec.outputPath} is incomplete.`);
+        }
+        if (finalize.code !== 0) {
+            const err = rec.ffmpegStderr().trim();
+            throw new Error(`ffmpeg exited abnormally (code ${finalize.code}) while finalizing the recording at ` +
+                `${rec.outputPath}; the file is likely corrupt or empty.` +
+                (err ? ` ffmpeg: ${err.slice(-800)}` : ''));
+        }
         let bytes = 0;
         try {
             const st = await fs.promises.stat(rec.outputPath);
             bytes = st.size;
         }
         catch {
-            // ffmpeg may have failed; file missing
+            // ffmpeg exited 0 but the file is missing — still a failed recording.
         }
-        const durationMs = Date.now() - rec.startedAt;
-        this.recordings.delete(taskId);
         return { path: rec.outputPath, bytes, durationMs, reason };
     }
     async recordStatus(taskId) {
@@ -824,7 +905,6 @@ export class BrowserService {
             return { recording: false };
         return { recording: true, path: rec.outputPath, elapsedMs: Date.now() - rec.startedAt };
     }
-    refsCache = new Map();
     async refs(taskId, tabHint, opts = {}) {
         const { conn, task } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
@@ -833,7 +913,51 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        return getRefs(conn.cdp, sessionId, opts);
+        const result = await getRefs(conn.cdp, sessionId, opts);
+        // Snapshot the stable descriptors AND the opts they were numbered against
+        // so a later click/type can self-heal a drifted ref by rebuilding with the
+        // same filter. `refs()` is the sole owner of this cache — actions read it,
+        // never overwrite it. Persist to tasks.json so it survives a daemon
+        // restart.
+        this.cacheRefDescriptors(task, shortId, result.nodeMap, result.opts);
+        await this.saveTaskState(task.profile, conn.tasks);
+        return { refs: result.refs, nodeMap: result.nodeMap };
+    }
+    /** Record the last ref listing (descriptors + opts) for a tab into state. */
+    cacheRefDescriptors(task, shortId, nodeMap, opts) {
+        if (!task.refDescriptors)
+            task.refDescriptors = {};
+        task.refDescriptors[shortId] = { descriptors: describeRefs(nodeMap), opts };
+    }
+    /**
+     * Re-resolve a caller-supplied ref against a freshly-built node map, healing
+     * it back to the right element when the integer ref has drifted since the
+     * cached `refs` listing. Shared by `click` and `type` so both self-heal
+     * identically. Returns the ref to act on plus, when a heal occurred, the
+     * {@link HealInfo} to surface. Throws when the cached element is gone.
+     */
+    resolveHealedRef(snapshot, nodeMap, ref) {
+        const cached = snapshot?.descriptors.find((d) => d.ref === ref);
+        if (!cached)
+            return { targetRef: ref };
+        const fresh = nodeMap.get(ref);
+        const stillMatches = fresh !== undefined &&
+            fresh.role === cached.role &&
+            fresh.name === cached.name &&
+            fresh.backendNodeId !== undefined;
+        if (stillMatches)
+            return { targetRef: ref };
+        const newRef = healRef(cached, nodeMap);
+        if (newRef === null) {
+            throw new Error(`Ref ${ref} (${cached.role} "${cached.name}") could not be re-resolved: ` +
+                `no matching element on the current page. Re-run 'browser refs' to ` +
+                `refresh the ref numbers, or act by position with 'browser click --at X,Y'.`);
+        }
+        if (newRef === ref)
+            return { targetRef: ref };
+        console.error(`[browser] self-healed ref ${ref} -> ${newRef} (${cached.role} "${cached.name}") — ` +
+            `cached descriptor re-matched after the ref drifted`);
+        return { targetRef: newRef, healed: { from: ref, to: newRef, role: cached.role, name: cached.name } };
     }
     async click(taskId, ref, tabHint) {
         const { conn, task } = await this.findTask(taskId);
@@ -843,8 +967,38 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
-        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
+        // Rebuild the node map with the SAME opts the cached listing was numbered
+        // against, so the caller's ref lands on the element they saw in `browser
+        // refs`. Rebuilding with a different filter (the old interactive:false)
+        // renumbers every ref and defeats self-heal on the second click. Default
+        // to the user-facing interactive numbering when no listing was cached yet.
+        const snapshot = task.refDescriptors?.[shortId];
+        const buildOpts = snapshot?.opts ?? { interactive: true, limit: 500 };
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, buildOpts);
+        // Self-heal: the integer ref is positional and drifts on re-render. If the
+        // fresh node at this position no longer matches the cached descriptor,
+        // re-resolve (by attrs/proximity-tie-broken role+name) BEFORE clicking the
+        // wrong element. The cache is owned by refs() and NOT rewritten here — the
+        // caller's ref numbers stay anchored to the listing they came from.
+        const { targetRef, healed } = this.resolveHealedRef(snapshot, nodeMap, ref);
+        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, targetRef);
+        await clickAtCoords(conn.cdp, sessionId, x, y);
+        return healed ? { healed } : {};
+    }
+    /**
+     * Click raw viewport coordinates, bypassing ref resolution entirely. Backs
+     * `browser click --at X,Y` — the escape hatch when the accessibility tree
+     * exposes no usable ref (canvas apps, custom-drawn UI) and the caller has
+     * located the target from a screenshot.
+     */
+    async clickAt(taskId, x, y, tabHint) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target)
+            throw new Error(`Tab ${shortId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
         await clickAtCoords(conn.cdp, sessionId, x, y);
     }
     async type(taskId, ref, text, tabHint, clear) {
@@ -855,8 +1009,14 @@ export class BrowserService {
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
-        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
-        const node = nodeMap.get(ref);
+        // Same self-healing story as click(): rebuild against the cached listing's
+        // opts so refs line up with what the user saw, then heal a drifted ref
+        // before typing into the wrong field.
+        const snapshot = task.refDescriptors?.[shortId];
+        const buildOpts = snapshot?.opts ?? { interactive: true, limit: 500 };
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, buildOpts);
+        const { targetRef } = this.resolveHealedRef(snapshot, nodeMap, ref);
+        const node = nodeMap.get(targetRef);
         if (!node)
             throw new Error(`Ref ${ref} not found`);
         if (node.editor) {

package/dist/lib/browser/types.d.ts

@@ -78,6 +78,15 @@ export interface Task {
     currentTabId?: string;
     createdAt: number;
     pid: number;
+    /**
+     * Per-tab snapshot of the last ref listing captured for that tab
+     * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
+     * `click`/`type <ref>` can self-heal a drifted ref — the cached `opts` let
+     * the action rebuild its node map with the SAME accessibility filter the
+     * listing was numbered against. Owned by `refs()`; actions never overwrite
+     * it. See RefSnapshot / RefDescriptor.
+     */
+    refDescriptors?: Record<string, import('./refs.js').RefSnapshot>;
 }
 export interface TabInfo {
     id: string;
@@ -118,7 +127,7 @@ export interface HistoricalTask {
     domains: string[];
     tabCount: number;
 }
-export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -129,6 +138,8 @@ export interface IPCRequest {
     expr?: string;
     path?: string;
     ref?: number;
+    atX?: number;
+    atY?: number;
     text?: string;
     key?: string;
     scrollX?: number;
@@ -194,6 +205,8 @@ export interface IPCResponse {
     height?: number;
     refs?: string;
     nodes?: RefNodeJson[];
+    /** Human-readable note surfaced to the CLI (e.g. a self-heal notice on click). */
+    message?: string;
     port?: number;
     pid?: number;
     fps?: number;

package/dist/lib/budget/live-cloud.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Live budget kill-switch for `agents cloud` dispatch (issue #399).
+ *
+ * Follow-up to #346, which shipped a pre-flight budget gate for cloud runs but
+ * no live mid-run enforcement — a runaway cloud task would keep spending until
+ * the user hit Ctrl-C. This wires the same `makeLiveSpendWatcher` the local
+ * headless run uses (src/lib/exec.ts) into the cloud SSE stream: each `usage`
+ * event from the provider feeds the watcher, and on breach we call
+ * `provider.cancel(taskId)` to terminate server-side.
+ *
+ * Wrapper shape mirrors `renderStream`'s input — it takes an
+ * `AsyncIterable<CloudEvent>` and yields the same events downstream. Dormant
+ * (returns the source stream unchanged) when no caps are configured.
+ */
+import type { CloudProvider, CloudEvent } from '../cloud/types.js';
+import { type BreachInfo } from './enforce.js';
+/** Result surface exposed to the caller so it can act on a mid-stream breach. */
+export interface CloudBudgetGate {
+    /** True once a cap crossed and cancel() was invoked. */
+    breached(): boolean;
+    breach(): BreachInfo | null;
+}
+/**
+ * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
+ * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
+ * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
+ * shows why the task stopped. Returns null when no caps are configured; callers
+ * fall through to the raw stream in that case.
+ */
+export declare function wrapStreamWithBudgetGate(args: {
+    provider: CloudProvider;
+    taskId: string;
+    /** Project attribution key — repo slug for Rush, or cwd. */
+    project: string;
+    /** Agent the dispatch runs under (for per_agent cap accounting). */
+    agent: string;
+    /** cwd used to resolve the effective budget config. */
+    cwd?: string;
+}): {
+    wrap: (source: AsyncIterable<CloudEvent>) => AsyncIterable<CloudEvent>;
+    gate: CloudBudgetGate;
+} | null;

package/dist/lib/budget/live-cloud.js

@@ -0,0 +1,79 @@
+import { capsFromConfig, makeLiveSpendWatcher, } from './enforce.js';
+import { resolveBudgetConfig, hasAnyCap } from './config.js';
+import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
+/**
+ * Wrap a cloud event stream with a live budget watcher. On a `usage` event we
+ * feed the shared watcher; on the first breach we call `provider.cancel(taskId)`
+ * and forward a synthetic `status:'cancelled'` + `error` frame so the renderer
+ * shows why the task stopped. Returns null when no caps are configured; callers
+ * fall through to the raw stream in that case.
+ */
+export function wrapStreamWithBudgetGate(args) {
+    const cfg = resolveBudgetConfig(args.cwd);
+    if (!hasAnyCap(cfg))
+        return null;
+    const today = localDay();
+    const entries = loadLedger();
+    const caps = capsFromConfig(cfg, {
+        daySpend: spendForDay(today, entries),
+        projectSpend: spendForProject(args.project, entries),
+    });
+    let firstBreach = null;
+    const watcher = makeLiveSpendWatcher({
+        caps,
+        onBreach: (b) => {
+            firstBreach = b;
+        },
+    });
+    async function* wrap(source) {
+        try {
+            for await (const event of source) {
+                if (event.type === 'usage') {
+                    watcher.feedUsage({
+                        agent: args.agent,
+                        model: event.model,
+                        inputTokens: event.inputTokens ?? 0,
+                        outputTokens: event.outputTokens ?? 0,
+                    });
+                    if (watcher.breached() && firstBreach) {
+                        // Cancel server-side FIRST so we stop the meter; then surface the
+                        // breach to the renderer as an error + cancelled status so the CLI
+                        // exits with a visible reason (not a silent stream close).
+                        try {
+                            await args.provider.cancel(args.taskId);
+                        }
+                        catch (err) {
+                            // Best-effort — even if cancel fails, break the stream: the
+                            // caller sees the error frame and can retry manually.
+                            yield {
+                                type: 'error',
+                                message: `[budget] cap ${firstBreach.cap} exceeded ($${firstBreach.spend.toFixed(2)} > $${firstBreach.limit.toFixed(2)}); cancel FAILED: ${err.message}`,
+                                timestamp: new Date().toISOString(),
+                            };
+                            yield { type: 'status', status: 'cancelled', timestamp: new Date().toISOString() };
+                            return;
+                        }
+                        yield {
+                            type: 'error',
+                            message: `[budget] cap ${firstBreach.cap} exceeded ($${firstBreach.spend.toFixed(2)} > $${firstBreach.limit.toFixed(2)}) — cancelled cloud task ${args.taskId}`,
+                            timestamp: new Date().toISOString(),
+                        };
+                        yield { type: 'status', status: 'cancelled', timestamp: new Date().toISOString() };
+                        return;
+                    }
+                }
+                yield event;
+            }
+        }
+        finally {
+            watcher.dispose();
+        }
+    }
+    return {
+        wrap,
+        gate: {
+            breached: () => watcher.breached(),
+            breach: () => firstBreach,
+        },
+    };
+}

package/dist/lib/budget/live-team.d.ts

@@ -0,0 +1,31 @@
+import type { AgentManager } from '../teams/agents.js';
+import { type BreachInfo } from './enforce.js';
+/** Public surface of the team-scoped budget watcher. */
+export interface TeamBudgetWatcher {
+    /** Feed any new usage events from every running teammate's stdout.log. */
+    poll(): Promise<void>;
+    /** True once any cap has been crossed (mirrors LiveSpendWatcher). */
+    breached(): boolean;
+    /** The first breach seen, or null if none yet. */
+    breach(): BreachInfo | null;
+    /** Release references and stop tapping streams. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Build a team-scoped budget watcher for the given team. Returns null when the
+ * effective budget config has no caps — matching the local watcher's dormant
+ * contract so callers pay nothing when the feature is off.
+ *
+ * The watcher is seeded with prior-day and prior-project spend from the ledger
+ * so a partway-through day counts today's earlier runs against `per_day`.
+ * Each `poll()` reads new bytes from every running teammate's stdout.log and
+ * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
+ * once, mirroring `makeLiveSpendWatcher`.
+ */
+export declare function createTeamBudgetWatcher(args: {
+    manager: AgentManager;
+    team: string;
+    /** Project/cwd used to (a) resolve budget config and (b) seed project spend. */
+    cwd: string;
+    onBreach: (breach: BreachInfo) => void;
+}): TeamBudgetWatcher | null;

package/dist/lib/budget/live-team.js

@@ -0,0 +1,115 @@
+/**
+ * Live budget kill-switch for `agents teams` supervisor (issue #399).
+ *
+ * Follow-up to #346, which wired `makeLiveSpendWatcher` into local `agents run`
+ * only. Teams spawns each teammate as its own `agents run --headless --json`
+ * process, so per-teammate `per_run` caps already fire from those child
+ * watchers. What was still missing was aggregate cross-teammate enforcement
+ * (`per_project` / `per_day` / `per_agent` combined), because the ledger only
+ * gets written on child close — a long-running teammate would blow the shared
+ * cap without any single child watcher noticing.
+ *
+ * This module reuses `makeLiveSpendWatcher` verbatim: on each supervisor wave
+ * we tail every running teammate's stdout.log through `extractUsageEvents`
+ * (the same primitive the local run path uses in src/lib/exec.ts), feed the
+ * usage events into ONE shared watcher, and expose `breached()` so the
+ * supervisor can call `stopByTask` to terminate the whole team.
+ *
+ * Dormant (returns null) when no caps are configured — same zero-cost contract
+ * as the local watcher.
+ */
+import * as fs from 'fs';
+import { capsFromConfig, extractUsageEvents, makeLiveSpendWatcher, } from './enforce.js';
+import { resolveBudgetConfig, hasAnyCap } from './config.js';
+import { loadLedger, localDay, spendForDay, spendForProject } from './ledger.js';
+/**
+ * Build a team-scoped budget watcher for the given team. Returns null when the
+ * effective budget config has no caps — matching the local watcher's dormant
+ * contract so callers pay nothing when the feature is off.
+ *
+ * The watcher is seeded with prior-day and prior-project spend from the ledger
+ * so a partway-through day counts today's earlier runs against `per_day`.
+ * Each `poll()` reads new bytes from every running teammate's stdout.log and
+ * feeds parsed usage events into the shared watcher — `onBreach` fires exactly
+ * once, mirroring `makeLiveSpendWatcher`.
+ */
+export function createTeamBudgetWatcher(args) {
+    const cfg = resolveBudgetConfig(args.cwd);
+    if (!hasAnyCap(cfg))
+        return null;
+    const today = localDay();
+    const entries = loadLedger();
+    const caps = capsFromConfig(cfg, {
+        daySpend: spendForDay(today, entries),
+        projectSpend: spendForProject(args.cwd, entries),
+    });
+    let firstBreach = null;
+    const watcher = makeLiveSpendWatcher({
+        caps,
+        onBreach: (b) => {
+            firstBreach = b;
+            args.onBreach(b);
+        },
+    });
+    const cursors = new Map();
+    let disposed = false;
+    return {
+        async poll() {
+            if (disposed || watcher.breached())
+                return;
+            const teammates = await args.manager.listByTask(args.team);
+            for (const agent of teammates) {
+                // Only tap running local teammates: PENDING has no output yet, cloud
+                // teammates emit through a different channel (their own SSE stream),
+                // and terminal states produce no new bytes.
+                if (agent.status !== 'running')
+                    continue;
+                if (agent.cloudProvider)
+                    continue;
+                const stdoutPath = await agent.getStdoutPath();
+                let stat;
+                try {
+                    stat = fs.statSync(stdoutPath);
+                }
+                catch {
+                    continue; // File not yet created — nothing to read.
+                }
+                const cursor = cursors.get(agent.agentId) ?? { offset: 0, pending: '' };
+                if (stat.size <= cursor.offset) {
+                    cursors.set(agent.agentId, cursor);
+                    continue;
+                }
+                const fd = fs.openSync(stdoutPath, 'r');
+                try {
+                    const toRead = stat.size - cursor.offset;
+                    const buffer = Buffer.alloc(toRead);
+                    const bytesRead = fs.readSync(fd, buffer, 0, toRead, cursor.offset);
+                    const chunk = buffer.toString('utf-8', 0, bytesRead);
+                    cursor.offset += bytesRead;
+                    const { events, rest } = extractUsageEvents(chunk, cursor.pending, undefined, agent.agentType);
+                    cursor.pending = rest;
+                    for (const ev of events) {
+                        watcher.feedUsage(ev);
+                        if (watcher.breached())
+                            break;
+                    }
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                cursors.set(agent.agentId, cursor);
+                if (watcher.breached())
+                    return;
+            }
+        },
+        breached: () => watcher.breached(),
+        breach: () => firstBreach,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            watcher.dispose();
+            cursors.clear();
+        },
+    };
+}

package/dist/lib/cloud/codex.js

@@ -104,6 +104,10 @@ export class CodexCloudProvider {
             cancel: false,
             message: false,
             multiRepo: false,
+            // `codex cloud exec --env <id> <prompt>` is the only dispatch surface the
+            // codex CLI exposes — it has no flag to attach images or ride-along skills,
+            // and the env bundles its own context at creation time. Both stay false
+            // until the upstream CLI grows an attachment surface.
             skills: false,
             images: false,
         };

package/dist/lib/cloud/rush.d.ts

@@ -4,7 +4,7 @@
  * Auth: reads the session token from ~/.rush/user.yaml (written by `rush login`).
  * Requires the Rush GitHub App installed on the target repo.
  */
-import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities, ImageAttachment, SkillRef } from './types.js';
 export declare const RUSH_CONSENT_PATH: string;
 export declare function hasRushUploadConsent(accountFingerprint: string, opts?: DispatchOptions, consentPath?: string): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
@@ -63,6 +63,17 @@ export declare function buildDispatchBody(input: {
     }>;
     accountManifest?: AccountManifest | null;
     accountTokens?: AccountTokenEntry[] | null;
+    /**
+     * Skill ride-alongs so the cloud pod isn't context-blind. Forwarded verbatim
+     * as `skills` so the Factory Floor can mount them by id/version before the
+     * agent runs. Omitted when empty.
+     */
+    skills?: SkillRef[] | null;
+    /**
+     * Base64 image attachments for vision dispatch. Sliced to
+     * MAX_IMAGES_PER_DISPATCH — extras are dropped, never sent. Omitted when empty.
+     */
+    images?: ImageAttachment[] | null;
 }): Record<string, unknown>;
 /** A single account registered in Rush Cloud's multi-account rotation pool. */
 export interface RemoteAccount {