@phnx-labs/agents-cli 1.22.75 → 1.22.76

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

@@ -151,11 +151,22 @@ export default {
       }
       const segments = path.split('/').filter(Boolean);
       if (auth.kind === 'phoenix') {
-        const expected = phoenixHandle(auth);
+        // The caller's handle is normally derived from the email local-part. An
+        // explicit x-share-handle (the CLI's --handle, PHNX-3547) lets a Phoenix
+        // user choose a DIFFERENT free handle — the escape hatch when their
+        // derived handle is taken or they want a vanity namespace. Sanitized to
+        // the same [a-z0-9-] shape; claim rules below bind it first-writer-writes,
+        // exactly like a derived handle.
+        const requestedRaw = request.headers.get('x-share-handle') || '';
+        const requested = sanitizeNamespace(requestedRaw);
+        if (requestedRaw && (!requested || requested.length > 63)) {
+          return json({ error: 'invalid handle', handle: requestedRaw }, 400);
+        }
+        const expected = requested || phoenixHandle(auth);
         if (!expected || segments[0] !== expected) {
           return json({ error: 'namespace mismatch', owner: expected }, 403);
         }
-        const claimed = await claimHandle(env.BUCKET, expected, auth.owner);
+        const claimed = await claimHandle(env.BUCKET, expected, auth.owner, auth.email || '');
         if (claimed.error) return claimed.error;
       }
       const expiresAt = request.headers.get('x-share-expires-at') || '';
