@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/crabbox/progress.js

@@ -9,6 +9,54 @@
  */
 /** Sentinel echoed on the box right before `agents run`. Distinctive + collision-proof. */
 export const LEASE_AGENT_MARKER = '___AGENTS_LEASE_AGENT_OUTPUT_b1f4c2___';
+const PHASE_PREFIX = '___PHASE_';
+const PHASE_SUFFIX = '___';
+/**
+ * The sentinel line the bootstrap script echoes to announce phase `name`.
+ * Kept distinct from `LEASE_AGENT_MARKER` (which does NOT start with `___PHASE_`).
+ */
+export function leasePhaseSentinel(name) {
+    return `${PHASE_PREFIX}${name}${PHASE_SUFFIX}`;
+}
+/** Parse a phase name out of a sentinel line, or null when the line is not one. */
+function parsePhaseSentinel(line) {
+    const t = line.trim();
+    if (!t.startsWith(PHASE_PREFIX) || !t.endsWith(PHASE_SUFFIX) || t.length <= PHASE_PREFIX.length + PHASE_SUFFIX.length) {
+        return null;
+    }
+    const name = t.slice(PHASE_PREFIX.length, t.length - PHASE_SUFFIX.length);
+    // Phase names are lowercase kebab tokens; this also rejects the agent marker's
+    // underscore-laden tail if it ever changed to share the ___PHASE_ prefix.
+    return /^[a-z0-9-]+$/.test(name) ? name : null;
+}
+/** Human labels for the known bootstrap phases. Falls back to the raw name. */
+const STEP_LABELS = {
+    sync: 'Syncing workspace',
+    install: 'Installing agents-cli',
+    runtime: 'Installing agent runtimes',
+    creds: 'Provisioning credentials',
+    'copy-setup': 'Copying your setup',
+    'joined-tailnet': 'Joined tailnet',
+};
+/** Human-readable elapsed: "0.8s", "3.4s", "1m 5s". */
+function formatElapsed(ms) {
+    if (ms < 10_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const secs = Math.round(ms / 1000);
+    if (secs < 60)
+        return `${secs}s`;
+    return `${Math.floor(secs / 60)}m ${secs % 60}s`;
+}
+/**
+ * Render one lease step as a single human line the command layer can print
+ * (e.g. behind a spinner). Self-contained: the lib never writes to a stream.
+ */
+export function renderStepLine(step) {
+    const label = STEP_LABELS[step.name] ?? step.name;
+    const detail = step.detail ? ` — ${step.detail}` : '';
+    const elapsed = step.elapsedMs !== undefined ? ` (${formatElapsed(step.elapsedMs)})` : '';
+    return `${label}${detail}${elapsed}`;
+}
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 /**
  * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
@@ -77,12 +125,21 @@ export function createSpinner(opts = {}) {
  * Split the crabbox run stream at `LEASE_AGENT_MARKER`. `onSetupLine` fires for
  * each complete non-empty line before the marker; `onAgentChunk` fires with raw
  * text after it (streamed promptly, not line-buffered, so agent output is live).
+ *
+ * Setup lines matching a `___PHASE_<name>___` sentinel are swallowed (never shown
+ * as setup noise) and surfaced through `onStep` instead — a structured step
+ * stream the command layer can render via `renderStepLine`. When `now` is
+ * provided, each step carries `elapsedMs` since the previous step (or router
+ * start for the first); omit `now` for deterministic, timing-free output.
  */
 export function createLeaseOutputRouter(cb) {
     const marker = cb.marker ?? LEASE_AGENT_MARKER;
+    const now = cb.now;
     let seen = false;
     let buf = '';
     const setup = [];
+    const stepList = [];
+    let lastStepAt = now ? now() : undefined;
     const emitLine = (line) => {
         const t = line.replace(/\r$/, '');
         if (t.trim()) {
@@ -90,6 +147,17 @@ export function createLeaseOutputRouter(cb) {
             cb.onSetupLine(t);
         }
     };
+    const emitStep = (name) => {
+        let elapsedMs;
+        if (now) {
+            const t = now();
+            elapsedMs = lastStepAt !== undefined ? t - lastStepAt : undefined;
+            lastStepAt = t;
+        }
+        const step = elapsedMs !== undefined ? { name, elapsedMs } : { name };
+        stepList.push(step);
+        cb.onStep?.(step);
+    };
     return {
         push(chunk) {
             if (seen) {
@@ -110,6 +178,11 @@ export function createLeaseOutputRouter(cb) {
                     }
                     return;
                 }
+                const phase = parsePhaseSentinel(line);
+                if (phase !== null) {
+                    emitStep(phase); // swallow the sentinel; report a structured step
+                    continue;
+                }
                 emitLine(line);
             }
             // A trailing partial line stays in `buf` — it may be the marker forming.
@@ -125,5 +198,8 @@ export function createLeaseOutputRouter(cb) {
         setupLines() {
             return setup;
         },
+        steps() {
+            return stepList;
+        },
     };
 }

package/dist/lib/crabbox/runtimes.d.ts

@@ -60,6 +60,10 @@ export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choi
  * under a non-obvious runtime are resolved separately — see RUSH-1725.
  */
 export declare function inferLeaseRuntime(agentName: string, detected: DetectedRuntime[]): AgentId | null;
+/** True when a profile already carries auth for its host runtime via env. */
+export declare function profileNeedsBaseRuntimeCredentials(agent: AgentId, env: Record<string, string>, authEnvVar?: string): boolean;
+/** Build a quoted heredoc write to a path under the remote user's home. */
+export declare function buildHomeFileWriteScript(remote: string, contents: string): string;
 /**
  * Where Claude Code reads its OAuth token on the box. `.claude.json` (the file
  * LEASE_RUNTIMES copies) is config/account-metadata ONLY — the actual token

package/dist/lib/crabbox/runtimes.js

@@ -103,10 +103,41 @@ export function inferLeaseRuntime(agentName, detected) {
     // Custom/workflow agent: fall back to the signed-in runtime (preferring claude).
     return signedIn.find((d) => d.id === 'claude')?.id ?? signedIn[0]?.id ?? null;
 }
+const PROFILE_AUTH_ENV_KEYS_BY_RUNTIME = {
+    claude: [
+        'ANTHROPIC_AUTH_TOKEN',
+        'ANTHROPIC_API_KEY',
+        'AWS_ACCESS_KEY_ID',
+        'AWS_PROFILE',
+        'AWS_BEARER_TOKEN_BEDROCK',
+        'GOOGLE_APPLICATION_CREDENTIALS',
+        'GOOGLE_CLOUD_PROJECT',
+        'ANTHROPIC_FOUNDRY_API_KEY',
+    ],
+    codex: ['OPENAI_API_KEY'],
+    gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+    grok: ['XAI_API_KEY', 'GROK_API_KEY'],
+};
+/** True when a profile already carries auth for its host runtime via env. */
+export function profileNeedsBaseRuntimeCredentials(agent, env, authEnvVar) {
+    if (!LEASE_RUNTIMES.some((c) => c.id === agent))
+        return false;
+    if (authEnvVar && typeof env[authEnvVar] === 'string' && env[authEnvVar].trim() !== '')
+        return false;
+    const keys = PROFILE_AUTH_ENV_KEYS_BY_RUNTIME[agent] ?? [];
+    return !keys.some((key) => typeof env[key] === 'string' && env[key].trim() !== '');
+}
 // A long random sentinel makes an accidental (or malicious) collision with a
 // token's contents effectively impossible, so the quoted heredoc can never be
 // closed early by the credential body.
 const CRED_EOF = 'AGENTS_LEASE_CRED_EOF_9f3c1a7b5e2d4068';
+/** Build a quoted heredoc write to a path under the remote user's home. */
+export function buildHomeFileWriteScript(remote, contents) {
+    const dir = path.posix.dirname(remote);
+    const mkdir = dir && dir !== '.' ? `mkdir -p "$HOME/${dir}"\n` : '';
+    return (`${mkdir}cat > "$HOME/${remote}" <<'${CRED_EOF}'\n${contents}${contents.endsWith('\n') ? '' : '\n'}${CRED_EOF}\n` +
+        `chmod 600 "$HOME/${remote}"`);
+}
 /**
  * Where Claude Code reads its OAuth token on the box. `.claude.json` (the file
  * LEASE_RUNTIMES copies) is config/account-metadata ONLY — the actual token
@@ -206,12 +237,6 @@ export async function resolveClaudeCredentialsBlob(opts) {
 export function buildCredentialScript(picked, detected, extras) {
     const byId = new Map(detected.map((d) => [d.id, d]));
     const parts = [];
-    const writeFile = (remote, contents) => {
-        const dir = path.posix.dirname(remote);
-        const mkdir = dir && dir !== '.' ? `mkdir -p "$HOME/${dir}"\n` : '';
-        return (`${mkdir}cat > "$HOME/${remote}" <<'${CRED_EOF}'\n${contents}${contents.endsWith('\n') ? '' : '\n'}${CRED_EOF}\n` +
-            `chmod 600 "$HOME/${remote}"`);
-    };
     for (const id of picked) {
         const d = byId.get(id);
         const cred = LEASE_RUNTIMES.find((c) => c.id === id);
@@ -224,11 +249,11 @@ export function buildCredentialScript(picked, detected, extras) {
         catch {
             continue;
         }
-        parts.push(writeFile(cred.remote, contents));
+        parts.push(buildHomeFileWriteScript(cred.remote, contents));
         // For claude the file above is config/state only; the OAuth token is a
         // second artifact — without it the box comes up "Not logged in".
         if (id === 'claude' && extras?.claudeCredentialsJson) {
-            parts.push(writeFile(CLAUDE_TOKEN_REMOTE, extras.claudeCredentialsJson));
+            parts.push(buildHomeFileWriteScript(CLAUDE_TOKEN_REMOTE, extras.claudeCredentialsJson));
         }
     }
     return parts.join('\n');

package/dist/lib/crabbox/setup-copy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Setup-copy for `agents run --lease` (RUSH-1920), transport = PUSH-FROM-LOCAL.
+ *
+ * A fresh crabbox box has agents-cli installed but none of the caller's own
+ * `~/.agents` config (skills, hooks, commands, MCP, profiles). This module
+ * replicates the *git-tracked* subset of the LOCAL `~/.agents` onto the box:
+ *
+ *   1. `git -C <userAgentsDir> ls-files` — tracked files only. Tracked-only is
+ *      the safety boundary: it excludes `.history/`, `.cache/`, `.system/` and
+ *      any keychain-backed secrets by construction (those are gitignored), so no
+ *      credential material is ever pushed.
+ *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
+ *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
+ *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
+ *   3. `agents repo refresh` on the box so the copied config takes effect.
+ *
+ * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
+ * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
+ * filter belts-and-braces the tracked-only guarantee.
+ *
+ * This is a self-contained local function the command layer calls; it does NOT
+ * ride the box-side bootstrap script (that only echoes the `copy-setup` progress
+ * sentinel — see `buildBootstrapScript`).
+ */
+/** Remote path (relative to the box user's home) the tracked config lands in. */
+export declare const REMOTE_AGENTS_DIR = ".agents/";
+export interface CopySetupOptions {
+    /** crabbox box slug to push to — its per-lease ssh key does the auth. */
+    slug: string;
+    /** Secrets bundle whose env the ssh/rsync children inherit (crabbox parity). */
+    secretsBundle?: string;
+    /** Override the local `~/.agents` dir (defaults to `getUserAgentsDir()`). */
+    userAgentsDir?: string;
+    /** Receives combined stdout/stderr of the rsync + refresh, if set. */
+    onData?: (chunk: string) => void;
+    /**
+     * Run `agents repo refresh` on the box after the push (default `true`). Set
+     * `false` when the caller runs the refresh itself in the box bootstrap — the
+     * lease path does this so the refresh runs AFTER the box installs agents-cli
+     * (this host-side push happens before the box boots agents-cli, so a host-side
+     * refresh here could not find the CLI).
+     */
+    refresh?: boolean;
+}
+export interface CopySetupResult {
+    /** The tracked files enumerated for the push (post-exclusion). */
+    files: string[];
+    /** rsync exit code, or null when the process failed to spawn. */
+    pushExitCode: number | null;
+    /** `agents repo refresh` exit code, or null when it was skipped/failed to spawn. */
+    refreshExitCode: number | null;
+}
+/**
+ * git-tracked files under `dir` (paths relative to `dir`), minus the never-copy
+ * set. Returns `[]` when `dir` is not a git repo — a caller with no tracked
+ * `~/.agents` simply copies nothing.
+ */
+export declare function enumerateTrackedFiles(dir: string): string[];
+/**
+ * Split crabbox's ssh argv (`['ssh', …opts, 'crabbox@host']`) into the `-e`
+ * transport string (`ssh …opts`) and the `crabbox@host` endpoint. This is what
+ * carries the per-lease identity key + known_hosts a raw ssh lacks.
+ */
+export declare function sshTransportFromArgv(sshArgv: string[]): {
+    rsh: string;
+    host: string;
+};
+/**
+ * rsync argv to push the tracked file set to `~/.agents` on the box. Reads the
+ * NUL-separated list at `filesFrom` (`--from0`, matching `ls-files -z`) so paths
+ * with spaces survive, and tunnels over crabbox's own ssh (`rsh`).
+ */
+export declare function buildSetupRsyncArgs(opts: {
+    rsh: string;
+    host: string;
+    filesFrom: string;
+    source: string;
+    remoteDir?: string;
+}): string[];
+/**
+ * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
+ * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
+ * `agents repo refresh` on the box. Refresh is skipped when the push fails or the
+ * file set is empty (nothing to refresh). Never throws — surfaces failure through
+ * the returned exit codes.
+ */
+export declare function copySetupToBox(opts: CopySetupOptions): Promise<CopySetupResult>;

package/dist/lib/crabbox/setup-copy.js

@@ -0,0 +1,127 @@
+/**
+ * Setup-copy for `agents run --lease` (RUSH-1920), transport = PUSH-FROM-LOCAL.
+ *
+ * A fresh crabbox box has agents-cli installed but none of the caller's own
+ * `~/.agents` config (skills, hooks, commands, MCP, profiles). This module
+ * replicates the *git-tracked* subset of the LOCAL `~/.agents` onto the box:
+ *
+ *   1. `git -C <userAgentsDir> ls-files` — tracked files only. Tracked-only is
+ *      the safety boundary: it excludes `.history/`, `.cache/`, `.system/` and
+ *      any keychain-backed secrets by construction (those are gitignored), so no
+ *      credential material is ever pushed.
+ *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
+ *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
+ *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
+ *   3. `agents repo refresh` on the box so the copied config takes effect.
+ *
+ * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
+ * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
+ * filter belts-and-braces the tracked-only guarantee.
+ *
+ * This is a self-contained local function the command layer calls; it does NOT
+ * ride the box-side bootstrap script (that only echoes the `copy-setup` progress
+ * sentinel — see `buildBootstrapScript`).
+ */
+import { spawn, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getUserAgentsDir } from '../state.js';
+import { crabboxEnv, crabboxSshArgv } from './cli.js';
+/** Remote path (relative to the box user's home) the tracked config lands in. */
+export const REMOTE_AGENTS_DIR = '.agents/';
+/** Top-level paths that must never be pushed, even if somehow tracked. */
+const NEVER_COPY = new Set(['.claude', '.claude.json']);
+/**
+ * git-tracked files under `dir` (paths relative to `dir`), minus the never-copy
+ * set. Returns `[]` when `dir` is not a git repo — a caller with no tracked
+ * `~/.agents` simply copies nothing.
+ */
+export function enumerateTrackedFiles(dir) {
+    const r = spawnSync('git', ['-C', dir, 'ls-files', '-z'], { encoding: 'utf-8' });
+    if (r.status !== 0 || !r.stdout)
+        return [];
+    return r.stdout
+        .split('\0')
+        .filter(Boolean)
+        .filter((f) => {
+        const top = f.split('/')[0];
+        return !NEVER_COPY.has(f) && !NEVER_COPY.has(top);
+    });
+}
+/**
+ * Split crabbox's ssh argv (`['ssh', …opts, 'crabbox@host']`) into the `-e`
+ * transport string (`ssh …opts`) and the `crabbox@host` endpoint. This is what
+ * carries the per-lease identity key + known_hosts a raw ssh lacks.
+ */
+export function sshTransportFromArgv(sshArgv) {
+    const host = sshArgv[sshArgv.length - 1];
+    const rsh = sshArgv.slice(0, -1).join(' '); // 'ssh -i <key> -o … -p 2222'
+    return { rsh, host };
+}
+/**
+ * rsync argv to push the tracked file set to `~/.agents` on the box. Reads the
+ * NUL-separated list at `filesFrom` (`--from0`, matching `ls-files -z`) so paths
+ * with spaces survive, and tunnels over crabbox's own ssh (`rsh`).
+ */
+export function buildSetupRsyncArgs(opts) {
+    const remote = `${opts.host}:${opts.remoteDir ?? REMOTE_AGENTS_DIR}`;
+    const source = opts.source.endsWith('/') ? opts.source : `${opts.source}/`;
+    return ['-az', '--files-from', opts.filesFrom, '--from0', '-e', opts.rsh, source, remote];
+}
+function runStreaming(cmd, args, env, onData) {
+    return new Promise((resolve) => {
+        const proc = spawn(cmd, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        const pump = (chunk) => {
+            const s = chunk.toString('utf-8');
+            if (onData)
+                onData(s);
+            else
+                process.stdout.write(s);
+        };
+        proc.stdout.on('data', pump);
+        proc.stderr.on('data', pump);
+        proc.on('error', () => resolve(null));
+        proc.on('close', (code) => resolve(code));
+    });
+}
+/**
+ * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
+ * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
+ * `agents repo refresh` on the box. Refresh is skipped when the push fails or the
+ * file set is empty (nothing to refresh). Never throws — surfaces failure through
+ * the returned exit codes.
+ */
+export async function copySetupToBox(opts) {
+    const dir = opts.userAgentsDir ?? getUserAgentsDir();
+    const files = enumerateTrackedFiles(dir);
+    if (files.length === 0) {
+        return { files, pushExitCode: null, refreshExitCode: null };
+    }
+    // crabbox provisions a per-lease ssh key; a raw `ssh crabbox@ip` fails publickey.
+    // Ask crabbox for its exact ssh invocation and tunnel rsync through it.
+    const sshArgv = crabboxSshArgv(opts.slug, { secretsBundle: opts.secretsBundle });
+    if (!sshArgv) {
+        return { files, pushExitCode: null, refreshExitCode: null };
+    }
+    const { rsh, host } = sshTransportFromArgv(sshArgv);
+    const env = crabboxEnv({ secretsBundle: opts.secretsBundle });
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agents-setup-copy-'));
+    const listPath = path.join(tmp, 'files.lst');
+    try {
+        // NUL-separated list, matching `buildSetupRsyncArgs`'s `--from0`.
+        fs.writeFileSync(listPath, files.join('\0'), 'utf-8');
+        const rsyncArgs = buildSetupRsyncArgs({ rsh, host, filesFrom: listPath, source: dir });
+        const pushExitCode = await runStreaming('rsync', rsyncArgs, env, opts.onData);
+        let refreshExitCode = null;
+        if (pushExitCode === 0 && opts.refresh !== false) {
+            // ssh <opts> crabbox@host bash -lc 'agents repo refresh'
+            const refreshArgs = [...sshArgv.slice(1), 'bash', '-lc', 'agents repo refresh'];
+            refreshExitCode = await runStreaming('ssh', refreshArgs, env, opts.onData);
+        }
+        return { files, pushExitCode, refreshExitCode };
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/lib/daemon.d.ts

@@ -33,9 +33,9 @@ export declare function isDaemonWedged(): boolean;
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
 /**
- * Single-instance claim for the daemon `_run` entrypoint.
+ * Single-instance claim for the daemon foreground entrypoint.
  *
- * `agents daemon _run` is reachable directly — a manual invocation, or a
+ * `agents __daemon-run` is reachable directly — a manual invocation, or a
  * service-manager restart that races a still-alive predecessor — bypassing the
  * start lock in startDaemon(). Without this guard runDaemon() would call
  * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
@@ -49,7 +49,7 @@ export declare function isDaemonRunning(): boolean;
  */
 export declare function claimDaemonInstance(): boolean;
 /**
- * Reap stray duplicate daemon processes — a `daemon _run` of THIS install that
+ * Reap stray duplicate daemon processes — a `__daemon-run` of THIS install that
  * isn't this process and isn't the pid-file owner. Mirrors the browser orphan
  * reaper (below): a predecessor that was SIGKILLed/OOM-ed without cleaning up,
  * or a duplicate that lost the pid-file write race, would otherwise keep a
@@ -141,8 +141,8 @@ export declare function ensureDaemonStarted(): {
  */
 export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv, oauthToken?: string | null): NodeJS.ProcessEnv;
 /**
- * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
- * exact form that works under a direct `daemon _run`.
+ * 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`

package/dist/lib/daemon.js

@@ -187,9 +187,9 @@ export function isDaemonRunning() {
     return false;
 }
 /**
- * Single-instance claim for the daemon `_run` entrypoint.
+ * Single-instance claim for the daemon foreground entrypoint.
  *
- * `agents daemon _run` is reachable directly — a manual invocation, or a
+ * `agents __daemon-run` is reachable directly — a manual invocation, or a
  * service-manager restart that races a still-alive predecessor — bypassing the
  * start lock in startDaemon(). Without this guard runDaemon() would call
  * writeDaemonPid() unconditionally, clobber a live daemon's recorded PID, and
@@ -216,7 +216,7 @@ export function claimDaemonInstance() {
     }
 }
 /**
- * Reap stray duplicate daemon processes — a `daemon _run` of THIS install that
+ * Reap stray duplicate daemon processes — a `__daemon-run` of THIS install that
  * isn't this process and isn't the pid-file owner. Mirrors the browser orphan
  * reaper (below): a predecessor that was SIGKILLed/OOM-ed without cleaning up,
  * or a duplicate that lost the pid-file write race, would otherwise keep a
@@ -252,10 +252,10 @@ export function reapStrayDaemons(keepPid = process.pid) {
         const args = m[2];
         if (isNaN(pid) || pid === keepPid || pid === process.pid || pid === ownerPid)
             continue;
-        // Same install (same launch entry) AND a `daemon _run` command line.
+        // Same install (same launch entry) AND a `__daemon-run` command line.
         if (!args.includes(selfEntry))
             continue;
-        if (!/\bdaemon\b.*\b_run\b/.test(args))
+        if (!/\b__daemon-run\b/.test(args))
             continue;
         try {
             process.kill(pid, 'SIGTERM');
@@ -295,7 +295,7 @@ export function log(level, message) {
 }
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export async function runDaemon() {
-    // Single-instance guard: a direct `agents daemon _run` (manual, or a
+    // Single-instance guard: a direct `agents __daemon-run` (manual, or a
     // service-manager restart racing a live predecessor) must not clobber a
     // running daemon's pid file and start a second scheduler.
     if (!claimDaemonInstance()) {
@@ -1005,8 +1005,8 @@ export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readD
     return env;
 }
 /**
- * Resolve how to launch the daemon: `node <entry> daemon _run`, matching the
- * exact form that works under a direct `daemon _run`.
+ * 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`
@@ -1026,7 +1026,7 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     const { warnings } = validateDaemonBinary(agentsBin);
     for (const w of warnings)
         process.stderr.write(`[agents] ${w}\n`);
-    return getCliLaunch(['daemon', '_run'], agentsBin);
+    return getCliLaunch(['__daemon-run'], agentsBin);
 }
 /**
  * The directory of the Node runtime that generated this service manifest, kept

package/dist/lib/drive-sync.js

@@ -13,6 +13,7 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getDriveDir } from './state.js';
 import { AGENTS } from './agents.js';
+import { sshExec } from './ssh-exec.js';
 const execFileAsync = promisify(execFile);
 // `remote` flows from disk into rsync/ssh argv. Use a strict regex so a
 // tampered ~/.agents/drive/config.json can't sneak shell metacharacters or
@@ -92,9 +93,11 @@ export async function push() {
     assertValidRemote(config.remote);
     const localDir = getDriveDir() + '/';
     const remoteSpec = `${config.remote}:~/.agents/drive/`;
-    // Ensure remote directory exists. ssh's command argument is one positional
-    // string; we hand it as a single argv element so no local shell sees it.
-    await execFileAsync('ssh', [config.remote, 'mkdir -p ~/.agents/drive']);
+    // Ensure remote directory exists via the shared hardened SSH primitive.
+    const mkdir = sshExec(config.remote, 'mkdir -p ~/.agents/drive', { timeoutMs: 30_000 });
+    if (mkdir.code !== 0) {
+        throw new Error(`Failed to prepare remote drive directory on ${config.remote}${mkdir.stderr.trim() ? `: ${mkdir.stderr.trim()}` : ''}`);
+    }
     await execFileAsync('rsync', ['-az', '--exclude=config.json', localDir, remoteSpec]);
     config.lastPush = new Date().toISOString();
     writeDriveConfig(config);

package/dist/lib/event-stream.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The unified event reader -- one stream over BOTH operational events
+ * (`~/.agents/events.jsonl` via events.ts: secrets, commands, teams, ...) and
+ * agent-semantic events (the per-session activity logs via activity.ts: plans,
+ * PRs, worktrees, sub-agents, artifacts). They share one {@link EventType}
+ * vocabulary and one {@link EventRecord} shape, so `agents events` and any
+ * higher-level feature (a session/project summarizer, RSS) read them together.
+ *
+ * The two write paths stay separate for efficiency -- operational events append
+ * to the locked global log (low frequency), agent events append to lock-free
+ * per-session shards (high frequency, one writer each). This module is the
+ * single READ surface that merges them; nothing here writes.
+ */
+import { type EventRecord, type EventType, type EventLevel } from './events.js';
+export interface UnifiedQuery {
+    startDate?: Date;
+    endDate?: Date;
+    eventTypes?: EventType[];
+    level?: EventLevel;
+    agent?: string;
+    caller?: string;
+    command?: string;
+    module?: string;
+    limit?: number;
+    /** Include agent-semantic activity events. Default true. */
+    includeActivity?: boolean;
+    /** Override the activity dir (tests). */
+    activityRoot?: string;
+}
+/**
+ * Read a unified, newest-first event stream. Operational events come from
+ * events.ts `query()`; agent-semantic events from the activity logs, normalized
+ * to the same record shape and filtered identically. `limit` caps the merged
+ * result (each source is fetched up to `limit`, so the top-N is exact).
+ */
+export declare function readUnifiedEvents(q?: UnifiedQuery): EventRecord[];

package/dist/lib/event-stream.js

@@ -0,0 +1,68 @@
+/**
+ * The unified event reader -- one stream over BOTH operational events
+ * (`~/.agents/events.jsonl` via events.ts: secrets, commands, teams, ...) and
+ * agent-semantic events (the per-session activity logs via activity.ts: plans,
+ * PRs, worktrees, sub-agents, artifacts). They share one {@link EventType}
+ * vocabulary and one {@link EventRecord} shape, so `agents events` and any
+ * higher-level feature (a session/project summarizer, RSS) read them together.
+ *
+ * The two write paths stay separate for efficiency -- operational events append
+ * to the locked global log (low frequency), agent events append to lock-free
+ * per-session shards (high frequency, one writer each). This module is the
+ * single READ surface that merges them; nothing here writes.
+ */
+import { query, levelFor } from './events.js';
+import { readActivityAsEventRecords } from './activity.js';
+/** Apply the same filters query() applies, to an activity-derived record. */
+function matches(r, q) {
+    const ms = Date.parse(r.ts);
+    // Mirror query()'s default upper bound (endDate = now) so both sources drop
+    // future-dated records identically -- keeps the two in exact filter parity.
+    const endMs = (q.endDate ?? new Date()).getTime();
+    if (q.startDate && !Number.isNaN(ms) && ms < q.startDate.getTime())
+        return false;
+    if (!Number.isNaN(ms) && ms > endMs)
+        return false;
+    if (q.eventTypes && !q.eventTypes.includes(r.event))
+        return false;
+    if (q.level && (r.level ?? levelFor(r.event)) !== q.level)
+        return false;
+    if (q.agent && r.agent !== q.agent)
+        return false;
+    if (q.caller && r.caller !== q.caller)
+        return false;
+    if (q.command && r.command !== q.command &&
+        !(typeof r.command === 'string' && r.command.startsWith(q.command + ' ')))
+        return false;
+    if (q.module && r.module !== q.module)
+        return false;
+    return true;
+}
+/**
+ * Read a unified, newest-first event stream. Operational events come from
+ * events.ts `query()`; agent-semantic events from the activity logs, normalized
+ * to the same record shape and filtered identically. `limit` caps the merged
+ * result (each source is fetched up to `limit`, so the top-N is exact).
+ */
+export function readUnifiedEvents(q = {}) {
+    const ops = query({
+        startDate: q.startDate,
+        endDate: q.endDate,
+        eventTypes: q.eventTypes,
+        level: q.level,
+        agent: q.agent,
+        caller: q.caller,
+        command: q.command,
+        module: q.module,
+        limit: q.limit,
+    });
+    if (q.includeActivity === false)
+        return ops;
+    const acts = readActivityAsEventRecords({
+        sinceMs: q.startDate?.getTime(),
+        limit: q.limit,
+        root: q.activityRoot,
+    }).filter((r) => matches(r, q));
+    const merged = [...ops, ...acts].sort((a, b) => Date.parse(b.ts) - Date.parse(a.ts));
+    return typeof q.limit === 'number' ? merged.slice(0, q.limit) : merged;
+}

package/dist/lib/events.d.ts

@@ -12,7 +12,7 @@
  * - Performance tracking: withTiming() wrapper for any async function
  */
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;