@phnx-labs/agents-cli 1.22.60 → 1.22.61

package/dist/commands/harness.js

@@ -17,7 +17,9 @@ import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists,
 import { listPresets, getPreset } from '../lib/profiles-presets.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 import { findAccount } from '../lib/account-registry.js';
-import { runWizardSteps, createSteps, editSteps, defaultWizardIO, } from './harness-wizard.js';
+import { runWizardSteps, createSteps, editSteps, defaultWizardIO, runConnectionTest, } from './harness-wizard.js';
+import { harnessHooks } from './harness-hooks.js';
+import { CONNECTION_TEST_PROMPT } from '../lib/harness-connection-test.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
@@ -196,6 +198,73 @@ export function addNeedsWizard(name, opts) {
         return true;
     return !getPreset(name);
 }
+/**
+ * Resolve the tri-state connection-test gate (RUSH-2221), pure so the branching
+ * is unit-tested with no prompt or spawn. `--test` forces it on, `--no-test`
+ * forces it off, and with neither flag a TTY is asked (default yes) while a
+ * non-interactive caller (`--key-stdin`, piped, CI) skips it — so scripting stays
+ * non-interactive unless it opts in with `--test`.
+ */
+export function connectionTestGate(testFlag, interactive) {
+    if (testFlag === true)
+        return 'on';
+    if (testFlag === false)
+        return 'off';
+    return interactive ? 'ask' : 'off';
+}
+/**
+ * Pre-save connection test (RUSH-2221). The harness is already on disk (the test
+ * drives the real `agents run <name>` path, so it must be), so this runs a
+ * classified smoke test and — on a TTY, when it fails — offers to keep it, edit
+ * it, or delete-and-cancel. A test is never blocking on its own: a save is only
+ * discarded when the user explicitly chooses to, so a `--test` failure in a
+ * non-interactive shell warns and keeps rather than exiting non-zero.
+ */
+async function preSaveConnectionTest(name, testFlag) {
+    const interactive = isInteractiveTerminal();
+    const gate = connectionTestGate(testFlag, interactive);
+    let shouldTest;
+    if (gate === 'on')
+        shouldTest = true;
+    else if (gate === 'off')
+        shouldTest = false;
+    else {
+        const { confirm } = await import('@inquirer/prompts');
+        shouldTest = await confirm({ message: `Test the connection for '${name}' now?`, default: true });
+    }
+    if (!shouldTest)
+        return;
+    console.log(chalk.gray(`Testing '${name}' — sending "${CONNECTION_TEST_PROMPT}" through agents run…`));
+    const result = await runConnectionTest({ mode: 'create', name }, harnessHooks());
+    if (!result)
+        return;
+    if (result.ok) {
+        console.log(chalk.green(`✓ ${result.message}`));
+        return;
+    }
+    console.log(chalk.yellow(`✗ ${result.message}`));
+    if (!interactive) {
+        console.log(chalk.gray(`Kept anyway. Fix and retest with: agents harness edit ${name}`));
+        return;
+    }
+    const { select } = await import('@inquirer/prompts');
+    const action = await select({
+        message: 'The connection test failed. What would you like to do?',
+        choices: [
+            { name: 'Keep it (the endpoint may just be down right now)', value: 'keep' },
+            { name: 'Edit it now', value: 'edit' },
+            { name: 'Delete it and cancel', value: 'delete' },
+        ],
+    });
+    if (action === 'edit') {
+        await runEditWizard(name, {});
+        return;
+    }
+    if (action === 'delete') {
+        deleteProfile(name);
+        throw new Error(`Harness '${name}' deleted after a failed connection test.`);
+    }
+}
 /**
  * Shared build+persist flow for a fork — used by `agents harness fork`'s
  * flag-driven path AND by the wizard (both for `fork` and, when it falls back
@@ -223,6 +292,7 @@ async function runForkFlow(source, name, opts) {
     writeProfile(forked);
     console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
     console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+    await preSaveConnectionTest(name, opts.test);
 }
 /**
  * Interactive `agents harness add`/`fork` wizard — runs when required info is
@@ -234,7 +304,7 @@ async function runForkFlow(source, name, opts) {
  */
 async function runCreateWizard() {
     const io = await defaultWizardIO();
-    const draft = await runWizardSteps(createSteps(), { mode: 'create' }, io);
+    const draft = await runWizardSteps(createSteps(), { mode: 'create' }, io, harnessHooks());
     return {
         source: draft.source,
         name: draft.name,
@@ -292,7 +362,7 @@ async function runEditWizard(name, cliOpts) {
     }
     const original = readProfile(name);
     const io = await defaultWizardIO();
-    const draft = await runWizardSteps(editSteps(original), { mode: 'edit', original, host: original.host.agent, name }, io);
+    const draft = await runWizardSteps(editSteps(original), { mode: 'edit', original, host: original.host.agent, name }, io, harnessHooks());
     const opts = { ...draftToEditOptions(draft, original), keyStdin: cliOpts.keyStdin };
     if (!hasEditFlags(opts)) {
         console.log(chalk.gray(`No changes made to '${name}'.`));
@@ -308,6 +378,9 @@ async function runEditWizard(name, cliOpts) {
     writeProfile(edited);
     console.log(chalk.green(`Harness '${name}' updated.`));
     console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
+    // An edit that touched host/model/endpoint/auth is exactly what can break the
+    // harness, so re-test after saving (RUSH-2221). cliOpts carries the --test flag.
+    await preSaveConnectionTest(name, cliOpts.test);
 }
 export function registerHarnessCommands(program) {
     const cmd = program
@@ -362,6 +435,8 @@ Examples:
         .option('--from-secrets <bundle>[:<key>]', 'Removed: import the value with agents accounts add, then use --account')
         .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
+        .option('--test', 'Run a connection test before saving (default: ask on a terminal)')
+        .option('--no-test', 'Skip the pre-save connection test')
         .action(async (name, opts) => {
         try {
             if (opts.authProvider || opts.fromSecrets)
@@ -371,10 +446,11 @@ Examples:
                     throw new Error("'agents harness add' needs --preset or --host + --model (or a name and an interactive terminal for the wizard).");
                 }
                 const wiz = await runCreateWizard();
-                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
+                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin, test: opts.test });
                 return;
             }
             await addProfile(name, opts, 'Harness');
+            await preSaveConnectionTest(name, opts.test);
         }
         catch (err) {
             console.error(chalk.red(err.message));
@@ -393,6 +469,8 @@ Examples:
         .option('--from-secrets <bundle>[:<key>]', 'Removed: import the value with agents accounts add, then use --account')
         .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing harness with the same name')
+        .option('--test', 'Run a connection test before saving (default: ask on a terminal)')
+        .option('--no-test', 'Skip the pre-save connection test')
         .addHelpText('after', `
 Examples:
   # Fork OpenCode into a harness pinned to a DeepSeek model on OpenRouter
@@ -417,7 +495,7 @@ Examples:
                     throw new Error("'agents harness fork' needs <source> and <name> (or an interactive terminal for the wizard).");
                 }
                 const wiz = await runCreateWizard();
-                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
+                await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin, test: opts.test });
                 return;
             }
             await runForkFlow(source, name, opts);
@@ -439,6 +517,8 @@ Examples:
         .option('--fallback-model <id>', 'Secondary model retried on the same host on a rate limit (pass an empty string to clear it)')
         .option('--from-secrets <bundle>[:<key>]', 'Removed: import the value with agents accounts add, then use --account')
         .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
+        .option('--test', 'Run a connection test after saving (default: ask on a terminal)')
+        .option('--no-test', 'Skip the connection test')
         .addHelpText('after', `
 Examples:
   # Swap the pinned model
@@ -479,6 +559,7 @@ Examples:
             writeProfile(edited);
             console.log(chalk.green(`Harness '${name}' updated.`));
             console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
+            await preSaveConnectionTest(name, opts.test);
         }
         catch (err) {
             console.error(chalk.red(err.message));

package/dist/commands/reminders.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents reminders` — list your personal operating reminders.
+ *
+ * The reminders live in `~/.agents/reminders/reminders.yaml` and are surfaced
+ * succinctly in the Claude statusline — one per session, chosen from the session
+ * id. This command shows the full set (and the file to edit).
+ */
+import type { Command } from 'commander';
+export declare function registerRemindersCommand(program: Command): void;

package/dist/commands/reminders.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { loadReminders, remindersFilePath } from '../lib/reminders.js';
+import { setHelpSections } from '../lib/help.js';
+const EXAMPLES = [
+    'agents reminders          # list your operating reminders',
+    'agents reminders --json   # machine-readable output',
+].join('\n');
+const NOTES = [
+    "Reminders live in ~/.agents/reminders/reminders.yaml and sync across the fleet via 'agents repo push'.",
+    'One shows succinctly in the Claude statusline per session, chosen deterministically from the session id,',
+    'so concurrent agents each show a different one and it stays stable within a session.',
+].join('\n');
+export function registerRemindersCommand(program) {
+    const cmd = program
+        .command('reminders')
+        .description('Personal operating reminders shown in the Claude statusline')
+        .option('--json', 'output as JSON')
+        .action((opts) => {
+        const file = remindersFilePath();
+        let reminders;
+        try {
+            reminders = loadReminders();
+        }
+        catch (err) {
+            console.error(chalk.red(`Could not read reminders: ${err instanceof Error ? err.message : String(err)}`));
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({ file, reminders }, null, 2)}\n`);
+            return;
+        }
+        if (reminders.length === 0) {
+            console.log(`No reminders yet. Add them to ${chalk.cyan(file)}`);
+            console.log(chalk.dim('Each shows succinctly in the Claude statusline — one per session.'));
+            return;
+        }
+        const count = `${reminders.length} reminder${reminders.length === 1 ? '' : 's'}`;
+        console.log(chalk.dim(`${count} · ${file}`));
+        console.log(chalk.dim('One shows in the Claude statusline per session, chosen from the session id.\n'));
+        for (const reminder of reminders) {
+            console.log(`  ${chalk.cyan('◆')} ${chalk.bold(reminder.short)}`);
+            if (reminder.full && reminder.full !== reminder.short) {
+                console.log(`    ${chalk.dim(reminder.full)}`);
+            }
+        }
+    });
+    setHelpSections(cmd, { examples: EXAMPLES, notes: NOTES });
+}

