@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/commands/resume.js

@@ -7,7 +7,25 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { resolveSessionMetadataValue } from './sessions.js';
 import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
+import { machineId } from '../lib/machine-id.js';
 export const RESUME_SOURCE_ENV = 'AGENTS_RESUME_SOURCE_JSON';
+/**
+ * The source a dead-remote local fallback resumes from: the same session, but
+ * with `machine` rewritten to THIS box so the delegated `agents run --resume`
+ * resolves recovery locally (`sessionRecoveryPeer` returns undefined) instead of
+ * bouncing back to the unreachable owner. Because no local version home owns the
+ * peer's transcript, that local recovery lands on a labelled `/continue` replay
+ * from the synced mirror — the only way to continue a session whose owning device
+ * is gone. Owner-approved prefer-device, fall-back-local (PHNX-3626).
+ *
+ * Safe against the RUSH-2022 "silent local resume forks live state" hazard by
+ * PRECONDITION: this is reached only after `runOnPeer` proved the owner
+ * unreachable, so there is no live process on the peer to fork, and the fallback
+ * is announced with a log line — never silent.
+ */
+export function resumeLocalFallbackSource(session, self = machineId()) {
+    return { ...session, machine: self };
+}
 /**
  * The argv to re-run this resume on the machine that owns the session.
  *
@@ -165,14 +183,30 @@ export async function runStrictResume(sessionId, prompt, options) {
             },
             sessionId: outcome.session.id,
         });
-        if (rc === 'no-target') {
-            console.error(chalk.red(`Session ${outcome.session.shortId} lives on ${owner}, which isn't a reachable device right now.`));
-            console.error(chalk.gray(`Register/wake it (agents devices), or run there: agents ssh ${owner}`));
-            process.exitCode = 1;
+        if (rc === 'no-target' || rc === 'unreachable') {
+            // Prefer-device, fall back to local (PHNX-3626): the owning device is
+            // unreachable — either not a dialable registered device ('no-target') or
+            // registered but offline/asleep so the SSH connection itself failed
+            // ('unreachable'). Either way there is no live harness to reach OR to fork,
+            // so continue the session HERE from its synced mirror rather than
+            // dead-ending. The local recovery resolves this to a labelled `/continue`
+            // replay (no local home owns the peer's transcript), the honest degradation.
+            if (!options.quiet) {
+                process.stderr.write(chalk.yellow(`[agents] session ${outcome.session.shortId} belongs to ${owner}, which is unreachable → resuming locally (/continue replay from the synced transcript)\n`));
+            }
+            process.exitCode = await delegateLocalResume(resumeLocalFallbackSource(outcome.session), prompt, options);
         }
         return;
     }
-    const args = buildResumeRunArgs(outcome.session, prompt, options);
+    process.exitCode = await delegateLocalResume(outcome.session, prompt, options);
+}
+/**
+ * Spawn the delegated local `agents run --resume` for a session this box owns
+ * (or is falling back to). The run command remains the sole executor; recovery
+ * (native vs `/continue`) is resolved there. Returns the child's exit code.
+ */
+async function delegateLocalResume(session, prompt, options) {
+    const args = buildResumeRunArgs(session, prompt, options);
     const child = spawn(process.execPath, [process.argv[1], ...args], {
         stdio: 'inherit',
         env: {
@@ -180,12 +214,11 @@ export async function runStrictResume(sessionId, prompt, options) {
             // Avoid repeating the fleet lookup in the delegated local `run`
             // process. The value is metadata-only and is not forwarded over SSH;
             // the owner performs its own local SQLite lookup.
-            [RESUME_SOURCE_ENV]: JSON.stringify(outcome.session),
+            [RESUME_SOURCE_ENV]: JSON.stringify(session),
         },
     });
-    const exitCode = await new Promise((resolve) => {
+    return new Promise((resolve) => {
         child.once('error', () => resolve(127));
         child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
     });
-    process.exitCode = exitCode;
 }

package/dist/commands/routines.js

@@ -10,8 +10,9 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, } from '../lib/daemon/daemon.js';
-import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled } from '../lib/device-config.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, } from '../lib/daemon/daemon.js';
+import { isDaemonServiceEnabled, setDaemonServiceEnabled } from '../lib/daemon-services.js';
+import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled, isSchedulerEnabled, } from '../lib/device-config.js';
 import { parseAgentVersionSpec, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
 import { isCustomHarnessName } from '../lib/profiles.js';
 import { RUN_STRATEGIES, normalizeRunStrategy } from '../lib/accounting/rotate.js';
@@ -313,10 +314,17 @@ function ensureSchedulerRunning(opts = {}) {
         console.error(chalk.yellow(err.message));
         return;
     }
+    const wasServiceEnabled = isDaemonServiceEnabled('scheduler');
+    if (!wasServiceEnabled)
+        setDaemonServiceEnabled('scheduler', true);
     if (isDaemonRunning()) {
-        signalDaemonReload();
-        if (!opts.quiet)
-            log(chalk.gray('Scheduler reloaded'));
+        const reloaded = signalDaemonReload();
+        if (!reloaded) {
+            console.error(chalk.yellow('Scheduler service enabled, but live reload is unavailable. Restart deliberately with: agents daemon restart'));
+        }
+        else if (!opts.quiet) {
+            log(chalk.gray(wasServiceEnabled ? 'Scheduler reloaded' : 'Scheduler service enabled and reloaded'));
+        }
         return;
     }
     const result = startDaemon();
@@ -2162,7 +2170,7 @@ export function registerRoutinesCommands(program) {
     // Scheduler lifecycle — usually auto-managed by `routines add`, exposed here for manual control.
     routinesCmd
         .command('start')
-        .description('Start the background scheduler. Usually unnecessary — it auto-starts when you add your first routine.')
+        .description('Enable and reload the scheduler service. Usually unnecessary — it auto-starts when you add your first routine.')
         .action(() => {
         try {
             // A manual start on a disabled device refuses with the same message the
@@ -2176,13 +2184,16 @@ export function registerRoutinesCommands(program) {
             console.error(chalk.red(err.message));
             process.exit(1);
         }
+        setDaemonServiceEnabled('scheduler', true);
         const result = startDaemon();
         if (result.method === 'already-running') {
             // Signal a reload even here: if the daemon booted while this device had
             // scheduler.enabled=false, the reload re-evaluates the gate and boots
             // the scheduler — a manual start heals a scheduler-less daemon.
-            signalDaemonReload();
-            console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid}) — reloaded`));
+            const reloaded = signalDaemonReload();
+            console.log(reloaded
+                ? chalk.yellow(`Scheduler service enabled (shared daemon PID: ${result.pid}) — reloaded`)
+                : chalk.yellow(`Scheduler service enabled, but live reload is unavailable. Restart deliberately with: agents daemon restart`));
         }
         else if (result.pid) {
             console.log(chalk.green(`Scheduler started (PID: ${result.pid})`));
@@ -2193,25 +2204,31 @@ export function registerRoutinesCommands(program) {
     });
     routinesCmd
         .command('stop')
-        .description('Stop the background scheduler. Routines will not fire until you start it again.')
+        .description('Stop only the scheduler service. The shared daemon and its browser, secrets, usage, and monitoring services stay running.')
         .action(() => {
-        if (!isDaemonRunning()) {
-            console.log(chalk.yellow('Scheduler is not running'));
+        const daemonRunning = isDaemonRunning();
+        setDaemonServiceEnabled('scheduler', false);
+        if (daemonRunning && !signalDaemonReload()) {
+            console.log(chalk.yellow('Scheduler service disabled, but live reload is unavailable. It will stay off after the next daemon start.'));
             return;
         }
-        stopDaemon();
-        console.log(chalk.green('Scheduler stopped'));
+        console.log(daemonRunning
+            ? chalk.green('Scheduler service stopped; shared daemon is still running')
+            : chalk.yellow('Scheduler service disabled; shared daemon was already stopped'));
     });
     routinesCmd
         .command('status')
-        .description('Show scheduler status, enabled routines, and when each one fires next.')
-        .option('--json', 'Emit machine-readable scheduler + per-routine status (owner device, last fire, last error, in-flight run)')
+        .description('Show scheduler service state, shared-daemon state, enabled routines, and upcoming runs.')
+        .option('--json', 'Emit machine-readable scheduler service + device gate + daemon + per-routine status (owner device, last fire, last error, in-flight run)')
         .action((options) => {
         try {
             monitorRunningJobs();
         }
         catch { /* best-effort orphan reap */ }
         const status = getDaemonStatus();
+        const schedulerServiceEnabled = isDaemonServiceEnabled('scheduler');
+        const schedulerDeviceEnabled = isSchedulerEnabled();
+        const schedulerState = schedulerServiceEnabled && schedulerDeviceEnabled ? status.state : 'stopped';
         // The daemon-owned status surface (PHNX-3215): scheduler truth plus, per
         // routine, its single owner device, last fire outcome + error, and any
         // in-flight spawn — the fields `list --json` (definition-shaped) does not
@@ -2221,7 +2238,10 @@ export function registerRoutinesCommands(program) {
             writeJson({
                 device: machineId(),
                 scheduler: {
-                    state: status.state,
+                    state: schedulerState,
+                    serviceEnabled: schedulerServiceEnabled,
+                    deviceEnabled: schedulerDeviceEnabled,
+                    daemonState: status.state,
                     pid: status.pid,
                     binaryPath: status.binaryPath,
                     heartbeat: status.heartbeat
@@ -2238,12 +2258,13 @@ export function registerRoutinesCommands(program) {
             return;
         }
         console.log(chalk.bold('Scheduler\n'));
-        const stateLabel = status.state === 'running'
+        const stateLabel = schedulerState === 'running'
             ? chalk.green('running')
-            : status.state === 'wedged'
+            : schedulerState === 'wedged'
                 ? chalk.red('wedged')
                 : chalk.gray('stopped');
         console.log(`  Status:    ${stateLabel}`);
+        console.log(`  Daemon:    ${status.running ? chalk.green('running') : chalk.gray('stopped')}`);
         if (status.pid)
             console.log(`  PID:       ${status.pid}`);
         if (status.binaryPath)
@@ -2256,9 +2277,9 @@ export function registerRoutinesCommands(program) {
         const enabled = jobs.filter((j) => j.enabled);
         console.log(`  Routines:  ${enabled.length} enabled / ${jobs.length} total`);
         if (status.state === 'wedged') {
-            console.log(chalk.red('\n  The daemon is wedged (heartbeat stale). Restart with: agents routines stop && agents routines start'));
+            console.log(chalk.red('\n  The shared daemon is wedged (heartbeat stale). Restart deliberately with: agents daemon restart'));
         }
-        if (status.running && enabled.length > 0) {
+        if (schedulerState === 'running' && enabled.length > 0) {
             const scheduler = new JobScheduler(async () => { });
             scheduler.loadAll();
             const scheduled = scheduler.listScheduled();
@@ -2269,7 +2290,7 @@ export function registerRoutinesCommands(program) {
             }
             scheduler.stopAll();
         }
-        else if (!status.running && jobs.length > 0) {
+        else if (schedulerState !== 'running' && jobs.length > 0) {
             console.log(chalk.gray('\n  Start the scheduler to begin firing routines: agents routines start'));
         }
     });

package/dist/commands/sessions-optimize.js

@@ -35,7 +35,7 @@ export function registerSessionsOptimizeCommand(sessionsCmd) {
         notes: `
       - FTS5 appends a segment on every insert and tombstones every delete; the scanner delete+inserts a session's docs on each rescan and never self-merges, so \`tool_call_text_data\` / \`session_text_data\` bloat with unmerged segments — GBs of index for tens of MB of content, and queries slow down.
       - This runs FTS5 \`'optimize'\`: it merges every segment into one and purges tombstones. Non-destructive — no searchable content is lost.
-      - Reclaimed space becomes reusable free pages inside the DB file. To return it to the OS, stop the daemon (\`agents routines stop\`) and run \`VACUUM\` against \`~/.agents/.history/sessions/sessions.db\`.
+      - Reclaimed space becomes reusable free pages inside the DB file. To return it to the OS, use the operator lifecycle command \`agents daemon stop\`, run \`VACUUM\` against \`~/.agents/.history/sessions/sessions.db\`, then \`agents daemon start\`. \`agents routines stop\` disables only the scheduler service.
     `,
     });
 }

package/dist/commands/sessions.js

@@ -53,7 +53,7 @@ import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
 import { listInstalledVersions, resolveVersionAliasLoose } from '../lib/installations/versions.js';
 import { getAgentsInvocation } from '../lib/daemon/daemon.js';
-import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
+import { sessionAgentSupportsResume, sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, loadSessionPreviewDigest, transcriptOnPeerOf, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
@@ -4062,6 +4062,8 @@ function versionedAliasIfPresent(agent, version) {
     return null;
 }
 export function buildResumeCommand(session) {
+    if (!sessionAgentSupportsResume(session.agent))
+        return null;
     switch (session.agent) {
         // opencode sessions are shared across versions, so resume is deliberately NOT
         // version-pinned — it always goes through the plain launcher.
@@ -4079,16 +4081,7 @@ export function buildResumeCommand(session) {
             }
             return resumeArgv(session.agent, session.id, cli);
         }
-        case 'gemini':
-        case 'antigravity':
-        case 'openclaw':
-        case 'rush':
-        case 'hermes':
-        case 'grok':
-        case 'kimi':
-        case 'droid':
-        case 'cursor':
-            // Grok (and some others) sessions are captured artifacts, not resumable the same way.
+        default:
             return null;
     }
 }

package/dist/commands/share.d.ts

@@ -80,7 +80,9 @@ export declare function runShareEdit(target: string, opts: {
     removeMeta?: string[];
     /** Change the page's visibility in place (public | unlisted | me | org).
      * A metadata-only rewrite like label/meta — the body is untouched, so no
-     * revision is created. me/org require a Phoenix session. */
+     * revision is created. me/org require a Phoenix session. `private` is
+     * rejected here — token-gating needs a fresh viewer key only the publish
+     * path mints (PHNX-3654). */
     visibility?: ShareVisibility;
     force?: boolean;
     fetchEdit?: typeof fetch;
@@ -116,7 +118,7 @@ export declare function runShareList(opts?: {
     /** Visibility filter. `public` (default) lists only public gallery pages;
      * `unlisted`/`me`/`org` include that owner's hidden pages; `all` includes
      * every active page. Hidden scopes send the owner's bearer and `scope=mine`. */
-    scope?: 'public' | 'unlisted' | 'me' | 'org' | 'all';
+    scope?: 'public' | 'unlisted' | 'private' | 'me' | 'org' | 'all';
 }): Promise<ShareListResult>;
 /** Client-side filtering over an already-fetched listing (RUSH-2683) — the
  * Worker has no query surface for this, so it narrows the fetched set instead
@@ -127,7 +129,7 @@ export declare function applyShareListFilters(result: ShareListResult, filters:
     session?: string;
     label?: string;
     meta?: Record<string, string>;
-    scope?: 'public' | 'unlisted' | 'me' | 'org' | 'all';
+    scope?: 'public' | 'unlisted' | 'private' | 'me' | 'org' | 'all';
 }): ShareListResult;
 export declare function formatShareList(result: ShareListResult, json?: boolean): string;
 /** One retained prior version of a slug, as reported by the Worker's

package/dist/commands/share.js

@@ -11,7 +11,7 @@ import { Argument, Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
 import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, resolveShareVisibility, scanShareContent, formatSensitiveContentError, SHARE_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
+import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, resolveShareVisibility, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerBundle } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
@@ -37,7 +37,11 @@ export function formatSharePublishResult(result, json = false) {
         lines.push(chalk.dim('  expires never'));
     const visibility = result.visibility ?? (result.unlisted ? 'unlisted' : 'public');
     if (visibility === 'unlisted') {
-        lines.push(chalk.dim('  visibility: unlisted (noindex, hidden from gallery)'));
+        lines.push(chalk.dim('  visibility: unlisted (noindex, hidden from gallery — NOT authenticated)'));
+    }
+    else if (visibility === 'private') {
+        lines.push(chalk.dim('  visibility: private (token-gated — 404 without the key; hidden from gallery)'));
+        lines.push(chalk.yellow('  the key is in the URL above (?k=…) — treat the whole link as a secret'));
     }
     else if (visibility === 'me' || visibility === 'org') {
         lines.push(chalk.dim(`  visibility: ${visibility} (login required, hidden from gallery)`));
@@ -57,6 +61,14 @@ export function shareTemplateStatus(cfg) {
     return cfg.templateHash === hashWorkerScript(renderWorkerBundle().script) ? 'current' : 'outdated';
 }
 export async function runShareEdit(target, opts) {
+    // Token-gated `private` can't be set in place: the metadata-edit route carries
+    // no viewer token, so re-stamping visibility=private alone would leave the page
+    // gated by a hash that doesn't exist — inaccessible to everyone (PHNX-3654).
+    // Fail loud pointing at the publish path, which mints the key.
+    if (opts.visibility === 'private') {
+        throw new Error("Can't change a page to 'private' in place — a token-gated link needs a fresh viewer key. " +
+            "Re-publish it with 'agents artifacts share <file> --protected' instead.");
+    }
     // Same public-listing gate as publish: label + every metadata value are
     // world-readable in the gallery and `share list --list-json`.
     if (opts.force !== true) {
@@ -158,7 +170,10 @@ export function parseShareListing(user, body) {
             host: item.host == null ? null : String(item.host),
             repo: item.repo == null ? null : String(item.repo),
             revisionCount: typeof item.revisionCount === 'number' ? item.revisionCount : 0,
-            visibility: item.visibility === 'unlisted' || item.visibility === 'me' || item.visibility === 'org'
+            visibility: item.visibility === 'unlisted' ||
+                item.visibility === 'private' ||
+                item.visibility === 'me' ||
+                item.visibility === 'org'
                 ? item.visibility
                 : 'public',
             meta: parseMetaField(item.meta),
@@ -609,11 +624,12 @@ export function registerShareCommands(artifactsCmd) {
         .option('--slug <slug>', 'URL slug override (default: stable slug of the artifact title, then filename)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config; ignored on the managed endpoint)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .addOption(new Option('--visibility <level>', 'public | unlisted | me | org (default public). unlisted is a capability URL; me/org require a Phoenix session and are hidden from the gallery')
-        .choices(['public', 'unlisted', 'me', 'org'])
+        .addOption(new Option('--visibility <level>', 'public | unlisted | private | me | org (default public). unlisted is an UNAUTHENTICATED capability URL; private is token-gated (404 without the key); me/org require a Phoenix session. All but public are hidden from the gallery')
+        .choices([...PUBLISH_VISIBILITY_LEVELS])
         .default('public'))
-        .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted').hideHelp())
-        .addOption(new Option('--private', 'hidden alias of --visibility unlisted').hideHelp())
+        .addOption(new Option('--protected', 'token-gated link (= --visibility private): the URL carries a secret key and returns 404 without it — the authenticated alternative to --unlisted'))
+        .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted (obscurity, NOT authentication)').hideHelp())
+        .addOption(new Option('--private', 'hidden alias of --visibility unlisted (obscurity, NOT authentication — for real read-auth use --protected)').hideHelp())
         .option('--force', 'publish even when the file contains emails or credential-shaped strings')
         .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
         .option('--no-analytics', 'skip injecting the Cloudflare Web Analytics beacon')
@@ -637,13 +653,21 @@ export function registerShareCommands(artifactsCmd) {
             const visibility = resolveShareVisibility({
                 visibility: opts.visibility,
                 unlisted: opts.unlisted === true || opts.private === true,
+                protected: opts.protected === true,
             });
+            // unlisted (incl. its --private alias) is obscurity, not read-auth — warn
+            // loudly before the publish so a "private" link is never mistaken for a
+            // gated one (PHNX-3654). Skipped for --json so machine output stays clean.
+            if (visibility === 'unlisted' && !opts.json) {
+                console.error(chalk.yellow(`⚠ ${unlistedNotPrivateWarning()}`));
+            }
             const result = await publishFile(file, {
                 slug: opts.slug,
                 githubUser: opts.githubUser,
                 expire: opts.expire,
                 visibility,
                 unlisted: visibility === 'unlisted',
+                protected: visibility === 'private',
                 force: opts.force,
                 cover: opts.cover,
                 analytics: opts.analytics,
@@ -929,8 +953,8 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
         // so the listing filter is named `--scope` here; `--all` is the convenience
         // alias for `--scope all`.
         .option('--for-user <user>', 'GitHub username whose namespace to list (default: resolved from gh/git config)')
-        .addOption(new Option('--scope <level>', 'visibility filter: public (default), unlisted, me, org, or all')
-        .choices(['public', 'unlisted', 'me', 'org', 'all'])
+        .addOption(new Option('--scope <level>', 'visibility filter: public (default), unlisted, private, me, org, or all')
+        .choices(['public', 'unlisted', 'private', 'me', 'org', 'all'])
         .default('public'))
         .option('--all', "list every page including hidden unlisted/me/org shares (alias for --scope all)")
         .option('--agent <name>', 'filter to shares published by this agent/harness (case-insensitive)')

package/dist/lib/accounting/account-pool-collect.d.ts

@@ -25,10 +25,12 @@ export declare function foldRegistryCandidates(agent: AgentId, inputs: RunCandid
  * provider can authenticate `agent` and whose credential is present locally
  * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
  *
- * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
- * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
- * recovery, teams placement) keep calling it directly and are unaffected. The
- * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path,
+ * and used by session recovery (`resolveSessionRecovery`, PHNX-3626) so an
+ * origin-account limit can rotate to a healthy provider account and stay NATIVE.
+ * The other consumers of {@link collectRunCandidates} (watchdog, teams
+ * placement) keep calling it directly and are unaffected. The existing
+ * {@link pickBalancedCandidate} selects over the combined list, so the
  * revoked / rate-limit / exhausted logic is unchanged.
  */
 export declare function collectRunCandidatesForRun(agent: AgentId): Promise<RotateCandidate[]>;

package/dist/lib/accounting/account-pool-collect.js

@@ -63,10 +63,12 @@ export function foldRegistryCandidates(agent, inputs) {
  * provider can authenticate `agent` and whose credential is present locally
  * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
  *
- * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path
- * ONLY — the other consumers of {@link collectRunCandidates} (watchdog, session
- * recovery, teams placement) keep calling it directly and are unaffected. The
- * existing {@link pickBalancedCandidate} selects over the combined list, so the
+ * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path,
+ * and used by session recovery (`resolveSessionRecovery`, PHNX-3626) so an
+ * origin-account limit can rotate to a healthy provider account and stay NATIVE.
+ * The other consumers of {@link collectRunCandidates} (watchdog, teams
+ * placement) keep calling it directly and are unaffected. The existing
+ * {@link pickBalancedCandidate} selects over the combined list, so the
  * revoked / rate-limit / exhausted logic is unchanged.
  */
 export async function collectRunCandidatesForRun(agent) {

package/dist/lib/accounting/usage-ingest.js

@@ -1,7 +1,7 @@
 /**
  * The `agents __usage-ingest` receiver (PHNX-3392 usage-sync).
  *
- * A headed peer's daemon pipes a {@link UsageSyncPayload} JSON envelope to our
+ * A legacy headed peer may pipe a {@link UsageSyncPayload} JSON envelope to our
  * stdin; we merge its identity-keyed rows into the local usage cache newest-wins
  * ({@link ingestPeerClaudeUsageRows}). Hidden internal verb — intercepted in
  * index.ts before bootstrap, so it never triggers an update check or a detached
@@ -12,7 +12,9 @@
  * accepting a wrong shape, but a busy cache lock degrades to best-effort inside
  * `ingestPeerClaudeUsageRows` like every other cache writer.
  *
- * The payload arrives on stdin, EXCEPT on a Windows receiver: the `agents.ps1`
+ * New daemon ticks use the fleet-shared store instead. This compatibility
+ * receiver remains for older installed versions. The payload arrives on stdin,
+ * EXCEPT on a Windows receiver: the `agents.ps1`
  * shim does not forward ssh-piped stdin to the node process, so the pusher writes
  * the payload to a temp file and passes `agents __usage-ingest --from <path>`
  * (the same workaround the secrets push uses — `buildWindowsStdinImportCommand`).

package/dist/lib/accounting/usage-sync.d.ts

@@ -1,107 +1,52 @@
-import { type DeviceProfile } from '../devices/registry.js';
-import { type ConfiguredDeviceRole } from '../device-config.js';
-import { type CachedUsageSnapshot } from './usage.js';
-/** How long a single peer push may take before it is abandoned for this tick. */
-export declare const USAGE_PUSH_DEADLINE_MS = 20000;
-export declare const USAGE_PULL_DEADLINE_MS = 20000;
 /**
- * A worker's newest local usage row older than this triggers a pull from the
- * primary. A worker cannot self-read usage (setup-token lacks `user:profile`,
- * RUSH-2392), so its only source of a fresh row is the daemon push every
- * `USAGE_SYNC_TICK_MS` (15m); this cutoff is 2× that tick, so one missed push
- * cycle is tolerated before the worker actively pulls. Bounds worker staleness
- * to ~30m instead of the days-old caches this replaces.
+ * Fleet distribution of identity-keyed Claude usage through the user repo.
+ *
+ * A headed device can read authoritative usage; a worker's setup-token cannot.
+ * Headed daemons therefore publish one snapshot into their conflict-free
+ * `~/.agents/devices/<device>/daemon-state.json`. The daemon's bounded Git
+ * transport delivers those files automatically; workers merge newest-wins.
+ * There is deliberately no device-to-device SSH in this module or its tick.
  */
-export declare const USAGE_SYNC_MAX_AGE_MS: number;
-/** The stdin envelope the `__usage-ingest` verb reads. `v` guards the shape. */
+import { type ConfiguredDeviceRole } from '../device-config.js';
+import { type CachedUsageSnapshot } from './usage.js';
+/** Legacy hidden ingest/export envelope kept for older fleet CLI compatibility. */
 export interface UsageSyncPayload {
     v: 1;
     rows: Record<string, CachedUsageSnapshot>;
 }
-/** One peer the local publisher is considering, reduced to the plan inputs. */
-export interface UsagePushTarget {
-    name: string;
-    /** The peer's configured role — headed peers are skipped (own reader). */
-    role: ConfiguredDeviceRole | undefined;
-    /** Live-ish reachability from the tailscale snapshot; offline peers are skipped. */
-    online: boolean;
-    /** Managed known-hosts pin — an unpinned host is skipped, never TOFU-accepted. */
-    pinned: boolean;
+export interface PublishUsageSnapshotOptions {
+    userAgentsDir?: string;
+    cachePath?: string;
+    role?: ConfiguredDeviceRole;
+    device?: string;
 }
-export type UsageSyncPlanItem = {
-    action: 'push';
-    device: string;
-} | {
-    action: 'skip';
-    device: string;
-    reason: string;
-};
-/**
- * Decide, per peer, whether to push the local usage snapshot. Pure.
- *
- * - `selfIsPublisher` is false on a `worker`/unmarked box: it has no authoritative
- *   usage to publish, so every peer is skipped.
- * - `hasLocalRows` false means the local cache is empty (nothing to teach yet).
- * - A HEADED peer is skipped — it reads its own usage; pushing risks nothing
- *   (the merge is newest-wins) but is wasted work, and keeping the fan-out to
- *   consumers only makes the intent legible.
- */
-export declare function planUsagePush(selfIsPublisher: boolean, hasLocalRows: boolean, targets: UsagePushTarget[]): UsageSyncPlanItem[];
-export interface UsageSyncResult {
-    pushed: string[];
-    skipped: Array<{
-        device: string;
-        reason: string;
-    }>;
-    errors: Array<{
-        device: string;
-        message: string;
-    }>;
+export interface PublishUsageSnapshotResult {
+    published: boolean;
+    changed: boolean;
+    skipped: string | null;
+    error: string | null;
+    path: string | null;
 }
-export interface UsageSyncDeps {
-    selfRole?: () => ConfiguredDeviceRole | undefined;
-    listDevices?: () => DeviceProfile[];
-    /** Configured roles by device name; default reads the fleet config. */
-    listRoles?: () => Record<string, ConfiguredDeviceRole>;
-    localName?: () => string;
-    isPinned?: (name: string) => boolean;
-    exportRows?: () => Record<string, CachedUsageSnapshot>;
-    /** Deliver the serialized payload to one peer. Default: ssh `__usage-ingest`. */
-    push?: (device: DeviceProfile, payload: string) => {
-        ok: boolean;
-        message?: string;
-    };
+/** Publish this headed device's stable usage snapshot into its owned store file. */
+export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): PublishUsageSnapshotResult;
+export interface ConsumeUsageSnapshotsOptions {
+    userAgentsDir?: string;
+    cachePath?: string;
+    role?: ConfiguredDeviceRole;
+    device?: string;
+    roles?: Record<string, ConfiguredDeviceRole>;
 }
-export interface UsagePullResult {
-    pulledFrom: string | null;
+export interface ConsumeUsageSnapshotsResult {
+    sources: string[];
     merged: number;
     skipped: string | null;
-    error: string | null;
-}
-export interface UsagePullDeps {
-    selfRole?: () => ConfiguredDeviceRole | undefined;
-    listDevices?: () => DeviceProfile[];
-    listRoles?: () => Record<string, ConfiguredDeviceRole>;
-    isPinned?: (name: string) => boolean;
-    exportRows?: () => Record<string, CachedUsageSnapshot>;
-    ingestRows?: (rows: Record<string, CachedUsageSnapshot>) => number;
-    /** Injectable clock for the staleness gate; defaults to `Date.now`. */
-    now?: () => number;
-    /** Read the versioned payload from the primary. Default: ssh `__usage-export`. */
-    pull?: (device: DeviceProfile) => {
-        ok: boolean;
-        stdout?: string;
-        message?: string;
-    };
+    errors: Array<{
+        device: string;
+        message: string;
+    }>;
 }
 /**
- * Pull usage from the fleet's primary headed device when this worker's local
- * cache is empty or contains an expired row. `personal` is the primary role;
- * a `desktop` is used only when the fleet has no personal device.
- */
-export declare function pullUsageFromPrimary(deps?: UsagePullDeps): UsagePullResult;
-/**
- * Push the local identity-keyed usage snapshot to every reachable, pinned,
- * non-headed peer. A no-op on a non-headed box or when the local cache is empty.
+ * Read headed publishers from the local user-repo checkout and merge one
+ * newest-wins batch into the worker cache. No network or subprocess is touched.
  */
-export declare function syncFleetUsageSnapshots(deps?: UsageSyncDeps): UsageSyncResult;
+export declare function consumeUsageSnapshotsFromSharedStore(options?: ConsumeUsageSnapshotsOptions): ConsumeUsageSnapshotsResult;