@phnx-labs/agents-cli 1.20.44 → 1.20.46

package/CHANGELOG.md

@@ -2,8 +2,18 @@
 
 ## Unreleased
 
-## 1.20.44
+## 1.20.46
+
+- **NEW: `Cmd-Shift-O` opens a Spotlight-style quick-issue bar in the menu-bar helper — type a sentence, attach recent screenshots, and an agent files the Linear ticket for you.** The menu-bar helper already turned a screenshot into a `<host>:<path>` token with `Cmd-Shift-V` (clip capture), but there was no path from "I see a bug" to "a triaged ticket exists." The new chord summons a borderless panel (a thin capture surface, not another form): you type a one-line note, optionally toggle one or more recent screenshots (from the system screencapture folder, CleanShot's export path, or the clip history) as a thumbnail strip (the newest is pre-selected when it's fresh), and hit Return. It then **dispatches a headless agent** (`agents run claude --mode auto`, isolated behind one `AgentsCLI.dispatchTicketAgent` call so a cloud pod is a later swap) that reads the screenshots, runs `agents sessions` to identify which repo/project this concerns, does a brief investigation for real context, and files the ticket via `~/.agents/skills/linear/scripts/linear create` with an honest priority + a `repo:<name>` label — no preview step, the panel closes immediately and a notification reports the created `RUSH-####`. Focus is handled for a no-Dock `.accessory` app (`NSApp.activate` → `makeKeyAndOrderFront` → `makeFirstResponder`, with a borderless `NSPanel` overriding `canBecomeKey`; click-outside dismissal is armed only after the summon settles so the activation race can't self-dismiss the panel). The `Cmd-Shift-V` clip hotkey is unchanged — the Carbon hotkey manager now demultiplexes both chords by `EventHotKeyID.id` through one installed handler. Self-test: `MENUBAR_ISSUE_TEST=1 MenubarHelper` exercises screenshot selection, ticket-id parsing, and the meta-prompt contract; `MENUBAR_PROMPT_PREVIEW=1` renders the panel without the global hotkey for QA. Source: `apps/cli/menubar/Sources/MenubarHelper/{PromptPanel,Hotkey,AgentsCLI,main,IssueSelfTest,Clip}.swift`.
 
+- **NEW: a unified self-heal subsystem — the shim/PATH "repair" notice no longer nags on every terminal, and the daemon now heals shim drift in the background.** agents-cli had accumulated ~37 separate repair routines scattered across the daemon, every CLI startup, and a handful of commands, each hand-rolling its own detect+fix on its own trigger. The most visible symptom: the interactive shim bootstrap (`maybeBootstrapShimIntegration`) regenerated shims, adopted shadowing launchers, and offered to add the shims dir to PATH **in the foreground on every invocation**, suppressed only by a `process.ppid`-keyed temp sentinel — so a new terminal re-ran the whole detect-and-nag, and the underlying condition was never permanently fixed. This lands a single `HealCheck` registry (`lib/self-heal/`) with one runner (`runSelfHeal`) driven by two front doors — the daemon (on its existing ~30s-after-start + ~6h `safe`-mode cycle) and the interactive startup — sharing the same checks: `shims` (regenerate stale shims/aliases), `shadowing` (adopt symlink launchers; report real-binary shadows), `path` (add the shims dir to PATH once), and `resources` (the existing `heal()` engine, wrapped unchanged). The daemon's heal cycle now runs all four in `safe` mode (low-risk fixes silently; risky ones reported), replacing the resource-only `heal()` call — and drops the desktop toast for background heals (the log is the record). The interactive startup now heals **silently** and prints at most a **persistent, once-per-condition** notice (`lib/shim-heal.ts`, keyed to a signature of the actionable state under `~/.agents/.cache/state/shim-notice.json`) for what a machine genuinely can't fix for you — a real native binary shadowing the shim — instead of re-nagging every shell. What changes is *where* the repairs run (background/silent) and *how often* you hear about them (once, not every terminal). Source: `apps/cli/src/lib/self-heal/` (new), `apps/cli/src/lib/shim-heal.ts` (new), `apps/cli/src/lib/daemon.ts`, `apps/cli/src/index.ts`, `apps/cli/src/lib/shims.ts` (`isShimCurrent` exported).
+## 1.20.45
+- **NEW: `agents run <agent> --host <name>` without a prompt forwards your TTY over SSH and runs the agent interactively on the remote host.** Previously `--host` runs required a prompt and were always headless (`agents run <agent> "<task>" --host <name>`). Now, omitting the prompt takes the interactive path: when local stdin is a TTY, the local CLI SSHes with `-tt`, runs `agents run <agent>` on the host, and lets the remote machine's `agents` start its normal tmux wrapper. The tmux session lives on the remote box, so detaching (`Ctrl-b d`) ends the SSH connection but keeps the agent running; you can reattach from the host or resume by session id. Session ids for Claude are still minted up front so `agents sessions` can surface and resolve the remote run. `--no-follow` is rejected for interactive host runs (it is meaningless for an attached TTY), and `--mode`, `--model`, `--name`, passthrough args after `--`, and `--raw`/`--no-tmux` are forwarded to the remote invocation. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/docs/hosts.md`.
+- **`agents secrets export --host` now works against Windows targets, and a new `agents secrets unlock --host` unlocks a bundle on a remote machine.** The export push was POSIX-only (`bash -lc`, `--from /dev/stdin`, `create … || true`, `IFS= read`), so a Windows remote died with `'true' is not recognized … cannot find the path specified`. Two changes fix it: `agents secrets import` now accepts **`--from -`** (read the `.env` from stdin, replacing the POSIX-only `/dev/stdin`), and the push is **platform-aware** — `bash -lc` on POSIX, `powershell -EncodedCommand` on Windows, with the target's OS taken from the device registry. Because the npm `agents.ps1` shim does **not** forward ssh-piped stdin to the underlying node process (a raw `--from -` read hangs), the Windows keychain push bridges the piped `.env` through PowerShell into a temp file and imports `--from <file>` (deleted afterwards). File-backend export to a Windows target is refused cleanly rather than emitting broken PowerShell. Verified end-to-end: `agents secrets export linear.app --host win-mini` imported all 13 keys. Separately, **`agents secrets unlock --host <machine> <bundle>`** runs the unlock ON the remote over `ssh -tt`, so a **file-backed** bundle's passphrase prompt surfaces on your terminal — the "unlock the Mac from the road with its password" path; keychain/biometry bundles are GUI-only (a local Touch-ID/passcode sheet can't cross SSH) and can't be remote-unlocked. `unlock`'s `--host` is single-valued so it never swallows the positional bundle name. Source: `apps/cli/src/commands/secrets.ts`, `apps/cli/src/lib/hosts/remote-cmd.ts`.
+- **A session now has ONE name, not two. `--name` seeds the session label instead of a parallel column.** Shipping `agents run --name` (1.20.43) as a separate immutable `name` column created two look-alike fields — an unshown, frozen `name` and the shown, searchable `label` — that both resolved `agents sessions <ref>` and forced tie-break bookkeeping nobody could keep straight. They unify into one field. `--name` is now the universal way to *seed* the `label` at launch — the same field an agent-generated title (Claude's `/rename`) later refines and `agents sessions` displays and searches — and it works consistently across interactive, headless, `--host`, and teams teammate runs (a teammate's friendly name now seeds its session label; before, teammate sessions had no name at all). Priority is a plain fallback chain resolved at scan time, no stored winner: an agent-generated title wins, else the `--name` seed, else the listing falls back to `topic`. So a Claude run's `--name` shows until Claude titles it (your seed, then refined); a non-Claude run keeps its `--name` as the label (it has no auto-title). The seeded name is now fuzzy-searchable in FTS (the old `name` column was not). `agents hosts logs <name>` is unchanged — it resolves against the host-task sidecar, not the session column. Schema v10 folds any existing `name` into `label` (where the label was empty), mirrors it into the FTS row, then drops the `name` column; the run-name sidecars re-seed every scan (`seedLabelsFromNames`), so no rescan is needed. Reworks the 1.20.43 `--name` design (partly reverts its separate-column approach). Source: `apps/cli/src/lib/session/{db,discover,run-names,types}.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/docs/{05-sessions,hosts}.md`.
+- **NEW: `agents teams add`/`start` warns when a *version-pinned* teammate is on a throttled or signed-out account.** The 1.20.43 `balanced`-default fix keeps *bare* teammates off rate-limited accounts (they route through bare `agents run`, which rotates), but a **version-pinned** (`claude@2.1.112`) or **profile** teammate spawns `agents run <agent>@<version>` / `agents run <profile>`, and a pin/profile deliberately *bypasses* rotation — so it would launch straight onto a maxed account and 429 on the first request, with no mid-run failover either (that only arms when a non-pinned strategy actually rotated). `agents teams add` (at add time) and `agents teams start` (per staged teammate, deduped by `agent@version`) now pre-check a **version-pinned** teammate's account and print an advisory when it's rate-limited, out of credits, or not signed in — reusing the router's *exact* eligibility gate (`checkRunAccountReadiness` → `hasUsageAvailable`, the same session-inclusive signal the `agents view` badge uses), so the warning can never disagree with what the spawn would actually do. It **warns, never blocks** (mirroring the existing "may not be signed in" advisory); `--force` silences it. Scoped to version-pinned teammates on purpose: bare teammates are already handled by rotation, and a profile injects its own auth (a different account than the version home carries) that isn't locally checkable — so no unreliable profile warning is emitted. Source: `apps/cli/src/lib/rotate.ts` (`readinessFromCandidate`, `checkRunAccountReadiness`, `rotate.test.ts`), `apps/cli/src/commands/teams.ts`.
+
+## 1.20.44
 - **Every `logs` command is concise by default; the token-heavy raw dump is now opt-in behind `--full`.** Agents that spin up agents on other machines or add teammates were pulling whole transcripts just to glance at status — `agents logs <session>` printed the full markdown transcript, and `agents hosts logs` / `agents teams logs` / `agents routines logs` each `cat`'d their entire captured stdout, because each subsystem had hand-rolled its own "cat the log" verb over its own storage. All four now default to a bounded, concise view, with `-m/--full` for the raw log: `agents logs <session>` renders the same summary digest as `agents sessions <id>` (a real session shrank 92% — 29.9 KB → 2.6 KB); `agents routines logs <name>` shows a status header + the extracted report (a real run shrank 99.5% — 386 KB → 1.8 KB), falling back to a bounded stdout tail when no report was extracted; `agents teams logs <teammate>` renders the teammate's session summary (its agentId **is** the session id), with `-n <lines>` / `--full` for raw stdout; `agents hosts logs <id>` shows a bounded tail of the captured stdout (`tailLines`, with a "… N earlier lines hidden — pass --full" note) instead of the whole log. `renderSessionLog` now takes a mode and defaults to `'summary'`; `agents sessions <id>` was already summary-by-default and is unchanged. Regression-tested: `tailLines` truncation/elision math (`hosts/logs.test.ts`) and `formatRunDuration` human-time formatting (`routines-logs.test.ts`). Source: `apps/cli/src/commands/{logs,sessions,hosts,teams,routines}.ts`, `apps/cli/src/lib/hosts/logs.ts`. Scoped follow-up (not in this PR): host-task and sandboxed-routine runs write their real transcript on the remote / in an overlay HOME, so `logs` can't yet resolve them to the full `renderSummary` — making those runs discoverable is a separate change; until then the bounded tail / extracted report is the safe concise default.
 - **The daemon now self-heals the `pane-died` hook on already-running `agents run` sessions.** The v1.20.42 fix that stops exiting a split from kicking you out of tmux is installed once, at session creation — so sessions already alive under the long-lived shared tmux server keep the old, unconditional `detach-client` hook until they exit or the server is recycled. On a machine that's never "between sessions," that meant hand-repairing live sessions. The daemon now runs `reconcileSessionHooks()` ~20s after startup and every ~5 min: it walks the managed `ag-` sessions on the shared socket and retrofits the `#{hook_pane}`-guarded hook onto any whose hook predates the current schema. It is strictly **non-destructive — `set-hook` only, never a `kill-pane` or `detach-client`** — so it is safe to run against sessions you're attached to; a per-session `@ag_hook_schema` marker makes steady-state a no-op. The hook string is now built in one place (`agentPaneDiedHook`) shared by the spawn-wrap and the reconcile so they can't drift. Source: `apps/cli/src/lib/tmux/session.ts`, `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/exec.ts`.
 - **NEW: `agents run` self-heals a gutted install instead of crashing with `ENOENT`.** The recurring failure: an npm agent whose native binary ships as an optional per-arch dependency (codex → `@openai/codex-<platform>`) can have that tarball extract **partially** — the platform package's `package.json` lands, its `vendor/<triple>/…/codex` binary does not (an interrupted or concurrently-raced `agents add` into the same version dir). The CLI's wrapper `require.resolve`s the platform package, finds the `package.json`, and sails straight past its own "missing optional dependency" guard into a `spawn(binaryPath)` that dies with a raw `ENOENT`. `agents run` now probes the version it's about to launch and, if the binary can't run, **repairs it in place** (a *clean* reinstall — the partial `node_modules` is wiped first, because npm treats the present-but-gutted platform package as already installed and would otherwise skip re-fetching it), then falls back to another installed version that launches (re-pinning it as the default so the shim path heals too), then to installing `latest` — only erroring if nothing can be made runnable. `installVersion` gained a `{ clean }` option for the wipe-then-reinstall. Source: `apps/cli/src/lib/versions.ts` (`ensureAgentRunnable`), `apps/cli/src/commands/exec.ts`.
@@ -11,6 +21,7 @@
 - **NEW: `--no-tmux` / `--disable-tmux` on `agents run`.** The interactive tmux wrapper (which gives `%pane` addressing + re-attach) already had an opt-out, but it was hidden behind the opaquely-named `--raw`. `--no-tmux` (and its alias `--disable-tmux`) spawn the agent directly with full stdio inherited — the fastest way to see an agent's real startup output when a launch is failing. Same effect as `--raw` and `AGENTS_NO_TMUX=1`. Source: `apps/cli/src/commands/exec.ts`.
 - **Fix: `agents add <agent>@<version>` no longer records a gutted install as healthy (root cause of the ENOENT crash + a broken default pin).** npm packages that ship their native binary via an optional per-arch dependency (e.g. codex → `@openai/codex-<platform>`) can land the JS wrapper at `node_modules/.bin/<cli>` while the real platform binary is missing (interrupted install, omitted optional dep, `--ignore-scripts`). `getBinaryPath()` only checked the wrapper, so the broken version read as installed, got pinned as the default, and got picked to run — then died with ENOENT. `installVersion` now probes `<binary> --version` (under the version's isolated HOME) after install and **fails the install** if the binary can't launch, so a broken version is never silently pinned. The check is deliberately narrow — only the missing-binary signature (`ENOENT`/"no such file"/"command not found") fails it; a plain nonzero exit or a timeout is treated as healthy, so a well-behaved agent that dislikes `--version` is never false-failed. Source: `apps/cli/src/lib/versions.ts`, `apps/cli/src/lib/versions-integrity.test.ts`.
 - **Security fix: the routines daemon log no longer leaks GitHub / AWS / npm tokens.** `daemon.ts` carried its own private `redactSecrets` (used by every `log()` write to `logs.jsonl`) that predated and diverged from the canonical `redact.ts` — it caught `sk-`, `eyJ…`, `Bearer …`, and a narrow `NAME=value` list, but **not** `ghp_` (GitHub PAT), `AKIA…` (AWS access key), or `npm_` (npm token), so any of those appearing in a daemon message (a git push URL, a bundle-env dump, an error string) was written to the log in the clear. The private copy is deleted; `log()` now routes through the canonical `redactSecrets` in `redact.ts`, which covers all of those classes with a stronger quote-aware `NAME=value` pattern. The one pattern the daemon copy had and the canonical lacked — `Bearer <token>` — is added to `redact.ts`, so the shared redactor (also used by session-transcript export in `session/render.ts`) is now a strict superset. New `redact.test.ts` pins every token class as a regression guard. Source: `apps/cli/src/lib/daemon.ts`, `apps/cli/src/lib/redact.ts`, `apps/cli/src/lib/redact.test.ts`.
+- **Fix: `agents teams doctor` tells the truth, a version fallback never spawns an unspawnable literal, and shims survive a vanished dispatcher (completing this release's self-heal series).** Three gaps remained after the `agents run` self-heal above. (1) **`agents teams doctor` lied** — it reported `installed: true` whenever a *shim file* existed, never checking the real binary, so a stub or gutted-native install (the exact codex/kimi failure) showed "ready" and then `ENOENT`'d at spawn. `checkCliAvailable` now verifies the resolved default version is actually installed, and doctor additionally **launch-probes** each installed agent (`verifyInstalledBinaryLaunches`) and flips a gutted-native one to not-installed with a repair hint. (2) **A version fallback spawned an unspawnable literal** — when a specific version was requested (`agents run kimi@0.19.2`, the path every version-pinned teammate takes) and no versioned shim existed on disk, the launch left the bare `<agent>@<version>` name as `argv[0]`, which is not on PATH, so it died with `spawn kimi@0.19.2 ENOENT`; it now resolves the version's real binary (`getBinaryPath`) instead, falling back to the literal only when no binary exists at all. (3) **A shim couldn't survive its dispatcher vanishing** — when the baked `AGENTS_BIN` (often a dev build under `~/.local/agents-cli-dev`) was removed, moved, or went stale, the shim exited 127 and bricked *every* managed launch; it now **self-recovers** to whatever `agents` resolves to on PATH before erroring (`SHIM_SCHEMA_VERSION` → 25). Also drops a stale, npm-unrecoverable `codex 0.116.0` pin from the repo's own `agents.yaml` so codex resolves to the machine default instead of self-healing on every run. Source: `apps/cli/src/lib/{exec,shims}.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/teams.ts`, `agents.yaml`.
 
 ## 1.20.43
 

package/dist/commands/exec.js

@@ -218,7 +218,7 @@ export function registerRunCommand(program) {
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
-        .option('--name <slug>', 'Give the run a durable name — a stable handle you can check on later with `agents sessions <name>` (and `agents hosts logs <name>` for --host runs), instead of an opaque id. Optional; omitting it keeps today\'s id-only behavior.')
+        .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing.')
@@ -359,13 +359,9 @@ export function registerRunCommand(program) {
                 process.exit(1);
             }
             const hostName = hostGiven[0];
-            if (prompt === undefined) {
-                console.error(chalk.red('A prompt is required for host runs: agents run <agent> "<task>" --host <name>'));
-                process.exit(1);
-            }
             const { resolveHost, resolveHostByCap } = await import('../lib/hosts/registry.js');
-            const { dispatchToHost } = await import('../lib/hosts/dispatch.js');
-            const { registerHostSession } = await import('../lib/hosts/session-index.js');
+            const { dispatchToHost, runInteractiveOnHost } = await import('../lib/hosts/dispatch.js');
+            const { registerHostSession, registerInteractiveHostSession } = await import('../lib/hosts/session-index.js');
             // A password-auth device throws DeviceOffloadUnsupportedError here; it's
             // printed cleanly by the top-level catch in index.ts (covers every
             // resolveHost caller), so it never falls through to capability routing.
@@ -396,10 +392,57 @@ export function registerRunCommand(program) {
                 // which can't run over a detached remote dispatch — only forward a
                 // concrete id.
                 const resumeId = typeof options.resume === 'string' ? options.resume : undefined;
-                // Mirror the local path (lib/exec.ts): only Claude accepts a forced
-                // `--session-id`. Generating it here lets us register the run in the
-                // local index and makes it resumable by that id. On resume the remote
-                // session keeps its existing id — don't mint a new one.
+                // Decide whether this host run is interactive. No prompt always means
+                // interactive (matching local resolveInteractive); --interactive forces
+                // interactive even when a prompt is provided; --headless forces headless
+                // and therefore requires a prompt.
+                if (options.interactive && options.headless) {
+                    console.error(chalk.red('--interactive and --headless are mutually exclusive. Pass one, or neither (mode is inferred from prompt presence).'));
+                    process.exit(1);
+                }
+                const interactiveHost = options.interactive === true || (prompt === undefined && options.headless !== true);
+                if (interactiveHost) {
+                    // Interactive host run: forward the local TTY over SSH and let the
+                    // remote agent start its normal interactive UI (tmux on the host).
+                    if (options.follow === false) {
+                        console.error(chalk.red('--no-follow is not compatible with interactive host runs. Interactive runs are attached by definition.'));
+                        process.exit(1);
+                    }
+                    // Mirror the local path (lib/exec.ts): only Claude accepts a forced
+                    // `--session-id`. Generating it here lets us register the run in the
+                    // local index and makes it resumable by id. On resume the remote
+                    // session keeps its existing id — don't mint a new one.
+                    const hostSessionId = runAgent === 'claude' && !resumeId ? randomUUID() : undefined;
+                    if (hostSessionId) {
+                        registerInteractiveHostSession({
+                            cwd: process.cwd(),
+                            host: host.name,
+                            agent: runAgent,
+                            sessionId: hostSessionId,
+                            name: options.name,
+                        });
+                    }
+                    const exitCode = await runInteractiveOnHost(host, {
+                        agent: runAgent,
+                        prompt,
+                        mode: options.mode,
+                        model: options.model,
+                        remoteCwd: options.remoteCwd,
+                        sessionId: hostSessionId,
+                        name: options.name,
+                        resume: resumeId,
+                        passthroughArgs,
+                        raw: options.raw || options.tmux === false || options.disableTmux === true,
+                        forceInteractive: options.interactive,
+                    });
+                    process.exit(exitCode);
+                }
+                // Headless host run: launch detached, tail the remote log, and follow
+                // until the remote process exits.
+                if (prompt === undefined) {
+                    console.error(chalk.red('A prompt is required for headless host runs: agents run <agent> "<task>" --host <name>'));
+                    process.exit(1);
+                }
                 const hostSessionId = runAgent === 'claude' && !resumeId ? randomUUID() : undefined;
                 const { task, exitCode } = await dispatchToHost(host, {
                     agent: runAgent,

package/dist/commands/secrets.d.ts

@@ -9,6 +9,24 @@ import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
 import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
+/**
+ * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
+ * from stdin (the SSH push path: `export --host` pipes the resolved dotenv over
+ * ssh stdin, which has no `/dev/stdin` on a Windows remote); any other value is
+ * a filesystem path.
+ */
+export declare function readImportDotenv(from: string): string;
+/**
+ * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
+ * forwards verbatim; otherwise the explicit bundle names. A `--ttl` is passed
+ * through as-is so the REMOTE parses its own duration (its platform rules, its
+ * defaults). Shared with the command action so the wiring is unit-testable
+ * without a live SSH session.
+ */
+export declare function buildRemoteUnlockArgs(names: string[], opts: {
+    all?: boolean;
+    ttl?: string;
+}): string[];
 export { SSH_TARGET_RE, assertValidSshTarget };
 /**
  * Build the child environment for `agents secrets exec`. Strips

package/dist/commands/secrets.js

@@ -12,7 +12,9 @@ import * as fs from 'fs';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted } from '../lib/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, resolveSshTarget, } from '../lib/secrets/remote.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveSshTarget, } from '../lib/secrets/remote.js';
+import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -139,6 +141,29 @@ function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
+/**
+ * Read the raw `.env` text for `import --from <path|->`. A `-` reads the .env
+ * from stdin (the SSH push path: `export --host` pipes the resolved dotenv over
+ * ssh stdin, which has no `/dev/stdin` on a Windows remote); any other value is
+ * a filesystem path.
+ */
+export function readImportDotenv(from) {
+    return from === '-' ? readStdinSync() : fs.readFileSync(from, 'utf-8');
+}
+/**
+ * Build the remote `agents secrets unlock` argv for `unlock --host`. `--all`
+ * forwards verbatim; otherwise the explicit bundle names. A `--ttl` is passed
+ * through as-is so the REMOTE parses its own duration (its platform rules, its
+ * defaults). Shared with the command action so the wiring is unit-testable
+ * without a live SSH session.
+ */
+export function buildRemoteUnlockArgs(names, opts) {
+    return [
+        'unlock',
+        ...(opts.all ? ['--all'] : names),
+        ...(opts.ttl ? ['--ttl', opts.ttl] : []),
+    ];
+}
 // SSH target validation is defined canonically in src/lib/ssh-exec.ts and
 // re-exported here for back-compat with existing importers of these symbols.
 export { SSH_TARGET_RE, assertValidSshTarget };
@@ -1162,7 +1187,7 @@ Examples:
     cmd
         .command('import [bundle]')
         .description('Import keys from a .env file or a 1Password vault into a bundle. The bundle is created if it does not exist. Values are stored in the bundle\'s backend (keychain by default).')
-        .option('--from <path>', 'Path to a .env file')
+        .option('--from <path>', 'Path to a .env file (use - to read the .env from stdin)')
         .option('--from-1password', 'Import secrets from a 1Password vault (requires the op CLI)')
         .option('--vault <name>', '1Password vault name (used with --from-1password)')
         .option('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
@@ -1227,7 +1252,7 @@ Examples:
                 console.log(chalk.green(`Imported ${added} key(s) from 1Password vault '${vault}'${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
             }
             else {
-                const raw = fs.readFileSync(opts.from, 'utf-8');
+                const raw = readImportDotenv(opts.from);
                 const pairs = parseDotenv(raw);
                 for (const [key, value] of Object.entries(pairs)) {
                     if (!opts.force && key in bundle.vars) {
@@ -1294,34 +1319,47 @@ Examples:
                 const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export` });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
-                // Drive the remote's own `agents secrets` CLI so values land in its
-                // chosen backend. `bash -lc` so the login PATH resolves `agents`; the
-                // .env (and, for file, the passphrase) flow over ssh stdin and are
-                // never parsed by a remote shell.
-                const force = opts.force ? ' --force' : '';
-                const backendFlag = remoteBackend === 'file' ? ' --backend file' : '';
-                let remoteAgents;
-                let input;
-                if (remoteBackend === 'file') {
-                    // import --backend file auto-creates the file-backed bundle; no
-                    // separate `create` needed.
-                    remoteAgents =
-                        `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
-                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${backendFlag}${force}`;
-                    input = `${remotePassphrase}\n${dotenv}`;
-                }
-                else {
-                    remoteAgents =
-                        `agents secrets create ${shellQuote(resolvedBundleName)} >/dev/null 2>&1 || true; ` +
-                            `agents secrets import ${shellQuote(resolvedBundleName)} --from /dev/stdin${force}`;
-                    input = dotenv;
-                }
-                const remoteCmd = `bash -lc ${shellQuote(remoteAgents)}`;
+                // Drive the remote's own `agents secrets import --from -` so the values
+                // land in its chosen backend, reading the .env off ssh stdin (never
+                // parsed by a remote shell — `--from -` replaces the POSIX-only
+                // `/dev/stdin`). The keychain path is built OS-aware via
+                // `remoteSecretsRaw` (bash -lc on POSIX, PowerShell on Windows), so it
+                // works on macOS, Linux AND Windows targets. `import` auto-creates the
+                // bundle, so no separate `create` (the old `|| true` was a POSIXism
+                // that broke on PowerShell: `'true' is not recognized`).
                 let failures = 0;
                 for (const host of hosts) {
-                    // Routed through the shared ssh engine: full hardened options
-                    // (BatchMode, ConnectTimeout, keepalive) + control-socket reuse.
-                    const res = sshExec(host, remoteCmd, { input });
+                    let res;
+                    if (remoteBackend === 'file') {
+                        // File backend forwards AGENTS_SECRETS_PASSPHRASE as the FIRST stdin
+                        // line (consumed by `read`, so it never lands in argv / `ps` /
+                        // remote history), then the .env. That `read`/`export` prologue is
+                        // POSIX shell — refuse a Windows target cleanly rather than emit
+                        // broken PowerShell.
+                        if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
+                            failures++;
+                            console.error(chalk.red(`${host}: file backend export to a Windows target is not yet supported.`));
+                            continue;
+                        }
+                        const remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
+                            `agents secrets import ${shellQuote(resolvedBundleName)} --from - --backend file${opts.force ? ' --force' : ''}`;
+                        res = sshExec(host, `bash -lc ${shellQuote(remoteAgents)}`, { input: `${remotePassphrase}\n${dotenv}` });
+                    }
+                    else if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
+                        // Keychain on a Windows target: the `agents.ps1` shim doesn't
+                        // forward ssh-piped stdin to node, so `--from -` would hang.
+                        // Bridge the piped .env through PowerShell into a temp file and
+                        // import `--from <file>` (deleted afterwards). Same hardened ssh
+                        // engine, .env still only ever crosses the wire over ssh stdin.
+                        res = sshExec(host, buildWindowsStdinImportCommand(resolvedBundleName, { force: opts.force }), { input: dotenv });
+                    }
+                    else {
+                        // Keychain on a POSIX target: OS-aware wrapping + hardened ssh
+                        // engine (BatchMode, ConnectTimeout, keepalive, control-socket
+                        // reuse) via the same path the READ inverse (`remoteResolveEnv`)
+                        // uses. `--from -` reads the .env off ssh stdin.
+                        res = remoteSecretsRaw(host, ['import', resolvedBundleName, '--from', '-', ...(opts.force ? ['--force'] : [])], { input: dotenv });
+                    }
                     if (res.code === null) {
                         failures++;
                         console.error(chalk.red(`${host}: ${res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed')}`));
@@ -1554,10 +1592,47 @@ Examples:
     });
     cmd
         .command('unlock [names...]')
-        .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS).')
+        .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .option('--all', 'Unlock every configured bundle')
+        .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
+        // Single-valued (not variadic): a variadic --host greedily consumes the
+        // positional bundle name (`unlock --host mac wztest` -> host=[mac,wztest],
+        // names=[]). Unlock targets one remote at a time anyway.
+        const hosts = opts.host ? [opts.host] : [];
+        if (hosts.length > 0) {
+            // Remote unlock: the REMOTE enforces its own platform rules, so the
+            // local darwin-only guard below does NOT apply. Only file-backed
+            // bundles are remote-unlockable — their passphrase prompt surfaces over
+            // the -tt SSH TTY; a keychain/biometry bundle would trigger a local GUI
+            // Touch-ID sheet that can't cross SSH.
+            if (!opts.all && (!names || names.length === 0)) {
+                console.error(chalk.red('Specify one or more bundle names, or --all.'));
+                process.exit(1);
+            }
+            const unlockArgs = buildRemoteUnlockArgs(names, opts);
+            let failures = 0;
+            for (const h of hosts) {
+                const target = await resolveSshTarget(h);
+                // FOREGROUND stream (stdio inherited), NOT the piped remoteSecretsRaw:
+                // the remote's passphrase prompt only surfaces if the remote process
+                // sees a real TTY, which requires our local terminal to pass straight
+                // through. The remote's prompt + output stream to this terminal; we get
+                // back only the exit code.
+                const code = remoteSecretsStream(target, unlockArgs);
+                if (code === 0) {
+                    console.log(chalk.green(`${h}: unlocked`));
+                }
+                else {
+                    failures++;
+                    console.error(chalk.red(`${h}: unlock failed (exit ${code})`));
+                }
+            }
+            if (failures > 0)
+                process.exit(1);
+            return;
+        }
         if (process.platform !== 'darwin') {
             console.error(chalk.red('secrets-agent is macOS-only (no biometry prompt to deduplicate elsewhere).'));
             process.exit(1);

package/dist/commands/teams.js

@@ -17,6 +17,7 @@ import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/se
 import { renderSessionLog } from './sessions.js';
 import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
+import { checkRunAccountReadiness } from '../lib/rotate.js';
 import { teamPicker, printTeamTable } from './teams-picker.js';
 import { itemPicker } from '../lib/picker.js';
 import { profileExists, readProfile } from '../lib/profiles.js';
@@ -192,6 +193,51 @@ export function wireCloudDispatcher(mgr) {
  * teammate whose CLI may not be signed in. Warn-only — never blocks `start`.
  * Local teammates only; cloud teammates authenticate through their provider.
  */
+/**
+ * Advisory line for a version-pinned teammate whose account can't serve a run
+ * right now. A pinned target (`agents run <agent>@<version>`) bypasses account
+ * rotation — the pin IS the target — so unlike a bare teammate it can't route
+ * around a throttled/expired account; it will launch and likely 429 at once.
+ */
+function throttleWarningLine(agent, version, r) {
+    const who = `${AGENT_NAMES[agent]} ${version}`;
+    const acct = r.email ? ` (${r.email})` : '';
+    const reason = r.reason === 'out_of_credits' ? 'is out of credits'
+        : r.reason === 'signed_out' ? 'is not signed in'
+            : 'is rate-limited right now';
+    return (chalk.yellow(`⚠ ${who}${acct} ${reason}.`) +
+        chalk.gray(`\n  A pinned version skips account rotation, so it will launch on this account and may immediately hit its limit.` +
+            `\n  Use a bare \`${agent}\` teammate to let the team pick a healthy account, or pass --force to silence this.`));
+}
+/**
+ * Advisory: for each staged VERSION-PINNED teammate, warn if its account is
+ * rate-limited / out of credits / signed out right now — reusing the router's
+ * own eligibility signal (`checkRunAccountReadiness`) so the warning matches
+ * what the spawn would actually do. Bare teammates (rotation handles them) and
+ * profile/cloud teammates (account not locally checkable) are skipped. Warns,
+ * never blocks. Deduped by agent@version so N teammates on one account warn once.
+ */
+async function warnThrottledTeammates(mgr, team) {
+    let pending;
+    try {
+        pending = (await mgr.listByTask(team)).filter((a) => a.status === 'pending' && !a.cloudProvider && !a.profileName && a.version);
+    }
+    catch {
+        return; // team not loadable yet — nothing to warn about
+    }
+    const seen = new Set();
+    for (const a of pending) {
+        const agent = a.agentType;
+        const version = a.version;
+        const key = `${agent}@${version}`;
+        if (seen.has(key) || !AGENT_NAMES[agent])
+            continue;
+        seen.add(key);
+        const readiness = await checkRunAccountReadiness(agent, version);
+        if (!readiness.ready)
+            console.error(throttleWarningLine(agent, version, readiness));
+    }
+}
 async function warnUnsignedTeammates(mgr, team) {
     let pending;
     try {
@@ -967,7 +1013,7 @@ export function registerTeamsCommands(program) {
         .option('--cloud <provider>', `Dispatch to cloud backend instead of local CLI: ${VALID_CLOUD_PROVIDERS.join('|')}`)
         .option('--repo <owner/repo>', 'GitHub repository (required for --cloud rush)')
         .option('--branch <name>', 'Target git branch for cloud dispatch')
-        .option('--force', "Skip the advisory 'may not be signed in' warning (detection is unreliable)")
+        .option('--force', "Skip the advisory 'may not be signed in' / 'account throttled' warnings")
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, teammate, task, opts) => {
         if (!VALID_MODES.includes(opts.mode)) {
@@ -1007,6 +1053,16 @@ export function registerTeamsCommands(program) {
             console.error(chalk.yellow(`⚠ ${AGENT_NAMES[agent]} may not be signed in (detection is unreliable). Adding anyway.`) +
                 chalk.gray(`\n  If it fails to start, run \`${AGENTS[agent].cliCommand}\` to log in, or pass --force to silence this.`));
         }
+        // Advisory throttle check — only for a version-pinned teammate, which
+        // bypasses account rotation and so can't route around a rate-limited /
+        // out-of-credits / signed-out account (see throttleWarningLine). Skip bare
+        // targets (rotation handles them), profiles (auth-injected account isn't
+        // the version-home one we can read), and cloud dispatch. Warn, never block.
+        if (!opts.force && !cloudProviderId && !profileName && version) {
+            const readiness = await checkRunAccountReadiness(agent, version);
+            if (!readiness.ready)
+                console.error(throttleWarningLine(agent, version, readiness));
+        }
         if (opts.name !== undefined) {
             if (!opts.name || !/^[A-Za-z0-9_-]+$/.test(opts.name)) {
                 die(`Invalid teammate name '${opts.name}'. Use letters, numbers, '-', or '_'.`);
@@ -1276,7 +1332,7 @@ export function registerTeamsCommands(program) {
         .option('--watch', 'Keep running: poll every --interval seconds, fire new waves, exit when the DAG drains.')
         .option('--interval <seconds>', 'Seconds between waves in --watch mode (default 8)', '8')
         .option('--max-waves <n>', 'Safety cap on waves in --watch mode (default 1000)', '1000')
-        .option('--force', "Skip the advisory 'may not be signed in' warning for staged teammates (detection is unreliable)")
+        .option('--force', "Skip the advisory 'may not be signed in' / 'account throttled' warnings for staged teammates")
         .action(async (team, opts) => {
         const mgr = mkManager();
         wireCloudDispatcher(mgr);
@@ -1286,8 +1342,10 @@ export function registerTeamsCommands(program) {
                 return;
             team = picked;
         }
-        if (!opts.force && !isJsonMode(opts))
+        if (!opts.force && !isJsonMode(opts)) {
             await warnUnsignedTeammates(mgr, team);
+            await warnThrottledTeammates(mgr, team);
+        }
         if (!opts.watch) {
             await runOneWave(mgr, team, Boolean(opts.json));
             return;