@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/devices/config-migration.d.ts

@@ -1,42 +1,37 @@
 /**
- * One-time migration: fold per-device config from the legacy stores into the
- * central `fleet.devices.<name>.config` block of `~/.agents/agents.yaml`.
+ * One-time migration to the current device-config + pins layout:
  *
- * Only SHARED-visibility keys move — the ones a peer reads. Machine-visibility
- * keys (see lib/config-machine-keys.ts) stay in the per-device doc, which is
- * exactly where the machine-local read path now looks for them.
+ *   (a) central `fleet.devices.<name>.config` (the short-lived #2458 store)
+ *       folds into each per-device doc's `config:` block — central wins
+ *       (newest intent) — and is stripped from central;
+ *   (b) legacy `.history/devices/auto-launch.json` flags fold into the doc
+ *       `config:` too (oldest store — only fills keys not already set);
+ *   (c) a top-level `defaultBrowserProfile:` in a device doc folds into that
+ *       doc's `config:`;
+ *   (d) agent pins (`agents:` / `isolatedAgents:`) leave the TRACKED
+ *       per-device docs: THIS machine's pins move to the untracked
+ *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
+ *       is the destination); peers' pins are simply dropped from the tracked
+ *       file (each peer owns/rewrites its own pins locally).
  *
- * Legacy sources (both pre-unification):
- *   - `~/.agents/devices/<name>/agents.yaml` — the `config:` map and the
- *     top-level `defaultBrowserProfile:` field. Agent pins (`agents:`,
- *     `isolatedAgents:`), `routines:`, and machine-visibility config STAY in the
- *     per-device doc — only shared operator config moves.
- *   - `~/.agents/.history/devices/auto-launch.json` — AGI EXT auto-launch
- *     enabled/preferred flags, becoming `autoLaunchEnabled` /
- *     `autoLaunchPreferred` config keys.
+ * What stays put: a device doc's existing `config:` (already the right home)
+ * and its `routines:` list (operator-owned, read cross-device by
+ * routine-activation.ts).
  *
- * The fold is ADDITIVE: the central block is written and the legacy stores are
- * left exactly as they were, so a box still on the previous CLI keeps reading
- * what it always read. The central-wins merge makes a re-run a byte no-op.
+ * Order is crash-safe: destination writes (pins file, device doc) land BEFORE
+ * the source strip (central), so a crash mid-fold re-folds on the next run and
+ * the destination-wins merges make that a no-op. Idempotent — after a
+ * successful run none of the legacy locations hold data, so re-running is a
+ * cheap existence check. A doc that fails to parse is LOUDLY skipped (left
+ * untouched) so the next run retries — never silently emptied, same corruption
+ * contract the device registry keeps.
  *
- * Invoked only from a lifecycle entry point — `runMigration()` (fresh installs)
- * and daemon boot. It must NEVER hang off a config read or write: agents.yaml is
- * tracked and shared by the whole fleet, so a migration on the read path lets an
- * ordinary `agents config get` dirty it on every machine.
+ * Invoked from three places so every install converges regardless of entry
+ * point: `runMigration()` (fresh / sentinel-less installs), daemon boot, and
+ * the first `lib/device-config.ts` read/write in a process.
  */
-import type { FleetDeviceOverride, FleetManifest } from '../fleet/types.js';
 /**
- * The `fleet.devices` map a config write should edit. A missing block starts
- * empty; the literal `'all'` upgrades to an explicit map of the
- * currently-registered roster so a config write never silently narrows what
- * `agents apply` targets. (The dynamic "new devices join automatically"
- * semantics of `'all'` do not survive the upgrade — per-device config is
- * inherently a map.)
+ * Fold every legacy device-config/pins location into the current layout. Safe
+ * to call on every boot / config access: cheap no-op once folded.
  */
-export declare function fleetDevicesMapForWrite(fleet: FleetManifest | undefined): Record<string, FleetDeviceOverride>;
-/**
- * Fold the legacy per-device config stores into the central
- * `fleet.devices.<name>.config` block. Safe to call on every boot / config
- * access: cheap no-op once the legacy stores are stripped.
- */
-export declare function migrateDeviceConfigToCentral(): void;
+export declare function migrateDeviceConfigStores(): void;

