@phnx-labs/agents-cli 1.22.66 → 1.22.69

package/dist/lib/ssh-exec.js

@@ -173,6 +173,8 @@ export function controlOpts() {
 export function sshConnectOpts(mux, hostKeyOpts) {
     return [...(hostKeyOpts ?? []), ...SSH_OPTS, ...mux];
 }
+/** Grace after a timed-out child receives SIGTERM before SIGKILL enforces the bound. */
+export const SSH_TIMEOUT_KILL_GRACE_MS = 250;
 /**
  * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
  *
@@ -228,12 +230,28 @@ export function sshExecAsync(target, remoteCmd, opts = {}) {
         let stderr = '';
         let settled = false;
         let timedOut = false;
+        let killTimer = null;
         const timer = opts.timeoutMs
             ? setTimeout(() => {
                 timedOut = true;
                 child.kill('SIGTERM');
+                // SIGTERM is advisory. A wedged ssh process can ignore it and keep the
+                // Promise (and daemon tick) open forever, so enforce a short hard-kill
+                // bound. Timeout calls always disable ControlMaster above; killing this
+                // direct client therefore tears down the remote connection too.
+                killTimer = setTimeout(() => {
+                    if (!settled)
+                        child.kill('SIGKILL');
+                }, SSH_TIMEOUT_KILL_GRACE_MS);
+                killTimer.unref?.();
             }, opts.timeoutMs)
             : null;
+        const clearTimers = () => {
+            if (timer)
+                clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
         child.stdout.setEncoding('utf-8');
         child.stderr.setEncoding('utf-8');
         child.stdout.on('data', (chunk) => { stdout += chunk; });
@@ -251,16 +269,14 @@ export function sshExecAsync(target, remoteCmd, opts = {}) {
             if (settled)
                 return;
             settled = true;
-            if (timer)
-                clearTimeout(timer);
+            clearTimers();
             resolve({ code: null, stdout, stderr: stderr + err.message, timedOut });
         });
         child.on('close', (code) => {
             if (settled)
                 return;
             settled = true;
-            if (timer)
-                clearTimeout(timer);
+            clearTimers();
             resolve({ code, stdout, stderr, timedOut });
         });
     });

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

@@ -0,0 +1,14 @@
+/**
+ * `lib/storage` — the surface-agnostic core the managed-storage surfaces share:
+ *
+ *   - {@link selection}  the ONE managed-vs-BYO selection policy.
+ *   - {@link visibility} the ONE visibility model + product default (`me`).
+ *
+ * Consume the SELECTION + VISIBILITY POLICY from here; keep each surface's typed,
+ * `kind`-tagged backend adapter (endpoint, namespace, covers) in that surface's
+ * own module. `agents artifacts share` (`lib/share/`) and `agents traces`
+ * (`lib/traces/`) are the two current adapters; the `sessions` sync adapter is
+ * the next consumer.
+ */
+export { type StorageBackendKind, type StorageSelectionOpts, selectStorageBackendKind, isManagedSelection, } from './selection.js';
+export { type ShareVisibility, type VisibilityFlags, PUBLISH_VISIBILITY_LEVELS, EDITABLE_VISIBILITY_LEVELS, MANAGED_DEFAULT_VISIBILITY, BYO_DEFAULT_VISIBILITY, defaultVisibilityForBackend, explicitVisibility, resolveVisibility, publishVisibility, } from './visibility.js';

package/dist/lib/storage/index.js

@@ -0,0 +1,14 @@
+/**
+ * `lib/storage` — the surface-agnostic core the managed-storage surfaces share:
+ *
+ *   - {@link selection}  the ONE managed-vs-BYO selection policy.
+ *   - {@link visibility} the ONE visibility model + product default (`me`).
+ *
+ * Consume the SELECTION + VISIBILITY POLICY from here; keep each surface's typed,
+ * `kind`-tagged backend adapter (endpoint, namespace, covers) in that surface's
+ * own module. `agents artifacts share` (`lib/share/`) and `agents traces`
+ * (`lib/traces/`) are the two current adapters; the `sessions` sync adapter is
+ * the next consumer.
+ */
+export { selectStorageBackendKind, isManagedSelection, } from './selection.js';
+export { PUBLISH_VISIBILITY_LEVELS, EDITABLE_VISIBILITY_LEVELS, MANAGED_DEFAULT_VISIBILITY, BYO_DEFAULT_VISIBILITY, defaultVisibilityForBackend, explicitVisibility, resolveVisibility, publishVisibility, } from './visibility.js';

package/dist/lib/storage/selection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The ONE managed-vs-BYO storage-backend selection policy.
+ *
+ * Every surface that persists to Phoenix-managed storage (`agents artifacts
+ * share` today, `agents sessions` sync next) makes the SAME choice: run on OUR
+ * managed infrastructure when the caller is signed in to Phoenix, and only fall
+ * back to a bring-your-own bucket when the caller explicitly asked for it. This
+ * module owns that decision so it is not re-derived — and re-drifted — per
+ * surface.
+ *
+ * What lives here is ONLY the identity + selection policy. It deliberately does
+ * NOT know a surface's endpoint, namespace shape, public-read semantics, or OG
+ * covers — those differ (share uses an email-handle namespace with public reads
+ * and covers; a traces/sessions adapter uses the userId and differs again). Each
+ * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
+ * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
+ * `lib/traces/backend.ts` for the two adapters.
+ */
+import { type PhoenixSession } from '../identity/client.js';
+/** The two legitimate principals any managed-capable surface can resolve to. */
+export type StorageBackendKind = 'managed' | 'byo';
+export interface StorageSelectionOpts {
+    /**
+     * True when the SURFACE detected an explicit bring-your-own override — a
+     * `--byo` flag, a caller-supplied static write token, a `…_BACKEND=byo` env,
+     * or a full BYO endpoint config. Detecting WHICH signals count is the
+     * surface's job (they differ per surface); this policy only honors the boolean.
+     */
+    byoOverride?: boolean;
+    /**
+     * DI seam for the Phoenix session. `undefined` reads the real persisted
+     * session (`readSession()`); `null` means "explicitly signed out".
+     */
+    session?: PhoenixSession | null;
+}
+/**
+ * Pick the storage principal. Managed when signed in (`readSession() != null`)
+ * AND the surface reported no explicit BYO override; otherwise BYO.
+ *
+ * This is not a fallback chain — it is a single decision. A surface that cannot
+ * authenticate EITHER principal (signed out AND no BYO config) still reads `byo`
+ * here and fails loud in its own adapter, where the actionable "run auth login
+ * or set up your bucket" message belongs.
+ */
+export declare function selectStorageBackendKind(opts?: StorageSelectionOpts): StorageBackendKind;
+/** True when the shared policy resolves to the managed principal. Thin sugar
+ * over {@link selectStorageBackendKind} for the common boolean check. */
+export declare function isManagedSelection(opts?: StorageSelectionOpts): boolean;

package/dist/lib/storage/selection.js

@@ -0,0 +1,39 @@
+/**
+ * The ONE managed-vs-BYO storage-backend selection policy.
+ *
+ * Every surface that persists to Phoenix-managed storage (`agents artifacts
+ * share` today, `agents sessions` sync next) makes the SAME choice: run on OUR
+ * managed infrastructure when the caller is signed in to Phoenix, and only fall
+ * back to a bring-your-own bucket when the caller explicitly asked for it. This
+ * module owns that decision so it is not re-derived — and re-drifted — per
+ * surface.
+ *
+ * What lives here is ONLY the identity + selection policy. It deliberately does
+ * NOT know a surface's endpoint, namespace shape, public-read semantics, or OG
+ * covers — those differ (share uses an email-handle namespace with public reads
+ * and covers; a traces/sessions adapter uses the userId and differs again). Each
+ * surface keeps its own DISCRIMINATED, typed adapter that reads this decision and
+ * returns its own `kind`-tagged backend. See `lib/share/backend.ts` and
+ * `lib/traces/backend.ts` for the two adapters.
+ */
+import { readSession } from '../identity/client.js';
+/**
+ * Pick the storage principal. Managed when signed in (`readSession() != null`)
+ * AND the surface reported no explicit BYO override; otherwise BYO.
+ *
+ * This is not a fallback chain — it is a single decision. A surface that cannot
+ * authenticate EITHER principal (signed out AND no BYO config) still reads `byo`
+ * here and fails loud in its own adapter, where the actionable "run auth login
+ * or set up your bucket" message belongs.
+ */
+export function selectStorageBackendKind(opts = {}) {
+    if (opts.byoOverride === true)
+        return 'byo';
+    const session = opts.session === undefined ? readSession() : opts.session;
+    return session != null ? 'managed' : 'byo';
+}
+/** True when the shared policy resolves to the managed principal. Thin sugar
+ * over {@link selectStorageBackendKind} for the common boolean check. */
+export function isManagedSelection(opts = {}) {
+    return selectStorageBackendKind(opts) === 'managed';
+}

package/dist/lib/storage/visibility.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The ONE visibility model, identical on every surface that publishes to managed
+ * storage. Three levels the operator ever chooses between:
+ *
+ *   - PRIVATE  = `me`      — owner-only, Phoenix-gated. THE DEFAULT for a new
+ *                            managed share (see {@link MANAGED_DEFAULT_VISIBILITY}).
+ *   - TEAM     = `org`     — everyone at the sharer's signed-in email DOMAIN,
+ *                            Phoenix-gated. Automatic from the domain — there is
+ *                            no organization to create and no member to add.
+ *   - PUBLIC   = `public`  — explicit opt-in; listed in the gallery, gets an OG
+ *                            card.
+ *
+ * Two capability-URL levels remain for the power path (unguessable link, not a
+ * login gate): `unlisted` (obscurity — noindex, gallery-hidden, still
+ * world-readable) and `private`-token-gated (`--protected`: a `?k=` key the
+ * Worker checks, 404 without it). `me`/`org` require a Phoenix session; the
+ * Worker refuses them for a bare WRITE_TOKEN (BYO) publish, which is why the BYO
+ * default stays `public`.
+ *
+ * The names match the Worker's own metadata vocabulary (`lib/share/worker-template.ts`),
+ * so this module is the single client-side source of truth for the level set and
+ * the DEFAULT, reusable by any surface.
+ */
+/** Every visibility level the Worker understands. `me`/`org` are the
+ * Phoenix-gated (login-required) levels; `public`/`unlisted`/`private` are the
+ * link-reachable levels. */
+export type ShareVisibility = 'public' | 'unlisted' | 'private' | 'me' | 'org';
+/** The levels a publish (`share <file> --visibility`) may select. */
+export declare const PUBLISH_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/** The levels an ALREADY-published page may be re-scoped to in place
+ * (`share visibility <target> <level>`). Excludes `private`: re-scoping to
+ * token-gated needs a fresh viewer token, which only the publish path mints. */
+export declare const EDITABLE_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/**
+ * The product default for a MANAGED (signed-in) share: PRIVATE = owner-only,
+ * Phoenix-gated. A publish with no visibility flag lands here.
+ */
+export declare const MANAGED_DEFAULT_VISIBILITY: ShareVisibility;
+/**
+ * The default for a BYO (bring-your-own bucket) publish. `me`/`org` are refused
+ * server-side for a WRITE_TOKEN publish — there is no Phoenix owner to gate on —
+ * so a BYO share with no flag stays `public`, matching the pre-managed behavior.
+ */
+export declare const BYO_DEFAULT_VISIBILITY: ShareVisibility;
+import type { StorageBackendKind } from './selection.js';
+/** The no-flags default for a given storage backend: `me` on managed,
+ * `public` on BYO. */
+export declare function defaultVisibilityForBackend(kind: StorageBackendKind): ShareVisibility;
+export interface VisibilityFlags {
+    /** An explicit `--visibility <level>`. */
+    visibility?: ShareVisibility;
+    /** `--unlisted` / `--private` (obscurity, not read-auth). */
+    unlisted?: boolean;
+    /** `--protected` — token-gated read auth (maps to `private`). */
+    protected?: boolean;
+}
+/**
+ * The visibility the caller EXPLICITLY asked for, or `undefined` when they
+ * passed no visibility signal at all. `--protected` wins over `--unlisted`
+ * (stronger control), which wins over an explicit `--visibility`.
+ *
+ * The distinction between "explicit" and "no preference" is what lets a caller
+ * apply the product default only when nothing was asked — a caller that passes
+ * `--visibility public` gets `public`, never the `me` default.
+ */
+export declare function explicitVisibility(opts?: VisibilityFlags): ShareVisibility | undefined;
+/**
+ * Resolve visibility from the caller's flags, falling back to `fallback` when no
+ * explicit signal was given. The library fallback stays `public` so a caller
+ * that hasn't opted into the managed private default (e.g. an existing lib
+ * consumer) is never silently flipped; the surface applies the product default
+ * itself via {@link defaultVisibilityForBackend}.
+ */
+export declare function resolveVisibility(opts?: VisibilityFlags, fallback?: ShareVisibility): ShareVisibility;
+/**
+ * The visibility a PUBLISH should stamp: the caller's explicit flag if any, else
+ * the product default for the resolved backend (`me` on managed, `public` on
+ * BYO). This is the one call a publishing surface makes — `agents artifacts
+ * share` today, `agents sessions` sync next — so "private by default when signed
+ * in" is decided in exactly one place.
+ */
+export declare function publishVisibility(opts: VisibilityFlags, kind: StorageBackendKind): ShareVisibility;

package/dist/lib/storage/visibility.js

@@ -0,0 +1,99 @@
+/**
+ * The ONE visibility model, identical on every surface that publishes to managed
+ * storage. Three levels the operator ever chooses between:
+ *
+ *   - PRIVATE  = `me`      — owner-only, Phoenix-gated. THE DEFAULT for a new
+ *                            managed share (see {@link MANAGED_DEFAULT_VISIBILITY}).
+ *   - TEAM     = `org`     — everyone at the sharer's signed-in email DOMAIN,
+ *                            Phoenix-gated. Automatic from the domain — there is
+ *                            no organization to create and no member to add.
+ *   - PUBLIC   = `public`  — explicit opt-in; listed in the gallery, gets an OG
+ *                            card.
+ *
+ * Two capability-URL levels remain for the power path (unguessable link, not a
+ * login gate): `unlisted` (obscurity — noindex, gallery-hidden, still
+ * world-readable) and `private`-token-gated (`--protected`: a `?k=` key the
+ * Worker checks, 404 without it). `me`/`org` require a Phoenix session; the
+ * Worker refuses them for a bare WRITE_TOKEN (BYO) publish, which is why the BYO
+ * default stays `public`.
+ *
+ * The names match the Worker's own metadata vocabulary (`lib/share/worker-template.ts`),
+ * so this module is the single client-side source of truth for the level set and
+ * the DEFAULT, reusable by any surface.
+ */
+/** The levels a publish (`share <file> --visibility`) may select. */
+export const PUBLISH_VISIBILITY_LEVELS = [
+    'public',
+    'unlisted',
+    'private',
+    'me',
+    'org',
+];
+/** The levels an ALREADY-published page may be re-scoped to in place
+ * (`share visibility <target> <level>`). Excludes `private`: re-scoping to
+ * token-gated needs a fresh viewer token, which only the publish path mints. */
+export const EDITABLE_VISIBILITY_LEVELS = [
+    'public',
+    'unlisted',
+    'me',
+    'org',
+];
+/**
+ * The product default for a MANAGED (signed-in) share: PRIVATE = owner-only,
+ * Phoenix-gated. A publish with no visibility flag lands here.
+ */
+export const MANAGED_DEFAULT_VISIBILITY = 'me';
+/**
+ * The default for a BYO (bring-your-own bucket) publish. `me`/`org` are refused
+ * server-side for a WRITE_TOKEN publish — there is no Phoenix owner to gate on —
+ * so a BYO share with no flag stays `public`, matching the pre-managed behavior.
+ */
+export const BYO_DEFAULT_VISIBILITY = 'public';
+/** The no-flags default for a given storage backend: `me` on managed,
+ * `public` on BYO. */
+export function defaultVisibilityForBackend(kind) {
+    return kind === 'managed' ? MANAGED_DEFAULT_VISIBILITY : BYO_DEFAULT_VISIBILITY;
+}
+/**
+ * The visibility the caller EXPLICITLY asked for, or `undefined` when they
+ * passed no visibility signal at all. `--protected` wins over `--unlisted`
+ * (stronger control), which wins over an explicit `--visibility`.
+ *
+ * The distinction between "explicit" and "no preference" is what lets a caller
+ * apply the product default only when nothing was asked — a caller that passes
+ * `--visibility public` gets `public`, never the `me` default.
+ */
+export function explicitVisibility(opts = {}) {
+    if (opts.protected === true)
+        return 'private';
+    if (opts.unlisted === true)
+        return 'unlisted';
+    if (opts.visibility === 'public' ||
+        opts.visibility === 'unlisted' ||
+        opts.visibility === 'private' ||
+        opts.visibility === 'me' ||
+        opts.visibility === 'org') {
+        return opts.visibility;
+    }
+    return undefined;
+}
+/**
+ * Resolve visibility from the caller's flags, falling back to `fallback` when no
+ * explicit signal was given. The library fallback stays `public` so a caller
+ * that hasn't opted into the managed private default (e.g. an existing lib
+ * consumer) is never silently flipped; the surface applies the product default
+ * itself via {@link defaultVisibilityForBackend}.
+ */
+export function resolveVisibility(opts = {}, fallback = 'public') {
+    return explicitVisibility(opts) ?? fallback;
+}
+/**
+ * The visibility a PUBLISH should stamp: the caller's explicit flag if any, else
+ * the product default for the resolved backend (`me` on managed, `public` on
+ * BYO). This is the one call a publishing surface makes — `agents artifacts
+ * share` today, `agents sessions` sync next — so "private by default when signed
+ * in" is decided in exactly one place.
+ */
+export function publishVisibility(opts, kind) {
+    return explicitVisibility(opts) ?? defaultVisibilityForBackend(kind);
+}

package/dist/lib/teams/agents.js

@@ -2361,7 +2361,9 @@ export class AgentManager {
                     ? `at its agents.max-concurrent cap (${e.detail} running)`
                     : e.reason === 'not-installed'
                         ? `does not have ${this.placementAgentLabel(agent)} installed`
-                        : e.reason;
+                        : e.reason === 'probe-timed-out'
+                            ? 'did not answer the probe in time (likely up but on a slow/relayed link)'
+                            : e.reason;
                 console.error(chalk.dim(`[placement] '${e.device}' excluded from auto-pick — ${why}`));
             }
         }

