@phnx-labs/agents-cli 1.22.43 → 1.22.45

package/dist/lib/session/watch.js

@@ -1,242 +1,3 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { createInterface } from 'node:readline';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
-import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
-import { machineId, normalizeHost } from '../machine-id.js';
-import { SSH_OPTS, controlOpts, shellQuote } from '../ssh-exec.js';
-import { buildWindowsAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
-import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, } from './session-cache.js';
-export const SESSION_WATCH_VERSION = 1;
-export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
-/** Stable, opaque identity for one row within one device scope. */
-export function sessionWatchRowKey(scope, row) {
-    const identity = activeSessionJournalIdentity(row);
-    return createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
-}
-export function toSessionWatchRow(scope, row) {
-    const rowKey = sessionWatchRowKey(scope, row);
-    const resumable = Boolean(row.sessionId);
-    const viewingIn = row.viewingIn
-        ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
-        : null;
-    return {
-        ...row,
-        rowKey,
-        sourceDevice: scope,
-        resumable,
-        unwatched: !viewingIn,
-        viewingIn,
-        recovery: resumable
-            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', scope], ...(row.cwd ? { cwd: row.cwd } : {}) }
-            : null,
-    };
-}
-function sameRow(a, b) {
-    return JSON.stringify(a) === JSON.stringify(b);
-}
-/** Stream-local sequencer and convergent row diff. */
-export class SessionWatchState {
-    streamId;
-    sequence = 0;
-    rows = new Map();
-    constructor(streamId = randomUUID()) { this.streamId = streamId; }
-    base(type) {
-        return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
-    }
-    reset(scope, sourceRows) {
-        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
-        return { ...this.base('reset'), scope, rows };
-    }
-    update(scope, sourceRows) {
-        const previous = this.rows.get(scope) ?? new Map();
-        const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
-        const events = [];
-        for (const [rowKey, row] of next) {
-            if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
-                events.push({ ...this.base('upsert'), scope, rowKey, row });
-            }
-        }
-        for (const rowKey of previous.keys()) {
-            if (!next.has(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
-        }
-        this.rows.set(scope, next);
-        return events;
-    }
-    patch(scope, upserts, removes) {
-        const current = new Map(this.rows.get(scope) ?? []);
-        const events = [];
-        for (const source of upserts) {
-            const row = toSessionWatchRow(scope, source);
-            if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
-                current.set(row.rowKey, row);
-                events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
-            }
-        }
-        for (const identity of removes) {
-            const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
-            if (current.delete(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
-        }
-        this.rows.set(scope, current);
-        return events;
-    }
-    scope(scope, status, reason) {
-        // Deliberately retain rows while unavailable. A reconnecting scope replaces
-        // them with a reset; transient fleet loss must not look like session death.
-        return { ...this.base('scope'), scope, status, ...(reason ? { reason } : {}) };
-    }
-    heartbeat(scope, capturedAt = Date.now()) {
-        return { ...this.base('heartbeat'), scope, capturedAt };
-    }
-}
-/**
- * Keep one local subscription alive. Startup reads one canonical reset snapshot;
- * steady state tails the canonical writer journal and never invokes a gather.
- */
-export async function watchLocalSessions(options) {
-    const state = new SessionWatchState();
-    const readCache = options.readCache ?? readActiveSessionsCache;
-    const journal = options.journalPath ?? activeSessionsJournalPath();
-    const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
-    let offset = 0;
-    try {
-        offset = fs.statSync(journal).size;
-    }
-    catch { /* first publication */ }
-    const initial = readCache('local');
-    options.emit(state.reset(options.scope, initial?.sessions ?? []));
-    options.emit(state.scope(options.scope, initial ? 'available' : 'unavailable', initial ? undefined : 'awaiting publisher'));
-    if (options.signal.aborted)
-        return;
-    await new Promise((resolve) => {
-        let partial = '';
-        let reading = false;
-        const readAppended = () => {
-            if (reading || options.signal.aborted)
-                return;
-            reading = true;
-            try {
-                const size = fs.statSync(journal).size;
-                if (size < offset) {
-                    offset = 0;
-                    partial = '';
-                }
-                if (size === offset)
-                    return;
-                const fd = fs.openSync(journal, 'r');
-                try {
-                    const buffer = Buffer.alloc(size - offset);
-                    fs.readSync(fd, buffer, 0, buffer.length, offset);
-                    offset = size;
-                    const lines = (partial + buffer.toString('utf8')).split('\n');
-                    partial = lines.pop() ?? '';
-                    for (const line of lines) {
-                        if (!line)
-                            continue;
-                        try {
-                            const record = JSON.parse(line);
-                            if (record.version !== 1 || record.scope !== 'local' || !Array.isArray(record.upserts) || !Array.isArray(record.removes))
-                                continue;
-                            for (const event of state.patch(options.scope, record.upserts, record.removes))
-                                options.emit(event);
-                            options.emit(state.scope(options.scope, 'available'));
-                        }
-                        catch { /* partial/corrupt journal lines are not state */ }
-                    }
-                }
-                finally {
-                    fs.closeSync(fd);
-                }
-            }
-            catch { /* journal may not exist until the first publisher write */ }
-            finally {
-                reading = false;
-            }
-        };
-        fs.mkdirSync(path.dirname(journal), { recursive: true });
-        const journalListener = () => readAppended();
-        fs.watchFile(journal, { interval: options.journalPollMs ?? 250 }, journalListener);
-        const heartbeatTimer = setInterval(() => options.emit(state.heartbeat(options.scope)), heartbeatMs);
-        const stop = () => { fs.unwatchFile(journal, journalListener); clearInterval(heartbeatTimer); resolve(); };
-        options.signal.addEventListener('abort', stop, { once: true });
-        // Close the offset/read/watch handoff: a publisher may append after the
-        // startup offset is captured but before watchFile is registered.
-        readAppended();
-    });
-}
-function remoteWatchCommand(os) {
-    const args = ['sessions', 'watch', '--json', '--local'];
-    return remoteShellFor(os) === 'powershell'
-        ? buildWindowsAgentsCommand({ args })
-        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
-}
-/**
- * Subscribe to every dialable compute device with one persistent SSH process.
- * A peer disconnect emits `scope: unavailable` but no removes; reconnecting
- * peer resets only its own scope. There is no recurring fleet list command.
- */
-export async function watchFleetSessions(options) {
-    const local = watchLocalSessions({ scope: machineId(), signal: options.signal, emit: options.emit });
-    let devices;
-    try {
-        devices = await loadDevices();
-    }
-    catch {
-        await local;
-        return;
-    }
-    const self = machineId();
-    const peers = Object.values(devices).filter((device) => isDialableDevice(device)
-        && !isControlDevice(device)
-        && normalizeHost(device.name) !== self
-        && ['windows', 'linux', 'macos'].includes(device.platform));
-    const reconnectMs = options.reconnectMs ?? 2_000;
-    const peerTasks = peers.map(async (device) => {
-        const scope = normalizeHost(device.name);
-        const state = new SessionWatchState();
-        while (!options.signal.aborted) {
-            let target;
-            try {
-                target = sshTargetFor(device);
-            }
-            catch (error) {
-                options.emit(state.scope(scope, 'unavailable', error instanceof Error ? error.message : String(error)));
-                break;
-            }
-            const child = spawn('ssh', [
-                ...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteWatchCommand(device.platform),
-            ], { stdio: ['ignore', 'pipe', 'ignore'] });
-            const stop = () => child.kill('SIGTERM');
-            options.signal.addEventListener('abort', stop, { once: true });
-            const reader = createInterface({ input: child.stdout });
-            reader.on('line', (line) => {
-                try {
-                    const event = JSON.parse(line);
-                    if (event.version === SESSION_WATCH_VERSION && typeof event.sequence === 'number')
-                        options.emit(event);
-                }
-                catch { /* incomplete/non-protocol peer output is not state */ }
-            });
-            const code = await new Promise((resolve) => {
-                child.once('error', () => resolve(null));
-                child.once('close', resolve);
-            });
-            reader.close();
-            options.signal.removeEventListener('abort', stop);
-            if (options.signal.aborted)
-                break;
-            options.emit(state.scope(scope, 'unavailable', code === null ? 'ssh failed' : `ssh exited ${code}`));
-            await new Promise((resolve) => {
-                const timer = setTimeout(resolve, reconnectMs);
-                options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
-            });
-        }
-    });
-    await Promise.all([local, ...peerTasks]);
-}
+// Moved to ./remote/watch.ts (move 4 of the core-module refactor).
+// Kept as a re-export shim so existing importers don't break.
+export * from './remote/watch.js';

package/dist/lib/share/config.d.ts

@@ -22,9 +22,19 @@ export declare const DEFAULT_BUCKET_NAME = "agents-share";
 export declare const DEFAULT_SHARE_DOMAIN = "share.agents-cli.sh";
 /** The write token may be injected ephemerally into fleet/cloud agents. */
 export declare function readWriteTokenEnv(env?: NodeJS.ProcessEnv): string | null;
-/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
+/**
+ * Read the persisted endpoint config, or null if there is no `share.baseUrl`.
+ *
+ * Publish talks only to `baseUrl` with `WRITE_TOKEN`. `accountId` / worker /
+ * bucket are provisioning metadata for `setup`/`update`. Requiring all four
+ * (and treating `accountId: ""` as missing) made `status` and publish both
+ * report "not set up" on an endpoint that still worked — RUSH-2837.
+ */
 export declare function readShareConfig(): ShareConfig | null;
-/** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
+/** Persist the endpoint config to `agents.yaml` (syncs across the fleet).
+ * Empty strings never overwrite a previously stored value and are not written
+ * back as `accountId: ""` (that form made {@link readShareConfig} return null
+ * under the old all-fields-required check, and it is still useless). */
 export declare function writeShareConfig(cfg: ShareConfig): void;
 /** A fresh 32-byte hex write token. */
 export declare function generateWriteToken(): string;

package/dist/lib/share/config.js

@@ -23,24 +23,60 @@ export function readWriteTokenEnv(env = process.env) {
     const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
     return token ? token : null;
 }
-/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
+/** Trim; empty / whitespace-only strings are absent. */
+function nonempty(v) {
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+/**
+ * Read the persisted endpoint config, or null if there is no `share.baseUrl`.
+ *
+ * Publish talks only to `baseUrl` with `WRITE_TOKEN`. `accountId` / worker /
+ * bucket are provisioning metadata for `setup`/`update`. Requiring all four
+ * (and treating `accountId: ""` as missing) made `status` and publish both
+ * report "not set up" on an endpoint that still worked — RUSH-2837.
+ */
 export function readShareConfig() {
     const s = readMeta().share;
-    if (!s?.baseUrl || !s.accountId || !s.workerName || !s.bucketName)
+    const baseUrl = nonempty(s?.baseUrl)?.replace(/\/+$/, '');
+    if (!baseUrl)
         return null;
     return {
-        baseUrl: s.baseUrl.replace(/\/+$/, ''),
-        accountId: s.accountId,
-        workerName: s.workerName,
-        bucketName: s.bucketName,
-        domain: s.domain,
-        analyticsToken: s.analyticsToken,
-        templateHash: s.templateHash,
+        baseUrl,
+        accountId: nonempty(s?.accountId) ?? '',
+        workerName: nonempty(s?.workerName) ?? DEFAULT_WORKER_NAME,
+        bucketName: nonempty(s?.bucketName) ?? DEFAULT_BUCKET_NAME,
+        domain: nonempty(s?.domain),
+        analyticsToken: nonempty(s?.analyticsToken),
+        templateHash: nonempty(s?.templateHash),
     };
 }
-/** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
+/** Persist the endpoint config to `agents.yaml` (syncs across the fleet).
+ * Empty strings never overwrite a previously stored value and are not written
+ * back as `accountId: ""` (that form made {@link readShareConfig} return null
+ * under the old all-fields-required check, and it is still useless). */
 export function writeShareConfig(cfg) {
-    updateMeta((meta) => ({ ...meta, share: { ...meta.share, ...cfg } }));
+    updateMeta((meta) => {
+        const prev = meta.share ?? {};
+        const next = { ...prev };
+        const assign = (key, incoming) => {
+            const v = nonempty(incoming);
+            if (v)
+                next[key] = v;
+        };
+        assign('baseUrl', cfg.baseUrl);
+        assign('accountId', cfg.accountId);
+        assign('workerName', cfg.workerName);
+        assign('bucketName', cfg.bucketName);
+        assign('domain', cfg.domain);
+        assign('analyticsToken', cfg.analyticsToken);
+        assign('templateHash', cfg.templateHash);
+        for (const key of Object.keys(next)) {
+            if (typeof next[key] === 'string' && !nonempty(next[key]))
+                delete next[key];
+        }
+        return { ...meta, share: next };
+    });
 }
 /** A fresh 32-byte hex write token. */
 export function generateWriteToken() {

package/dist/lib/share/delete.js

@@ -1,4 +1,4 @@
-// The delete path for `agents artifacts share delete` / `agents unshare` — an authed DELETE
+// The delete path for `agents artifacts share delete` / `agents artifacts unshare` — an authed DELETE
 // to the Worker, which already implements it (worker-template.ts). Mirrors
 // publish.ts: pure target-resolution logic is exported for tests, the network
 // calls (a status check + a delete) sit behind an injectable DI seam.

package/dist/lib/share/publish.js

@@ -459,7 +459,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // strings unless --force. Runs on the raw file body AND on every piece of
     // free-text metadata that lands in public customMetadata — --label (explicit
     // or derived) and every --meta value. Metadata is visible in the gallery,
-    // `share list --json`, and `share revisions` just like the page itself, so a
+    // `share list --list-json`, and `share revisions` just like the page itself, so a
     // credential smuggled in there is exactly as exposed as one in the body; it
     // must not have a free pass around this gate. Runs before analytics/cover
     // mutation so a beacon injection never triggers a false positive on the body

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

@@ -21,8 +21,8 @@
 //   - GET  /<slug>             — backward-compat flat slug (legacy shares before
 //     per-user namespaces).
 //
-// Emitted as a string (mirrors src/lib/serve/page.ts `renderPage()`), so it compiles
-// into `dist/**` and ships with no package.json#files change. `provision.ts` uploads
+// Emitted as a string, so it compiles into `dist/**` and ships with no
+// package.json#files change. `provision.ts` uploads
 // this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
 /**
  * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.

package/dist/lib/smart-launch.d.ts

@@ -34,9 +34,7 @@ export declare function sampleWeighted(candidates: WeightedCandidate[], rng?: ()
  * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
  * marking workers moves every `--device auto` at once instead of one surface.
  *
- * Paired cockpits (`role: control` in the device registry) are dropped here,
- * where the registry is already being read — they are control surfaces, not
- * compute. It CAN return an empty list — a fleet where every marked worker is
+ * It CAN return an empty list — a fleet where every marked worker is
  * offline, or where this box is the only candidate and is marked `personal`. That is a
  * real answer, and both callers fail loud on it rather than falling back to the
  * local machine (which would be the exact box the operator marked personal to
@@ -94,6 +92,8 @@ export declare function formatNoHealthyDeviceError(pool: string[], signals: Map<
 export declare function resolveDeviceAuto(agent?: string, opts?: {
     eligibleHosts?: string[];
     localMachine?: string;
+    /** Route only to devices with a row the interactive account picker can launch. */
+    accountPicker?: boolean;
     probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
 }): Promise<DeviceAutoPlan>;
 /**
@@ -136,7 +136,7 @@ export type DeviceAutoApplyResult = {
  * `auto`, so callers fail loud instead of silently launching locally.
  */
 export declare function applyDeviceAutoToOptions(options: DeviceAutoHostOptions, deps?: {
-    resolve?: () => DeviceAutoPlan | Promise<DeviceAutoPlan>;
+    resolve?: (accountPicker: boolean) => DeviceAutoPlan | Promise<DeviceAutoPlan>;
     agent?: string;
     accountPickerRequested?: boolean;
 }): Promise<DeviceAutoApplyResult>;

package/dist/lib/smart-launch.js

@@ -7,12 +7,11 @@
  */
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
-import { isControlDevice, loadDevicesSync } from './devices/registry.js';
+import { loadDevicesSync } from './devices/registry.js';
 import { describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
-import { getAccountInfo } from './agents.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export const DEFAULT_AFFINITY_ALPHA = 1.3;
 /**
@@ -55,9 +54,7 @@ export function sampleWeighted(candidates, rng = Math.random) {
  * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
  * marking workers moves every `--device auto` at once instead of one surface.
  *
- * Paired cockpits (`role: control` in the device registry) are dropped here,
- * where the registry is already being read — they are control surfaces, not
- * compute. It CAN return an empty list — a fleet where every marked worker is
+ * It CAN return an empty list — a fleet where every marked worker is
  * offline, or where this box is the only candidate and is marked `personal`. That is a
  * real answer, and both callers fail loud on it rather than falling back to the
  * local machine (which would be the exact box the operator marked personal to
@@ -74,10 +71,6 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
             // No tailscale snapshot → treat as candidate (registry-only box).
             if (online === false)
                 continue;
-            // A paired cockpit (iPhone/iPad) is a control surface, not compute — it
-            // is never dialed for a session, so it is never a placement candidate.
-            if (isControlDevice(d))
-                continue;
             names.add(normalizeHost(name));
         }
     }
@@ -147,18 +140,15 @@ export async function resolveDeviceAuto(agent, opts = {}) {
                 signals.set(key, { ...current, installed: accountEligible, signedIn: accountEligible });
         }
     }
-    if (agent && !opts.probe && signals.has(local)) {
-        const info = await getAccountInfo(agent).catch(() => null);
-        const eligible = !!info?.signedIn && info.usageStatus !== 'rate_limited' && info.usageStatus !== 'out_of_credits';
-        signals.set(local, { ...signals.get(local), signedIn: eligible });
-    }
     const eligiblePool = pool.filter((key) => {
         const signal = signals.get(key);
         if (signal?.reachable !== true || signal.headroom === 'loaded')
             return false;
         if (!agent)
             return opts.probe ? true : signal.installed === true && signal.signedIn === true;
-        return signal.installed === true && signal.signedIn === true;
+        return signal.installed === true && (opts.accountPicker === true
+            ? signal.pickerEligible === true
+            : signal.signedIn === true);
     });
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
@@ -260,15 +250,15 @@ export async function applyDeviceAutoToOptions(options, deps = {}) {
     if (!hasAuto) {
         return { attempted: false, deprecationSmart };
     }
-    const resolve = deps.resolve ?? (() => resolveDeviceAuto(deps.agent));
-    const plan = await resolve();
+    const accountPickerRequested = deps.accountPickerRequested ?? false;
+    const resolve = deps.resolve ?? ((accountPicker) => resolveDeviceAuto(deps.agent, { accountPicker }));
+    const plan = await resolve(accountPickerRequested);
     const concrete = plan.host; // null = local
     for (const k of HOST_SLOTS) {
         if (isDeviceAuto(options[k])) {
             options[k] = concrete ?? undefined;
         }
     }
-    const accountPickerRequested = deps.accountPickerRequested ?? false;
     if (!accountPickerRequested && !options.strategy && !options.balanced) {
         options.balanced = true;
     }

package/dist/lib/staleness/index.d.ts

@@ -4,7 +4,9 @@
  *
  *   - `buildManifest(agent, version, cwd)` — snapshot current state.
  *   - `isStale(manifest, agent, version, cwd)` — true when any tracked
- *     resource has drifted from its stored fingerprint.
+ *     resource has drifted from its stored fingerprint, or when an artifact
+ *     the last full sync wrote (`writtenTargets`) has been deleted from the
+ *     version home (#2398).
  *
  * `loadManifest` / `saveManifest` round-trip the on-disk JSON. The format
  * version stays at 1; new optional fields (workflows, plugins) on old files

package/dist/lib/staleness/index.js

@@ -4,7 +4,9 @@
  *
  *   - `buildManifest(agent, version, cwd)` — snapshot current state.
  *   - `isStale(manifest, agent, version, cwd)` — true when any tracked
- *     resource has drifted from its stored fingerprint.
+ *     resource has drifted from its stored fingerprint, or when an artifact
+ *     the last full sync wrote (`writtenTargets`) has been deleted from the
+ *     version home (#2398).
  *
  * `loadManifest` / `saveManifest` round-trip the on-disk JSON. The format
  * version stays at 1; new optional fields (workflows, plugins) on old files
@@ -91,6 +93,12 @@ export function buildManifest(agent, version, cwd, previous) {
         subagents: {},
         workflows: {},
         plugins: {},
+        // Empty baseline ("nothing recorded to verify"). The full-sync
+        // orchestrator (versions.ts) replaces this with the writer-reported
+        // artifact paths right before saving; a manifest built outside that path
+        // simply verifies nothing. Only an ABSENT field (a pre-upgrade manifest
+        // on disk) forces the one-time migration re-sync in isStale.
+        writtenTargets: [],
     };
     for (const { checker, field } of STANDARD_CHECKERS) {
         const target = manifest[field];
@@ -143,5 +151,17 @@ export function isStale(manifest, agent, version, cwd) {
         return true;
     if (isRulesStale(manifest.rules, agent, version, cwd))
         return true;
+    // Home-side deletion check (#2398): every artifact the last full sync wrote
+    // must still exist, or the version home has rotted and needs a re-sync —
+    // regardless of source fingerprints. One existsSync per path, no content
+    // reads, so the fast-guard budget holds (RUSH-2320). A manifest that
+    // predates the field reads as stale once so the next full sync records the
+    // baseline (same precedent as the optional workflows/plugins maps).
+    if (manifest.writtenTargets === undefined)
+        return true;
+    for (const target of manifest.writtenTargets) {
+        if (!fs.existsSync(target))
+            return true;
+    }
     return false;
 }

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

@@ -54,4 +54,15 @@ export interface SyncManifest {
     subagents: Record<string, DirEntry>;
     workflows?: Record<string, DirEntry>;
     plugins?: Record<string, PluginEntry>;
+    /**
+     * Absolute paths of the artifacts the last full sync materialized in the
+     * version home (writer-reported — see `WriteResult.paths`). `isStale`
+     * treats a missing path as stale so a deleted resource is restored by a
+     * plain `agents sync`, not only `--force` (#2398). An absent field means a
+     * pre-upgrade manifest: it reads as stale once, and the resulting full sync
+     * establishes the baseline — same migration precedent as the optional
+     * `workflows`/`plugins` maps above. An empty array is a valid baseline
+     * ("nothing recorded to verify"), never a migration trigger.
+     */
+    writtenTargets?: string[];
 }

package/dist/lib/staleness/writers/commands.js

@@ -25,7 +25,7 @@ import { supports } from '../../capabilities.js';
 import { safeJoin } from '../../paths.js';
 import { markdownToToml } from '../../convert.js';
 import { commandAppliesTo, parseCommandMetadata } from '../../commands.js';
-import { installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
+import { commandSkillName, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../../command-skills.js';
 import { installGooseCommandToVersion, listGooseCommandsInVersion, removeGooseCommandFromVersion, } from '../../goose-commands.js';
 import { resolveCommandSource, trustedSkillRoots } from './sources.js';
 import { lazyAgentMap } from './lazy-map.js';
@@ -50,6 +50,7 @@ function buildCommandsWriter(agent) {
                 fs.mkdirSync(commandsTarget, { recursive: true });
             }
             const synced = [];
+            const paths = [];
             for (const cmd of selection) {
                 const srcFile = resolveCommandSource(cmd);
                 if (!srcFile)
@@ -63,9 +64,13 @@ function buildCommandsWriter(agent) {
                     // which is a deliberate no-op, not a failure — the native file is still written.
                     if (!installed.success)
                         continue;
+                    if (!installed.skipped) {
+                        paths.push(safeJoin(path.join(agentDir, 'skills'), commandSkillName(cmd)));
+                    }
                 }
                 if (supportsCommands && agent === 'goose') {
                     // Goose: recipe YAML + config.yaml slash_commands entry, not a file copy.
+                    // No artifact path recorded — the recipe layout lives in goose-commands.ts.
                     const installed = installGooseCommandToVersion(versionHome, cmd, srcFile);
                     if (!installed.success)
                         continue;
@@ -73,14 +78,18 @@ function buildCommandsWriter(agent) {
                 else if (supportsCommands && agentConfig.format === 'toml') {
                     const content = fs.readFileSync(srcFile, 'utf-8');
                     const tomlContent = markdownToToml(cmd, content);
-                    fs.writeFileSync(safeJoin(commandsTarget, `${cmd}.toml`), tomlContent);
+                    const dest = safeJoin(commandsTarget, `${cmd}.toml`);
+                    fs.writeFileSync(dest, tomlContent);
+                    paths.push(dest);
                 }
                 else if (supportsCommands) {
-                    fs.copyFileSync(srcFile, safeJoin(commandsTarget, `${cmd}.md`));
+                    const dest = safeJoin(commandsTarget, `${cmd}.md`);
+                    fs.copyFileSync(srcFile, dest);
+                    paths.push(dest);
                 }
                 synced.push(cmd);
             }
-            return { synced };
+            return { synced, paths };
         },
         remove({ versionHome, name }) {
             const agentConfig = AGENTS[agent];

package/dist/lib/staleness/writers/hooks.js

@@ -75,6 +75,7 @@ function buildHooksWriter(agent) {
             const hooksTarget = path.join(agentDir, 'hooks');
             fs.mkdirSync(hooksTarget, { recursive: true });
             const synced = [];
+            const paths = [];
             for (const hook of selection) {
                 const srcFile = resolveHookSource(hook);
                 if (!srcFile)
@@ -82,6 +83,7 @@ function buildHooksWriter(agent) {
                 const destFile = safeJoin(hooksTarget, hook);
                 if (copyHookSource(srcFile, destFile)) {
                     synced.push(hook);
+                    paths.push(destFile);
                 }
             }
             // Native hook registration in settings.json/hooks.json. Grok is included
@@ -93,7 +95,7 @@ function buildHooksWriter(agent) {
             if (agent === 'claude' || agent === 'codex' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid' || agent === 'copilot' || agent === 'kiro' || agent === 'goose' || agent === 'cursor' || agent === 'grok' || agent === 'hermes' || agent === 'muse') {
                 registerHooksToSettings(agent, versionHome);
             }
-            return { synced };
+            return { synced, paths };
         },
         remove({ versionHome, name }) {
             // Delete the copied hook artifact from `{agentDir}/hooks/<name>`. Native

package/dist/lib/staleness/writers/mcp.d.ts

@@ -1,10 +1,3 @@
-/**
- * MCP writer — thin dispatcher into `installMcpServers` from `lib/mcp.ts`.
- *
- * The per-agent format handling (Claude CLI, Codex TOML, Cursor JSON, etc.)
- * lives in lib/mcp.ts; we keep it there to avoid the import cycle with
- * `versions.ts`. The writer simply hands the selection to that function.
- */
 import type { AgentId } from '../../types.js';
 import type { ResourceWriter } from './types.js';
 export declare const mcpWriters: Partial<Record<AgentId, ResourceWriter<string[]>>>;