@phnx-labs/agents-cli 1.22.51 → 1.22.53

package/dist/lib/feed-broadcast.js

@@ -36,6 +36,7 @@
 import { spawnSync } from 'child_process';
 import { isOwnerAlias, readOwnerDest, resolveSendEnvelope, deliverEnvelope } from './channels/send.js';
 import { lookupTransport } from './channels/resolve.js';
+import { forwardOwnerNotifyToPeer } from './channels/owner-forward.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 const LEVEL_RANK = { milestone: 0, important: 1 };
 /** Parse a `--level` value; anything unrecognized is a usage error, not a default. */
@@ -473,7 +474,20 @@ async function runChannelSink(sink, meta) {
     if (!provider)
         return { name, ok: false, error };
     const result = await deliverEnvelope(resolved.envelope, meta);
-    return result.ok ? { name, ok: true } : { name, ok: false, error: result.error };
+    if (result.ok)
+        return { name, ok: true };
+    // The owner sink failed locally. When this box structurally cannot reach the
+    // owner (the rush-backed channel is macOS-only, so a headless Linux worker can
+    // never ring the phone — PHNX-3303), hand the delivery to a capable fleet peer
+    // over SSH rather than stranding the important post. Only the `owner` alias
+    // forwards: it resolves the peer's own fleet-synced owner destination, so a
+    // non-owner channel sink with an explicit recipient stays local.
+    if (owner) {
+        const forwarded = await forwardOwnerNotifyToPeer(sink.text ?? '', resolved.envelope.channel, meta);
+        if (forwarded?.ok)
+            return { name, ok: true };
+    }
+    return { name, ok: false, error: result.error };
 }
 /**
  * Run the planned sinks. A `command:` sink is a direct spawn with a bounded

package/dist/lib/git.d.ts

@@ -260,6 +260,99 @@ export declare function adoptRepo(source: string, targetDir: string): Promise<{
     backedUp: string[];
     error?: string;
 }>;
+/** Read an origin remote URL from a git dir, or null when there is none. */
+export declare function readOriginUrl(dir: string): string | null;
+/**
+ * Persist the user repo's remote URL to device-local runtime state so a future
+ * adopt-in-place can recover it after a `.git` loss. Best-effort — a write
+ * failure never blocks a sync.
+ */
+export declare function recordUserRepoRemote(dir: string, url: string): void;
+/**
+ * Resolve the user config repo's remote URL WITHOUT hardcoding it, for the
+ * adopt-in-place self-heal. In priority order:
+ *   1. an existing `origin` remote on the dir (a partial repo that kept its
+ *      `.git` but drifted) — the same source `agents repo sync` already reads;
+ *   2. the `AGENTS_USER_REPO_URL` env override (a fresh/never-cloned box);
+ *   3. the device-local record written by a prior healthy sync (a box that lost
+ *      its `.git` but kept `.history/` runtime state).
+ * Returns null when none is known — the caller then guides the operator to
+ * `agents repo pull user <git-url>` instead of crashing.
+ */
+export declare function resolveUserRepoRemoteUrl(dir: string): string | null;
+/**
+ * Decide whether a local top-level `agents.yaml` is a stale install stub that
+ * should be restored from the committed copy, vs. a legitimately customized file
+ * that must be preserved.
+ *
+ * The stub a partial install leaves behind (createDefaultMeta + a few config
+ * writes) is strictly SHORTER than the committed config AND missing whole
+ * top-level blocks the committed one carries (`config:` / `hooks:` — the fleet
+ * browser hub and hook registrations). Device-specific settings live in
+ * `devices/<host>/agents.yaml`, never here, so restoring the top-level file is
+ * safe. A file that already carries those blocks (or is longer) is treated as a
+ * real local edit and left alone — it surfaces as a modified path instead.
+ */
+export declare function isStaleAgentsYamlStub(local: string, committed: string): boolean;
+export interface AdoptInPlaceResult {
+    success: boolean;
+    commit: string;
+    /** Tracked files that were absent locally and materialized from origin/main. */
+    materialized: number;
+    /** True when the stale-stub top-level agents.yaml was restored from origin. */
+    reconciledAgentsYaml: boolean;
+    /**
+     * When agents.yaml was reconciled, the path the PRE-reconcile local copy was
+     * saved to first — so even a false-positive stub match (e.g. a user who
+     * deliberately removed a whole `hooks:`/`config:` block) is recoverable, never
+     * silently lost.
+     */
+    agentsYamlBackup?: string;
+    /**
+     * Tracked paths whose local copy differs from origin/main and was NOT touched
+     * — un-gitignored local edits surfaced rather than silently overwritten.
+     */
+    localEdits: string[];
+    error?: string;
+}
+/**
+ * Adopt an EXISTING, non-git (or origin-less) `~/.agents` directory in place —
+ * git-back it against its remote WITHOUT re-cloning and WITHOUT destroying the
+ * runtime state it carries (`.cache` / `.history` / `scratch` / `.system`, all
+ * gitignored). The self-heal for a partial install (PHNX-3301): the current code
+ * hard-fails with "Not a git repo", and the only manual fix is a destructive
+ * re-clone that wipes that runtime state.
+ *
+ * Plumbing-only, so it never trips the fleet git-guard (no `reset` / `checkout
+ * <branch>` / `stash` / `git config`):
+ *   1. `git init` + point HEAD at `main`.
+ *   2. `git remote add origin <url>`.
+ *   3. `git fetch origin main`.
+ *   4. `git update-ref refs/heads/main origin/main`; set upstream to origin/main.
+ *   5. `git read-tree origin/main` — index = origin/main, working tree untouched.
+ *   6. Materialize only the tracked files MISSING from the working tree
+ *      (`checkout-index` on that set) — existing local files are never overwritten.
+ *   7. Reconcile the top-level `agents.yaml`: restore it from origin/main only
+ *      when the local copy is a stale stub ({@link isStaleAgentsYamlStub}).
+ *
+ * Idempotent: a second run finds the remote/refs already present and simply
+ * re-materializes nothing. Any tracked path with real local edits is returned in
+ * `localEdits` (surfaced, never clobbered).
+ */
+export declare function adoptRepoInPlace(dir: string, remoteUrl: string): Promise<AdoptInPlaceResult>;
+/**
+ * Self-heal entry point for the USER config repo: when `dir` is not a git repo
+ * (or is a repo with no `origin`), resolve its remote URL and adopt it in place;
+ * otherwise return null (nothing to adopt — the normal sync path runs). Returns a
+ * failed result carrying `needsUrl` when the URL cannot be resolved, so the
+ * caller can print the `agents repo pull user <git-url>` remediation instead of
+ * the old "Not a git repo" crash.
+ */
+export declare function adoptUserRepoIfNeeded(dir: string, opts?: {
+    explicitUrl?: string;
+}): Promise<(AdoptInPlaceResult & {
+    needsUrl?: boolean;
+}) | null>;
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/git.js

