@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/commands/auth-mint.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { readStdinSync, runOrDie } from '../lib/format.js';
+import { isInteractiveTerminal } from './utils.js';
+import { getMintFlow, listMintableHarnesses, mintAndSeed, } from '../lib/auth-mint.js';
+function collect(value, previous) {
+    return [...previous, value];
+}
+function printResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            harness: result.harness,
+            account: result.account,
+            email: result.email,
+            authBundleKey: result.authBundleKey,
+            rotated: result.rotated,
+            fleet: result.fleet,
+        }, null, 2));
+        return;
+    }
+    const verb = result.rotated ? 'Rotated' : 'Minted';
+    console.log(chalk.green(`${verb} ${result.harness} setup-token for ${result.email} into account '${result.account}' and reserved auth bundle key ${result.authBundleKey}.`));
+    console.log(chalk.gray('The token is never printed. Native OAuth was not copied.'));
+    console.log(chalk.gray(`Run: agents run ${result.harness} --account ${result.account}`));
+    if (result.fleet.length) {
+        for (const row of result.fleet) {
+            console.log(chalk.green(`  synced ${row.device} (${row.message})`));
+        }
+    }
+}
+export function registerMintCommand(parent, testHooks) {
+    const mint = parent
+        .command('mint <harness>')
+        .description('Mint a long-lived setup-token and seed it as a named account')
+        .option('--account <name-or-email>', 'Named account to create/rotate, or the account email')
+        .option('--email <email>', 'Email that keys the reserved auth bundle when --account is a name')
+        .option('--token-stdin', 'Seed an already-minted token from stdin (skip the PTY drive)')
+        .option('--code <code>', 'Authorization code to paste into the setup-token prompt')
+        .option('--no-open', 'Print the authorize URL instead of opening a browser')
+        .option('--fleet', 'Sync the minted account and reserved auth bundle to every other registered device')
+        .option('--device <name>', 'Sync to this device (repeatable)', collect, [])
+        .option('--json', 'Machine-readable result (never includes the token)')
+        .action((harness, o, command) => {
+        const json = !!o.json || !!command.optsWithGlobals().json;
+        return runOrDie(async () => {
+            getMintFlow(harness);
+            let token;
+            if (o.tokenStdin) {
+                token = readStdinSync();
+                if (!token)
+                    throw new Error('No value received on stdin. Pass the setup-token on stdin with --token-stdin.');
+            }
+            else if (!isInteractiveTerminal() && !o.code) {
+                throw new Error(`Minting ${harness} interactively needs a TTY (or --token-stdin / --code). Supported harnesses: ${listMintableHarnesses().join(', ')}.`);
+            }
+            const result = await mintAndSeed({
+                harness,
+                account: o.account,
+                email: o.email,
+                token,
+                code: o.code,
+                open: o.open,
+                fleet: o.fleet,
+                devices: o.device,
+                json,
+                hooks: {
+                    ...testHooks,
+                    ...(o.tokenStdin || o.code || !isInteractiveTerminal()
+                        ? {}
+                        : {
+                            readCode: async () => {
+                                const { input } = await import('@inquirer/prompts');
+                                return input({ message: 'Paste the authorization code from the browser' });
+                            },
+                        }),
+                },
+            });
+            printResult(result, json);
+        }, { json });
+    });
+    setHelpSections(mint, {
+        examples: `agents accounts mint claude
+agents accounts mint claude --account ada@example.com
+agents accounts mint claude --account work --email ada@example.com
+agents accounts mint claude --token-stdin < token.txt
+agents accounts mint claude --code AUTHCODE --json
+agents accounts mint claude --fleet
+agents auth mint claude --account ada@example.com --json`,
+        notes: `Claude is the only harness with an interactive long-lived setup-token (\`claude setup-token\`, ~1 year, shareable across machines). The command drives that flow in a PTY, opens the authorize URL, captures a well-formed sk-ant-oat01- token (refusing the #1767 TTY-banner capture), and seeds:
+  1. a named provider account (policy never) for \`agents run --account\` / \`agents accounts sync\`
+  2. the reserved FILE-BASED auth bundle keyed per email, which usage/probe reads
+Native rotating OAuth is never copied. Other harnesses fail loud: device-code login is \`agents fleet login\`; API keys are \`agents accounts add\`.
+Already have a token? \`--token-stdin\` skips the browser dance. \`agents auth mint\` is the same command as \`agents accounts mint\`.`,
+    });
+    return mint;
+}

