@phnx-labs/agents-cli 1.22.65 → 1.22.68

package/dist/lib/share/publish.js

@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { hostname as osHostname } from 'node:os';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { readSession } from '../identity/client.js';
 import { readShareConfig } from './config.js';
 import { resolveGitHubUsername } from '../git.js';
@@ -18,20 +18,72 @@ import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
 import { injectAnalyticsBeacon } from './analytics.js';
 import { prepareShareHtml } from './html.js';
-/** The visibility levels a share may carry — the Worker's own set, used to
- * validate `--visibility` and `share visibility <target> <level>`. */
+/** The visibility levels a publish `--visibility` may select — the Worker's own
+ * set. `private` (token-gated, PHNX-3654) is settable only at publish time,
+ * since it mints a viewer token the metadata-edit route can't carry, so it is
+ * NOT in {@link SHARE_VISIBILITY_LEVELS} (the in-place `share visibility <level>`
+ * set). */
+export const PUBLISH_VISIBILITY_LEVELS = ['public', 'unlisted', 'private', 'me', 'org'];
+/** The visibility levels an ALREADY-published share may be re-scoped to in place
+ * — the set `share visibility <target> <level>` and the inline owner control
+ * accept. Excludes `private`: re-scoping to token-gated needs a fresh viewer
+ * token, which only the publish path mints. */
 export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
 /**
- * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
- * passes through; otherwise `visibility` (default public).
+ * `--protected` / `{ protected: true }` map to `private` (token-gated — it wins
+ * over `--unlisted` when both are set, being the stronger control); `--unlisted`
+ * maps to `unlisted`; `--visibility private|unlisted|me|org` passes through;
+ * otherwise `visibility` (default public).
  */
 export function resolveShareVisibility(opts = {}) {
+    if (opts.protected === true)
+        return 'private';
     if (opts.unlisted === true)
         return 'unlisted';
-    if (opts.visibility === 'unlisted' || opts.visibility === 'me' || opts.visibility === 'org')
+    if (opts.visibility === 'unlisted' ||
+        opts.visibility === 'private' ||
+        opts.visibility === 'me' ||
+        opts.visibility === 'org') {
         return opts.visibility;
+    }
     return 'public';
 }
