@phnx-labs/agents-cli 1.22.106 → 1.22.109

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.22.109
+
+- **`agents sessions backup-setup` provisions the managed session-backup endpoint (PHNX-3726).** The operator command that deploys `sessions.agents-cli.sh` — the Cloudflare Worker + R2 bucket a signed-in user's `agents sessions export --to-r2` backs up to with no `r2.backups` bucket of their own. Mirrors `agents traces setup`: reads Cloudflare credentials from the `cloudflare` secrets bundle (`agents secrets exec cloudflare -- agents sessions backup-setup`), idempotent (re-running redeploys the current Worker template in place). It is NOT a per-user step — signing in with `agents auth login` is all a user does; this is how the first-party endpoint itself is deployed. The Worker it deploys is Phoenix-only with no static token (PHNX-3726). Source: `cli/src/commands/sessions-backup-setup.ts`, `cli/src/lib/session/sync/provision.ts` (+ `provision.test.ts`), `cli/docs/sessions.md`.
+
+- **`agents doctor` flags a leaked daemon no owner record names (W4, PHNX-3736).**
+  A headless e2e session launched `agents __daemon-run` under
+  `HOME=/tmp/pin-e2e-<pid>` and never stopped it; the daemon ran 4+ days,
+  invisible to the pid-file takeover because it keeps its own pid file under the
+  temp home. `agents doctor` now reports any same-uid `__daemon-run` whose pid is
+  neither the service manager's unit main PID nor the recorded `daemon.pid` —
+  checked against both the caller's HOME and the real account home, so a
+  test-harness caller never accuses the production daemon — as a `leaked-daemon`
+  warning carrying the process's HOME and start time, with a `kill <pid>`
+  remediation. Source: `cli/src/lib/daemon/leaked-daemons.ts`,
+  `cli/src/lib/devices/doctor-findings.ts`.
+
+- **`agents daemon start` refuses under a redirected HOME unless
+  `AGENTS_ALLOW_TEST_DAEMON=1` (W4, PHNX-3736).** RUSH-3021 gated auto-start from
+  a sandbox/test HOME but left the explicit `startDaemon()` open — the path the
+  e2e harness took to leak the `/tmp/pin-e2e-<pid>` daemon. The launch now throws
+  `RedirectedHomeDaemonError` (printed without a stack, exit 1); a deliberate
+  test/e2e launch opts in with `AGENTS_ALLOW_TEST_DAEMON=1` and owns stopping
+  what it starts. Reporting an already-running daemon — and therefore
+  `agents daemon stop` of a leaked one — is not gated. Auto-start side effects
+  (`routines add`, webhook fires, `monitors add`) state the refusal and leave
+  the foreground command green, the same tier split as the auto-start circuit
+  breaker; only the explicit start commands fail loud. Source:
+  `cli/src/lib/daemon/daemon.ts` (`startDaemon`).
+
+- **The managed share Worker now proxies same-origin human collaboration to Prix (PHNX-3835).** The Cloudflare Worker that fronts a managed share gains a `/__collab/*` transport so authorized humans can review a hosted artifact together (comments now; agent mentions/wake-up later). It stays the trust boundary exactly as the page GET does: every `/__collab` request loads the R2 object FIRST (a missing/just-deleted share 404s, so existence is never enumerable), re-derives the share id (`SHA-256(ownerId + NUL + normalized path)`), current revision (etag), owner, visibility, org domain, and producer provenance SERVER-SIDE from R2 metadata — the browser-supplied `share` is a lookup key only, never trusted as identity — then reuses the EXACT page read gate (me/org identity gate + private viewer-token gate) with every denial normalized to 404. Public/unlisted readers may read anonymously; every write additionally requires a verified signed-in Phoenix human; private still requires its share token. It proxies to the Prix `/v1/artifact-collaboration` routes (`context`, `threads` list/create, thread replies, comment/thread PATCH, SSE `events`, and a best-effort authenticated `purge` on share delete) with the service token in `Authorization` (never surfaced to the browser) plus trusted `X-Artifact-*` / `X-Phoenix-Actor-*` headers, preserves the client `Idempotency-Key` and `Last-Event-ID`, streams SSE through unbuffered (cancel/disconnect propagated), and marks every collaboration response `no-store`. A visibility downgrade is immediate (re-gated per request) and a deleted share drops its comments the instant the object is gone. The whole surface fails closed (404) when `PRIX_ARTIFACT_COLLAB_BASE` / `ARTIFACT_COLLAB_SERVICE_TOKEN` are absent — so BYO endpoints (no Phoenix identity) never expose it and the artifact page GET is unaffected — and stays dormant until an operator sets both secrets, which `agents artifacts share update`/`setup` now apply on a managed deploy (both or neither). Because the Worker template changed, already-deployed managed endpoints read `outdated` until re-run through `agents artifacts share update`. Source: `cli/src/lib/share/worker-template.ts`, `cli/src/lib/share/provision.ts`, `cli/src/lib/share/backend.ts`, `cli/src/commands/share.ts`, `cli/docs/share.md`.
+
+- **`agents sync --dry-run` no longer mutates every native home (PHNX-3923).** The umbrella verb (bare `agents sync`, including `--local`/`--yes`/`--json`) ignored `--dry-run` entirely: it ran the full reconcile, evicted central browser profiles, verified, and repaired — mutating every installed version home despite the preview flag. The umbrella composes only mutating stages (repo `git pull`, `refresh()` reconcile, device sync, `repairAfterSync`) with no non-mutating preview, so it now refuses `--dry-run` LOUD and up front — before any change — and points at the scoped path (`agents sync <agent> --dry-run`), which honors it non-destructively. `--json` reports `{ ok: false, mode: 'umbrella', dryRun: true, error, hint, installedAgents }`. Source: `cli/src/commands/sync.ts`.
+
+- Terminal session resumes preserve follow-up prompts, including spaces and shell characters. Remote terminals use the origin directory or explicit `--cwd`; run pickers retain `--remote-cwd` precedence, and home-relative paths expand on the target. An invalid remote directory or failed terminal launch reports failure.
+
+- Publishes the session-resume fixes from the unshipped 1.22.108 candidate: account homes refresh their session tracker, Codex hook trust follows registration, empty local picks are skipped, and remote picks are validated on their origin device. The 1.22.108 tag is preserved; npm publication resumes with this patch after correcting its release notes.
+
+- **`agents view` shows OpenCode's real model, account, plan, and last-active (PHNX-3982).** The OpenCode row was the only one in the table with nothing usable in it — `1.18.15 (default)  default  id:meta+openai+opencode-go` — while every other harness showed a model, an email, and a plan. Three separate reads were pointed at the wrong place. (1) The model came from `<home>/.opencode/settings.json`, which is agents-cli's own plugin-enablement file; OpenCode reads `~/.config/opencode/opencode.{jsonc,json}`, and ships no catalog default, so the row fell through to the literal placeholder `default`. Both spellings are now read comment-tolerantly, and when nothing is configured the row shows the model OpenCode itself will start with, from the selection it persists to `$XDG_STATE_HOME/opencode/model.json`. (2) The account showed only the provider join because the code asserted OpenCode's `auth.json` carries no identity — it does, for `type: 'oauth'` providers, in the same namespaced JWT claims `case 'codex'` already decodes, so the email and plan now render (secrets are never read out, only claims). (3) `lastActive` was blank because the per-file session walk finds nothing for a harness that keeps every session in one sqlite file; it now dates from `opencode.db`. Live usage *windows* remain unavailable for OpenCode — it records no rate-limit state locally and each provider would need its own reader. Source: `cli/src/lib/agent-spec/agents.ts`, `cli/src/lib/models.ts`.
+
+## 1.22.108
+
+- Account sync now refreshes the native session-tracking hook in every account home, replacing stale registrations from previous CLI installations so new sessions retain their account identity. Codex tracker installation also refreshes hook trust so headless runs can execute the registered hook.
+
+- Resume selection validates peer-owned transcripts on their origin device instead of treating a missing local copy as a missing session. Local empty picks are still skipped; explicit local replay still requires readable local content.
+
+- **The resume picker skips a local session with no transcript before opening a
+  tab (PHNX-4080).** Empty local selections are reported as skipped, and a batch
+  with nothing left to resume exits 1. Peer-owned sessions and mirror entries are
+  validated on their origin device. Explicit local replay still requires readable
+  local content; the executing device refuses recovery when no transcript exists.
+  Source: `src/commands/sessions-resume.ts`, `src/lib/session/recovery.ts`.
+
+## 1.22.107
+
+- **A bare interactive run places itself like `--device auto` (PHNX-4083).**
+  `agents run <harness>` with no prompt on a real TTY (no `--json`) now
+  auto-places onto a fleet worker — the same engine, pool, and banner as
+  `--device auto` — instead of always running on the machine you typed it at;
+  headless runs (any prompt, `--json`, teams/routines/hooks) are unchanged and
+  still run in place. To keep a local interactive run, pass
+  `--device <this machine>` or pick this machine (listed first) in the
+  `<harness>@` device picker; when placement finds no healthy device (empty
+  pool, or the PHNX-4051 stale-usage refusal) the run fails loud with the
+  placement error plus `Run here instead: agents run <harness> --device
+  <this machine>` — never a silent local fallback. Source:
+  `src/commands/exec.ts`, `src/commands/run-account-picker.ts`.
+
+- **Run pickers move to `#` (account) and `@` (device), `#@` asks both
+  (PHNX-4083).** `agents run claude#` now opens the account picker (the old
+  `claude@` menu, same rows and code path); `agents run claude@` opens the new
+  fleet device picker — this machine first, offline rows disabled, cached-state
+  age in the prompt — and `claude#@` asks the account first, then the device,
+  dispatching with the picked account label. A picker combined with an explicit
+  pin of the same thing (`claude@2.1.218#`, `claude#work#`, `claude@@`) or a
+  conflicting flag (`--account`, `--device`/`--on`/`--computer`/`--host`) fails
+  loud; a cancelled menu launches nothing. Source: `src/commands/exec.ts`,
+  `src/lib/hosts/dispatch.ts`.
+
 ## 1.22.106
 
 - Fixed release packages omitting the session-tracking hook. Release qualification now uses the complete CLI build, so installed agents can record the account that owns each native session.

