@phnx-labs/agents-cli 1.20.49 → 1.20.50

package/dist/lib/exec.js

@@ -16,6 +16,7 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
+import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
@@ -610,18 +611,25 @@ export function buildExecCommand(options) {
     else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
-    // Add model (only if explicitly provided by user)
-    if (options.model && template.modelFlag) {
+    // Add model. Prefer the user's explicit --model. Otherwise, for Codex, fall
+    // back to the model configured in the user's active ~/.codex/config.toml:
+    // Codex runs under a per-version CODEX_HOME (see buildExecEnv) that may not
+    // carry that setting, so without this it silently defaults to gpt-5.3-codex,
+    // which a ChatGPT-tier account can't use (HTTP 400). Forwarding keeps the
+    // user's default model setup for both `agents run` and `agents teams`.
+    const effectiveModel = options.model
+        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
+    if (effectiveModel && template.modelFlag) {
         const effectiveVersion = options.version || resolveVersion(options.agent, options.cwd || process.cwd());
         if (effectiveVersion) {
-            const resolved = resolveModel(options.agent, effectiveVersion, options.model);
+            const resolved = resolveModel(options.agent, effectiveVersion, effectiveModel);
             if (resolved.warning) {
                 process.stderr.write(`[agents] ${resolved.warning}\n`);
             }
             cmd.push(template.modelFlag, resolved.forwarded);
         }
         else {
-            cmd.push(template.modelFlag, options.model);
+            cmd.push(template.modelFlag, effectiveModel);
         }
     }
     // Add JSON output flags if requested

package/dist/lib/hosts/passthrough.js

@@ -91,6 +91,20 @@ export async function maybeRunOnHost(command, allArgs) {
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec)
         return false;
+    // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
+    // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
+    // command itself always runs locally on the orchestrator. Bail before the
+    // generic teams routing below so those flags reach the local action. Every
+    // other teams subcommand (`status`/`logs`/`stop`/…) keeps `--host` routing.
+    // Find the subcommand = the first non-flag token AFTER `teams` (robust to any
+    // leading global flags), then bail for the add/create aliases.
+    if (command === 'teams') {
+        const teamsIdx = allArgs.indexOf('teams');
+        const sub = teamsIdx >= 0 ? allArgs.slice(teamsIdx + 1).find((a) => !a.startsWith('-')) : undefined;
+        if (sub === 'add' || sub === 'a' || sub === 'create' || sub === 'c' || sub === 'new') {
+            return false;
+        }
+    }
     // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
     // device registry is the source of truth for machine identity. Reject a
     // conflicting pair rather than silently preferring one — same rule as run.
@@ -101,6 +115,11 @@ export async function maybeRunOnHost(command, allArgs) {
         process.exitCode = 1;
         return true;
     }
+    // `--devices` / `--hosts` fan out to every registered device locally; don't
+    // let a per-host passthrough turn it into a cascading remote fan-out.
+    const fleetFlag = allArgs.includes('--devices') || allArgs.includes('--hosts');
+    if (fleetFlag)
+        return false;
     const hostName = hostFlag ?? deviceFlag;
     if (!hostName)
         return false;
@@ -142,7 +161,17 @@ export async function maybeRunOnHost(command, allArgs) {
         }
         return true;
     }
-    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, resolveRemoteOsSync(host.name));
+    // Doctor commands probe the agent CLIs; remote POSIX login shells often don't
+    // have the agents shims on PATH, which produces false "not installed" negatives.
+    // Bootstrap PATH with the canonical shim locations before the remote command.
+    // Windows is skipped: PowerShell usually has the shim dir via the install
+    // profile, and single-quoted env values would not expand $HOME/$PATH.
+    const isDoctorCommand = command === 'doctor' || (command === 'teams' && forwarded[1] === 'doctor');
+    const remoteOs = resolveRemoteOsSync(host.name);
+    const env = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
+        ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
+        : undefined;
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +

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

@@ -13,6 +13,37 @@
  * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
  * longer spawns thousands of ssh processes per hour on the laptop.
  */
