@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/index.js

@@ -51,9 +51,11 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
+import { renderWhatsNew } from './lib/whats-new.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
+import { emit, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -75,6 +77,56 @@ program
     .version(VERSION)
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
+// ─── Audit backbone ────────────────────────────────────────────────────────────
+// One choke point logs every `agents <module> <cmd>` invocation to the structured
+// event log — so team create/disband, agent run, secrets access, and everything
+// else is captured generically (with SSH/remote-user attribution added in emit()),
+// no per-command wiring. `agents events` reads it back. Attached to the root
+// program, so it's inherited by every subcommand regardless of lazy registration.
+/** Command path from the acting command up to (but excluding) the `agents` root. */
+function auditCommandPath(cmd) {
+    const parts = [];
+    let c = cmd;
+    while (c && c.name() && c.name() !== 'agents') {
+        parts.unshift(c.name());
+        c = c.parent;
+    }
+    return parts;
+}
+const auditStarts = new WeakMap();
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        auditStarts.set(actionCommand, Date.now());
+        emit('command.start', {
+            module: parts[0],
+            command: parts.join(' '),
+            args: redactArgs(actionCommand.args),
+            cwd: process.cwd(),
+        });
+    }
+    catch {
+        // Audit logging must never break command dispatch.
+    }
+});
+program.hook('postAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        const started = auditStarts.get(actionCommand);
+        emit('command.end', {
+            module: parts[0],
+            command: parts.join(' '),
+            ...(started !== undefined ? { durationMs: Date.now() - started } : {}),
+        });
+    }
+    catch {
+        // Best-effort completion record; the start line is the durable audit fact.
+    }
+});
 // Custom help for the main program only
 const originalHelpInformation = program.helpInformation.bind(program);
 program.helpInformation = function () {
@@ -121,6 +173,7 @@ Run and dispatch:
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
+  logs [id]                       Show a run's log — host-dispatch task or session; -f to follow
   browser                         Automate a browser — navigate, click, screenshot, console, network
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
@@ -175,41 +228,13 @@ async function showWhatsNew(fromVersion, toVersion) {
         const response = await fetch(`https://unpkg.com/@phnx-labs/agents-cli@${toVersion}/CHANGELOG.md`);
         if (!response.ok)
             return;
-        const changelog = await response.text();
-        const lines = changelog.split('\n');
-        const relevantChanges = [];
-        let inRelevantSection = false;
-        let currentVersion = '';
-        for (const line of lines) {
-            const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
-            if (versionMatch) {
-                currentVersion = versionMatch[1];
-                // Only the range the user actually moved through: (fromVersion, toVersion].
-                // Bounding the top end matters when upgrading to a specific older
-                // version, and guards against a changelog that lists unreleased entries.
-                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
-                    compareVersions(currentVersion, toVersion) <= 0;
-                inRelevantSection = inRange;
-                if (inRelevantSection) {
-                    relevantChanges.push('');
-                    relevantChanges.push(chalk.bold(`v${currentVersion}`));
-                }
-                continue;
-            }
-            if (inRelevantSection && line.trim()) {
-                if (line.startsWith('**') && line.endsWith('**')) {
-                    relevantChanges.push(chalk.cyan(line.replace(/\*\*/g, '')));
-                }
-                else if (line.startsWith('- ')) {
-                    relevantChanges.push(chalk.gray(`  ${line}`));
-                }
-            }
-        }
+        const relevantChanges = renderWhatsNew(await response.text(), fromVersion, toVersion);
         if (relevantChanges.length > 0) {
             console.log(chalk.bold("\nWhat's new:\n"));
             for (const line of relevantChanges) {
                 console.log(line);
             }
+            console.log(chalk.gray('\nFull notes: https://github.com/phnx-labs/agents-cli/blob/main/CHANGELOG.md'));
             console.log();
         }
     }
@@ -785,6 +810,8 @@ async function registerAllEagerCommands() {
     await reg(loadBrowser);
     await reg(loadComputer);
     await reg(loadHosts);
+    await reg(loadLogs);
+    await reg(loadEvents);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');

package/dist/lib/agents.js

@@ -327,11 +327,16 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.copilot', 'skills'),
         hooksDir: 'hooks',
+        // Copilot reads a plugin's manifest from the plugin ROOT (plugin.json),
+        // not `.claude-plugin/plugin.json`. Mirror it there. Verified against the
+        // GitHub Copilot CLI (1.0.56): `copilot plugin install` produces an
+        // installed plugin dir whose manifest sits at the root.
+        pluginManifestDir: '.',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -491,11 +496,26 @@ export const AGENTS = {
     // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
     // Binary is NOT in node_modules/.bin — the shim resolves the fixed install
     // path ~/.local/bin/droid directly (see the droid branch in shims.ts).
-    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
-    // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
-    // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
-    // switch (no FACTORY_HOME env var exists). Headless: `droid exec "<prompt>"`
-    // with --auto low|medium|high, -o stream-json, -m <model>, -r <effort>.
+    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/, hooks/,
+    // plugins/). Memory: native AGENTS.md. Subagents = custom droids (top-level
+    // .md files in ~/.factory/droids/). Config isolation rides the ~/.factory
+    // symlink switch (no FACTORY_HOME env var exists). Headless:
+    // `droid exec "<prompt>"` with --auto low|medium|high, -o stream-json,
+    // -m <model>, -r <effort>.
+    //
+    // Hooks: Claude-shaped. settings.json carries a top-level `hooks` object keyed
+    // by event (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart,
+    // SessionEnd, Stop, SubagentStop, Notification, PreCompact), each an array of
+    // `{ matcher?, hooks: [{ type: "command", command, timeout? }] }` matcher
+    // groups — verified against the droid binary's zod schema. So the Claude
+    // registrar is reused verbatim, just targeting `.factory/settings.json`.
+    //
+    // Plugins: native `droid plugin` command group + ~/.factory/plugins/ with the
+    // same marketplace layout Claude uses (known_marketplaces.json +
+    // marketplaces/<name>/plugins/<plugin>/). Droid's plugin manifest dir is
+    // `.factory-plugin/` (it also reads `.claude-plugin/` for compatibility) — set
+    // pluginManifestDir so syncPluginToVersion mirrors the manifest into it, the
+    // same pattern codex uses with `.codex-plugin`.
     droid: {
         id: 'droid',
         name: 'Droid',
@@ -509,20 +529,21 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: '', // no skills concept
         hooksDir: 'hooks',
+        pluginManifestDir: '.factory-plugin',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
+        supportsHooks: true,
         // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
         // remote headless `droid exec`.
         cloudProvider: 'factory',
         capabilities: {
-            hooks: false,
+            hooks: true,
             mcp: true,
             allowlist: false,
             skills: false,
             commands: true,
-            plugins: false,
+            plugins: true,
             subagents: true,
             rules: { file: 'AGENTS.md' },
             workflows: false,

package/dist/lib/browser/cdp.js

@@ -219,7 +219,11 @@ export function verifyBrowserIdentity(reported, expected, port, host = 'localhos
         // to a Comet instance doesn't trip a false "identity mismatch".
         comet: ['comet', 'chrome'],
         brave: ['brave', 'brave-browser', 'chrome'],
-        edge: ['edge', 'microsoft-edge', 'msedge', 'chrome'],
+        // Windows/Chromium Edge reports its /json/version "Browser" field as
+        // "Edg/<version>" (the `Edg` token, not `Edge`), which normalizeBrowserName
+        // reduces to "edg". Accept it so attaching to a real Edge doesn't trip a
+        // false identity mismatch (the profile enum only allows "edge").
+        edge: ['edge', 'edg', 'microsoft-edge', 'msedge', 'chrome'],
     };
     const accepted = matches[expected] || [expected];
     if (accepted.includes(reported))

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

@@ -53,7 +53,15 @@ export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string,
  * (Get-NetTCPConnection → Stop-Process).
  */
 export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
+export declare function ensureRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
 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
+ * the ssh tunnel is torn down — killing only the tunnel left it running on
+ * win-mini after every `browser stop`. Best-effort: never rejects.
+ */
+export declare function killRemoteBrowser(user: string, host: string, remoteOs: RemoteOs, port: number): Promise<void>;
 /**
  * Identify whether a pid listening on our target local port is an SSH
  * tunnel WE would have spawned for `host:remotePort`. Used so that two

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

@@ -48,12 +48,12 @@ export async function connectSSH(endpoint, profile) {
             `is already in use by ${occupant.command} (pid ${occupant.pid}). ` +
             `Either kill that process (\`kill ${occupant.pid}\`) or change the profile's port.`);
     }
-    try {
-        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
-    }
-    catch {
-        // Browser may already be running, continue
-    }
+    // A non-zero remote exit (missing exe, auth failure, bad launch) now rejects
+    // with the captured stderr and propagates. An already-running browser exits 0
+    // (the launch backgrounds/WMI-spawns regardless), so this does not spuriously
+    // fail the reconnect path — only genuine launch failures reach the caller
+    // instead of being swallowed and mis-reported later as a tunnel timeout.
+    await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
     let tunnel;
     if (occupant) {
         // Reuse the existing tunnel rather than spawning a duplicate.
@@ -102,6 +102,11 @@ export async function connectSSH(endpoint, profile) {
         pid: tunnelPid,
         cleanup: () => {
             cdp.close();
+            // Kill the remote browser BEFORE tearing down the tunnel. It runs on a
+            // separate ssh connection (independent of the tunnel we're about to
+            // kill), so tunnel teardown can't cut it off. Fire-and-forget — cleanup
+            // stays synchronous, and killRemoteBrowser never rejects.
+            killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
             tunnel.kill();
             clearProfileRuntime(profile.name);
         },
@@ -177,9 +182,9 @@ export function encodePowerShell(script) {
  * registry at runtime rather than relying on a bare `msedge` name.
  */
 export function buildWindowsLaunchScript(browserType, port, customBinary) {
-    let exeExpr;
+    let exeStmts;
     if (customBinary) {
-        exeExpr = psSingleQuote(customBinary);
+        exeStmts = [`$exe = ${psSingleQuote(customBinary)}`];
     }
     else if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -188,13 +193,24 @@ export function buildWindowsLaunchScript(browserType, port, customBinary) {
         const exeKey = WIN_BROWSER_APPPATH[browserType];
         if (!exeKey)
             throw new Error(`Unknown browser type for windows remote: ${browserType}`);
-        exeExpr =
-            `(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}').'(default)'`;
+        const appPath = `SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\${exeKey}`;
+        // Per-user installs — the DEFAULT for Edge and Chrome — register App Paths
+        // under HKCU, not HKLM, so an HKLM-only lookup silently missed them and the
+        // launch failed. Resolve from HKLM first, then fall through to HKCU.
+        // Windows PowerShell 5.1 (what `powershell.exe` is) has no `??`, so the
+        // fallback is an explicit `if`. A missing exe `throw`s so the failure rides
+        // out as a non-zero ssh exit (surfaced by ensureRemoteBrowser) instead of a
+        // silent empty launch.
+        exeStmts = [
+            `$exe = (Get-ItemProperty 'HKLM:\\${appPath}' -EA SilentlyContinue).'(default)'`,
+            `if (-not $exe) { $exe = (Get-ItemProperty 'HKCU:\\${appPath}' -EA SilentlyContinue).'(default)' }`,
+            `if (-not $exe) { throw 'browser exe not found in HKLM/HKCU App Paths: ${exeKey}' }`,
+        ];
     }
     // Keep the `--remote-allow-origins=http://127.0.0.1:${port}` literal in
     // source — a test asserts CDP is never opened to `*`.
     return [
-        `$exe = ${exeExpr}`,
+        ...exeStmts,
         `$cl = '"' + $exe + '" --remote-debugging-port=${port}` +
             ` --remote-allow-origins=http://127.0.0.1:${port}` +
             ` --disable-background-timer-throttling --user-data-dir="' + $env:TEMP + '\\agents-browser-${port}"'`,
@@ -242,21 +258,56 @@ export function buildKillCmd(remoteOs, port) {
     }
     return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
 }
-async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+export async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
     const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
+        // Capture stderr so a real launch failure (missing exe, auth denied, bad
+        // CreateProcess) surfaces here as a clear error. Previously stdio was
+        // 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".
         const child = spawn('ssh', [
             `${user}@${host}`,
             '-o',
             'BatchMode=yes',
             remoteCmd,
-        ], { stdio: 'ignore' });
-        child.on('close', () => resolve());
-        child.on('error', reject);
-        setTimeout(() => {
+        ], { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            // ssh is still running the backgrounding launch command past our window.
+            // Killing the local ssh client does NOT reap the WMI/detached remote
+            // browser, so treat this as launched and let waitForPort confirm.
             child.kill();
             resolve();
         }, 2000);
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code && code !== 0) {
+                const detail = stderr.trim();
+                reject(new Error(`Remote browser launch failed on ${host} (ssh exit ${code})` +
+                    (detail ? `: ${detail}` : '')));
+            }
+            else {
+                resolve();
+            }
+        });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
     });
 }
 export async function restartRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