+/** The bytes of viewer-token entropy the `private` mode mints (128-bit; the
+ * base64url form is ~22 URL-safe chars). Well past the 64-bit floor a guessable
+ * capability URL would fall to. */
+const VIEWER_TOKEN_BYTES = 16;
+/** Mint a fresh random viewer token for a `private` (token-gated) publish. The
+ * raw token rides ONLY in the returned URL's `?k=`; the Worker stores just its
+ * SHA-256 hash, so the object metadata never carries the secret. */
+export function generateViewerToken() {
+    return randomBytes(VIEWER_TOKEN_BYTES).toString('base64url');
+}
+/** SHA-256 hex of a viewer token — the form the Worker also computes and stores,
+ * so a CLI-side preview of the stored hash matches. Exported for tests. */
+export function hashViewerToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/** A 64-bit random slug tail (16 lowercase hex chars) for a capability-URL
+ * publish, so the slug can never be derived/guessed from the title (PHNX-3654).
+ * `unlisted` leans on this for obscurity; `private` uses it as defense-in-depth
+ * behind the viewer token. */
+export function randomSlugTail() {
+    return randomBytes(8).toString('hex');
+}
+/**
+ * The loud stderr warning printed on an `unlisted` / `--private` publish
+ * (PHNX-3654): `unlisted` is obscurity, NOT read-authentication — anyone with
+ * the URL can read it. Points the user at the real controls (`--protected`,
+ * `--expire`, `me`/`org`). Lives here beside the visibility logic; `share.ts`
+ * prints it so the lib layer stays free of `console.*`.
+ */
+export function unlistedNotPrivateWarning() {
+    return ('unlisted is NOT private — anyone with the URL can read it (a capability link, ' +
+        'hidden from the gallery and marked noindex, but not authenticated).\n' +
+        '  For sensitive content use --protected (a token-gated link that returns 404 ' +
+        'without the key), and/or --expire to bound the window; --visibility me|org ' +
+        'gates on your Phoenix login.');
+}
 /**
  * Reserved `customMetadata` keys a `--meta key=value` may not target (see
  * {@link parseMetaEntries}). Matches the Worker's `RESERVED_METADATA_KEYS`:
@@ -42,6 +94,7 @@ export const RESERVED_META_KEYS = [
     'expires-at',
     'published-at',
     'visibility',
+    'viewer-token-hash',
     'owner',
     'org_domain',
     'agent',
@@ -516,11 +569,26 @@ export async function publishFile(filePath, opts = {}) {
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const username = await resolveShareUsername(opts);
     let body = readFileSync(filePath);
-    const slugPart = (opts.slug ?? defaultSlug(filePath, body)).replace(/^\/+/, '');
-    const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
     const visibility = resolveShareVisibility(opts);
     const unlisted = visibility === 'unlisted';
+    // A capability-URL publish (unlisted / token-gated private) must not have a
+    // guessable slug — that was the PHNX-3654 hole. Without an explicit --slug the
+    // slug always carries a 64-bit random tail (a title-derived prefix may lead it,
+    // but the random suffix is what makes the whole URL unguessable); an explicit
+    // --slug is the caller's own choice (e.g. republishing to a known URL) and is
+    // honored verbatim.
+    const capabilityUrl = visibility === 'unlisted' || visibility === 'private';
+    const explicitSlug = typeof opts.slug === 'string' && opts.slug.trim() !== '';
+    const slugPart = (explicitSlug
+        ? opts.slug
+        : capabilityUrl
+            ? `${defaultSlug(filePath, body)}-${randomSlugTail()}`
+            : defaultSlug(filePath, body)).replace(/^\/+/, '');
+    const key = buildShareKey(username, slugPart);
+    // Token-gated read auth (PHNX-3654): mint a random viewer token for a private
+    // publish. Only its hash is sent to the Worker; the raw token rides in ?k=.
+    const viewerToken = visibility === 'private' ? generateViewerToken() : undefined;
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
     const avatarUrl = opts.avatar ?? resolveShareAvatar({ session: opts.session });
@@ -598,6 +666,11 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         h['x-share-visibility'] = visibility;
+        // Token-gated read auth (PHNX-3654): send the RAW viewer token. The Worker
+        // hashes it (SHA-256) and stores only the hash in customMetadata, so the
+        // secret never lands in object metadata. Only present for a private publish.
+        if (viewerToken)
+            h['x-share-viewer-token'] = viewerToken;
         // Two headers per free-text field, backward-compatible by construction
         // (PHNX-2786): `x-share-<field>` always carries the latin1-safe folded value
         // an already-deployed Worker reads verbatim, and — only when the fold is lossy
@@ -677,8 +750,12 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         }
         throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
+    // A token-gated page is only reachable WITH its key, so the URL we hand back
+    // (and store nowhere) carries it — https://<host>/<user>/<slug>?k=<token>.
+    const baseUrl = r.url ?? pageUrl;
+    const url = viewerToken ? `${baseUrl}?k=${encodeURIComponent(viewerToken)}` : baseUrl;
     return {
-        url: r.url ?? pageUrl,
+        url,
         slug: key.slice(key.indexOf('/') + 1),
         expiresAt,
         coverUrl,
@@ -686,5 +763,6 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         labelSource,
         visibility,
         ...(unlisted ? { unlisted: true } : {}),
+        ...(viewerToken ? { viewerToken } : {}),
     };
 }

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

@@ -137,6 +137,18 @@ export default {
           }
         }
       }
+      // Token-gated read auth (PHNX-3654). A 'private' page is served only to a
+      // request carrying the matching viewer key; we store just its SHA-256 hash
+      // so the secret never lands in R2 metadata. Any write principal (Phoenix or
+      // BYO WRITE_TOKEN) may publish 'private' — the gate is the token, not an
+      // identity, unlike me/org. The token is mandatory: a private page with no
+      // stored hash fails closed on read, so refuse the write instead.
+      let viewerTokenHash = '';
+      if (visibility === 'private') {
+        const rawToken = request.headers.get('x-share-viewer-token') || '';
+        if (!rawToken) return json({ error: 'visibility private requires a viewer token' }, 400);
+        viewerTokenHash = await sha256Hex(rawToken);
+      }
       const segments = path.split('/').filter(Boolean);
       if (auth.kind === 'phoenix') {
         const expected = phoenixHandle(auth);
@@ -225,6 +237,7 @@ export default {
       }
       if (expiresAt) customMetadata['expires-at'] = expiresAt;
       customMetadata['visibility'] = visibility;
+      if (viewerTokenHash) customMetadata['viewer-token-hash'] = viewerTokenHash;
       const owner =
         auth.kind === 'phoenix'
           ? auth.owner
@@ -364,6 +377,11 @@ export default {
         const vis = normalizeVisibility(edit.visibility);
         if (vis.error) return vis.error;
         const visibility = vis.value;
+        // 'private' can't be set via the metadata-edit route: token-gating needs a
+        // fresh viewer key, which only a full publish mints (PHNX-3654). Re-stamping
+        // visibility=private here alone would leave the page gated by a hash that
+        // never got stored — inaccessible to everyone. Fail loud.
+        if (visibility === 'private') return json({ error: 'visibility private must be set at publish time (share --protected)' }, 400);
         if (visibility === 'me' || visibility === 'org') {
           const phoenixBase = typeof env.PHOENIX_ID_BASE === 'string' ? env.PHOENIX_ID_BASE.replace(/\\/+$/, '') : '';
           if (auth.kind !== 'phoenix' || !phoenixBase) return json({ error: 'visibility me/org requires Phoenix identity' }, 400);
@@ -459,23 +477,33 @@ export default {
       // ?revisions=json must not leak that the page exists.
       if (segments.length === 2 && url.searchParams.get('revisions') === 'json') {
         const canonical = await env.BUCKET.get(path);
+        const canonicalVis = canonical ? ((canonical.customMetadata && canonical.customMetadata.visibility) || 'public') : 'public';
         // Only a me/org canonical needs the viewer resolved — and only there does
         // a phoenix_ticket failure gate the response, exactly as before this route
         // shared resolveViewer with the page GET. A public/unlisted revision list
         // never invoked ticket redemption, so a stale ticket must not 401 it.
-        if (canonical && isIdentityGated((canonical.customMetadata && canonical.customMetadata.visibility) || 'public')) {
+        if (canonical && isIdentityGated(canonicalVis)) {
           const viewer = await resolveViewer(request, env, url);
           if (viewer.redirect) return viewer.redirect;
           if (viewer.error) return viewer.error;
           const denied = gateVisibility(url, env, canonical, viewer.identity || null);
           if (denied) return denied;
         }
+        // A private canonical gates its revision list on the viewer key too
+        // (PHNX-3654) — listing session/host/repo of a token-gated page to an
+        // unauthenticated caller would leak the very metadata the gate protects.
+        if (canonical && canonicalVis === 'private') {
+          const viewer = await resolveViewer(request, env, url);
+          if (viewer.redirect) return viewer.redirect;
+          const tokenDenied = await gateTokenRead(request, url, canonical, viewer.identity || null);
+          if (tokenDenied) return tokenDenied;
+        }
         return renderRevisions(
           env.BUCKET,
           url.origin,
           path,
           request.method,
-          canonical && isIdentityGated((canonical.customMetadata && canonical.customMetadata.visibility) || 'public'),
+          !!canonical && (isIdentityGated(canonicalVis) || canonicalVis === 'private'),
         );
       }
 
@@ -498,6 +526,10 @@ export default {
             if (viewer.error && isIdentityGated(pageVisibility)) return viewer.error;
             const denied = gateVisibility(url, env, page, viewer.identity || null);
             if (denied) return denied;
+            // A token-gated page's cover is token-gated too (PHNX-3654): a crawler
+            // fetching <slug>.png without the key gets 404, so no preview leaks.
+            const coverTokenDenied = await gateTokenRead(request, url, page, viewer.identity || null);
+            if (coverTokenDenied) return coverTokenDenied;
 
             if (existingCover && existingCover.customMetadata['og-source-etag'] === page.etag) {
               const current = await env.BUCKET.get(pagePath);
@@ -589,6 +621,12 @@ export default {
       const identity = viewer.identity || null;
       const denied = gateVisibility(url, env, obj, identity);
       if (denied) return denied;
+      // Token-gated read auth (PHNX-3654): a 'private' page is served only to a
+      // request carrying the matching viewer key (?k= or Bearer), or to its owner.
+      // A miss returns 404 — never leaking that the page exists — exactly like a
+      // wrong me/org viewer.
+      const tokenDenied = await gateTokenRead(request, url, obj, identity);
+      if (tokenDenied) return tokenDenied;
       // The owner of the namespace (their handle === the first path segment) gets
       // an interactive visibility control; everyone else keeps the static cue.
       const isOwner = !!identity && handleFromEmail(identity.email) === firstSeg;
@@ -597,7 +635,9 @@ export default {
       obj.writeHttpMetadata(headers);
       headers.set('etag', obj.httpEtag);
       if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8');
-      if (visibility === 'me' || visibility === 'org') {
+      if (visibility === 'me' || visibility === 'org' || visibility === 'private') {
+        // Token-gated + identity-gated reads must never be cached by a shared
+        // proxy, and never indexed.
         headers.set('cache-control', 'private, no-store');
         headers.set('X-Robots-Tag', 'noindex');
       } else {
@@ -647,7 +687,11 @@ export default {
       // without text/html) falls through to raw bytes so embedding is never broken.
       const wantsRaw = url.searchParams.get('raw') != null;
       const kind = viewableAssetKind(ctype);
-      if (!wantsRaw && kind && acceptsHtml(request)) {
+      // A token-gated (private) asset is served as raw bytes, NOT wrapped in the
+      // viewer page (PHNX-3654): the viewer's inner <img src=…?raw> would drop the
+      // ?k= key and 404 (there's no cookie to carry it, unlike me/org), breaking the
+      // media. The gate already passed above, so the raw bytes are safe to serve.
+      if (!wantsRaw && kind && acceptsHtml(request) && visibility !== 'private') {
         const viewerPage = renderAssetViewer(url.pathname, kind, obj.customMetadata || {}, firstSeg, {
           isOwner,
           ownerDomain,
@@ -896,7 +940,7 @@ async function renderRevisions(bucket, origin, key, method, identityGated) {
 // before it ever reaches this Worker; see RESERVED_META_KEYS in publish.ts).
 // One list, reused both to strip a same-named --meta collision on write and
 // to split arbitrary --meta entries back out on read.
-var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source', 'og-title', 'og-description', 'og-generated', 'og-source-etag'];
+var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'viewer-token-hash', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source', 'og-title', 'og-description', 'og-generated', 'og-source-etag'];
 var PUBLIC_INBOX_DOMAINS = ['gmail.com', 'googlemail.com', 'outlook.com', 'hotmail.com', 'live.com', 'icloud.com', 'me.com'];
 var SHARE_COOKIE = '__Host-phoenix_share';
 var SHARE_COOKIE_MAX_AGE = 604800;
@@ -1025,6 +1069,7 @@ var ASH_OWNER_JS = \`(function(){
 function visibilityChip(visibility, orgDomain) {
   if (visibility === 'me') return { icon: VIS_ICON.me, label: 'Only you', color: '#f59e0b' };
   if (visibility === 'org') return { icon: VIS_ICON.org, label: 'Anyone at ' + escapeHtml(orgDomain || 'your organization'), color: '#5b9dff' };
+  if (visibility === 'private') return { icon: VIS_ICON.me, label: 'Protected (link + key)', color: '#f59e0b' };
   if (visibility === 'unlisted') return { icon: VIS_ICON.unlisted, label: 'Unlisted', color: '#9aa0a6' };
   return { icon: VIS_ICON.public, label: 'Public', color: '#30a46c' };
 }
@@ -1340,8 +1385,8 @@ async function claimHandle(bucket, handle, userId) {
 function normalizeVisibility(raw) {
   const v = (raw || '').trim().toLowerCase();
   if (!v || v === 'public') return { value: 'public' };
-  if (v === 'unlisted' || v === 'me' || v === 'org') return { value: v };
-  return { error: json({ error: 'visibility must be public, unlisted, me, or org' }, 400) };
+  if (v === 'unlisted' || v === 'private' || v === 'me' || v === 'org') return { value: v };
+  return { error: json({ error: 'visibility must be public, unlisted, private, me, or org' }, 400) };
 }
 
 function emailDomain(email) {
@@ -1352,7 +1397,7 @@ function emailDomain(email) {
 }
 
 function isHiddenFromGallery(visibility) {
-  return visibility === 'unlisted' || visibility === 'me' || visibility === 'org';
+  return visibility === 'unlisted' || visibility === 'private' || visibility === 'me' || visibility === 'org';
 }
 
 function isIdentityGated(visibility) {
@@ -1384,6 +1429,52 @@ function gateVisibility(url, env, obj, identity) {
   return null;
 }
 
+// SHA-256 hex of a string — the form a 'private' object's stored
+// 'viewer-token-hash' takes. Both the PUT (hash-on-store) and the read gate use
+// this, so a token minted by the CLI matches byte-for-byte (PHNX-3654).
+async function sha256Hex(text) {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(text)));
+  return bufToHex(digest);
+}
+
+// The viewer key a reader presents for a token-gated ('private') page: the ?k=
+// query param first (the shape the CLI emits — https://host/<u>/<s>?k=<token>),
+// then an Authorization: Bearer token as an alternative for scripted callers.
+function readViewerKey(request, url) {
+  const q = url.searchParams.get('k');
+  if (q) return q;
+  const bearer = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  return bearer || '';
+}
+
+// Gate a 'private' (token-gated) read (PHNX-3654). Returns a 404 Response when
+// the request may NOT read, or null when it may. A miss ALWAYS 404s — never a
+// 401 and never a distinct "wrong key" — so a token-gated page never even leaks
+// that it exists, exactly like a wrong me/org viewer. The namespace owner
+// (resolved identity whose userId stamped the object) is let through without the
+// key so 'share open' and the owner's own browsing still work. Constant-time
+// compare (safeEqual) over the stored SHA-256 hash keeps the check timing-safe.
+async function gateTokenRead(request, url, obj, identity) {
+  const meta = obj.customMetadata || {};
+  const visibility = meta.visibility || 'public';
+  if (visibility !== 'private') return null;
+  const notFound = function () {
+    return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  };
+  // Owner bypass: the signed-in owner of the page reads their own private page
+  // without the key (mirrors 'me').
+  if (identity && meta.owner && meta.owner === identity.userId) return null;
+  const stored = meta['viewer-token-hash'] || '';
+  // Fail closed: a private object with no stored hash can never be matched, so it
+  // is unreadable rather than accidentally public.
+  if (!stored) return notFound();
+  const presented = readViewerKey(request, url);
+  if (!presented) return notFound();
+  const presentedHash = await sha256Hex(presented);
+  if (!safeEqual(presentedHash, stored)) return notFound();
+  return null;
+}
+
 // Per-slug view counter, stored as a SEPARATE R2 object under __views/<path> so
 // counting a view never rewrites the page object (which would reset its uploaded
 // timestamp and corrupt "last updated"). Best-effort telemetry: a read/write
@@ -1805,6 +1896,7 @@ async function renderOgCard(input) {
   const visibilityLabels = {
     public: 'PUBLIC',
     unlisted: 'UNLISTED',
+    private: 'PROTECTED',
     me: 'ONLY YOU',
     org: input.orgDomain ? 'ANYONE AT ' + input.orgDomain.toUpperCase() : 'ORGANIZATION',
   };

package/dist/lib/ssh-exec.d.ts

@@ -126,6 +126,8 @@ export interface SshExecResult {
     stderr: string;
     timedOut: boolean;
 }
+/** Grace after a timed-out child receives SIGTERM before SIGKILL enforces the bound. */
+export declare const SSH_TIMEOUT_KILL_GRACE_MS = 250;
 /**
  * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
  *

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/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/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/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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.65",
+  "version": "1.22.68",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",

package/dist/lib/account-state-service.d.ts

@@ -1,21 +0,0 @@
-/** Device-local owner for usage snapshots and authentication health. */
-export declare const USAGE_STATE_TICK_MS = 60000;
-export declare const AUTH_STATE_TICK_MS: number;
-export interface AccountStateService {
-    stop(): void;
-}
-export interface AccountStateServiceDeps {
-    refreshUsage: () => Promise<void>;
-    refreshAuth: () => Promise<void>;
-    onError?: (area: 'usage' | 'auth', error: unknown) => void;
-    setInterval?: typeof globalThis.setInterval;
-    clearInterval?: typeof globalThis.clearInterval;
-}
-/**
- * Start the daemon-owned account-state loops.
- *
- * Each loop is overlap-safe within the daemon. Provider-level work is also
- * guarded by the cross-process refresh lease, so an explicit CLI refresh and
- * an older routine process converge on the same published result.
- */
-export declare function startAccountStateService(deps: AccountStateServiceDeps): AccountStateService;