package/dist/commands/run-account-picker.d.ts

@@ -52,6 +52,20 @@ export declare function signInLaunchDecision(input: {
     tty: boolean;
     json: boolean;
 }): 'launch' | 'fail-loud';
+/**
+ * How a `balanced`/`available` run reacts when every account's usage is stale and
+ * none is verified (PHNX-2526). A human present at a real terminal gets the
+ * account `picker` — they can choose knowing the numbers are stale — while every
+ * unattended shape (`--headless`, `--json`, or no TTY) `fail-loud`s with
+ * NO_VERIFIED_USAGE rather than silently guess on a stale snapshot. `headless`
+ * joins the gate because a routine/machine dispatch can carry a TTY yet have no
+ * human to answer a picker; the split mirrors `signInLaunchDecision`.
+ */
+export declare function noVerifiedUsageDecision(input: {
+    tty: boolean;
+    json: boolean;
+    headless: boolean;
+}): 'picker' | 'fail-loud';
 /**
  * Choose which installed version to launch so the user can authenticate, when a
  * strategy found zero healthy accounts but at least one is merely signed out

package/dist/commands/run-account-picker.js

@@ -221,6 +221,19 @@ export function signInLaunchDecision(input) {
     const humanPresent = input.tty && !input.json;
     return input.recoverable > 0 && humanPresent ? 'launch' : 'fail-loud';
 }
+/**
+ * How a `balanced`/`available` run reacts when every account's usage is stale and
+ * none is verified (PHNX-2526). A human present at a real terminal gets the
+ * account `picker` — they can choose knowing the numbers are stale — while every
+ * unattended shape (`--headless`, `--json`, or no TTY) `fail-loud`s with
+ * NO_VERIFIED_USAGE rather than silently guess on a stale snapshot. `headless`
+ * joins the gate because a routine/machine dispatch can carry a TTY yet have no
+ * human to answer a picker; the split mirrors `signInLaunchDecision`.
+ */
+export function noVerifiedUsageDecision(input) {
+    const humanPresent = input.tty && !input.json && !input.headless;
+    return humanPresent ? 'picker' : 'fail-loud';
+}
 /**
  * Choose which installed version to launch so the user can authenticate, when a
  * strategy found zero healthy accounts but at least one is merely signed out

package/dist/commands/teams.d.ts

@@ -108,7 +108,7 @@ export declare function staleRepoError(params: {
  * the teammate itself so we don't need the original --cloud CLI args.
  */
 export declare function wireCloudDispatcher(mgr: AgentManager): void;
