@phnx-labs/agents-cli 1.22.56 → 1.22.57

package/dist/lib/analytics/mix-commands.js

@@ -4,11 +4,13 @@
  * These used to live as the top-level `agents trends` tree. That name was a
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
- * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
+ * usage.db) still exists — it is now `agents insights mix`. Latency stays on
+ * `agents insights perf`; quota on `agents view`.
  *
- * Former top-level `agents trends` is gone. The nested spelling
- * `agents insights trends` is an alias of `agents insights mix`.
+ * One surface, not five: the board is `agents insights mix`, one section is
+ * `agents insights mix <recipe>`, and `--list` names the recipe ids. The former
+ * per-recipe shortcut commands (`harness-mix`, `model-mix`, …), the `recipes`
+ * lister, and the `trends` alias were removed — `mix` already did all three.
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../help.js';
@@ -60,23 +62,53 @@ export function renderMixDashboard(days, asJson, bannerLabel = 'agents insights
  *
  * Layout:
  *   <parent> mix                 multi-recipe board
- *   <parent> trends              alias of mix (former top-level `agents trends`)
- *   <parent> recipes             list recipe ids
+ *   <parent> mix <recipe>        one baked recipe (harness-mix, model-mix, …)
+ *   <parent> mix --list          list recipe ids
  *   <parent> query               raw usage.db rows
- *   <parent> harness-mix|…       one baked recipe
  */
 export function registerMixCommands(parent) {
     const banner = 'agents insights mix';
     const mix = parent
-        .command('mix')
-        .description('Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db)')
+        .command('mix [recipe]')
+        .description('Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db). Bare shows the board; pass a recipe id for one section.')
         .option('--days <n>', 'Days of history to include', '7')
+        .option('--list', 'List baked recipe ids and exit')
         .option('--json', 'Emit JSON instead of tables')
-        .action(function summary() {
+        .action(function summary(recipe) {
         // optsWithGlobals(): --json collides by name with the `insights` parent, so
         // commander binds it to the parent and this.opts() never sees it. Merging
-        // ancestor opts is what the per-recipe leaves below already do.
+        // ancestor opts is what the per-recipe path below already does.
         const o = this.optsWithGlobals();
+        if (o.list) {
+            const list = listRecipes();
+            if (o.json) {
+                console.log(JSON.stringify(list, null, 2));
+                return;
+            }
+            for (const r of list) {
+                console.log(`${r.id.padEnd(22)} ${r.store.padEnd(10)} ${r.title}`);
+            }
+            return;
+        }
+        if (recipe) {
+            if (!RECIPE_IDS.includes(recipe)) {
+                console.error(`Unknown recipe '${recipe}'. Known: ${RECIPE_IDS.join(', ')} (or 'agents insights mix --list').`);
+                process.exitCode = 1;
+                return;
+            }
+            const win = analyticsWindow(parseMixDays(o.days));
+            const section = runRecipe(recipe, win);
+            if (o.json) {
+                console.log(JSON.stringify({ window: win, section }, null, 2));
+                return;
+            }
+            if (section.empty) {
+                console.log(chalk.gray(`No data for recipe '${recipe}' in the last ${win.days} days.`));
+                return;
+            }
+            printMixSection(section);
+            return;
+        }
         renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
     });
     setHelpSections(mix, {
@@ -88,36 +120,23 @@ export function registerMixCommands(parent) {
       agents insights mix --days 30
 
       # One recipe as JSON
-      agents insights harness-mix --json
+      agents insights mix harness-mix --json
+
+      # List baked recipe ids
+      agents insights mix --list
 
       # Raw usage events
       agents insights query --kind secret --days 7
-
-      # List baked recipe ids
-      agents insights recipes
     `,
         notes: `
       Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
-      Empty recipes are skipped on the default mix board.
+      Empty recipes are skipped on the default mix board. Pass one recipe id
+      (\`agents insights mix harness-mix\`) for just that section; \`--list\` names them.
       This is the cheap counter path. Behavioural report (transcript content, account split)
-      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents view\`.
+      is bare \`agents insights\`. Latency is \`agents insights perf\`; quota is \`agents view\`.
       Skill/slash-command popularity is \`agents sessions stats\`.
     `,
     });
-    parent.command('recipes')
-        .description('List baked mix-recipe ids')
-        .option('--json', 'Emit JSON')
-        .action(function recipes() {
-        const o = this.optsWithGlobals();
-        const list = listRecipes();
-        if (o.json) {
-            console.log(JSON.stringify(list, null, 2));
-            return;
-        }
-        for (const r of list) {
-            console.log(`${r.id.padEnd(22)} ${r.store.padEnd(10)} ${r.title}`);
-        }
-    });
     parent.command('query')
         .description('Raw usage-event query (usage.db)')
         .option('--kind <kind>', `One of: ${USAGE_KINDS.join(', ')}`)
@@ -164,46 +183,4 @@ export function registerMixCommands(parent) {
             })),
         });
     });