@@ -268,11 +279,8 @@ export default {
       // publish rate limit, enforced ONLY for a managed Phoenix identity. A BYO
       // WRITE_TOKEN publish writes to the operator's OWN bucket at their own
       // cost, so it skips all four — a deliberate, documented policy, NOT a
-      // silent no-op. The current object is needed for BOTH the revision copy and
-      // the charge math, so read it once here; a BYO no-revision publish still
-      // skips the read entirely (nothing consumes it).
-      const needExisting = !noRevision || auth.kind === 'phoenix';
-      const existing = needExisting ? await env.BUCKET.get(path) : null;
+      // silent no-op.
+      //
       // Enforcement measures the REAL request body, never a client-declared size.
       // A spoofed-low content-length must NOT (a) slip an oversized body past the
       // per-file cap, (b) let real bytes exceed the total quota, or — most
@@ -281,8 +289,10 @@ export default {
       // Phoenix write we buffer the body bounded by the plan's per-file cap and
       // reject on the REAL size BEFORE any write; only then do we copy the
       // revision and store the buffered bytes. BYO streams unbuffered (uncapped,
-      // its own bucket).
+      // its own bucket) — which also means a BYO body cannot be re-read for a
+      // retry, so BYO gets a single conditional attempt below.
       let putBody = request.body;
+      let realBytes = 0;
       if (auth.kind === 'phoenix') {
         const limits = planLimits((await readUsage(env, auth.owner)).usage.plan);
         // Fast-reject an HONEST oversized content-length without reading the body.
@@ -290,47 +300,101 @@ export default {
         // read below, which measures the truth.
         const declaredLen = parseInt(request.headers.get('content-length') || '', 10);
         if (Number.isFinite(declaredLen) && declaredLen > limits.maxFileBytes) {
-          return json({ error: 'file too large', maxBytes: limits.maxFileBytes, gotBytes: declaredLen }, 413);
+          return json({ error: 'file too large: max ' + limits.maxFileBytes + ' bytes', maxBytes: limits.maxFileBytes, gotBytes: declaredLen }, 413);
         }
         // readBodyBounded aborts the moment it passes the cap, so a chunked/
         // streaming body can never buffer more than the cap (+ one chunk).
         const read = await readBodyBounded(request, limits.maxFileBytes);
         if (read.oversize) {
-          return json({ error: 'file too large', maxBytes: limits.maxFileBytes, gotBytes: read.size }, 413);
+          return json({ error: 'file too large: max ' + limits.maxFileBytes + ' bytes', maxBytes: limits.maxFileBytes, gotBytes: read.size }, 413);
         }
-        const realBytes = read.size;
-        const existingSize = existing && typeof existing.size === 'number' ? existing.size : 0;
-        const newCanonical = !existing;
-        // Keeping a revision retains the old canonical bytes AND adds the new
-        // ones, so storage grows by the full new size. A no-revision or first
-        // publish grows by new minus the bytes it replaces (may be negative on a
-        // shrink; the ledger clamps at >= 0).
-        const charge = (!noRevision && existing) ? realBytes : realBytes - existingSize;
-        const charged = await chargeShareWrite(env, auth, {
-          charge: charge,
-          newCanonical: newCanonical,
-          fileBytes: realBytes,
-          countRate: true,
-        });
-        if (charged.error) return charged.error; // rejected BEFORE any destructive write
+        realBytes = read.size;
         putBody = read.bytes;
       }
 
-      if (!noRevision && existing) {
-        const existingHeaders = new Headers();
-        if (typeof existing.writeHttpMetadata === 'function') existing.writeHttpMetadata(existingHeaders);
-        const existingContentType = existingHeaders.get('content-type');
-        const revKey = path + '/rev-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
-        await env.BUCKET.put(revKey, existing.body, {
-          httpMetadata: existingContentType ? { contentType: existingContentType } : undefined,
-          customMetadata: existing.customMetadata || {},
-        });
-      }
+      // Revision retention + quota charge + canonical write as a BOUNDED
+      // compare-and-swap loop (PHNX-3547). The old code read the current object,
+      // archived it, then overwrote the canonical key UNCONDITIONALLY: two
+      // concurrent republishers both archived the same old version and the
+      // loser's new body ended up neither canonical nor retained — silently
+      // discarded. R2 has no transactions, so each attempt re-reads the canonical
+      // object, archives it as a revision, and overwrites ONLY while the etag
+      // still matches the read (onlyIf.etagMatches — the same CAS primitive the
+      // PATCH path at :513 and the usage ledger already rely on; R2 returns null
+      // on the mismatch instead of storing). A conflicted attempt therefore loses
+      // nothing: it re-reads the winner's body, archives THAT as the revision on
+      // the next attempt, and lands its own body canonical — both writers survive.
+      // Phoenix bytes are buffered above, so retrying is safe; the rate counter
+      // and object count advance once (attempt 0) and a conflicted re-charge only
+      // bills the growth beyond what this request already paid. A BYO stream is
+      // consumed by the first attempt, so it gets one conditional try and a 409
+      // asking the caller to retry the whole publish.
+      const MAX_PUT_ATTEMPTS = 3;
+      let chargedAlready = 0;
+      let chargedNewCanonical = false;
+      let putResult = null;
+      for (let attempt = 0; attempt < MAX_PUT_ATTEMPTS; attempt++) {
+        // The current object is needed for BOTH the revision copy and the charge
+        // math, and even a first/no-revision publish must read before its
+        // conditional write so two concurrent creates cannot both report 200.
+        const existing = await env.BUCKET.get(path);
+        if (auth.kind === 'phoenix') {
+          const existingSize = existing && typeof existing.size === 'number' ? existing.size : 0;
+          const newCanonical = !existing;
+          // Keeping a revision retains the old canonical bytes AND adds the new
+          // ones, so storage grows by the full new size. A no-revision or first
+          // publish grows by new minus the bytes it replaces (may be negative on a
+          // shrink; the ledger clamps at >= 0).
+          const charge = (!noRevision && existing) ? realBytes : realBytes - existingSize;
+          // Conflict retry: only the growth beyond what this request already
+          // paid. Exact accounting under a lost race is impossible without
+          // reconciling the bucket; this stays the ledger's documented
+          // best-effort, same as its >= 0 clamp.
+          const bill = Math.max(0, charge - chargedAlready);
+          chargedAlready += bill;
+          const chargeNewCanonical = newCanonical && attempt === 0;
+          const charged = await chargeShareWrite(env, auth, {
+            charge: bill,
+            newCanonical: chargeNewCanonical,
+            fileBytes: realBytes,
+            countRate: attempt === 0,
+          });
+          if (charged.error) return charged.error; // rejected BEFORE any destructive write
+          if (chargeNewCanonical) chargedNewCanonical = true;
+        }
 
-      await env.BUCKET.put(path, putBody, {
-        httpMetadata: { contentType },
-        customMetadata,
-      });
+        if (!noRevision && existing) {
+          const existingHeaders = new Headers();
+          if (typeof existing.writeHttpMetadata === 'function') existing.writeHttpMetadata(existingHeaders);
+          const existingContentType = existingHeaders.get('content-type');
+          const revKey = path + '/rev-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+          await env.BUCKET.put(revKey, existing.body, {
+            httpMetadata: existingContentType ? { contentType: existingContentType } : undefined,
+            customMetadata: existing.customMetadata || {},
+          });
+        }
+
+        const putOpts = { httpMetadata: { contentType }, customMetadata };
+        // Existing objects use the bare R2Object#etag for CAS; missing objects
+        // use R2's create-only condition so a concurrent first writer wins loud.
+        if (existing && existing.etag) putOpts.onlyIf = { etagMatches: existing.etag };
+        else putOpts.onlyIf = { etagDoesNotMatch: '*' };
+        putResult = await env.BUCKET.put(path, putBody, putOpts);
+        if (putResult !== null) break;
+        // A failed create-only condition means another first publisher won.
+        // Do not turn that loser into a republish: the caller must see the race.
+        if (!existing) break;
+        if (auth.kind !== 'phoenix') break; // BYO stream is spent — cannot retry
+      }
+      if (putResult === null) {
+        if (auth.kind === 'phoenix') {
+          await refundShareWrite(env, auth.owner, {
+            refund: chargedAlready,
+            freeCanonical: chargedNewCanonical,
+          });
+        }
+        return json({ error: 'publish conflict: another write landed first, retry the publish' }, 409);
+      }
       // 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.
@@ -345,15 +409,36 @@ export default {
       if (segments.length < 2) return json({ error: 'metadata edit requires /<username>/<slug>' }, 400);
       if (auth.kind === 'phoenix') {
         const expected = phoenixHandle(auth);
-        if (!expected || segments[0] !== expected) return json({ error: 'namespace mismatch', owner: expected }, 403);
+        const handle = segments[0];
+        if (!expected || handle !== expected) {
+          // An alternate handle must already have a claim; unlike PUT, PATCH
+          // cannot create a new namespace as a side effect.
+          const claim = handle ? await env.BUCKET.get('__handles/' + handle) : null;
+          if (!claim) return json({ error: 'namespace mismatch', owner: expected }, 403);
+        }
+        // Use the same ownership path as PUT/DELETE so the same verified email
+        // under a new userId transfers the claim and re-stamps old pages before
+        // the per-object ownership check below.
+        const owned = await assertHandleOwner(env.BUCKET, handle, auth.owner, auth.email || '');
+        if (owned.error) return json({ error: 'forbidden' }, 403);
       }
       const existing = await env.BUCKET.get(path);
       if (!existing) return json({ error: 'share not found', key: path }, 404);
-      const owner = existing.customMetadata && existing.customMetadata.owner;
-      // WRITE_TOKEN is the endpoint owner/admin credential (the same authority
-      // the DELETE path grants it). Phoenix must prove ownership — fail closed
-      // when the object has no owner stamp (handles collide after sanitization).
-      if (auth.kind === 'phoenix' && (!owner || owner !== auth.owner)) return json({ error: 'forbidden' }, 403);
+      // Ownership was settled above, the same way DELETE settles it: WRITE_TOKEN
+      // is the endpoint owner/admin credential, and a Phoenix caller has proven
+      // the handle claim (or, pre-claim, that no rival userId owns the prefix).
+      // There is deliberately NO per-object owner comparison here. Pages in a
+      // claimed namespace can carry a stamp that is not the claim holder's
+      // userId — a BYO WRITE_TOKEN publish stamps owner = the namespace, a page
+      // from the same human's earlier userId that transferHandle never saw, or
+      // a page with no stamp at all — and the claim holder could DELETE every
+      // one of them yet was refused a visibility change (403 'forbidden'), which
+      // left confidential pages public with takedown as the only remedy. The
+      // claim is the authority. The stamp itself is deliberately NOT rewritten:
+      // the anonymous lazy-expiry path refunds the STAMPED owner's usage ledger
+      // (see the GET expiry branch + refundShareWrite), and a fleet/BYO page was
+      // never charged to a Phoenix ledger — re-stamping it to the caller would
+      // credit her quota with bytes and a slot she never paid for on expiry.
 
       let edit;
       try { edit = await request.json(); } catch { return json({ error: 'PATCH body must be JSON' }, 400); }
@@ -486,7 +571,7 @@ export default {
           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);
+          const denied = await gateVisibility(url, env, canonical, viewer.identity || null);
           if (denied) return denied;
         }
         // A private canonical gates its revision list on the viewer key too
@@ -524,7 +609,7 @@ export default {
             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);
+            const denied = await 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.
@@ -534,7 +619,7 @@ export default {
             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);
+              const currentDenied = await gateVisibility(url, env, current, viewer.identity || null);
               if (currentDenied) return currentDenied;
               return new Response(request.method === 'HEAD' ? null : existingCover.body, {
                 status: 200,
@@ -619,7 +704,7 @@ export default {
       if (viewer.redirect) return viewer.redirect;
       if (viewer.error && isIdentityGated(visibility)) return viewer.error;
       const identity = viewer.identity || null;
-      const denied = gateVisibility(url, env, obj, identity);
+      const denied = await 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.
@@ -718,7 +803,16 @@ export default {
         if (delSegments[0] && delSegments[0] === uid) {
           // own leftover UUID prefix
         } else if (delSegments[0] && delSegments[0] === handle) {
-          const owned = await assertHandleOwner(env.BUCKET, handle, auth.owner);
+          const owned = await assertHandleOwner(env.BUCKET, handle, auth.owner, auth.email || '');
+          if (owned.error) return owned.error;
+        } else if (delSegments[0]) {
+          // An explicitly-chosen handle (the CLI's --handle, PHNX-3547): the
+          // caller's derived handle differs from the namespace, so the claim is
+          // the authority — assertHandleOwner refuses strangers (409) and
+          // recovers a same-email account move. No claim at all is a mismatch.
+          const claim = await env.BUCKET.get('__handles/' + delSegments[0]);
+          if (!claim) return json({ error: 'namespace mismatch', owner: handle || uid }, 403);
+          const owned = await assertHandleOwner(env.BUCKET, delSegments[0], auth.owner, auth.email || '');
           if (owned.error) return owned.error;
         } else {
           return json({ error: 'namespace mismatch', owner: handle || uid }, 403);
@@ -1335,8 +1429,13 @@ function phoenixHandle(auth) {
 }
 
 // First writer of a handle owns it. Later PUTs from the same userId are fine;
-// a different userId whose email local-part collides gets 409, not a silent overwrite.
-async function assertHandleOwner(bucket, handle, userId) {
+// a different userId whose email local-part collides gets 409, not a silent
+// overwrite — EXCEPT when the verified Phoenix email matches the claim's
+// recorded email exactly: that is the same human re-authenticated under a new
+// userId (an account move), and the claim transfers to them instead of
+// dead-ending (PHNX-3547). The transfer also re-stamps owner on the old
+// account's objects so PATCH/DELETE keep working.
+async function assertHandleOwner(bucket, handle, userId, email) {
   // The __handles/<handle> claim object is the authoritative first-writer record
   // of ownership. When it exists it decides ownership OUTRIGHT: the recorded
   // userId may write, anyone else is refused. Consult it FIRST — a stray page
@@ -1347,8 +1446,17 @@ async function assertHandleOwner(bucket, handle, userId) {
   const key = '__handles/' + handle;
   const existing = await bucket.get(key);
   if (existing) {
-    const claimed = existing.customMetadata && existing.customMetadata.userId;
+    const meta = existing.customMetadata || {};
+    const claimed = meta.userId;
     if (claimed && claimed !== userId) {
+      // Same verified email, different userId → account move, not a rival:
+      // rebind the claim and migrate the old owner's objects. Legacy claims
+      // written before the claim recorded an email cannot prove this and keep
+      // the permanent 409.
+      if (email && meta.email && String(meta.email).toLowerCase() === String(email).toLowerCase()) {
+        await transferHandle(bucket, handle, claimed, userId, email);
+        return {};
+      }
       return { error: json({ error: 'handle taken', handle: handle }, 409) };
     }
     return {};
@@ -1369,15 +1477,48 @@ async function assertHandleOwner(bucket, handle, userId) {
   return {};
 }
 
-async function claimHandle(bucket, handle, userId) {
-  const owned = await assertHandleOwner(bucket, handle, userId);
+// Account-move recovery (PHNX-3547): the claim's recorded userId held the handle;
+// the caller proves the SAME verified email under a NEW userId. Rebind the claim
+// and re-stamp owner on every object the old userId owned under this prefix, so
+// the moved account keeps full control of its shares. Objects owned by anyone
+// else (BYO namespace stamps, a pre-claim stray) are left untouched.
+async function transferHandle(bucket, handle, oldUserId, newUserId, email) {
+  await bucket.put('__handles/' + handle, JSON.stringify({ userId: newUserId, email: email }), {
+    httpMetadata: { contentType: 'application/json' },
+    customMetadata: { userId: newUserId, email: email, visibility: 'unlisted' },
+  });
+  let cursor;
+  do {
+    const list = await bucket.list({ prefix: handle + '/', cursor: cursor, include: ['customMetadata'] });
+    for (const o of list.objects || []) {
+      const owner = o.customMetadata && o.customMetadata.owner;
+      if (!owner || owner !== oldUserId) continue;
+      const obj = await bucket.get(o.key);
+      if (!obj) continue;
+      const headers = new Headers();
+      if (typeof obj.writeHttpMetadata === 'function') obj.writeHttpMetadata(headers);
+      const customMetadata = { ...(obj.customMetadata || {}), owner: newUserId };
+      await bucket.put(o.key, obj.body, {
+        httpMetadata: headers.get('content-type') ? { contentType: headers.get('content-type') } : undefined,
+        customMetadata: customMetadata,
+      });
+    }
+    cursor = list.truncated ? list.cursor : undefined;
+  } while (cursor);
+}
+
+async function claimHandle(bucket, handle, userId, email) {
+  const owned = await assertHandleOwner(bucket, handle, userId, email);
   if (owned.error) return owned;
   const key = '__handles/' + handle;
   // Write (or rewrite) so a same-user republish resets object Age against the
-  // bucket's 366-day lifecycle — otherwise the claim can expire while pages stay live.
-  await bucket.put(key, JSON.stringify({ userId: userId }), {
+  // bucket's 366-day lifecycle — otherwise the claim can expire while pages stay
+  // live. The claim also records the verified email: it is what lets a future
+  // same-email/different-userId request prove an account move and recover the
+  // handle instead of hitting the permanent 409.
+  await bucket.put(key, JSON.stringify({ userId: userId, email: email }), {
     httpMetadata: { contentType: 'application/json' },
-    customMetadata: { userId: userId, visibility: 'unlisted' },
+    customMetadata: { userId: userId, email: email || '', visibility: 'unlisted' },
   });
   return {};
 }
@@ -1423,16 +1564,36 @@ function managedCoverHeaders(visibility) {
 // 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.
-function gateVisibility(url, env, obj, identity) {
+async function gateVisibility(url, env, obj, identity) {
   const visibility = (obj.customMetadata && obj.customMetadata.visibility) || 'public';
   if (!isIdentityGated(visibility)) return null;
   if (!identity) return bounceToLogin(url, env);
   if (!viewerMayRead(visibility, obj.customMetadata, identity)) {
+    // A 'me' page reads for its stamped owner (the fast path above) OR for the
+    // holder of the namespace's handle claim — the same authority PATCH and
+    // DELETE use. Without this, the claim holder who takes a fleet/BYO-stamped
+    // or pre-stamp page to 'me' (owner = namespace, or none) would be locked
+    // out of her own page: PATCH says 200, GET says 404. The stamp itself stays
+    // untouched (expiry refunds credit the stamped ledger), so the read gate
+    // has to consult the claim rather than the stamp.
+    const handle = decodeURIComponent(url.pathname).split('/').filter(Boolean)[0] || '';
+    if (visibility === 'me' && handle && (await holdsHandleClaim(env.BUCKET, handle, identity.userId))) return null;
     return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
   }
   return null;
 }
 
+// True when userId is the recorded holder of the __handles/<handle> claim.
+// Read-only: never transfers or writes a claim (that is claimHandle /
+// assertHandleOwner's job on the write paths).
+async function holdsHandleClaim(bucket, handle, userId) {
+  if (!handle || !userId) return false;
+  const claim = await bucket.get('__handles/' + handle);
+  if (!claim) return false;
+  const claimed = claim.customMetadata && claim.customMetadata.userId;
+  return !!claimed && claimed === userId;
+}
+
 // 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).
@@ -1909,7 +2070,7 @@ async function renderOgCard(input) {
     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', color: '#a3e635', fontFamily: 'JetBrains Mono', fontSize: 25, fontWeight: 600, letterSpacing: '-0.5px' }, children: 'share.getrush.ai' } },
         { 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,

package/dist/lib/startup/command-registry.js

@@ -2,9 +2,9 @@ const LOADED_COMMAND_NAMES = [
     'accounts', 'auth', 'view', 'inspect', 'feedback', 'commands', 'hooks', 'skills', 'rules', 'memory',
     'permissions', 'mcp', 'clis', 'subagents', 'plugins', 'workflows', 'add', 'use',
     'remove', 'rm', 'purge', 'update', 'prune', 'import', 'registry', 'search', 'install', 'packages',
-    'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
+    'routines', 'monitors', 'projects', 'run', '_callback', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
-    'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
+    'route', 'routes', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
     'refresh-rules', 'factory', 'insights', 'trace', 'reminders',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',

package/dist/lib/state.d.ts

@@ -319,6 +319,21 @@ export declare function getRuntimeStateDir(): string;
 export declare function getCompanionDir(): string;
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export declare function getBrowserRuntimeDir(): string;
+/**
+ * Path to DURABLE browser-profile data (~/.agents/.history/browser-profiles/).
+ *
+ * This is the persistent home for an attach-only profile's `--user-data-dir` —
+ * where a one-time browser sign-in lives. It sits under `.history` (durable),
+ * NOT `.cache` (regenerable), for two reasons the ticket (PHNX-3967) named:
+ *  - `agents browser profiles remove` sweeps `~/.agents/.cache/browser/<name>*`;
+ *    a durable dir here survives that so logins are not wiped by a routine cleanup.
+ *  - A cache wipe or the daemon reaper never touches it, so a signed-in Comet
+ *    survives quit+relaunch.
+ * The user's canonical Comet is launched with this as `--user-data-dir`, and the
+ * ownership guard in the local driver compares the running instance's
+ * `--user-data-dir` against it to reject a foreign port-squatter.
+ */
+export declare function getBrowserDurableDir(): string;
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export declare function getHelpersDir(): string;
 /**

package/dist/lib/state.js

@@ -642,6 +642,21 @@ export function getRuntimeStateDir() { return process.env.AGENTS_STATE_DIR ?? RU
 export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 /** Path to browser runtime data — chrome-data, pids (~/.agents/.cache/browser/). */
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
+/**
+ * Path to DURABLE browser-profile data (~/.agents/.history/browser-profiles/).
+ *
+ * This is the persistent home for an attach-only profile's `--user-data-dir` —
+ * where a one-time browser sign-in lives. It sits under `.history` (durable),
+ * NOT `.cache` (regenerable), for two reasons the ticket (PHNX-3967) named:
+ *  - `agents browser profiles remove` sweeps `~/.agents/.cache/browser/<name>*`;
+ *    a durable dir here survives that so logins are not wiped by a routine cleanup.
+ *  - A cache wipe or the daemon reaper never touches it, so a signed-in Comet
+ *    survives quit+relaunch.
+ * The user's canonical Comet is launched with this as `--user-data-dir`, and the
+ * ownership guard in the local driver compares the running instance's
+ * `--user-data-dir` against it to reject a foreign port-squatter.
+ */
+export function getBrowserDurableDir() { return path.join(HISTORY_DIR, 'browser-profiles'); }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export function getHelpersDir() { return HELPERS_DIR; }
 /**
@@ -1136,6 +1151,13 @@ function serializeCentral(central) {
  * read-snapshot-then-separately-lock race that {@link updateMeta} would impose.
  */
 export function writeMetaUnlocked(meta) {
+    const writesDeviceRoutines = Object.prototype.hasOwnProperty.call(meta, 'deviceRoutines');
+    const writesDeviceConfig = Object.prototype.hasOwnProperty.call(meta, 'deviceConfig');
+    const writesDeviceBrowser = Object.prototype.hasOwnProperty.call(meta, 'deviceBrowser');
+    const writesDeviceFleet = Object.prototype.hasOwnProperty.call(meta, 'deviceFleet');
+    const writesDeviceHosts = Object.prototype.hasOwnProperty.call(meta, 'deviceHosts');
+    const writesDeviceAccounts = Object.prototype.hasOwnProperty.call(meta, 'deviceAccounts');
+    const writesProjectRoot = Object.prototype.hasOwnProperty.call(meta, 'projectRoot');
     // INVARIANT: every key destructured here must also be in BESPOKE_DEVICE_KEYS (and
     // vice versa) — a bespoke device key that is classified but NOT pulled out here
     // would fall into `central`, and the generic router skips it (BESPOKE_DEVICE_KEY_SET),
@@ -1191,17 +1213,17 @@ export function writeMetaUnlocked(meta) {
     delete doc.isolatedAgents;
     if (Array.isArray(deviceRoutines))
         doc.routines = deviceRoutines;
-    else
+    else if (writesDeviceRoutines)
         delete doc.routines;
     const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
     if (hasDeviceConfig)
         doc.config = deviceConfig;
-    else
+    else if (writesDeviceConfig)
         delete doc.config;
     const hasDeviceBrowser = !!deviceBrowser && Object.keys(deviceBrowser).length > 0;
     if (hasDeviceBrowser)
         doc.browser = deviceBrowser;
-    else
+    else if (writesDeviceBrowser)
         delete doc.browser;
     // PHNX-3315 device-scoped fleet/hosts/accounts blocks. Each is this box's OWN
     // slice; the effective fleet view is unioned across every device doc at read
@@ -1219,12 +1241,12 @@ export function writeMetaUnlocked(meta) {
             df.ignored = fleetIgnored;
         doc.fleet = df;
     }
-    else
+    else if (writesDeviceFleet)
         delete doc.fleet;
     const hasDeviceHosts = !!deviceHosts && Object.keys(deviceHosts).length > 0;
     if (hasDeviceHosts)
         doc.hosts = deviceHosts;
-    else
+    else if (writesDeviceHosts)
         delete doc.hosts;
     const accountsNative = deviceAccounts?.native && Object.keys(deviceAccounts.native).length > 0
         ? deviceAccounts.native : undefined;
@@ -1238,12 +1260,12 @@ export function writeMetaUnlocked(meta) {
             da.bindings = accountsBindings;
         doc.accounts = da;
     }
-    else
+    else if (writesDeviceAccounts)
         delete doc.accounts;
     const hasProjectRoot = typeof projectRoot === 'string' && projectRoot.length > 0;
     if (hasProjectRoot)
         doc.projectRoot = projectRoot;
-    else
+    else if (writesProjectRoot)
         delete doc.projectRoot;
     // Generic device-scoped keys (PHNX-3315): any key left in `central` that this
     // version classifies as device but does NOT bespoke-route round-trips through

package/dist/lib/summarizer/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Session-summarizer configuration (PHNX-3939).
+ *
+ * Resolves the three knobs behind the daemon summarizer — enabled / base URL /
+ * model — from `agents config` (`summarizer.*`, user-scope in the central
+ * agents.yaml) with a per-process env override
+ * (`AGENTS_SUMMARIZER_ENABLED` / `AGENTS_SUMMARIZER_BASEURL` /
+ * `AGENTS_SUMMARIZER_MODEL`). Off by default: with no config and no env, the
+ * summarizer is disabled and makes zero model calls.
+ *
+ * `isSummarizerReady()` is memoized on a short TTL because the display merge
+ * (the watch-stream projections) calls it once per session row — a fresh
+ * agents.yaml read per row would defeat the "blazing fast" requirement.
+ */
+export interface SummarizerConfig {
+    enabled: boolean;
+    /** Anthropic-wire base URL (Ollama/vLLM/LiteLLM), or undefined when unconfigured. */
+    baseUrl?: string;
+    /** Model id to request, or undefined when unconfigured. */
+    model?: string;
+}
+/**
+ * Resolve the full summarizer config. Env overrides the stored config key by key;
+ * an unset env var falls through to `agents config`, then to the built-in
+ * default (disabled). Never throws — a missing/corrupt config reads as unset.
+ */
+export declare function resolveSummarizerConfig(env?: NodeJS.ProcessEnv): SummarizerConfig;
+/**
+ * True only when the summarizer is enabled AND has a base URL + model to call.
+ * A configuration that is `enabled` but missing an endpoint cannot produce a
+ * summary, so it is treated as unconfigured (the service no-ops, the merge marks
+ * `skipped`) rather than erroring on every tick.
+ */
+export declare function isSummarizerRunnable(config: SummarizerConfig): boolean;
+/**
+ * Memoized "will a summary actually be produced?" check for the hot merge path.
+ * Reflects {@link isSummarizerRunnable} — enabled AND a base URL AND a model —
+ * NOT just `enabled`, because an enabled-but-unconfigured summarizer computes
+ * nothing, so a row with no cached summary must read `skipped`, not a `pending`
+ * that never resolves (the exact case: `summarizer.enabled on` set before the
+ * endpoint). TTL keeps a config change visible within a few seconds without a
+ * per-row agents.yaml read.
+ */
+export declare function isSummarizerReady(nowMs?: number): boolean;
+/** Test seam: drop the memoized ready flag so the next read re-resolves. */
+export declare function resetSummarizerReadyCacheForTest(): void;