@phnx-labs/agents-cli 1.22.74 → 1.22.76

package/dist/lib/share/provision.js

@@ -219,7 +219,7 @@ export async function enableWorkersDev(apiToken, accountId, workerName, opts = {
 /** Resolve a zone id for a domain the token can see, or null if not owned/visible. */
 export async function findZoneId(apiToken, domain, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
-    // Try the exact name, then the registrable parent (share.agents-cli.sh -> agents-cli.sh).
+    // Try the exact name, then the registrable parent (share.getrush.ai -> getrush.ai).
     const candidates = [domain, domain.split('.').slice(-2).join('.')];
     for (const name of candidates) {
         const zones = await request({
@@ -232,7 +232,7 @@ export async function findZoneId(apiToken, domain, opts = {}) {
     }
     return null;
 }
-/** Map a custom hostname (e.g. `share.agents-cli.sh`) to the Worker via Workers Custom Domains. */
+/** Map a custom hostname (e.g. `share.getrush.ai`) to the Worker via Workers Custom Domains. */
 export async function addCustomDomain(apiToken, accountId, workerName, zoneId, hostname, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     try {

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

@@ -69,8 +69,17 @@ export interface PublishOptions {
     analytics?: boolean;
     /** Override the analytics token from share config. */
     analyticsToken?: string;
-    /** Override the GitHub username used for the URL namespace. */
+    /** Override the GitHub username used for the URL namespace (BYO path). */
     githubUser?: string;
+    /**
+     * Override the managed public handle (PHNX-3547). Managed publishes normally
+     * namespace under the email local-part; when that handle is taken — or a
+     * vanity namespace is wanted — pass an alternate. Sanitized to
+     * `[a-z0-9-]` (max 63 chars, matching the Worker); the Worker binds it with
+     * the same first-writer claim as a derived handle. Ignored on BYO (use
+     * `githubUser` there).
+     */
+    handle?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
     /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
@@ -209,12 +218,15 @@ export declare function resolveShareProvenance(opts?: {
 }): ShareProvenance;
 /**
  * The sharer's avatar URL, stamped so the share bar can show a real profile
- * picture instead of only the initials circle. We key a Gravatar on the SHA-256
- * of the signed-in user's lowercased email (Gravatar resolves either MD5 or
- * SHA-256), with `d=404` so Gravatar returns 404 for a user who has none — the
- * bar's `<img>` onerror then falls back to the initials circle. Only the hash
- * lands in public metadata, never the raw email. Returns '' when signed out
- * (BYO without a Phoenix session), leaving the bar on the initials circle.
+ * picture instead of only the initials circle. A hosted OAuth profile image
+ * already known to identity (PhoenixSession.avatarUrl — captured at login and
+ * refreshed from `/api/v1/auth/me`) wins outright; only when none exists do we
+ * fall back to a Gravatar keyed on the SHA-256 of the signed-in user's
+ * lowercased email (Gravatar resolves either MD5 or SHA-256), with `d=404` so
+ * Gravatar returns 404 for a user who has none — the bar's `<img>` onerror
+ * then falls back to the initials circle. Only the hash lands in public
+ * metadata, never the raw email. Returns '' when signed out (BYO without a
+ * Phoenix session), leaving the bar on the initials circle.
  *
  * `opts.session === null` means "explicitly signed out" (a test seam / BYO) and
  * yields ''; `undefined` reads the real persisted session.
@@ -369,4 +381,8 @@ export declare function resolveShareUsername(opts?: {
 /** Build the R2 object key from a namespace username and a slug part. */
 export declare function buildShareKey(username: string, slugPart: string): string;
 export declare function publishFile(filePath: string, opts?: PublishOptions): Promise<PublishResult>;
+/** Sanitize a caller-chosen managed handle to the Worker's namespace shape.
+ * Returns '' when the result is empty or over the Worker's 63-char cap (the
+ * caller then falls back to the derived handle / errors). */
+export declare function resolveManagedHandle(handle: string | undefined): string;
 export declare function publishToEndpoint(filePath: string, endpoint: PublishEndpoint, opts?: PublishOptions): Promise<PublishResult>;

package/dist/lib/share/publish.js

@@ -129,18 +129,24 @@ export function resolveShareProvenance(opts = {}) {
 }
 /**
  * The sharer's avatar URL, stamped so the share bar can show a real profile
- * picture instead of only the initials circle. We key a Gravatar on the SHA-256
- * of the signed-in user's lowercased email (Gravatar resolves either MD5 or
- * SHA-256), with `d=404` so Gravatar returns 404 for a user who has none — the
- * bar's `<img>` onerror then falls back to the initials circle. Only the hash
- * lands in public metadata, never the raw email. Returns '' when signed out
- * (BYO without a Phoenix session), leaving the bar on the initials circle.
+ * picture instead of only the initials circle. A hosted OAuth profile image
+ * already known to identity (PhoenixSession.avatarUrl — captured at login and
+ * refreshed from `/api/v1/auth/me`) wins outright; only when none exists do we
+ * fall back to a Gravatar keyed on the SHA-256 of the signed-in user's
+ * lowercased email (Gravatar resolves either MD5 or SHA-256), with `d=404` so
+ * Gravatar returns 404 for a user who has none — the bar's `<img>` onerror
+ * then falls back to the initials circle. Only the hash lands in public
+ * metadata, never the raw email. Returns '' when signed out (BYO without a
+ * Phoenix session), leaving the bar on the initials circle.
  *
  * `opts.session === null` means "explicitly signed out" (a test seam / BYO) and
  * yields ''; `undefined` reads the real persisted session.
  */
 export function resolveShareAvatar(opts = {}) {
     const session = opts.session !== undefined ? opts.session : readSession();
+    const hosted = session?.avatarUrl?.trim();
+    if (hosted && /^https:\/\//i.test(hosted))
+        return hosted;
     const email = session?.email?.trim().toLowerCase();
     if (!email)
         return '';
@@ -553,8 +559,9 @@ export function buildShareKey(username, slugPart) {
 }
 export async function publishFile(filePath, opts = {}) {
     const backend = resolveShareBackend(opts);
+    const managedHandle = backend.kind === 'managed' ? requireManagedHandle(opts.handle) : '';
     const username = backend.kind === 'managed'
-        ? backend.namespace
+        ? managedHandle || backend.namespace
         : await resolveShareUsername({ githubUser: opts.githubUser || backend.namespace || undefined });
     const analyticsToken = opts.analyticsToken ?? (backend.kind === 'byo' ? (opts.config ?? readShareConfig())?.analyticsToken : undefined);
     return publishToEndpoint(filePath, { baseUrl: backend.baseUrl, token: backend.token }, {
@@ -564,8 +571,28 @@ export async function publishFile(filePath, opts = {}) {
         backendKind: backend.kind,
     });
 }
+/** Sanitize a caller-chosen managed handle to the Worker's namespace shape.
+ * Returns '' when the result is empty or over the Worker's 63-char cap (the
+ * caller then falls back to the derived handle / errors). */
+export function resolveManagedHandle(handle) {
+    if (!handle)
+        return '';
+    const sanitized = sanitizeShareNamespace(handle);
+    return sanitized && sanitized.length <= 63 ? sanitized : '';
+}
+function requireManagedHandle(handle) {
+    const resolved = resolveManagedHandle(handle);
+    if (handle && !resolved) {
+        throw new Error(`Invalid --handle '${handle}': must sanitize to 1-63 [a-z0-9-] characters`);
+    }
+    return resolved;
+}
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
-    const username = await resolveShareUsername(opts);
+    // A managed publish may carry an explicit --handle: it namespaces the URL and
+    // rides the x-share-handle header so the Worker binds the claim to it (a
+    // derived handle is proven by the email; an alternate one must be declared).
+    const managedHandle = opts.backendKind === 'managed' ? requireManagedHandle(opts.handle) : '';
+    const username = managedHandle || (await resolveShareUsername(opts));
     let body = readFileSync(filePath);
     const expiresAt = resolveExpire(opts.expire);
     const visibility = resolveShareVisibility(opts);
@@ -666,6 +693,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     assertMetadataSize(metadataPreview);
     const authHeaders = (contentType) => {
         const h = { authorization: `Bearer ${endpoint.token}`, 'content-type': contentType };
+        if (managedHandle)
+            h['x-share-handle'] = managedHandle;
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         h['x-share-visibility'] = visibility;
@@ -748,11 +777,28 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
-        if (r.status === 409) {
-            throw new Error(`Handle '${username}' is already claimed by another account. The public URL namespace is the email local-part; two Phoenix users cannot share it.`);
+        // 409 has two distinct shapes on the managed Worker: 'handle taken' (the
+        // caller's namespace belongs to another account) and 'publish conflict'
+        // (a concurrent write won the republish race — retry, per PHNX-3547).
+        const httpError = extractShareHttpError({ status: r.status, body: r.body, retryAfter: r.retryAfter });
+        if (r.status === 409 && httpError.serverMessage === 'handle taken' && opts.backendKind === 'managed') {
+            throw new Error(`Handle '${username}' is already claimed by another account. ` +
+                'If you signed in again and got a new account id, republishing with the same email re-binds your handle automatically; ' +
+                'otherwise pick a different public namespace with --handle <name>.');
+        }
+        const detail = formatShareHttpErrorDetail(httpError);
+        // The write-token/setup advice is only meaningful for an auth failure — a
+        // 413 (quota/size) or 429 (rate) rejection has nothing to do with the
+        // token, and 'Check the write token' there is plain wrong (PHNX-3579).
+        // Managed endpoints carry a Phoenix bearer, so the recovery is re-login.
+        let advice = '';
+        if (r.status === 401 || r.status === 403) {
+            advice =
+                opts.backendKind === 'managed'
+                    ? ". Check that you're signed in — run 'agents auth login'."
+                    : ". Check the write token, or that 'agents artifacts setup' completed.";
         }
-        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: r.status, body: r.body, retryAfter: r.retryAfter }));
-        throw new Error(`Publish failed (${r.status}) for ${pageUrl}${detail}. Check the write token, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Publish failed (${r.status}) for ${pageUrl}${detail}${advice}`);
     }
     // 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>.

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',