-export declare function cloudDispatchOptions(agent: Pick<AgentProcess, 'prompt' | 'agentType' | 'cloudRepo' | 'cloudBranch' | 'model'>): DispatchOptions;
+export declare function cloudDispatchOptions(agent: Pick<AgentProcess, 'prompt' | 'agentType' | 'cloudRepo' | 'cloudBranch' | 'model' | 'mode'>): DispatchOptions;
 /**
  * Single-wave start used by `teams start` without --watch. startReady()
  * terminalizes a placement/spawn/cloud/dependency failure to FAILED with

package/dist/commands/teams.js

@@ -3,7 +3,7 @@ import { dieFriction, relTime, truncate, isJsonMode, padRight } from '../lib/for
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, withTeammatePrPolicy, } from '../lib/teams/agents.js';
 import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/feed/events.js';
@@ -373,7 +373,10 @@ export function wireCloudDispatcher(mgr) {
 }
 export function cloudDispatchOptions(agent) {
     return {
-        prompt: agent.prompt,
+        // PHNX-3236: a cloud teammate runs in the provider sandbox and never inherits
+        // the local merge-guard.sh hook, so the prompt policy is its ONLY self-merge
+        // boundary — apply the same helper buildRunArgv uses for local/remote.
+        prompt: withTeammatePrPolicy(agent.prompt, agent.mode),
         agent: agent.agentType,
         repo: agent.cloudRepo ?? undefined,
         branch: agent.cloudBranch ?? undefined,
@@ -1933,7 +1936,10 @@ export function registerTeamsCommands(program) {
             mgr.setCloudDispatcher(async (a) => {
                 const prov = resolveProvider(providerId);
                 const dispatchOpts = {
-                    prompt: a.prompt,
+                    // PHNX-3236: same self-merge boundary as the local/remote path — a
+                    // cloud teammate has no inherited merge-guard.sh, so the prompt is
+                    // its only layer.
+                    prompt: withTeammatePrPolicy(a.prompt, a.mode),
                     agent: a.agentType,
                     repo: opts.repo,
                     branch: opts.branch,

package/dist/index.js

@@ -72,6 +72,15 @@ if (process.argv[2] === '__shim') {
     const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
     process.exit(code);
 }
+// gh overload delegate: the `gh` PATH shim routes `gh pr checks` here as
+// `agents __gh --real-gh <path> -- pr checks …`, so the rate-limit-prone read
+// runs over REST instead of GraphQL (PHNX-3501). Above bootstrap for the same
+// reason as __shim: no update check, no command-tree load — this is on the hot
+// path of an agent's CI watch, and the gh argv must pass through untouched.
+if (process.argv[2] === '__gh') {
+    const { runGhOverload } = await import('./lib/github/gh-overload.js');
+    process.exit(await runGhOverload(process.argv.slice(3)));
+}
 if (process.argv[2] === '__claude-statusline') {
     const { runClaudeStatusLine } = await import('./lib/claude-statusline.js');
     process.exit(await runClaudeStatusLine());

package/dist/lib/accounting/rotate.d.ts

@@ -8,6 +8,7 @@ import type { AgentId, RunStrategy } from '../types.js';
 import type { FallbackEntry } from '../exec.js';
 import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { type AccountInfo, type CredentialPresence } from '../agents.js';
+import { type EventPayload } from '../feed/events.js';
 import { type UsageSnapshot } from './usage.js';
 import { type AuthVerdict } from '../auth-health.js';
 export interface RotateCandidate {
@@ -75,6 +76,21 @@ export interface RotateResult {
      * was silently reported as verified.)
      */
     usageUnverified?: boolean;