@@ -266,6 +317,15 @@ export async function restartRemoteBrowser(user, host, browserType, port, remote
     await ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary);
     await sleep(1500);
 }
+/**
+ * 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
+ * the ssh tunnel is torn down — killing only the tunnel left it running on
+ * win-mini after every `browser stop`. Best-effort: never rejects.
+ */
+export function killRemoteBrowser(user, host, remoteOs, port) {
+    return runSSHCommand(user, host, buildKillCmd(remoteOs, port));
+}
 function runSSHCommand(user, host, cmd) {
     return new Promise((resolve) => {
         const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {

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

@@ -8,6 +8,9 @@ export declare class BrowserDaemonNotRunningError extends Error {
 }
 export declare function formatBrowserDaemonNotRunningError(): string;
 export declare function getSocketPath(): string;
+/** Is the daemon reachable? A real connect probe on every platform — a socket
+ * file existing on disk is not proof a daemon is listening on it. */
+export declare function isDaemonReachable(): Promise<boolean>;
 export declare class BrowserIPCServer {
     private server;
     private service;

package/dist/lib/browser/ipc.js

@@ -32,8 +32,12 @@ export function getSocketPath() {
 function getIpcEndpoint() {
     return ipcEndpoint(getSocketPath());
 }
-/** Can we open a connection to the daemon right now? Used on Windows where a
- * named pipe can't be probed with fs.existsSync. Resolves false on any error. */
+/** Can we open a connection to the daemon right now? Resolves false on any
+ * error. This is the authoritative liveness check on every platform: a live
+ * daemon accepts the connection, while a stale POSIX socket file left behind by
+ * a crashed daemon (or one that "appears and is immediately destroyed", #556)
+ * rejects with ECONNREFUSED and is correctly reported as not reachable —
+ * something fs.existsSync can't distinguish. */
 function probeDaemon(endpoint, timeoutMs = 500) {
     return new Promise((resolve) => {
         const sock = net.createConnection(endpoint);
@@ -45,16 +49,16 @@ function probeDaemon(endpoint, timeoutMs = 500) {
         sock.on('error', () => { clearTimeout(timer); finish(false); });
     });
 }
-/** Is the daemon reachable? existsSync probe on POSIX, connect probe on Windows. */
-async function isDaemonReachable() {
-    if (IS_WINDOWS)
-        return probeDaemon(getIpcEndpoint());
-    return fs.existsSync(getSocketPath());
+/** Is the daemon reachable? A real connect probe on every platform — a socket
+ * file existing on disk is not proof a daemon is listening on it. */
+export async function isDaemonReachable() {
+    return probeDaemon(getIpcEndpoint());
 }
-async function waitForSocket(socketPath, timeoutMs) {
+async function waitForSocket(_socketPath, timeoutMs) {
+    const endpoint = getIpcEndpoint();
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (IS_WINDOWS ? await probeDaemon(getIpcEndpoint()) : fs.existsSync(socketPath))
+        if (await probeDaemon(endpoint))
             return;
         await new Promise((resolve) => setTimeout(resolve, 100));
     }

package/dist/lib/browser/service.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');
@@ -693,14 +704,22 @@ 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'] });
@@ -724,9 +743,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 +778,7 @@ export class BrowserService {
             durationMs,
             maxBytes,
             ffmpeg,
+            ffmpegStderr,
             sessionId,
             conn,
             frameHandler,
@@ -795,27 +822,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) {

package/dist/lib/daemon.d.ts

@@ -46,6 +46,40 @@ export declare function startDaemon(): {
  * value (e.g. inherited from launchd) is left untouched.
  */
 export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
+ * exact form that works under a direct `daemon _run`.
+ *
+ * We spawn the Node runtime (`process.execPath`) with the CLI entry as an
+ * argument rather than executing the entry path directly. Executing the `.js`
+ * path relies on its shebang on POSIX, and on Windows CreateProcess can't run a
+ * `.js`/shim directly at all — it gets launched through a transient
+ * console-owning wrapper (cmd.exe / the npm shim). When that wrapper exits it
+ * closes its console, and the detached daemon sharing that console receives a
+ * console-close event that trips its shutdown handler — the daemon comes up,
+ * binds the browser IPC socket, then tears itself down ~36ms later (#556).
+ * Going through `process.execPath` means a real PE/binary is spawned with
+ * `detached: true` and no console, so nothing signals the daemon after launch.
+ *
+ * When the entry isn't a JS file (e.g. a native launcher resolved via
+ * `which agents`), run it directly — it owns its own runtime resolution.
+ */
+export declare function getDaemonLaunch(agentsBin?: string): {
+    command: string;
+    args: string[];
+};
+interface StartDetachedOptions {
+    /** CLI entry to launch (defaults to the running binary). Injectable for tests. */
+    agentsBin?: string;
+    /** Log file the daemon's stdio is redirected to (defaults to the daemon log). */
+    logPath?: string;
+    /** Environment for the child (defaults to the OAuth-augmented detached env). */
+    env?: NodeJS.ProcessEnv;
+}
+export declare function startDetached(opts?: StartDetachedOptions): {
+    pid: number | null;
+    method: string;
+};
 /** Stop the daemon, unloading it from launchd/systemd if applicable. */
 export declare function stopDaemon(): boolean;
 /** Get current daemon status including running state, PID, and enabled job count. */
@@ -59,3 +93,4 @@ export declare function getDaemonStatus(): {
 export declare function readDaemonLog(lines?: number): string;
 /** Send SIGHUP to the daemon to trigger a job reload. */
 export declare function signalDaemonReload(): boolean;
+export {};