@phnx-labs/agents-cli 1.22.33 → 1.22.35

package/dist/lib/shims.js

@@ -236,6 +236,43 @@ function codexShimLaunchArgs() {
         ...codexPolicyArgs('edit'),
     ].map(shellQuote).join(' ');
 }
+/**
+ * The `exec` tail for a generated shim. For most agents this is a plain
+ * `exec "$BINARY"<launchArgs> "$@"`.
+ *
+ * Codex is special: its `workspace-write` sandbox hardcodes any `.agents/` (and
+ * `.codex/`) directory read-only, but agents-cli keeps every worktree at
+ * `<repo>/.agents/worktrees/<slug>`, so an in-repo build under a static
+ * shim would hit `EROFS`. The `agents run codex` path fixes this by adding
+ * `<repo>/.agents` to the profile's `workspace_roots` (see codexEditWritableRoots
+ * / repoAgentsDirForCwd), but a static shim has no cwd at generation time. So the
+ * shim resolves the repo's `.agents` from `$PWD` at RUN time — worktree-aware,
+ * mirroring repoAgentsDirForCwd — and passes it via Codex's own `--add-dir`
+ * (verified to compose with the `agents-edit` profile). The resolution is inline
+ * bash because the shim is the launch hot path and must not spawn Node to compute
+ * one directory. `--add-dir` is added only when the resolved `.agents` exists.
+ */
+function shimExecTail(agent, launchArgs) {
+    if (agent !== 'codex')
+        return `exec "$BINARY"${launchArgs} "$@"`;
+    return `_repo_agents=""
+case "$PWD" in
+  */.agents/worktrees/*) _repo_agents="\${PWD%%/.agents/worktrees/*}/.agents" ;;
+  *)
+    _d="$PWD"
+    # Stop before $HOME so a dotfiles repo at $HOME is not treated as the project
+    # root (mirrors repoRootForCwd's home exclusion in project-key.ts).
+    while [ -n "$_d" ] && [ "$_d" != "/" ] && [ "$_d" != "$HOME" ]; do
+      if [ -e "$_d/.git" ]; then _repo_agents="$_d/.agents"; break; fi
+      _d=$(dirname "$_d")
+    done
+    ;;
+esac
+if [ -n "$_repo_agents" ] && [ -d "$_repo_agents" ]; then
+  exec "$BINARY"${launchArgs} --add-dir "$_repo_agents" "$@"
+fi
+exec "$BINARY"${launchArgs} "$@"`;
+}
 function getAgentsBinForGeneratedShim() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
 }
@@ -707,7 +744,7 @@ if [ "\$LAUNCH_SKIP" = "0" ]; then
   "\$AGENTS_BIN" sync --agent "\$AGENT" --agent-version "\$VERSION" --launch --cwd "\$PWD" --quiet 2>/dev/null || true
 fi
 
-exec "$BINARY"${launchArgs} "$@"
+${shimExecTail(agent, launchArgs)}
 `;
 }
 /**
@@ -933,7 +970,7 @@ function assertSafeVersion(version) {
  * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
  * The colocated test `shims.isolation-capability.test.ts` enforces this.
  */
-export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode', 'muse'];
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'cursor', 'grok', 'kimi', 'opencode', 'muse'];
 /**
  * Whether an agent supports a clean `--isolated` install — i.e. its config
  * location can be redirected by an env var so the isolated copy stays fully
@@ -999,7 +1036,14 @@ export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/
 export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
 export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
 `
-                                : '';
+                                : agent === 'cursor'
+                                    ? `
+# Cursor: no config-dir env var. Its OAuth token (the login gate) lives at
+# $XDG_CONFIG_HOME/cursor/auth.json, so pin XDG_CONFIG_HOME at the version home
+# to isolate each account's login for direct aliases (parity with buildExecEnv).
+export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+`
+                                    : '';
     const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
@@ -1087,7 +1131,7 @@ if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
 fi
 ${managedEnv}
 
