@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/hosts/dispatch.js

@@ -1,14 +1,4 @@
 import { launchIdentityEnv } from '../launch-identity.js';
-/**
- * Dispatch a headless `agents …` command onto a host over SSH.
- *
- * The command is launched detached (`nohup … &`) writing combined output to a
- * remote log and its exit code to a sibling `.exit` file, so progress survives a
- * dropped connection (followed via offset-tail in progress.ts). This is the
- * offload win: the process/thread/file fan-out happens on the host, not the
- * laptop. `agents run` uses it; `agents teams start --watch --device` reuses the
- * same core so a remote team supervisor keeps running after you disconnect.
- */
 import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
@@ -22,15 +12,7 @@ import { wrapHostCommandWithCredentials } from './credentials.js';
 import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
 import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV, REMOTE_INTERACTIVE_ENV } from '../types.js';
-// The home-relative portability helpers live in project-root.js (the canonical
-// home-relative conversion home), reused by the interactive `agents ssh` login
-// shell builder (devices/connect.ts) as well as this dispatch layer. Re-exported
-// here so existing `hosts/dispatch.js` importers and tests keep resolving them.
 export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
-/**
- * Diagnostic helper for RUSH-2441: log the requested agent and initial remote
- * `agents run` argv without changing normal command output.
- */
 function logForwardedArgs(kind, agent, version, args, hasPrompt) {
     if (!process.env.AGENTS_DISPATCH_DEBUG)
         return;
@@ -51,62 +33,18 @@ function logForwardedArgs(kind, agent, version, args, hasPrompt) {
     }
     process.stderr.write(`[dispatch:${kind}] agent=${agent}${version ? `@${version}` : ''} args=${JSON.stringify(safeArgs)}\n`);
 }
-// Use $HOME (not ~) so the path is correct whether or not it's quoted and
-// regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
-// injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
-/**
- * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
- * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
- * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
- * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
- * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
- * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
- */
 export function withActorEnv(env) {
     return { ...actorEnv(resolveActor()), ...launchIdentityEnv(), ...(env ?? {}) };
 }
-/**
- * The shell-export prelude prepended to EVERY remote `agents run` dispatch —
- * actor provenance plus, for a `run auto` dispatch, the chain-hop guard
- * (RUN_AUTO_HOST_RESOLVED_ENV): this dispatch already IS the affinity pick, so
- * the remote CLI must not re-run host affinity and hop to a third host. The
- * guard MUST be a shell export (landing in the remote CLI's own process.env,
- * which `runAutoDefaultsToAffinity` reads) — a forwarded `--env` flag would
- * only reach the spawned agent's env and the remote `run auto` would re-pick.
- * Shared by the interactive (runInteractiveOnHost) and detached
- * (launchDetached) paths so both behave identically.
- *
- * `extra` carries the markers that are true of ONE path rather than both — the
- * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
- * requirement). It goes through this builder rather than being concatenated on
- * at the call site so every remote env marker is exported the same way, in one
- * place.
- */
 export function remoteRunShellPrelude(agent, extra = {}) {
     const exports = posixEnvExports(remoteRunEnv(agent, extra));
     return exports ? `${exports}; ` : '';
 }
-/**
- * The env every remote `agents run` dispatch carries across the SSH hop —
- * actor provenance, the `run auto` chain-hop guard, and the caller's path
- * markers. `remoteRunShellPrelude` renders it as POSIX exports; a Windows peer
- * gets the same record as `$env:` assignments in its PowerShell script.
- */
 export function remoteRunEnv(agent, extra = {}) {
     const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
     return withActorEnv({ ...guard, ...extra });
 }