package/README.md

@@ -202,11 +202,15 @@ agents run claude "refactor auth module" --mode edit --fallback codex,antigravit
 # Picks the signed-in account you haven't used recently.
 agents run claude "summarize recent commits" --strategy balanced
 
-# Or choose one account/version interactively for only this run.
-agents run claude@
-agents run codex@ "review this branch"
-agents run claude@ --device auto        # pick the device, then choose there
-agents run claude@ --device yosemite-s0 # choose from one device's accounts
+# Or choose one account/version interactively for only this run (# = account picker).
+agents run claude#
+agents run codex# "review this branch"
+agents run claude# --device auto        # pick the device, then choose there
+agents run claude# --device yosemite-s0 # choose from one device's accounts
+
+# @ picks the device instead; #@ asks both (account first, then device).
+agents run claude@                      # pick the device for this run
+agents run claude#@                     # pick the account, then the device
 ```
 
 `--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force a rate-limited default) -- it never launches into an exhausted account. A logged-out default is never forced: unpinned dispatch picks a signed-in version on the execution device instead of dying on a credential-less default home.

package/dist/commands/daemon.js

@@ -21,7 +21,8 @@ import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, } from '../lib/daemon/daemon.js';
+import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
+import { listDaemonRunProcesses } from '../lib/daemon/leaked-daemons.js';
 import { getConfigValue, setConfigValue, isDaemonEnabled } from '../lib/device-config.js';
 import { readSubsystemHealth, readAllSubsystemHealth, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START, } from '../lib/daemon-health.js';
 import { DAEMON_SERVICE_IDS, listDaemonServiceStates, setDaemonServiceEnabled, getDaemonServicesConfigPath, queueDaemonServiceRestart, } from '../lib/daemon-services.js';
@@ -32,6 +33,27 @@ import { parseDuration } from '../lib/hooks/cache.js';
 import { registerFunnelCommand } from './funnel.js';
 import { DEFAULT_WEBHOOK_PORT, DEFAULT_WEBHOOK_RATE_LIMIT, addHostedReceiver, getDaemonWebhooksConfigPath, hostedReceiverPort, readDaemonWebhooksConfig, removeHostedReceiver, } from '../lib/daemon-webhooks.js';
 import { parseFunnelPort } from '../lib/funnel.js';
+// ─── Process scanning — which install owns the pid, and every duplicate ──────
+/**
+ * startDaemon for the explicit start/restart commands: the redirected-HOME
+ * refusal (W4, PHNX-3736) is user-actionable, not an engineering bug, so it
+ * prints without a stack and exits 1. Anything else (a genuinely unspawnable
+ * binary) still throws. Kept local to this command rather than in bootstrap's
+ * catch list — a bootstrap.ts edit selects the 54s non-interactive suite into
+ * the required impact gate, and this change's budget cannot carry it.
+ */
+function startDaemonClean() {
+    try {
+        return startDaemon();
+    }
+    catch (err) {
+        if (err instanceof RedirectedHomeDaemonError) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        throw err;
+    }
+}
 /**
  * Provably absent, or null when unknowable.
  *
@@ -188,19 +210,14 @@ function entryFromTokens(tokens) {
     return tokens.length >= 2 ? tokens[tokens.length - 2] : null;
 }
 /**
- * Every live `__daemon-run` process on this box, regardless of which install
- * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
- * Windows.
- *
- * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
- * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
- * A substring/regex test anywhere in the full command line is not enough: an
- * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
- * literal text `__daemon-run` (this ticket's own brief does) matches that test
- * too, and was observed producing false "duplicate daemon" rows. Requiring it
- * to be the LAST whitespace-delimited token is the actual invariant.
+ * Every live `__daemon-run` process on this box, enriched with display
+ * metadata (entry/version/entryMissing). The raw `ps` scan and its
+ * last-token `__daemon-run` invariant live in
+ * `lib/daemon/leaked-daemons.ts` (`listDaemonRunProcesses`) — shared with the
+ * doctor's leaked-daemon detection so the two can never disagree on what a
+ * daemon process is.
  *
- * This raw box-wide scan is deliberately NOT the duplicate-detection scope
+ * This box-wide scan is deliberately NOT the duplicate-detection scope
  * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
  * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
  * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
@@ -209,35 +226,14 @@ function entryFromTokens(tokens) {
  * `findSurvivingStateDirDaemons` has already confirmed as real duplicates.
  */
 function scanDaemonProcesses() {
-    if (process.platform === 'win32')
-        return [];
-    let out;
-    try {
-        out = execFileSync('ps', ['-eo', 'pid=,uid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-    }
-    catch {
-        return [];
-    }
     const found = [];
-    for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
-        if (!m)
-            continue;
-        const args = m[3].trim();
-        const tokens = args.split(/\s+/);
-        if (tokens.length === 0 || tokens[tokens.length - 1] !== '__daemon-run')
-            continue;
-        const pid = parseInt(m[1], 10);
-        if (isNaN(pid))
-            continue;
-        const uidParsed = parseInt(m[2], 10);
-        const uid = isNaN(uidParsed) ? null : uidParsed;
-        const entry = entryFromTokens(tokens);
-        const version = entry ? resolveVersionNear(entry, pid) : null;
+    for (const p of listDaemonRunProcesses()) {
+        const entry = entryFromTokens(p.tokens);
+        const version = entry ? resolveVersionNear(entry, p.pid) : null;
         // Asks whether the code is on disk for the NEXT launch -- what a restart and
         // every other reader will see -- not what this pid currently has mapped.
         const entryMissing = entry ? entryAbsent(entry) : false;
-        found.push({ pid, entry, version, entryMissing, uid });
+        found.push({ pid: p.pid, entry, version, entryMissing, uid: p.uid });
     }
     return found;
 }
@@ -905,6 +901,15 @@ export function registerDaemonCommand(program) {
       'agents daemon start' still starts it explicitly, same as
       'systemctl start' on a disabled unit.
 
+      Under a redirected HOME (a test/e2e harness), 'agents daemon start'
+      REFUSES to launch: a daemon started there keeps its own pid file under
+      the temp home and leaks, invisible to the real install (W4, PHNX-3736).
+      'daemon restart' inherits the same guard — it stops first, so run it
+      with the same opt-in. A deliberate test launch sets
+      AGENTS_ALLOW_TEST_DAEMON=1 — and the harness owns stopping what it
+      started. 'agents doctor' flags any leaked daemon that already exists,
+      with its HOME and start time.
+
       'agents daemon services enable|disable|restart <id>' applies live (no
       daemon restart) for supervisor-managed services that were registered at
       boot. browser-ipc is also registered while disabled, specifically so a
@@ -924,7 +929,7 @@ export function registerDaemonCommand(program) {
     cmd.command('start')
         .description('Start the daemon. Bypasses daemon.enabled — this is the deliberate override.')
         .action(() => {
-        const result = startDaemon();
+        const result = startDaemonClean();
         if (result.method === 'already-running') {
             console.log(chalk.yellow(`Daemon already running (PID: ${result.pid})`));
         }
@@ -977,7 +982,7 @@ export function registerDaemonCommand(program) {
             for (const s of stop.surviving)
                 console.log(chalk.red(`  surviving: ${s}`));
         }
-        const result = startDaemon();
+        const result = startDaemonClean();
         if (result.pid)
             console.log(chalk.green(`Daemon started (PID: ${result.pid}, ${result.method})`));
         else

package/dist/commands/doctor.js

@@ -16,6 +16,7 @@ import { hostIdentityArgs, sshTargetFor } from '../lib/hosts/types.js';
 import { deviceIdentityArgs } from '../lib/devices/connect.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { findAmbiguousDevicePins } from '../lib/scheduling/routines.js';
+import { findLeakedDaemons } from '../lib/daemon/leaked-daemons.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -478,6 +479,10 @@ async function runDevicesDoctor(opts) {
                 // remote boxes self-report it in their own `agents doctor --json`.
                 ownerSink: await probeOwnerSink(readMeta()),
                 binaryShadows: detectAgentsBinaryShadows(),
+                // A `__daemon-run` no unit main PID or daemon.pid owns (W4, PHNX-3736) —
+                // the /tmp/pin-e2e leak class the registry-scoped duplicate check cannot
+                // see. Local only: a remote box self-reports in its own doctor.
+                leakedDaemons: findLeakedDaemons(),
             }));
             accounts[localName] = r.inventory?.signIn ?? {};
             continue;
@@ -1478,6 +1483,8 @@ export function registerDoctorCommand(program) {
                 // Can the owner-delivery lane (feed/notify) escalate a block from this
                 // box? A factory that cannot escalate is not healthy (RUSH-2262).
                 ownerSink: await probeOwnerSink(readMeta()),
+                // A `__daemon-run` no unit main PID or daemon.pid owns (W4, PHNX-3736).
+                leakedDaemons: findLeakedDaemons(),
             });
             if (opts.json) {
                 const overviewPayload = {

package/dist/commands/exec.d.ts

@@ -10,13 +10,24 @@ import type { ExecEffort } from '../lib/exec.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
 /** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
 export declare function parseExplicitSessionId(value: string): string;
-export interface RunAccountPickerRequest {
-    requested: boolean;
+export interface RunPickerMarkers {
+    accountPicker: boolean;
+    devicePicker: boolean;
     normalizedAgentSpec: string;
     valid: boolean;
+    reason?: string;
 }
-/** Distinguish a terminal account-picker marker from an explicit @version pin. */
-export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
+/**
+ * Parse the trailing picker markers on an `agents run` agent spec. A terminal
+ * run of `#`/`@` characters requests the account picker (`#`) and/or the
+ * device picker (`@`) — each at most once, in either order (`claude#@`,
+ * `claude@#`). Stripping them yields the normalized spec (`claude#work@` →
+ * `claude#work`, version pins and `#label` account pins intact). A picker
+ * cannot combine with an explicit pin of what it picks: `claude@2.1.218#`
+ * (the account picker already chooses the version — the old `claude@2.1.218@`
+ * rule), `claude#work#`, `claude@@`.
+ */
+export declare function parseRunPickerMarkers(agentSpec: string): RunPickerMarkers;
 /**
  * The `--device` alias family — the flags that mean "dispatch this run to another
  * machine over SSH". `--device` is canonical; `--on`/`--computer` are hidden
@@ -31,11 +42,29 @@ export declare function hostTargetGiven(options: {
     on?: string;
     computer?: string;
 }): string[];
-/** Return every option whose selection semantics conflict with an account choice. */
+/**
+ * Return every option whose selection semantics conflict with an account
+ * choice (`agent#`). Device routing is deliberately absent: the marker rides
+ * the hop and the peer picks from ITS slots.
+ */
 export declare function runAccountPickerConflicts(options: {
     resume?: string | boolean;
     strategy?: string;
     balanced?: boolean;
+    lease?: string | boolean;
+    box?: string;
+    account?: string;
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
+/**
+ * Return every option that already decides where the run lands, so a device
+ * choice (`agent@`) would be silently ignored: any explicit host flag, and the
+ * lease/box paths, which own placement outright.
+ */
+export declare function runDevicePickerConflicts(options: {
     lease?: string | boolean;
     box?: string;
     host?: string;
@@ -47,11 +76,15 @@ export { RUN_AUTO_KEYWORD };
 /**
  * Whether `run auto` should default its host layer to the affinity pick (the
  * same machinery as `--device auto`). False when the caller pinned any host
- * flag, and false when this process was itself dispatched by a host run — the
- * dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
+ * flag, and false when this process was itself dispatched by a host run —
+ * the dispatcher exports AGENTS_RUN_AUTO_HOST_RESOLVED=1 into the remote SHELL
  * (hosts/dispatch.ts remoteRunShellPrelude) because it already resolved the
  * host layer, and re-picking here would chain-hop the run across the fleet.
- * Pure so the pinning matrix is unit-testable.
+ * An INTERACTIVE dispatch of a named harness also reaches the remote as a bare
+ * `agents run <harness>` (its argv forwards without the routing flag), so the
+ * interactive prelude's AGENTS_REMOTE_INTERACTIVE=1 counts as "already placed"
+ * too — without it the remote would re-place the run and ping-pong across the
+ * fleet. Pure so the pinning matrix is unit-testable.
  */
 export declare function runAutoDefaultsToAffinity(options: {
     host?: string;
@@ -59,6 +92,43 @@ export declare function runAutoDefaultsToAffinity(options: {
     on?: string;
     computer?: string;
 }, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether a bare human-facing `agents run <harness>` — no prompt, so an
+ * interactive TUI run — defaults its placement to `--device auto` (PHNX-4083).
+ * A marker left off is decided for you: no `#` means balanced rotation, and no
+ * `@` (and no other placement flag) now means automatic device placement — the
+ * same engine as `--device auto`, whose pool never contains a box marked
+ * `personal`. ALL of these must hold:
+ *
+ * - no prompt (headless runs — teams, routines, hooks, `run <agent> "…"` —
+ *   keep running in place, unchanged);
+ * - a human-facing surface: a real TTY and no `--json`. This is the same
+ *   two-condition gate `signInLaunchDecision` uses in run-account-picker.ts —
+ *   reused here through isHumanFacingRun, not re-derived;
+ * - no device-picker marker (`agent@` already chose the device; picking this
+ *   machine there is a plain local run);
+ * - no `--resume` / `--lease` / `--box` / `--cloud` (those own placement);
+ * - the host layer is unpinned and this process is not itself a dispatched
+ *   hop — delegated to runAutoDefaultsToAffinity, which encodes both.
+ *
+ * Pure so the default-placement matrix is unit-testable.
+ */
+export declare function bareInteractiveRunDefaultsToDeviceAuto(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+    resume?: string | boolean;
+    lease?: string | boolean;
+    box?: string;
+    cloud?: boolean;
+}, run: {
+    prompt?: string;
+    devicePickerRequested?: boolean;
+}, surface: {
+    tty: boolean;
+    json?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether an interactive host dispatch must mint a correlation launch id and
  * resolve the remote session via the launch-id join (RUSH-2034), rather than