-exec "$BINARY"${launchArgs} "$@"
+${shimExecTail(agent, launchArgs)}
 `;
 }
 /**

package/dist/lib/startup/command-registry.d.ts

@@ -98,6 +98,7 @@ export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;
 export declare const loadSetup: ModuleLoader;
 export declare const loadUninstall: ModuleLoader;
+export declare const loadUpgrade: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
 export declare const loadCloud: ModuleLoader;

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

@@ -19,6 +19,9 @@
  * `cleanup` subcommand to it), in that order — see commands/prune.ts.
  */
 import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { configureRootCommand } from './root-command.js';
 // One loader per command module. Each dynamically imports the module and hands
 // back its register function. Kept as named consts so src/index.ts can compose
 // them into the exact main-branch registration order for the slow path.
@@ -98,6 +101,7 @@ export const loadPush = async () => (await import('../../commands/push.js')).reg
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
 export const loadSetup = async () => (await import('../../commands/setup.js')).registerSetupCommand;
 export const loadUninstall = async () => (await import('../../commands/uninstall.js')).registerUninstallCommands;
+export const loadUpgrade = async () => (await import('../../commands/upgrade.js')).registerUpgradeCommand;
 export const loadSessions = async () => (await import('../../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../../commands/teams.js')).registerTeamsCommands;
 export const loadCloud = async () => (await import('../../commands/cloud.js')).registerCloudCommands;
@@ -247,6 +251,7 @@ export const COMMAND_LOADERS = {
     repo: [loadRepo],
     setup: [loadSetup],
     uninstall: [loadUninstall],
+    upgrade: [loadUpgrade],
     sessions: [loadSessions],
     // Observe-umbrella alias of sessions --active (same lazy module).
     roster: [loadSessions],
@@ -263,6 +268,9 @@ export const COMMAND_LOADERS = {
     mailbox: [loadMailboxes],
     serve: [loadServe],
     share: [loadShare],
+    // `unshare` is a top-level convenience alias of `share delete` (see
+    // commands/share.ts) — same module, registered as its own program.command().
+    unshare: [loadShare],
     audit: [loadAudit],
     webhook: [loadWebhook],
     funnel: [loadFunnel],
@@ -272,7 +280,7 @@ export const COMMAND_LOADERS = {
 /**
  * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
  * registered inline in src/index.ts — closures over entry-point state (the
- * deprecated aliases and tombstones) plus the internal/upgrade commands. They are
+ * deprecated aliases and tombstones) plus the internal command. They are
  * real commands, so anything that asks "does this command exist?" must count them.
  */
 const INLINE_COMMAND_NAMES = [
@@ -284,7 +292,6 @@ const INLINE_COMMAND_NAMES = [
     'resources', // tombstone -> view --merged
     'hq', // tombstone
     '_internal',
-    'upgrade',
 ];
 /**
  * Every top-level command name the CLI answers to — the loader table plus the
@@ -318,7 +325,8 @@ export function isKnownTopLevelCommand(name) {
  * are closures over entry-point state that src/index.ts registers directly.
  */
 export async function buildFullCommandTree() {
-    const program = new Command();
+    const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8'));
+    const program = configureRootCommand(new Command(), 'agents', packageJson.version);
     const done = new Set();
     for (const loaders of Object.values(COMMAND_LOADERS)) {
         for (const loader of loaders) {

package/dist/lib/startup/root-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+/** Configure the public root surface shared by the live CLI and reference generator. */
+export declare function configureRootCommand(program: Command, name: string, version: string): Command;

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

@@ -0,0 +1,10 @@
+/** Configure the public root surface shared by the live CLI and reference generator. */
+export function configureRootCommand(program, name, version) {
+    return program
+        .name(name)
+        .description('Environment manager for AI agents')
+        .version(version)
+        .option('--verbose', 'Show startup self-heal details on stderr')
+        .helpOption('-h, --help', 'Show help')
+        .addHelpCommand(false);
+}

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

@@ -15,6 +15,45 @@ export declare enum AgentStatus {
     FAILED = "failed",
     STOPPED = "stopped"
 }
+/**
+ * The statuses a teammate can never leave — its process has run and finished
+ * (or been stopped). Everything else (pending, running) is still live work.
+ *
+ * This is the ONLY set that retention (cleanupOldAgents) may reap: a `pending`
+ * teammate has not launched yet and a `running` one is doing work, so deleting
+ * either is data loss. Treating "not running" as "completed" was the RUSH-2356
+ * bug — it swept live `pending` `--after` teammates past the 50-record cap.
+ */
+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;
+/**
+ * One remote teammate's liveness, resolved by a single host probe. Three states,
+ * kept distinct on purpose (RUSH-2366):
+ *   - alive=true                                → process still running.
+ *   - exitFilePresent=true                      → the `.exit` sentinel exists;
+ *     `exit` is its (possibly empty, mid-write) contents.
+ *   - alive=false && !exitFilePresent  ("GONE") → the process is gone AND the
+ *     wrapper never recorded a sentinel — it was killed / the box died. There is
+ *     no exit code coming, so this MUST resolve terminal instead of "running
+ *     forever". Collapsing GONE into the empty-`.exit` case is exactly the bug
+ *     that left a dead `--device` teammate RUNNING indefinitely.
+ */
+export interface RemoteLivenessSnapshot {
+    alive: boolean;
+    exit: string | null;
+    exitFilePresent: boolean;
+}
+/**
+ * The per-teammate shell that emits `<id> <ALIVE|EXITED|GONE> <codeOrEmpty>`.
+ * Shared by the batched prefetch (many teammates, one round-trip) and the
+ * direct single-teammate probe, so both classify liveness identically.
+ * `exitFile` is interpolated UNQUOTED so `$HOME` in the dispatch path expands on
+ * the remote shell (shellQuote would defeat the `[ -f ]` test).
+ */
+export declare function remoteLivenessSnippet(id: string, exitFile: string, pid: number): string;
+/** Parse one `<STATE> <codeOrEmpty>` reading into a snapshot. */
+export declare function parseRemoteLivenessState(state: string, code: string | undefined): RemoteLivenessSnapshot;
 /** Task type label for Software Factory workflows. Drives planner fan-out. Optional — teammates without a task_type work exactly as before. */
 export type TaskType = 'plan' | 'implement' | 'test' | 'review' | 'bugfix' | 'docs';
 export declare const VALID_TASK_TYPES: readonly TaskType[];
@@ -162,10 +201,7 @@ export declare class AgentProcess {
     remoteLog: string | null;
     remoteExit: string | null;
     remoteLogOffset: number;
-    remotePollSnapshot: {
-        alive: boolean;
-        exit: string | null;
-    } | null;
+    remotePollSnapshot: RemoteLivenessSnapshot | null;
     private eventsCache;
     private lastReadPos;
     private baseDir;
@@ -231,6 +267,13 @@ export declare class AgentProcess {
      * --active --local` take ~4.3s on a box with 30 completed teammates.
      */
     private syncRemoteMirror;
