@phnx-labs/agents-cli 1.22.52 → 1.22.54

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

@@ -19,7 +19,8 @@
 export function configureRootCommand(program, name, version) {
     return program
         .name(name)
-        .description('Environment manager for AI agents')
+        .description('Install, configure, run, and dispatch AI coding agents from one place.\n' +
+        'Works with Claude, Codex, Antigravity, Cursor, OpenCode, OpenClaw, and Droid.')
         .version(version)
         .option('--verbose', 'Show startup self-heal details on stderr')
         .helpOption('-h, --help', 'Show help')

package/dist/lib/state.d.ts

@@ -391,6 +391,30 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
+ * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
+ * heals on its next central write (serializeCentral). An absent or headerless
+ * file is NOT stale (a headerless central file is deliberately left alone).
+ * Surfaced as config drift by `agents sync status` (PHNX-3315).
+ */
+export declare function hasStaleMetaHeader(): boolean;
+/**
+ * Parse the top-level user `agents.yaml` (this box's synced central file) WITHOUT
+ * the system-repo merge, machine-local overlay, or cache — the raw on-disk central
+ * map, or null when the file is absent/unparseable. Used by config-drift detection
+ * to see the central blocks that should have folded into the device doc, without
+ * mis-attributing a system-repo default as this box's own leak (PHNX-3315).
+ */
+export declare function readTopLevelUserMeta(): Record<string, unknown> | null;
+/**
+ * Write `meta` to disk (central + device docs + pins) WITHOUT taking the meta
+ * lock — the caller must already hold it via {@link withMetaLock}. Exported so a
+ * writer that needs to read fresh state, decide, and commit within a SINGLE lock
+ * acquisition (e.g. browser tombstone eviction) can do so without the
+ * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ */
+export declare function writeMetaUnlocked(meta: Meta): void;
 /**
  * Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed.
  *

package/dist/lib/state.js

@@ -858,49 +858,99 @@ function writeIfChanged(filePath, content) {
  * `agents:` / `versions:` are not written (no empty committed files).
  */
 /**
- * Every `Meta` key, classified as `central` (synced via agents.yaml) or `device`
- * (routed to the per-machine device file by {@link writeMetaUnlocked}). The
- * `Record<keyof Meta, …>` type makes this EXHAUSTIVE: adding a field to `Meta`
- * without classifying it here is a compile error. That guarantee is what lets
- * `serializeCentral` delete only keys THIS version models — a key a newer CLI
- * version added (absent from this map) is preserved verbatim instead of being
- * dropped and synced fleet-wide as data loss. This is the fix for the recurring
- * agents.yaml key-loss (beta flags, `notify.owner`, and `feed:` all vanished
- * this way when an older-versioned CLI on the fleet rewrote the file).
+ * Fleet-shared (`central`) Meta keys — the OPT-IN allowlist. A key listed here is
+ * written to the synced `~/.agents/agents.yaml`. Device-scope is the DEFAULT:
+ * {@link metaKeyScope} returns `'device'` for every Meta key NOT listed here, so a
+ * newly-added key can never SILENTLY churn the shared file the way a
+ * central-by-default would — the very trap behind the recurring agents.yaml churn.
+ * Making a key fleet-shared is now a deliberate edit HERE, not the path of least
+ * resistance (PHNX-3315).
  */
-const META_KEY_SCOPE = {
-    // Device-local — writeMetaUnlocked destructures these out; never in central.
-    agents: 'device',
-    isolatedAgents: 'device',
-    versions: 'device',
-    deviceRoutines: 'device',
-    deviceConfig: 'device',
-    deviceBrowser: 'device',
-    // Central — synced via agents.yaml.
-    accounts: 'central',
-    run: 'central',
-    model: 'central',
-    watchdog: 'central',
-    lease: 'central',
-    secrets: 'central',
-    budget: 'central',
-    feed: 'central',
-    beta: 'central',
-    registries: 'central',
-    profiles: 'central',
-    source: 'central',
-    projectRoot: 'device',
-    extraRepos: 'central',
-    brands: 'central',
-    actors: 'central',
-    seededPresets: 'central',
-    hooks: 'central',
-    config: 'central',
-    hosts: 'central',
-    fleet: 'central',
-    share: 'central',
-    notify: 'central',
-};
+const CENTRAL_META_KEYS = [
+    'accounts',
+    'run',
+    'model',
+    'watchdog',
+    'lease',
+    'secrets',
+    'budget',
+    'feed',
+    'beta',
+    'registries',
+    'profiles',
+    'source',
+    'extraRepos',
+    'brands',
+    'actors',
+    'seededPresets',
+    'hooks',
+    'config',
+    'hosts',
+    'fleet',
+    'share',
+    'notify',
+];
+/**
+ * Device-scoped Meta keys with BESPOKE routing — each lands in a special file
+ * (pins JSON / version-resources JSON) or a REMAPPED device-doc sub-block
+ * (`deviceHosts`->`hosts:`, `deviceFleet`->`fleet:`, ...), so their handling is
+ * hand-written in {@link writeMetaUnlocked} / {@link overlayMachineLocal} and kept
+ * behavior-identical. A device-scoped key NOT listed here is a GENERIC device key:
+ * it round-trips through `devices/<host>/agents.yaml` under its OWN name with no
+ * bespoke wiring (see the generic loops in those two functions). The `browser`
+ * tombstone is bespoke too — drained by lib/browser/registry.ts.
+ */
+const BESPOKE_DEVICE_KEYS = [
+    'agents',
+    'isolatedAgents',
+    'versions',
+    'deviceRoutines',
+    'deviceConfig',
+    'deviceBrowser',
+    'deviceFleet',
+    'deviceHosts',
+    'deviceAccounts',
+    'projectRoot',
+];
+const CENTRAL_KEY_SET = new Set(CENTRAL_META_KEYS);
+const _metaKeysAreExhaustive = true;
+void _metaKeysAreExhaustive;
+/**
+ * Sync-domain of a Meta key. `'central'` ONLY for the opt-in allowlist; `'device'`
+ * by DEFAULT for everything else — so the classification is authoritative (it
+ * DRIVES the generic device-doc router below) rather than a decorative string map,
+ * and forgetting to classify a new key routes it to the SAFE per-box file.
+ */
+function metaKeyScope(key) {
+    return CENTRAL_KEY_SET.has(key) ? 'central' : 'device';
+}
+/** Bespoke device keys as a runtime Set (the generic router skips these). */
+const BESPOKE_DEVICE_KEY_SET = new Set([
+    ...BESPOKE_DEVICE_KEYS,
+    // The `browser` tombstone is device-scoped but bespoke: lib/browser/registry.ts
+    // drains it (collision-checked) into deviceBrowser, so the generic router must
+    // never blindly relocate it.
+    'browser',
+]);
+/**
+ * Device-doc sub-block names the read/write paths handle BESPOKE-ly (each maps to
+ * a different `device*` Meta key, or lives in a separate file). The generic
+ * device-doc overlay skips these so it only surfaces genuine generic keys.
+ */
+const BESPOKE_DEVICE_DOC_KEYS = new Set([
+    'agents',
+    'isolatedAgents',
+    'routines',
+    'config',
+    'browser',
+    'fleet',
+    'hosts',
+    'accounts',
+    'projectRoot',
+    // Legacy top-level doc key the config migration folds into `config:`; never
+    // surfaced onto Meta before, so keep the generic overlay from doing so.
+    'defaultBrowserProfile',
+]);
 /**
  * Every key this version models (central + device). serializeCentral deletes an
  * on-disk key only when it is KNOWN and absent from the write's in-memory object:
@@ -910,11 +960,91 @@ const META_KEY_SCOPE = {
  * a newer CLI version added — is preserved verbatim, never dropped + synced away.
  */
 const KNOWN_META_KEYS = new Set([
-    ...Object.keys(META_KEY_SCOPE),
+    ...CENTRAL_META_KEYS,
+    ...BESPOKE_DEVICE_KEYS,
     // Removed browser-profile store. Kept only as a serializer tombstone so the
     // first registry read can migrate it into this device's file and delete it.
     'browser',
 ]);
+/**
+ * Rewrite a frozen `agents.yaml` header to the current {@link META_HEADER}.
+ *
+ * `serializeCentral` parses the existing file to preserve its hand-written body
+ * comments, but that also preserves the leading metadata header verbatim, so a
+ * top-level file written before the agi-cli rename (or before the `$schema` line
+ * existed) keeps its stale header forever — every freshly-written device doc gets
+ * the current header while the shared file is left behind (PHNX-3315).
+ *
+ * The header is healed TEXTUALLY, on the already-serialized string, rather than
+ * via `doc.commentBefore`: the `yaml` library folds the whole leading comment
+ * block onto the FIRST key's `commentBefore` when that key already carries a
+ * hand-written comment, so the header is not reliably the document comment — but
+ * it is always the top block of the output. Strip a leading `agents-cli metadata`
+ * header (any pre-rename variant, with or without the `$schema` line — the URL
+ * and schema lines are matched specifically so a hand-written body comment is
+ * never mistaken for a header line) and prepend the canonical header. A file with
+ * no recognizable header simply gains one. Body comments, which sit below the
+ * blank line that terminates the header, are untouched.
+ */
+function healMetaHeader(serialized) {
+    const headerBlock = /^# agents-cli metadata\n# Auto-generated - do not edit manually\n(?:# (?:https:\/\/github\.com\/phnx-labs\/[^\n]*|yaml-language-server: \$schema=[^\n]*)\n)*\n?/;
+    const stripped = serialized.replace(headerBlock, '');
+    // No metadata header present (replace was a no-op) → leave the file exactly as
+    // it is. We heal a STALE header; we never prepend one to a file that never had
+    // it (that would rewrite a hand-authored, headerless central file on the first
+    // real central change). A current header round-trips to the identical bytes.
+    return stripped === serialized ? serialized : META_HEADER + stripped;
+}
+/**
+ * True when the top-level `~/.agents/agents.yaml` carries a metadata header that
+ * is NOT the canonical {@link META_HEADER} — the P1 frozen-header case a box only
+ * heals on its next central write (serializeCentral). An absent or headerless
+ * file is NOT stale (a headerless central file is deliberately left alone).
+ * Surfaced as config drift by `agents sync status` (PHNX-3315).
+ */
+export function hasStaleMetaHeader() {
+    let content;
+    try {
+        content = fs.readFileSync(META_FILE, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    return healMetaHeader(content) !== content;
+}
+/**
+ * Parse the top-level user `agents.yaml` (this box's synced central file) WITHOUT
+ * the system-repo merge, machine-local overlay, or cache — the raw on-disk central
+ * map, or null when the file is absent/unparseable. Used by config-drift detection
+ * to see the central blocks that should have folded into the device doc, without
+ * mis-attributing a system-repo default as this box's own leak (PHNX-3315).
+ */
+export function readTopLevelUserMeta() {
+    let content;
+    try {
+        content = fs.readFileSync(META_FILE, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = yaml.parse(content);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch { /* malformed — nothing to report */ }
+    return null;
+}
+/**
+ * Top-level keys currently on disk in the central `agents.yaml` ({} when the file
+ * is absent or unparseable). The generic device-doc router uses this to leave a
+ * FOREIGN key — one this version does not model, already written to central by a
+ * newer CLI — in place instead of relocating it to this box's device doc.
+ */
+function readCentralKeys() {
+    return new Set(Object.keys(readTopLevelUserMeta() ?? {}));
+}
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -973,20 +1103,41 @@ function serializeCentral(central) {
         }
     }
     // No central field changed → keep the file byte-identical (comments intact), so
-    // writeIfChanged skips it and the churn loop never starts.
+    // writeIfChanged skips it and the churn loop never starts. A device-only write
+    // (pins/routines/etc. routed elsewhere) reaches here with changed=false and
+    // MUST NOT rewrite the shared file — header healing waits for a genuine central
+    // change below rather than dirtying agents.yaml on an unrelated write, which is
+    // the very churn that wedges `agents sync` and blocks fleet pulls.
     if (!changed)
         return existing;
-    // Everything cleared → header only (never leave a flow `{}` behind).
-    // Otherwise stringifyDoc: it still normalizes a legacy flow root (`{}`) to
-    // block, so edited nodes do not render flow (`disabledCommands: [ teams ]`
-    // instead of a `- teams` block list), but it no longer forces block on a
-    // normal document — that flattened committed flow sequences and made this
-    // writer disagree with feed.ts/activity.ts/migrate.ts on the same file
-    // (RUSH-2505). parseDocument still preserves comments + key ordering.
-    return isEmpty ? META_HEADER : stringifyDoc(doc);
+    // Everything cleared → header only (never leave a flow `{}` behind). Byte-stable
+    // when the file is already exactly the current header.
+    if (isEmpty)
+        return existing === META_HEADER ? existing : META_HEADER;
+    // A central key changed: serialize the edited doc and heal a frozen header on
+    // the result. stringifyDoc still normalizes a legacy flow root (`{}`) to block,
+    // so edited nodes do not render flow (`disabledCommands: [ teams ]` instead of a
+    // `- teams` block list), but it no longer forces block on a normal document —
+    // that flattened committed flow sequences and made this writer disagree with
+    // feed.ts/activity.ts/migrate.ts on the same file (RUSH-2505). parseDocument
+    // still preserves body comments + key ordering; healMetaHeader is a no-op unless
+    // a stale metadata header is actually present, so a headerless central file is
+    // updated in place without gaining one.
+    return healMetaHeader(stringifyDoc(doc));
 }
-function writeMetaUnlocked(meta) {
-    const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, projectRoot, ...central } = meta;
+/**
+ * Write `meta` to disk (central + device docs + pins) WITHOUT taking the meta
+ * lock — the caller must already hold it via {@link withMetaLock}. Exported so a
+ * writer that needs to read fresh state, decide, and commit within a SINGLE lock
+ * acquisition (e.g. browser tombstone eviction) can do so without the
+ * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
+ */
+export function writeMetaUnlocked(meta) {
+    // INVARIANT: every key destructured here must also be in BESPOKE_DEVICE_KEYS (and
+    // vice versa) — a bespoke device key that is classified but NOT pulled out here
+    // would fall into `central`, and the generic router skips it (BESPOKE_DEVICE_KEY_SET),
+    // so it would silently sync to the shared file. Keep the two lists in lockstep.
+    const { agents, isolatedAgents, versions, deviceRoutines, deviceConfig, deviceBrowser, deviceFleet, deviceHosts, deviceAccounts, projectRoot, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const hasAgents = !!agents && Object.keys(agents).length > 0;
@@ -1049,11 +1200,69 @@ function writeMetaUnlocked(meta) {
         doc.browser = deviceBrowser;
     else
         delete doc.browser;
+    // PHNX-3315 device-scoped fleet/hosts/accounts blocks. Each is this box's OWN
+    // slice; the effective fleet view is unioned across every device doc at read
+    // time (lib/devices/device-docs.ts). Empty slices are dropped so a box that
+    // has made no decision leaves no key behind (no committed empty maps).
+    const fleetDiscovery = deviceFleet?.discovery && Object.keys(deviceFleet.discovery).length > 0
+        ? deviceFleet.discovery : undefined;
+    const fleetIgnored = deviceFleet?.ignored && deviceFleet.ignored.length > 0
+        ? deviceFleet.ignored : undefined;
+    if (fleetDiscovery || fleetIgnored) {
+        const df = {};
+        if (fleetDiscovery)
+            df.discovery = fleetDiscovery;
+        if (fleetIgnored)
+            df.ignored = fleetIgnored;
+        doc.fleet = df;
+    }
+    else
+        delete doc.fleet;
+    const hasDeviceHosts = !!deviceHosts && Object.keys(deviceHosts).length > 0;
+    if (hasDeviceHosts)
+        doc.hosts = deviceHosts;
+    else
+        delete doc.hosts;
+    const accountsNative = deviceAccounts?.native && Object.keys(deviceAccounts.native).length > 0
+        ? deviceAccounts.native : undefined;
+    const accountsBindings = deviceAccounts?.bindings && Object.keys(deviceAccounts.bindings).length > 0
+        ? deviceAccounts.bindings : undefined;
+    if (accountsNative || accountsBindings) {
+        const da = {};
+        if (accountsNative)
+            da.native = accountsNative;
+        if (accountsBindings)
+            da.bindings = accountsBindings;
+        doc.accounts = da;
+    }
+    else
+        delete doc.accounts;
     const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
     if (hasProjectRoot)
         doc.projectRoot = projectRoot;
     else
         delete doc.projectRoot;
+    // Generic device-scoped keys (PHNX-3315): any key left in `central` that this
+    // version classifies as device but does NOT bespoke-route round-trips through
+    // this box's device doc under its OWN name — so a NEWLY DECLARED device-scoped
+    // key lands per-box BY DEFAULT, with no bespoke wiring, and never reaches the
+    // synced central file. Today the bespoke set covers every device key, so this
+    // loop moves nothing (behavior-identical). A key that is UNKNOWN to this version
+    // AND already present in the on-disk central file is a FOREIGN key a newer CLI
+    // wrote as central — left in `central` and preserved verbatim by serializeCentral
+    // (the fleet-wide config-loss guard), never relocated to this box's doc.
+    const centralRecord = central;
+    const onDiskCentralKeys = readCentralKeys();
+    for (const k of Object.keys(centralRecord)) {
+        if (metaKeyScope(k) !== 'device')
+            continue; // fleet-shared: stays central
+        if (BESPOKE_DEVICE_KEY_SET.has(k))
+            continue; // bespoke (incl. browser tombstone)
+        if (!KNOWN_META_KEYS.has(k) && onDiskCentralKeys.has(k))
+            continue; // foreign — preserve
+        doc[k] = centralRecord[k];
+        delete centralRecord[k];
+    }
     if (Object.keys(doc).length > 0) {
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         writeIfChanged(devicePath, META_HEADER + yaml.stringify(doc));
@@ -1121,12 +1330,67 @@ function overlayMachineLocal(meta) {
             if (dm?.config && typeof dm.config === 'object' && !Array.isArray(dm.config)) {
                 meta.deviceConfig = { ...meta.deviceConfig, ...dm.config };
             }
+            // PHNX-3315: this box's own device-scoped fleet/hosts/accounts slices.
+            // These populate the `device*` keys the writers read-modify-write; the
+            // effective UNION across all boxes is computed separately by
+            // lib/devices/device-docs.ts, not here (this overlay is this box only).
+            // A malformed block on THIS box's own doc is a HARD error, exactly like
+            // `routines` below and the cross-box union readers (device-docs.ts): a
+            // silent drop would let the next writeMetaUnlocked round-trip overwrite the
+            // whole block with just the new entry, discarding the rest on this box's
+            // tracked file (PHNX-3315).
+            const isMap = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+            const dmRaw = dm;
+            if (dmRaw.fleet !== undefined) {
+                if (!isMap(dmRaw.fleet))
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet must be a map.`);
+                const df = dmRaw.fleet;
+                if (df.discovery !== undefined && !isMap(df.discovery)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet.discovery must be a map.`);
+                }
+                if (df.ignored !== undefined && !Array.isArray(df.ignored)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: fleet.ignored must be a list.`);
+                }
+                const discovery = df.discovery;
+                const ignored = df.ignored;
+                if (discovery || ignored)
+                    meta.deviceFleet = { ...(discovery ? { discovery } : {}), ...(ignored ? { ignored } : {}) };
+            }
+            if (dmRaw.hosts !== undefined) {
+                if (!isMap(dmRaw.hosts))
+                    throw new Error(`Device config corrupted at ${devicePath}: hosts must be a map.`);
+                meta.deviceHosts = { ...meta.deviceHosts, ...dmRaw.hosts };
+            }
+            if (dmRaw.accounts !== undefined) {
+                if (!isMap(dmRaw.accounts))
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts must be a map.`);
+                const acc = dmRaw.accounts;
+                if (acc.native !== undefined && !isMap(acc.native)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts.native must be a map.`);
+                }
+                if (acc.bindings !== undefined && !isMap(acc.bindings)) {
+                    throw new Error(`Device config corrupted at ${devicePath}: accounts.bindings must be a map.`);
+                }
+                const native = acc.native;
+                const bindings = acc.bindings;
+                if (native || bindings)
+                    meta.deviceAccounts = { ...(native ? { native } : {}), ...(bindings ? { bindings } : {}) };
+            }
             if (Object.prototype.hasOwnProperty.call(dm, 'routines')) {
                 if (!Array.isArray(dm.routines) || dm.routines.some((name) => typeof name !== 'string')) {
                     throw new Error(`Device config corrupted at ${devicePath}: routines must be a string list.`);
                 }
                 meta.deviceRoutines = dm.routines;
             }
+            // Generic device-scoped keys (PHNX-3315): device-doc keys this overlay does
+            // NOT bespoke-handle map straight back onto Meta under their own name —
+            // symmetry with the generic write in writeMetaUnlocked. The bespoke sub-blocks
+            // are handled above and skipped, so a stock device doc surfaces nothing extra.
+            for (const [k, v] of Object.entries(dm)) {
+                if (BESPOKE_DEVICE_DOC_KEYS.has(k))
+                    continue;
+                meta[k] = v;
+            }
         }
     }
     const vrPath = getVersionResourcesPath();

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

@@ -20,6 +20,7 @@
  */
 import { AgentId } from './types.js';
 import { type DoctorKind } from './doctor-diff.js';
+import { type ConfigDrift } from './config-drift.js';
 /**
  * One stable status per resource, unified across every surface.
  *  - `synced`  — installed copy matches the resolved source (DiffStatus 'ok').
@@ -76,6 +77,9 @@ export interface UserRepoStatus {
 export interface UnifiedSyncStatus {
     system: SystemRepoStatus;
     user: UserRepoStatus;
+    /** Config drift: has this box drained its device-scoped state, or is it still
+     *  carrying per-box state in the shared top-level agents.yaml? (PHNX-3315) */
+    config: ConfigDrift;
     agents: AgentVersionStatus[];
     totals: {
         drifted: number;

package/dist/lib/sync-status.js

@@ -26,6 +26,7 @@ import { loadManifest } from './staleness/index.js';
 import { getSystemAgentsDir, getUserAgentsDir } from './state.js';
 import * as fs from 'fs';
 import { isGitRepo, readOriginUrl } from './git.js';
+import { detectConfigDrift } from './config-drift.js';
 const STATUS_MAP = {
     ok: 'synced',
     diff: 'drifted',
@@ -125,6 +126,7 @@ export async function computeSyncStatus(options = {}) {
     }
     const system = await getSystemRepoStatus();
     const user = await getUserRepoStatus();
+    const config = detectConfigDrift();
     const agentsNeedingSync = new Set();
     let drifted = 0, missing = 0, orphan = 0, versionsNeedingSync = 0, versionsNeverSynced = 0;
     for (const v of agents) {
@@ -141,6 +143,7 @@ export async function computeSyncStatus(options = {}) {
     return {
         system,
         user,
+        config,
         agents,
         totals: {
             drifted,

package/dist/lib/terminal/resolve.d.ts

@@ -34,6 +34,7 @@ export type InjectResolution = {
 } | {
     addressable: false;
     reason: string;
+    hint?: string;
 };
 export interface ResolveOptions {
     /**
@@ -49,6 +50,12 @@ export interface ResolveOptions {
      */
     ptyId?: string;
 }
+/**
+ * Human-facing recovery hint for a session the resolver judged un-addressable.
+ * Tells the user both how to continue THIS session and how to make FUTURE runs
+ * addressable, so the failure is not silent and the fix is actionable.
+ */
+export declare function addressabilityRecoveryHint(session: ActiveSession, fallbackId?: string): string;
 /**
  * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
  * precedence logic is unit-testable without the process table. This is where the

package/dist/lib/terminal/resolve.js

@@ -1,10 +1,40 @@
 import { getActiveSessions } from '../session/active.js';
+import { machineId } from '../machine-id.js';
 /** The editor CLIs that speak the swarm-ext URI protocol, keyed by the host detectHost() reports. */
 const IDE_INJECT_VARIANTS = {
     codium: { cli: 'codium', scheme: 'vscodium' },
     cursor: { cli: 'cursor', scheme: 'cursor' },
     code: { cli: 'code', scheme: 'vscode' },
 };
+/**
+ * Human-facing recovery hint for a session the resolver judged un-addressable.
+ * Tells the user both how to continue THIS session and how to make FUTURE runs
+ * addressable, so the failure is not silent and the fix is actionable.
+ */
+export function addressabilityRecoveryHint(session, fallbackId) {
+    const sid = session.sessionId;
+    // Branch on the live sessionId (an IDE terminal that has not registered one
+    // yet is a distinct message), but render the resume command with the real id
+    // when the caller can supply it — e.g. `focus` has meta.id even though the
+    // live row's sessionId is falsy, so without this the hint printed a useless
+    // `agents sessions resume <id>` placeholder in exactly that case (PHNX-3070).
+    const resumeId = sid ?? fallbackId;
+    const shortId = resumeId ? resumeId.slice(0, 8) : '<id>';
+    const device = session.machine ?? machineId();
+    const resumeCmd = resumeId ? `agents sessions resume ${shortId}` : 'agents sessions resume <id>';
+    const tmuxCmd = `agents config set devices.${device}.tmux on`;
+    const interactive = session.context === 'terminal' || !!session.tty;
+    if (session.host === 'ghostty') {
+        return `Ghostty has no per-split addressing. ${interactive ? `Enable tmux wrapping with \`${tmuxCmd}\` and re-launch, or ` : ''}use \`${resumeCmd}\` to continue this session.`;
+    }
+    if (session.host && session.host in IDE_INJECT_VARIANTS && !sid) {
+        return `This IDE terminal has not registered a session id yet. Wait a moment and retry, or use \`${resumeCmd}\` to continue.`;
+    }
+    if (session.host) {
+        return `Host '${session.host}' has no addressable rail here. ${interactive ? `Enable tmux wrapping with \`${tmuxCmd}\` and re-launch, or ` : ''}use \`${resumeCmd}\` to continue this session.`;
+    }
+    return `This session has no addressable terminal rail (not tmux, iTerm, an IDE terminal, or a pty sidecar). ${interactive ? `Enable tmux wrapping with \`${tmuxCmd}\` and re-launch, or ` : ''}use \`${resumeCmd}\` to continue this session.`;
+}
 /**
  * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
  * precedence logic is unit-testable without the process table. This is where the
@@ -35,7 +65,11 @@ export function resolveInjectTargetForSession(session, opts = {}) {
     const variant = session.host ? IDE_INJECT_VARIANTS[session.host] : undefined;
     if (variant) {
         if (!session.sessionId) {
-            return { addressable: false, reason: `IDE terminal (${session.host}) has no session id to address` };
+            return {
+                addressable: false,
+                reason: `IDE terminal (${session.host}) has no session id to address`,
+                hint: addressabilityRecoveryHint(session),
+            };
         }
         return {
             addressable: true,
@@ -58,13 +92,18 @@ export function resolveInjectTargetForSession(session, opts = {}) {
                 note: 'coarse Ghostty window path (opt-in): raises a window and types into the FOCUSED split — not split-precise',
             };
         }
-        return { addressable: false, reason: 'un-addressable (ghostty, no tmux): no per-split addressing; watchdog skips' };
+        return {
+            addressable: false,
+            reason: 'un-addressable (ghostty, no tmux): no per-split addressing; watchdog skips',
+            hint: addressabilityRecoveryHint(session),
+        };
     }
     return {
         addressable: false,
         reason: session.host
             ? `no precise inject rail for host '${session.host}' (no tmux/iterm/IDE terminal detected)`
             : 'no inject rail: session is not inside tmux, iTerm, or an IDE terminal',
+        hint: addressabilityRecoveryHint(session),
     };
 }
 /**