+    /**
+     * True when NO candidate carries a fresh usage snapshot AND at least one
+     * carries a STALE-but-present one — the "entirely stale usage" case
+     * (PHNX-2526). The INITIAL route MUST NOT be decided on a stale number that
+     * looks plausible but is wrong (the yosemite-s1 incident: 26h–2.7d-old
+     * snapshots read 48% while the account was at its weekly cap). `picked` is
+     * still populated (a stale candidate) so `healthy` stays intact for BOUNDED
+     * post-rejection failover, but a caller doing the initial selection MUST NOT
+     * launch it — it diverts to the account picker (interactive) or fails loud
+     * with NO_VERIFIED_USAGE (unattended). Distinct from a BLIND pool with no
+     * snapshot at all (a worker box whose usage endpoint 403s, RUSH-2392): that
+     * carries no misleading number, so it still draws a pick and this stays
+     * false.
+     */
+    noVerifiedUsage?: boolean;
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
 /**
@@ -139,6 +155,20 @@ export declare const USAGE_DECISION_MAX_AGE_MS: number;
  * narrowing rule below exists to prevent.
  */
 export declare function isUsageVerified(candidate: RotateCandidate, nowMs?: number): boolean;
+/**
+ * Whether this candidate carries a STALE-but-present usage number: a snapshot
+ * with windows whose capture time is older than {@link USAGE_DECISION_MAX_AGE_MS}.
+ *
+ * This is the misleading case the initial route must refuse — the number reads
+ * "48% used" with the same confidence whether captured a minute or three days
+ * ago, and a box whose refresh is failing stays wrong indefinitely. It is
+ * deliberately NARROWER than "not verified": a BLIND candidate with no snapshot
+ * (or a plan-only meterless one with no windows) carries no number to be misled
+ * by — a worker box whose usage endpoint 403s (RUSH-2392), or a meterless Grok
+ * login — so it is not "stale", and an entirely-blind pool still draws a pick
+ * (PHNX-3392) rather than fail loud with NO_VERIFIED_USAGE.
+ */
+export declare function hasStaleUsage(candidate: RotateCandidate, nowMs?: number): boolean;
 /**
  * Whether a specific account can serve a run right now, and — when it can't —
  * why. `signed_out` covers a missing usable credential; `revoked` is a token the
@@ -291,6 +321,16 @@ export declare function earliestResetAcross(candidates: RotateCandidate[], nowMs
  * and `resets <time>` (parsed for the rotate cooldown). Do not deviate.
  */
 export declare function formatNoHealthyAccountError(agent: AgentId, strategy: RunStrategy, excluded: RotateCandidate[], nowMs?: number): string;