@@ -829,6 +829,238 @@ export async function adoptRepo(source, targetDir) {
         return { success: false, commit: '', backedUp: [], error: err.message };
     }
 }
+/**
+ * Device-local record of the user config repo's remote URL, kept OUTSIDE the git
+ * tree so it survives a lost `.git` (`.history/` is gitignored runtime state).
+ * This is what lets `agents repo sync user` adopt-in-place a box that was healthy
+ * once and later lost its checkout, without the operator re-typing the URL.
+ */
+function userRepoRemoteRecordPath(dir) {
+    return path.join(dir, '.history', 'user-repo-remote.json');
+}
+/** Read an origin remote URL from a git dir, or null when there is none. */
+export function readOriginUrl(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    try {
+        const url = execFileSync('git', ['-C', dir, 'config', '--get', 'remote.origin.url'], {
+            encoding: 'utf-8',
+        }).trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the user repo's remote URL to device-local runtime state so a future
+ * adopt-in-place can recover it after a `.git` loss. Best-effort — a write
+ * failure never blocks a sync.
+ */
+export function recordUserRepoRemote(dir, url) {
+    try {
+        const file = userRepoRemoteRecordPath(dir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ url }, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* runtime cache write is best-effort */
+    }
+}
+/**
+ * Resolve the user config repo's remote URL WITHOUT hardcoding it, for the
+ * adopt-in-place self-heal. In priority order:
+ *   1. an existing `origin` remote on the dir (a partial repo that kept its
+ *      `.git` but drifted) — the same source `agents repo sync` already reads;
+ *   2. the `AGENTS_USER_REPO_URL` env override (a fresh/never-cloned box);
+ *   3. the device-local record written by a prior healthy sync (a box that lost
+ *      its `.git` but kept `.history/` runtime state).
+ * Returns null when none is known — the caller then guides the operator to
+ * `agents repo pull user <git-url>` instead of crashing.
+ */
+export function resolveUserRepoRemoteUrl(dir) {
+    const fromOrigin = readOriginUrl(dir);
+    if (fromOrigin)
+        return fromOrigin;
+    const fromEnv = process.env.AGENTS_USER_REPO_URL?.trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const raw = fs.readFileSync(userRepoRemoteRecordPath(dir), 'utf-8');
+        const url = JSON.parse(raw).url?.trim();
+        if (url)
+            return url;
+    }
+    catch {
+        /* no record yet */
+    }
+    return null;
+}
+/**
+ * Decide whether a local top-level `agents.yaml` is a stale install stub that
+ * should be restored from the committed copy, vs. a legitimately customized file
+ * that must be preserved.
+ *
+ * The stub a partial install leaves behind (createDefaultMeta + a few config
+ * writes) is strictly SHORTER than the committed config AND missing whole
+ * top-level blocks the committed one carries (`config:` / `hooks:` — the fleet
+ * browser hub and hook registrations). Device-specific settings live in
+ * `devices/<host>/agents.yaml`, never here, so restoring the top-level file is
+ * safe. A file that already carries those blocks (or is longer) is treated as a
+ * real local edit and left alone — it surfaces as a modified path instead.
+ */
+export function isStaleAgentsYamlStub(local, committed) {
+    if (local.trim() === committed.trim())
+        return false;
+    const shorter = local.split('\n').length < committed.split('\n').length;
+    const missingBlock = (/^config:/m.test(committed) && !/^config:/m.test(local)) ||
+        (/^hooks:/m.test(committed) && !/^hooks:/m.test(local));
+    return shorter && missingBlock;
+}
+/**
+ * Adopt an EXISTING, non-git (or origin-less) `~/.agents` directory in place —
+ * git-back it against its remote WITHOUT re-cloning and WITHOUT destroying the
+ * runtime state it carries (`.cache` / `.history` / `scratch` / `.system`, all
+ * gitignored). The self-heal for a partial install (PHNX-3301): the current code
+ * hard-fails with "Not a git repo", and the only manual fix is a destructive
+ * re-clone that wipes that runtime state.
+ *
+ * Plumbing-only, so it never trips the fleet git-guard (no `reset` / `checkout
+ * <branch>` / `stash` / `git config`):
+ *   1. `git init` + point HEAD at `main`.
+ *   2. `git remote add origin <url>`.
+ *   3. `git fetch origin main`.
+ *   4. `git update-ref refs/heads/main origin/main`; set upstream to origin/main.
+ *   5. `git read-tree origin/main` — index = origin/main, working tree untouched.
+ *   6. Materialize only the tracked files MISSING from the working tree
+ *      (`checkout-index` on that set) — existing local files are never overwritten.
+ *   7. Reconcile the top-level `agents.yaml`: restore it from origin/main only
+ *      when the local copy is a stale stub ({@link isStaleAgentsYamlStub}).
+ *
+ * Idempotent: a second run finds the remote/refs already present and simply
+ * re-materializes nothing. Any tracked path with real local edits is returned in
+ * `localEdits` (surfaced, never clobbered).
+ */
+export async function adoptRepoInPlace(dir, remoteUrl) {
+    const empty = {
+        success: false,
+        commit: '',
+        materialized: 0,
+        reconciledAgentsYaml: false,
+        localEdits: [],
+    };
+    const trimmed = remoteUrl.trim();
+    try {
+        // The URL is always a resolved git remote (origin / env / record), never a
+        // `gh:` shorthand — so skip parseSource (which THROWS on ssh:// and rewrites
+        // git@github -> https, breaking SSH-key-only auth). assertSafeGitTransport
+        // still blocks the dangerous transports (ext::, file://, option injection)
+        // while permitting https / ssh / scp-style / a local bare repo.
+        assertSafeGitTransport(trimmed);
+        if (!fs.existsSync(dir)) {
+            return { ...empty, error: `Target directory does not exist: ${dir}` };
+        }
+        // Non-interactive git — fail fast on a missing credential instead of hanging
+        // on a prompt (same rationale as adoptRepo).
+        process.env.GIT_TERMINAL_PROMPT = '0';
+        const git = simpleGit(dir);
+        // 1. init + HEAD -> main (idempotent: init on an existing repo is a no-op).
+        //    Set HEAD via symbolic-ref rather than `init -b main` so it works on git
+        //    < 2.28, and lands on `main` even if the repo already initialized as
+        //    `master`.
+        if (!isGitRepo(dir))
+            await git.init();
+        await git.raw(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+        // 2. origin — add only when absent, so a re-run keeps the existing remote.
+        const remotes = await git.getRemotes(true);
+        if (!remotes.some((r) => r.name === 'origin')) {
+            await git.raw(['remote', 'add', 'origin', trimmed]);
+        }
+        // 3-4. fetch, plant the local main on origin/main, set upstream.
+        await git.raw(['fetch', 'origin', 'main']);
+        await git.raw(['update-ref', 'refs/heads/main', 'origin/main']);
+        await git.raw(['branch', '--set-upstream-to=origin/main', 'main']);
+        // 5. index = origin/main, working tree untouched.
+        await git.raw(['read-tree', 'origin/main']);
+        // 6. Materialize only the tracked files MISSING on disk. Passing the explicit
+        //    missing set (never `checkout-index -a`) guarantees no existing local
+        //    file — a stub agents.yaml, a modified rule — is overwritten. Chunked to
+        //    stay under the argv limit on a cold box where most files are missing.
+        const tracked = (await git.raw(['ls-files', '-z'])).split('\0').filter(Boolean);
+        const missing = tracked.filter((rel) => !fs.existsSync(path.join(dir, rel)));
+        for (let i = 0; i < missing.length; i += 500) {
+            await git.raw(['checkout-index', '-f', '--', ...missing.slice(i, i + 500)]);
+        }
+        // 7. Reconcile a stale-stub top-level agents.yaml from origin/main. `restore`
+        //    is plumbing the git-guard allows; it rewrites only this one path.
+        let reconciledAgentsYaml = false;
+        let agentsYamlBackup;
+        if (tracked.includes('agents.yaml')) {
+            const abs = path.join(dir, 'agents.yaml');
+            const local = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : '';
+            const committed = await git.raw(['show', 'origin/main:agents.yaml']);
+            if (isStaleAgentsYamlStub(local, committed)) {
+                // The stub heuristic can't perfectly distinguish a partial-install stub
+                // from a user who deliberately removed a whole block, so save the local
+                // copy to gitignored runtime state BEFORE restoring — a false positive is
+                // then recoverable and surfaced, never silent data loss.
+                if (local) {
+                    agentsYamlBackup = path.join(dir, '.history', 'agents.yaml.pre-adopt.bak');
+                    fs.mkdirSync(path.dirname(agentsYamlBackup), { recursive: true });
+                    fs.writeFileSync(agentsYamlBackup, local);
+                }
+                await git.raw(['restore', '--source=origin/main', '--', 'agents.yaml']);
+                reconciledAgentsYaml = true;
+            }
+        }
+        // Surface — never silently keep — any tracked path whose local copy still
+        // differs from origin/main after the reconcile (real un-gitignored edits).
+        const dirty = (await git.raw(['status', '--porcelain', '--untracked-files=no']))
+            .split('\n')
+            .map((l) => l.slice(3).trim())
+            .filter(Boolean);
+        installGithooksSymlinks(dir);
+        recordUserRepoRemote(dir, trimmed);
+        const commit = (await git.raw(['rev-parse', '--short', 'HEAD'])).trim();
+        return {
+            success: true,
+            commit,
+            materialized: missing.length,
+            reconciledAgentsYaml,
+            ...(agentsYamlBackup ? { agentsYamlBackup } : {}),
+            localEdits: dirty,
+        };
+    }
+    catch (err) {
+        return { ...empty, error: err.message };
+    }
+}
+/**
+ * Self-heal entry point for the USER config repo: when `dir` is not a git repo
+ * (or is a repo with no `origin`), resolve its remote URL and adopt it in place;
+ * otherwise return null (nothing to adopt — the normal sync path runs). Returns a
+ * failed result carrying `needsUrl` when the URL cannot be resolved, so the
+ * caller can print the `agents repo pull user <git-url>` remediation instead of
+ * the old "Not a git repo" crash.
+ */
+export async function adoptUserRepoIfNeeded(dir, opts = {}) {
+    const hasOrigin = isGitRepo(dir) && readOriginUrl(dir) !== null;
+    if (hasOrigin)
+        return null;
+    const url = opts.explicitUrl?.trim() || resolveUserRepoRemoteUrl(dir);
+    if (!url) {
+        return {
+            success: false,
+            commit: '',
+            materialized: 0,
+            reconciledAgentsYaml: false,
+            localEdits: [],
+            needsUrl: true,
+            error: `${displayHomePath(dir)} is not a git repo and no remote URL is known.`,
+        };
+    }
+    return adoptRepoInPlace(dir, url);
+}
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/hosts/dispatch.d.ts

@@ -40,9 +40,10 @@ export declare function withActorEnv(env?: Record<string, string>): Record<strin
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
 /**

package/dist/lib/hosts/dispatch.js

@@ -78,9 +78,10 @@ export function withActorEnv(env) {
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export function remoteRunShellPrelude(agent, extra = {}) {
     const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
@@ -497,11 +498,14 @@ export async function runInteractiveOnHost(host, opts) {
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
     // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
     //
-    // REMOTE_INTERACTIVE_ENV rides the same prelude and is what makes the remote
-    // agent DETACHED: its stdio is this ssh link, so without the tmux wrap a
-    // blink SIGHUPs it and the in-flight turn is gone — while reconnect.ts is
-    // built to re-attach a pane it assumes survived (RUSH-3125). Set here, on the
-    // interactive path only: `launchDetached` already setsids the headless one.
+    // REMOTE_INTERACTIVE_ENV rides the same prelude and tells the remote CLI its
+    // stdio is this ssh link: it marks the run as reconnect-managed (a drop is
+    // answered by reconnect.ts, which rejoins the live pane or resumes the
+    // session in place) and, when the launcher has no TTY (CI, scripts), requires
+    // the detached pane that is the run's only interface. Since PHNX-3316 it no
+    // longer forces the tmux wrap on a TTY-followed run — the peer's
+    // tmux.enabled decides that. Set here, on the interactive path only:
+    // `launchDetached` already setsids the headless one.
     const prelude = remoteRunShellPrelude(opts.agent, { [REMOTE_INTERACTIVE_ENV]: '1' });
     let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {

package/dist/lib/hosts/providers/local.d.ts

@@ -2,9 +2,15 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import type { Host, HostProvider, HostProviderCapabilities } from '../types.js';
 export declare class LocalHostProvider implements HostProvider {

package/dist/lib/hosts/providers/local.js

@@ -2,14 +2,28 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import { readMeta, updateMeta } from '../../state.js';
+import { unionDeviceHosts } from '../../devices/device-docs.js';
 import { listSshConfigHosts, isSshConfigHost } from '../ssh-config.js';
+/** The EFFECTIVE host overlay: the cross-box union of every device doc's
+ * `hosts:` block, with any lingering central-legacy `hosts:` entries as a base
+ * (a device doc wins on a name collision). Newest `addedAt` wins across boxes. */
 function entries() {
-    return readMeta().hosts ?? {};
+    return { ...readMeta().hosts, ...unionDeviceHosts() };
+}
+/** THIS box's OWN host registrations (the writable slice in the device doc). */
+function ownEntries(meta = readMeta()) {
+    return meta.deviceHosts ?? {};
 }
 function toHost(name, entry, enrolled) {
     return {
@@ -63,19 +77,16 @@ export class LocalHostProvider {
             ...(spec.caps && spec.caps.length ? { caps: spec.caps } : {}),
             addedAt: spec.addedAt ?? new Date().toISOString(),
         };
-        updateMeta((meta) => ({ ...meta, hosts: { ...(meta.hosts ?? {}), [spec.name]: entry } }));
+        // Device-scoped: land in THIS box's device doc, never the shared central map.
+        updateMeta((meta) => ({ ...meta, deviceHosts: { ...ownEntries(meta), [spec.name]: entry } }));
         return toHost(spec.name, entry, true);
     }
     async remove(name) {
+        // A box only owns the registrations in its own device doc; drop from there.
         updateMeta((meta) => {
-            const hosts = { ...(meta.hosts ?? {}) };
+            const hosts = { ...ownEntries(meta) };
             delete hosts[name];
-            // Drop the key entirely when empty so we don't leave `hosts: {}` behind.
-            if (Object.keys(hosts).length === 0) {
-                const { hosts: _omit, ...rest } = meta;
-                return rest;
-            }
-            return { ...meta, hosts };
+            return { ...meta, deviceHosts: hosts };
         });
     }
 }

package/dist/lib/hosts/reconnect.d.ts

@@ -211,10 +211,13 @@ export declare function startConnectionTarget(opts: {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export declare function afterInteractiveRemoteExit(opts: {
     target?: ReconnectTarget;

package/dist/lib/hosts/reconnect.js

@@ -2,34 +2,35 @@
  * Auto-reconnect for an interactive `agents run --device` session whose
  * SSH link dropped.
  *
- * A remote interactive agent runs in a DETACHED tmux session on the peer (see
- * lib/exec.ts `runInTmux`), so a network blink kills only the local ssh client —
- * the agent keeps running.
- *
- * **That premise is a guarantee, not a hope, only since RUSH-3125.** It used to
- * rest on the peer's `tmux.enabled`, an ergonomics preference that defaults OFF
- * — so on a default box the agent was a child of the sshd session, a blink
- * SIGHUPed it, and this file reconnected to a corpse while telling the user it
- * was "still running there." The interactive dispatch now exports
- * REMOTE_INTERACTIVE_ENV and exec.ts `resolveTmuxWrap` wraps on it regardless of
- * that toggle, so what is written below actually holds. Anything that would let
- * a remote interactive run reach the peer unwrapped breaks this whole file.
+ * What the reconnect lands on depends on the peer's `tmux.enabled`
+ * (PHNX-3316). With the wrap opted in, the agent runs in a DETACHED tmux
+ * session on the peer (see lib/exec.ts `runInTmux`), so a network blink kills
+ * only the local ssh client and the reattach below rejoins the live pane.
+ * With the wrap off — the fleet default — the remote agent is a child of the
+ * sshd session and a blink SIGHUPs it: the in-flight turn is lost, and the
+ * reattach RESUMES the harness session from disk instead. Both outcomes go
+ * through the same verb below; what changed in PHNX-3316 is that "resumed"
+ * is once again an honest, expected result rather than a corpse this file
+ * pretended was alive (the pre-RUSH-3125 bug), and RUSH-3125's forced wrap —
+ * which made the pane a guarantee by overriding the operator's tmux.enabled —
+ * is gone with it.
  *
  * `sshStream` reports that drop as exit code 255 (ssh's
  * own connection-layer failure; see ssh-exec.ts). Without this, exec.ts would
  * `process.exit(255)` and the user would have to notice, find the session id, and
- * `agents sessions focus` by hand. Instead we re-attach the live remote pane over
- * SSH automatically, with bounded backoff, until the user detaches cleanly (the
- * remote returns 0), the agent exits (the tmux session is gone; a non-255 code),
- * or the user interrupts the wait with Ctrl-C ({@link waitOrInterrupt} → 130).
+ * `agents sessions focus` by hand. Instead we re-attach over SSH automatically,
+ * with bounded backoff, until the user detaches cleanly (the remote returns 0),
+ * the agent exits (a non-255 code), or the user interrupts the wait with
+ * Ctrl-C ({@link waitOrInterrupt} → 130).
  *
  * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
  * --local` — which JOINS the live local tmux pane there (a second client, no fork)
- * when it still exists, and RESUMES the session in place when the pane is already
- * gone. Dropping `--attach-only` is deliberate: a reattach that lands after the
- * remote pane died must not dead-end at a bare shell (the RUSH-2085 bug), it must
- * fall through to resume so the user is put back into the agent. There is one
- * re-attach implementation (the peer's focus) to keep in sync.
+ * when it exists, and RESUMES the session in place when there is no pane — which
+ * is every drop on a default (wrap-off) box. Dropping `--attach-only` is
+ * deliberate: a reattach that finds no pane must not dead-end at a bare shell
+ * (the RUSH-2085 bug), it must fall through to resume so the user is put back
+ * into the agent. There is one re-attach implementation (the peer's focus) to
+ * keep in sync.
  *
  * **What it takes to refill the budget: reached the host AND held the pane.** ssh
  * returns 255 for BOTH "couldn't connect at all" and "connected, then the link
@@ -314,10 +315,13 @@ export function startConnectionTarget(opts) {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export function afterInteractiveRemoteExit(opts) {
     if (!opts.target)

package/dist/lib/hosts/registry.js

@@ -22,6 +22,7 @@ import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
 import { normalizeHost } from '../machine-id.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
@@ -187,7 +188,9 @@ export async function matchHost(name, opts = {}) {
     catch {
         reg = {};
     }
-    const overlay = readMeta().hosts?.[host];
+    // The effective host overlay is the cross-box union of every device doc's
+    // `hosts:` block (PHNX-3315), plus any lingering central-legacy entry.
+    const overlay = { ...readMeta().hosts, ...unionDeviceHosts() }[host];
     // 1. A registered device (normalized match) — its live address/OS/presence win.
     const device = matchDevice(host, reg);
     if (device)

package/dist/lib/hosts/remote-os.js

@@ -19,6 +19,7 @@
 import { loadDevicesSync } from '../devices/registry.js';
 import { readDeviceConfigValues } from '../device-config.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 /** Resolve the OS/platform string for a host name, or undefined if unknown. */
 export function resolveRemoteOsSync(name) {
     try {
@@ -33,5 +34,6 @@ export function resolveRemoteOsSync(name) {
         // A corrupt/unreadable device registry must never break command building —
         // fall through to the host overlay and ultimately the POSIX default.
     }
-    return readMeta().hosts?.[name]?.os;
+    // Cross-box union of the device-scoped host overlays, central legacy as base.
+    return ({ ...readMeta().hosts, ...unionDeviceHosts() }[name])?.os;
 }