@phnx-labs/agents-cli 1.22.52 → 1.22.53

package/dist/lib/session/db.js

@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 40;
+export const SCHEMA_VERSION = 41;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -64,6 +64,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   id TEXT PRIMARY KEY,
   short_id TEXT NOT NULL,
   agent TEXT NOT NULL,
+  harness TEXT,
   origin TEXT DEFAULT 'cli',
   routine_name TEXT,
   routine_run_id TEXT,
@@ -1072,6 +1073,18 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions ADD COLUMN background_shell_count INTEGER`);
         }
     }
+    if (fromVersion < 41) {
+        // v40 -> v41: persist the custom-harness / profile name a run was launched
+        // as (PHNX-2935). Transcript discovery still keys `agent` on the HOST
+        // (the file lives under the host's session dir), so without this column
+        // `agents sessions` cannot tell `agents run deepseek` from a native claude
+        // run. Additive, no ledger flush — the name is launch metadata joined from
+        // the actor sidecar, not parsed from the transcript. Pre-upgrade rows stay
+        // NULL (native / unknown) until a sidecar-backed rescan fills them.
+        const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
+        if (!cols.has('harness'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN harness TEXT`);
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -1194,6 +1207,21 @@ export function getDB() {
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_machine_ts ON sessions(machine, timestamp DESC)`);
         db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_agent_ts ON sessions(agent, timestamp DESC)`);
     }
+    // harness column: only after the column is guaranteed present.
+    // Fresh SCHEMA (v41) includes the column; older DBs get it from migrate v41.
+    // schema_version can be stamped at SCHEMA_VERSION without the column existing
+    // — getDB writes the marker for any DB whose meta has no row (a hand-built
+    // or partially-created index), and migrateSchema never runs in that path
+    // (`currentVersion === undefined`). If a partial upgrade left schema_version
+    // ahead of the column, repair here so the next upsertSession INSERT naming
+    // `harness` does not throw (PHNX-2935). Same shape as the `machine` repair
+    // above, for the same reason.
+    {
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some((c) => c.name === 'harness')) {
+            db.exec(`ALTER TABLE sessions ADD COLUMN harness TEXT`);
+        }
+    }
     // One-shot cleanup of the pre-SQLite JSONL indexes. Safe — nothing reads
     // them anymore. Guarded by a meta flag so we only try once.
     const cleaned = db.prepare(`SELECT value FROM meta WHERE key = 'legacy_indexes_removed'`).get();
@@ -1583,7 +1611,7 @@ export function recordDirScans(entries) {
 }
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
-    id, short_id, agent, origin, routine_name, routine_run_id,
+    id, short_id, agent, harness, origin, routine_name, routine_run_id,
     version, account, account_key, account_org, mode, timestamp, last_activity,
     project, cwd, git_branch, topic, label, message_count, token_count,
     output_tokens, input_tokens, cache_read_tokens, cache_write_tokens,