package/dist/lib/teams/placement-probe.js

@@ -137,6 +137,7 @@ export async function probePoolSignals(pool, agent, opts = {}) {
             continue; // fully unknown device — leave it out of the map
         signals.set(name, {
             reachable: s?.reachable,
+            timedOut: s?.timedOut,
             headroom: s ? headroom(s) : undefined,
             loadPercent: s?.loadPercent,
             memPercent: s?.memPercent,

package/dist/lib/teams/registry.js

@@ -14,6 +14,7 @@ import lockfile from 'proper-lockfile';
 import { getTeamsRegistryPath } from '../state.js';
 import { emit } from '../feed/events.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
+import { logAndContinueOnLockCompromised } from '../lock-compromise.js';
 async function registryPath() {
     return getTeamsRegistryPath();
 }
@@ -38,6 +39,7 @@ async function withRegistryLock(p, fn) {
     const release = await lockfile.lock(p, {
         retries: { retries: 60, minTimeout: 25, maxTimeout: 250, factor: 1.5 },
         stale: 10_000,
+        onCompromised: logAndContinueOnLockCompromised('teams registry'),
     });
     try {
         return await fn();

package/dist/lib/teams/scheduler.d.ts

@@ -10,6 +10,13 @@ import type { Headroom } from '../devices/health.js';
 export interface DevicePlacementSignal {
     /** SSH probe answered. `false` → excluded (unreachable). undefined → unknown. */
     reachable?: boolean;
+    /**
+     * The probe was killed for exceeding its budget rather than failing to
+     * connect. Ranking treats it exactly like `reachable:false` — an
+     * unresponsive box is still not placeable — but the operator-facing
+     * exclusion reason says "probe timed out", not "unreachable" (PHNX-3682).
+     */
+    timedOut?: boolean;
     /** Headroom bucket from load+memory. `'loaded'` → excluded (overloaded). */
     headroom?: Headroom;
     /** Normalized CPU load percent (finer rank tiebreak within a headroom tier). */
@@ -60,7 +67,7 @@ export interface PlacementOptions {
     preferred?: ReadonlySet<string>;
 }
 /** Why a device was excluded from the viable set, for the fail-loud message. */
-export type ExclusionReason = 'unreachable' | 'overloaded' | 'capped' | 'not-installed';
+export type ExclusionReason = 'unreachable' | 'probe-timed-out' | 'overloaded' | 'capped' | 'not-installed';
 /** A pool device dropped from the auto-pick, with the reason + live detail. */
 export interface ExcludedDevice {
     device: string;

package/dist/lib/teams/scheduler.js

@@ -199,7 +199,10 @@ export function classifyExclusions(devices, roster, opts) {
     for (const d of devices) {
         const s = signals?.get(d);
         if (s?.reachable === false) {
-            excluded.push({ device: d, reason: 'unreachable' });
+            // A probe killed for exceeding its budget is a slow link, not a box that
+            // is down. Same exclusion either way — an unresponsive device is still not
+            // placeable — but the operator sees which one it was (PHNX-3682).
+            excluded.push({ device: d, reason: s.timedOut ? 'probe-timed-out' : 'unreachable' });
             continue;
         }
         if (s?.installed === false) {

package/dist/lib/testdata/daemon-health-writer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/testdata/daemon-health-writer.js

@@ -0,0 +1,8 @@
+import { recordSubsystemError } from '../daemon-health.js';
+const [subsystem, countRaw] = process.argv.slice(2);
+const count = Number(countRaw);
+if (!subsystem || !Number.isInteger(count) || count < 1)
+    process.exit(2);
+for (let i = 0; i < count; i++) {
+    recordSubsystemError(subsystem, `${process.pid}:${i}`);
+}

package/dist/lib/traces/backend.js

@@ -10,6 +10,7 @@
  * `agents artifacts setup`.
  */
 import { readSession } from '../identity/client.js';
+import { selectStorageBackendKind } from '../storage/selection.js';
 export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
 /**
  * Resolve the backend for the current machine. Throws when not signed in.
@@ -21,11 +22,21 @@ export const DEFAULT_TRACES_DOMAIN = 'traces.agents-cli.sh';
 export function resolveTracesBackend() {
     const envBase = (process.env['AGENTS_TRACES_BASE_URL'] ?? '').replace(/\/+$/, '').trim();
     const envToken = (process.env['AGENTS_TRACES_WRITE_TOKEN'] ?? '').trim();
-    if (envBase && envToken) {
-        return { baseUrl: envBase, token: envToken, userId: 'byo' };
+    // The traces surface's only BYO signal is the full BASE_URL + WRITE_TOKEN env
+    // pair; the managed-vs-BYO decision itself is the shared selection policy.
+    const byoOverride = Boolean(envBase && envToken);
+    if (selectStorageBackendKind({ byoOverride }) === 'byo') {
+        if (byoOverride) {
+            return { baseUrl: envBase, token: envToken, userId: 'byo' };
+        }
+        // Not signed in and no BYO env pair — the managed principal is the only one
+        // this surface exposes, so fail loud with the login hint.
+        throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     const session = readSession();
     if (!session) {
+        // selectStorageBackendKind read the same session and returned 'managed', so a
+        // null here means it was cleared between the two reads — treat as signed out.
         throw new Error("Not signed in. Run 'agents auth login' to sync traces to your Phoenix account.");
     }
     if (!session.access_token) {

package/dist/lib/traces/sync.d.ts

@@ -390,6 +390,13 @@ interface SyncLedger {
 }
 export declare function readSyncLedger(): SyncLedger;
 export declare function writeSyncLedger(ledger: SyncLedger): void;
+/**
+ * True once the user has run `agents traces sync` at least once (the ledger
+ * file exists). This is the opt-in signal the run-exit auto-sync gates on
+ * (PHNX-3628): a user who has never synced has not opted into the traces store,
+ * so an `agents run` never uploads on their behalf.
+ */
+export declare function hasSyncedBefore(): boolean;
 export interface SyncRow {
     id: string;
     short_id: string;

package/dist/lib/traces/sync.js

@@ -816,6 +816,15 @@ export function writeSyncLedger(ledger) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(ledger, null, 2) + '\n', 'utf8');
 }
+/**
+ * True once the user has run `agents traces sync` at least once (the ledger
+ * file exists). This is the opt-in signal the run-exit auto-sync gates on
+ * (PHNX-3628): a user who has never synced has not opted into the traces store,
+ * so an `agents run` never uploads on their behalf.
+ */
+export function hasSyncedBefore() {
+    return fs.existsSync(ledgerPath());
+}
 // ---------------------------------------------------------------------------
 // Local device name
 // ---------------------------------------------------------------------------

package/dist/lib/usage-refresh.d.ts

@@ -150,8 +150,12 @@ export declare function providerSpacingTokens(lastCallMs: number, now: number):
 export interface LocalUsageAccount {
     usageKey: string;
     agentId: AgentId;
-    /** Live-fetch this account's usage; the daemon passes the real network fetch. */
-    fetch: () => Promise<UsageInfo>;
+    /**
+     * Live-fetch this account's usage; the daemon passes the real network fetch.
+     * `signal` (the daemon tick's deadline AbortSignal) bounds the provider fetch
+     * so a hung refresh is aborted at deadlineMs, not just its own 5s timeout.
+     */
+    fetch: (signal?: AbortSignal) => Promise<UsageInfo>;
 }
 /**
  * Order a pass STALEST-FIRST so a scarce per-provider budget
@@ -206,6 +210,8 @@ export interface UsageRefreshDeps {
      * spending scarce provider budget re-fetching an already-current account.
      */
     readCachedSnapshot?: (usageKey: string) => UsageSnapshot | null;
+    /** Daemon tick deadline signal, forwarded to each account's provider fetch (PHNX-3608). */
+    signal?: AbortSignal;
 }
 export interface UsageRefreshResult {
     refreshed: number;

package/dist/lib/usage-refresh.js

@@ -392,14 +392,14 @@ export async function buildLocalUsageAccounts() {
                 // only, never the interactive login (see loadClaudeOauth); no setup-token
                 // reads as "usage unavailable (no usage credential)" — "usage pending"
                 // is now the cold-cache state only (#2987).
-                fetch: async () => {
+                fetch: async (signal) => {
                     const { getUsageInfoForIdentity } = await import('./accounting/usage.js');
                     return getUsageInfoForIdentity({
                         agentId,
                         home: fetchInput.home,
                         cliVersion: fetchInput.cliVersion,
                         info: canonical,
-                    }, { forceRefresh: true, fileOnly: true });
+                    }, { forceRefresh: true, fileOnly: true, signal });
                 },
             });
         }
@@ -487,7 +487,7 @@ export async function runUsageRefresh(deps) {
             spacingUsed.set(account.agentId, (spacingUsed.get(account.agentId) ?? 0) + 1);
         }
         try {
-            const usage = await account.fetch();
+            const usage = await account.fetch(deps.signal);
             if (usage.snapshot) {
                 // `source` is provenance, not freshness. A forced collection that just
                 // reread a local harness event returns `last_seen`; that is still a