-    for (const id of RECIPE_IDS) {
-        parent.command(id)
-            .description(`Mix recipe: ${id}`)
-            .option('--days <n>', 'Days of history', '7')
-            .option('--json', 'Emit JSON')
-            .action(function recipeAction() {
-            // optsWithGlobals() merges the `insights` parent opts, so the name-colliding
-            // --json/--since reach this leaf (see the sibling commands above).
-            const o = this.optsWithGlobals();
-            const win = analyticsWindow(parseMixDays(o.days));
-            const section = runRecipe(id, win);
-            if (o.json) {
-                console.log(JSON.stringify({ window: win, section }, null, 2));
-                return;
-            }
-            if (section.empty) {
-                console.log(chalk.gray(`No data for recipe '${id}' in the last ${win.days} days.`));
-                return;
-            }
-            printMixSection(section);
-        });
-    }
-    // Nested home for the former top-level `agents trends` spelling.
-    const trends = parent
-        .command('trends')
-        .description('Alias of `mix` — former top-level `agents trends`')
-        .option('--days <n>', 'Days of history to include', '7')
-        .option('--json', 'Emit JSON instead of tables')
-        .action(function summary() {
-        const o = this.optsWithGlobals();
-        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
-    });
-    setHelpSections(trends, {
-        examples: `
-      agents insights trends
-      agents insights mix
-    `,
-        notes: `
-      \`agents insights trends\` is the nested spelling of the former top-level
-      \`agents trends\`. Prefer \`agents insights mix\`.
-    `,
-    });
 }

package/dist/lib/daemon/daemon.js

@@ -41,6 +41,7 @@ import { DeviceProbeService } from './device-probe-service.js';
 import { SelfHealService } from './self-heal-service.js';
 import { KeychainReapService } from './keychain-reap-service.js';
 import { AuthSyncService } from './auth-sync-service.js';
+import { UsageSyncService } from './usage-sync-service.js';
 import { StateDirCheckService } from './state-dir-check-service.js';
 import { SessionStateService } from './session-state-service.js';
 import { WebhookReceiverService } from './webhook-receiver-service.js';