+/**
+ * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
+ * appends remote bytes into the local mirror forever; a team can spin 10+ chatty
+ * remote teammates, so the orchestrator must keep a bounded window (the full log
+ * always lives on the host). The teams remote path (agents.ts readNewEvents) writes
+ * its own append into each teammate's `stdout.log`, then truncates that file to its
+ * trailing `REMOTE_MIRROR_MAX_BYTES` — the parser has already consumed the bytes
+ * (status/digest updated via lastReadPos), so trailing-tail history is dead weight.
+ */
+export declare const REMOTE_MIRROR_MAX_BYTES: number;
+/**
+ * Pull the new bytes of a remote log since `offset` in ONE ssh round-trip.
+ *
+ * The teams remote-teammate monitor calls this each poll to advance its offset-tail
+ * cursor into the host's log, mirroring only the delta into the local `stdout.log`
+ * the stream-json parser consumes. Byte-exact (raw Buffer, no UTF-8 decode) so a
+ * multibyte character split at the `tail -c` boundary neither drifts the offset nor
+ * renders as U+FFFD — the same discipline `fetchProgress` uses. `bytes.length` is
+ * the exact wire count; `newOffset` is `offset + bytes.length`.
+ *
+ * Returns null on a transient ssh failure (the caller retries next poll without
+ * advancing). `remoteLog` is a $HOME-prefixed path with a safe basename; it's
+ * shell-quoted defensively even so.
+ */
+export declare function pullRemoteLogDelta(target: string, opts: {
+    remoteLog: string;
+    offset: number;
+}): {
+    bytes: Buffer;
+    newOffset: number;
+} | null;
 export interface FollowOptions {
     remoteLog: string;
     remoteExit: string;

package/dist/lib/hosts/progress.js

@@ -19,6 +19,41 @@ import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
+ * appends remote bytes into the local mirror forever; a team can spin 10+ chatty
+ * remote teammates, so the orchestrator must keep a bounded window (the full log
+ * always lives on the host). The teams remote path (agents.ts readNewEvents) writes
+ * its own append into each teammate's `stdout.log`, then truncates that file to its
+ * trailing `REMOTE_MIRROR_MAX_BYTES` — the parser has already consumed the bytes
+ * (status/digest updated via lastReadPos), so trailing-tail history is dead weight.
+ */
+export const REMOTE_MIRROR_MAX_BYTES = 512 * 1024;
+/**
+ * Pull the new bytes of a remote log since `offset` in ONE ssh round-trip.
+ *
+ * The teams remote-teammate monitor calls this each poll to advance its offset-tail
+ * cursor into the host's log, mirroring only the delta into the local `stdout.log`
+ * the stream-json parser consumes. Byte-exact (raw Buffer, no UTF-8 decode) so a
+ * multibyte character split at the `tail -c` boundary neither drifts the offset nor
+ * renders as U+FFFD — the same discipline `fetchProgress` uses. `bytes.length` is
+ * the exact wire count; `newOffset` is `offset + bytes.length`.
+ *
+ * Returns null on a transient ssh failure (the caller retries next poll without
+ * advancing). `remoteLog` is a $HOME-prefixed path with a safe basename; it's
+ * shell-quoted defensively even so.
+ */
+export function pullRemoteLogDelta(target, opts) {
+    // remoteLog is a dispatch-generated `$HOME/.agents/.cache/hosts/<hex>.log` path —
+    // interpolate UNQUOTED so the remote shell expands `$HOME` (shellQuote would
+    // single-quote it into a literal `$HOME`, and the tail would find nothing). The
+    // hex basename is injection-safe, matching fetchProgress below.
+    const remote = `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null`;
+    const res = sshExecRaw(target, remote, { timeoutMs: 20000, multiplex: true });
+    if (res.code === null)
+        return null; // ssh itself failed / timed out
+    return { bytes: res.stdout, newOffset: opts.offset + res.stdout.length };
+}
 /**
  * Build the per-task sentinel that separates the log tail from the exit-file
  * contents in one combined fetch. The task id (8 hex chars) makes collision with

package/dist/lib/hosts/remote-cmd.d.ts

@@ -44,7 +44,7 @@ export declare const HOST_ROUTING_SPECS: StripSpec[];
  * does not exist). Anything else — including an unknown/absent OS — keeps the
  * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
-export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string): string;
+export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string, env?: Record<string, string>): string;
 /** The two remote shell dialects we build commands for. */
 export type RemoteShell = 'posix' | 'powershell';
 /**

package/dist/lib/hosts/remote-cmd.js

@@ -61,13 +61,23 @@ export const HOST_ROUTING_SPECS = [
  * does not exist). Anything else — including an unknown/absent OS — keeps the
  * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
-export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os) {
+export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os, env) {
     if (remoteShellFor(os) === 'powershell') {
-        return buildWindowsAgentsCommand({ args: forwardedArgs, cwd: remoteCwd });
+        return buildWindowsAgentsCommand({ args: forwardedArgs, cwd: remoteCwd, env });
     }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
-    return `bash -lc ${shellQuote(withCwd)}`;
+    if (!env || Object.keys(env).length === 0) {
+        return `bash -lc ${shellQuote(withCwd)}`;
+    }
+    // Prepend env exports so the remote command sees the shims dir even when the
+    // login shell hasn't sourced the interactive rc files that usually add it.
+    // Values are double-quoted (not single-quoted) so remote variables like
+    // $HOME and $PATH are expanded by the login shell.
+    const exports = Object.entries(env)
+        .map(([k, v]) => `export ${shellQuote(k)}="${v.replace(/[\\"]/g, '\\$&')}"`)
+        .join('; ');
+    return `bash -lc ${shellQuote(`${exports}; ${withCwd}`)}`;
 }
 /**
  * Pick the remote shell dialect from a recorded OS/platform string. A Windows

package/dist/lib/shims.d.ts

@@ -203,6 +203,23 @@ export declare function removeVersionedAlias(agent: AgentId, version: string): b
  * Check if a versioned alias exists (the on-disk artifact for this platform).
  */
 export declare function versionedAliasExists(agent: AgentId, version: string): boolean;
+/**
+ * Read the user's configured Codex model from their active `~/.codex/config.toml`.
+ *
+ * Codex runs under a per-version `CODEX_HOME` (see `buildExecEnv`). A dispatch
+ * pinned to a version whose home config lacks a top-level `model` key silently
+ * falls back to Codex's built-in default (currently `gpt-5.3-codex`), which a
+ * ChatGPT-tier account is not entitled to use — the run dies with HTTP 400
+ * before doing any work. The user's model preference lives in whichever
+ * version-home was active when they set it (`~/.codex` symlinks to it), so it is
+ * NOT visible to a run pinned to a different version. Forwarding it via `--model`
+ * keeps the user's "default model setup" regardless of the active version-home,
+ * and is concurrency-safe (no file writes) when fanning out many parallel runs.
+ *
+ * Returns the top-level `model` only (ignores `[profile.*]` tables). Best-effort:
+ * a missing/unreadable/unset config yields `undefined` (caller keeps prior behaviour).
+ */
+export declare function readCodexConfiguredModel(): string | undefined;
 /**
  * Switch the agent's config symlink to point to a specific version.
  * e.g., ~/.claude -> ~/.agents/versions/claude/2.0.65/home/.claude/

package/dist/lib/shims.js

@@ -1008,6 +1008,35 @@ function getAgentConfigPath(agent) {
     const home = process.env.AGENTS_REAL_HOME || os.homedir();
     return agentConfig.configDir.replace(os.homedir(), home);
 }
+/**
+ * Read the user's configured Codex model from their active `~/.codex/config.toml`.
+ *
+ * Codex runs under a per-version `CODEX_HOME` (see `buildExecEnv`). A dispatch
+ * pinned to a version whose home config lacks a top-level `model` key silently
+ * falls back to Codex's built-in default (currently `gpt-5.3-codex`), which a
+ * ChatGPT-tier account is not entitled to use — the run dies with HTTP 400
+ * before doing any work. The user's model preference lives in whichever
+ * version-home was active when they set it (`~/.codex` symlinks to it), so it is
+ * NOT visible to a run pinned to a different version. Forwarding it via `--model`
+ * keeps the user's "default model setup" regardless of the active version-home,
+ * and is concurrency-safe (no file writes) when fanning out many parallel runs.
+ *
+ * Returns the top-level `model` only (ignores `[profile.*]` tables). Best-effort:
+ * a missing/unreadable/unset config yields `undefined` (caller keeps prior behaviour).
+ */
+export function readCodexConfiguredModel() {
+    try {
+        const cfg = path.join(getAgentConfigPath('codex'), 'config.toml');
+        const text = fs.readFileSync(cfg, 'utf-8');
+        // Only trust keys before the first [table]; a `model` under [profile.x] is
+        // not the default the CLI uses at top level.
+        const topLevel = text.split(/^\s*\[/m)[0];
+        return topLevel.match(/^\s*model\s*=\s*["']([^"']+)["']/m)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Get the path to the version's config directory.
  * e.g., ~/.agents/versions/claude/2.0.65/home/.claude/

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

@@ -92,6 +92,21 @@ export interface SignInAdvisory {
  * probe). Never flips the authoritative installed/ready column.
  */
 export declare function resolveSignInAdvisory(installed: boolean, running: boolean, probeSignedIn: boolean): SignInAdvisory;
+/** One row of `agents teams doctor --json` output. */
+export interface TeamsDoctorEntry {
+    installed: boolean;
+    path: string | null;
+    error: string | null;
+    signedIn: boolean | null;
+    running: boolean;
+}
+/**
+ * Collect the same data `agents teams doctor` prints: per-agent install status,
+ * launch health, and advisory sign-in state. Kept in one place so `agents doctor
+ * --devices` can run it locally or compare it against remote JSON without
+ * duplicating the probe logic.
+ */
+export declare function collectTeamsDoctorData(): Promise<Record<string, TeamsDoctorEntry>>;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export declare function getAgentsDir(): Promise<string>;
 /**
@@ -131,6 +146,17 @@ export declare class AgentProcess {
     cloudBranch: string | null;
     worktreeName: string | null;
     worktreePath: string | null;
+    hostName: string | null;
+    hostTarget: string | null;
+    repoPath: string | null;
+    remotePid: number | null;
+    remoteLog: string | null;
+    remoteExit: string | null;
+    remoteLogOffset: number;
+    remotePollSnapshot: {
+        alive: boolean;
+        exit: string | null;
+    } | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
@@ -175,7 +201,35 @@ export declare class AgentProcess {
      * Falls back to null when none are available.
      */
     private getLatestEventTime;
+    /**
+     * For a distributed (remote-host) teammate, pull NEW bytes of the host's log
+     * into the LOCAL mirror the parser consumes, advance the remote offset, and
+     * resolve terminal status from the remote `.exit` sentinel. Runs BEFORE the
+     * local read in readNewEvents(), so the existing stream-json parse path then
+     * runs unchanged over the freshly-mirrored bytes.
+     *
+     * Uses a per-wave batched snapshot (remotePollSnapshot) when the supervisor's
+     * one-ssh-per-host pre-pass populated it; otherwise falls back to its own
+     * round-trips so a bare `teams status`/`teams logs` is still correct.
+     */
+    private syncRemoteMirror;
     readNewEvents(): Promise<void>;
+    /**
+     * Truncate the local mirror to its trailing REMOTE_MIRROR_MAX_BYTES and reset
+     * lastReadPos to the new (smaller) size so the parser doesn't re-read the kept
+     * tail. Only trims when over the cap — a normal-length log is untouched.
+     */
+    private capMirrorToTail;
+    /** Cap on the in-memory event backlog kept per remote teammate. */
+    private static readonly REMOTE_EVENTS_MAX;
+    /**
+     * Drop the oldest cached events for a remote teammate once past the cap. The
+     * status path only needs recent events (last N messages, recentToolCalls,
+     * terminal status) and the getDelta cursor filters by timestamp, so a bounded
+     * recent window preserves the digest while bounding the heap. Terminal status
+     * is already latched onto `this.status`, so trimming can't lose it.
+     */
+    private capEventsCache;
     saveMeta(): Promise<void>;
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
@@ -246,12 +300,51 @@ export declare class AgentManager {
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
-    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<AgentProcess>;
+    spawn(taskName: string, agentType: AgentType, prompt: string, cwd?: string | null, mode?: Mode | null, effort?: EffortLevel, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<AgentProcess>;
     /**
      * Actually spawn the OS process for a teammate. Extracted from spawn() so
      * staged teammates can be launched later by startReady().
      */
     private launchProcess;
+    /**
+     * Dispatch a distributed teammate onto its host over SSH — the remote-host
+     * analog of launchProcess(). Symmetric to the cloud path: no local process; the
+     * lifecycle lives on the host and is polled (isProcessAlive/readNewEvents over
+     * SSH via the remote `.exit` sentinel + offset-tailed log).
+     *
+     * When the team uses worktrees (agent.worktreeName set), a git worktree is first
+     * created ON THE HOST off the freshly-fetched default branch; the teammate runs
+     * there. Otherwise it runs in the host repo path directly.
+     */
+    private launchRemoteProcess;
+    /**
+     * Resolve a scheduler-picked device to host placement fields on an unpinned
+     * teammate at LAUNCH time (the same resolution `teams add --device` runs, minus
+     * the fatal `die()` — a scheduling failure here is per-teammate, not per-add).
+     * Sets hostName/hostTarget/repoPath + persists, so the subsequent
+     * launchRemoteProcess dispatches over SSH. Mirrors the `add`-time pin path:
+     * resolve device → reject Windows (POSIX-only) → ssh target → ensure the repo
+     * is present on the host from the team's --repo (ensureRemoteRepo).
+     */
+    private resolveScheduledPlacement;
+    /**
+     * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
+     * (least-loaded), if the team declares one. A no-op for a pinned teammate
+     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
+     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
+     * teammate schedules identically no matter how it was fired.
+     */
+    private maybeSchedulePlacement;
+    /**
+     * 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
+     * isProcessAlive()/readNewEvents() consume a cached snapshot instead of each
+     * issuing its own SSH handshake — avoiding N round-trips per wave at 10+ remote
+     * teammates. Groups by hostTarget and, for each host, checks every teammate's
+     * `.exit` + `kill -0` in a single ssh call over the shared ControlMaster socket.
+     */
+    prefetchRemoteStatus(taskName: string): Promise<void>;
     /**
      * Fire any pending teammates in the given team whose `after` deps have all
      * completed. Returns the list of teammates just launched. Repeatable:
@@ -266,6 +359,20 @@ export declare class AgentManager {
      * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
      * and reads stream-json events off stdout.
      */
+    /**
+     * Build the `agents run …` argv AFTER the `agents` binary — the flags + prompt
+     * scaffolding shared by the LOCAL launch (buildCommand, which prefixes
+     * process.execPath + the agents CLI path) and the REMOTE launch
+     * (launchRemoteProcess, which prefixes `agents` on the host via dispatch). Kept
+     * in one place so the PROMPT_SUFFIX / CLAUDE_PLAN_MODE_PREFIX scaffolding and the
+     * flag set can never drift between the two backends.
+     *
+     * `cwd` is intentionally NOT emitted here: the local path passes it as
+     * `--cwd`/`--add-dir` (below), while the remote path `cd`s into the host cwd
+     * before invoking `agents`. `sessionId` is likewise local-only (the remote run
+     * mints its own session on the host).
+     */
+    private buildRunArgv;
     private buildCommand;
     get(agentId: string): Promise<AgentProcess | null>;
     /**