package/dist/commands/auth.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { PhoenixApiError, clearSession, createSpace, createSpaceInvite, fetchWhoAmI, listSpaceMembers, listSpaces, pollDeviceToken, readSession, removeSpaceMember, resolveMemberFromList, resolveSpaceFromList, slugify, startDeviceAuthorization, updateSpaceMemberRole, writeSession, } from '../lib/identity/index.js';
 import { setHelpSections } from '../lib/help.js';
 import { runOrDie } from '../lib/format.js';
+import { registerMintCommand } from './auth-mint.js';
 /**
  * `agents auth` — sign in to Phoenix ID, the account layer behind team spaces.
  * Signing in is optional: every local feature works with no account. Everything
@@ -95,13 +96,15 @@ export function registerAuthCommand(program) {
     setHelpSections(auth, {
         examples: `agents auth login                         # device-code sign-in via your browser
 agents auth whoami                        # who this machine is signed in as
+agents auth mint claude                   # mint a Claude setup-token into a named account
 agents auth space create "Design Team"    # start a space
 agents auth space invite ada@example.com  # add a teammate
 agents auth logout                        # clear this machine only`,
         notes: `Signing in is optional — every local feature works with no account; team spaces are what it unlocks.
 Sign-in is Google-only and opens a Phoenix-branded page; the CLI never sees a password.
 The session lives in this machine's agents state dir, so logging out here signs out nothing else.
-Point at a different backend with PHOENIX_ID_BASE (defaults to the production service).`,
+Point at a different backend with PHOENIX_ID_BASE (defaults to the production service).
+\`agents auth mint\` is the harness setup-token mint (same command as \`agents accounts mint\`); it does not sign you into Phoenix ID.`,
     });
     auth
         .command('login')
@@ -115,6 +118,7 @@ Point at a different backend with PHOENIX_ID_BASE (defaults to the production se
         const json = !!o.json || !!command.optsWithGlobals().json;
         return runOrDie(() => whoami(json), { json });
     });
+    registerMintCommand(auth);
     auth
         .command('logout')
         .description("Clear this machine's session (no other device is affected)")

package/dist/commands/browser.js

@@ -1308,7 +1308,7 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('remote-control [state]')
-        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device`. " +
+        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device` or `agents ssh …` (`agents browser` / `ag browser` / standalone `browser`). " +
         '`on`/`off` to set (device-local, never synced); no argument prints the current value. Default off.')
         .option('--json', 'Output as JSON')
         .action((state, opts) => {

package/dist/commands/cost.js

@@ -21,8 +21,14 @@ Examples:
 
 Cost is computed offline from a versioned per-model price table (${PRICING_VERSION}).
 `)
-        .action(async (options) => {
-        await costAction(options);
+        // Read opts via optsWithGlobals(): `--json`/`--since`/`--by` collide by name
+        // with the `insights` parent's own options, so commander binds them to the
+        // parent at parse time and the leaf's plain opts() never sees them. Merging
+        // ancestor opts is what the sibling `insights mix` recipes already do
+        // (mix-commands.ts) — without it every flag on this command is silently
+        // dropped (e.g. `agents insights cost --json` printed the human table).
+        .action(async (_options, command) => {
+        await costAction(command.optsWithGlobals());
     });
 }
 /** Map the --by flag to a rollup group, rejecting unknown values. */

package/dist/commands/daemon.js