-/**
- * Launch a detached login-shell command in its own Unix session/process group.
- *
- * Node is already a hard requirement for a host that can run `agents`. Its
- * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
- * a non-interactive shell where the background wrapper can remain in the SSH
- * shell's process group. Returning the group leader PID makes `kill(-pid)` a
- * reliable whole-tree operation for both normal stops and rollback cleanup.
- */
 export function buildDetachedLaunchCommand(inner) {
     const nodeScript = [
         "const { spawn } = require('node:child_process');",
@@ -116,7 +54,6 @@ export function buildDetachedLaunchCommand(inner) {
     ].join(' ');
     return `bash -lc ${shellQuote(`node -e ${shellQuote(nodeScript)}`)}`;
 }
-/** Build the detached PowerShell launch protocol used by Windows SSH hosts. */
 export function buildWindowsDetachedLaunchCommand(opts) {
     const log = windowsRemotePath(opts.remoteLog);
     const exit = windowsRemotePath(opts.remoteExit);
@@ -159,27 +96,14 @@ function terminateRemoteLaunch(task) {
             `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
     }
 }
-/** Terminate a detached dispatch that its caller could not persist locally. */
 export function terminateDispatchedTask(task) {
     terminateRemoteLaunch(task);
     updateTask(task.id, terminalPatch(143));
 }
-/**
- * Build the remote shell used by {@link stopDispatchedTask}. Exported for
- * unit tests — the keep-log / no-clobber contract lives in this script.
- *
- * Protocol (printed to stdout for the local caller):
- * - `SIGNALED`  — process group was live; SIGTERM/KILL applied; wrote 143
- * - `ALREADY` + code — group gone; adopted existing `.exit` (never overwrite)
- * - `GONE` — group gone and no `.exit`; write 143 as the local stop outcome
- * Exit 1 if the group is still alive after TERM/KILL (can't stop it).
- */
 export function buildStopRemoteCommand(pid, remoteExit) {
     if (!Number.isInteger(pid) || pid <= 0) {
         throw new Error(`Invalid remote task pid: ${pid}`);
     }
-    // Only force-write 143 when we actually signaled a live group (or nothing
-    // left a code). Never `echo 143` over a real completed-run exit code.
     return (`if kill -TERM -- -${pid} 2>/dev/null; then ` +
         `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
         `echo 143 > ${remoteExit}; echo SIGNALED; ` +
@@ -202,14 +126,6 @@ export function buildWindowsStopRemoteCommand(pid, remoteExit) {
         `else { Set-Content -LiteralPath ${exit} -Value 143 -NoNewline -Encoding ascii; Write-Output 'GONE' }`;
     return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
 }
-/**
- * Stop a running host task from the origin machine (`agents devices stop <id>`).
- *
- * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
- * persist), this keeps the remote log so `agents logs <id>` still works,
- * writes a terminal `.exit` marker only when we actually stopped a live group
- * (or no code existed), and never clobbers a real completed-run exit code.
- */
 export function stopDispatchedTask(task) {
     if (task.status !== 'running') {
         throw new Error(`Task ${task.id} is already ${task.status}`);
@@ -232,26 +148,13 @@ export function stopDispatchedTask(task) {
         if (Number.isFinite(parsed))
             code = parsed;
     }
-    // SIGNALED / GONE / ALREADY all end with a terminal local record.
     return updateTask(task.id, terminalPatch(code)) ?? { ...task, ...terminalPatch(code) };
 }
-/**
- * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
- * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
- * so the nohup/exit-file/offset-tail machinery lives in exactly one place.
- *
- * POSIX hosts use a detached bash process group; Windows hosts use a hidden
- * detached PowerShell process and the same durable log/exit-file protocol.
- */
 async function launchDetached(host, target, opts) {
     const remoteShell = remoteShellFor(host.os ?? resolveRemoteOsSync(host.name));
     const id = randomUUID().slice(0, 8);
     const remoteLog = `${REMOTE_DIR}/${id}.log`;
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
-    // Inner command run under a login shell so PATH resolves `agents`. Export the
-    // resolved actor provenance first so the detached remote run inherits it
-    // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028); a
-    // `run auto` dispatch also gets the chain-hop guard (remoteRunShellPrelude).
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
     const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
     const prelude = remoteRunShellPrelude(opts.agentLabel);
@@ -259,13 +162,7 @@ async function launchDetached(host, target, opts) {
     if (opts.copyCreds) {
         inner = wrapHostCommandWithCredentials(inner, opts.copyCreds);
     }
-    // When credentials ride this launch, verify the host key strictly against the
-    // managed pin (the gate in exec.ts already required the host to be pinned) and
-    // force a fresh connection — reusing a control socket opened by an earlier
-    // accept-new connection would bypass the strict check (RUSH-1767).
     const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
-    // Outer: ensure dir, launch the login-shell wrapper as a new process-group
-    // leader, and print that leader PID.
     const launch = remoteShell === 'powershell'
         ? buildWindowsDetachedLaunchCommand({
             forwardedArgs: opts.forwardedArgs,
@@ -326,23 +223,9 @@ async function launchDetached(host, target, opts) {
         extraSshArgs: hostIdentityArgs(host),
         remoteShell,
     });
-    // -1 = the follow window closed while the run continues on the host. Leave the
-    // record 'running' (do NOT freeze it terminal) so a later `agents devices ps` / `agents logs`
-    // reconcile against the remote `.exit` resolves the true final status.
     const finished = exitCode === -1 ? task : (updateTask(id, terminalPatch(exitCode)) ?? task);
     return { task: finished, exitCode };
 }
-/**
- * Build the remote `agents run …` argv for a host dispatch. Pure so the
- * session-id / resume flag wiring is unit-testable without an SSH round-trip.
- * `--session-id` and `--resume` are mutually exclusive (the CLI rejects both);
- * resume wins when — defensively — both are set.
- *
- * Every field here is classified 'forward' in RUN_OPTION_FORWARDING
- * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
- * the table side.
- */
-/** Compose `agent[@version][#account]` so the peer resolves ITS slot (PHNX-3940 T5). */
 function runAgentSpecArg(opts) {
     if (opts.accountPicker)
         return `${opts.agent}#`;
@@ -360,7 +243,6 @@ export function buildRunForwardedArgs(opts) {
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
-    // 'auto' is the remote default — forwarding it would only add noise.
     if (opts.effort && opts.effort !== 'auto')
         args.push('--effort', opts.effort);
     for (const kv of opts.env ?? [])
@@ -410,13 +292,6 @@ export function buildRunForwardedArgs(opts) {
     logForwardedArgs('headless', opts.agent, opts.version, args, true);
     return args;
 }
-/**
- * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
- * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
- * normal interactive TUI / tmux wrapper. A prompt is only included when the
- * caller explicitly forced interactive mode (otherwise the remote CLI would
- * infer headless from the prompt).
- */
 export function buildInteractiveRunForwardedArgs(opts) {
     if (opts.version && opts.accountPicker) {
         throw new Error('Interactive host dispatch cannot combine an account picker with a version pin');
@@ -431,7 +306,6 @@ export function buildInteractiveRunForwardedArgs(opts) {
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
-    // 'auto' is the remote default — forwarding it would only add noise.
     if (opts.effort && opts.effort !== 'auto')
         args.push('--effort', opts.effort);
     for (const kv of opts.env ?? [])
@@ -470,30 +344,8 @@ export function buildInteractiveRunForwardedArgs(opts) {
     logForwardedArgs('interactive', opts.agent, opts.version, args, Boolean(opts.prompt && opts.forceInteractive));
     return args;
 }
-/**
- * The remote command of an interactive host dispatch, by peer shell.
- *
- * A Windows peer's sshd hands the command to PowerShell, which cannot parse the
- * POSIX `export …; { cd … || cd "$HOME"; } && agents …` form (a `run --device
- * <windows box>` from a TTY died with `At line:1 char:420` at the `||`). That
- * peer gets the rendered PowerShell every other `--device` site uses — env,
- * mirrored cwd and argv inside one `-EncodedCommand` — the interactive analogue
- * of `buildWindowsDetachedLaunchCommand`.
- */
 export function buildInteractiveRemoteCommand(remoteShell, opts) {
     const forwardedArgs = buildInteractiveRunForwardedArgs(opts);
-    // Forward actor provenance so the interactive remote run inherits it rather
-    // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
-    // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
-    //
-    // REMOTE_INTERACTIVE_ENV rides the same prelude and tells the remote CLI its
-    // stdio is this ssh link: it marks the run as reconnect-managed (a drop is
-    // answered by reconnect.ts, which rejoins the live pane or resumes the
-    // session in place) and, when the launcher has no TTY (CI, scripts), requires
-    // the detached pane that is the run's only interface. Since PHNX-3316 it no
-    // longer forces the tmux wrap on a TTY-followed run — the peer's
-    // tmux.enabled decides that. Set here, on the interactive path only:
-    // `launchDetached` already setsids the headless one.
     const env = { [REMOTE_INTERACTIVE_ENV]: '1' };
     if (remoteShell === 'powershell') {
         if (opts.copyCreds)
@@ -510,42 +362,22 @@ export function buildInteractiveRemoteCommand(remoteShell, opts) {
     const remoteCmd = `${remoteRunShellPrelude(opts.agent, env)}${cwd}${invocation}`;
     return opts.copyCreds ? wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds) : remoteCmd;
 }
-/**
- * Run an agent interactively on a host, forwarding the local TTY over SSH.
- * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
- * tmux wrapping; the local machine is just the transport.
- */
 export async function runInteractiveOnHost(host, opts) {
     const target = sshTargetFor(host);
-    // Concrete version pins fail loud here (RUSH-2313) so we never open a TTY
-    // to a box that cannot run the pin.
     const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const remoteCmd = buildInteractiveRemoteCommand(remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)), opts);
-    // Credentials ride this stream when --copy-creds is set: verify the host key
-    // strictly against the managed pin and force a fresh connection so a stale
-    // accept-new control socket can't bypass the check (RUSH-1767).
     const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
     return sshStream(target, remoteCmd, {
         tty: process.stdin.isTTY,
-        // NOT multiplexed. `ControlPath=cm-%C` hashes only local host / remote host
-        // / port / user, so every agent tab pointed at a peer shares ONE master —
-        // and OpenSSH closes every channel on it the instant that master dies. One
-        // blink therefore ejected all six tabs on a box at once, which is what made
-        // a brief outage read as "all my agents exited" (RUSH-3125). The handshake
-        // this gives up is a one-time ~200ms on a session that runs for hours;
-        // probes and fan-outs keep the shared master, where it actually pays.
         multiplex: false,
         hostKeyOpts: credHostKeyOpts,
         extraSshArgs: hostIdentityArgs(host),
     });
 }
-/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --device` path). */
 export async function dispatchToHost(host, opts) {
     const target = sshTargetFor(host);
-    // Concrete agent@version pins fail loud before we print "Dispatched" and
-    // leave a dead remote log (RUSH-2313). Aliases stay remote-resolved.
     const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
@@ -558,18 +390,10 @@ export async function dispatchToHost(host, opts) {
         agentLabel: opts.agent,
         promptLabel: opts.prompt,
         name: opts.name,
-        // On resume the remote session keeps its existing id; record that id so the
-        // task stays mapped to the same session.
         sessionId: opts.resume ?? opts.sessionId,
         copyCreds: opts.copyCreds,
     });
 }
-/**
- * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
- * used for `teams start --watch --device`, whose supervisor must outlive the SSH
- * connection. Reachability is assumed (the caller has already resolved the host);
- * a launch failure surfaces the remote stderr.
- */
 export async function dispatchAgentsCommand(host, opts) {
     const target = sshTargetFor(host);
     return launchDetached(host, target, {

package/dist/lib/hosts/logs.d.ts

@@ -1,38 +1,13 @@
-/**
- * Shared host-task log viewer — the show-or-follow core behind the
- * top-level `agents logs <id>`.
- *
- * A running task with follow re-enters the offset-tail (`followHostTask`).
- * Otherwise the view is **concise by default**: a bounded tail of the captured
- * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
- * log. `full` opts into the entire raw log. (A host run's real transcript lives
- * on the remote, not the local index — surfacing its rich summary needs remote
- * runs to be discoverable there first; until then the bounded tail is the safe
- * concise default.) Kept in one place so the two commands can never drift.
- */
 import { type HostTask } from './tasks.js';
 interface HostLogResult {
-    /** False when no host task with this id exists (caller may fall through to sessions). */
     found: boolean;
-    /** Process exit code to adopt when the task was shown/followed. */
     exitCode?: number;
 }
-/**
- * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
- * default; `full` dumps the entire raw combined-stdout log.
- */
 export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
-/**
- * Machine-readable form of a host-dispatch task's log — the task record plus its
- * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
- * Reconciles a still-'running' record from the remote `.exit` first, like the
- * text path does.
- */
 export declare function hostTaskLogJson(id: string): {
     found: boolean;
     task?: HostTask;
     log?: string | null;
 };
-/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
 export declare function tailLines(text: string, n: number): string;
 export {};

package/dist/lib/hosts/logs.js

@@ -1,15 +1,3 @@
-/**
- * Shared host-task log viewer — the show-or-follow core behind the
- * top-level `agents logs <id>`.
- *
- * A running task with follow re-enters the offset-tail (`followHostTask`).
- * Otherwise the view is **concise by default**: a bounded tail of the captured
- * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
- * log. `full` opts into the entire raw log. (A host run's real transcript lives
- * on the remote, not the local index — surfacing its rich summary needs remote
- * runs to be discoverable there first; until then the bounded tail is the safe
- * concise default.) Kept in one place so the two commands can never drift.
- */
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
@@ -17,12 +5,7 @@ import { followHostTask } from './progress.js';
 import { reconcileTask } from './reconcile.js';
 import { sshExecRaw } from '../ssh-exec.js';
 import { encodePowershell } from './remote-cmd.js';
-/** Lines of raw combined-stdout to show in the concise (non-`full`) view. */
 const HOST_LOG_TAIL_LINES = 40;
-/**
- * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
- * default; `full` dumps the entire raw combined-stdout log.
- */
 export async function showHostTaskLog(id, follow, full = false) {
     const task = loadTask(id);
     if (!task)
@@ -36,19 +19,12 @@ export async function showHostTaskLog(id, follow, full = false) {
             remoteShell: task.remoteShell,
             extraSshArgs: task.identityFile ? ['-i', task.identityFile, '-o', 'IdentitiesOnly=yes'] : [],
         });
-        // -1 = follow window closed; the run continues on the host (not a failure,
-        // so exit 0). Any real code is the finished run — persist the terminal
-        // status the killed dispatch follower would have written.
         if (code === -1)
             return { found: true, exitCode: 0 };
         updateTask(id, terminalPatch(code));
         return { found: true, exitCode: code };
     }
-    // Non-follow view: heal a still-'running' record from the remote `.exit` so a
-    // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
-    // ssh) once the record is already terminal.
     reconcileTask(task);
-    // Raw combined-stdout: the whole log with `full`, else a bounded tail.
     const raw = readTaskLog(task);
     if (raw === null) {
         process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
@@ -57,40 +33,24 @@ export async function showHostTaskLog(id, follow, full = false) {
     process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
     return { found: true, exitCode: 0 };
 }
-/**
- * Machine-readable form of a host-dispatch task's log — the task record plus its
- * combined stdout. Powers `agents logs <id> --json` for the host-task branch.
- * Reconciles a still-'running' record from the remote `.exit` first, like the
- * text path does.
- */
 export function hostTaskLogJson(id) {
     const task = loadTask(id);
     if (!task)
         return { found: false };
-    // reconcileTask returns the healed record; it does NOT mutate its argument in
-    // place. Emit the reconciled task so a run that finished between dispatch and
-    // this one-shot read surfaces its terminal status/exitCode, not a stale
-    // 'running'. (The text path can discard the return — it only reads the log by
-    // id — but this JSON payload carries task.status straight to the consumer.)
     const reconciled = reconcileTask(task);
     return { found: true, task: reconciled, log: readTaskLog(reconciled) };
 }
-/** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
 function readTaskLog(task) {
     try {
         return fs.readFileSync(localLogPath(task.id), 'utf-8');
     }
     catch {
-        // No local log — task was dispatched with --no-follow. Fetch from the remote
-        // on demand and cache locally so subsequent calls are instant.
         const remote = fetchAndCacheRemoteLog(task);
         return remote !== null ? remote.toString('utf-8') : null;
     }
 }
-/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
 export function tailLines(text, n) {
     const lines = text.split('\n');
-    // A trailing newline yields a final empty element — drop it from the count.
     if (lines.length > 0 && lines[lines.length - 1] === '')
         lines.pop();
     if (lines.length <= n)
@@ -99,15 +59,6 @@ export function tailLines(text, n) {
     const note = chalk.gray(`… ${hidden} earlier line${hidden === 1 ? '' : 's'} hidden — pass --full for the whole log\n`);
     return note + lines.slice(-n).join('\n') + '\n';
 }
-/**
- * Fetch a task's remote log over SSH, write it to the local mirror path (for
- * future instant reads), and return its content. Returns null when the host is
- * unreachable or the remote log is empty/absent.
- *
- * `remoteLog` is a $HOME-prefixed path with a safe (hex) basename — intentionally
- * unquoted so the remote shell expands $HOME, matching the contract in reconcile.ts
- * and progress.ts.
- */
 function fetchAndCacheRemoteLog(task) {
     const command = task.remoteShell === 'powershell'
         ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`$path = Join-Path $HOME '${task.remoteLog.replace(/^\$HOME\//, '').replace(/'/g, "''")}'; if (Test-Path -LiteralPath $path) { $bytes = [IO.File]::ReadAllBytes($path); [Console]::OpenStandardOutput().Write($bytes, 0, $bytes.Length) }`)}`
@@ -119,10 +70,9 @@ function fetchAndCacheRemoteLog(task) {
     });
     if (res.code !== 0 || res.stdout.length === 0)
         return null;
-    // The hosts cache dir already exists (saveTask created it) — write is best-effort.
     try {
         fs.writeFileSync(localLogPath(task.id), res.stdout);
     }
-    catch { /* best-effort cache */ }
+    catch { }
     return res.stdout;
 }

package/dist/lib/hosts/option.d.ts

@@ -1,14 +1,2 @@
-/**
- * Shared `--device` option registrar. Every command that can run on a remote device
- * declares the flag through here, so its spelling, help text, and companions
- * (`--remote-cwd`, `--no-tty`, `--any`) stay identical everywhere and show up in
- * each command's `--help`.
- *
- * The flags are consumed centrally by `maybeRunOnHost` (passthrough.ts) *before*
- * commander parses, so for a real remote run the local action never sees them.
- * Registering them here still matters: it documents the flag and keeps the local
- * fall-through (e.g. `--device <this-machine>`) from erroring on an unknown option.
- */
 import type { Command } from 'commander';
-/** Attach the standard `--device` flag family to a command and return it (chainable). */
 export declare function addHostOption(cmd: Command): Command;

package/dist/lib/hosts/option.js

@@ -1,15 +1,3 @@
-/**
- * Shared `--device` option registrar. Every command that can run on a remote device
- * declares the flag through here, so its spelling, help text, and companions
- * (`--remote-cwd`, `--no-tty`, `--any`) stay identical everywhere and show up in
- * each command's `--help`.
- *
- * The flags are consumed centrally by `maybeRunOnHost` (passthrough.ts) *before*
- * commander parses, so for a real remote run the local action never sees them.
- * Registering them here still matters: it documents the flag and keeps the local
- * fall-through (e.g. `--device <this-machine>`) from erroring on an unknown option.
- */
-/** Attach the standard `--device` flag family to a command and return it (chainable). */
 export function addHostOption(cmd) {
     return cmd
         .option('-D, --device <name>', 'Run this command on another machine over SSH instead of locally — a registered device, user@host, or `all` to fan out across every registered device. See `agents devices` / `agents hosts`.')