+    /**
+     * One-shot direct liveness probe for a single remote teammate — the fallback
+     * used outside a batched supervisor wave (a bare `teams status`, `mgr.get()`
+     * for `teams resume`). Returns null on a transient ssh failure so the caller
+     * leaves the teammate RUNNING rather than reaping it on a dropped connection.
+     */
+    private probeRemoteLiveness;
     /** Reset the local stdout cursor for a newly truncated resume log. */
     resetLogReadPosition(): number;
     /** Restore the cursor when a resume transaction puts the prior log back. */
@@ -263,6 +306,24 @@ export declare class AgentProcess {
     saveMeta(): Promise<void>;
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
+    /**
+     * Read just the persisted status + completion time from meta.json, without
+     * reconstructing the whole teammate. Returns null when there is no readable
+     * record on disk. Used to detect that ANOTHER process (a `teams stop`, a
+     * sibling supervisor) has already moved this teammate to a terminal status.
+     */
+    private readDiskStatus;
+    /**
+     * If this in-memory teammate is still non-terminal but disk already shows a
+     * terminal status, adopt the disk state. Returns true when it did.
+     *
+     * This is the guard against the stale-manager race (RUSH-2366): a long-lived
+     * supervisor holding a teammate as `running` must never re-persist that stale
+     * `running` over a `stopped`/`failed`/`completed` another process just wrote
+     * (e.g. an explicit `teams stop` in a separate CLI invocation). A terminal
+     * status is a one-way latch, so disk-terminal always wins over memory-running.
+     */
+    private adoptDiskTerminalIfNewer;
     /**
      * @param opts.skipRemote A `--local` caller (RUSH-2118): a distributed
      *   teammate is never dialed — its in-memory state (already loaded from
@@ -333,6 +394,13 @@ export declare class AgentManager {
      */
     private localOnly;
     private constructorAgentsDir;
+    /**
+     * One-shot memo of the last `validateAddPreconditions` result, so the
+     * command-layer pre-worktree call and spawn()'s own call don't each pay a
+     * full `listAll()` status refresh (a round of SSH probes on a `--device`
+     * team). Consumed by the first matching call — see that method.
+     */
+    private validatedAdd;
     constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, localOnly?: boolean);
     private initialize;
     private doInitialize;
