@phnx-labs/agents-cli 1.22.42 → 1.22.43

package/dist/lib/exec.js

@@ -37,6 +37,8 @@ import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
+import { getAccountInfo } from './agents.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, parseClaudeSessionLimitReset } from './accounting/usage.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -2083,12 +2085,20 @@ export async function runWithFallback(options) {
             }
             throw err;
         }
-        if (result.exitCode === 0)
+        const output = `${result.stderr}\n${result.stdout}`;
+        const sessionLimitReset = agent === 'claude' ? parseClaudeSessionLimitReset(output) : null;
+        if (sessionLimitReset && version) {
+            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+            const usageKey = getUsageLookupKey(account);
+            if (usageKey)
+                noteClaudeSessionLimit(usageKey, sessionLimitReset);
+        }
+        if (result.exitCode === 0 && !sessionLimitReset)
             return 0;
         const isLast = i === chain.length - 1;
         if (isLast)
-            return result.exitCode;
-        if (!detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
+            return result.exitCode || 1;
+        if (!sessionLimitReset && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

package/dist/lib/format.d.ts

@@ -27,6 +27,15 @@ export declare function formatDie(msg: string, opts?: DieOptions): {
  * keep the original red-stderr behavior.
  */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export declare function runOrDie(fn: () => void | Promise<void>, opts?: DieOptions): Promise<void>;
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures

package/dist/lib/format.js

@@ -44,6 +44,22 @@ export function die(msg, code = 1, opts = {}) {
         console.error(text);
     process.exit(code);
 }
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export async function runOrDie(fn, opts = {}) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        die(err instanceof Error ? err.message : String(err), 1, opts);
+    }
+}
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures

package/dist/lib/github/pr-mergeable.d.ts

@@ -0,0 +1,49 @@
+/**
+ * List this user's mergeable PRs across registered project repos.
+ *
+ * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
+ * with no `--repo`. `gh` then infers the repository from the working directory,
+ * and the daemon's cwd is not a git repo, so every poll returned empty.
+ *
+ * This helper:
+ *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
+ *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *      nothing; the live name is `phnx-labs/agi-cli`).
+ *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
+ *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
+ *      OR an APPROVE comment on THIS PR).
+ *
+ * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
+ * observation under `condition.mode: every` — do not write to stderr on the
+ * no-match path, or command.ts will treat stderr as the observation and fire.
+ */
+import { type ProjectDef } from '../projects.js';
+import { type MergeablePrInput, type StatusCheck } from './pr-verdict.js';
+export type GhExec = (args: string[]) => Promise<string>;
+/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
+export declare function ghExec(args: string[]): Promise<string>;
+/** Unique GitHub slugs declared on project definitions. */
+export declare function projectRepoSlugs(defs: readonly ProjectDef[]): string[];
+/**
+ * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
+ * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
+ * name; `gh repo view` returns the live one. On error, keep the input slug.
+ */
+export declare function canonicalizeRepo(slug: string, gh: GhExec): Promise<string>;
+interface ListedPr {
+    number: number;
+    reviewDecision?: string | null;
+    statusCheckRollup?: StatusCheck[] | null;
+}
+/**
+ * Given PRs already listed for one repo, attach verdict payloads only for the
+ * CI-green ones that lack a formal APPROVED reviewDecision, then select.
+ */
+export declare function selectListedMergeable(repo: string, listed: readonly ListedPr[], gh: GhExec): Promise<MergeablePrInput[]>;
+/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
+export declare function listMergeableRefs(opts?: {
+    gh?: GhExec;
+    defs?: ProjectDef[];
+    repos?: string[];
+}): Promise<string>;
+export {};

package/dist/lib/github/pr-mergeable.js

@@ -0,0 +1,157 @@
+/**
+ * List this user's mergeable PRs across registered project repos.
+ *
+ * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
+ * with no `--repo`. `gh` then infers the repository from the working directory,
+ * and the daemon's cwd is not a git repo, so every poll returned empty.
+ *
+ * This helper:
+ *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
+ *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *      nothing; the live name is `phnx-labs/agi-cli`).
+ *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
+ *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
+ *      OR an APPROVE comment on THIS PR).
+ *
+ * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
+ * observation under `condition.mode: every` — do not write to stderr on the
+ * no-match path, or command.ts will treat stderr as the observation and fire.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { listProjectDefs } from '../projects.js';
+import { formatMergeableRef, hasApproveVerdict, isCiGreen, } from './pr-verdict.js';
+const execFileAsync = promisify(execFile);
+/**
+ * `gh --json` is not color-safe when this fleet exports FORCE_COLOR /
+ * CLICOLOR_FORCE: gh paints the payload and JSON.parse / jq die on the ANSI
+ * prefix (live miss on the sibling poll script). Strip the force vars and
+ * pin GH_NO_COLOR for every gh spawn.
+ */
+function ghEnv() {
+    const env = { ...process.env };
+    env.CLICOLOR = '0';
+    env.NO_COLOR = '1';
+    env.GH_NO_COLOR = '1';
+    env.GH_PAGER = 'cat';
+    delete env.CLICOLOR_FORCE;
+    delete env.FORCE_COLOR;
+    delete env.GH_FORCE_TTY;
+    return env;
+}
+/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
+export async function ghExec(args) {
+    const { stdout } = await execFileAsync('gh', args, {
+        timeout: 30_000,
+        maxBuffer: 8 * 1024 * 1024,
+        encoding: 'utf-8',
+        env: ghEnv(),
+    });
+    return String(stdout ?? '');
+}
+/** Unique GitHub slugs declared on project definitions. */
+export function projectRepoSlugs(defs) {
+    const slugs = new Set();
+    for (const d of defs) {
+        if (d.repo)
+            slugs.add(d.repo);
+        for (const r of d.repos ?? []) {
+            if (r.slug)
+                slugs.add(r.slug);
+        }
+    }
+    return [...slugs].sort();
+}
+/**
+ * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
+ * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
+ * name; `gh repo view` returns the live one. On error, keep the input slug.
+ */
+export async function canonicalizeRepo(slug, gh) {
+    try {
+        const out = (await gh([
+            'repo', 'view', slug, '--json', 'nameWithOwner', '--jq', '.nameWithOwner',
+        ])).trim();
+        return out || slug;
+    }
+    catch {
+        return slug;
+    }
+}
+async function fetchVerdict(repo, number, gh) {
+    const [reviewsRaw, commentsRaw] = await Promise.all([
+        gh(['api', `repos/${repo}/pulls/${number}/reviews`, '--cache', '60s']),
+        gh(['api', `repos/${repo}/issues/${number}/comments`, '--cache', '60s']),
+    ]);
+    const reviews = JSON.parse(reviewsRaw);
+    const comments = JSON.parse(commentsRaw);
+    return {
+        reviews: Array.isArray(reviews) ? reviews : [],
+        comments: Array.isArray(comments) ? comments : [],
+    };
+}
+/**
+ * Given PRs already listed for one repo, attach verdict payloads only for the
+ * CI-green ones that lack a formal APPROVED reviewDecision, then select.
+ */
+export async function selectListedMergeable(repo, listed, gh) {
+    const candidates = [];
+    for (const row of listed) {
+        if (!isCiGreen(row.statusCheckRollup))
+            continue;
+        const base = {
+            number: row.number,
+            repo,
+            reviewDecision: row.reviewDecision ?? '',
+            statusCheckRollup: row.statusCheckRollup,
+            reviews: [],
+            comments: [],
+        };
+        if (base.reviewDecision === 'APPROVED') {
+            candidates.push(base);
+            continue;
+        }
+        try {
+            const extra = await fetchVerdict(repo, row.number, gh);
+            candidates.push({ ...base, ...extra });
+        }
+        catch {
+            // A single PR's reviews/comments probe failed — skip it, keep the rest.
+            continue;
+        }
+    }
+    return candidates.filter((pr) => pr.reviewDecision === 'APPROVED' || hasApproveVerdict(pr.reviews, pr.comments));
+}
+/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
+export async function listMergeableRefs(opts) {
+    const gh = opts?.gh ?? ghExec;
+    const slugs = opts?.repos ?? projectRepoSlugs(opts?.defs ?? listProjectDefs());
+    const seen = new Set();
+    const refs = [];
+    for (const raw of slugs) {
+        const repo = await canonicalizeRepo(raw, gh);
+        if (seen.has(repo))
+            continue;
+        seen.add(repo);
+        let listed = [];
+        try {
+            const rawList = await gh([
+                'pr', 'list',
+                '--repo', repo,
+                '--author', '@me',
+                '--state', 'open',
+                '--limit', '50',
+                '--json', 'number,reviewDecision,statusCheckRollup',
+            ]);
+            const parsed = JSON.parse(rawList);
+            listed = Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            continue;
+        }
+        const mergeable = await selectListedMergeable(repo, listed, gh);
+        for (const pr of mergeable)
+            refs.push(formatMergeableRef(pr));
+    }
+    return refs.join(' ');
+}

package/dist/lib/github/pr-verdict.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Non-author PR approval + CI-green checks for merge-on-green.
+ *
+ * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
+ * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
+ * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
+ * verdict comment on THIS PR, and rejects a comment that only cites another
+ * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
+ *
+ * Do not invent a third rule. If the hook's regexes change, change these in
+ * the same delivery.
+ */
+/** A GitHub pull-request review, shaped after `GET .../pulls/{n}/reviews`. */
+export interface PrReview {
+    state?: string;
+}
+/** An issue comment on a PR, shaped after `GET .../issues/{n}/comments`. */
+export interface PrComment {
+    body?: string;
+}
+/**
+ * One status-check rollup item from `gh pr list --json statusCheckRollup`.
+ * `gh` exposes conclusion/state/status under those names; empty fields are
+ * pending/in-progress.
+ */
+export interface StatusCheck {
+    conclusion?: string;
+    state?: string;
+    status?: string;
+}
+/** One open PR with the fields the mergeable selector reads. */
+export interface MergeablePrInput {
+    number: number;
+    /** `owner/repo`. Required so a daemon with no git cwd can still merge. */
+    repo: string;
+    reviewDecision?: string | null;
+    statusCheckRollup?: StatusCheck[] | null;
+    reviews?: PrReview[] | null;
+    comments?: PrComment[] | null;
+}
+/**
+ * True when a non-author verdict exists ON this PR.
+ *
+ * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
+ * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
+ * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
+ */
+export declare function hasApproveVerdict(reviews: readonly PrReview[] | null | undefined, comments: readonly PrComment[] | null | undefined): boolean;
+/**
+ * True when every check is a terminal success-class conclusion.
+ *
+ * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
+ * (ascii-uppercased conclusion, else state, else status). An empty rollup
+ * is green — jq `all([])` is true, and a PR with no checks is mergeable
+ * from this filter's point of view.
+ */
+export declare function isCiGreen(rollup: readonly StatusCheck[] | null | undefined): boolean;
+/**
+ * Keep PRs that are CI-green AND non-author-approved.
+ *
+ * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
+ * field is empty — the fleet convention: reviewers post an APPROVE *comment*
+ * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
+ */
+export declare function selectMergeablePrs(prs: readonly MergeablePrInput[]): MergeablePrInput[];
+/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
+export declare function formatMergeableRef(pr: Pick<MergeablePrInput, 'repo' | 'number'>): string;

package/dist/lib/github/pr-verdict.js

@@ -0,0 +1,72 @@
+/**
+ * Non-author PR approval + CI-green checks for merge-on-green.
+ *
+ * Verdict rules are copied from merge-guard.sh (the PreToolUse hook in
+ * phnx-labs/.agents-system `rules/subrules/gh-merge-guard/merge-guard.sh`).
+ * That hook accepts EITHER a formal GitHub `APPROVED` review OR an APPROVE
+ * verdict comment on THIS PR, and rejects a comment that only cites another
+ * PR ("carried from #N" / "APPROVE on #N") — the #2736 laundering pattern.
+ *
+ * Do not invent a third rule. If the hook's regexes change, change these in
+ * the same delivery.
+ */
+/**
+ * True when a non-author verdict exists ON this PR.
+ *
+ * Mirrors merge-guard.sh: a GitHub review with `state == "APPROVED"`, or an
+ * issue comment whose body contains `\bAPPROVE\b` and is not a carried-from
+ * citation (`\bcarried\s+(?:over\s+)?from\b` or `\bAPPROVE\s+(?:on|from)\s+#\d+`).
+ */
+export function hasApproveVerdict(reviews, comments) {
+    if (Array.isArray(reviews) && reviews.some((r) => r?.state === 'APPROVED')) {
+        return true;
+    }
+    if (!Array.isArray(comments))
+        return false;
+    for (const c of comments) {
+        const body = c?.body ?? '';
+        if (!/\bAPPROVE\b/.test(body))
+            continue;
+        // A verdict that only points at another PR is laundering, not review.
+        if (/\bcarried\s+(?:over\s+)?from\b|\bAPPROVE\s+(?:on|from)\s+#\d+/.test(body)) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * True when every check is a terminal success-class conclusion.
+ *
+ * Matches the built-in monitor's original jq: SUCCESS / NEUTRAL / SKIPPED
+ * (ascii-uppercased conclusion, else state, else status). An empty rollup
+ * is green — jq `all([])` is true, and a PR with no checks is mergeable
+ * from this filter's point of view.
+ */
+export function isCiGreen(rollup) {
+    const items = rollup ?? [];
+    return items.every((c) => {
+        const v = (c.conclusion || c.state || c.status || '').toUpperCase();
+        return v === 'SUCCESS' || v === 'NEUTRAL' || v === 'SKIPPED';
+    });
+}
+/**
+ * Keep PRs that are CI-green AND non-author-approved.
+ *
+ * `reviewDecision == "APPROVED"` is sufficient (a formal review). When that
+ * field is empty — the fleet convention: reviewers post an APPROVE *comment*
+ * rather than a GitHub review — fall through to {@link hasApproveVerdict}.
+ */
+export function selectMergeablePrs(prs) {
+    return prs.filter((pr) => {
+        if (!isCiGreen(pr.statusCheckRollup))
+            return false;
+        if (pr.reviewDecision === 'APPROVED')
+            return true;
+        return hasApproveVerdict(pr.reviews, pr.comments);
+    });
+}
+/** `owner/repo#n` — the poll observation the merge action can parse without a cwd. */
+export function formatMergeableRef(pr) {
+    return `${pr.repo}#${pr.number}`;
+}

package/dist/lib/harness/adapter.d.ts

@@ -73,9 +73,10 @@ export interface ExecLaunchArgsCtx {
 }
 /**
  * Context for the routine (daemon-job) launch-arg quirks (mapping B, runner.ts
- * side). This idiom mutates a pre-baked token array from ROUTINE_AGENT_COMMANDS,
- * distinct from buildExecCommand's declarative modeFlags — so it is a separate
- * method on the same adapter, one source of truth per harness across both.
+ * side). This idiom mutates a token array baked from AGENT_COMMANDS
+ * (bakeRoutineArgv), distinct from buildExecCommand's declarative modeFlags —
+ * so it is a separate method on the same adapter, one source of truth per
+ * harness across both.
  */
 export interface RoutineLaunchCtx {
     /** normalizeMode(config.mode) — the canonicalized mode. */
@@ -131,8 +132,8 @@ export interface HarnessAdapter {
     execModeArgs?(ctx: ExecLaunchArgsCtx): string[] | undefined;
     /**
      * This harness's routine (daemon-job) launch-arg quirks for buildJobCommand
-     * (runner.ts). Mutates the ROUTINE_AGENT_COMMANDS token array in place, exactly
-     * as the old per-agent arm did; runner appends model/reasoning flags after.
+     * (runner.ts). Mutates the bakeRoutineArgv token array in place, exactly as
+     * the old per-agent arm did; runner appends model/reasoning flags after.
      * Omitted for a harness with no routine launch quirks.
      */
     routineModeArgs?(cmd: string[], ctx: RoutineLaunchCtx): void;

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

@@ -48,6 +48,16 @@ export declare const REMOTE_PASSTHROUGH: Record<string, RemoteSpec>;
  * these to {@link REMOTE_PASSTHROUGH}.
  */
 export declare const OWN_HOST_COMMANDS: Set<string>;
+/**
+ * Argv forwarded over SSH for a `--device` passthrough.
+ *
+ * `sync`'s umbrella spec appends `--yes` when there is no TTY so a remote
+ * reconcile does not hang on a picker. `sync status` is inspect-only unless the
+ * caller typed `--yes` themselves: `--yes` on that command is reconcile, not
+ * "don't prompt". Nesting it under `sync` must not inherit the umbrella flag
+ * (RUSH-2864).
+ */
+export declare function buildPassthroughForwardedArgs(command: string, allArgs: string[], interactive: boolean): string[];
 /** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
 export interface FleetPassthroughOptions {
     /** Override the device registry loader (tests). */

package/dist/lib/hosts/passthrough.js

@@ -52,11 +52,10 @@ export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
  * `add`/`use`/`list`, and none) and were removed.
  */
 export const REMOTE_PASSTHROUGH = {
-    // status / inspect
+    // inspect
     view: {},
     inspect: {},
     doctor: {},
-    status: {},
     check: {},
     list: {},
     usage: {},
@@ -81,7 +80,6 @@ export const REMOTE_PASSTHROUGH = {
     workflows: {},
     models: {},
     defaults: {},
-    alias: {},
     // Installations are per-machine, so updating one on a peer means running it
     // there — the same local/remote shape `add` would need.
     update: {},
@@ -137,6 +135,32 @@ const STRIP_SPECS = [
     { long: 'hosts', takesValue: true },
     { long: 'devices', takesValue: true },
 ];
+/** First non-flag token after `group` in argv (the subcommand, robust to leading flags). */
+function firstSubcommand(allArgs, group) {
+    const idx = allArgs.indexOf(group);
+    return idx >= 0 ? allArgs.slice(idx + 1).find((a) => !a.startsWith('-')) : undefined;
+}
+/**
+ * Argv forwarded over SSH for a `--device` passthrough.
+ *
+ * `sync`'s umbrella spec appends `--yes` when there is no TTY so a remote
+ * reconcile does not hang on a picker. `sync status` is inspect-only unless the
+ * caller typed `--yes` themselves: `--yes` on that command is reconcile, not
+ * "don't prompt". Nesting it under `sync` must not inherit the umbrella flag
+ * (RUSH-2864).
+ */
+export function buildPassthroughForwardedArgs(command, allArgs, interactive) {
+    const spec = REMOTE_PASSTHROUGH[command];
+    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
+    // Detect the subcommand on the *stripped* argv. On the raw argv,
+    // `sync --device peer status` would treat `peer` as the first non-flag
+    // token and inherit umbrella `--yes` (RUSH-2864 review).
+    const skipInheritedYes = command === 'sync' && firstSubcommand(forwarded, 'sync') === 'status';
+    if (!interactive && spec?.nonInteractive && !skipInheritedYes) {
+        forwarded = [...forwarded, ...spec.nonInteractive];
+    }
+    return forwarded;
+}
 /** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
 function syntheticHost(target) {
     const at = target.indexOf('@');
@@ -531,9 +555,7 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // out — otherwise force the command's non-interactive path so no half-drawn
     // picker is piped into a file or another program.
     const interactive = !!process.stdout.isTTY && !allArgs.includes('--no-tty');
-    let forwarded = stripRoutingFlags(allArgs, STRIP_SPECS);
-    if (!interactive && spec.nonInteractive)
-        forwarded = [...forwarded, ...spec.nonInteractive];
+    const forwarded = buildPassthroughForwardedArgs(command, allArgs, interactive);
     // The one long-running case: keep the remote team supervisor alive past a
     // disconnect by dispatching it detached (nohup), still streaming live.
     const isWatchedTeamStart = command === 'teams' && forwarded[1] === 'start' && forwarded.includes('--watch');

package/dist/lib/hosts/session-index.js

@@ -21,7 +21,7 @@ import { upsertSession } from '../session/db.js';
 import { isSessionTrackedAgent } from '../session/types.js';
 import { localLogPath, updateTask } from './tasks.js';
 import { parseSessionIdMarker } from './session-marker.js';
-import { deriveShortId } from '../session/short-id.js';
+import { deriveShortId } from '../text/short-id.js';
 import { normalizeHost } from '../machine-id.js';
 /**
  * Build the SessionMeta for a host-dispatched run. Returns null when the run has

package/dist/lib/installations/shims.js

@@ -2015,7 +2015,7 @@ export function pruneOrphanedCommandShim(fileName) {
         return false;
     }
     if (content.includes('# Alias shim:'))
-        return false; // a user `agents alias` — leave it
+        return false; // a user `agents setup alias` shim — leave it
     const bin = readAgentsBinFromShim(shimPath);
     if (!bin)
         return false; // not an AGENTS_BIN-baked shim

package/dist/lib/installations/versions.d.ts

@@ -230,6 +230,46 @@ export declare function printTrashFooter(moved: Array<{
  * containing only `home/`) remain under the agent dir.
  */
 export declare function removeAllVersions(agent: AgentId): number;
+export interface HealedVersionPointers {
+    /** Global default reassigned off a not-installed version (`to: null` = cleared). */
+    globalDefault?: {
+        from: string;
+        to: string | null;
+    };
+    /** Isolated default (bare `agents run <agent>`) reassigned off a not-installed version. */
+    isolatedDefault?: {
+        from: string;
+        to: string | null;
+    };
+    /** `~/.<agent>` config symlink repointed off a not-installed version. */
+    configSymlink?: {
+        from: string;
+        to: string;
+    };
+}
+/**
+ * Repoint an agent's version pointers — the global/isolated default and the
+ * `~/.<agent>` config symlink — off any version that is no longer installed, so
+ * neither `agents sync`/`agents run` resolution nor the conventional-path home
+ * can land on a dead version (RUSH-2471).
+ *
+ * How a pointer goes dangling: {@link removeVersion} reassigns the defaults and
+ * clears the config symlink only when IT removes the pointed-at version. A
+ * version-home whose launch binary disappears by any other route — grok
+ * self-updated its per-version binary out from under the old dir, a manual
+ * delete, a half-finished install that seeded the home but never landed the
+ * binary — leaves the default and/or the symlink pointing at something
+ * {@link isVersionInstalled} reports as gone.
+ *
+ * Called from the sync resolve path so the invariant self-heals. Mirrors
+ * {@link removeVersion}'s reassignment: the global default prefers the newest
+ * NON-isolated survivor else clears; the isolated default prefers the newest
+ * remaining isolated copy else clears. The symlink is repointed at the now-healed
+ * resolved default, else the newest installed non-isolated version. A symlink
+ * already on an installed version, a real (non-symlink) config dir, and an
+ * isolated-only agent are left untouched.
+ */
+export declare function healDanglingVersionPointers(agent: AgentId, cwd: string): Promise<HealedVersionPointers>;
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *