@phnx-labs/agents-cli 1.22.72 → 1.22.74

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 1.22.74
+
+- **Launching an agent no longer dirties your tracked `.gitignore` (PHNX-3718).**
+  The per-harness resource sync self-manages ignore rules for the generated
+  `.claude/`, `.cursor/`, `.codex/`, … dirs it writes on every launch. Those
+  rules used to be written into the tracked `<project>/.gitignore`, but they are
+  never committed upstream — so every launch left the repo with a permanent
+  `M .gitignore` (one managed block per harness that had run there) that in turn
+  blocked `git pull` with *"local changes to .gitignore would be overwritten by
+  merge"*. The managed block now lives in `.git/info/exclude` (git's per-clone,
+  uncommitted ignore file, resolved via `git rev-parse --git-path info/exclude`
+  so it works from a subdir, linked worktree, or submodule), keeping the
+  generated dirs hidden while leaving the working tree clean. On the next launch,
+  a repo already dirtied by the old behavior self-heals: the leftover managed
+  block is stripped from the tracked `.gitignore` (hand-written rules untouched;
+  an untracked file that held only our block is removed). Source:
+  `cli/src/lib/project-resources.ts`.
+
+- **`sessions preview` of a remote session no longer dead-ends on the dispatcher
+  (PHNX-3890).** A box that launched a session running on another device kept a
+  transcript-less live row for it whose machine defaulted to itself, so
+  `agents sessions preview <full-uuid>` — and the interactive browser's preview
+  pane — rendered `Live session — full transcript not indexed here.` instead of
+  fetching the owning peer's digest. A passive peer rendered the same session
+  fine. The launcher shim is now reconciled against the fleet's own view of which
+  device runs the session, and a full-UUID hit only skips the fleet fan-out when
+  this box can actually answer for it (a transcript on disk, or a row that already
+  names another device). Remote previews fill in asynchronously over SSH; a
+  locally readable transcript or synced mirror still renders with no hop, and an
+  unreachable owner still fails loud. Source: `cli/src/commands/sessions.ts`,
+  `cli/src/lib/session/live-metadata.ts`.
+
+## 1.22.73
+
+- **Ctrl-C works again while `agents sessions` is reaching other machines (PHNX-3791).** The static session list, `Searching the fleet…`, and the cloud session/fetch paths wrap their long SSH/network waits in `ora(...)`. ora defaults to `discardStdin: true`, which on a TTY flips stdin into raw mode for the spinner's lifetime (via `stdin-discarder`) — and raw mode disables the terminal's own ISIG, so a Ctrl-C keystroke no longer raises SIGINT. ora's compensating "re-emit SIGINT when I read a 0x03 byte" only fires when stdin is in *flowing* mode, but a fresh `process.stdin` has `flowing === null`, `isPaused()` returns false, the discarder skips its `resume()`, and `prependListener('data')` doesn't auto-resume — so the byte is never read and SIGINT is never raised. The global handler in `index.ts` (`process.exit(130)`) was correct; it simply never fired. The user-visible result: a sweep that stalls on offline/unreachable boxes (each burning a ~12s SSH `ConnectTimeout`) could not be aborted — measured, `agents sessions --flat` had to be SIGKILLed. New `lib/spinner.ts#interruptibleSpinner` is a drop-in for `ora(text)` built with `discardStdin: false`: the terminal stays in cooked mode, Ctrl-C raises SIGINT normally (and the terminal SIGINTs the whole foreground group, reaping the outstanding `ssh` children), and the process exits promptly — only cosmetic stray-keystroke discarding during the spin is lost. The five cross-machine/network spinners in `sessions.ts` route through it; short local spinners are unchanged. Source: `cli/src/lib/spinner.ts`, `cli/src/lib/spinner.test.ts`, `cli/src/commands/sessions.ts`.
+
+- **Remote-host session previews render inline, no per-row SSH (PHNX-3792).** On
+  the interactive device, a session that originated on another box used to show
+  as a bare `[host/<peer>]` row with no topic, and its preview pane fetched the
+  peer's digest live over SSH — slow, and blank when the peer was asleep. Each
+  box now mirrors its own sessions' lightweight preview/metadata (topic, first
+  user message, last activity, agent+version, cwd, ticket, PR) into its
+  conflict-free `devices/<device>/daemon-state.json`, which the daemon's existing
+  bounded Git transport already delivers fleet-wide. The picker, `agents sessions`
+  list, and `focus` read the local mirror, so a peer session shows its real
+  topic/preview inline — even while the peer is offline (last-synced). The live
+  SSH digest fetch remains the fallback for a never-synced session, and `space`
+  still reads the full transcript live. No transcript leaves the worker; the
+  mirror is bounded and pruned by age. Source: `src/lib/session/mirror.ts`,
+  `src/lib/fleet-shared-state.ts`, `src/lib/session/db.ts`,
+  `src/lib/daemon/usage-sync-service.ts`, `src/commands/sessions-picker.ts`.
+
+- **Ctrl-C works during `agents repo` git operations too (PHNX-3793).** Follow-up to PHNX-3791. `cli/src/commands/repo.ts` wrapped its seven git network ops — clone, git-backing, pull, push, adopt, sync — in bare `ora(...)` spinners, whose default `discardStdin: true` raw-modes the TTY and swallows Ctrl-C for the whole operation (same trap PHNX-3791 fixed for the session sweep). A `git clone`/`pull` stalled on a slow or dead remote could hang longer than a fleet sweep with no way to abort. All seven now use `lib/spinner.ts#interruptibleSpinner` (`discardStdin: false`), so Ctrl-C raises SIGINT and the process exits promptly. Source: `cli/src/commands/repo.ts`.
+
+- **`agents sessions --json` now carries the initiator's Phoenix ID (PHNX-3798).**
+  The actor resolver already mapped a run's tailnet identity to a `phoenixId`
+  (the stable internal work identity) and rode it through the exec env, but it was
+  never persisted per session, so a durable listing couldn't attribute a session
+  to a person's work identity. The `phoenixId` now flows the same path the
+  `actor`/`initiatedBy` fields already take — stamped into the durable actor
+  sidecar at launch, joined into a new write-once `phoenix_id` column via a v47
+  schema migration, and emitted by the sessions feed. Best-effort throughout: a
+  session with no mapped Phoenix ID (the common case) simply omits the field
+  rather than emitting a null/empty sentinel. This is the persistence half of the
+  ownership work whose resolver landed in PHNX-3798's first PR. Source:
+  `src/lib/session/actor-sidecar.ts`, `src/lib/session/db.ts`,
+  `src/lib/session/types.ts`, `src/lib/exec.ts`.
+
+- **`agents packages materialize` materializes a schema-v3 `agent.yaml` package into an ephemeral Claude, Codex, or OpenCode home (PHNX-3838).** The noun-first surface takes `--harness`, `--harness-version` (root `--version` is the CLI version flag), and `--output-home`. It is a thin front door over the canonical native-home materializer (`agent-spec/materialize.ts`): it resolves the package once and projects every declared resource (instructions, skills, subagents, mcp, hooks) into the output home, then prints the materialization receipt (agent ref + digest, harness, per-resource targets, warnings); `--json` is the Factory/Prix Cloud handoff and is byte-identical to the `materialization-receipt.json` written into the home. It writes only under `--output-home`: it never mutates the live user home, never copies secrets, and never execs a harness. A non-portable harness, a non-exact `--harness-version`, a missing/invalid package, and an output-path escape (including the live `~/.claude`/`~/.codex`/`~/.opencode` homes) all fail loud. Source: `cli/src/commands/packages-materialize.ts`, `cli/src/lib/packages/output-home.ts`, `cli/src/lib/agent-spec/materialize.ts`.
+- **`agents packages materialize` is hardened against four path-traversal / symlink escapes (PHNX-3838).** (1) `materializeAgentPackage` now realpath-verifies every per-resource write/delete target against the canonical output home before touching disk, and `--output-home` additionally refuses the live home ROOT and canonicalizes symlinked ancestors. So neither `--output-home "$HOME"` (the materializer appends `.claude`/`.codex`/`.opencode`), a symlink aliasing `$HOME`, nor a symlink planted at the harness-config-dir join point inside the output home can write into the live harness home — and a direct (Factory / Prix Cloud) caller that skips the CLI front door is protected too. (2) The stale-prune step strictly validates the unsigned `materialization-receipt.json` schema and realpath-checks every `resources[].target` as a contained path at deletion time, so a planted receipt can no longer make it `rm -rf` a `../victim`, an absolute path, or a path under a symlinked ancestor outside the output home. (3) A package `hook.name` must be a safe single path segment, re-checked for containment before the script is copied and `chmod +x`'d. (4) Package resources reject symlinked file/directory/hook sources and realpath-check every source under the package's real root, so `instructions.md -> /etc/passwd` or a skill dir symlinked outside the package can no longer be read or copied. Source: `cli/src/lib/packages/output-home.ts`, `cli/src/lib/agent-spec/materialize.ts`, `cli/src/lib/agent-spec/package-resolve.ts`, `cli/src/lib/paths.ts`.
+- **`agents packages materialize` closes two more output-home boundary gaps (PHNX-3838).** (1) When any protected `~/.claude`/`~/.codex`/`~/.opencode` home is a DANGLING symlink or dangling chain (following relative links and chains), `resolveOutputHome` now fails closed and refuses EVERY output home until the link is repaired — because the materializer's first `mkdir -p` would otherwise follow the link and re-create the operator's live harness home at the materialized tree, and the absent target it points at has no canonical spelling to compare a specific candidate against. (2) Materializing a package that carries hooks no longer runs the normal orphan-shim sweep against the ONE process-global shim dir (`~/.agents/.cache/shims/hooks/`): that sweep deletes every shim absent from the manifest it is handed, so with a package's hooks-only manifest it would wipe the operator's unrelated hook shims. `registerHooksToSettings` gained an isolated `skipGlobalShimSweep` option that the materializer sets; normal install/sync keeps the sweep. Source: `cli/src/lib/packages/output-home.ts`, `cli/src/lib/hooks/install.ts`, `cli/src/lib/agent-spec/materialize.ts`.
+- **`agents packages materialize` fails closed on a dangling protected home instead of approximating filesystem collation (PHNX-3838).** An earlier iteration compared the live-home identity case- and Unicode-normalization-insensitively (NFC + `toLowerCase`) on macOS/Windows to catch a spelling-equivalent alias of a DANGLING `~/.claude` (e.g. an absent `.../Real-Claude` vs `--output-home .../real-claude`). An independent macOS review proved that approximation wrong: APFS treats e.g. U+017F ſ and ASCII `s` as identical while JS `toLowerCase` does not, and an OS-derived case-sensitivity flag is wrong for per-volume semantics. The guard no longer tries to reproduce a volume's collation from the path text — when a protected home dangles it refuses every output home (fail closed, above), and an EXISTING protected home is compared with exact `realpath` identity, which needs no approximation. The `pathIdentityKey`/`pathIsWithin`/`FS_CASE_INSENSITIVE` helpers added for the approximation are removed. Source: `cli/src/lib/packages/output-home.ts`, `cli/src/lib/paths.ts`.
+
 ## 1.22.72
 
 - **The self-managed `.gitignore` block now ignores the `.agents-managed.json` manifest too, so a synced harness dir is actually clean in `git status` (PHNX-3717).** The project-resource sync's gitignore reconciliation (shipped in 1.22.71) listed the synced commands/skills but not the manifest marker file the sync also writes into each harness dir — so `.factory/` (etc.) still showed as untracked on the strength of that one unignored file, defeating the point. `reconcileProjectGitignore` now feeds `.agents-managed.json` through the same anchoring + escape guard, and the block persists (shrunk to just the manifest) while that file exists rather than fully pruning. Covered by a new test that asserts a real `git status --porcelain` no longer reports the generated dir. Source: `cli/src/lib/project-resources.ts`, `cli/src/lib/project-resources.test.ts`.

package/README.md

@@ -154,6 +154,8 @@ agents mcp list
 
 Skills, slash commands, rules, hooks, and permissions work the same way -- install once in `~/.agents/`, synced to every agent's native format automatically.
 
+A schema-v3 `agent.yaml` package materializes into an ephemeral Claude, Codex, or OpenCode home for Factory / Prix Cloud workers (`agents packages materialize ./reviewer --harness codex --harness-version 0.42.0 --output-home "$OUTPUT_HOME" --json`) -- it never writes the live user home.
+
 ```bash
 agents skills add gh:yourteam/python-expert     # Knowledge pack -> all agents
 agents commands add gh:yourteam/commands         # Slash commands -> all agents

package/dist/cli/command-registry.d.ts

@@ -105,7 +105,7 @@ export declare const LAZY_COMMAND_NAMES: ReadonlySet<string>;
  *
  * Most names map to a single loader. The exceptions encode real coupling on main:
  *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
- *  - `registry`/`search`/`install` all come from the packages module.
+ *  - `registry`/`search`/`install`/`packages` all come from the packages module.
  *  - `trash` and `restore` are separate registrars in the trash module.
  *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
  *    (which finds that command and attaches the `cleanup` subcommand).

package/dist/cli/command-registry.js

@@ -115,7 +115,7 @@ export const LAZY_COMMAND_NAMES = new Set([
  *
  * Most names map to a single loader. The exceptions encode real coupling on main:
  *  - `add`/`use`/`list`/`remove`/`rm`/`purge` all come from the versions module.
- *  - `registry`/`search`/`install` all come from the packages module.
+ *  - `registry`/`search`/`install`/`packages` all come from the packages module.
  *  - `trash` and `restore` are separate registrars in the trash module.
  *  - `prune` needs versions FIRST (it creates `prune <specs...>`) then prune.js
  *    (which finds that command and attaches the `cleanup` subcommand).
@@ -152,6 +152,7 @@ export const COMMAND_LOADERS = {
     registry: [loadPackages],
     search: [loadPackages],
     install: [loadPackages],
+    packages: [loadPackages],
     routines: [loadRoutines],
     monitors: [loadMonitors],
     projects: [loadProjects],

package/dist/commands/packages-materialize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents packages materialize` — user-facing front door for portable-agent
+ * materialization (PHNX-3838). ONE execution path: this command resolves the
+ * schema-v3 package once with {@link resolveAgentPackage} and projects it into
+ * an ephemeral native home with the canonical {@link materializeAgentPackage}
+ * (agent-spec/materialize.ts). The front door owns only what a materializer must
+ * not: the portable-harness allowlist, an exact harness version, and the
+ * output-home refusal that keeps a run off the live `~/.claude` / `~/.codex` /
+ * `~/.opencode` homes.
+ */
+import type { Command } from 'commander';
+import { type MaterializationReceipt } from '../lib/agent-spec/index.js';
+import { PORTABLE_HARNESSES } from '../lib/packages/output-home.js';
+export { PORTABLE_HARNESSES };
+export type { MaterializationReceipt };
+/** Register `agents packages materialize`. */
+export declare function registerPortablePackageCommands(program: Command): void;

package/dist/commands/packages-materialize.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import { die, isJsonMode } from '../lib/format.js';
+import { setHelpSections } from '../lib/help.js';
+import { resolveAgentPackage, materializeAgentPackage, AgentPackageError, } from '../lib/agent-spec/index.js';
+import { MaterializeGuardError, PORTABLE_HARNESSES, assertExactHarnessVersion, assertPortableHarness, resolveOutputHome, } from '../lib/packages/output-home.js';
+export { PORTABLE_HARNESSES };
+function printReceipt(receipt, outputHome) {
+    console.log(chalk.bold(`Materialized ${receipt.agent.ref} → ${receipt.harness.id}@${receipt.harness.version}`));
+    console.log(`  digest       ${receipt.agent.digest}`);
+    console.log(`  output home  ${outputHome}`);
+    for (const entry of receipt.resources) {
+        console.log(`  ${entry.kind.padEnd(12)} ${entry.name}  →  ${entry.target}`);
+    }
+    if (receipt.warnings.length > 0) {
+        console.log(chalk.yellow('  warnings'));
+        for (const warning of receipt.warnings)
+            console.log(chalk.yellow(`    ${warning}`));
+    }
+}
+function fail(err, json) {
+    if (err instanceof MaterializeGuardError || err instanceof AgentPackageError) {
+        die(err.message, 1, { json });
+    }
+    die(err instanceof Error ? err.message : String(err), 1, { json });
+}
+/** Register `agents packages materialize`. */
+export function registerPortablePackageCommands(program) {
+    const packagesCmd = program
+        .command('packages')
+        .description('Portable agent packages — materialize schema-v3 agent.yaml into an ephemeral harness home');
+    setHelpSections(packagesCmd, {
+        examples: `
+      # Materialize a package into an ephemeral Claude home
+      agents packages materialize ./reviewer --harness claude --harness-version 2.1.0 --output-home /tmp/reviewer-claude
+
+      # Machine-readable receipt for Factory / Prix Cloud
+      agents packages materialize ./reviewer --harness codex --harness-version 0.42.0 --output-home "$OUTPUT_HOME" --json
+
+      # OpenCode worker on a Factory box
+      agents packages materialize ./reviewer --harness opencode --harness-version 1.0.0 --output-home "$OUTPUT_HOME" --json
+    `,
+        notes: `
+      Materialize writes only under --output-home. It never mutates ~/.claude,
+      ~/.codex, or ~/.opencode, never copies secrets, and never execs a harness.
+
+      Factory usage: point --output-home at the worker's ephemeral home and pass
+      --json so the orchestrator can read the receipt (agent ref + digest,
+      harness, per-resource targets, warnings).
+    `,
+    });
+    const materializeCmd = packagesCmd
+        .command('materialize <package>')
+        .description('Materialize a schema-v3 agent.yaml package into an ephemeral Claude, Codex, or OpenCode home')
+        .requiredOption('--harness <id>', `Target harness: ${PORTABLE_HARNESSES.join(', ')}`)
+        .requiredOption('--harness-version <version>', 'Exact harness version to gate capabilities and stamp on the receipt (not --version: that is the CLI version flag)')
+        .requiredOption('--output-home <dir>', 'Ephemeral home to write into (must not escape or target the live user home)')
+        .option('--json', 'Emit the materialization receipt as JSON')
+        .action((pkg, opts) => {
+        const json = isJsonMode(opts);
+        try {
+            const harness = assertPortableHarness(opts.harness);
+            const harnessVersion = assertExactHarnessVersion(opts.harnessVersion);
+            const outputHome = resolveOutputHome(opts.outputHome);
+            const resolved = resolveAgentPackage(pkg);
+            const receipt = materializeAgentPackage(resolved, { harness, harnessVersion, outputHome });
+            if (json) {
+                // Verbatim canonical receipt — byte-identical to the
+                // materialization-receipt.json the materializer wrote into the home.
+                console.log(JSON.stringify(receipt, null, 2));
+                return;
+            }
+            printReceipt(receipt, outputHome);
+        }
+        catch (err) {
+            fail(err, json);
+        }
+    });
+    setHelpSections(materializeCmd, {
+        examples: `
+      agents packages materialize ./reviewer --harness claude --harness-version 2.1.0 --output-home /tmp/reviewer-claude
+      agents packages materialize ./reviewer --harness codex --harness-version 0.42.0 --output-home "$OUTPUT_HOME" --json
+      agents packages materialize ./reviewer --harness opencode --harness-version 1.0.0 --output-home "$OUTPUT_HOME" --json
+    `,
+        notes: `
+      Factory / Prix Cloud: materialize into the worker's ephemeral home, then
+      exec the harness with HOME=$OUTPUT_HOME. The --json receipt is the handoff.
+
+      Supported harnesses: claude, codex, opencode. Any other id fails as an
+      unsupported capability. A package must be a directory containing agent.yaml
+      with schema_version: 3 and an execution block declaring the harness.
+    `,
+    });
+}

package/dist/commands/packages.d.ts

@@ -1,13 +1,15 @@
 /**
  * Package registry and installation commands.
  *
- * Registers `agents registry`, `agents search`, and `agents install`
- * for discovering and installing MCP servers, skills, commands, and
- * hooks from configured registries or GitHub sources.
+ * Registers `agents registry`, `agents search`, `agents install`, and
+ * `agents packages materialize` for discovering and installing MCP servers,
+ * skills, commands, and hooks from configured registries or GitHub sources,
+ * and for materializing a schema-v3 agent.yaml package into an ephemeral
+ * harness home (PHNX-3838).
  */
 import type { Command } from 'commander';
 import type { McpPackage } from '../lib/types.js';
 import { type McpCommandSpec } from '../lib/mcp.js';
 export declare function buildMcpPackageCommand(pkg: McpPackage): McpCommandSpec;
-/** Register the `agents registry`, `agents search`, and `agents install` commands. */
+/** Register the `agents registry`, `agents search`, `agents install`, and `agents packages` commands. */
 export declare function registerPackagesCommands(program: Command): void;

package/dist/commands/packages.js

@@ -1,9 +1,11 @@
 /**
  * Package registry and installation commands.
  *
- * Registers `agents registry`, `agents search`, and `agents install`
- * for discovering and installing MCP servers, skills, commands, and
- * hooks from configured registries or GitHub sources.
+ * Registers `agents registry`, `agents search`, `agents install`, and
+ * `agents packages materialize` for discovering and installing MCP servers,
+ * skills, commands, and hooks from configured registries or GitHub sources,
+ * and for materializing a schema-v3 agent.yaml package into an ephemeral
+ * harness home (PHNX-3838).
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -23,6 +25,7 @@ import { listInstalledVersions, resolveConfiguredAgentTargets, syncResourcesToVe
 import { formatPath, isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
 import { registerMcpCommandToTargets, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
+import { registerPortablePackageCommands } from './packages-materialize.js';
 export function buildMcpPackageCommand(pkg) {
     const packageName = pkg.name || pkg.registry_name;
     if (pkg.runtime === 'node') {
@@ -80,8 +83,9 @@ async function pickRegistryName(type, verb, pred) {
         throw err;
     }
 }
-/** Register the `agents registry`, `agents search`, and `agents install` commands. */
+/** Register the `agents registry`, `agents search`, `agents install`, and `agents packages` commands. */
 export function registerPackagesCommands(program) {
+    registerPortablePackageCommands(program);
     // ==========================================================================
     // REGISTRY COMMANDS
     // ==========================================================================

package/dist/commands/repo.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { visibleWidth, padVisible } from '../lib/format.js';
 import { stripAnsi } from '../lib/session/width.js';
-import ora from 'ora';
+import { interruptibleSpinner } from '../lib/spinner.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -785,7 +785,7 @@ export function registerRepoCommands(program) {
             return;
         }
         const parsed = parseSource(options.from);
-        const spinner = ora(`Cloning ${options.from} into ${targetDir}...`).start();
+        const spinner = interruptibleSpinner(`Cloning ${options.from} into ${targetDir}...`).start();
         try {
             fs.mkdirSync(path.dirname(targetDir), { recursive: true });
             await simpleGit().clone(parsed.url, targetDir);
@@ -885,7 +885,7 @@ export function registerRepoCommands(program) {
             process.exitCode = 1;
             return;
         }
-        const spinner = ora(`Cloning ${source}...`).start();
+        const spinner = interruptibleSpinner(`Cloning ${source}...`).start();
         try {
             fs.mkdirSync(path.dirname(targetDir), { recursive: true });
             await simpleGit().clone(parsed.url, targetDir);
@@ -1023,7 +1023,7 @@ export function registerRepoCommands(program) {
                 // user. Only the USER repo gets this — system is cloned by setup, extras
                 // by `repo add`.
                 if (t.alias === 'user' && url) {
-                    const spinner = ora(`Git-backing ${t.dir} from ${url}...`).start();
+                    const spinner = interruptibleSpinner(`Git-backing ${t.dir} from ${url}...`).start();
                     const res = await adoptRepo(url, t.dir);
                     if (!res.success) {
                         spinner.fail(`user: could not git-back — ${res.error}`);
@@ -1049,7 +1049,7 @@ export function registerRepoCommands(program) {
                 // Skip system repo unless explicitly requested
                 continue;
             }
-            const spinner = ora(`Pulling ${formatRepoTarget(t.alias, t.dir)}...`).start();
+            const spinner = interruptibleSpinner(`Pulling ${formatRepoTarget(t.alias, t.dir)}...`).start();
             const result = await pullRepo(t.dir);
             if (result.success) {
                 spinner.succeed(`${formatRepoTarget(t.alias, t.dir, result.branch)}: ${result.commit}`);
@@ -1127,7 +1127,7 @@ export function registerRepoCommands(program) {
             // the previous tick's state and delays propagation by one repo cycle.
             if (t.alias === 'user')
                 await publishUserRepoAccountState(true);
-            const spinner = ora(`Pushing ${formatRepoTarget(t.alias, t.dir)}...`).start();
+            const spinner = interruptibleSpinner(`Pushing ${formatRepoTarget(t.alias, t.dir)}...`).start();
             const result = await commitAndPush(t.dir, options.message);
             if (result.success) {
                 spinner.succeed(`${formatRepoTarget(t.alias, t.dir, result.branch)}: ${result.detail ?? 'pushed'}`);
@@ -1171,7 +1171,7 @@ Examples:
                 // state, then fall through to the normal sync (PHNX-3301). System is
                 // cloned by setup and extras by `repo add`, so those still skip.
                 if (t.alias === 'user' && fs.existsSync(t.dir)) {
-                    const spinner = ora(`Adopting ${formatRepoTarget(t.alias, t.dir)} in place...`).start();
+                    const spinner = interruptibleSpinner(`Adopting ${formatRepoTarget(t.alias, t.dir)} in place...`).start();
                     const adopted = await adoptUserRepoIfNeeded(t.dir);
                     if (!adopted || !adopted.success) {
                         spinner.fail(`${formatRepoTarget(t.alias, t.dir)}: ${adopted?.error ?? 'adopt failed'}`);
@@ -1199,7 +1199,7 @@ Examples:
             // so the same transaction carries it; consume peers after the pull.
             if (t.alias === 'user')
                 await publishUserRepoAccountState(false);
-            const spinner = ora(`Syncing ${formatRepoTarget(t.alias, t.dir)}...`).start();
+            const spinner = interruptibleSpinner(`Syncing ${formatRepoTarget(t.alias, t.dir)}...`).start();
             const result = t.alias === 'user'
                 ? await (async () => {
                     const { syncFleetSharedStateRepo } = await import('../lib/fleet-shared-repo-sync.js');

package/dist/commands/sessions-picker.js

@@ -306,6 +306,7 @@ function previewCacheKey(session, remote) {
         session.topic, session.ticketId, session.prUrl, session.messageCount,
         session.tokenCount, session.model, session.todos, session.plan,
         session.recentDirectoriesTouched, session.skillsUsed,
+        session.firstUserMessage, session.mirrorSyncedAt,
     ]);
 }
 export function clearPreviewMemoryCacheForTest() {
@@ -363,12 +364,38 @@ export function buildPreview(session) {
         return cached;
     const safe = sanitizeMeta(session);
     // Remote session: the transcript is on the peer's disk, so there is nothing to
-    // parse here. Fetch the peer's already-computed digest over SSH (kicked off on
-    // first render; the pane repaints when it lands) and render the same compact
-    // preview a local row gets. Until it arrives — or when the peer can't answer —
-    // show the metadata header (agent, cwd, msgs, tokens — all carried over in the
-    // fan-out) plus where it lives and how to open it.
+    // parse here. The common case is now a fleet-synced MIRROR row (PHNX-3792): its
+    // topic + first-user snippet + metadata are already local, so the compact card
+    // renders INLINE with no per-row SSH. The live SSH digest fetch stays as the
+    // fallback for a never-synced row (or a peer whose digest was already fetched
+    // this session), and `space` still reads the full transcript live over SSH.
     if (remote) {
+        // A fleet-synced MIRROR row is the explicit signal that this box already
+        // holds the peer session's topic + first-user snippet locally (PHNX-3792):
+        // render inline with NO per-row SSH. An ordinary remote row (a live fan-out
+        // row, or a never-synced host-dispatch stub) is NOT treated as synced — it
+        // keeps the live digest fetch below, so this change is scoped to mirror rows.
+        const fetched = remoteDigestCache.get(remoteDigestKey(session.id, remote));
+        if (fetched?.state === 'ready') {
+            // A richer live digest already landed this session (changed files, tool
+            // mix) — prefer it over the lightweight mirror card.
+            const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
+                + chalk.gray(` — enter to resume there`);
+            const body = formatCompactPreview(fetched.digest, safe);
+            const output = [formatHeader(safe, []), '', note, body].filter(Boolean).join('\n');
+            previewCache.set(cacheKey, output);
+            return output;
+        }
+        if (safe.mirrorSyncedAt !== undefined) {
+            const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
+                + chalk.gray(` — synced from the fleet; enter to resume there, or space to read it live over SSH`);
+            const metaBody = formatMetaOnlyBody(safe);
+            const output = [formatHeader(safe, []), '', note, metaBody].filter(Boolean).join('\n');
+            previewCache.set(cacheKey, output);
+            return output;
+        }
+        // Not a mirror row: fall back to the live SSH digest fetch (kicked off on
+        // first render; the pane repaints when it lands).
         const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
             + chalk.gray(` — enter to resume there, or space then enter to read it over SSH`);
         const entry = remoteDigestForPreview(session, remote);
@@ -554,8 +581,12 @@ function formatMetaOnlyBody(session) {
     const termWidth = process.stdout.columns || 80;
     const valueWidth = termWidth - VERB_GUTTER - 5;
     // Same verb-led rows as the digest body (RUSH-2757), from SessionMeta alone.
-    if (session.topic) {
-        lines.push(verbLabel('Asked') + chalk.white(`"${truncate(session.topic.trim(), valueWidth)}"`));
+    // Prefer the fuller first genuine user turn over the one-line topic when the
+    // row carries it (a fleet-synced mirror row does — PHNX-3792) so the inline
+    // card reads like the originating prompt, not just its title.
+    const asked = session.firstUserMessage?.trim() || session.topic?.trim();
+    if (asked) {
+        lines.push(verbLabel('Asked') + chalk.white(`"${truncate(asked, valueWidth)}"`));
     }
     const compact = formatTodoCompact(session.todos);
     const teamLine = formatTeamLineage(session);

package/dist/commands/sessions.d.ts

@@ -896,9 +896,58 @@ export declare function metadataResolveOutcome(localMatches: SessionMeta[], remo
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
-/** Injectable dependency for the live-registry cold-miss fallback (RUSH-2682). */
+/**
+ * Whether a local candidate answers a full-UUID selector **definitively** — i.e.
+ * whether finding it on this box is the whole answer, so the fleet fan-out can be
+ * skipped (PHNX-3890).
+ *
+ * Two shapes qualify, and both are claims this box can actually back:
+ *
+ * - **A real transcript on this disk** (`filePath`). It renders locally, whoever
+ *   owns it — a local session or a fleet-synced mirror — so no SSH hop is needed.
+ * - **A genuine peer attribution** (`machine` names another box). The row already
+ *   routes the read to its owner through `transcriptOnPeerOf`, so the peer that
+ *   would answer the fan-out is the peer the render already dials.
+ *
+ * What does NOT qualify is the launcher-shim shape: a transcript-less live row
+ * whose `machine` is this box only because it DEFAULTED there
+ * (`activeSessionToSessionMeta`'s `active.machine ?? self`,
+ * `computeLocalMetadataMatches`'s `machine || localMachine`). A dispatcher holds
+ * exactly that row for a session whose agent and transcript live on a peer: the
+ * launch process is here, the conversation is not. Treating it as definitive is
+ * what dead-ended `agents sessions preview <full-uuid>` on the local
+ * "Live session — full transcript not indexed here." stub while a passive peer —
+ * which has no local row at all, so it fans out — rendered the real digest.
+ * Process locality is not transcript locality.
+ */
+export declare function isLocallyDefinitiveMatch(session: SessionMeta, self: string): boolean;
+/**
+ * Drop the launcher-shim local rows that a peer has since answered for
+ * (PHNX-3890). `fleetCandidatesByQuery` groups a logical session's copies per
+ * machine and every consumer reads `hits[0]`, with local rows passed first — so
+ * simply fanning out is not enough: the self-defaulted shim would still win the
+ * attribution and route the read back to a box with no transcript. When the peer
+ * that actually owns the session has answered the sweep, its row is the strictly
+ * better one, and the shim carries no information the candidate loses (same
+ * logical id, so the candidate — and any ambiguity it is part of — survives
+ * through the remote hit).
+ *
+ * A row that is {@link isLocallyDefinitiveMatch} is never dropped, so a locally
+ * readable transcript or a synced mirror still renders here with no SSH hop. When
+ * no peer answered for that id, the shim is kept: with no fleet evidence, a
+ * transcript-less self-attributed row is indistinguishable from a session THIS box
+ * just started, and dropping it would re-break the cold-index lookup RUSH-2682
+ * fixed.
+ */
+export declare function preferOwnerAttribution(localMatches: SessionMeta[], remoteSessions: SessionMeta[], self: string): SessionMeta[];
+/** Injectable dependencies for the live-registry cold-miss fallback (RUSH-2682)
+ * and the fleet-attribution reconciliation (PHNX-3890). */
 export type LiveMetadataDeps = {
     loadActive?: typeof loadLocalActiveSessions;
+    /** The fleet-active snapshot rows used to attribute a self-defaulted launcher
+     * shim to its true execution host. Defaults to the cached fleet snapshot; the
+     * cache is warmed by any fleet-wide `agents sessions --active`. */
+    loadFleetActive?: () => ActiveSession[];
 };
 /**
  * Local metadata candidates for a selector: the indexed SQLite rows, plus — when