@phnx-labs/agents-cli 1.22.117 → 1.22.119

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;
 }
@@ -2539,7 +2550,8 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
         // Orphan-sweep stale skill directories from previous syncs under a
         // different cwd. Only runs in "full sync" mode (no explicit selection) —
         // see the matching guard on the commands sweep above for why. Skip
-        // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact.
+        // dot-dirs to keep plugin-managed subtrees (.plugins/, .promptcuts) intact,
+        // and the harness's own directories (ownedSkillDirs), which it writes itself.
         const skillsTargetSweep = path.join(agentDir, 'skills');
         if (!userPassedSelection && fs.existsSync(skillsTargetSweep) && !fs.lstatSync(skillsTargetSweep).isSymbolicLink()) {
             // Trust real skills AND command-skills: when commandsInstallAsSkills, the
@@ -2547,7 +2559,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
             // skills/. Those names are not in skillsToSync, so without this they'd be
             // swept as orphans — silently deleting every converted command (e.g.
             // /recap on Kimi or newer Codex releases).
-            const trustedSkills = new Set(skillsToSync);
+            const trustedSkills = new Set([...skillsToSync, ...(agentConfig.ownedSkillDirs ?? [])]);
             if (commandsInstallAsSkills)
                 for (const cmd of commandsToSync)
                     trustedSkills.add(cmd);

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/projects.d.ts

@@ -193,6 +193,22 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
     forRemote: boolean;
     primary?: string;
 }): string[];
+/**
+ * The repository paths a project claims, as `{ slug, prefix }` with `prefix`
+ * repo-relative and `dir/` shaped — the same ownership {@link projectRootsAbs}
+ * applies to a session's cwd, expressed against the repository instead of a
+ * checkout: a `defaultPath` narrowed under `root` claims that subtree of the
+ * primary `repo`, and a `repos[]` entry with a `subpath` claims that subpath. A
+ * project with no narrowed claim on a repository claims all of it and yields no
+ * row for it. Two cases of {@link projectRootsAbs} have no repository form and
+ * yield nothing here: a `defaultPath` outside `root` (no repo-relative path),
+ * and the weak root of a narrowed project (it only takes what nobody claims,
+ * which for a PR is the `repo-wide` scope).
+ */
+export declare function repoPathClaims(def: ProjectDef): Array<{
+    slug: string;
+    prefix: string;
+}>;
 /**
  * Which defined project a session belongs to, derived from its working
  * directory. A session whose `cwd` sits inside a project's repo root (or a

package/dist/lib/projects.js

@@ -411,6 +411,37 @@ function projectRootsAbs(defs) {
     }
     return out;
 }
+/**
+ * The repository paths a project claims, as `{ slug, prefix }` with `prefix`
+ * repo-relative and `dir/` shaped — the same ownership {@link projectRootsAbs}
+ * applies to a session's cwd, expressed against the repository instead of a
+ * checkout: a `defaultPath` narrowed under `root` claims that subtree of the
+ * primary `repo`, and a `repos[]` entry with a `subpath` claims that subpath. A
+ * project with no narrowed claim on a repository claims all of it and yields no
+ * row for it. Two cases of {@link projectRootsAbs} have no repository form and
+ * yield nothing here: a `defaultPath` outside `root` (no repo-relative path),
+ * and the weak root of a narrowed project (it only takes what nobody claims,
+ * which for a PR is the `repo-wide` scope).
+ */
+export function repoPathClaims(def) {
+    const out = [];
+    const add = (slug, rel) => {
+        const trimmed = rel.split(path.sep).join('/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+        if (trimmed && trimmed !== '.')
+            out.push({ slug, prefix: `${trimmed}/` });
+    };
+    if (def.repo && def.root && def.defaultPath) {
+        const rootAbs = path.resolve(expandLocalHome(def.root));
+        const defaultAbs = path.resolve(expandLocalHome(def.defaultPath));
+        if (isUnder(defaultAbs, rootAbs))
+            add(def.repo, path.relative(rootAbs, defaultAbs));
+    }
+    for (const r of def.repos ?? []) {
+        if (r.slug && r.subpath)
+            add(r.slug, r.subpath);
+    }
+    return out;
+}
 /** True when `child` is `parent` or nested under it (path-segment aware). */
 function isUnder(child, parent) {
     if (child === parent)

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