@phnx-labs/agents-cli 1.20.50 → 1.20.51

package/dist/lib/auto-dispatch-linear.js

@@ -0,0 +1,107 @@
+/**
+ * Concrete Linear gateway for auto-dispatch.
+ *
+ * Talks to the Linear GraphQL API. The API key is read from the LINEAR_API_KEY
+ * env var, falling back to the macOS keychain generic-password `linear-api-key`
+ * (how the rest of the stack stores it). If no key is resolvable, the gateway is
+ * absent and the daemon skips auto-dispatch entirely.
+ *
+ * "Started" (Doing) and "unstarted" (Todo) are Linear state *types*, so we never
+ * hardcode a team's custom state names. `startIssue` resolves the team's first
+ * started-type state (cached per team) and moves the issue there — the existing
+ * factory webhook turns that transition into a real run.
+ */
+import { execFileSync } from 'child_process';
+const LINEAR_API = 'https://api.linear.app/graphql';
+/** Resolve the Linear API key from env or (on macOS) the keychain. Null if absent. */
+export function resolveLinearApiKey() {
+    const fromEnv = process.env.LINEAR_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (process.platform === 'darwin') {
+        try {
+            const out = execFileSync('security', ['find-generic-password', '-s', 'linear-api-key', '-w'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            const key = out.trim();
+            if (key)
+                return key;
+        }
+        catch {
+            // not in keychain — fall through
+        }
+    }
+    return null;
+}
+async function gql(apiKey, query, variables) {
+    const res = await fetch(LINEAR_API, {
+        method: 'POST',
+        headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ query, variables }),
+    });
+    if (!res.ok)
+        throw new Error(`Linear API HTTP ${res.status}`);
+    const json = (await res.json());
+    if (json.errors?.length)
+        throw new Error(`Linear API: ${json.errors.map((e) => e.message).join('; ')}`);
+    if (!json.data)
+        throw new Error('Linear API: empty response');
+    return json.data;
+}
+/** Build a real Linear gateway, or null when no API key is configured. */
+export function createLinearGateway() {
+    const apiKey = resolveLinearApiKey();
+    if (!apiKey)
+        return null;
+    // Cache the resolved started-state id per team so we don't re-query each dispatch.
+    const startedStateByTeam = new Map();
+    async function resolveStartedState(teamId) {
+        const cached = startedStateByTeam.get(teamId);
+        if (cached)
+            return cached;
+        const data = await gql(apiKey, `query($t:String!){ workflowStates(filter:{ team:{ id:{ eq:$t } }, type:{ eq:"started" } }, first:10){ nodes{ id type position } } }`, { t: teamId });
+        const nodes = data.workflowStates.nodes.slice().sort((a, b) => a.position - b.position);
+        const state = nodes[0];
+        if (!state)
+            throw new Error(`no started-type workflow state for team ${teamId}`);
+        startedStateByTeam.set(teamId, state.id);
+        return state.id;
+    }
+    // team id per issue, captured during fetchDelegatedTodo, so startIssue can resolve state.
+    const teamByIssue = new Map();
+    return {
+        async countInFlight(linearProjectId) {
+            const data = await gql(apiKey, `query($p:ID!){ issues(filter:{ project:{ id:{ eq:$p } }, state:{ type:{ eq:"started" } }, delegate:{ null:false } }, first:250){ nodes{ id } } }`, { p: linearProjectId });
+            return data.issues.nodes.length;
+        },
+        async fetchDelegatedTodo(linearProjectId) {
+            const data = await gql(apiKey, `query($p:ID!){ issues(filter:{ project:{ id:{ eq:$p } }, state:{ type:{ eq:"unstarted" } }, delegate:{ null:false } }, first:50){ nodes{ id identifier title priority delegate{ name } team{ id } } } }`, { p: linearProjectId });
+            const out = [];
+            for (const n of data.issues.nodes) {
+                if (!n.delegate?.name)
+                    continue;
+                if (n.team?.id)
+                    teamByIssue.set(n.id, n.team.id);
+                out.push({ id: n.id, identifier: n.identifier, title: n.title ?? '', priority: n.priority ?? 0, delegateName: n.delegate.name });
+            }
+            return out;
+        },
+        async markStarted(issueId, delegateName) {
+            const teamId = teamByIssue.get(issueId);
+            if (!teamId)
+                throw new Error(`unknown team for issue ${issueId} (fetch it first)`);
+            const stateId = await resolveStartedState(teamId);
+            const data = await gql(apiKey, `mutation($id:String!,$s:String!){ issueUpdate(id:$id, input:{ stateId:$s }){ success } }`, { id: issueId, s: stateId });
+            if (!data.issueUpdate.success)
+                throw new Error(`issueUpdate failed for ${issueId}`);
+            // Leave a trail so the auto-dispatch is visible in the ticket history.
+            try {
+                await gql(apiKey, `mutation($i:String!,$b:String!){ commentCreate(input:{ issueId:$i, body:$b }){ success } }`, { i: issueId, b: `Auto-dispatched to **${delegateName}** by the factory (moved Todo → Doing).` });
+            }
+            catch {
+                // comment is best-effort — the state change is what matters
+            }
+        },
+    };
+}

