@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/lib/ssh-exec.js

@@ -18,6 +18,14 @@ import { getCacheDir } from './state.js';
  * smuggled in as part of a remote command, and `sshExec` additionally rejects a
  * leading `-` so it can never be parsed as an ssh argv flag.
  */
+/**
+ * ssh's own connection-layer failure code — the transport dropped or never came
+ * up, as opposed to the remote command choosing an exit status. Defined here,
+ * in the layer that owns the ssh invocation, and re-exported by
+ * `lib/hosts/reconnect.ts` as `SSH_CONN_FAILURE` so there is one constant for
+ * the concept rather than two that can drift apart.
+ */
+export const SSH_CONN_FAILURE_CODE = 255;
 export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
 export function assertValidSshTarget(host) {
     if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
@@ -314,20 +322,128 @@ export function sshExecRawStream(target, remoteCmd, opts) {
 export function sshReachable(target, timeoutMs = 10000) {
     return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
 }
+/**
+ * The DEC private modes a full-screen remote app turns ON and, when it exits
+ * cleanly, turns back off itself. A remote agent TUI killed by a dropped link
+ * never gets to, so they stay enabled on the LOCAL terminal after ssh is gone:
+ * focus reporting (1004) and the mode/colour-scheme reports (996/997) then make
+ * the terminal emit answerback sequences at a shell that is not expecting them,
+ * which is the `^[[?997;1n ^[[I ^[[O` litter seen after a drop (RUSH-3125). Also
+ * resets bracketed paste (2004), the alternate screen (1049), mouse tracking
+ * (1000/1002/1003/1006), and re-shows the cursor (25) — every one of which a TUI
+ * leaves armed the same way.
+ */
+export const TERMINAL_MODE_RESET = '\x1b[?1004l\x1b[?996l\x1b[?997l\x1b[?2004l\x1b[?1049l'
+    + '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?25h';
+/**
+ * Put the local terminal back the way ssh found it.
+ *
+ * Two independent kinds of state survive a hard ssh death, and BOTH have to be
+ * undone or the next thing the user sees is corrupted:
+ *
+ *  - **termios** (kernel side): `-tt` puts the tty in raw mode, so a killed ssh
+ *    leaves it with echo and line-editing off. `saved` is the `stty -g` snapshot
+ *    taken before the spawn; restoring it is exact, unlike guessing at `sane`.
+ *  - **DEC private modes** (terminal side): see {@link TERMINAL_MODE_RESET}.
+ *
+ * Then drain whatever the terminal already answered back into the input buffer.
+ * Without the drain those bytes are not merely cosmetic — they are still queued
+ * on the tty, so the NEXT attach hands them straight to the agent as if the user
+ * had typed them.
+ *
+ * Best-effort by construction: this runs while recovering from a failure, so a
+ * missing `stty`, a non-TTY stdin, or a closed stream must never turn a
+ * recoverable drop into a thrown error.
+ */
+export function restoreLocalTerminal(saved, opts) {
+    try {
+        if (saved)
+            spawnSync('stty', [saved], { stdio: ['inherit', 'ignore', 'ignore'] });
+    }
+    catch { /* no stty, or stdin is not a tty — nothing to restore */ }
+    try {
+        if (process.stdout.isTTY)
+            process.stdout.write(TERMINAL_MODE_RESET);
+    }
+    catch { /* stream closed */ }
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode?.(false);
+    }
+    catch { /* stdin not controllable in this context */ }
+    // The DRAIN is the one destructive step here, so it is opt-in per exit. See
+    // {@link sshStream} for why it must not run on a clean exit.
+    if (!opts.drainStdin)
+        return;
+    try {
+        // read() on a paused non-flowing stdin returns the buffered bytes and
+        // discards them; the loop clears a burst rather than one chunk.
+        if (process.stdin.isTTY) {
+            while (process.stdin.read() !== null) { /* discard */ }
+        }
+    }
+    catch { /* stdin not readable in this context */ }
+}
+/** `stty -g` snapshot of the local tty, or undefined when there is nothing to snapshot. */
+export function saveLocalTerminal() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    try {
+        const r = spawnSync('stty', ['-g'], { stdio: ['inherit', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const out = r.status === 0 ? r.stdout?.trim() : '';
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
  * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
  * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
  * until the remote command exits and returns its exit code (255 is ssh's own
  * connection-layer failure; any other non-zero is the remote command's code).
+ *
+ * On a `tty` stream the local terminal state is snapshotted before the spawn and
+ * restored after it. ssh restores termios itself when it exits cleanly, so this
+ * is for the case that matters here: the link dying under a full-screen agent
+ * TUI, which leaves the tty raw and the TUI's DEC modes armed. Doing it HERE
+ * rather than in the reconnect loop means every caller that opens an interactive
+ * remote stream is covered, not just the one that noticed (RUSH-3125).
+ *
+ * **The stdin drain is gated on an ABNORMAL exit, and the distinction is not
+ * cosmetic.** Resetting termios and the DEC modes is idempotent — on a clean
+ * exit ssh and the remote TUI have already done it, so re-doing it changes
+ * nothing. Draining stdin is destructive: it discards whatever the user has
+ * typed ahead. On a clean exit those bytes are legitimate type-ahead the
+ * resuming shell should receive, and eating them would be a new bug in every
+ * caller of this function (`runInteractiveOnHost`, the remote-tmux attach in
+ * commands/go.ts, the remote secrets browse) rather than a fix. Only an
+ * abnormal exit — ssh killed by a signal (`status === null`) or its own
+ * connection-layer failure (255) — produces the answerback storm the drain
+ * exists to clear, because only then did the TUI die without sending its own
+ * mode resets.
  */
 export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
     const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), ...tty, target, remoteCmd];
-    const res = spawnSync('ssh', args, { stdio: 'inherit' });
-    if (typeof res.status === 'number')
-        return res.status;
-    return 255; // spawn error / signal — treat as a connection-layer failure
+    const saved = opts.tty ? saveLocalTerminal() : undefined;
+    let abnormal = true; // a throw before/inside the spawn is abnormal by definition
+    try {
+        const res = spawnSync('ssh', args, { stdio: 'inherit' });
+        const code = typeof res.status === 'number' ? res.status : 255;
+        // Killed by a signal (no numeric status) or ssh's own connection-layer
+        // failure — the two shapes in which the remote TUI never got to reset the
+        // terminal. Any other code is ssh exiting normally with the remote's status.
+        abnormal = res.status === null || code === SSH_CONN_FAILURE_CODE;
+        return code;
+    }
+    finally {
+        // `finally`, because the abnormal exits are precisely the ones that leave
+        // the terminal wrecked — but the drain within it is gated (see the doc).
+        if (opts.tty)
+            restoreLocalTerminal(saved, { drainStdin: abnormal });
+    }
 }

package/dist/lib/startup/command-registry.js

@@ -10,7 +10,7 @@ const LOADED_COMMAND_NAMES = [
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',
     'mailboxes', 'mailbox', 'artifacts', 'webhooks',
-    'humans', 'daemon',
+    'humans', 'daemon', 'traces',
 ];
 const INLINE_COMMAND_NAMES = [
     'perms', 'exec', 'jobs', 'cron', 'check', 'resources', 'hq', '_internal',

package/dist/lib/startup/dev-build.js

@@ -22,12 +22,12 @@ import * as path from 'path';
  * looking for `.git`.
  *
  * That package root does not always hold `.git` itself, though — this repo is a
- * monorepo where the package lives at `apps/cli` and `.git` sits one level
+ * monorepo where the package lives at `cli` and `.git` sits one level
  * higher, at the true repo root. `.git` is therefore searched for in a SMALL,
  * bounded set of ancestors above the package root (see
  * `DEV_BUILD_GIT_ANCESTOR_DEPTH`), not just the package root itself — a source
- * checkout run via tsx/ts-node from `apps/cli/src/` or built to
- * `apps/cli/dist/` must still be recognized. The bound keeps this well short of
+ * checkout run via tsx/ts-node from `cli/src/` or built to
+ * `cli/dist/` must still be recognized. The bound keeps this well short of
  * an unrelated ancestor repo: a real Homebrew npm-global install's package root
  * sits 3 directories below `/opt/homebrew` (`lib/node_modules/@phnx-labs/…`),
  * so a depth of 2 finds this repo's `.git` while staying short of Homebrew's.

package/dist/lib/state.d.ts

@@ -31,7 +31,7 @@ export declare function getHumansFilePath(): string;
  * file against `schema/agents-yaml.schema.json`. Exported so
  * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
-export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
+export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents/.system/). */

package/dist/lib/state.js

@@ -168,7 +168,7 @@ const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yam
 export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
 # https://github.com/phnx-labs/agents-cli
-# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
@@ -895,7 +895,6 @@ const META_KEY_SCOPE = {
     actors: 'central',
     seededPresets: 'central',
     hooks: 'central',
-    browser: 'central',
     config: 'central',
     hosts: 'central',
     fleet: 'central',
@@ -910,7 +909,12 @@ const META_KEY_SCOPE = {
  * in central is stale and must be migrated out). A key NOT listed here — e.g. one
  * a newer CLI version added — is preserved verbatim, never dropped + synced away.
  */
-const KNOWN_META_KEYS = new Set(Object.keys(META_KEY_SCOPE));
+const KNOWN_META_KEYS = new Set([
+    ...Object.keys(META_KEY_SCOPE),
+    // Removed browser-profile store. Kept only as a serializer tombstone so the
+    // first registry read can migrate it into this device's file and delete it.
+    'browser',
+]);
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.

package/dist/lib/subagents-registry.js

@@ -27,7 +27,7 @@
  *
  * The per-agent `transform`/metadata parsers are the escape hatch: they live in
  * `subagents.ts` and are referenced by the table, so the generic engine has zero
- * per-agent branches. See the integration tiers in `docs/subagents.md`.
+ * per-agent branches. See `docs/orchestration.md`.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/dist/lib/teams/agents.d.ts

@@ -1,6 +1,5 @@
 import { captureProcessStartTime } from '../platform/index.js';
 import { AgentType } from './parsers.js';
-import { NoViableDeviceError } from './scheduler.js';
 /**
  * Compute the Lowest Common Ancestor (LCA) of multiple file paths.
  * Returns the deepest common directory shared by all paths.
@@ -27,6 +26,16 @@ export declare enum AgentStatus {
 export declare const TERMINAL_STATUSES: ReadonlySet<AgentStatus>;
 /** True when a teammate has reached a terminal (completed/failed/stopped) status. */
 export declare function isTerminalStatus(status: AgentStatus): boolean;
+export type TeammateFailureStage = 'placement' | 'spawn' | 'execution' | 'dependency' | 'cloud';
+/** Durable evidence observed at a concrete teammate lifecycle boundary. */
+export interface TeammateFailure {
+    stage: TeammateFailureStage;
+    code: string;
+    message: string;
+    exit_code: number | null;
+    retryable: boolean;
+    observed_at: string;
+}
 /**
  * One remote teammate's liveness, resolved by a single host probe. Three states,
  * kept distinct on purpose (RUSH-2366):
@@ -201,6 +210,7 @@ export declare class AgentProcess {
     remotePid: number | null;
     remoteLog: string | null;
     remoteExit: string | null;
+    failure: TeammateFailure | null;
     remoteLogOffset: number;
     remotePollSnapshot: RemoteLivenessSnapshot | null;
     private eventsCache;
@@ -227,6 +237,7 @@ export declare class AgentProcess {
         cloud_session_id: string | null;
         cloud_repo: string | null;
         cloud_branch: string | null;
+        failure: TeammateFailure | null;
         agent_dir: string;
         cwd: string | null;
     }>;
@@ -432,6 +443,8 @@ export declare class AgentManager {
      */
     setCloudDispatcher(fn: CloudDispatchFn | null): void;
     registerAgent(agent: AgentProcess): void;
+    private failAgent;
+    private deferAgent;
     /**
      * Scan the agents dir for meta.json files not already in the in-memory
      * cache and load them. Needed when another process (e.g. a Planner
@@ -553,16 +566,6 @@ export declare class AgentManager {
     private maybeSchedulePlacement;
     /** Human label of a teammate's agent for the placement fail-loud message. */
     private placementAgentLabel;
-    /**
-     * Pre-flight the team pool at `teams start` (RUSH-2002): probe the pool and
-     * confirm each distinct agent among the pending, unpinned, pooled teammates
-     * has at least one viable device. Returns the first {@link NoViableDeviceError}
-     * so the command can fail loud BEFORE launching a wave, rather than silently
-     * leaving teammates stranded pending. A poolless team (no `--devices`) or a
-     * probe that could not gather positive evidence returns null — fail-loud fires
-     * only on proof that no device can run the agent, never on a probe miss.
-     */
-    preflightPlacement(taskName: string): Promise<NoViableDeviceError | null>;
     /**
      * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
      * The supervisor calls this each wave BEFORE listByTask() so the per-teammate
@@ -659,6 +662,5 @@ export declare class AgentManager {
         alreadyStopped: string[];
     }>;
     stop(agentId: string): Promise<boolean>;
-    private cleanupPartialAgent;
     private cleanupOldAgents;
 }