+/**
+ * The all-stale-usage error (PHNX-2526) an UNATTENDED `balanced`/`available`
+ * run fails loud with when no account's usage is fresh enough to route on. EXACT
+ * contract — it MUST contain the literal `NO_VERIFIED_USAGE` so a machine caller
+ * (and the Factory watchdog) can tail-detect it distinctly from the
+ * `no healthy` throttle error, which is a different condition (throttled vs
+ * merely stale). Names each candidate with how stale its snapshot is, so the
+ * operator can see the failing-refresh box rather than guess.
+ */
+export declare function formatNoVerifiedUsageError(agent: AgentId, strategy: RunStrategy, candidates: RotateCandidate[], nowMs?: number): string;
 /**
  * The zero-healthy-harness error for `agents run auto` — names each harness's
  * exclusion reason plus the earliest reset across all snapshots.
@@ -336,6 +376,16 @@ export declare function resolveAccountVersion(agent: AgentId, account: string):
 export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
+/**
+ * Build the enriched `rotation.resolved`/`rotation.unresolved` event payload:
+ * the full candidate pool as the router saw it, the pick and WHY, and a
+ * freshness tally. Replaces the old `{ version, healthy: <n>, excluded: <n> }`
+ * shape, which recorded only counts and a device-local version and so could not
+ * tell a blind-pool draw from a skewed-verified pick from a refused-stale route
+ * — the exact ambiguity that keeps a bad pick undebuggable from the log. All
+ * candidates share ONE `nowMs` so their `tier`/`ageMs` are mutually consistent.
+ */
+export declare function buildRotationDecisionEvent(rotation: RotateResult, agent: AgentId, strategy: RunStrategy): EventPayload;
 /**
  * Resolve the version `agents run` should use when the caller did not pin
  * one with `@version`. The caller supplies the effective strategy.
@@ -362,6 +412,19 @@ export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy,
      * path — there is no account to be "unhealthy").
      */
     exhausted?: RotateCandidate[];
+    /**
+     * Set (with `version: null`) for a `balanced`/`available` route when EVERY
+     * eligible account's usage is stale and none is verified (PHNX-2526). The
+     * initial selection MUST NOT auto-launch on a stale number: an interactive
+     * caller diverts to the account picker, an unattended one fails loud with
+     * NO_VERIFIED_USAGE (`formatNoVerifiedUsageError`). `rotation` is still
+     * returned — its `healthy` set (the stale candidates) is preserved ONLY for
+     * bounded post-rejection failover, never the initial pick. Undefined when a
+     * verified account exists, when the pool is entirely blind (no snapshots —
+     * the worker-box case still draws a pick), for `pinned`, and for the
+     * zero-healthy `exhausted` case.
+     */
+    noVerifiedUsage?: boolean;
 }>;
 /**
  * Cap on the number of healthy accounts a single run will re-dispatch through