package/dist/lib/auto-dispatch-provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Concrete Dispatcher for auto-dispatch — runs a ticket through agents-cli's own
+ * cloud-provider abstraction (`resolveProvider().dispatch()`), the same layer as
+ * `agents cloud run`. Rush (Prix) is one provider among rush/codex/factory; a
+ * project pins its provider via `provider` in projects.json, else the delegate
+ * agent's native cloud is used. This is what removes the hidden Prix coupling —
+ * auto-dispatch no longer depends on the prix/api webhook.
+ */
+import type { Dispatcher } from './auto-dispatch.js';
+export declare function createProviderDispatcher(): Dispatcher;

package/dist/lib/auto-dispatch-provider.js

@@ -0,0 +1,25 @@
+/**
+ * Concrete Dispatcher for auto-dispatch — runs a ticket through agents-cli's own
+ * cloud-provider abstraction (`resolveProvider().dispatch()`), the same layer as
+ * `agents cloud run`. Rush (Prix) is one provider among rush/codex/factory; a
+ * project pins its provider via `provider` in projects.json, else the delegate
+ * agent's native cloud is used. This is what removes the hidden Prix coupling —
+ * auto-dispatch no longer depends on the prix/api webhook.
+ */
+import { resolveProvider } from './cloud/registry.js';
+export function createProviderDispatcher() {
+    return {
+        async dispatch({ agent, prompt, repo, provider }) {
+            const p = resolveProvider(provider, agent);
+            const caps = p.capabilities();
+            if (!caps.available) {
+                throw new Error(`cloud provider '${p.id}' is not available (auth/binary missing)`);
+            }
+            if (!caps.dispatch) {
+                throw new Error(`cloud provider '${p.id}' does not support dispatch`);
+            }
+            const task = await p.dispatch({ agent, prompt, repo });
+            return { id: task.id };
+        },
+    };
+}