package/dist/lib/devices/config-migration.js

@@ -1,73 +1,50 @@
 /**
- * One-time migration: fold per-device config from the legacy stores into the
- * central `fleet.devices.<name>.config` block of `~/.agents/agents.yaml`.
+ * One-time migration to the current device-config + pins layout:
  *
- * Only SHARED-visibility keys move — the ones a peer reads. Machine-visibility
- * keys (see lib/config-machine-keys.ts) stay in the per-device doc, which is
- * exactly where the machine-local read path now looks for them.
+ *   (a) central `fleet.devices.<name>.config` (the short-lived #2458 store)
+ *       folds into each per-device doc's `config:` block — central wins
+ *       (newest intent) — and is stripped from central;
+ *   (b) legacy `.history/devices/auto-launch.json` flags fold into the doc
+ *       `config:` too (oldest store — only fills keys not already set);
+ *   (c) a top-level `defaultBrowserProfile:` in a device doc folds into that
+ *       doc's `config:`;
+ *   (d) agent pins (`agents:` / `isolatedAgents:`) leave the TRACKED
+ *       per-device docs: THIS machine's pins move to the untracked
+ *       `.history/devices/pins-<host>.json` (pins file wins on conflict — it
+ *       is the destination); peers' pins are simply dropped from the tracked
+ *       file (each peer owns/rewrites its own pins locally).
  *
- * Legacy sources (both pre-unification):
- *   - `~/.agents/devices/<name>/agents.yaml` — the `config:` map and the
- *     top-level `defaultBrowserProfile:` field. Agent pins (`agents:`,
- *     `isolatedAgents:`), `routines:`, and machine-visibility config STAY in the
- *     per-device doc — only shared operator config moves.
- *   - `~/.agents/.history/devices/auto-launch.json` — AGI EXT auto-launch
- *     enabled/preferred flags, becoming `autoLaunchEnabled` /
- *     `autoLaunchPreferred` config keys.
+ * What stays put: a device doc's existing `config:` (already the right home)
+ * and its `routines:` list (operator-owned, read cross-device by
+ * routine-activation.ts).
  *
- * The fold is ADDITIVE: the central block is written and the legacy stores are
- * left exactly as they were, so a box still on the previous CLI keeps reading
- * what it always read. The central-wins merge makes a re-run a byte no-op.
+ * Order is crash-safe: destination writes (pins file, device doc) land BEFORE
+ * the source strip (central), so a crash mid-fold re-folds on the next run and
+ * the destination-wins merges make that a no-op. Idempotent — after a
+ * successful run none of the legacy locations hold data, so re-running is a
+ * cheap existence check. A doc that fails to parse is LOUDLY skipped (left
+ * untouched) so the next run retries — never silently emptied, same corruption
+ * contract the device registry keeps.
  *
- * Invoked only from a lifecycle entry point — `runMigration()` (fresh installs)
- * and daemon boot. It must NEVER hang off a config read or write: agents.yaml is
- * tracked and shared by the whole fleet, so a migration on the read path lets an
- * ordinary `agents config get` dirty it on every machine.
+ * Invoked from three places so every install converges regardless of entry
+ * point: `runMigration()` (fresh / sentinel-less installs), daemon boot, and
+ * the first `lib/device-config.ts` read/write in a process.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getDevicesAutoLaunchPath, getUserAgentsDir, updateMeta, } from '../state.js';
-import { loadDevicesSync } from './registry.js';
-import { MACHINE_LOCAL_YAML_KEYS } from '../config-machine-keys.js';
-/**
- * The `fleet.devices` map a config write should edit. A missing block starts
- * empty; the literal `'all'` upgrades to an explicit map of the
- * currently-registered roster so a config write never silently narrows what
- * `agents apply` targets. (The dynamic "new devices join automatically"
- * semantics of `'all'` do not survive the upgrade — per-device config is
- * inherently a map.)
- */
-export function fleetDevicesMapForWrite(fleet) {
-    if (fleet && fleet.devices !== 'all')
-        return { ...fleet.devices };
-    if (fleet?.devices !== 'all')
-        return {};
-    // devices === 'all': expand to the registered roster.
-    const roster = loadDevicesSync();
-    const devices = {};
-    for (const name of Object.keys(roster))
-        devices[name] = {};
-    return devices;
-}
-function mergeFold(folds, device, values) {
-    folds[device] = { ...folds[device], ...values };
-}
-/**
- * Read every legacy device doc, returning the config to fold per device.
- * A doc that fails to parse is LOUDLY skipped (and left untouched) so the next
- * run retries — never silently emptied, same corruption contract the device
- * registry keeps.
- */
-function collectDeviceDocFolds(devicesRoot) {
-    const folds = {};
+import { META_HEADER, getDevicesAutoLaunchPath, getDevicePinsPath, getUserAgentsDir, readMeta, updateMeta, withMetaLock, } from '../state.js';
+import { atomicWriteFileSync } from '../fs-atomic.js';
+import { machineId } from '../machine-id.js';
+/** Read every device doc. A doc that fails to parse is loudly skipped. */
+function readDeviceDocs(devicesRoot) {
     const docs = [];
     let entries;
     try {
         entries = fs.readdirSync(devicesRoot, { withFileTypes: true });
     }
     catch {
-        return { folds, docs }; // no devices/ tree — nothing to fold
+        return docs; // no devices/ tree — nothing to fold
     }
     for (const entry of entries) {
         if (!entry.isDirectory())
@@ -89,48 +66,38 @@ function collectDeviceDocFolds(devicesRoot) {
             console.error(`device config migration: ${docPath} is not a YAML map; leaving it for manual repair`);
             continue;
         }
-        const doc = parsed;
-        const config = {};
-        if (doc.config !== undefined) {
-            if (typeof doc.config !== 'object' || doc.config === null || Array.isArray(doc.config)) {
-                console.error(`device config migration: ${docPath} has a non-map config: block; leaving it for manual repair`);
-                continue;
+        docs.push({ name: entry.name, path: docPath, doc: parsed });
+    }
+    return docs;
+}
+/** Write a device doc, or remove it (and its dir) when nothing remains. */
+function writeDeviceDoc(docPath, doc) {
+    try {
+        if (Object.keys(doc).length === 0) {
+            fs.rmSync(docPath, { force: true });
+            try {
+                fs.rmdirSync(path.dirname(docPath));
             }
-            Object.assign(config, doc.config);
-        }
-        if (typeof doc.defaultBrowserProfile === 'string') {
-            config.defaultBrowserProfile = doc.defaultBrowserProfile;
+            catch { /* not empty — other files live in the device dir */ }
         }
-        // Machine-visibility keys are NOT folded. Two reasons, both load-bearing:
-        //
-        //  1. They already live exactly where they belong. `config:` in this doc is
-        //     the machine-local store the new read path uses (state.ts overlays it
-        //     as `deviceConfig`), so folding would only copy them into the shared
-        //     file this whole change exists to keep clean.
-        //  2. Copying a PEER's would be a leak. `browserRemoteControl` is a consent
-        //     flag gating whether other machines may drive that box's browser;
-        //     hoisting one box's opt-in into the synced file spreads it to the fleet.
-        //     Each machine keeps its own, in its own doc.
-        for (const key of Object.keys(config)) {
-            if (MACHINE_LOCAL_YAML_KEYS.has(key))
-                delete config[key];
+        else {
+            fs.mkdirSync(path.dirname(docPath), { recursive: true });
+            atomicWriteFileSync(docPath, META_HEADER + yaml.stringify(doc));
         }
-        if (Object.keys(config).length === 0)
-            continue;
-        mergeFold(folds, entry.name, config);
-        docs.push({ name: entry.name, path: docPath, doc });
     }
-    return { folds, docs };
+    catch (err) {
+        console.error(`device config migration: could not rewrite ${docPath} (${err.message}); a later run retries`);
+    }
 }
-/** Read the legacy auto-launch.json, returning the flags to fold per device. */
-function collectAutoLaunchFolds(autoLaunchPath) {
-    const folds = {};
+/** The legacy auto-launch.json flags, keyed by device name ({} when absent). */
+function readAutoLaunchFlags(autoLaunchPath) {
+    const out = {};
     let raw;
     try {
         raw = fs.readFileSync(autoLaunchPath, 'utf-8');
     }
     catch {
-        return folds; // absent — nothing to fold
+        return out; // absent — nothing to fold
     }
     let parsed;
     try {
@@ -138,7 +105,7 @@ function collectAutoLaunchFolds(autoLaunchPath) {
     }
     catch (err) {
         console.error(`device config migration: could not parse ${autoLaunchPath} (${err.message}); leaving it for a later retry`);
-        return folds;
+        return out;
     }
     const devices = parsed?.devices;
     if (devices && typeof devices === 'object' && !Array.isArray(devices)) {
@@ -149,55 +116,167 @@ function collectAutoLaunchFolds(autoLaunchPath) {
             if (pref?.preferred === true)
                 config.autoLaunchPreferred = true;
             if (Object.keys(config).length > 0)
-                mergeFold(folds, name, config);
+                out[name] = config;
         }
     }
-    return folds;
+    return out;
+}
+function isConfigMap(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 /**
- * Fold the legacy per-device config stores into the central
- * `fleet.devices.<name>.config` block. Safe to call on every boot / config
- * access: cheap no-op once the legacy stores are stripped.
+ * Fold every legacy device-config/pins location into the current layout. Safe
+ * to call on every boot / config access: cheap no-op once folded.
  */
-export function migrateDeviceConfigToCentral() {
+export function migrateDeviceConfigStores() {
     const devicesRoot = path.join(getUserAgentsDir(), 'devices');
     const autoLaunchPath = getDevicesAutoLaunchPath();
-    const { folds: docFolds, docs } = collectDeviceDocFolds(devicesRoot);
-    const autoFolds = collectAutoLaunchFolds(autoLaunchPath);
-    const folds = {};
-    for (const [name, config] of Object.entries(docFolds))
-        mergeFold(folds, name, config);
-    for (const [name, config] of Object.entries(autoFolds))
-        mergeFold(folds, name, config);
-    if (Object.keys(folds).length === 0)
+    const self = machineId();
+    // ── 1. Gather ────────────────────────────────────────────────────────────
+    // Central per-device config (the #2458 store).
+    const fleet = readMeta().fleet;
+    const centralDevices = fleet && fleet.devices !== 'all' ? fleet.devices : {};
+    const centralHasConfig = Object.values(centralDevices).some((ov) => ov?.config && Object.keys(ov.config).length > 0);
+    const autoLaunchFlags = readAutoLaunchFlags(autoLaunchPath);
+    const docs = readDeviceDocs(devicesRoot);
+    const pinsPath = getDevicePinsPath();
+    let selfPins = {};
+    try {
+        selfPins = JSON.parse(fs.readFileSync(pinsPath, 'utf-8')) || {};
+    }
+    catch { /* absent or malformed — the fold below recreates it */ }
+    // ── 1b. Plan (pure) — so a converged install never takes the meta lock or
+    //    rewrites a byte-identical doc on every boot.
+    const plans = [];
+    for (const { name, path: docPath, doc } of docs) {
+        const plan = planDeviceDocFold(name, docPath, doc, centralDevices[name]?.config, autoLaunchFlags[name]);
+        if (plan)
+            plans.push(plan);
+    }
+    const docNames = new Set(docs.map((d) => d.name));
+    const newDocs = [];
+    for (const [name, ov] of Object.entries(centralDevices)) {
+        if (docNames.has(name) || !isConfigMap(ov?.config))
+            continue;
+        newDocs.push({ path: path.join(devicesRoot, name, 'agents.yaml'), doc: { config: { ...autoLaunchFlags[name], ...ov.config } } });
+    }
+    for (const [name, flags] of Object.entries(autoLaunchFlags)) {
+        if (docNames.has(name) || isConfigMap(centralDevices[name]?.config))
+            continue;
+        newDocs.push({ path: path.join(devicesRoot, name, 'agents.yaml'), doc: { config: { ...flags } } });
+    }
+    const selfDoc = docs.find((d) => d.name === self);
+    const docAgents = isConfigMap(selfDoc?.doc.agents) ? selfDoc.doc.agents : undefined;
+    const docIsolated = isConfigMap(selfDoc?.doc.isolatedAgents)
+        ? selfDoc.doc.isolatedAgents
+        : undefined;
+    const hasDestinationWork = plans.length > 0 || newDocs.length > 0 || docAgents !== undefined || docIsolated !== undefined;
+    const autoLaunchPending = fs.existsSync(autoLaunchPath);
+    if (!centralHasConfig && !hasDestinationWork && !autoLaunchPending)
         return;
-    // 1. Central write FIRST. A `fleet.devices: all` declaration upgrades to an
-    //    explicit map of the currently-registered roster so `agents apply` keeps
-    //    targeting the same devices. A key already present centrally WINS over
-    //    the legacy value — a re-fold after a mid-migration crash is then a
-    //    no-op, and a value written by a newer CLI is never clobbered.
-    updateMeta((m) => {
-        const devices = fleetDevicesMapForWrite(m.fleet);
-        for (const [name, config] of Object.entries(folds)) {
-            const prev = devices[name] ?? {};
-            devices[name] = { ...prev, config: { ...config, ...prev.config } };
+    // ── 2. Destination writes FIRST (crash-safe), under the meta lock so they
+    //    serialize against writeMetaUnlocked's own read-merge-write of the doc.
+    //    Only taken when there IS a write — a converged install never locks
+    //    (taking it would create a default central agents.yaml as a side effect).
+    if (hasDestinationWork) {
+        withMetaLock(() => {
+            // 2a. THIS machine's pins: doc pins merge INTO the pins file (pins file
+            //     wins — it is the destination, and a re-fold after a crash must not
+            //     clobber pins the new CLI already wrote).
+            if (docAgents || docIsolated) {
+                const pins = { ...selfPins };
+                if (docAgents)
+                    pins.agents = { ...docAgents, ...selfPins.agents };
+                if (docIsolated)
+                    pins.isolatedAgents = { ...docIsolated, ...selfPins.isolatedAgents };
+                try {
+                    fs.mkdirSync(path.dirname(pinsPath), { recursive: true });
+                    atomicWriteFileSync(pinsPath, JSON.stringify(pins, null, 2) + '\n');
+                }
+                catch (err) {
+                    console.error(`device config migration: could not write ${pinsPath} (${err.message}); a later run retries`);
+                }
+            }
+            // 2b/2c. The planned doc rewrites + creations.
+            for (const plan of plans)
+                writeDeviceDoc(plan.path, plan.next);
+            for (const nd of newDocs)
+                writeDeviceDoc(nd.path, nd.doc);
+        });
+    }
+    // ── 3. Source strips LAST ────────────────────────────────────────────────
+    // 3a. Central: drop every devices.<name>.config block (now folded into the
+    //     device docs). Overrides left with no other fields are dropped; an
+    //     emptied fleet block (no defaults/secrets/routines) goes away entirely.
+    if (centralHasConfig) {
+        updateMeta((m) => {
+            const devices = m.fleet?.devices;
+            if (!devices || devices === 'all')
+                return m;
+            const nextDevices = {};
+            for (const [name, ov] of Object.entries(devices)) {
+                const rest = { ...ov };
+                delete rest.config;
+                if (Object.keys(rest).length > 0)
+                    nextDevices[name] = rest;
+            }
+            const fleet = { ...m.fleet, devices: nextDevices };
+            if (Object.keys(nextDevices).length === 0 && !fleet.defaults && !fleet.secrets && !fleet.routines) {
+                const { fleet: _, ...rest } = m;
+                void _;
+                return rest;
+            }
+            return { ...m, fleet };
+        });
+    }
+    // 3b. The legacy auto-launch.json.
+    if (autoLaunchPending) {
+        try {
+            fs.rmSync(autoLaunchPath, { force: true });
         }
-        const fleet = { ...m.fleet, devices };
-        return { ...m, fleet };
-    });
-    // 2. The legacy stores are deliberately LEFT IN PLACE.
-    //
-    //    This migration used to delete them — `fs.rmSync` on the device doc and
-    //    `fs.rmdirSync` on its directory. Deleting is what made the fold unsafe
-    //    to run anywhere: it had to win a race against every other machine's copy
-    //    of the same shared file, and a box on an older CLI that re-created the
-    //    doc would be stripped again on the next command.
-    //
-    //    An additive fold has neither problem. The central block is written; the
-    //    source is untouched; a box still running the previous CLI keeps reading
-    //    what it always read. The now-redundant legacy copy is pruned in a later
-    //    release by one explicit operator command, not by 13 machines each
-    //    deciding to delete on their own schedule.
-    void docs;
-    void autoLaunchPath;
+        catch (err) {
+            console.error(`device config migration: could not remove ${autoLaunchPath} (${err.message}); a later run retries`);
+        }
+    }
+}
+/** Shallow-set equality for folded doc content (values compared deep via JSON). */
+function sameDocContent(a, b) {
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    return ak.every((k) => k in b && JSON.stringify(a[k]) === JSON.stringify(b[k]));
+}
+/**
+ * Compute a device doc's post-fold content: merge the config layers (oldest
+ * auto-launch.json flags < the doc's own config: < the central #2458 block —
+ * newest wins), fold a top-level defaultBrowserProfile into config:, and strip
+ * pins from the tracked file. Returns null when the doc is corrupt (loudly —
+ * left for manual repair) or the fold would not change its content.
+ */
+function planDeviceDocFold(name, docPath, doc, centralConfig, autoFlags) {
+    const config = {};
+    Object.assign(config, autoFlags);
+    if (doc.config !== undefined) {
+        if (!isConfigMap(doc.config)) {
+            console.error(`device config migration: ${docPath} has a non-map config: block; leaving it for manual repair`);
+            return null;
+        }
+        Object.assign(config, doc.config);
+    }
+    if (typeof doc.defaultBrowserProfile === 'string' && config.defaultBrowserProfile === undefined) {
+        config.defaultBrowserProfile = doc.defaultBrowserProfile;
+    }
+    if (isConfigMap(centralConfig))
+        Object.assign(config, centralConfig);
+    const next = {};
+    // Preserve fields the migration does not own (routines:, anything else).
+    for (const [k, v] of Object.entries(doc)) {
+        if (k === 'config' || k === 'defaultBrowserProfile' || k === 'agents' || k === 'isolatedAgents')
+            continue;
+        next[k] = v;
+    }
+    if (Object.keys(config).length > 0)
+        next.config = config;
+    return sameDocContent(next, doc) ? null : { name, path: docPath, next };
 }

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

@@ -44,7 +44,7 @@ export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]):
  * (`mirrorCwd` is undefined, or resolves to the home root itself) so the caller
  * keeps the plain no-command interactive login.
  *
- * This is the interactive analogue of `agents run --host`'s cwd mirroring, and
+ * This is the interactive analogue of `agents run --device`'s cwd mirroring, and
  * it reuses the SAME machinery so there is no second resolver: the portable
  * `mirrorCwd` comes from `deriveMirroredCwd`, and — for POSIX — the best-effort
  * `cd` comes from `remoteCdPrefix({ mirror: true })`, whose `|| cd "$HOME"`
@@ -94,7 +94,7 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
  * interactive login (no `cmd`) — from `deriveMirroredCwd(process.cwd())`. When
  * it names a real home-relative sub-path, the login starts there via
  * {@link buildInteractiveShellCommand} (best-effort — a missing dir falls back
- * to the remote home), matching `agents run --host`. It is ignored when a `cmd`
+ * to the remote home), matching `agents run --device`. It is ignored when a `cmd`
  * is given: an explicit command keeps its current cwd (the remote home) and its
  * behavior unchanged (RUSH-2412).
  */

package/dist/lib/devices/connect.js

@@ -93,7 +93,7 @@ export function wrapRemoteCommand(device, cmd) {
  * (`mirrorCwd` is undefined, or resolves to the home root itself) so the caller
  * keeps the plain no-command interactive login.
  *
- * This is the interactive analogue of `agents run --host`'s cwd mirroring, and
+ * This is the interactive analogue of `agents run --device`'s cwd mirroring, and
  * it reuses the SAME machinery so there is no second resolver: the portable
  * `mirrorCwd` comes from `deriveMirroredCwd`, and — for POSIX — the best-effort
  * `cd` comes from `remoteCdPrefix({ mirror: true })`, whose `|| cd "$HOME"`
@@ -153,7 +153,7 @@ export function deviceIdentityArgs(device) {
  * interactive login (no `cmd`) — from `deriveMirroredCwd(process.cwd())`. When
  * it names a real home-relative sub-path, the login starts there via
  * {@link buildInteractiveShellCommand} (best-effort — a missing dir falls back
- * to the remote home), matching `agents run --host`. It is ignored when a `cmd`
+ * to the remote home), matching `agents run --device`. It is ignored when a `cmd`
  * is given: an explicit command keeps its current cwd (the remote home) and its
  * behavior unchanged (RUSH-2412).
  */

package/dist/lib/devices/discovery-policy.d.ts

@@ -0,0 +1,30 @@
+export type DeviceDiscoveryStatus = 'approved' | 'ignored';
+export interface DeviceDiscoveryReconcileResult {
+    approved: string[];
+    ignored: string[];
+    registered: string[];
+    unresolved: string[];
+}
+/** Read one portable decision. Absence means pending. */
+export declare function getDeviceDiscoveryStatus(name: string): DeviceDiscoveryStatus | undefined;
+/** Persist one portable decision in the central fleet manifest. */
+export declare function setDeviceDiscoveryStatus(name: string, status: DeviceDiscoveryStatus | undefined): void;
+/** Load every explicit decision from the synced central fleet manifest. */
+export declare function loadDeviceDiscoveryPolicies(): Map<string, DeviceDiscoveryStatus>;
+/**
+ * Apply synced intent to this machine's local registry. Approval resolves live
+ * Tailscale metadata; ignore never needs the network. Missing approved peers are
+ * reported as unresolved rather than written with invented connection details.
+ *
+ * Only devices with an EXPLICIT entry in the synced policy are touched. A
+ * device absent from the map is left alone, whether or not the map itself is
+ * defined — the map is not treated as authoritative-by-omission, because not
+ * every local registration path writes a policy entry (pair-ios control
+ * devices, daemon/umbrella auto-refresh, and any device registered before this
+ * feature shipped). Wiping those on the next `agents repo pull user` would be
+ * silent, fleet-wide data loss for a decision (e.g. "ignore this one iPad")
+ * that never meant to touch them.
+ */
+export declare function reconcileDeviceDiscoveryPolicies(): Promise<DeviceDiscoveryReconcileResult>;
+/** Complete reconciliation from real `tailscale status --json` output. */
+export declare function registerApprovedDevicesFromTailscale(json: string, approved: string[], ignored: string[], missing: string[]): Promise<DeviceDiscoveryReconcileResult>;

package/dist/lib/devices/discovery-policy.js

@@ -0,0 +1,101 @@
+/** Synced device approval/ignore policy and local registry reconciliation. */
+import { readMeta, updateMeta } from '../state.js';
+import { addIgnored, assertValidDeviceName, loadDevices, removeDevice, removeIgnored, upsertDevice, } from './registry.js';
+import { localLoginUser, withDefaultUser } from './sync.js';
+import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson } from './tailscale.js';
+/** Read one portable decision. Absence means pending. */
+export function getDeviceDiscoveryStatus(name) {
+    assertValidDeviceName(name);
+    return loadDeviceDiscoveryPolicies().get(name);
+}
+/** Persist one portable decision in the central fleet manifest. */
+export function setDeviceDiscoveryStatus(name, status) {
+    assertValidDeviceName(name);
+    updateMeta((meta) => {
+        const discovery = { ...meta.fleet?.discovery };
+        if (status)
+            discovery[name] = status;
+        else
+            delete discovery[name];
+        const fleet = {
+            ...meta.fleet,
+            devices: meta.fleet?.devices ?? {},
+            // Keep an empty map as the synced tombstone: it distinguishes "policy is
+            // authoritative and every device is pending" from an older config that
+            // has never opted into portable discovery decisions.
+            discovery,
+        };
+        return { ...meta, fleet };
+    });
+}
+/** Load every explicit decision from the synced central fleet manifest. */
+export function loadDeviceDiscoveryPolicies() {
+    const policies = new Map();
+    for (const [name, status] of Object.entries(readMeta().fleet?.discovery ?? {})) {
+        assertValidDeviceName(name);
+        if (status !== 'approved' && status !== 'ignored') {
+            throw new Error(`Device discovery policy for '${name}' must be approved or ignored.`);
+        }
+        policies.set(name, status);
+    }
+    return policies;
+}
+/**
+ * Apply synced intent to this machine's local registry. Approval resolves live
+ * Tailscale metadata; ignore never needs the network. Missing approved peers are
+ * reported as unresolved rather than written with invented connection details.
+ *
+ * Only devices with an EXPLICIT entry in the synced policy are touched. A
+ * device absent from the map is left alone, whether or not the map itself is
+ * defined — the map is not treated as authoritative-by-omission, because not
+ * every local registration path writes a policy entry (pair-ios control
+ * devices, daemon/umbrella auto-refresh, and any device registered before this
+ * feature shipped). Wiping those on the next `agents repo pull user` would be
+ * silent, fleet-wide data loss for a decision (e.g. "ignore this one iPad")
+ * that never meant to touch them.
+ */
+export async function reconcileDeviceDiscoveryPolicies() {
+    const configured = readMeta().fleet?.discovery;
+    if (configured === undefined) {
+        return { approved: [], ignored: [], registered: [], unresolved: [] };
+    }
+    const policies = loadDeviceDiscoveryPolicies();
+    const approved = [...policies].filter(([, s]) => s === 'approved').map(([n]) => n).sort();
+    const ignored = [...policies].filter(([, s]) => s === 'ignored').map(([n]) => n).sort();
+    for (const name of ignored) {
+        await removeDevice(name);
+        await addIgnored(name);
+    }
+    for (const name of approved)
+        await removeIgnored(name);
+    const currentRegistry = await loadDevices();
+    const missing = approved.filter((name) => !currentRegistry[name]);
+    if (missing.length === 0)
+        return { approved, ignored, registered: [], unresolved: [] };
+    let json;
+    try {
+        json = tailscaleStatusJson();
+    }
+    catch {
+        return { approved, ignored, registered: [], unresolved: missing };
+    }
+    return registerApprovedDevicesFromTailscale(json, approved, ignored, missing);
+}
+/** Complete reconciliation from real `tailscale status --json` output. */
+export async function registerApprovedDevicesFromTailscale(json, approved, ignored, missing) {
+    const nodes = parseTailscaleStatus(json);
+    const byName = new Map(nodes.map((node) => [node.name, node]));
+    const registered = [];
+    const unresolved = [];
+    const user = localLoginUser();
+    for (const name of missing) {
+        const node = byName.get(name);
+        if (!node) {
+            unresolved.push(name);
+            continue;
+        }
+        await upsertDevice(name, withDefaultUser(nodeToDeviceInput(node), undefined, user));
+        registered.push(name);
+    }
+    return { approved, ignored, registered, unresolved };
+}