@@ -350,11 +418,66 @@ export declare class AgentManager {
      * manager is alive — the supervisor loop calls this each wave so
      * dynamically-added teammates get picked up.
      *
-     * Does not modify or re-load agents already in the cache; that path is
-     * covered by updateStatusFromProcess() which re-reads stdout.log.
+     * For a teammate ALREADY cached, refreshes it only when disk has latched it
+     * terminal while the cache still holds it non-terminal — the case where
+     * another process (e.g. `agents teams stop` in a separate CLI invocation)
+     * moved it to `stopped`/`failed` and this long-lived manager would otherwise
+     * never see it and re-persist a stale `running` (RUSH-2366). A still-live
+     * cached teammate is left untouched; updateStatusFromProcess() owns that path.
      */
     rescanFromDisk(): Promise<number>;
     private loadExistingAgents;
+    /**
+     * Validate an add's name uniqueness and `--after` dependency graph, without
+     * any side effects. Throws a user-facing error on: a duplicate name, `--after`
+     * without `--name`, an unknown dependency, or a cycle. Returns the cleaned
+     * (whitespace-filtered) `after` list.
+     *
+     * Extracted from spawn() so the command layer can run it BEFORE creating a
+     * worktree — a rejected add must not leave an orphan `agents/<name>` branch
+     * that then breaks the retry with `fatal: a branch ... already exists`
+     * (RUSH-2356). spawn() calls it too, so validation lives in exactly one place.
+     *
+     * The result is cached for exactly ONE subsequent call with the same
+     * arguments, which spawn() then consumes. `listByTask()` → `listAll()`
+     * refreshes every sibling's status, and on a `--device` team that is a full
+     * round of SSH liveness probes — running it twice per `teams add` would
+     * double that cost for no gain, since the second pass reads the same snapshot
+     * and cannot catch anything the first missed. The cache is single-use so any
+     * later spawn (a `teams start --watch` supervisor launching staged teammates)
+     * still validates against fresh state and still rejects a duplicate name.
+     */
+    validateAddPreconditions(taskName: string, name: string | null, after: string[]): Promise<string[]>;
+    /**
+     * Does any LIVE teammate — in any team — already own `worktreeName`?
+     *
+     * A RAW disk scan: no status probing, no cache, no `listAll()`. The caller is
+     * the `teams add` failure path, where the manager's own status refresh can be
+     * the very thing that threw (`cleanupOldAgents()` → `listAll()` →
+     * `updateStatusFromProcess()` runs AFTER the staged record is saved), so a
+     * check that re-entered that machinery would throw again and answer nothing.
+     *
+     * `teams add` asks this before removing a worktree, to tell an ORPHAN from
+     * someone's live checkout (RUSH-2356). Two deliberate scoping choices:
+     *
+     * - **Any team, not just the one being added to.** Worktree names are global
+     *   to the repo but records are per-team, so a same-named worktree owned by
+     *   another team's teammate must also block the removal.
+     * - **Non-terminal records only.** A completed/failed/stopped teammate's
+     *   worktree was already cleaned up at `teams stop`, and its record lingers
+     *   until retention reaps it — counting those would leave a genuine orphan
+     *   branch stranded forever, which is the bug this all exists to fix.
+     * - **Fails CLOSED.** This guards a `git worktree remove --force`, so the two
+     *   errors are not symmetric: a false "claimed" strands an orphan branch that
+     *   a human can delete, while a false "unclaimed" deletes a live agent's
+     *   checkout and its uncommitted work. Only `ENOENT` proves absence — no
+     *   agents dir means no records, and a record with no `meta.json` is not a
+     *   record. Any other failure (EACCES, EIO, half-written or invalid JSON,
+     *   a race with a writer) means we could not READ the records, which is not
+     *   the same as there being none, so it answers `true`. This is deliberate
+     *   asymmetry, not defensive coding: the caller acts destructively on `false`.
+     */
+    isWorktreeClaimed(worktreeName: string): Promise<boolean>;
     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>;
     /**
      * Resume a STOPPED teammate (completed / failed / stopped) by re-entering its
@@ -481,6 +604,13 @@ export declare class AgentManager {
     }>;
     listAll(): Promise<AgentProcess[]>;
     listRunning(): Promise<AgentProcess[]>;
+    /**
+     * Teammates that have reached a terminal status (completed/failed/stopped) —
+     * the ONLY records retention may reap. A `pending` teammate has not launched
+     * and a `running` one is working, so neither is "completed"; classifying them
+     * as such let cleanupOldAgents sweep live `pending` `--after` teammates past
+     * the cap (RUSH-2356). Filter on `isTerminalStatus`, never `!== RUNNING`.
+     */
     listCompleted(): Promise<AgentProcess[]>;
     listByTask(taskName: string): Promise<AgentProcess[]>;
     listByParentSession(parentSessionId: string): Promise<AgentProcess[]>;