@phnx-labs/agents-cli 1.20.33 → 1.20.35

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

@@ -12,6 +12,7 @@ export { shellQuote };
 // the single ssh-tunnel helper. Calling it with no options preserves this
 // driver's original foreground, stderr-captured behavior exactly.
 import { startSSHTunnel } from '../../ssh-tunnel.js';
+import { encodePwshBase64 } from '../../pwsh.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -47,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.
@@ -101,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);
         },
@@ -159,8 +165,7 @@ function psSingleQuote(s) {
  * `powershell -Command "…"` is fragile the moment a path or URL is involved).
  */
 export function encodePowerShell(script) {
-    const b64 = Buffer.from(script, 'utf16le').toString('base64');
-    return `powershell -NoProfile -EncodedCommand ${b64}`;
+    return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(script)}`;
 }
 /**
  * The PowerShell that launches the browser on a Windows remote. Two hard
@@ -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], {
@@ -290,8 +350,23 @@ function sleep(ms) {
  *
  * Best-effort match against the ssh -L command line via `ps`. If we
  * can't read the cmd or the args don't look like ours, treat as not-ours.
+ *
+ * Windows has no `ps`, so the POSIX branch below always throws there and every
+ * reuse check returned false — the second invocation to the same host:port then
+ * failed "port in use". On win32 we instead reuse the netstat -ano + tasklist
+ * occupant lookup (getPortOccupant): the tunnel binds `remotePort` locally
+ * (localPort === remotePort in the caller), so the pid holding that port is our
+ * ssh.exe. tasklist only exposes the image name, not the full command line, so
+ * we can't match host/remotePort as tightly as the POSIX branch — an ssh
+ * process on our exact local port is our tunnel in practice.
  */
-function isOwnTunnel(pid, host, remotePort) {
+export function isOwnTunnel(pid, host, remotePort) {
+    if (process.platform === 'win32') {
+        const occupant = getPortOccupant(remotePort);
+        if (!occupant || occupant.pid !== pid)
+            return false;
+        return occupant.command.toLowerCase().startsWith('ssh');
+    }
     try {
         const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
             encoding: 'utf-8',

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 {};

package/dist/lib/daemon.js

@@ -538,14 +538,42 @@ export function buildDetachedDaemonEnv(baseEnv = process.env) {
     }
     return env;
 }
-function startDetached() {
-    const agentsBin = getAgentsBinPath();
-    const logPath = getLogPath();
+/**
+ * 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 function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
+    if (/\.(c|m)?js$/.test(agentsBin)) {
+        return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
+    }
+    return { command: agentsBin, args: ['daemon', '_run'] };
+}
+export function startDetached(opts = {}) {
+    const agentsBin = opts.agentsBin ?? getAgentsBinPath();
+    const logPath = opts.logPath ?? getLogPath();
     const logFd = fs.openSync(logPath, 'a');
-    const child = spawn(agentsBin, ['daemon', '_run'], {
+    const { command, args } = getDaemonLaunch(agentsBin);
+    const child = spawn(command, args, {
         stdio: ['ignore', logFd, logFd],
         detached: true,
-        env: buildDetachedDaemonEnv(),
+        // No console window on Windows — a hidden, consoleless process can't be
+        // torn down by a console-close event when its launcher exits (#556).
+        windowsHide: true,
+        env: opts.env ?? buildDetachedDaemonEnv(),
     });
     child.unref();
     fs.closeSync(logFd);

package/dist/lib/devices/connect.d.ts

@@ -11,8 +11,9 @@ export declare function sshTargetFor(device: DeviceProfile): string;
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
 /**

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { encodePwshBase64 } from '../pwsh.js';
 import { getCacheDir } from '../state.js';
 import { hostNameFor } from './ssh-config.js';
 /** Env var the askpass shim reads to know which bundle holds the password. */
@@ -38,15 +39,16 @@ export function sshTargetFor(device) {
 /**
  * Wrap a remote command for the device's shell. Windows devices speak
  * PowerShell, so a bare command is run through `powershell -NoProfile