package/dist/lib/auto-dispatch.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Auto-dispatch — pull side of the factory dispatch loop.
+ *
+ * Polls Linear for issues that are delegated to an agent and still in Todo for a
+ * managed project, and — up to a per-project concurrency cap — DISPATCHES each
+ * through agents-cli's own cloud-provider abstraction (`resolveProvider().dispatch()`),
+ * then marks the ticket Doing so it isn't picked up twice.
+ *
+ * The dispatch goes through the same provider layer as `agents cloud run`, so Rush
+ * (Prix) is just one provider among rush/codex/factory — NOT a hidden requirement.
+ * A project may pin its provider via `provider` in ~/.agents/factory/projects.json.
+ *
+ * OPT-IN: a project auto-dispatches ONLY when `autoDispatch: true` AND `maxAgents > 0`.
+ * Nothing global is on by default.
+ */
+/** The subset of a managed project this module needs (mirror of the shared JSON). */
+export interface AutoDispatchProject {
+    id: string;
+    name: string;
+    linearProjectId?: string;
+    repoSlug?: string;
+    autoDispatch?: boolean;
+    maxAgents?: number;
+    provider?: string;
+}
+/** A Linear issue that is a candidate for dispatch. */
+export interface DelegatedIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    delegateName: string;
+    priority: number;
+}
+/** One planned dispatch: which issue, to which agent, in which project. */
+export interface PlannedDispatch {
+    projectId: string;
+    repoSlug?: string;
+    provider?: string;
+    issueId: string;
+    identifier: string;
+    title: string;
+    delegateName: string;
+}
+/** Path to the shared factory project registry (written by the factory UI). */
+export declare function factoryProjectsPath(): string;
+/** Read the project registry rows this module cares about. */
+export declare function readAutoDispatchProjects(): AutoDispatchProject[];
+/** A project is eligible only when it has explicitly opted in with a positive cap. */
+export declare function isEligible(p: AutoDispatchProject): boolean;
+/**
+ * PURE planner. Given eligible projects, in-flight counts, and delegated-Todo
+ * issues per project, decide which issues to dispatch — never exceeding
+ * `maxAgents` in-flight. Highest Linear priority first.
+ */
+export declare function planAutoDispatch(projects: AutoDispatchProject[], inFlightByProject: Record<string, number>, delegatedTodoByProject: Record<string, DelegatedIssue[]>): PlannedDispatch[];
+/** Map Linear priority to a sortable rank (urgent first, none last). */
+export declare function priorityRank(priority: number): number;
+/** Build the prompt an auto-dispatched agent receives for a ticket. */
+export declare function dispatchPrompt(identifier: string, title: string): string;
+/** Linear I/O surface — discovery + bookkeeping (NOT the dispatch trigger). */
+export interface LinearGateway {
+    /** Count issues in a started ("Doing") state whose delegate is set, per project. */
+    countInFlight(linearProjectId: string): Promise<number>;
+    /** Fetch delegated issues in an unstarted ("Todo") state for a project. */
+    fetchDelegatedTodo(linearProjectId: string): Promise<DelegatedIssue[]>;
+    /** After a successful dispatch: move the issue Todo -> Doing so it isn't re-picked. */
+    markStarted(issueId: string, delegateName: string): Promise<void>;
+}
+/** Dispatch surface — runs a ticket through agents-cli's cloud/local provider layer. */
+export interface Dispatcher {
+    dispatch(opts: {
+        agent: string;
+        prompt: string;
+        repo?: string;
+        provider?: string;
+    }): Promise<{
+        id: string;
+    }>;
+}
+export interface AutoDispatchDeps {
+    projects: AutoDispatchProject[];
+    linear: LinearGateway;
+    dispatcher: Dispatcher;
+    log?: (level: 'INFO' | 'WARN' | 'ERROR', msg: string) => void;
+}
+/** One tick: read state per eligible project, plan, dispatch, then mark started. */
+export declare function autoDispatchTick(deps: AutoDispatchDeps): Promise<PlannedDispatch[]>;

package/dist/lib/auto-dispatch.js

