@phnx-labs/agents-cli 1.22.54 → 1.22.55

package/dist/lib/session/db.js

@@ -435,7 +435,8 @@ CREATE INDEX IF NOT EXISTS idx_computer_sessions_started ON computer_sessions(st
  */
 /** Bump when facet extraction changes so cached rows recompute (shell-command-by-binary v7). */
 export const INSIGHTS_EXTRACTOR_VERSION = 7;
-export const SESSION_TOPIC_EXTRACTOR_VERSION = 1;
+/** Bump when classifyTopic's output changes so cached topics recompute (human task taxonomy v2). */
+export const SESSION_TOPIC_EXTRACTOR_VERSION = 2;
 const PREVIEW_EXTRACTOR_VERSION = 1;
 let dbInstance = null;
 /**

package/dist/lib/share/capture.js

@@ -36,8 +36,17 @@ export function candidateBrowsers() {
         if (p && fs.existsSync(p) && !out.includes(p))
             out.push(p);
     };
-    // 1) An explicit override always wins.
-    push(process.env.PUPPETEER_EXECUTABLE_PATH || process.env.AGENTS_SHARE_BROWSER);
+    // 1) Explicit overrides are contracts, not hints. A typo must fail at the
+    // boundary instead of silently falling through to an unrelated browser.
+    for (const name of ['PUPPETEER_EXECUTABLE_PATH', 'AGENTS_SHARE_BROWSER']) {
+        const value = process.env[name]?.trim();
+        if (!value)
+            continue;
+        if (!fs.existsSync(value)) {
+            throw new Error(`${name} points to a browser that does not exist: ${value}`);
+        }
+        push(value);
+    }
     // 2) Managed Chromium in the Playwright / Puppeteer caches — purpose-built for
     //    headless, so it's the most reliable capture host when present.
     for (const bin of scanCaches())

package/dist/lib/share/publish.d.ts

@@ -1,4 +1,5 @@
 import { type ShareConfig } from './config.js';
+import { type ShareBackendKind } from './backend.js';
 export type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
     ok: boolean;
     status: number;
@@ -9,6 +10,8 @@ export interface PublishEndpoint {
     token: string;
 }
 export interface PublishOptions {
+    /** Internal resolved backend; publishFile sets this after authentication. */
+    backendKind?: ShareBackendKind;
     slug?: string;
     /**
      * Auto-expire window. Relative (`30d`, `12h`), absolute (`2026-08-01`), or
@@ -133,7 +136,7 @@ export interface ShareProvenance {
  * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
  * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source"];
+export declare const RESERVED_META_KEYS: readonly ["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"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a

package/dist/lib/share/publish.js

@@ -52,6 +52,10 @@ export const RESERVED_META_KEYS = [
     'avatar',
     'label',
     'label-source',
+    'og-title',
+    'og-description',
+    'og-generated',
+    'og-source-etag',
 ];
 const META_KEY_RE = /^[a-z0-9-]{1,64}$/;
 /**
@@ -506,6 +510,7 @@ export async function publishFile(filePath, opts = {}) {
         ...opts,
         githubUser: username,
         analyticsToken,
+        backendKind: backend.kind,
     });
 }
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
@@ -536,6 +541,19 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // is only reached when --label is omitted.
     const label = explicitLabel ? sanitizeLabel(explicitLabel) : deriveLabel(filePath, body);
     const labelSource = explicitLabel ? 'explicit' : 'derived';
+    const ogMeta = isHtml ? deriveMeta(body.toString('utf8')) : undefined;
+    // The managed Worker owns deterministic OG generation. Point crawlers at the
+    // lazy sibling route without invoking a browser on the publishing machine.
+    if (isHtml && opts.cover !== false && opts.backendKind === 'managed' && ogMeta) {
+        coverUrl = `${pageUrl}.png`;
+        body = Buffer.from(injectOgMeta(body.toString('utf8'), {
+            ...ogMeta,
+            imageUrl: coverUrl,
+            pageUrl,
+            imageWidth: OG_WIDTH,
+            imageHeight: OG_HEIGHT,
+        }), 'utf8');
+    }
     // Pre-publish scan (RUSH-2443/RUSH-2683): refuse emails / credential-shaped
     // strings unless --force. Runs on the raw file body AND on every piece of
     // free-text metadata that lands in public customMetadata — --label (explicit
@@ -558,6 +576,10 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // Validate the FULL customMetadata payload before any network call — fail
     // fast, not mid-upload.
     const metadataPreview = { ...meta, label, 'label-source': labelSource };
+    if (ogMeta && opts.backendKind === 'managed') {
+        metadataPreview['og-title'] = ogMeta.title;
+        metadataPreview['og-description'] = ogMeta.description;
+    }
     if (provenance.agent)
         metadataPreview.agent = provenance.agent;
     if (provenance.session)
@@ -606,6 +628,10 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
             setText('x-share-avatar', avatarUrl);
         setText('x-share-label', label);
         h['x-share-label-source'] = labelSource;
+        if (ogMeta && opts.backendKind === 'managed') {
+            setText('x-share-og-title', ogMeta.title);
+            setText('x-share-og-description', ogMeta.description);
+        }
         // Per VALUE, before JSON.stringify — folding the serialized form would rewrite
         // a curly quote inside a value into a bare `"`, which is structural in JSON and
         // makes the Worker's JSON.parse throw. It swallows that error, so every --meta
@@ -633,7 +659,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     // Cover: screenshot the page's hero → upload <slug>.png → inject og:image meta.
     // Unlisted pages still get a cover (the direct URL is the capability), but the
     // cover inherits visibility=unlisted so it is also omitted from the gallery.
-    if (isHtml && opts.cover !== false) {
+    if (isHtml && opts.cover !== false && opts.backendKind !== 'managed') {
         const res = await attachOgCover(filePath, body, {
             pngUrl: `${pageUrl}.png`,
             pageUrl,

package/dist/lib/share/worker-template.d.ts

@@ -1,13 +1,4 @@
-/**
- * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
- *
- * The literal below still spells the CLI `agents share` in its provenance comment,
- * its root response, and its gallery title, even though the command is now
- * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
- * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
- * recorded `templateHash` against, so editing ANY byte here marks every already-
- * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
- * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
- * worth that; change this text only alongside a real Worker behavior change.
- */
+/** Bundle the Worker and its renderer into one uploadable ES module. */
 export declare function renderWorkerScript(): string;
+/** Unbundled Worker source. Kept separate so esbuild can resolve npm modules. */
+export declare function renderWorkerSource(): string;

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

@@ -1,3 +1,6 @@
+import { buildSync } from 'esbuild';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 // The Cloudflare Worker that fronts the R2 share bucket.
 //
 // One tiny Worker does both sides:
@@ -68,11 +71,48 @@
  * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
  * worth that; change this text only alongside a real Worker behavior change.
  */
+let bundledWorkerScript;
+/** Bundle the Worker and its renderer into one uploadable ES module. */
 export function renderWorkerScript() {
-    return `// GENERATED by agents-cli agents share setup — do not edit here; edit
+    if (bundledWorkerScript)
+        return bundledWorkerScript;
+    const result = buildSync({
+        stdin: {
+            contents: renderWorkerSource(),
+            loader: 'js',
+            resolveDir: dirname(fileURLToPath(import.meta.url)),
+            sourcefile: 'agents-share-worker.js',
+        },
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2022',
+        write: false,
+        minify: true,
+        loader: { '.wasm': 'binary', '.woff': 'binary' },
+    });
+    const output = result.outputFiles[0];
+    if (!output)
+        throw new Error('Worker bundling produced no JavaScript output.');
+    bundledWorkerScript = output.text;
+    return bundledWorkerScript;
+}
+/** Unbundled Worker source. Kept separate so esbuild can resolve npm modules. */
+export function renderWorkerSource() {
+    return `import satori, { init as initSatori } from 'satori/wasm';
+import initYoga from 'yoga-wasm-web';
+import { Resvg, initWasm as initResvg } from '@resvg/resvg-wasm';
+import yogaWasm from 'yoga-wasm-web/dist/yoga.wasm';
+import resvgWasm from '@resvg/resvg-wasm/index_bg.wasm';
+import interRegular from '@fontsource/inter/files/inter-latin-400-normal.woff';
+import interBold from '@fontsource/inter/files/inter-latin-700-normal.woff';
+import jetbrainsMono from '@fontsource/jetbrains-mono/files/jetbrains-mono-latin-600-normal.woff';
+
+// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.
 export const hooks = {
   verifyPhoenixToken: defaultVerifyPhoenixToken,
+  renderOgCard: renderOgCard,
 };
 
 export default {
@@ -91,6 +131,21 @@ export default {
       return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
     }
 
+    // POST /__ticket — mint a short-lived, single-navigation login ticket for the
+    // authenticated owner (PHNX-3370). The CLI (which holds the Phoenix bearer)
+    // calls this, then opens the owner's page with ?phoenix_ticket=<t> so the
+    // browser trades it for the __share cookie and the inline visibility control
+    // goes live. The ticket is SELF-signed with the Worker's own HMAC secret — no
+    // external ticket service — and carries the SAME identity authorizeWrite
+    // already proved, so it grants nothing the caller didn't already have.
+    if (request.method === 'POST' && firstSeg === '__ticket') {
+      const auth = await authorizeWrite(request, env);
+      if (auth.error) return auth.error;
+      const ticket = await signSelfTicket({ userId: auth.owner, email: auth.email || '' }, env);
+      if (!ticket) return json({ error: 'ticket minting is not configured' }, 501);
+      return json({ ticket: ticket }, 200);
+    }
+
     if (request.method === 'PUT') {
       const auth = await authorizeWrite(request, env);
       if (auth.error) return auth.error;
@@ -162,6 +217,8 @@ export default {
       const date = readText('date');
       const avatar = readText('avatar');
       const label = readText('label');
+      const ogTitle = readText('og-title');
+      const ogDescription = readText('og-description');
       const labelSource = request.headers.get('x-share-label-source') || '';
       let extraMeta = {};
       // The -u meta companion carries the whole raw object percent-encoded, so a
@@ -210,6 +267,8 @@ export default {
       if (avatar) customMetadata['avatar'] = avatar;
       if (label) customMetadata['label'] = label;
       if (labelSource) customMetadata['label-source'] = labelSource;
+      if (ogTitle) customMetadata['og-title'] = ogTitle;
+      if (ogDescription) customMetadata['og-description'] = ogDescription;
 
       // Revision retention (RUSH-2683): R2 has no native object versioning, so a
       // republish over an EXISTING key first copies the current object to
@@ -238,6 +297,10 @@ export default {
         httpMetadata: { contentType },
         customMetadata,
       });
+      // A managed republish may change the title/description. Invalidate only
+      // its generated sibling so the next crawler receives a fresh card; BYO
+      // publishes send no OG metadata and keep their explicitly uploaded cover.
+      if (ogTitle) await env.BUCKET.delete(path + '.png');
       return json({ ok: true, url: url.origin + '/' + path, expiresAt: expiresAt || null, unlisted: visibility === 'unlisted', visibility }, 200);
     }
 
@@ -263,6 +326,7 @@ export default {
       if (!edit || typeof edit !== 'object') return json({ error: 'PATCH body must be an object' }, 400);
       const metadata = { ...(existing.customMetadata || {}) };
       const previousVisibility = metadata.visibility || 'public';
+      let visibilityChanged = false;
       if (Object.prototype.hasOwnProperty.call(edit, 'label')) {
         if (edit.label !== null && typeof edit.label !== 'string') return json({ error: 'label must be a string or null' }, 400);
         if (typeof edit.label === 'string' && (edit.label.trim() !== edit.label || !edit.label || edit.label.length > 200)) return json({ error: 'label must be 1-200 trimmed characters' }, 400);
@@ -289,6 +353,7 @@ export default {
           }
         }
         metadata.visibility = visibility;
+        visibilityChanged = visibility !== previousVisibility;
         // org_domain is meaningful only for org — set it there, drop the stale
         // value on any move away from org so it can never gate a later read.
         if (visibility === 'org') metadata.org_domain = emailDomain(auth.email);
@@ -327,6 +392,16 @@ export default {
       if (existing.etag) putOpts.onlyIf = { etagMatches: existing.etag };
       const putResult = await env.BUCKET.put(path, existing.body, putOpts);
       if (putResult === null) return json({ error: 'conflict', key: path }, 409);
+      // A generated cover copies the canonical visibility gate into its own R2
+      // metadata. Invalidate it after a successful visibility rewrite so the
+      // next cover GET re-gates and renders from the canonical page. Explicitly
+      // uploaded BYO siblings carry no marker and remain independent assets.
+      if (visibilityChanged) {
+        const cover = await env.BUCKET.get(path + '.png');
+        if (cover && cover.customMetadata && cover.customMetadata['og-generated'] === 'true') {
+          await env.BUCKET.delete(path + '.png');
+        }
+      }
       return json({ ok: true, url: url.origin + '/' + path, label: metadata.label || null, meta: extraMetaOf(metadata), visibility: metadata.visibility || 'public', previousVisibility: previousVisibility }, 200);
     }
 
@@ -383,6 +458,70 @@ export default {
         );
       }
 
+      // Managed OG cover: generated siblings are caches, never visibility
+      // authorities. Gate every request against the current canonical page and
+      // bind each cached render to that page's etag. Re-read after rendering and
+      // after storing so a concurrent PATCH cannot publish a card from the old
+      // visibility/title/description snapshot. Explicit BYO siblings carry no
+      // generated marker and continue through the ordinary object route below.
+      if (segments.length === 2 && path.endsWith('.png')) {
+        let existingCover = await env.BUCKET.get(path);
+        if (!existingCover || (existingCover.customMetadata && existingCover.customMetadata['og-generated'] === 'true')) {
+          const pagePath = path.slice(0, -4);
+          const viewer = await resolveViewer(request, env, url);
+          if (viewer.redirect) return viewer.redirect;
+          for (let attempt = 0; attempt < 3; attempt += 1) {
+            const page = await env.BUCKET.get(pagePath);
+            if (!page) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+            const pageVisibility = (page.customMetadata && page.customMetadata.visibility) || 'public';
+            if (viewer.error && isIdentityGated(pageVisibility)) return viewer.error;
+            const denied = gateVisibility(url, env, page, viewer.identity || null);
+            if (denied) return denied;
+
+            if (existingCover && existingCover.customMetadata['og-source-etag'] === page.etag) {
+              const current = await env.BUCKET.get(pagePath);
+              if (!current || current.etag !== page.etag) { existingCover = null; continue; }
+              const currentDenied = gateVisibility(url, env, current, viewer.identity || null);
+              if (currentDenied) return currentDenied;
+              return new Response(request.method === 'HEAD' ? null : existingCover.body, {
+                status: 200,
+                headers: managedCoverHeaders(pageVisibility),
+              });
+            }
+
+            const pageHtml = await page.text();
+            const meta = page.customMetadata || {};
+            const png = await hooks.renderOgCard({
+              title: meta['og-title'] || extractHtmlMeta(pageHtml, 'title') || meta.label || segments[1],
+              description: meta['og-description'] || extractHtmlMeta(pageHtml, 'description') || '',
+              handle: segments[0],
+              visibility: pageVisibility,
+              orgDomain: meta.org_domain || '',
+            });
+            const beforeStore = await env.BUCKET.get(pagePath);
+            if (!beforeStore || beforeStore.etag !== page.etag) { existingCover = null; continue; }
+            await env.BUCKET.put(path, png, {
+              httpMetadata: { contentType: 'image/png' },
+              customMetadata: { ...meta, 'og-generated': 'true', 'og-source-etag': page.etag },
+            });
+            const beforeServe = await env.BUCKET.get(pagePath);
+            if (!beforeServe || beforeServe.etag !== page.etag) {
+              const justStored = await env.BUCKET.get(path);
+              if (justStored && justStored.customMetadata && justStored.customMetadata['og-source-etag'] === page.etag) {
+                await env.BUCKET.delete(path);
+              }
+              existingCover = null;
+              continue;
+            }
+            return new Response(request.method === 'HEAD' ? null : png, {
+              status: 200,
+              headers: managedCoverHeaders(pageVisibility),
+            });
+          }
+          return new Response('cover changed during rendering; retry', { status: 503, headers: { 'content-type': 'text/plain', 'retry-after': '1' } });
+        }
+      }
+
       const obj = await env.BUCKET.get(path);
       if (!obj) return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
       const expiresAt = obj.customMetadata && obj.customMetadata['expires-at'];
@@ -694,7 +833,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'];
+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 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;
@@ -1140,6 +1279,18 @@ function isIdentityGated(visibility) {
   return visibility === 'me' || visibility === 'org';
 }
 
+function managedCoverHeaders(visibility) {
+  const headers = new Headers({ 'content-type': 'image/png' });
+  if (isIdentityGated(visibility)) {
+    headers.set('cache-control', 'private, no-store');
+    headers.set('X-Robots-Tag', 'noindex');
+  } else {
+    headers.set('cache-control', 'public, max-age=31536000, immutable');
+    if (visibility === 'unlisted') headers.set('X-Robots-Tag', 'noindex');
+  }
+  return headers;
+}
+
 // Gate a me/org read given the ALREADY-RESOLVED viewer identity. Pure/sync: the
 // caller resolves the viewer once (it also needs the identity for the ownership
 // check) and both the page GET and the ?revisions=json path share this gate.
@@ -1257,6 +1408,66 @@ async function signShareCookie(identity, env) {
   return SHARE_COOKIE + '=' + value + '; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=' + SHARE_COOKIE_MAX_AGE;
 }
 
+// A short-lived login ticket, self-signed with the same HMAC secret as the cookie
+// but DOMAIN-SEPARATED (the signature covers a 'ticket:'-prefixed payload), so a
+// ticket value can never be replayed as a cookie value or vice versa. It rides in
+// the ?phoenix_ticket= param for exactly one navigation; resolveViewer verifies it
+// locally and exchanges it for the __share cookie. TTL is deliberately tiny — it
+// only has to survive the round-trip from CLI mint to the browser opening the URL.
+var SELF_TICKET_MAX_AGE = 120;
+
+async function signSelfTicket(identity, env) {
+  const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
+  if (!secret || !identity || !identity.userId) return '';
+  const exp = Math.floor(Date.now() / 1000) + SELF_TICKET_MAX_AGE;
+  const payload = identity.userId + '|' + (identity.email || '') + '|' + exp;
+  const sig = await hmacHex(secret, 'ticket:' + payload);
+  return toB64Url(payload) + '.' + sig;
+}
+
+async function verifySelfTicket(ticket, env) {
+  const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
+  if (!secret || !ticket) return null;
+  const dot = ticket.lastIndexOf('.');
+  if (dot < 1) return null;
+  let payload;
+  try {
+    payload = fromB64Url(ticket.slice(0, dot));
+  } catch {
+    return null;
+  }
+  const sig = ticket.slice(dot + 1);
+  const expected = await hmacHex(secret, 'ticket:' + payload);
+  if (!safeEqual(sig, expected)) return null;
+  const first = payload.indexOf('|');
+  const last = payload.lastIndexOf('|');
+  if (first < 0 || last <= first) return null;
+  const userId = payload.slice(0, first);
+  const email = payload.slice(first + 1, last);
+  const exp = Number(payload.slice(last + 1));
+  if (!userId || !Number.isFinite(exp) || Math.floor(Date.now() / 1000) > exp) return null;
+  return { userId: userId, email: email };
+}
+
+// Single-use enforcement for a self-signed ticket: claim its signature the first
+// time it is redeemed, and reject any later presentation of the same ticket. The
+// HMAC + short TTL stop forgery and bound the window, but without this a ticket the
+// CLI printed (--json / --no-open / a browser-open failure) could be replayed by
+// anyone who captured that output before it expired, minting the owner's 7-day
+// cookie a second time. Get-then-put mirrors claimHandle's one-time-claim pattern;
+// the marker rides a __-prefixed key (GET-blocked, excluded from every listing).
+async function consumeSelfTicket(env, sig) {
+  if (!sig) return false;
+  const key = '__ticket-used/' + sig;
+  const existing = await env.BUCKET.get(key);
+  if (existing) return false;
+  await env.BUCKET.put(key, '1', {
+    httpMetadata: { contentType: 'text/plain' },
+    customMetadata: { visibility: 'unlisted' },
+  });
+  return true;
+}
+
 async function identityFromCookie(request, env) {
   const secret = typeof env.WRITE_TOKEN === 'string' ? env.WRITE_TOKEN : '';
   if (!secret) return null;
@@ -1316,7 +1527,17 @@ async function resolveViewer(request, env, url) {
   if (cookieId) return { identity: cookieId };
   const ticket = url.searchParams.get('phoenix_ticket');
   if (!ticket) return {};
-  const redeemed = await redeemTicket(ticket, env);
+  // Prefer the locally-verifiable self-signed ticket (PHNX-3370, no network), and
+  // enforce single use by claiming its signature on first redemption — a captured
+  // ticket replayed within its TTL finds it already spent. Fall back to the
+  // external identity-server redeem for tickets it issued.
+  let redeemed = await verifySelfTicket(ticket, env);
+  if (redeemed) {
+    const sig = ticket.slice(ticket.lastIndexOf('.') + 1);
+    if (!(await consumeSelfTicket(env, sig))) redeemed = null;
+  } else {
+    redeemed = await redeemTicket(ticket, env);
+  }
   if (!redeemed) return { error: json({ error: 'invalid ticket' }, 401) };
   const cookie = await signShareCookie(redeemed, env);
   if (!cookie) return { error: json({ error: 'phoenix login is not configured' }, 401) };
@@ -1327,6 +1548,61 @@ async function resolveViewer(request, env, url) {
   return { redirect: new Response(null, { status: 302, headers: headers }) };
 }
 
+function extractHtmlMeta(html, field) {
+  const pattern = field === 'title'
+    ? /<title[^>]*>([\\s\\S]*?)<\\/title>/i
+    : /<meta[^>]+(?:name|property)=["'](?:description|og:description)["'][^>]+content=["']([^"']*)["'][^>]*>/i;
+  const match = pattern.exec(html);
+  return match ? match[1].replace(/<[^>]*>/g, '').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').trim() : '';
+}
+
+let rendererReady;
+async function renderOgCard(input) {
+  if (!rendererReady) {
+    rendererReady = Promise.all([
+      initYoga(yogaWasm).then(function (yoga) { initSatori(yoga); }),
+      initResvg(resvgWasm),
+    ]);
+  }
+  await rendererReady;
+  const visibilityLabels = {
+    public: 'PUBLIC',
+    unlisted: 'UNLISTED',
+    me: 'ONLY YOU',
+    org: input.orgDomain ? 'ANYONE AT ' + input.orgDomain.toUpperCase() : 'ORGANIZATION',
+  };
+  const node = {
+    type: 'div',
+    props: {
+      style: { width: '100%', height: '100%', display: 'flex', flexDirection: 'column', background: '#0a0a0a', color: '#f5f5f5', padding: '68px 76px 58px', fontFamily: 'Inter' },
+      children: [
+        { type: 'div', props: { style: { display: 'flex', color: '#a3e635', fontFamily: 'JetBrains Mono', fontSize: 25, fontWeight: 600, letterSpacing: '-0.5px' }, children: 'AGI · agents-cli.sh' } },
+        { type: 'div', props: { style: { display: 'flex', flexDirection: 'column', flexGrow: 1, justifyContent: 'center', maxWidth: 1050 }, children: [
+          { type: 'div', props: { style: { display: 'flex', fontSize: 66, lineHeight: 1.06, fontWeight: 700, letterSpacing: '-2.8px', maxHeight: 218, overflow: 'hidden' }, children: input.title || 'Shared artifact' } },
+          input.description ? { type: 'div', props: { style: { display: 'flex', marginTop: 24, color: '#a3a3a3', fontSize: 27, lineHeight: 1.35, maxHeight: 74, overflow: 'hidden' }, children: input.description } } : null,
+        ].filter(Boolean) } },
+        { type: 'div', props: { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', borderTop: '1px solid #262626', paddingTop: 25, fontSize: 21, color: '#a3a3a3' }, children: [
+          { type: 'div', props: { style: { display: 'flex' }, children: [
+            { type: 'span', props: { style: { color: '#737373' }, children: 'shared by ' } },
+            { type: 'span', props: { style: { marginLeft: 7, color: '#f5f5f5', fontWeight: 700 }, children: '@' + input.handle } },
+          ] } },
+          { type: 'div', props: { style: { display: 'flex', border: '1px solid #3f3f46', borderRadius: 999, padding: '9px 17px', color: '#d4d4d8', fontFamily: 'JetBrains Mono', fontSize: 16, letterSpacing: '1px' }, children: visibilityLabels[input.visibility] || 'PUBLIC' } },
+        ] } },
+      ],
+    },
+  };
+  const svg = await satori(node, {
+    width: 1200,
+    height: 630,
+    fonts: [
+      { name: 'Inter', data: interRegular, weight: 400, style: 'normal' },
+      { name: 'Inter', data: interBold, weight: 700, style: 'normal' },
+      { name: 'JetBrains Mono', data: jetbrainsMono, weight: 600, style: 'normal' },
+    ],
+  });
+  return new Resvg(svg, { fitTo: { mode: 'width', value: 1200 } }).render().asPng();
+}
+
 async function defaultVerifyPhoenixToken(request, env) {
   const presented = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
   if (!presented) return null;

package/dist/lib/view-types.d.ts

@@ -21,7 +21,12 @@ export interface ViewJsonVersion {
         amount: number;
         currency: string;
     } | null;
-    /** Human-readable usage refresh error, when the live refresh could not populate a snapshot. */
+    /**
+     * Human-readable reason a usage snapshot is absent: a live-refresh failure, or
+     * (without `--refresh`, on a never-cached account) a plain "not collected yet"
+     * pending state. Always a full sentence — never the internal `'stale'` cache
+     * sentinel, which `usageErrorForDisplay` normalizes away (PHNX-3348).
+     */
     usageError?: string | null;
     windows: Array<{
         key: 'session' | 'week' | 'sonnet_week' | 'month';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.54",
+  "version": "1.22.55",
   "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",
@@ -86,8 +86,11 @@
     "@homebridge/node-pty-prebuilt-multiarch"
   ],
   "dependencies": {
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@homebridge/node-pty-prebuilt-multiarch": "0.13.1",
     "@inquirer/prompts": "8.5.2",
+    "@resvg/resvg-wasm": "^2.6.2",
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
@@ -98,17 +101,20 @@
     "commander": "15.0.0",
     "croner": "10.0.1",
     "diff": "9.0.0",
+    "esbuild": "^0.28.2",
     "lru-cache": "11.5.2",
     "marked": "15.0.12",
     "marked-terminal": "7.3.0",
     "ora": "9.4.1",
     "proper-lockfile": "4.1.2",
+    "satori": "0.12.2",
     "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
     "unbash": "4.0.5",
     "ws": "^8.21.0",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "yoga-wasm-web": "^0.3.3"
   },
   "devDependencies": {
     "@types/diff": "8.0.0",