@@ -886,7 +886,7 @@ export function registerDaemonCommand(program) {
       always. Use 'agents routines stats' for per-routine failure detail.
 
       'disable' is a persisted kill switch: it stops routines/add,
-      routines/start, routines/catchup, and webhook triggers from auto-starting
+      routines/start, routines/catchup, monitors/add, and webhook triggers from auto-starting
       the daemon (daemon.enabled: false in ~/.agents/devices/<host>/agents.yaml).
       'agents daemon start' still starts it explicitly, same as
       'systemctl start' on a disabled unit.
@@ -974,7 +974,7 @@ export function registerDaemonCommand(program) {
         .description('Clear the daemon.enabled kill switch. Does not start the daemon by itself.')
         .action(() => {
         setConfigValue('daemon.enabled', true);
-        console.log(chalk.green('daemon.enabled: true') + chalk.gray(' — auto-start surfaces (routines add/start/catchup, webhooks) may bring the daemon up again'));
+        console.log(chalk.green('daemon.enabled: true') + chalk.gray(' — auto-start surfaces (routines add/start/catchup, monitors add, webhooks) may bring the daemon up again'));
     });
     cmd.command('disable')
         .description('Persist daemon.enabled: false — nothing auto-starts the daemon until re-enabled. Does not stop a running daemon.')

package/dist/commands/doctor.js

@@ -24,6 +24,7 @@ import { resolveAgentTargets, AgentSpecError } from '../lib/agent-spec/index.js'
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings, repairManagedHookRuntimeArtifacts } from '../lib/hooks/install.js';
+import { inspectReservedAuthBundle } from '../lib/secrets/bundles.js';
 import { isVersionIsolated } from '../lib/installations/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
 import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
@@ -118,13 +119,15 @@ function printWrappedLine(prefix, text) {
  * file and line. Run `agents doctor` on that box for the specifics — the
  * message says so.
  */
-const REMOTE_FORWARDED_KINDS = ['rc-secret-export', 'env-secret-export', 'ssh-key-enrollment'];
+const REMOTE_FORWARDED_KINDS = ['rc-secret-export', 'env-secret-export', 'auth-bundle-wrong-backend', 'ssh-key-enrollment'];
 /** Canonical, locally-authored text for a forwarded kind. Never the remote's. */
 const REMOTE_SECRET_MESSAGE = {
     'rc-secret-export': 'a credential-shaped export was found in this box\'s shell rc files'
         + ' — run `agents doctor` there for the file and line',
     'env-secret-export': 'AGENTS_SECRETS_PASSPHRASE is set in this box\'s process environment'
         + ' — run `agents doctor` there for detail',
+    'auth-bundle-wrong-backend': "reserved secrets bundle 'auth' exists but is not file-backed"
+        + ' — run `agents doctor` there to recreate it',
     'ssh-key-enrollment': 'Windows OpenSSH key enrollment is invalid'
         + ' — run `agents doctor` on this box for the effective path or ACL failure',
 };
@@ -442,6 +445,7 @@ async function runDevicesDoctor(opts) {
                 hostClis: toHostCliInput(listCliStatus(cwd)),
                 rcSecrets: scanUserRcFiles(),
                 masterPassphraseInEnv: masterPassphraseInEnv(),
+                authBundleWrongBackend: !inspectReservedAuthBundle().ok,
                 execPolicy: process.platform === 'win32'
                     ? { platform: process.platform, policy: getEffectiveExecutionPolicy() }
                     : undefined,
@@ -1680,6 +1684,7 @@ export function registerDoctorCommand(program) {
                 hostClis: toHostCliInput(hostClis),
                 rcSecrets: scanUserRcFiles(),
                 masterPassphraseInEnv: masterPassphraseInEnv(),
+                authBundleWrongBackend: !inspectReservedAuthBundle().ok,
                 // getEffectiveExecutionPolicy spawns powershell — a doomed process on
                 // POSIX, where the advisory never applies. Probe only on Windows.
                 execPolicy: process.platform === 'win32'

package/dist/commands/exec.js

@@ -654,13 +654,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         Interactive plan (omit the prompt) works everywhere it is listed.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
-        pinned     use the workspace/global pinned version
+        pinned     use the workspace/global pinned version; if that version is logged out on this device, pick a signed-in sibling instead of dying (an explicit @version pin is unchanged)
         available  use pinned if it can run right now; otherwise switch to another signed-in version
         balanced   distribute load across healthy accounts by remaining capacity (default)
         A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
-        Zero healthy accounts under balanced/available exits nonzero naming each
-        excluded account and the earliest window reset — use --strategy pinned to force.
+        Zero healthy accounts under balanced/available (or a logged-out pinned default with no signed-in sibling) exits nonzero naming each
+        excluded account and the earliest window reset — use --strategy pinned to force a rate-limited default; a logged-out default is never forced.
 
       'auto' harness (agents run auto): picks the host (14d usage affinity,
       unless --device is given), the harness (installed CLIs weighted by
@@ -1569,15 +1569,19 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             });
                         }
                     }
-                    // A network drop kills the local ssh client (exit 255) but the remote
-                    // agent survives in its detached tmux session. With a known session id
-                    // (Claude's forced id, a resumed run, or a non-Claude id we just
-                    // resolved from the remote hook record) and a tmux-hosted run,
-                    // re-attach the live pane automatically instead of exiting — the user
-                    // never has to notice the drop and `agents sessions focus` by hand.
-                    // `raw` runs aren't tmux wrapped, so there is nothing to reconnect to.
-                    // For `run auto` prefer the join-resolved id (the harness the remote
-                    // ACTUALLY picked) over the explicit --session-id only claude adopts.
+                    // A network drop kills the local ssh client (exit 255). What the
+                    // remote agent does next depends on the peer's tmux.enabled
+                    // (PHNX-3316): wrapped, it survives in its detached pane and the
+                    // reconnect rejoins it; bare (the default), the drop SIGHUPs it and
+                    // the reconnect resumes the session in place from disk. Either way,
+                    // with a known session id (Claude's forced id, a resumed run, or a
+                    // non-Claude id we just resolved from the remote hook record) we
+                    // reconnect automatically instead of exiting — the user never has
+                    // to notice the drop and `agents sessions focus` by hand.
+                    // `raw` runs opted out of all of this, so there is nothing to
+                    // reconnect to. For `run auto` prefer the join-resolved id (the
+                    // harness the remote ACTUALLY picked) over the explicit
+                    // --session-id only claude adopts.
                     const { pickReconnectTarget, reconnectInteractiveSession, afterInteractiveRemoteExit, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
                     const reconnectTarget = pickReconnectTarget({
                         agent: runAgent,
@@ -1814,6 +1818,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         let accountConfigVersion;
         let profileProvider;
         let fromProfile = false;
+        let profileName;
         let profileFallbackModel;
         let workflowModel;
         // WORKFLOW.md capability scoping, translated to Claude headless flags below.
@@ -1897,6 +1902,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 profileProvider = readProfile(rawAgent).provider;
                 profileFallbackModel = resolved.fallbackModel;
                 fromProfile = true;
+                profileName = resolved.profileName;
                 process.stderr.write(chalk.gray(`Resolved custom harness '${resolved.profileName}' -> ${agent}${version ? `@${version}` : ''}\n`));
                 if (resolved.tierNote) {
                     process.stderr.write(chalk.gray(`[agents] ${resolved.tierNote}\n`));
@@ -2362,13 +2368,15 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             process.exit(1);
         }
         const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
-        // Strategy only applies to bare agent invocations. Explicit @version and
-        // profiles already define their execution target. A --fallback chain does
-        // NOT pin the primary: it only names where to cascade on a rate limit, so
-        // the bare primary still resolves through the strategy — otherwise every
+        // Strategy applies to bare (unpinned) invocations. Explicit @version and
+        // profiles already name the target. A --fallback chain does NOT pin the
+        // primary: it only names where to cascade on a rate limit, so the bare
+        // primary still resolves through the strategy — otherwise every
         // `agents run claude --fallback codex` run lands on the pinned default
         // account and account rotation silently stops (the gh-monitor heal bug).
-        if (!accountPickerRequested && !configuredAccount && (strategy !== 'pinned' || options.balanced || explicitStrategy)) {
+        // `pinned` still resolves so a logged-out default can yield to a signed-in
+        // sibling on this device (PHNX-2685); an explicit @version pin is unchanged.
+        if (!accountPickerRequested && !configuredAccount && (!version || strategy !== 'pinned' || options.balanced || explicitStrategy)) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -2745,6 +2753,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
         }
         const execOptions = {
             agent,
+            harnessName: profileName,
             version,
             configVersion: accountConfigVersion,
             prompt,

package/dist/commands/fleet-capture.js

@@ -71,6 +71,13 @@ async function runCapture(opts) {
         secretsBundles: listBundles().map((b) => b.name),
         routines: listJobs().map((j) => j.name),
     };
+    // Discovery decisions and dismissals are device-scoped now (PHNX-3315): they
+    // live in each box's device doc and sync via the repo, so `capture` must NOT
+    // hoist the cross-box union back into the shared `agents.yaml` `fleet:` block
+    // (that would recreate the N-boxes-rewrite-one-map conflict Task A removed and
+    // re-arm the fold-then-delete migration on every capture). `meta.fleet` carries
+    // only the roster/defaults; any lingering central-legacy discovery/ignored is
+    // carried forward verbatim and drained by the migration.
     const next = captureFleet(meta.fleet, inputs);
     if (opts.dryRun) {
         console.log(chalk.gray('# agents.yaml fleet: block (dry run — not written)'));

package/dist/commands/focus.d.ts

@@ -110,6 +110,7 @@ export declare function dedupeSessionsByLogicalId(rows: SessionMeta[], self?: st
  * peer-owned session without `--device`, matching `resume`/`preview`.
  */
 export declare function focusTargetForResolved(poolMatch: SessionMeta | undefined, resolved: SessionMeta): SessionMeta;
+export declare function focusResolvedSession(meta: SessionMeta, liveById: Map<string, ActiveSession>, self: string, fallback: UnreachableFallback, attachOnly: boolean, reconnectReattach?: boolean): Promise<void>;
 /** Focus one row selected by the shared session browser through the same
  * attach/recover decision as `agents sessions focus <id>`. */
 export declare function focusSelectedSession(meta: SessionMeta, active: ActiveSession | undefined, self: string): Promise<void>;

package/dist/commands/focus.js

@@ -31,6 +31,7 @@ import { multiItemPicker } from '../lib/picker.js';
 import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { shellQuote, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
+import { addressabilityRecoveryHint } from '../lib/terminal/resolve.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 const INHERITED_FOCUS_OPTIONS = [
@@ -493,10 +494,10 @@ async function pickFocusCandidates(sessions, liveById, initialSearch) {
 export function focusTargetForResolved(poolMatch, resolved) {
     return poolMatch ?? resolved;
 }
-async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
+export async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
     const active = liveById.get(meta.id);
     if (active && isAttachableLiveSession(active)) {
-        await jumpTo(active, self, fallback);
+        await jumpTo(active, self, fallback, meta.id);
         return;
     }
     if (attachOnly) {
@@ -534,6 +535,7 @@ export async function focusSelectedSession(meta, active, self) {
             return;
         }
         console.log(chalk.yellow('This live session has no session id or living attach rail to focus.'));
+        console.log(chalk.gray(addressabilityRecoveryHint(active, meta.id)));
         process.exitCode = 1;
         return;
     }

package/dist/commands/go.d.ts

@@ -104,9 +104,10 @@ export declare function describeWhere(s: ActiveSession, self: string): Where;
 /**
  * What to do when a session can't be *attached* (no tmux/Ghostty rail). `go`
  * refuses; `focus` opens a new tab and resumes. `remote` is the peer name when
- * the session lives on another machine, else undefined.
+ * the session lives on another machine, else undefined. `fallbackId` is the
+ * indexed session id when the live row has not registered one yet (PHNX-3356).
  */
-export type UnreachableFallback = (s: ActiveSession, remote: string | undefined) => void | Promise<void>;
+export type UnreachableFallback = (s: ActiveSession, remote: string | undefined, fallbackId?: string) => void | Promise<void>;
 export type AttachRailLiveness = {
     state: 'alive';
 } | {
@@ -121,5 +122,5 @@ export type AttachRailLiveness = {
 export declare function probeAttachRail(s: ActiveSession, self: string): Promise<AttachRailLiveness>;
 /** Strict attach-only fallback: no pane means no attach. Never open a shell or
  * start recovery, because both would violate the caller's no-fork intent. */
-export declare function refuseFallback(s: ActiveSession, remote: string | undefined): Promise<void>;
-export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback): Promise<void>;
+export declare function refuseFallback(s: ActiveSession, remote: string | undefined, fallbackId?: string): Promise<void>;
+export declare function jumpTo(s: ActiveSession, self: string, fallback?: UnreachableFallback, fallbackId?: string): Promise<void>;

package/dist/commands/go.js

@@ -34,6 +34,7 @@ import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { sshExec, sshStream, assertValidSshTarget, shellQuote, SSH_CONN_FAILURE_CODE } from '../lib/ssh-exec.js';
 import { connectionEndedNotice } from '../lib/hosts/reconnect.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
+import { addressabilityRecoveryHint } from '../lib/terminal/resolve.js';
 const execFileAsync = promisify(execFile);
 export function registerGoCommand(program) {
     program
@@ -311,17 +312,17 @@ export async function probeAttachRail(s, self) {
 }
 /** Strict attach-only fallback: no pane means no attach. Never open a shell or
  * start recovery, because both would violate the caller's no-fork intent. */
-export async function refuseFallback(s, remote) {
+export async function refuseFallback(s, remote, fallbackId) {
     if (remote) {
         console.log(chalk.yellow(`Can't attach ${shortId(s)} on ${remote} — it has no living tmux pane.`));
         process.exitCode = 1;
         return;
     }
     console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
-        chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+        chalk.gray(`\n${addressabilityRecoveryHint(s, fallbackId)}`));
     process.exitCode = 1;
 }
-export async function jumpTo(s, self, fallback = refuseFallback) {
+export async function jumpTo(s, self, fallback = refuseFallback, fallbackId) {
     const remote = sessionProcessHost(s, self);
     const mux = s.provenance?.mux;
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
@@ -329,7 +330,7 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
         if (mux?.kind === 'tmux' && mux.pane) {
             const liveness = await probeAttachRail(s, self);
             if (liveness.state !== 'alive') {
-                await fallback(s, remote);
+                await fallback(s, remote, fallbackId);
                 return;
             }
             assertValidSshTarget(remote);
@@ -348,14 +349,14 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
             process.exit(code);
         }
         // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
-        await fallback(s, remote);
+        await fallback(s, remote, fallbackId);
         return;
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
         const liveness = await probeAttachRail(s, self);
         if (liveness.state !== 'alive') {
-            await fallback(s, undefined);
+            await fallback(s, undefined, fallbackId);
             return;
         }
         const socket = mux.socket ?? getDefaultSocketPath();
@@ -402,7 +403,7 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
         return;
     }
     // Path D: no attach rail (headless / plain terminal) → hand off to the fallback.
-    await fallback(s, undefined);
+    await fallback(s, undefined, fallbackId);
 }
 /** Resolve a local tmux pane id to its session name + window index. */
 async function resolveLocalPane(socket, pane) {

package/dist/commands/insights.js

@@ -246,6 +246,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
     for (const g of groups)
         mergeFacets(all, g.facets);
     renderCounts('Top tools', topEntries(all.toolCounts, 8), out);
+    // The `Bash`/`exec` bar above says a shell ran; this says WHICH binary — git, gh,
+    // agents, find, ssh→git — so the tool mix is actionable rather than one lump.
+    renderCounts('Shell commands', topEntries(all.bashCommands, 12), out);
     renderCounts('Languages', topEntries(all.languages, 6), out);
     renderCounts('Models', topEntries(all.models, 6), out);
     // Friction — the section that earns the command.
@@ -281,6 +284,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`    ${chalk.gray('·')} ${padToWidth(e.name, 16)} ${chalk.gray(String(e.count))}`);
     }
     renderCounts('Friction / thrash', topEntries(all.frictionSignals, 10), out);
+    // Which shell binary was failing when a `failed tool loop: Bash` fired — makes the
+    // loop attributable (`git reconcile`, `find`, `gh`) instead of a bare tool name.
+    renderCounts('Shell command failures', topEntries(all.bashCommandFailures, 8), out);
     renderCounts('Dissatisfaction / corrections', topEntries(all.correctionSignals, 10), out);
     renderCounts('Automatable repeats', topEntries(all.automationSignals, 10), out);
     renderCounts('Harness split', harnesses, out);
@@ -297,6 +303,9 @@ function renderReport(groups, dim, meta, actions, harnesses) {
             out.push(`  ${padToWidth(action.priority, 7)} ${padToWidth(action.category, 11)} ` +
                 `${String(action.evidenceCount).padStart(8)}  ${padToWidth(action.sampleSessionIds.join(', '), 25)} ${action.action}`);
         }
+        // This report is aggregate by contract (SES-IF-4c); a sample id above drills into
+        // one session's timeline via the per-session surface, not a single-session mode here.
+        out.push(chalk.gray('  drill into a sample session:  agents sessions trace <id>'));
     }
     // Output
     out.push('');