@@ -0,0 +1,142 @@
+/**
+ * Auto-dispatch — pull side of the factory dispatch loop.
+ *
+ * Polls Linear for issues that are delegated to an agent and still in Todo for a
+ * managed project, and — up to a per-project concurrency cap — DISPATCHES each
+ * through agents-cli's own cloud-provider abstraction (`resolveProvider().dispatch()`),
+ * then marks the ticket Doing so it isn't picked up twice.
+ *
+ * The dispatch goes through the same provider layer as `agents cloud run`, so Rush
+ * (Prix) is just one provider among rush/codex/factory — NOT a hidden requirement.
+ * A project may pin its provider via `provider` in ~/.agents/factory/projects.json.
+ *
+ * OPT-IN: a project auto-dispatches ONLY when `autoDispatch: true` AND `maxAgents > 0`.
+ * Nothing global is on by default.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { homedir } from 'os';
+/** Path to the shared factory project registry (written by the factory UI). */
+export function factoryProjectsPath() {
+    return path.join(homedir(), '.agents', 'factory', 'projects.json');
+}
+/** Read the project registry rows this module cares about. */
+export function readAutoDispatchProjects() {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(factoryProjectsPath(), 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const r of raw) {
+        if (!r || typeof r !== 'object')
+            continue;
+        const o = r;
+        if (typeof o.id !== 'string' || typeof o.name !== 'string')
+            continue;
+        out.push({
+            id: o.id,
+            name: o.name,
+            linearProjectId: typeof o.linearProjectId === 'string' ? o.linearProjectId : undefined,
+            repoSlug: typeof o.repoSlug === 'string' ? o.repoSlug : undefined,
+            autoDispatch: o.autoDispatch === true,
+            maxAgents: typeof o.maxAgents === 'number' ? o.maxAgents : undefined,
+            provider: typeof o.provider === 'string' ? o.provider : undefined,
+        });
+    }
+    return out;
+}
+/** A project is eligible only when it has explicitly opted in with a positive cap. */
+export function isEligible(p) {
+    return p.autoDispatch === true && typeof p.maxAgents === 'number' && p.maxAgents > 0 && !!p.linearProjectId;
+}
+/**
+ * PURE planner. Given eligible projects, in-flight counts, and delegated-Todo
+ * issues per project, decide which issues to dispatch — never exceeding
+ * `maxAgents` in-flight. Highest Linear priority first.
+ */
+export function planAutoDispatch(projects, inFlightByProject, delegatedTodoByProject) {
+    const plan = [];
+    for (const p of projects) {
+        if (!isEligible(p))
+            continue;
+        const cap = p.maxAgents;
+        const slots = cap - (inFlightByProject[p.id] ?? 0);
+        if (slots <= 0)
+            continue;
+        const candidates = (delegatedTodoByProject[p.id] ?? [])
+            .slice()
+            .sort((a, b) => priorityRank(a.priority) - priorityRank(b.priority));
+        for (const issue of candidates.slice(0, slots)) {
+            plan.push({
+                projectId: p.id,
+                repoSlug: p.repoSlug,
+                provider: p.provider,
+                issueId: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                delegateName: issue.delegateName,
+            });
+        }
+    }
+    return plan;
+}
+/** Map Linear priority to a sortable rank (urgent first, none last). */
+export function priorityRank(priority) {
+    return priority === 0 ? 5 : priority;
+}
+/** Build the prompt an auto-dispatched agent receives for a ticket. */
+export function dispatchPrompt(identifier, title) {
+    return `Work on Linear ticket ${identifier}: ${title}. Read the ticket for full context, implement it, and open a PR when done.`;
+}
+/** One tick: read state per eligible project, plan, dispatch, then mark started. */
+export async function autoDispatchTick(deps) {
+    const log = deps.log ?? (() => { });
+    const eligible = deps.projects.filter(isEligible);
+    if (eligible.length === 0)
+        return [];
+    const inFlight = {};
+    const todo = {};
+    for (const p of eligible) {
+        const pid = p.linearProjectId;
+        try {
+            inFlight[p.id] = await deps.linear.countInFlight(pid);
+            todo[p.id] = await deps.linear.fetchDelegatedTodo(pid);
+        }
+        catch (err) {
+            log('WARN', `auto-dispatch: failed to read Linear state for '${p.name}': ${err.message}`);
+            inFlight[p.id] = Number.MAX_SAFE_INTEGER; // fail closed for this project
+            todo[p.id] = [];
+        }
+    }
+    const plan = planAutoDispatch(eligible, inFlight, todo);
+    const dispatched = [];
+    for (const d of plan) {
+        try {
+            const task = await deps.dispatcher.dispatch({
+                agent: d.delegateName.trim().toLowerCase(),
+                prompt: dispatchPrompt(d.identifier, d.title),
+                repo: d.repoSlug,
+                provider: d.provider,
+            });
+            // Bookkeeping only — dispatch already happened; moving to Doing keeps the
+            // ticket out of the next Todo poll. A failure here is non-fatal.
+            try {
+                await deps.linear.markStarted(d.issueId, d.delegateName);
+            }
+            catch (err) {
+                log('WARN', `auto-dispatch: dispatched ${d.identifier} but failed to mark Doing: ${err.message}`);
+            }
+            dispatched.push(d);
+            log('INFO', `auto-dispatch: dispatched ${d.identifier} to ${d.delegateName} (task ${task.id})`);
+        }
+        catch (err) {
+            log('WARN', `auto-dispatch: failed to dispatch ${d.identifier}: ${err.message}`);
+        }
+    }
+    return dispatched;
+}

package/dist/lib/browser/cdp.js