package/dist/lib/account-state-service.js

@@ -1,60 +0,0 @@
-/** Device-local owner for usage snapshots and authentication health. */
-export const USAGE_STATE_TICK_MS = 60_000;
-export const AUTH_STATE_TICK_MS = 3 * 60_000;
-/**
- * Start the daemon-owned account-state loops.
- *
- * Each loop is overlap-safe within the daemon. Provider-level work is also
- * guarded by the cross-process refresh lease, so an explicit CLI refresh and
- * an older routine process converge on the same published result.
- */
-export function startAccountStateService(deps) {
-    const setTimer = deps.setInterval ?? globalThis.setInterval;
-    const clearTimer = deps.clearInterval ?? globalThis.clearInterval;
-    let usageRunning = false;
-    let authRunning = false;
-    let stopped = false;
-    const runUsage = async () => {
-        if (stopped || usageRunning)
-            return;
-        usageRunning = true;
-        try {
-            await deps.refreshUsage();
-        }
-        catch (error) {
-            deps.onError?.('usage', error);
-        }
-        finally {
-            usageRunning = false;
-        }
-    };
-    const runAuth = async () => {
-        if (stopped || authRunning)
-            return;
-        authRunning = true;
-        try {
-            await deps.refreshAuth();
-        }
-        catch (error) {
-            deps.onError?.('auth', error);
-        }
-        finally {
-            authRunning = false;
-        }
-    };
-    const usageTimer = setTimer(() => { void runUsage(); }, USAGE_STATE_TICK_MS);
-    const authTimer = setTimer(() => { void runAuth(); }, AUTH_STATE_TICK_MS);
-    usageTimer.unref?.();
-    authTimer.unref?.();
-    void runUsage();
-    void runAuth();
-    return {
-        stop() {
-            if (stopped)
-                return;
-            stopped = true;
-            clearTimer(usageTimer);
-            clearTimer(authTimer);
-        },
-    };
-}