@@ -858,6 +859,10 @@ export async function runDaemon() {
         supervisor.register(new AuthSyncService());
     else
         log('INFO', 'Auth-sync service disabled');
+    if (isEnabled('usage-sync'))
+        supervisor.register(new UsageSyncService());
+    else
+        log('INFO', 'Usage-sync service disabled');
     if (isEnabled('webhook-receiver'))
         supervisor.register(new WebhookReceiverService());
     else

package/dist/lib/daemon/runner.js

@@ -39,7 +39,7 @@ import { resolveClaudeSetupToken } from '../claude-account-token.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from '../accounting/rotate.js';
 import { readAuthHealth, isDeadVerdict } from '../auth-health.js';
 import { machineId } from '../machine-id.js';
-import { selfConfiguredDeviceRole } from '../device-config.js';
+import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../device-config.js';
 import { isSelfUpdatingAgent, ROUTINE_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
 import { isCustomHarnessName, readProfile } from '../profiles.js';
 export class RoutineAlreadyRunningError extends Error {
@@ -1121,13 +1121,14 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
     const setupToken = agent === 'claude' && version
         ? resolveClaudeSetupToken(getVersionHomePath('claude', version))
         : null;
-    // A `personal` device (the user's own interactive box) uses the per-version
-    // login for EVERY run, routines included — the setup-token is a worker-only
-    // credential (RUSH-2395, mirrors the claude adapter's personal-device branch).
-    // On a personal box, only strip an inherited copy of the account's OWN
-    // setup-token by value so a leaked ambient value can't override the login; a
-    // token the user set deliberately is a different string and survives.
-    if (selfConfiguredDeviceRole() === 'personal') {
+    // A headed device (personal or desktop — the user's own interactive box or a
+    // headed always-on box) uses the per-version login for EVERY run, routines
+    // included — the setup-token is a worker-only credential (RUSH-2395, mirrors
+    // the claude adapter's headed-device branch). On a headed box, only strip an
+    // inherited copy of the account's OWN setup-token by value so a leaked ambient
+    // value can't override the login; a token the user set deliberately is a
+    // different string and survives.
+    if (isHeadedDeviceRole(selfConfiguredDeviceRole())) {
         if (setupToken && out.CLAUDE_CODE_OAUTH_TOKEN === setupToken)
             delete out.CLAUDE_CODE_OAUTH_TOKEN;
     }

package/dist/lib/daemon/usage-sync-service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ *
+ * On a headed box (personal/desktop) each tick pushes the local identity-keyed
+ * Claude usage rows to worker peers that cannot read usage themselves. A no-op on
+ * a worker/unmarked box or when the local cache is empty — the driver
+ * ({@link syncFleetUsageSnapshots}) gates on the self role, so this service is
+ * safe to register everywhere. Single-executor per destination: each daemon only
+ * writes the DESTINATION's own cache, and the merge is newest-wins + idempotent.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class UsageSyncService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs = 90000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/usage-sync-service.js

@@ -0,0 +1,36 @@
+/**
+ * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ *
+ * On a headed box (personal/desktop) each tick pushes the local identity-keyed
+ * Claude usage rows to worker peers that cannot read usage themselves. A no-op on
+ * a worker/unmarked box or when the local cache is empty — the driver
+ * ({@link syncFleetUsageSnapshots}) gates on the self role, so this service is
+ * safe to register everywhere. Single-executor per destination: each daemon only
+ * writes the DESTINATION's own cache, and the merge is newest-wins + idempotent.
+ */
+import { BasePeriodicService } from './service.js';
+const USAGE_SYNC_TICK_MS = 15 * 60_000;
+const USAGE_SYNC_DEADLINE_MS = 2 * 60_000;
+const USAGE_SYNC_KICKOFF_MS = 90_000;
+export class UsageSyncService extends BasePeriodicService {
+    id = 'usage-sync';
+    intervalMs = USAGE_SYNC_TICK_MS;
+    deadlineMs = USAGE_SYNC_DEADLINE_MS;
+    startupDelayMs = USAGE_SYNC_KICKOFF_MS;
+    async onStart(_ctx) {
+        // No connections to open — each tick re-reads the local cache + registry.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup.
+    }
+    async onTick(ctx) {
+        const { syncFleetUsageSnapshots } = await import('../accounting/usage-sync.js');
+        const result = syncFleetUsageSnapshots();
+        if (result.pushed.length > 0) {
+            ctx.log('INFO', `usage-sync: pushed usage to ${result.pushed.join(', ')}`);
+        }
+        for (const err of result.errors) {
+            ctx.log('WARN', `usage-sync: ${err.device}: ${err.message}`);
+        }
+    }
+}

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -97,6 +97,11 @@ export const DAEMON_SERVICES = [
         title: 'Auth bundle sync',
         description: 'Pushes the reserved file-backed auth bundle (setup-tokens) to pinned fleet devices that do not yet have it.',
     },
+    {
+        id: 'usage-sync',
+        title: 'Usage snapshot sync',
+        description: 'From a personal/desktop box, pushes the per-account usage snapshot to worker peers that cannot read it themselves.',
+    },
 ];
 /** Stable order of service IDs. */
 export const DAEMON_SERVICE_IDS = DAEMON_SERVICES.map((s) => s.id);

package/dist/lib/device-config.d.ts

@@ -87,7 +87,7 @@ export interface ConfigTarget {
     fleet?: boolean;
 }
 /** Roles a device can be marked with — see the `role` key below. */
-declare const DEVICE_ROLES: readonly ["worker", "personal"];
+declare const DEVICE_ROLES: readonly ["worker", "personal", "desktop"];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
@@ -150,13 +150,24 @@ export declare function configuredDeviceRole(name: string): ConfiguredDeviceRole
  * it was never marked. Keyed off {@link machineId} (overridable via
  * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
  *
- * The auth strategy reads this: a `personal` device (the user's own interactive
- * box) holds a real per-version login and MUST authenticate from it for EVERY
- * run, interactive or headless; only a `worker` uses the file-based setup-token
- * (RUSH-2395). `undefined` is treated as non-personal (worker-equivalent) by
- * that gate — an unmarked box has no login to defer to.
+ * The auth strategy reads this: a headed device (`personal` or `desktop`, see
+ * {@link isHeadedDeviceRole}) holds a real per-version login and MUST
+ * authenticate from it for EVERY run, interactive or headless; only a `worker`
+ * uses the file-based setup-token (RUSH-2395). `undefined` is treated as
+ * non-headed (worker-equivalent) by that gate — an unmarked box has no login to
+ * defer to.
  */
 export declare function selfConfiguredDeviceRole(): ConfiguredDeviceRole | undefined;
+/**
+ * A "headed" device — one with an interactive desktop login, so it authenticates
+ * from its own per-version Claude login (which carries the `user:profile` scope
+ * the usage endpoint needs) rather than the headless file setup-token. Both
+ * `personal` (the box you sit at) and `desktop` (a headed always-on box like a
+ * Mac mini) qualify; a `worker` and an unmarked box do NOT. This is the single
+ * predicate the auth-bucket sites read, so `personal` and `desktop` never drift
+ * apart (claude adapter, routine spawn env, `agents view` usage login).
+ */
+export declare function isHeadedDeviceRole(role: ConfiguredDeviceRole | undefined): boolean;
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export declare function setConfiguredDeviceRole(name: string, role: ConfiguredDeviceRole | undefined): void;
 /**

package/dist/lib/device-config.js

@@ -41,7 +41,7 @@ import { migrateDeviceConfigStores } from './devices/config-migration.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
 /** Roles a device can be marked with — see the `role` key below. */
-const DEVICE_ROLES = ['worker', 'personal'];
+const DEVICE_ROLES = ['worker', 'personal', 'desktop'];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 const AUTO_POOL_MODES = ['workers', 'all'];
 export const CONFIG_KEYS = [
@@ -67,8 +67,8 @@ export const CONFIG_KEYS = [
         scope: 'user',
         type: 'string',
         description: "Which devices automatic placement (`--device auto`) may pick: 'workers' (default — only devices marked role=worker, " +
-            "once at least one is marked) or 'all' (every online device, ignoring worker marks). A device marked personal is " +
-            'never picked automatically under either mode.',
+            "once at least one is marked) or 'all' (every online device, ignoring worker marks). A device marked personal or " +
+            'desktop is never picked automatically under either mode.',
         defaultValue: 'workers',
         validate: (v) => AUTO_POOL_MODES.includes(v)
             ? null
@@ -279,9 +279,10 @@ export const CONFIG_KEYS = [
         scope: 'device',
         visibility: 'shared',
         type: 'string',
-        description: "What this device is for, fleet-wide: 'worker' (a box agents run on) or 'personal' (a machine you sit at — never " +
-            'picked automatically). Marking ANY device worker turns automatic placement into an allowlist: `--device auto` then ' +
-            'picks only from the marked workers.',
+        description: "What this device is for, fleet-wide: 'worker' (a box agents run on), 'personal' (a machine you sit at — your " +
+            "interactive seat), or 'desktop' (a headed always-on box like a Mac mini — the release/credential home). Personal " +
+            'and desktop are never picked automatically. Marking ANY device worker turns automatic placement into an allowlist: ' +
+            '`--device auto` then picks only from the marked workers.',
         validate: (v) => DEVICE_ROLES.includes(v)
             ? null
             : `role must be one of ${DEVICE_ROLES.join(' | ')}.`,
@@ -630,15 +631,28 @@ export function configuredDeviceRole(name) {
  * it was never marked. Keyed off {@link machineId} (overridable via
  * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
  *
- * The auth strategy reads this: a `personal` device (the user's own interactive
- * box) holds a real per-version login and MUST authenticate from it for EVERY
- * run, interactive or headless; only a `worker` uses the file-based setup-token
- * (RUSH-2395). `undefined` is treated as non-personal (worker-equivalent) by
- * that gate — an unmarked box has no login to defer to.
+ * The auth strategy reads this: a headed device (`personal` or `desktop`, see
+ * {@link isHeadedDeviceRole}) holds a real per-version login and MUST
+ * authenticate from it for EVERY run, interactive or headless; only a `worker`
+ * uses the file-based setup-token (RUSH-2395). `undefined` is treated as
+ * non-headed (worker-equivalent) by that gate — an unmarked box has no login to
+ * defer to.
  */
 export function selfConfiguredDeviceRole() {
     return configuredDeviceRole(machineId());
 }
+/**
+ * A "headed" device — one with an interactive desktop login, so it authenticates
+ * from its own per-version Claude login (which carries the `user:profile` scope
+ * the usage endpoint needs) rather than the headless file setup-token. Both
+ * `personal` (the box you sit at) and `desktop` (a headed always-on box like a
+ * Mac mini) qualify; a `worker` and an unmarked box do NOT. This is the single
+ * predicate the auth-bucket sites read, so `personal` and `desktop` never drift
+ * apart (claude adapter, routine spawn env, `agents view` usage login).
+ */
+export function isHeadedDeviceRole(role) {
+    return role === 'personal' || role === 'desktop';
+}
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export function setConfiguredDeviceRole(name, role) {
     assertValidDeviceName(name);

package/dist/lib/devices/pool.d.ts

@@ -15,10 +15,11 @@
  * |---|---|
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
- * | marked `personal` | never, under either state |
+ * | marked `personal` / `desktop` | never, under either state |
  *
- * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
- * machine the user sits at is marked precisely so agents stay off it.
+ * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * excluded, because a box the user sits at (personal) or a headed always-on
+ * release/credential box (desktop) is marked precisely so agents stay off it.
  */
 import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 export interface AutoPoolOptions {

package/dist/lib/devices/pool.js

@@ -15,15 +15,23 @@
  * |---|---|
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
- * | marked `personal` | never, under either state |
+ * | marked `personal` / `desktop` | never, under either state |
  *
- * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
- * machine the user sits at is marked precisely so agents stay off it.
+ * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * excluded, because a box the user sits at (personal) or a headed always-on
+ * release/credential box (desktop) is marked precisely so agents stay off it.
  */
 import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';
-/** Roles that automatic placement never picks, whatever the pool mode. */
-const NEVER_AUTO = new Set(['personal']);
+/**
+ * Roles that automatic placement never picks, whatever the pool mode.
+ *
+ * `personal` (a box you sit at) and `desktop` (a headed always-on box — the
+ * release/credential home, e.g. a Mac mini) are both off-limits to `--device
+ * auto`: neither is headless fan-out capacity, and landing agent work on them
+ * is the outcome the mark exists to prevent. Only `worker` is auto-eligible.
+ */
+const NEVER_AUTO = new Set(['personal', 'desktop']);
 /**
  * Narrow a candidate host list to the devices automatic placement may pick.
  *

package/dist/lib/exec.d.ts

@@ -502,49 +502,10 @@ export type TmuxWrapDecision =
     kind: 'undurable';
 };
 /**
- * Decide whether to run an interactive agent INSIDE a detached tmux session on
- * the shared socket (then attach the current TTY) instead of a bare spawn.
- *
- * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
- * unique `%pane` handle so `agents sessions --active` can tell co-located
- * agents apart and `agents focus` re-attaches without forking, plus scrollback
- * and mouse at the operator's keyboard. Off means OFF, for local and remote
- * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
- * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
- * when one exists and resumes the harness session from disk when it does not.
- * The RUSH-3125 forced remote wrap conflated durability with that preference
- * and surprised every operator who had explicitly left tmux off.
- *
- * One case still wraps regardless: a followed remote run whose launcher has
- * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
- * the detached pane is the run's only interface, not an ergonomics choice.
- *
- * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
- * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
- * escape hatch that silently stopped applying over `--device` would be worse
- * than the bare run the user asked for.
- *
- * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
+ * Tmux is opt-in except when a TTY-less remote launch would otherwise have no
+ * interface. Explicit per-run opt-outs always win.
  */
 export declare function resolveTmuxWrap(ctx: TmuxWrapContext): TmuxWrapDecision;
-/**
- * Build the shell command that runs an agent inside a tmux pane with the exact
- * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
- * K=V … <agent> <args…>` so:
- *   - `env` materializes the full agent env INTO the pane, independent of the
- *     (possibly stale, shared) tmux server environment — additive, so tmux's own
- *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
- *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
- *     `#{pane_pid}`, clean signal delivery on detach/kill).
- * Keys are filtered to valid identifiers so exported shell functions
- * (`BASH_FUNC_*%%`) can't make `env` choke.
- *
- * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
- * the KEY names. The env map here carries resolved secrets bundles (options.env),
- * so the real string would embed secret VALUES — which get persisted verbatim
- * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
- * real values; the stored/informational copy uses the redacted form (RUSH-1758).
- */
 /**
  * True when `options.sessionId` is an id the HARNESS actually received, and so a
  * real, resumable handle — rather than one the launcher generated for its own
@@ -562,6 +523,10 @@ export declare function resolveTmuxWrap(ctx: TmuxWrapContext): TmuxWrapDecision;
  * or this reports a genuine id as fabricated.
  */
 export declare function isHarnessKnownSessionId(agent: AgentId, sessionId: string | undefined, resume: boolean | undefined): boolean;
+/**
+ * Build the pane command without inheriting stale tmux-server env. Redacted
+ * copies keep secret values out of persisted SessionMeta commands.
+ */
 export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
     redactEnvValues?: boolean;
     envFile?: string;

package/dist/lib/exec.js

@@ -1241,29 +1241,8 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
     return code === 0 && stdout.trim() === '0';
 }
 /**
- * Decide whether to run an interactive agent INSIDE a detached tmux session on
- * the shared socket (then attach the current TTY) instead of a bare spawn.
- *
- * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
- * unique `%pane` handle so `agents sessions --active` can tell co-located
- * agents apart and `agents focus` re-attaches without forking, plus scrollback
- * and mouse at the operator's keyboard. Off means OFF, for local and remote
- * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
- * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
- * when one exists and resumes the harness session from disk when it does not.
- * The RUSH-3125 forced remote wrap conflated durability with that preference
- * and surprised every operator who had explicitly left tmux off.
- *
- * One case still wraps regardless: a followed remote run whose launcher has
- * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
- * the detached pane is the run's only interface, not an ergonomics choice.
- *
- * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
- * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
- * escape hatch that silently stopped applying over `--device` would be worse
- * than the bare run the user asked for.
- *
- * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
+ * Tmux is opt-in except when a TTY-less remote launch would otherwise have no
+ * interface. Explicit per-run opt-outs always win.
  */
 export function resolveTmuxWrap(ctx) {
     // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
@@ -1297,24 +1276,6 @@ export function resolveTmuxWrap(ctx) {
         return ctx.remoteDispatch ? { kind: 'undurable' } : { kind: 'bare' };
     return { kind: 'wrap' };
 }
-/**
- * Build the shell command that runs an agent inside a tmux pane with the exact
- * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
- * K=V … <agent> <args…>` so:
- *   - `env` materializes the full agent env INTO the pane, independent of the
- *     (possibly stale, shared) tmux server environment — additive, so tmux's own
- *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
- *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
- *     `#{pane_pid}`, clean signal delivery on detach/kill).
- * Keys are filtered to valid identifiers so exported shell functions
- * (`BASH_FUNC_*%%`) can't make `env` choke.
- *
- * `redactEnvValues` replaces every value with a `<redacted>` marker while keeping
- * the KEY names. The env map here carries resolved secrets bundles (options.env),
- * so the real string would embed secret VALUES — which get persisted verbatim
- * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
- * real values; the stored/informational copy uses the redacted form (RUSH-1758).
- */
 /**
  * True when `options.sessionId` is an id the HARNESS actually received, and so a
  * real, resumable handle — rather than one the launcher generated for its own
@@ -1338,6 +1299,10 @@ export function isHarnessKnownSessionId(agent, sessionId, resume) {
         return true;
     return agent === 'claude';
 }
+/**
+ * Build the pane command without inheriting stale tmux-server env. Redacted
+ * copies keep secret values out of persisted SessionMeta commands.
+ */
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     // envFile: source the values instead of inlining them, so no VALUE ever lands

package/dist/lib/git.d.ts

@@ -152,6 +152,15 @@ export declare function getCurrentBranch(repoPath: string): Promise<string>;
  * repo" as a requested source before adopting it.
  */
 export declare function canonicalGitRemote(url: string): string;
+/**
+ * True when a git remote URL (any transport form: ssh, https, scp-style) points
+ * at the system DotAgents repo — {@link DEFAULT_SYSTEM_REPO}'s current slug OR
+ * its `phnx-labs/.agents` rename target (PHNX-3394), which
+ * {@link canonicalGitRemote} folds onto it via {@link RENAMED_REMOTE_ALIASES}.
+ * Pure string check with no git spawn, so it is unit-testable off a live
+ * checkout; {@link isSystemRepoOrigin} reads a dir's origin and delegates here.
+ */
+export declare function isSystemRepoRemote(remote: string | null | undefined): boolean;
 /** True when two git remote URLs point at the same repo across transport forms. */
 export declare function sameGitRemote(a: string | null | undefined, b: string | null | undefined): boolean;
 /**
@@ -354,7 +363,10 @@ export declare function adoptUserRepoIfNeeded(dir: string, opts?: {
     needsUrl?: boolean;
 }) | null>;
 /**
- * Check if the repo's origin points to the system repo.
+ * Check if the repo's origin points to the system repo — `phnx-labs/.agents-system`
+ * or its GitHub rename target `phnx-labs/.agents` (PHNX-3394), across any
+ * transport form. Reads the dir's origin and delegates the match to the pure
+ * {@link isSystemRepoRemote}.
  */
 export declare function isSystemRepoOrigin(dir: string): Promise<boolean>;
 /**