- * -Command`; POSIX devices get the command verbatim (the remote login shell
- * parses it). Returns undefined when no command was given (interactive login).
+ * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
+ * shell parses it). Returns undefined when no command was given (interactive
+ * login).
  */
 export function wrapRemoteCommand(device, cmd) {
     if (cmd.length === 0)
         return undefined;
     const joined = cmd.join(' ');
     if (device.shell === 'powershell') {
-        return `powershell -NoProfile -Command ${shellQuote(joined)}`;
+        return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(joined)}`;
     }
     return joined;
 }

package/dist/lib/doctor-diff.js

@@ -29,6 +29,8 @@ import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
+import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
+import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
@@ -87,6 +89,15 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
+    // Command-as-skill agents (kimi, codex>=0.117, grok) install every command as a
+    // SKILL wrapper at <agentDir>/skills/<cmd>/SKILL.md, not a native command file.
+    // The compare must follow that or every command false-reports as drifted.
+    const asSkill = shouldInstallCommandAsSkill(agent, version);
+    // Agents that hold commands neither natively nor as skills (e.g. goose) must not
+    // report source commands as "missing" — they structurally can't take them.
+    if (!asSkill && !supports(agent, 'commands', version).ok)
+        return [];
+    const agentDir = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent));
     const installed = new Set(listCommandsInVersionHome(agent, version));
     const layerBases = buildLayerBases(cwd, 'commands', { excludeProject });
     const sourceByName = new Map();
@@ -113,11 +124,24 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const seen = new Set();
     for (const [name, src] of sourceByName) {
         seen.add(name);
-        const homePath = path.join(homeDir, `${name}${ext}`);
         if (!installed.has(name)) {
             rows.push({ kind: 'commands', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
+        if (asSkill) {
+            // Compare against the installed command-skill wrapper, not a native path.
+            const matches = commandSkillMatches(agentDir, name, src.path);
+            rows.push({
+                kind: 'commands',
+                name,
+                status: matches ? 'ok' : 'diff',
+                source: src.layer,
+                sourcePath: src.path,
+                homePath: path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md'),
+            });
+            continue;
+        }
+        const homePath = path.join(homeDir, `${name}${ext}`);
         const installedContent = readSafe(homePath);
         const sourceContent = readSafe(src.path);
         if (installedContent == null || sourceContent == null) {
@@ -138,7 +162,10 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     for (const name of installed) {
         if (seen.has(name))
             continue;
-        rows.push({ kind: 'commands', name, status: 'extra', homePath: path.join(homeDir, `${name}${ext}`) });
+        const extraHome = asSkill
+            ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
+            : path.join(homeDir, `${name}${ext}`);
+        rows.push({ kind: 'commands', name, status: 'extra', homePath: extraHome });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/lib/drift-sync.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import { type VersionHealResult } from './heal.js';
+import { type UnifiedSyncStatus } from './sync-status.js';
+export interface DriftSyncOptions {
+    cwd?: string;
+    /** Reconcile everything detected with no prompts — the "kick it" path, also the
+     * non-TTY / menu-bar-launched-with-flag behavior. Pulls `.system` if behind. */
+    yes?: boolean;
+    /** Pre-computed status, to avoid a second scan when the caller already has one. */
+    status?: UnifiedSyncStatus;
+    /** Skip the drift summary — set by callers that already printed their own. */
+    quiet?: boolean;
+}
+export interface DriftSyncResult {
+    systemBehindBefore: number;
+    systemPulled: boolean;
+    healed: VersionHealResult[];
+    /** True when the user declined at the prompt (nothing was changed). */
+    cancelled: boolean;
+    /** True when there was no drift to act on in the first place. */
+    nothingToDo: boolean;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export declare function promptDriftSync(opts?: DriftSyncOptions): Promise<DriftSyncResult>;