@phnx-labs/agents-cli 1.22.117 → 1.22.118

package/dist/lib/installations/update.js

@@ -6,7 +6,7 @@ import { getBinaryPath, invalidateInstalledVersionsCache, invalidateLiveVersionC
 import { assertValidRelease, selectUpdateStrategy, } from './strategies.js';
 import { listInstallations, readInstallation, recordRelease, writeInstallation } from './store.js';
 import { effectiveUpdatePolicy, isAutoUpdateEnabledForAgent } from './update-policy.js';
-import { isInstallationLikelyActive } from './active-check.js';
+import { describeInstallationActivity, formatInUseDeferral } from './active-check.js';
 import { installationLockTarget, INSTALLATION_LOCK_OPTIONS } from './installation-lock.js';
 /**
  * Move one frozen installation to a new vendor release, preserving its identity.
@@ -88,18 +88,21 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
         return { installation, strategy: strategy.id, fromRelease: installation.releaseVersion, toRelease: target,
             unchanged: true, deferred: 'Update cancelled or automatic update policy changed.', alsoUpdated: [] };
     }
-    if (strategy.transactional && await isInstallationLikelyActive(installation)) {
-        options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active right now (a process or launch lease); `
-            + `not staging release ${target}.`);
-        return {
-            installation,
-            strategy: strategy.id,
-            fromRelease: installation.releaseVersion,
-            toRelease: target,
-            unchanged: true,
-            deferred: 'Account home is in use; retry after its sessions finish.',
-            alsoUpdated: [],
-        };
+    if (strategy.transactional) {
+        const activity = await describeInstallationActivity(installation);
+        if (activity.active) {
+            const name = `${AGENTS[agent].name}@${installation.label}`;
+            options.onProgress?.(`${name} looks active right now; not staging release ${target}.`);
+            return {
+                installation,
+                strategy: strategy.id,
+                fromRelease: installation.releaseVersion,
+                toRelease: target,
+                unchanged: true,
+                deferred: formatInUseDeferral(name, activity),
+                alsoUpdated: [],
+            };
+        }
     }
     let staged = null;
     try {
@@ -179,7 +182,8 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
         // identical pre-stage check above for why this cannot be opt-in: a launch
         // that starts AFTER that first check but before this swap is exactly the
         // window this closes.
-        if (options.shouldCancel?.() || (strategy.transactional && await isInstallationLikelyActive(installation))) {
+        const lateActivity = strategy.transactional ? await describeInstallationActivity(installation) : null;
+        if (options.shouldCancel?.() || lateActivity?.active) {
             options.onProgress?.(`${AGENTS[agent].name}@${installation.label} looks active now (a process or launch lease appeared while `
                 + `${staged.release} was staging); not committing it.`);
             return {
@@ -188,7 +192,9 @@ async function runUpdateInstallation(agent, requestedInstallation, options) {
                 fromRelease: installation.releaseVersion,
                 toRelease: staged.release,
                 unchanged: true,
-                deferred: 'Update cancelled or the account home became active.',
+                deferred: lateActivity?.active
+                    ? formatInUseDeferral(`${AGENTS[agent].name}@${installation.label}`, lateActivity)
+                    : 'Update cancelled while the release was being prepared.',
                 alsoUpdated: [],
             };
         }

package/dist/lib/installations/versions.js

@@ -28,7 +28,7 @@ import { INSTALLATION_RECORD_FILE } from './types.js';
 import { composeWin32CommandLine } from '../platform/index.js';
 import { listInstalledSubagents } from '../subagents.js';
 import { listInstalledWorkflows } from '../workflows.js';
-import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings, installSessionTrackerHookSync, installSessionTrackerHook } from '../hooks/install.js';
+import { parseHookManifest, registerHooksToSettings, selectHookManifest, pruneVersionHomeHookEntriesFromSettings, installSessionTrackerHookSync, installSessionTrackerHook, repairManagedHookRuntimeArtifacts } from '../hooks/install.js';
 import { supports, explainSkip } from '../capabilities.js';
 import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills, marketplaceSpecForName } from '../plugins/plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from '../staleness/index.js';
@@ -1630,6 +1630,17 @@ export function removeVersion(agent, version) {
             pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, version);
         }
     }
+    // The global hook shims embed one SOURCE path. When it pointed into this
+    // version home every shimmed guard would exit 127 (allow) until a self-heal
+    // pass ran, and that pass needs a live daemon. Re-point them now. Best
+    // effort: the removal itself already succeeded, and a repair failure on an
+    // unrelated harness's shim must not abort a bulk removal.
+    try {
+        repairManagedHookRuntimeArtifacts();
+    }
+    catch (err) {
+        console.warn(`hook shim repair after removing ${agent}@${version} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     emit('version.remove', { agent, version });
     return true;
 }

package/dist/lib/manifest.js

@@ -125,7 +125,7 @@ export function createDefaultManifest() {
         defaults: {
             method: 'symlink',
             scope: 'global',
-            agents: ['claude', 'codex', 'gemini', 'cursor', 'opencode'],
+            agents: ['claude', 'codex', 'cursor', 'opencode'],
         },
     };
 }

package/dist/lib/models.js

@@ -113,8 +113,6 @@ export function locateModelSource(agent, version) {
         }
         return null;
     }
-    // gemini is hard-deprecated (no launch path left to validate a model
-    // against), so its bundle is deliberately not parsed for a catalog here.
     if (agent === 'opencode') {
         // The `opencode` shim under node_modules/.bin dispatches to a platform-
         // specific native binary. We don't parse the 100MB binary; we let the CLI

package/dist/lib/open-url.js

@@ -101,68 +101,42 @@ export async function resolveViewer(opts = {}) {
     if (opts.osBrowser)
         return 'os';
     const { getConfigValue } = await import('./device-config.js');
-    const configured = opts.profile ?? (getConfigValue('browser.viewer').value || undefined);
-    // Unset means "follow the profile agents drive" — the whole point is that a
-    // machine with a configured browser stops leaking pages to the OS handler.
-    const { getConfiguredDefaultProfileName, resolveProfileRef, getProfile, isProfileLaunchableHere } = await import('./browser/profiles.js');
-    const name = configured ?? getConfiguredDefaultProfileName();
-    if (!name)
+    // A configured viewer, else the profile agents drive (`browser.profile`) — the
+    // whole point is that a machine with a configured browser stops leaking pages
+    // to the OS handler. Both keys are shared with the standalone `browser` CLI,
+    // whose `show` verb applies exactly this precedence itself; agents-cli resolves
+    // the NAME only to decide viewer-vs-OS, then delegates suitability (Arc/Firefox/
+    // launchable-here) to the engine (PHNX-4101).
+    const name = opts.profile
+        ?? (getConfigValue('browser.viewer').value || undefined)
+        ?? (getConfigValue('browser.profile').value || undefined);
+    if (!name || name === 'os')
         return 'os';
-    if (name === 'os')
-        return 'os';
-    let resolved;
-    try {
-        resolved = await resolveProfileRef(name);
-    }
-    catch (err) {
-        console.error(`[viewer] ${name}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);
-        return 'os';
-    }
-    if (!resolved) {
-        console.error(`[viewer] "${name}" does not resolve to a profile — using the OS browser.`);
-        return 'os';
-    }
-    const profile = await getProfile(resolved);
-    if (!profile) {
-        console.error(`[viewer] profile "${resolved}" is not configured — using the OS browser.`);
-        return 'os';
-    }
-    if (profile.browser === 'arc') {
-        // agents browser can drive an attached Arc's existing tabs, but showing the
-        // user a page needs its OWN fresh tab, and Arc crashes on tab creation over
-        // CDP (Target.createTarget). So Arc is a fine automation profile but never a
-        // viewer — fall back to the OS browser for anything a human is meant to read.
-        console.error(`[viewer] "${resolved}" is Arc, which cannot open a new viewer tab — using the OS browser.`);
-        return 'os';
-    }
-    if (profile.browser === 'firefox') {
-        // agents drives Firefox headless over BiDi for its own read-back; a page a
-        // human is meant to read goes to the visible OS browser, not the headless one.
-        console.error(`[viewer] "${resolved}" is a headless-automation Firefox profile — using the OS browser.`);
-        return 'os';
-    }
-    if (!isProfileLaunchableHere(profile)) {
-        console.error(`[viewer] "${resolved}" cannot launch on this machine — using the OS browser.`);
-        return 'os';
-    }
-    return { profile: resolved };
+    return { profile: name };
 }
 /** Show a URL to the human at this machine. Never throws. */
 export async function showUrl(url, opts = {}) {
     const viewer = await resolveViewer(opts);
     if (viewer === 'os')
         return osOpen(url, opts.spawnOpen);
+    // Delegate to the standalone `browser show`, which opens the URL in the viewer
+    // profile (or `browser.viewer`/`browser.profile`) and owns its own service
+    // lifecycle and viewer-suitability fallbacks. When the engine is not installed,
+    // or the call fails, degrade to the OS handler with one stderr line.
     try {
-        const { sendIPCRequest } = await import('./browser/ipc.js');
-        // Deliberately does NOT auto-start the browser daemon. Showing a page is a
-        // side errand — `devices lease` opens a console and immediately prompts for
-        // a pasted key — so blocking that on a daemon cold start is a surprising
-        // multi-second stall. Daemon already up: use the viewer. Not up: the OS
-        // handler is the fast, correct answer.
-        const response = await sendIPCRequest({ action: 'show', url, profile: viewer.profile }, { autoStartDaemon: false });
-        if (response.ok)
-            return { via: 'profile', profile: viewer.profile, tabId: response.tabId };
-        console.error(`[viewer] ${viewer.profile}: ${response.error} — using the OS browser.`);
+        const { browserInstalled, runBrowser } = await import('./browser-client.js');
+        if (!browserInstalled()) {
+            console.error(`[viewer] the standalone browser CLI is not installed — using the OS browser.`);
+            return osOpen(url, opts.spawnOpen);
+        }
+        const { buildBrowserContext } = await import('./browser/context.js');
+        const { exitCode } = await runBrowser({
+            argv: ['show', url, '--profile', viewer.profile],
+            context: await buildBrowserContext(),
+        });
+        if (exitCode === 0)
+            return { via: 'profile', profile: viewer.profile };
+        console.error(`[viewer] ${viewer.profile}: browser show exited ${exitCode} — using the OS browser.`);
     }
     catch (err) {
         console.error(`[viewer] ${viewer.profile}: ${err instanceof Error ? err.message : String(err)} — using the OS browser.`);

package/dist/lib/profiles.js

@@ -352,7 +352,6 @@ const MODEL_ENV_KEY_BY_HOST = {
     claude: 'ANTHROPIC_MODEL',
     opencode: 'OPENCODE_MODEL',
     grok: 'GROK_MODEL',
-    gemini: 'GEMINI_MODEL',
     codex: 'OPENAI_MODEL',
 };
 /** Base-URL env var per host, for the OpenAI/Anthropic-compatible hosts where it applies. */
@@ -372,7 +371,6 @@ export function baseUrlEnvKeyForHost(host) {
 const AUTH_ENV_KEY_BY_HOST = {
     claude: 'ANTHROPIC_AUTH_TOKEN',
     codex: 'OPENAI_API_KEY',
-    gemini: 'GEMINI_API_KEY',
     grok: 'XAI_API_KEY',
     opencode: 'OPENCODE_API_KEY',
 };

package/dist/lib/refresh.js

@@ -32,7 +32,7 @@ function migratePromptcutsToRoot(agentsDir, quiet = false) {
     const rootPath = path.join(agentsDir, 'promptcuts.yaml');
     if (fs.existsSync(rootPath))
         return;
-    const agentDirs = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+    const agentDirs = ['claude', 'codex', 'cursor', 'opencode'];
     for (const dir of agentDirs) {
         const legacyPath = path.join(agentsDir, dir, 'promptcuts.yaml');
         if (fs.existsSync(legacyPath)) {

package/dist/lib/routine-readiness.d.ts

@@ -11,6 +11,7 @@
  */
 import type { JobConfig } from './scheduling/routines.js';
 import { type RoutineReadinessResult, type RoutineReadiness } from './routine-context.js';
+import { type AuthVerdict } from './auth-health.js';
 /**
  * Fire-time auth preflight: read the daemon-warmed auth-health cache for the
  * exact (agent, version) a routine has resolved to run, and return an
@@ -48,6 +49,40 @@ export declare function parseRemoteProjectSnapshot(stdout: string): {
 export declare function buildRemoteWorkspaceProbe(cwd: string, windows: boolean): string;
 /** A successful probe must contain the exact requested postcondition, not merely exit zero. */
 export declare function probeOutputHasSentinel(stdout: string, sentinel: string): boolean;
+/**
+ * ONE decision the local ({@link evaluateActivationReadinessLive}) and host
+ * ({@link evaluateHostActivationReadiness}) readiness paths share, so both reach
+ * the SAME answer for the same box (PHNX-4116). `row` is that box's probe verdict
+ * for the routine's agent — ABSENT when the box could not probe (a worker's
+ * setup-token box, or a headed box that spent its hourly usage-endpoint budget,
+ * both drop `no_evidence` in `probeLocalFleetAuth`). `launchable` is whether the
+ * box holds a launchable signed-in credential, from the SAME
+ * `collectRunCandidates`/`isLaunchableSignedIn` the run router uses — so a
+ * token-backed routine on a box that cannot probe stays activatable, a box with
+ * no credential at all fails `unconfigured`, and a server rejection (`revoked` —
+ * the only present-but-not-accepted verdict these force-probed paths produce)
+ * blocks regardless of a token on disk.
+ */
+export declare function decideRoutineAuthReadiness(row: {
+    verdict: AuthVerdict;
+} | undefined, launchable: boolean): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * Decide a host-placed routine's auth readiness from the REMOTE box's `devices
+ * ping --local --json` payload (PHNX-4116). Pure over the payload TEXT so it is
+ * unit-tested without SSH: it finds this agent's probe row (ABSENT when the box
+ * dropped its `no_evidence` row) and reads the box's per-agent launchability the
+ * ping now carries, then runs {@link decideRoutineAuthReadiness} — so a host box
+ * that could not probe but holds a token is ready, exactly as the local path
+ * decides for the same box. Returns null when the payload cannot be parsed; the
+ * caller treats that as a probe failure, never as "no credential".
+ */
+export declare function decideHostAuthFromPing(stdout: string, agent: string): {
+    ok: boolean;
+    reason?: string;
+} | null;
 /**
  * Interactive setup/repair readiness. Unlike the scheduler's deterministic
  * structural gate, this completes a real local auth request and reads Codex's

package/dist/lib/routine-readiness.js

@@ -162,6 +162,62 @@ function codexWorkspaceTrusted(version, cwd) {
         return false;
     }
 }
+/**
+ * Verdicts a routine's activation auth check accepts as usable. `no_evidence` is
+ * here for robustness (a payload that still carries one), but a box that cannot
+ * probe DROPS it in {@link probeLocalFleetAuth}, so the real path for those boxes
+ * is the absent-row + launchability fallback in {@link decideRoutineAuthReadiness}
+ * (PHNX-4116).
+ */
+const ROUTINE_AUTH_ACCEPTED = new Set([
+    'live', 'rate_limited', 'unverified', 'no_evidence',
+]);
+/**
+ * ONE decision the local ({@link evaluateActivationReadinessLive}) and host
+ * ({@link evaluateHostActivationReadiness}) readiness paths share, so both reach
+ * the SAME answer for the same box (PHNX-4116). `row` is that box's probe verdict
+ * for the routine's agent — ABSENT when the box could not probe (a worker's
+ * setup-token box, or a headed box that spent its hourly usage-endpoint budget,
+ * both drop `no_evidence` in `probeLocalFleetAuth`). `launchable` is whether the
+ * box holds a launchable signed-in credential, from the SAME
+ * `collectRunCandidates`/`isLaunchableSignedIn` the run router uses — so a
+ * token-backed routine on a box that cannot probe stays activatable, a box with
+ * no credential at all fails `unconfigured`, and a server rejection (`revoked` —
+ * the only present-but-not-accepted verdict these force-probed paths produce)
+ * blocks regardless of a token on disk.
+ */
+export function decideRoutineAuthReadiness(row, launchable) {
+    if (row && ROUTINE_AUTH_ACCEPTED.has(row.verdict))
+        return { ok: true };
+    if (!row)
+        return launchable ? { ok: true } : { ok: false, reason: 'unconfigured' };
+    return { ok: false, reason: row.verdict };
+}
+/**
+ * Decide a host-placed routine's auth readiness from the REMOTE box's `devices
+ * ping --local --json` payload (PHNX-4116). Pure over the payload TEXT so it is
+ * unit-tested without SSH: it finds this agent's probe row (ABSENT when the box
+ * dropped its `no_evidence` row) and reads the box's per-agent launchability the
+ * ping now carries, then runs {@link decideRoutineAuthReadiness} — so a host box
+ * that could not probe but holds a token is ready, exactly as the local path
+ * decides for the same box. Returns null when the payload cannot be parsed; the
+ * caller treats that as a probe failure, never as "no credential".
+ */
+export function decideHostAuthFromPing(stdout, agent) {
+    let payload;
+    try {
+        payload = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const { rows, launchable } = payload;
+    const verdict = rows?.find((row) => row.agent === agent)?.health?.verdict;
+    const row = verdict ? { verdict } : undefined;
+    return decideRoutineAuthReadiness(row, launchable?.includes(agent) ?? false);
+}
 /**
  * Interactive setup/repair readiness. Unlike the scheduler's deterministic
  * structural gate, this completes a real local auth request and reads Codex's
@@ -180,13 +236,14 @@ export async function evaluateActivationReadinessLive(config) {
     if (!version)
         return structural;
     const context = resolveJobExecutionContext(config, { mode: 'local' });
-    let authVerdict;
+    // The probe row (absent when this box could not probe — a worker's setup-token
+    // box drops `no_evidence`) plus the run-router launchability, run through the
+    // ONE decision the host path also uses so both agree for the same box.
     const rows = await probeLocalFleetAuth({ agents: [config.agent] });
     const row = rows.find((candidate) => candidate.version === version);
-    const accepted = new Set(['live', 'rate_limited', 'unverified']);
-    authVerdict = row && accepted.has(row.health.verdict)
-        ? { ok: true }
-        : { ok: false, reason: row?.health.verdict ?? 'unconfigured' };
+    const { collectRunCandidates } = await import('./accounting/rotate.js');
+    const launchable = (await collectRunCandidates(config.agent)).some((candidate) => candidate.signedIn);
+    const authVerdict = decideRoutineAuthReadiness(row?.health, launchable);
     return evaluateRoutineReadiness(context, {
         agentInstalled: () => true,
         ...(config.agent === 'codex' && context.absoluteCwd
@@ -259,19 +316,20 @@ export async function evaluateHostActivationReadiness(config) {
                 ? `powershell -NoProfile -EncodedCommand ${encodePowershell(`${POWERSHELL_PROGRESS_SILENCE}; & agents ${pingArgs.map(powershellQuote).join(' ')}`)}`
                 : `agents ${pingArgs.map(shellQuote).join(' ')}`;
             const probe = sshExec(target, command, { timeoutMs: 30_000, extraSshArgs: identity });
-            let verdict = 'error';
-            if (probe.code === 0) {
-                try {
-                    const payload = JSON.parse(probe.stdout);
-                    verdict = payload.rows?.find((row) => row.agent === config.agent)?.health.verdict ?? 'unconfigured';
-                }
-                catch {
-                    verdict = 'error';
-                }
+            // A ping that could not run or parse is a probe FAILURE, never mistaken for
+            // "no credential": block with the failure so the operator sees it. A parsed
+            // payload runs the shared decision — an ABSENT row (the remote dropped its
+            // `no_evidence`) plus the launchability the ping now carries is ready,
+            // exactly as the local path decides for the same box (PHNX-4116).
+            const decision = probe.code === 0 ? decideHostAuthFromPing(probe.stdout, config.agent) : null;
+            if (!decision) {
+                return evaluateRoutineReadiness(unprobed, {
+                    authOk: () => ({ ok: false, reason: `devices ping --local failed on ${host.name}` }),
+                }, { agent: config.agent });
             }
-            if (!new Set(['live', 'rate_limited', 'unverified']).has(verdict)) {
+            if (!decision.ok) {
                 return evaluateRoutineReadiness(unprobed, {
-                    authOk: () => ({ ok: false, reason: verdict }),
+                    authOk: () => decision,
                 }, { agent: config.agent });
             }
         }

package/dist/lib/rules/compile.js

@@ -303,6 +303,12 @@ export function compileRulesForProject(cwd, opts = {}) {
             const fname = agent.instructionsFile;
             if (seen.has(fname))
                 continue;
+            // Hard-deprecated agents (e.g. Gemini, retired by Google) never get an
+            // instruction-file symlink — the harness is gone, so GEMINI.md would only
+            // litter the tree. Mirrors the deprecated?.hard skip used everywhere else
+            // (capabilities.ts, MANAGED_AGENT_IDS, modes.ts).
+            if (agent.deprecated?.hard)
+                continue;
             // Skip agents whose instructions live at a nested path (e.g. OpenClaw's
             // workspace/AGENTS.md) — those are managed by their own setup paths.
             if (fname.includes('/') || fname.includes('\\'))

package/dist/lib/sandbox.js

@@ -137,8 +137,6 @@ export function prepareJobHome(config, version) {
     const overlayHome = getJobHomePath(config.name);
     cleanJobHome(config.name);
     fs.mkdirSync(overlayHome, { recursive: true });
-    // gemini is hard-deprecated: runner.ts rejects a gemini routine before it
-    // ever reaches prepareJobHome, so there is deliberately no branch here.
     if (config.agent === 'claude') {
         generateClaudeConfig(overlayHome, config);
     }

package/dist/lib/secrets-policy.d.ts

@@ -2,7 +2,7 @@ import { type SecretsContext } from './secrets-client.js';
 import type { PushBundleResult } from './secrets-types.js';
 import type { AgentId, Meta, NativeAccountRecord } from './types.js';
 import { type DeviceProfile } from './devices/registry.js';
-import { type SharedAuthStatus } from './fleet-shared-state.js';
+import { type FleetSharedDeviceState, type SharedAuthStatus } from './fleet-shared-state.js';
 import { selfConfiguredDeviceRole } from './device-config.js';
 import { AUTH_STORE_ALIAS, AUTH_BUNDLE_BACKEND, RESERVED_BUNDLE_NAMES, isReservedBundleName, ReservedBundleWrongBackendError, assertReservedAuthBackend, isReservedBundleBackendError, RESERVED_STORES, reservedStoreName, isReservedStoreName, assertStorableCredentialKind, inspectReservedAuthBundle, type StorableCredentialKind } from './reserved-stores.js';
 export { AUTH_STORE_ALIAS, AUTH_BUNDLE_BACKEND, RESERVED_BUNDLE_NAMES, isReservedBundleName, ReservedBundleWrongBackendError, assertReservedAuthBackend, isReservedBundleBackendError, RESERVED_STORES, reservedStoreName, isReservedStoreName, assertStorableCredentialKind, inspectReservedAuthBundle, type StorableCredentialKind, };
@@ -107,6 +107,25 @@ export declare function publishReservedAuthVerdict(options?: PublishAuthVerdictO
  * only peers whose shared verdict says the bundle is missing.
  */
 export declare function syncReservedAuthBundle(deps?: AuthSyncDeps): Promise<AuthSyncResult>;
+/**
+ * Skip reason for a peer that has never sent a daemon-state reply (no
+ * `devices/<peer>/daemon-state.json`). auth-sync logs these at INFO — a
+ * brand-new or never-dialed worker legitimately has no reply on an early tick,
+ * so it is informational, not a warning. Stable so the service classifies the
+ * skip without matching a substring.
+ */
+export declare const SKIP_REASON_NO_PEER_REPLY = "no daemon-state reply from this peer yet";
+/**
+ * Skip reason for a peer whose reply exists but carries no `accounts.rows` field
+ * at all (an older CLI that does not publish per-account verdicts, or a partial
+ * state written before the account-state daemon ran). Without those rows there is
+ * no first-hand knowledge of what the peer holds, so the plan FAILS CLOSED and
+ * skips rather than pushing every key blindly. auth-sync logs it at INFO — it is
+ * transient during a rolling upgrade. An EMPTY `accounts.rows` array (a peer with
+ * no registered account) is NOT this case: it is a legitimate "holds nothing",
+ * and its keys are (correctly) pushed to provision it.
+ */
+export declare const SKIP_REASON_NO_ACCOUNT_ROWS = "daemon-state reply carries no account rows (fail closed)";
 /** One account's durable worker credential, resolved to (bundle, key). */
 export interface ReservedSyncAccount {
     accountId: string;
@@ -116,8 +135,11 @@ export interface ReservedSyncAccount {
     /** Storage key `<ENV>_<accountId>` (or the legacy email-keyed claude key). */
     key: string;
     /**
-     * `workerCredential.mintedAt` -- a re-mint bumps it, so a delivered-memo hit on
-     * the old value re-pushes. `'legacy'` for a pre-T1 claude row with no field.
+     * The credential's rotation fingerprint: `workerCredential.mintedAt` for a T1
+     * row, `'legacy'` for a pre-T1 claude row. A re-mint (`accounts login`) bumps
+     * `mintedAt`, so this changes even though the OLD token still authenticates —
+     * which is why presence is gated on BOTH the peer's verdict AND a delivered-
+     * fingerprint match (see {@link peerPresentKeys}).
      */
     fingerprint: string;
 }
@@ -128,7 +150,24 @@ export interface ReservedSyncPeer {
     headed: boolean;
     reachable: boolean;
     pinned: boolean;
-    /** bundle -> keys the peer already holds at the current fingerprint. Absent ⇒ none known. */
+    /**
+     * Whether this peer has ever sent a daemon-state reply on this box
+     * (`devices/<peer>/daemon-state.json` exists). Without one there is no
+     * first-hand knowledge of what it holds, so the peer is skipped this tick.
+     */
+    hasReply: boolean;
+    /**
+     * Whether the peer's reply actually carried an `accounts.rows` array (present,
+     * even if empty). A reply file with no such field (older CLI, partial state)
+     * has no first-hand inventory, so the plan skips it fail-closed rather than
+     * pushing blindly. See {@link SKIP_REASON_NO_ACCOUNT_ROWS}.
+     */
+    hasAccountRows: boolean;
+    /**
+     * bundle -> keys the peer is KNOWN to hold: its own reply verdict says present
+     * AND the fingerprint we last delivered to it matches the current one. Absent ⇒
+     * none known.
+     */
     presentKeys: Record<string, ReadonlySet<string>>;
 }
 type ReservedSyncPlanItem = {
@@ -144,7 +183,12 @@ type ReservedSyncPlanItem = {
 /**
  * Pure plan: for each worker peer, push each bundle it is missing at least one
  * key of. Deterministic (peers and bundles sorted) so it pins exactly in tests.
- * A headed peer is skipped BEFORE any key comparison -- it never receives a key.
+ * A headed peer is skipped BEFORE any key comparison -- it never receives a key;
+ * a peer with no reply yet (`hasReply: false`) is skipped next -- there is no
+ * first-hand knowledge of what it holds, so nothing is pushed to it this tick;
+ * a peer whose reply carries no `accounts.rows` field (`hasAccountRows: false`)
+ * is skipped FAIL-CLOSED for the same reason (an older CLI's reply is not proof
+ * of an empty inventory), rather than pushing every key blindly.
  */
 export declare function planReservedStoreSync(accounts: ReservedSyncAccount[], peers: ReservedSyncPeer[]): ReservedSyncPlanItem[];
 /**
@@ -156,14 +200,41 @@ export declare function planReservedStoreSync(accounts: ReservedSyncAccount[], p
  * `workerCredential`) is not a sync target.
  */
 export declare function reservedSyncTargets(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): ReservedSyncAccount[];
+/** The subset of a peer's per-account verdict row this planner reads. */
+export interface PeerAccountVerdict {
+    accountId: string;
+    harness: string;
+    /** `missing` ⇒ no working credential on the peer; anything else ⇒ present. */
+    verdict: string;
+}
+/** Narrow a peer's opaque `accounts.rows` to the verdict fields the planner reads. */
+export declare function readPeerAccountVerdicts(state: FleetSharedDeviceState | undefined): PeerAccountVerdict[];
+/**
+ * True when the peer's reply carried an `accounts.rows` array at all (present,
+ * even if empty). An older CLI, or a partial state written before the account-
+ * state daemon ran, has no such field — and its absence must NOT read as "the
+ * peer holds nothing", or the plan would push every key blindly. An EMPTY array
+ * (a peer with no registered account) IS a valid first-hand "holds nothing".
+ */
+export declare function peerHasAccountRows(state: FleetSharedDeviceState | undefined): boolean;
 /**
- * The keys a peer is KNOWN to hold, per bundle, from what we have delivered to it
- * (memo, matched by fingerprint) plus the coarse legacy-`auth` verdict: a peer
- * reporting `auth.status === 'ready'` is known to hold every legacy `auth` key.
- * Reserved `__<harness>__` bundles have no coarse verdict, so their presence comes
- * from the memo alone -- which is what makes a newly-added reserved account push.
+ * The reserved keys a peer is KNOWN to hold, per bundle. Two conditions must BOTH
+ * hold (PHNX-4116):
+ *
+ * 1. FIRST-HAND — the peer's own daemon-state reply reports a NON-`missing`
+ *    verdict for the account, so it has a working credential for it (its slot
+ *    materialized). A `missing` verdict, or no row for the account at all, means
+ *    it does not — self-correcting: a key removed on the worker flips its next
+ *    verdict to `missing` and the push resumes, which a publisher-side memo alone
+ *    could never see.
+ * 2. ROTATION — the fingerprint we last delivered to this peer (`delivered`)
+ *    matches the account's CURRENT fingerprint. A re-mint bumps
+ *    `workerCredential.mintedAt` while the old token still authenticates, so the
+ *    verdict stays non-`missing`; without this the rotated key would never
+ *    propagate. A never-delivered key (no memo entry ⇒ `undefined`) never
+ *    matches, so a newly-added account still pushes.
  */
-export declare function peerPresentKeys(peer: string, accounts: ReservedSyncAccount[], memo: Record<string, string>, legacyAuthReady: boolean): Record<string, ReadonlySet<string>>;
+export declare function peerPresentKeys(accounts: ReservedSyncAccount[], verdicts: PeerAccountVerdict[], delivered: (bundle: string, key: string) => string | undefined): Record<string, ReadonlySet<string>>;
 interface ReservedStoreSyncResult {
     publisher: string | null;
     /** Legacy raw reserved items adopted into their bundle on this box before planning (local repair). */
@@ -189,6 +260,7 @@ interface ReservedStoreSyncDeps {
     listDevices?: () => DeviceProfile[];
     localName?: string;
     userAgentsDir?: string;
+    /** Where the publisher-side delivery memo lives; defaults to `getCacheDir()`. */
     cacheDir?: string;
     readMetaFn?: () => Pick<Meta, 'accounts' | 'deviceAccounts'>;
     isPinned?: (name: string) => boolean;
@@ -221,6 +293,8 @@ interface ReservedStoreSyncDeps {
 export declare function syncReservedStores(deps?: ReservedStoreSyncDeps): Promise<ReservedStoreSyncResult>;
 interface ReconcileWorkerSlotsResult {
     provisioned: string[];
+    /** Stale slots removed from the device doc (accountId no longer registered). */
+    dropped: string[];
     skipped: Array<{
         accountId: string;
         reason: string;
@@ -237,6 +311,10 @@ interface ReconcileWorkerSlotsDeps {
     provision?: (account: NativeAccountRecord) => void;
     /** True when an existing durable slot already carries everything provisioning seeds. */
     slotSeeded?: (harness: AgentId, slotDir: string) => boolean;
+    /** Remove stale slot records from the device doc. Default: {@link dropSlots}. */
+    dropSlots?: (accountIds: readonly string[]) => void;
+    /** Emit an operational log line. Default: the daemon log (fire-and-forget). */
+    log?: (level: 'INFO' | 'WARN', message: string) => void;
 }
 /**
  * Worker-side: after a durable key lands, materialize a slot for each portable