@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/dist/lib/session/recovery.js

@@ -0,0 +1,95 @@
+import { AGENTS } from '../agents.js';
+import { isSelfHost } from '../devices/self-host.js';
+import { nativeResume } from '../exec.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../rotate.js';
+export class SessionRecoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SessionRecoveryError';
+    }
+}
+/** Canonical origin-device label for every recovery consumer. */
+export function sessionOriginDevice(session, self = machineId()) {
+    return normalizeHost(session.machine ?? self);
+}
+/** The peer that must execute recovery, or undefined when this is the origin. */
+export function sessionRecoveryPeer(session, selfCheck = isSelfHost) {
+    if (!session.machine || selfCheck(session.machine))
+        return undefined;
+    return normalizeHost(session.machine);
+}
+/** Whether an explicit placement names the session's origin device. */
+export function sessionRecoveryDestinationMatches(session, requestedHost, self = machineId()) {
+    const requested = normalizeHost(requestedHost.split('@').pop() || requestedHost);
+    return requested === sessionOriginDevice(session, self);
+}
+function runnableSessionAgent(session) {
+    if (!(session.agent in AGENTS)) {
+        throw new SessionRecoveryError(`Session ${session.shortId} belongs to ${session.agent}, which is indexed but cannot be launched by agents run.`);
+    }
+    return session.agent;
+}
+function sourceReason(session, candidates) {
+    if (!session.version)
+        return 'the origin version was not recorded';
+    const source = candidates.find((candidate) => candidate.version === session.version);
+    if (!source)
+        return `origin ${session.agent}@${session.version} is not installed`;
+    const readiness = readinessFromCandidate(source);
+    return readiness.ready
+        ? `origin ${session.agent}@${session.version} has no native resume form`
+        : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
+}
+/**
+ * Decide how a durable session resumes on the device that owns it.
+ *
+ * Native resume is legal only in the exact origin version's isolated home and
+ * only while that account is healthy. Every other successful path stays on the
+ * same harness and uses `/continue`, whose indexed transcript reader can reach
+ * retained version trash. No healthy same-harness account is a loud failure.
+ */
+export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume) {
+    const agent = runnableSessionAgent(session);
+    const device = sessionOriginDevice(session);
+    const source = session.version
+        ? candidates.find((candidate) => candidate.version === session.version)
+        : undefined;
+    const sourceReady = source ? readinessFromCandidate(source).ready : false;
+    // An exact healthy origin is deterministic: preserve its isolated home. If
+    // native resume is unavailable for that harness, /continue still launches in
+    // that same healthy home. Only an unusable/missing origin enters balanced
+    // account selection.
+    const selection = sourceReady
+        ? { picked: source }
+        : pickBalancedCandidate(candidates);
+    if (!selection) {
+        const detail = formatNoHealthyAccountError(agent, 'balanced', candidates);
+        throw new SessionRecoveryError(`Cannot recover session ${session.shortId} on ${device}; origin ${agent}@${session.version ?? 'unknown'}. ${detail}`);
+    }
+    const version = selection.picked.version;
+    if (session.version === version && supportsNative(agent, version)) {
+        return {
+            mode: 'native',
+            agent,
+            version,
+            reason: `origin ${agent}@${version} is installed and healthy`,
+        };
+    }
+    return {
+        mode: 'continue',
+        agent,
+        version,
+        reason: `${sourceReason(session, candidates)}; continuing with healthy ${agent}@${version}`,
+    };
+}
+export async function resolveSessionRecovery(session) {
+    const agent = runnableSessionAgent(session);
+    return resolveSessionRecoveryFromCandidates(session, await collectRunCandidates(agent));
+}
+/** Stable self-command used by focus, resume, and attach. The owning device runs
+ * the recovery resolver above; callers must not native-resume another version's
+ * isolated home themselves. */
+export function sessionRecoveryRunArgs(session) {
+    return ['run', 'auto', '--resume', session.id, '--interactive'];
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 28;
+export declare const SHIM_SCHEMA_VERSION = 29;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -160,7 +160,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 14;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/shims.js

@@ -223,7 +223,7 @@ async function promptConflictStrategy(conflictInfos) {
 //        The old dispatcher checked only the global dir, so a pinned grok that
 //        installed into the versioned home fell through to the "not installed"
 //        error.
-export const SHIM_SCHEMA_VERSION = 28;
+export const SHIM_SCHEMA_VERSION = 29;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -299,7 +299,18 @@ export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
 # mcp.json, sessions, skills, hooks). Point it at the versioned home.
 export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 `
-                            : '';
+                            : agent === 'muse'
+                                ? `
+# Muse Code has no MUSE_CONFIG_DIR. It resolves config via XDG:
+#   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+#   $XDG_DATA_HOME/muse    (sessions, plugins)
+# Pin XDG into the version home so managed runs never walk the adopt-time
+# ~/.config/muse -> version-home symlink — Muse refuses agent-definition
+# sources that are SymlinkOrReparse (exit 1). Same idea as CLAUDE_CONFIG_DIR.
+export XDG_CONFIG_HOME="$VERSION_DIR/home/.config"
+export XDG_DATA_HOME="$VERSION_DIR/home/.local/share"
+`
+                                : '';
     const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -871,7 +882,7 @@ export function removeShim(agent) {
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 14;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -898,7 +909,7 @@ function assertSafeVersion(version) {
  * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
  * The colocated test `shims.isolation-capability.test.ts` enforces this.
  */
-export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode'];
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode', 'muse'];
 /**
  * Whether an agent supports a clean `--isolated` install — i.e. its config
  * location can be redirected by an env var so the isolated copy stays fully
@@ -956,7 +967,15 @@ export OPENCODE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                            : '';
+                            : agent === 'muse'
+                                ? `
+# Muse Code: no dedicated config env var. Pin XDG so config/sessions live under
+# the version home as real directories (not via the adopt symlink at
+# ~/.config/muse, which Muse rejects with SymlinkOrReparse).
+export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
+`
+                                : '';
     const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native

package/dist/lib/startup/command-registry.d.ts

@@ -51,6 +51,7 @@ export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;
 export declare const loadModels: ModuleLoader;
+export declare const loadModes: ModuleLoader;
 export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -29,6 +29,7 @@ export const loadFork = async () => (await import('../../commands/fork.js')).reg
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
 export const loadSet = async () => (await import('../../commands/set.js')).registerSetCommand;
 export const loadModels = async () => (await import('../../commands/models.js')).registerModelsCommand;
+export const loadModes = async () => (await import('../../commands/modes.js')).registerModesCommand;
 export const loadPrune = async () => (await import('../../commands/prune.js')).registerPruneCommand;
 export const loadTrash = async () => (await import('../../commands/trash.js')).registerTrashCommands;
 export const loadRestore = async () => (await import('../../commands/trash.js')).registerRestoreCommand;
@@ -154,6 +155,7 @@ export const COMMAND_LOADERS = {
     defaults: [loadDefaults],
     set: [loadSet],
     models: [loadModels],
+    modes: [loadModes],
     trash: [loadTrash],
     restore: [loadRestore],
     doctor: [loadDoctor],

package/dist/lib/sync-umbrella.d.ts

@@ -68,6 +68,11 @@ export interface RunUmbrellaArgs {
     yes: boolean;
     /** Secrets passphrase, if available (env var or prompt). Undefined => skip secrets. */
     passphrase?: string;
+    /**
+     * Suppress human progress from the reconcile stage (`refresh`). Required so
+     * `agents sync --json` / fleet fan-out leave stdout as a single JSON object.
+     */
+    quiet?: boolean;
 }
 /**
  * Execute the planned stages in order: repos -> secrets -> reconcile.

package/dist/lib/sync-umbrella.js

@@ -18,6 +18,7 @@
 import { pullRepo } from './git.js';
 import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
+import { SYNC_PASSPHRASE_ENV } from './secrets/sync-passphrase.js';
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
  *   bare (no flags)        fetch repos, then reconcile
@@ -52,7 +53,7 @@ export function planUmbrellaStages(f) {
  * reconcile — `agents sync` should make as much current as it can in one pass.
  */
 export async function runUmbrellaSync(args) {
-    const { flags, log, yes, passphrase } = args;
+    const { flags, log, yes, passphrase, quiet = false } = args;
     const plan = planUmbrellaStages(flags);
     const result = { plan, reconciled: false };
     if (plan.fetchRepos) {
@@ -79,10 +80,10 @@ export async function runUmbrellaSync(args) {
             result.secrets = {
                 pulled: 0,
                 skipped: true,
-                reason: 'no passphrase — set AGENTS_SECRETS_PASSPHRASE or run `agents login` (#366)',
+                reason: `no passphrase — set ${SYNC_PASSPHRASE_ENV} or run \`agents login\` (#366)`,
                 errors: [],
             };
-            log('secrets: skipped (no passphrase available)');
+            log(`secrets: skipped (no passphrase — set ${SYNC_PASSPHRASE_ENV})`);
         }
         else {
             let pulled = 0;
@@ -108,7 +109,7 @@ export async function runUmbrellaSync(args) {
     }
     if (plan.reconcile) {
         const { refresh } = await import('./refresh.js');
-        await refresh({ skipPrompts: yes });
+        await refresh({ skipPrompts: yes, quiet });
         result.reconciled = true;
         // Keep already-registered devices' reachability current, and surface newly
         // appeared tailnet nodes as "pending" for the menu-bar Register/Ignore gate

package/dist/lib/tmux/session.d.ts

@@ -114,6 +114,8 @@ export interface TmuxClient {
 export declare function listClients(socket?: string): Promise<TmuxClient[]>;
 /** A dead pane's exit status, read from tmux while the pane lingers under remain-on-exit. */
 export interface PaneExit {
+    /** False when the pane/socket no longer exists or tmux could not query it. */
+    found: boolean;
     /** True once the process that ran in the pane has exited (pane is dead). */
     dead: boolean;
     /** Exit status of the dead pane's process, when tmux reports it. */
@@ -122,8 +124,8 @@ export interface PaneExit {
 /**
  * Read whether a pane's process has exited and, if so, its exit status. Used by
  * the spawn-wrap path to recover the wrapped agent's exit code after the attach
- * client returns. Returns `{ dead: false }` when tmux can't answer (session gone,
- * pane missing) so the caller treats an unreadable pane as "still alive / detach".
+ * client returns. `found: false` distinguishes a missing pane from a living one;
+ * focus must recover the former instead of attaching a retained/stale target.
  */
 export declare function paneExitStatus(pane: string, socket?: string): Promise<PaneExit>;
 /**

package/dist/lib/tmux/session.js

@@ -248,8 +248,8 @@ export async function listClients(socket) {
 /**
  * Read whether a pane's process has exited and, if so, its exit status. Used by
  * the spawn-wrap path to recover the wrapped agent's exit code after the attach
- * client returns. Returns `{ dead: false }` when tmux can't answer (session gone,
- * pane missing) so the caller treats an unreadable pane as "still alive / detach".
+ * client returns. `found: false` distinguishes a missing pane from a living one;
+ * focus must recover the former instead of attaching a retained/stale target.
  */
 export async function paneExitStatus(pane, socket) {
     let res;
@@ -261,13 +261,13 @@ export async function paneExitStatus(pane, socket) {
         });
     }
     catch {
-        return { dead: false };
+        return { found: false, dead: false };
     }
     if (res.code !== 0)
-        return { dead: false };
+        return { found: false, dead: false };
     const [deadRaw, statusRaw] = res.stdout.trim().split(/\s+/);
     const status = statusRaw !== undefined && statusRaw !== '' ? parseInt(statusRaw, 10) : undefined;
-    return { dead: deadRaw === '1', status: Number.isFinite(status) ? status : undefined };
+    return { found: true, dead: deadRaw === '1', status: Number.isFinite(status) ? status : undefined };
 }
 /**
  * Bind a per-session hook. Used by the spawn-wrap path to install a `pane-died`

package/dist/lib/types.d.ts

@@ -11,6 +11,7 @@ import type { FeedBroadcastConfig } from './feed-broadcast.js';
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi' | 'muse';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
+export type RunEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /**
  * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
  * host (14d launch affinity) → harness (best-account headroom, weighted) →
@@ -36,6 +37,7 @@ export interface AgentRunConfig {
 export interface RunDefaults {
     mode?: Mode;
     model?: string;
+    effort?: RunEffort;
 }
 /** `run:` section in agents.yaml. Agent keys keep strategy; `defaults` stores selector rules. */
 export type RunConfig = Partial<Record<AgentId, AgentRunConfig>> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.23",
+  "version": "1.22.24",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",