@@ -1,3 +1,12 @@
+// The `ws` client, NOT the platform (undici) WebSocket: undici enforces a
+// non-configurable max decompressed message size, and a CDP response carrying
+// a base64 screenshot of a content-rich page blows past it — the socket dies
+// with code 1006 ("Max decompressed message size exceeded") while the command
+// is pending. `ws` offers no permessage-deflate by default and takes an
+// explicit payload cap. (Reproduced live against a remote Edge over
+// `browser --host`: fresh blank newtab passed, reused content-rich newtab
+// failed on every Page.captureScreenshot.)
+import WSWebSocket from 'ws';
 const pipeTransports = new Map();
 export function registerPipeTransport(transport) {
     const id = `pipe://${process.pid}/${pipeTransports.size + 1}`;
@@ -26,7 +35,7 @@ export class CDPClient {
             return;
         }
         return new Promise((resolve, reject) => {
-            this.ws = new WebSocket(endpoint);
+            this.ws = new WSWebSocket(endpoint, { maxPayload: 256 * 1024 * 1024 });
             this.transport = 'websocket';
             this.ws.onopen = () => resolve();
             this.ws.onerror = () => reject(new Error('WebSocket error'));
@@ -102,7 +111,7 @@ export class CDPClient {
         this.transport = null;
     }
     get connected() {
-        return ((this.ws !== null && this.ws.readyState === WebSocket.OPEN) ||
+        return ((this.ws !== null && this.ws.readyState === WSWebSocket.OPEN) ||
             (this.pipe !== null && !this.pipe.write.destroyed));
     }
     get isOpen() {

package/dist/lib/browser/drivers/ssh.d.ts

@@ -25,26 +25,44 @@ export declare function connectSSH(endpoint: string, profile: BrowserProfile): P
  */
 export declare function encodePowerShell(script: string): string;
 /**
- * The PowerShell that launches the browser on a Windows remote. Two hard
+ * The PowerShell that launches the browser on a Windows remote. Three hard
  * requirements shaped this:
  *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
  *      the session's job tree on disconnect, which reaps both `start /B` and
- *      `Start-Process` children (verified against a real box). WMI
- *      `Win32_Process.Create` spawns under the WMI provider service instead,
- *      so the process survives after we drop the ssh connection and reconnect
- *      over the CDP tunnel.
- *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      `Start-Process` children (verified against a real box). A scheduled
+ *      task runs under the Task Scheduler service, so the process survives
+ *      after we drop the ssh connection and reconnect over the CDP tunnel.
+ *   2. The browser must run in the user's INTERACTIVE session. The previous
+ *      WMI `Win32_Process.Create` launch also survived disconnect, but it
+ *      spawned Edge in session 0 (the services session): the CDP socket bound
+ *      and accepted, yet the DevTools server never initialized — every
+ *      /json/version probe hung forever and DevToolsActivePort was never
+ *      written (verified against a real box, Edg/150). A scheduled task
+ *      registered and started by the logged-on user runs in that user's
+ *      interactive session, where DevTools comes up normally.
+ *   3. A distinct `--user-data-dir` so a fresh instance bound to the debugging
  *      port comes up even when the user already has Edge open.
  * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
- * registry at runtime rather than relying on a bare `msedge` name.
+ * registry at runtime rather than relying on a bare `msedge` name. The task is
+ * unregistered immediately after start — the browser keeps running; nothing
+ * lingers in the scheduler.
  */
 export declare function buildWindowsLaunchScript(browserType: string, port: number, customBinary?: string): string;
-/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+/**
+ * The PowerShell that kills whatever holds the CDP port on a Windows remote.
+ * Tree-kill (`taskkill /T`), not `Stop-Process`: Chromium is multi-process, and
+ * killing only the port-owning main process orphans its children. The orphans
+ * keep the profile's SingletonLock, so every later launch against the same
+ * `--user-data-dir` delegates to the zombie tree, exits, and never binds the
+ * CDP port — `browser start --host` then fails until someone hand-cleans the
+ * box (found live on win-mini by the #561 e2e suite).
+ */
 export declare function buildWindowsKillScript(port: number): string;
 /**
  * Build the remote command that launches the browser detached with a CDP port.
  * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
- * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ * starts it via an interactive one-shot scheduled task (encoded PowerShell)
+ * so it survives the ssh session AND serves CDP (session 0 never does).
  */
 export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string, port: number, customBinary?: string): string;
 /**
@@ -57,7 +75,7 @@ export declare function ensureRemoteBrowser(user: string, host: string, browserT
 export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
 /**
  * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
- * WMI-spawned (Windows) / detached (posix) browser process is not orphaned when
+ * task-launched (Windows) / detached (posix) browser process is not orphaned when
  * the ssh tunnel is torn down — killing only the tunnel left it running on
  * win-mini after every `browser stop`. Best-effort: never rejects.
  */

package/dist/lib/browser/drivers/ssh.js

@@ -5,8 +5,11 @@ import { getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } from '../profiles.js';
 import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // shellQuote lives in the shared ssh-exec helper (single choke point); re-export
-// so existing importers of `shellQuote` from this module keep working.
-import { shellQuote } from '../../ssh-exec.js';
+// so existing importers of `shellQuote` from this module keep working. SSH_OPTS
+// is the shared hardened baseline (BatchMode + ConnectTimeout + keepalive) —
+// reuse it so the raw-ssh spawns below fail fast on an unreachable host instead
+// of hanging on the default ~127s TCP timeout, rather than re-listing options.
+import { shellQuote, SSH_OPTS } from '../../ssh-exec.js';
 export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
@@ -168,18 +171,27 @@ export function encodePowerShell(script) {
     return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(script)}`;
 }
 /**
- * The PowerShell that launches the browser on a Windows remote. Two hard
+ * The PowerShell that launches the browser on a Windows remote. Three hard
  * requirements shaped this:
  *   1. The browser must OUTLIVE the ssh session. Windows OpenSSH terminates
  *      the session's job tree on disconnect, which reaps both `start /B` and
- *      `Start-Process` children (verified against a real box). WMI
- *      `Win32_Process.Create` spawns under the WMI provider service instead,
- *      so the process survives after we drop the ssh connection and reconnect
- *      over the CDP tunnel.
- *   2. A distinct `--user-data-dir` so a fresh instance bound to the debugging
+ *      `Start-Process` children (verified against a real box). A scheduled
+ *      task runs under the Task Scheduler service, so the process survives
+ *      after we drop the ssh connection and reconnect over the CDP tunnel.
+ *   2. The browser must run in the user's INTERACTIVE session. The previous
+ *      WMI `Win32_Process.Create` launch also survived disconnect, but it
+ *      spawned Edge in session 0 (the services session): the CDP socket bound
+ *      and accepted, yet the DevTools server never initialized — every
+ *      /json/version probe hung forever and DevToolsActivePort was never
+ *      written (verified against a real box, Edg/150). A scheduled task
+ *      registered and started by the logged-on user runs in that user's
+ *      interactive session, where DevTools comes up normally.
+ *   3. A distinct `--user-data-dir` so a fresh instance bound to the debugging
  *      port comes up even when the user already has Edge open.
  * CreateProcess ignores App Paths, so we resolve the real `.exe` from the
- * registry at runtime rather than relying on a bare `msedge` name.
+ * registry at runtime rather than relying on a bare `msedge` name. The task is
+ * unregistered immediately after start — the browser keeps running; nothing
+ * lingers in the scheduler.
  */
 export function buildWindowsLaunchScript(browserType, port, customBinary) {
     let exeStmts;
@@ -211,21 +223,42 @@ export function buildWindowsLaunchScript(browserType, port, customBinary) {
     // source — a test asserts CDP is never opened to `*`.
     return [
         ...exeStmts,
-        `$cl = '"' + $exe + '" --remote-debugging-port=${port}` +
+        // First-run / default-browser modals block automation (same rationale as
+        // the local launcher in chrome.ts), and the crash-restore bubble is worse
+        // here: `browser stop` hard-kills the remote process, so the NEXT launch
+        // against the same --user-data-dir marks the profile crashed and session
+        // restore swaps the initial page target — closing its CDP websocket while
+        // a command is pending (reproduced live: Page.captureScreenshot rejected
+        // with "CDP connection closed" on every reused-profile launch).
+        `$args = '--remote-debugging-port=${port}` +
             ` --remote-allow-origins=http://127.0.0.1:${port}` +
+            ` --no-first-run --no-default-browser-check` +
+            ` --hide-crash-restore-bubble --disable-session-crashed-bubble` +
             ` --disable-background-timer-throttling --user-data-dir="' + $env:TEMP + '\\agents-browser-${port}"'`,
-        `Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cl } | Out-Null`,
+        `$action = New-ScheduledTaskAction -Execute $exe -Argument $args`,
+        `Register-ScheduledTask -TaskName 'agents-browser-${port}' -Action $action -Force | Out-Null`,
+        `Start-ScheduledTask -TaskName 'agents-browser-${port}'`,
+        `Unregister-ScheduledTask -TaskName 'agents-browser-${port}' -Confirm:$false`,
     ].join('; ');
 }
-/** The PowerShell that kills whatever holds the CDP port on a Windows remote. */
+/**
+ * The PowerShell that kills whatever holds the CDP port on a Windows remote.
+ * Tree-kill (`taskkill /T`), not `Stop-Process`: Chromium is multi-process, and
+ * killing only the port-owning main process orphans its children. The orphans
+ * keep the profile's SingletonLock, so every later launch against the same
+ * `--user-data-dir` delegates to the zombie tree, exits, and never binds the
+ * CDP port — `browser start --host` then fails until someone hand-cleans the
+ * box (found live on win-mini by the #561 e2e suite).
+ */
 export function buildWindowsKillScript(port) {
     return (`Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue ` +
-        `| ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }`);
+        `| ForEach-Object { taskkill /PID $_.OwningProcess /T /F 2>$null } | Out-Null`);
 }
 /**
  * Build the remote command that launches the browser detached with a CDP port.
  * POSIX backgrounds the `.app` binary with `… &`; Windows resolves the exe and
- * spawns it via WMI (encoded PowerShell) so it survives the ssh session.
+ * starts it via an interactive one-shot scheduled task (encoded PowerShell)
+ * so it survives the ssh session AND serves CDP (session 0 never does).
  */
 export function buildLaunchCmd(remoteOs, browserType, port, customBinary) {
     if (remoteOs === 'windows') {
@@ -266,10 +299,12 @@ export async function ensureRemoteBrowser(user, host, browserType, port, remoteO
         // ignored and this resolved on close regardless of exit code, so failures
         // were swallowed and only re-emerged 8s later as a generic
         // "SSH tunnel failed to establish".
+        // Options BEFORE the target (matching `sshExec`): OpenSSH's BSD getopt on
+        // macOS stops at the first non-option, so any `-o` after `user@host` would
+        // be swallowed into the remote command instead of applied.
         const child = spawn('ssh', [
+            ...SSH_OPTS,
             `${user}@${host}`,
-            '-o',
-            'BatchMode=yes',
             remoteCmd,
         ], { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
         let stderr = '';
@@ -319,7 +354,7 @@ export async function restartRemoteBrowser(user, host, browserType, port, remote
 }
 /**
  * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
- * WMI-spawned (Windows) / detached (posix) browser process is not orphaned when
+ * task-launched (Windows) / detached (posix) browser process is not orphaned when
  * the ssh tunnel is torn down — killing only the tunnel left it running on
  * win-mini after every `browser stop`. Best-effort: never rejects.
  */
@@ -328,7 +363,11 @@ export function killRemoteBrowser(user, host, remoteOs, port) {
 }
 function runSSHCommand(user, host, cmd) {
     return new Promise((resolve) => {
-        const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {
+        // Reuse the shared hardened baseline so a hung TCP SYN to an unreachable
+        // host is bounded by ConnectTimeout (the local 3s kill below only bounds a
+        // connected-but-slow command, not the connect itself). Options precede the
+        // target — see ensureRemoteBrowser.
+        const child = spawn('ssh', [...SSH_OPTS, `${user}@${host}`, cmd], {
             stdio: 'ignore',
             windowsHide: true,
         });

package/dist/lib/browser/refs.js

@@ -1,3 +1,4 @@
+import { truncate } from '../format.js';
 /** Snapshot the stable descriptor for every ref in a freshly-built node map. */
 export function describeRefs(nodeMap) {
     return Array.from(nodeMap.values()).map((n) => ({
@@ -175,11 +176,6 @@ export async function getRefs(cdp, sessionId, opts = {}) {
     }
     return { refs: lines.join('\n'), nodeMap, opts: { interactive, limit } };
 }
-function truncate(s, max) {
-    if (s.length <= max)
-        return s;
-    return s.slice(0, max - 1) + '…';
-}
 export async function resolveRefToCoords(cdp, sessionId, nodeMap, ref) {
     const node = nodeMap.get(ref);
     if (!node)

package/dist/lib/cli-resources.d.ts

@@ -133,5 +133,3 @@ export declare function listCliStatus(cwd?: string): {
     statuses: CliStatus[];
     errors: CliManifestError[];
 };
-/** Names of CLIs that are declared but not currently installed on the host. */
-export declare function getMissingClis(cwd?: string): CliManifest[];