@@ -1594,7 +1622,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     recent_directories_touched, linear_project, linear_project_url, machine,
     actor, initiated_by, used_browser, used_computer
   ) VALUES (
-    @id, @short_id, @agent, @origin, @routine_name, @routine_run_id,
+    @id, @short_id, @agent, @harness, @origin, @routine_name, @routine_run_id,
     @version, @account, @account_key, @account_org, @mode, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @output_tokens, @input_tokens, @cache_read_tokens, @cache_write_tokens,
@@ -1608,6 +1636,11 @@ const upsertSessionStmt = (db) => db.prepare(`
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
     agent = excluded.agent,
+    -- Custom harness/profile name is launch metadata, not transcript-derived.
+    -- COALESCE(existing, incoming) keeps a stored stamp on rescan (the scanner
+    -- carries none) and backfills a NULL-first row once the sidecar lands —
+    -- the same write-once pattern as actor/initiated_by (PHNX-2935).
+    harness = COALESCE(sessions.harness, excluded.harness),
     origin = excluded.origin,
     routine_name = excluded.routine_name,
     routine_run_id = excluded.routine_run_id,
@@ -1886,6 +1919,7 @@ export function upsertSession(meta, content, scan) {
         id: meta.id,
         short_id: meta.shortId,
         agent: meta.agent,
+        harness: meta.harness ?? actorRec?.harness ?? null,
         origin: meta.origin ?? 'cli',
         routine_name: meta.routineName ?? null,
         routine_run_id: meta.routineRunId ?? null,
@@ -2081,6 +2115,7 @@ export function upsertSessionsBatch(entries) {
                     id: meta.id,
                     short_id: meta.shortId,
                     agent: meta.agent,
+                    harness: meta.harness ?? actorIndex.get(meta.id)?.harness ?? null,
                     origin: meta.origin ?? 'cli',
                     routine_name: meta.routineName ?? null,
                     routine_run_id: meta.routineRunId ?? null,
@@ -2309,6 +2344,7 @@ function rowToMeta(row) {
         id: row.id,
         shortId: row.short_id,
         agent: row.agent,
+        harness: row.harness ?? undefined,
         origin: (row.origin === 'routine' ? 'routine' : 'cli'),
         routineName: row.routine_name ?? undefined,
         routineRunId: row.routine_run_id ?? undefined,

package/dist/lib/session/discover.js

@@ -26,7 +26,7 @@ import { getConfigSymlinkVersion } from '../installations/shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { deriveShortId } from './short-id.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
-import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, classifyUserPrompt } from './prompt.js';
+import { extractSessionTopic, extractSlashCommandName, extractSlashCommandFromToolInput, cleanGeneratedSessionLabel } from './prompt.js';
 import { isBackgroundShellStart, isSkillInvocation, extractSkills, extractSlashCommands, isSubAgentTool } from './highlights.js';
 import { parseAntigravity, parseCursor, splitSessionFilePath } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
@@ -3268,15 +3268,10 @@ export function finalizeClaudeScan(state) {
     // A topic is the first meaningful prompt. Harness-owned names travel in the
     // separate label field so consumers can replace an early topic once Claude's
     // generated title (or a later `/rename`) arrives.
-    // Claude's generated `ai-title` is derived from the first turn, so a session
-    // opened with a skill gets named after the injected "Base directory for this
-    // skill: …" line instead of its task — and that name then wins on every
-    // surface for the session's whole life. `classifyUserPrompt` reports `skill`
-    // only for that injected line, so collapse it to `/<skill>`. A `/rename`
-    // (`custom-title`) is the user's own words and is never rewritten.
-    const generated = classifyUserPrompt(state.aiTitle ?? '');
-    const label = state.customTitle
-        || (generated.kind === 'skill' ? generated.clean : state.aiTitle);
+    // Generated titles (Claude `ai-title`, Cursor `chatMeta.title`) go through
+    // one shared cleaner so a skill-preamble echo collapses to `/<skill>`. A
+    // `/rename` (`custom-title`) is the user's own words and is never rewritten.
+    const label = state.customTitle || cleanGeneratedSessionLabel(state.aiTitle);
     const worktree = detectWorktree(state.cwd, state.gitBranch);
     const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
@@ -4391,8 +4386,8 @@ export function readCursorMeta(filePath, currentVersion) {
         .filter((event) => event.type === 'message' && event.role === 'user' && event.content)
         .map((event) => event.content);
     const firstUserText = userTexts[0];
-    const title = typeof chatMeta?.title === 'string' && chatMeta.title.trim()
-        ? chatMeta.title.trim()
+    const title = typeof chatMeta?.title === 'string'
+        ? cleanGeneratedSessionLabel(chatMeta.title)
         : undefined;
     const meta = {
         id: sessionId,

package/dist/lib/session/live-metadata.js

@@ -37,6 +37,7 @@ export function activeSessionToSessionMeta(active, self, nowMs) {
         id,
         shortId: deriveShortId(id),
         agent: active.kind,
+        harness: active.harness,
         timestamp: new Date(startedMs).toISOString(),
         lastActivity: new Date(lastMs).toISOString(),
         // An empty file path is honest — a just-created session may have no

package/dist/lib/session/pid-registry.d.ts

@@ -1,6 +1,13 @@
 export interface PidSessionEntry {
     pid: number;
     agent: string;
+    /**
+     * Custom harness / profile name when this pid was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * CLI (`claude`) so process matching and transcript discovery keep
+     * working. `sessions --active` displays this when set (PHNX-2935).
+     */
+    harness?: string;
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;

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

@@ -69,5 +69,20 @@ export interface ClassifiedPrompt {
 export declare function classifyUserPrompt(raw: string | undefined, opts?: {
     hasImageAttachment?: boolean;
 }): ClassifiedPrompt;
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export declare function cleanGeneratedSessionLabel(title: string | undefined): string | undefined;
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export declare function extractSessionTopic(raw: string): string | undefined;

package/dist/lib/session/prompt.js

@@ -201,6 +201,27 @@ export function classifyUserPrompt(raw, opts = {}) {
     const display = (cleanedFirst || firstLine).replace(IMAGE_PATH_RE, '[image]').trim();
     return { clean: display, kind: 'text' };
 }
+/**
+ * Collapse a harness-generated session title when it is injected skill
+ * scaffolding; otherwise leave the title as the harness wrote it.
+ *
+ * Claude's `ai-title` and Cursor's `chatMeta.title` are both derived from the
+ * first turn, so a session opened with a skill gets named after the injected
+ * "Base directory for this skill: …" line. {@link classifyUserPrompt} reports
+ * `kind: 'skill'` only for that line, so collapse it to `/<skill>`. Empty or
+ * whitespace-only input yields `undefined` so the caller falls through to the
+ * first-prompt topic.
+ *
+ * A user-authored title (Claude `/rename` / `custom-title`) is never passed
+ * here — the caller keeps it verbatim.
+ */
+export function cleanGeneratedSessionLabel(title) {
+    const trimmed = title?.trim();
+    if (!trimmed)
+        return undefined;
+    const classified = classifyUserPrompt(trimmed);
+    return classified.kind === 'skill' ? classified.clean : trimmed;
+}
 /** Extract a one-line topic from a raw user message, or undefined if the message is pure noise. */
 export function extractSessionTopic(raw) {
     if (!raw.trim())

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

@@ -31,6 +31,16 @@ export declare const AG_TMUX_NAME_RE: RegExp;
 /** Whether `name` is an `ag-<agent>-<shortid>` tmux session name. */
 export declare function isAgentTmuxAlias(name: string): boolean;
 export declare function isSessionTrackedAgent(agent: string): agent is SessionAgentId;
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export declare function sessionDisplayAgent(session: {
+    agent: string;
+    harness?: string | null;
+}): string;
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
 export interface SessionEvent {
     type: 'message' | 'tool_use' | 'tool_result' | 'thinking' | 'error' | 'init' | 'result' | 'usage' | 'attachment' | 'hook' | 'interrupt';
@@ -154,6 +164,13 @@ export interface SessionMeta {
     id: string;
     shortId: string;
     agent: SessionAgentId;
+    /**
+     * Custom harness / profile name when this session was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST
+     * harness that produced the transcript (`claude`, …) so discovery and
+     * parsing keep working. Display surfaces this when set (PHNX-2935).
+     */
+    harness?: string;
     /** Where the indexed transcript came from. Routine rows are archived from a run directory. */
     origin?: 'cli' | 'routine';
     /** Routine name for transcripts archived from ~/.agents/.history/runs/<name>/<runId>/. */

package/dist/lib/session/types.js

@@ -31,3 +31,13 @@ export function isAgentTmuxAlias(name) {
 export function isSessionTrackedAgent(agent) {
     return SESSION_AGENTS.includes(agent);
 }
+/**
+ * The name `agents sessions` shows for a run. A custom harness launched via a
+ * profile (`agents run deepseek`) keeps its host agent for transcript discovery
+ * and parsing (`claude`) and stamps the profile name on `harness`. Display
+ * prefers that stamp so a deepseek run is not listed as claude (PHNX-2935).
+ */
+export function sessionDisplayAgent(session) {
+    const harness = session.harness?.trim();
+    return harness || session.agent;
+}

package/dist/lib/share/worker-template.js

@@ -518,20 +518,25 @@ function renderAttributionBar(meta, handle) {
   // page's own CSS can never wash the bar out (inline beats a page stylesheet);
   // the rest is a namespaced style block with !important on every colour so a
   // broad page rule (span selector to black, etc.) cannot make the text vanish.
+  // FIXED, full-viewport-width chrome (not sticky-inside-body — that inherited the
+  // page's max-width/margins and rendered as a floating box). html padding-top
+  // pushes the whole page down by the bar's height; flex-wrap:nowrap + ellipsis on
+  // the left keeps the bar exactly one line tall so the push height stays correct.
   return '<div class="agents-share-bar" role="contentinfo" aria-label="Sharing details" ' +
     'style="background:#0b0b0c !important;color:#e8e8e8 !important">' +
     '<style>' +
-    '.agents-share-bar{all:initial;position:sticky;top:0;left:0;right:0;z-index:2147483647;box-sizing:border-box;display:flex !important;align-items:center;gap:12px;flex-wrap:wrap;' +
-    'padding:8px 16px !important;background:#0b0b0c !important;color:#e8e8e8 !important;border-bottom:1px solid #24242b !important;' +
-    'font:13px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,system-ui,sans-serif !important}' +
+    'html{padding-top:38px !important}' +
+    '.agents-share-bar{all:initial;position:fixed !important;top:0 !important;left:0 !important;right:0 !important;width:100% !important;z-index:2147483647 !important;box-sizing:border-box;display:flex !important;align-items:center;gap:12px;flex-wrap:nowrap;' +
+    'padding:8px 16px !important;background:#0b0b0c !important;color:#e8e8e8 !important;border-bottom:1px solid #23232a !important;box-shadow:0 1px 3px rgba(0,0,0,.35) !important;' +
+    'font:13px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,system-ui,sans-serif !important}' +
     '.agents-share-bar *{box-sizing:border-box;font-family:inherit}' +
-    '.agents-share-bar .ash-left{display:flex;align-items:center;gap:8px;min-width:0;color:#cfd3d9 !important}' +
+    '.agents-share-bar .ash-left{flex:1 1 auto;min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;color:#cfd3d9 !important}' +
     '.agents-share-bar strong{color:#fff !important;font-weight:600}' +
-    '.agents-share-bar .ash-dot{opacity:.4;margin:0 3px}' +
-    '.agents-share-bar .ash-right{margin-left:auto;display:flex;align-items:center;gap:12px}' +
+    '.agents-share-bar .ash-dot{opacity:.4;margin:0 4px}' +
+    '.agents-share-bar .ash-right{flex:none;display:flex;align-items:center;gap:12px}' +
     '.agents-share-bar .ash-date{color:#9096a0 !important}' +
     '.agents-share-bar .ash-chip{display:inline-flex;align-items:center;gap:6px;padding:3px 10px;border-radius:999px;border:1px solid;font-weight:600;font-size:12px;white-space:nowrap}' +
-    '.agents-share-bar .ash-chip svg{flex:none}' +
+    '.agents-share-bar .ash-chip svg{flex:none;vertical-align:middle}' +
     '</style>' +
     '<span class="ash-left">' + left + '</span>' +
     '<span class="ash-right">' + right + '</span>' +

package/dist/lib/state.d.ts

@@ -391,6 +391,14 @@ export declare function getDeviceMetaPath(): string;
  */
 export declare function getVersionResourcesPath(): string;
 export declare function withMetaLock<T>(fn: () => T): T;
+/**
+ * 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

@@ -876,6 +876,9 @@ const META_KEY_SCOPE = {
     deviceRoutines: 'device',
     deviceConfig: 'device',
     deviceBrowser: 'device',
+    deviceFleet: 'device',
+    deviceHosts: 'device',
+    deviceAccounts: 'device',
     // Central — synced via agents.yaml.
     accounts: 'central',
     run: 'central',
@@ -915,6 +918,35 @@ const KNOWN_META_KEYS = new Set([
     // 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;
+}
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -973,20 +1005,37 @@ 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) {
+    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,6 +1098,43 @@ 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;
@@ -1121,6 +1207,52 @@ 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.`);

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),
     };
 }
 /**