@phnx-labs/agents-cli 1.22.68 → 1.22.69

package/dist/lib/session/prompt.js

@@ -49,6 +49,7 @@ const SYNTHETIC_USER_MESSAGE_PATTERNS = [
     /^\s*<(?:apps|plugins|skills)_instructions>/i,
     /^\s*<recommended_plugins>/i,
     /^\s*<(?:multi_agent_mode|environment_context)>/i,
+    /^\s*<user_info>/i,
     /^\s*## (?:In-flight in this repo|Host & Fleet)/i,
     /^\s*Your current session id is\b/i,
     /^\s*Linear context skipped:/i,
@@ -69,17 +70,26 @@ export function isSyntheticUserMessage(raw) {
         return false;
     return SYNTHETIC_USER_MESSAGE_PATTERNS.some(pattern => pattern.test(raw));
 }
+/**
+ * Inner text of a `<user_query>` wrapper, or the original string if none.
+ * Same extraction Cursor already applies in `parseCursorUserText`.
+ */
+export function unwrapUserQuery(text) {
+    const query = text.match(/<user_query>\s*([\s\S]*?)\s*<\/user_query>/);
+    return (query?.[1] ?? text).trim();
+}
 /**
  * Return one genuine user turn in full.
  * Synthetic scaffolding is rejected as a whole so an injected Apps/AGENTS
  * preamble can never become the session's displayed request. Unlike the topic
  * cleaner, this intentionally preserves internal whitespace and every line of
- * the user's actual request.
+ * the user's actual request. A Grok/Cursor `<user_query>` wrapper is unwrapped
+ * so the stored turn is the originating request, not the harness tags.
  */
 export function cleanFirstUserMessage(raw) {
     if (!raw || isSyntheticUserMessage(raw))
         return undefined;
-    const clean = raw.trim();
+    const clean = unwrapUserQuery(raw);
     return clean || undefined;
 }
 /** First genuine user message from an already-normalized event stream. */

package/dist/lib/session/recovery.d.ts

@@ -4,15 +4,18 @@ import type { SessionAgentId, SessionMeta } from './types.js';
 /** One capability boundary for every surface that advertises faithful Resume. */
 export declare function sessionAgentSupportsResume(agent: SessionAgentId): boolean;
 /**
- * The account a recovery should authenticate as. Present only when resume
- * rotates AWAY from the session's original login (an account limit) to a
- * healthy sibling of the SAME harness. A `providerAccount` is a durable
- * setup-token / API-key account (RUSH-3182) injected via the `--account` spawn
- * path (`resolveSpawnAccount` → `accountEnv`); it is the only kind that can
+ * The account a recovery should authenticate as. Present when resume rotates
+ * AWAY from the session's original login (an account limit) to a healthy
+ * sibling of the SAME harness. A `providerAccount` is a durable setup-token /
+ * API-key account (RUSH-3182) injected via the `--account` spawn path
+ * (`resolveSpawnAccount` → `accountEnv`); it is the only kind that can
  * authenticate a NATIVE resume in the origin version home, because a native
- * login lives in its own isolated home and cannot be forwarded. Absent means
- * "use the launched version home's own native login" — the healthy-origin happy
- * path and every /continue fallback.
+ * login lives in its own isolated home and cannot be forwarded. It is also
+ * required on `/continue` when the balanced pick is a provider: exec only
+ * injects from this field, so omitting it would launch the version home's
+ * native login — the exhausted origin in the PHNX-3674 fixture. Absent means
+ * "use the launched version home's own native login" (the healthy-origin happy
+ * path, or `/continue` on a healthy native sibling).
  */
 export interface RecoveryAccount {
     providerAccount: string;
@@ -30,6 +33,7 @@ export type SessionRecoveryTarget = {
     mode: 'continue';
     agent: AgentId;
     version: string;
+    account?: RecoveryAccount;
     reason: string;
 };
 export type NativeResumeInspection = {
@@ -59,10 +63,15 @@ export declare function inspectNativeResumeSession(session: SessionMeta, version
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
- * Native resume is legal only in the exact origin version's isolated home and
- * only while that account is healthy. Every other successful path stays on the
- * same harness and uses `/continue`, whose indexed transcript reader can reach
- * retained version trash. No healthy same-harness account is a loud failure.
+ * Native resume is legal only in the exact origin version's isolated home,
+ * and only while that home owns the indexed transcript AND some injectable
+ * credential for this harness is healthy: the origin login itself, or a
+ * provider account rotated in when the origin is usage-limited (PHNX-3626).
+ * Every other successful path stays on the same harness and uses `/continue`,
+ * whose indexed transcript reader can reach retained version trash. A
+ * `/continue` pick of a provider account carries RecoveryAccount so exec
+ * injects it instead of launching the version home's native login
+ * (PHNX-3674). No healthy same-harness account is a loud failure.
  */
 export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean, nativeInspection?: NativeResumeInspection): SessionRecoveryTarget;
 /**

package/dist/lib/session/recovery.js

@@ -50,6 +50,16 @@ function sourceReason(session, candidates) {
         ? `origin ${session.agent}@${session.version} has no native resume form`
         : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
 }
+function recoveryAccountFromCandidate(candidate) {
+    const providerAccount = candidate.providerAccount;
+    if (!providerAccount)
+        return undefined;
+    return {
+        providerAccount,
+        label: candidate.accountLabel || providerAccount,
+        email: candidate.email,
+    };
+}
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
     return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
@@ -146,10 +156,15 @@ export function inspectNativeResumeSession(session, versionHome) {
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
- * Native resume is legal only in the exact origin version's isolated home and
- * only while that account is healthy. Every other successful path stays on the
- * same harness and uses `/continue`, whose indexed transcript reader can reach
- * retained version trash. No healthy same-harness account is a loud failure.
+ * Native resume is legal only in the exact origin version's isolated home,
+ * and only while that home owns the indexed transcript AND some injectable
+ * credential for this harness is healthy: the origin login itself, or a
+ * provider account rotated in when the origin is usage-limited (PHNX-3626).
+ * Every other successful path stays on the same harness and uses `/continue`,
+ * whose indexed transcript reader can reach retained version trash. A
+ * `/continue` pick of a provider account carries RecoveryAccount so exec
+ * injects it instead of launching the version home's native login
+ * (PHNX-3674). No healthy same-harness account is a loud failure.
  */
 export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume, nativeInspection) {
     const agent = runnableSessionAgent(session);
@@ -175,18 +190,17 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
             ?? inspectNativeResumeSession(session, getVersionHomePath(agent, session.version));
         if (inspection.available) {
             const rotated = pickBalancedCandidate(candidates.filter((c) => c.providerAccount && c.accountKey !== source.accountKey));
-            const providerAccount = rotated?.picked.providerAccount;
-            if (providerAccount) {
+            const account = rotated ? recoveryAccountFromCandidate(rotated.picked) : undefined;
+            if (account) {
                 // `originLimited` guarantees the origin is unhealthy with a limit reason.
                 const why = originReadiness.ready ? 'limited' : originReadiness.reason;
-                const label = rotated.picked.accountLabel || providerAccount;
                 return {
                     mode: 'native',
                     agent,
                     version: session.version,
                     cwd: inspection.cwd,
-                    account: { providerAccount, label, email: rotated.picked.email },
-                    reason: `origin ${agent}@${session.version} account is ${why}; rotated to healthy ${label} and resuming natively in the same home`,
+                    account,
+                    reason: `origin ${agent}@${session.version} account is ${why}; rotated to healthy ${account.label} and resuming natively in the same home`,
                 };
             }
         }
@@ -203,6 +217,8 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         throw new SessionRecoveryError(`Cannot recover session ${session.shortId} on ${device}; origin ${agent}@${session.version ?? 'unknown'}. ${detail}`);
     }
     const version = selection.picked.version;
+    const account = recoveryAccountFromCandidate(selection.picked);
+    const continueWith = account ? `healthy ${account.label}` : `healthy ${agent}@${version}`;
     // Native resume without an injected RecoveryAccount is valid only for the
     // exact healthy origin login. A balanced same-version provider selected for
     // a signed-out/revoked origin must stay on /continue; otherwise we would open
@@ -223,14 +239,16 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
             mode: 'continue',
             agent,
             version,
-            reason: `${inspection.reason}; continuing with healthy ${agent}@${version}`,
+            ...(account ? { account } : {}),
+            reason: `${inspection.reason}; continuing with ${continueWith}`,
         };
     }
     return {
         mode: 'continue',
         agent,
         version,
-        reason: `${sourceReason(session, candidates)}; continuing with healthy ${agent}@${version}`,
+        ...(account ? { account } : {}),
+        reason: `${sourceReason(session, candidates)}; continuing with ${continueWith}`,
     };
 }
 /**

package/dist/lib/session/remote/watch.js

@@ -265,9 +265,12 @@ export function readPreviousSessionsForWatch(scope) {
     try {
         return querySessions({
             machine: normalizeHost(scope),
-            limit: SESSION_WATCH_PREVIOUS_LIMIT,
+            agents: ['claude', 'codex', 'muse', 'opencode'],
+            sinceMs: Date.now() - 7 * 24 * 60 * 60 * 1000,
             excludeTeamOrigin: true,
-        });
+        })
+            .filter((session) => !session.archived && Boolean(session.filePath))
+            .slice(0, SESSION_WATCH_PREVIOUS_LIMIT);
     }
     catch {
         return [];

package/dist/lib/session/state.js

@@ -19,6 +19,7 @@ import { isCompletedTodoStatus, SNAPSHOT_TODO_TOOLS, summarizeToolUse } from './
 import { isShellExecTool } from './shell-programs.js';
 import { classifyFileChanges } from './digest.js';
 import { extractArtifacts } from './highlights.js';
+import { LINEAR_KEY_DENYLIST, linearIssueKeys } from './linear.js';
 /**
  * Detect per-session rate-limit / usage-limit signals in assistant or error
  * text (RUSH-1523). Matches the same shapes the ext's prewarm detectBlockingPrompt
@@ -187,15 +188,12 @@ export function extractRecentDirectoriesTouched(events, cwd) {
 const QUESTION_TRAILING = /\?["'”)\]]?\s*$/;
 const QUESTION_PHRASE = /\b(shall i|should i|do you want|would you like|which (?:one|option|approach|of)|can you (?:confirm|clarify)|please (?:confirm|clarify|advise)|let me know|are you (?:ok|okay|sure)|proceed\?)\b/i;
 /**
- * Linear/Jira-style ref, e.g. RUSH-1234. Team key is letters-only (2–6) so a
- * regex snippet like `[A-Z0-9]-\d` in a code discussion can't masquerade as a
- * ticket. Uppercase-only so we don't match `utf-8`.
+ * Linear/Jira-style ref detection reuses the canonical key matcher +
+ * {@link LINEAR_KEY_DENYLIST} from `./linear.js`, so the transcript detector and
+ * the owner-ping linkifier agree on what a real key is (no second copy to drift).
  */
-const TICKET_RE = /\b([A-Z]{2,6}-\d{1,6})\b/;
 /** Lowercase branch form (Linear branch names): muqsit/rush-1234-fix. */
 const TICKET_BRANCH_RE = /(?:^|[/_-])([a-z]{2,6})-(\d{2,6})(?=[/_-]|$)/;
-/** Keys that look like tickets but aren't — avoid false positives from branches. */
-const TICKET_DENYLIST = new Set(['UTF', 'SHA', 'ISO', 'RFC', 'IPV', 'X86', 'ARM', 'MP', 'H']);
 const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
 // Either separator: a Windows session cwd is `…\.agents\worktrees\<slug>`, and a
 // forward-slash-only pattern silently derived no slug there (the RUSH-2358
@@ -283,15 +281,15 @@ export function detectWorktree(cwd, branch) {
 /** Detect a tracker ticket from free text (prompt/topic) then a branch name. */
 export function detectTicket(text, branch) {
     if (text) {
-        const m = text.match(TICKET_RE);
-        if (m && !TICKET_DENYLIST.has(m[1].split('-')[0]))
-            return { id: m[1] };
+        const key = linearIssueKeys(text)[0];
+        if (key)
+            return { id: key };
     }
     if (branch) {
         const m = branch.match(TICKET_BRANCH_RE);
         if (m) {
             const key = m[1].toUpperCase();
-            if (!TICKET_DENYLIST.has(key))
+            if (!LINEAR_KEY_DENYLIST.has(key))
                 return { id: `${key}-${m[2]}` };
         }
     }
@@ -355,9 +353,9 @@ export function isTicketCreateTool(name, command) {
 export function extractCreatedTicket(text) {
     if (!text)
         return undefined;
-    const lin = text.match(TICKET_RE);
-    if (lin && !TICKET_DENYLIST.has(lin[1].split('-')[0]))
-        return lin[1];
+    const lin = linearIssueKeys(text)[0];
+    if (lin)
+        return lin;
     const gh = text.match(GH_ISSUE_URL_RE);
     if (gh)
         return `#${gh[1]}`;

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

@@ -88,8 +88,8 @@ export declare function phoenixIdBaseForDeploy(opts?: {
     domain?: string;
 }): string | undefined;
 /**
- * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
- * override → managed; otherwise BYO.
+ * Pick the principal via the shared selection policy. Signed-in AND no explicit
+ * BYO override → managed; otherwise BYO.
  */
 export declare function shouldUseManaged(opts?: ResolveShareBackendOpts): boolean;
 export declare function resolveShareBackend(opts?: ResolveShareBackendOpts): ShareBackend;

package/dist/lib/share/backend.js

@@ -18,6 +18,7 @@
  *   - `AGENTS_SHARE_BACKEND=byo`
  */
 import { PHOENIX_ID_BASE, readSession } from '../identity/client.js';
+import { selectStorageBackendKind } from '../storage/selection.js';
 import { DEFAULT_SHARE_DOMAIN, readShareConfig, readWriteToken, readWriteTokenEnv, } from './config.js';
 /** Env var that forces the BYO path. Value must be exactly `byo`. */
 export const SHARE_BACKEND_ENV = 'AGENTS_SHARE_BACKEND';
@@ -82,18 +83,28 @@ export function phoenixIdBaseForDeploy(opts = {}, cfg) {
     return base;
 }
 /**
- * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
- * override → managed; otherwise BYO.
+ * The share surface's BYO-override signals: an explicit `--byo`, a
+ * caller-supplied static write token, or `AGENTS_SHARE_BACKEND=byo`. Detecting
+ * WHICH signals count is surface-specific; the managed-vs-BYO decision itself is
+ * the shared policy (`selectStorageBackendKind`). A persisted BYO endpoint config
+ * is deliberately NOT an override here — a signed-in user with a stale BYO config
+ * still publishes to managed unless they opt out explicitly (the product's
+ * managed-first contract).
  */
-export function shouldUseManaged(opts = {}) {
+function shareByoOverride(opts) {
     if (opts.byo === true)
-        return false;
+        return true;
     if (opts.writeToken)
-        return false;
-    if ((process.env[SHARE_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo')
-        return false;
-    const session = opts.session === undefined ? readSession() : opts.session;
-    return session != null;
+        return true;
+    return (process.env[SHARE_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo';
+}
+/**
+ * Pick the principal via the shared selection policy. Signed-in AND no explicit
+ * BYO override → managed; otherwise BYO.
+ */
+export function shouldUseManaged(opts = {}) {
+    return (selectStorageBackendKind({ byoOverride: shareByoOverride(opts), session: opts.session }) ===
+        'managed');
 }
 export function resolveShareBackend(opts = {}) {
     if (shouldUseManaged(opts)) {

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

@@ -1,8 +1,12 @@
 import { type ShareConfig } from './config.js';
-/** DI seam for tests — override the real HTTP DELETE. */
+/** DI seam for tests — override the real HTTP DELETE. `body`/`retryAfter` carry
+ * the Worker's error response (read only on `!ok`) so a failed delete surfaces
+ * WHY, via the bounded {@link extractShareHttpError}. */
 export type DeleteFn = (url: string, headers: Record<string, string>) => Promise<{
     ok: boolean;
     status: number;
+    body?: string;
+    retryAfter?: string;
 }>;
 /** DI seam for tests — override the real HTTP existence check (HEAD). */
 export type CheckFn = (url: string) => Promise<{

package/dist/lib/share/delete.js

@@ -9,6 +9,7 @@
 // the operation is reported as successful.
 import { resolveShareBackend } from './backend.js';
 import { buildShareKey, resolveShareUsername } from './publish.js';
+import { extractShareHttpError, formatShareHttpErrorDetail } from './http-error.js';
 /**
  * Normalize any of the three accepted target forms to the R2 key that publish
  * would have written:
@@ -59,7 +60,10 @@ async function defaultCheck(url) {
 }
 async function defaultDelete(url, headers) {
     const res = await fetch(url, { method: 'DELETE', headers });
-    return { ok: res.ok, status: res.status };
+    if (res.ok)
+        return { ok: true, status: res.status };
+    const body = await res.text().catch(() => undefined);
+    return { ok: false, status: res.status, body, retryAfter: res.headers.get('retry-after') ?? undefined };
 }
 async function defaultRevisionsFetch(url) {
     const res = await fetch(url, { headers: { accept: 'application/json' } });
@@ -103,7 +107,8 @@ export async function deleteObject(endpoint, key, opts = {}) {
     const existedBefore = before.status !== 404;
     const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
     if (!r.ok) {
-        throw new Error(`Delete failed (${r.status}) for ${url}. Check the bearer (Phoenix session or WRITE_TOKEN), or that 'agents artifacts setup' completed.`);
+        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: r.status, body: r.body, retryAfter: r.retryAfter }));
+        throw new Error(`Delete failed (${r.status}) for ${url}${detail}. Check the bearer (Phoenix session or WRITE_TOKEN), or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;

package/dist/lib/share/http-error.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ONE bounded extractor for the share Worker's error responses.
+ *
+ * Every share HTTP call (publish PUT, list/revisions GET, delete DELETE)
+ * previously threw on `!ok` with only the status code, discarding the JSON error
+ * body the Worker actually returns (`{"error":"…"}` for a 400/413/429, plus a
+ * `Retry-After` on a 429). The result: a rate-limited or quota-exceeded publish
+ * surfaced as a bare "Publish failed (429)" with no reason. This pulls the
+ * server's own `error` string and preserves the status + `Retry-After`, so the
+ * user sees why.
+ *
+ * Bounded and safe by construction: it parses at most {@link MAX_ERROR_BODY_BYTES}
+ * of the body, only lifts a string `error` field, caps its length, and NEVER
+ * surfaces an arbitrary body — a non-JSON or oversized body yields no message,
+ * so an HTML error page or a huge payload can't leak into a CLI error string.
+ */
+/** The raw pieces a caller's fetch wrapper hands in — status plus the (optional)
+ * response body text and `Retry-After` header value. */
+export interface ShareHttpResponse {
+    status: number;
+    /** The response body text, when the caller read it (only on `!ok` paths). */
+    body?: string;
+    /** The `Retry-After` header value, when present (a 429 carries it). */
+    retryAfter?: string;
+}
+/** The extracted, bounded error facts. `serverMessage` is present only when the
+ * body parsed as JSON carrying a non-empty string `error`. */
+export interface ShareHttpError {
+    status: number;
+    serverMessage?: string;
+    retryAfter?: string;
+}
+/** Never parse more than this many chars of a body — a legitimate `{"error":"…"}`
+ * is tiny; a larger body is an HTML page or noise we deliberately don't surface. */
+export declare const MAX_ERROR_BODY_BYTES = 4096;
+/** Cap the surfaced message so even a pathological (but valid-JSON) `error`
+ * string can't blow up the CLI output. */
+export declare const MAX_ERROR_MESSAGE_CHARS = 300;
+/**
+ * Extract the bounded error facts from a share Worker response. Pulls a string
+ * `error` field from a small JSON body, preserves status + `Retry-After`, and
+ * never surfaces an arbitrary body.
+ */
+export declare function extractShareHttpError(res: ShareHttpResponse): ShareHttpError;
+/**
+ * A one-line suffix summarizing the server's structured error, or `''` when the
+ * response carried nothing extractable. Appended after the status-bearing prefix
+ * a caller already builds, e.g.:
+ *   `Publish failed (429) for <url>` + `formatShareHttpErrorDetail(err)`
+ *   → `Publish failed (429) for <url> — rate limit exceeded; retry after 37s`
+ */
+export declare function formatShareHttpErrorDetail(err: ShareHttpError): string;

package/dist/lib/share/http-error.js

@@ -0,0 +1,65 @@
+/**
+ * ONE bounded extractor for the share Worker's error responses.
+ *
+ * Every share HTTP call (publish PUT, list/revisions GET, delete DELETE)
+ * previously threw on `!ok` with only the status code, discarding the JSON error
+ * body the Worker actually returns (`{"error":"…"}` for a 400/413/429, plus a
+ * `Retry-After` on a 429). The result: a rate-limited or quota-exceeded publish
+ * surfaced as a bare "Publish failed (429)" with no reason. This pulls the
+ * server's own `error` string and preserves the status + `Retry-After`, so the
+ * user sees why.
+ *
+ * Bounded and safe by construction: it parses at most {@link MAX_ERROR_BODY_BYTES}
+ * of the body, only lifts a string `error` field, caps its length, and NEVER
+ * surfaces an arbitrary body — a non-JSON or oversized body yields no message,
+ * so an HTML error page or a huge payload can't leak into a CLI error string.
+ */
+/** Never parse more than this many chars of a body — a legitimate `{"error":"…"}`
+ * is tiny; a larger body is an HTML page or noise we deliberately don't surface. */
+export const MAX_ERROR_BODY_BYTES = 4096;
+/** Cap the surfaced message so even a pathological (but valid-JSON) `error`
+ * string can't blow up the CLI output. */
+export const MAX_ERROR_MESSAGE_CHARS = 300;
+/**
+ * Extract the bounded error facts from a share Worker response. Pulls a string
+ * `error` field from a small JSON body, preserves status + `Retry-After`, and
+ * never surfaces an arbitrary body.
+ */
+export function extractShareHttpError(res) {
+    const out = { status: res.status };
+    const retryAfter = res.retryAfter?.trim();
+    if (retryAfter)
+        out.retryAfter = retryAfter;
+    const raw = res.body;
+    if (raw && raw.length <= MAX_ERROR_BODY_BYTES) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const err = parsed.error;
+                if (typeof err === 'string' && err.trim()) {
+                    out.serverMessage = err.trim().slice(0, MAX_ERROR_MESSAGE_CHARS);
+                }
+            }
+        }
+        catch {
+            // Not JSON (an HTML error page, a proxy body, truncated bytes) — deliberately
+            // surface nothing rather than dump an arbitrary body into the CLI error.
+        }
+    }
+    return out;
+}
+/**
+ * A one-line suffix summarizing the server's structured error, or `''` when the
+ * response carried nothing extractable. Appended after the status-bearing prefix
+ * a caller already builds, e.g.:
+ *   `Publish failed (429) for <url>` + `formatShareHttpErrorDetail(err)`
+ *   → `Publish failed (429) for <url> — rate limit exceeded; retry after 37s`
+ */
+export function formatShareHttpErrorDetail(err) {
+    const parts = [];
+    if (err.serverMessage)
+        parts.push(err.serverMessage);
+    if (err.retryAfter)
+        parts.push(`retry after ${err.retryAfter}s`);
+    return parts.length ? ` — ${parts.join('; ')}` : '';
+}

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

@@ -1,10 +1,20 @@
 import { type ShareConfig } from './config.js';
 import { type ShareBackendKind } from './backend.js';
-export type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<{
+import { type ShareVisibility } from '../storage/visibility.js';
+/** The share upload result. `body`/`retryAfter` carry the server's error
+ * response so a failed publish can surface WHY (the Worker returns
+ * `{"error":"…"}` + a `Retry-After` on a 429); they are read only on `!ok`
+ * paths, and only ever fed through the bounded {@link extractShareHttpError}. */
+export type PutResult = {
     ok: boolean;
     status: number;
     url?: string;
-}>;
+    /** Response body text, present on the `!ok` path so the error can be extracted. */
+    body?: string;
+    /** `Retry-After` header value, present on a 429. */
+    retryAfter?: string;
+};
+export type PutFn = (url: string, body: Buffer, headers: Record<string, string>) => Promise<PutResult>;
 export interface PublishEndpoint {
     baseUrl: string;
     token: string;
@@ -102,7 +112,7 @@ export interface PublishOptions {
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
-export type ShareVisibility = 'public' | 'unlisted' | 'private' | 'me' | 'org';
+export { type ShareVisibility } from '../storage/visibility.js';
 /** The visibility levels a publish `--visibility` may select — the Worker's own
  * set. `private` (token-gated, PHNX-3654) is settable only at publish time,
  * since it mints a viewer token the metadata-edit route can't carry, so it is

package/dist/lib/share/publish.js

@@ -16,6 +16,8 @@ import { resolveGitHubUsername } from '../git.js';
 import { resolveShareBackend, sanitizeShareNamespace } from './backend.js';
 import { captureCover, OG_WIDTH, OG_HEIGHT, OG_SCALE } from './capture.js';
 import { deriveMeta, injectOgMeta } from './og.js';
+import { extractShareHttpError, formatShareHttpErrorDetail } from './http-error.js';
+import { PUBLISH_VISIBILITY_LEVELS as STORAGE_PUBLISH_VISIBILITY_LEVELS, EDITABLE_VISIBILITY_LEVELS, resolveVisibility, } from '../storage/visibility.js';
 import { injectAnalyticsBeacon } from './analytics.js';
 import { prepareShareHtml } from './html.js';
 /** The visibility levels a publish `--visibility` may select — the Worker's own
@@ -23,12 +25,12 @@ import { prepareShareHtml } from './html.js';
  * since it mints a viewer token the metadata-edit route can't carry, so it is
  * NOT in {@link SHARE_VISIBILITY_LEVELS} (the in-place `share visibility <level>`
  * set). */
-export const PUBLISH_VISIBILITY_LEVELS = ['public', 'unlisted', 'private', 'me', 'org'];
+export const PUBLISH_VISIBILITY_LEVELS = STORAGE_PUBLISH_VISIBILITY_LEVELS;
 /** The visibility levels an ALREADY-published share may be re-scoped to in place
  * — the set `share visibility <target> <level>` and the inline owner control
  * accept. Excludes `private`: re-scoping to token-gated needs a fresh viewer
  * token, which only the publish path mints. */
-export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
+export const SHARE_VISIBILITY_LEVELS = EDITABLE_VISIBILITY_LEVELS;
 /**
  * `--protected` / `{ protected: true }` map to `private` (token-gated — it wins
  * over `--unlisted` when both are set, being the stronger control); `--unlisted`
@@ -36,17 +38,13 @@ export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
  * otherwise `visibility` (default public).
  */
 export function resolveShareVisibility(opts = {}) {
-    if (opts.protected === true)
-        return 'private';
-    if (opts.unlisted === true)
-        return 'unlisted';
-    if (opts.visibility === 'unlisted' ||
-        opts.visibility === 'private' ||
-        opts.visibility === 'me' ||
-        opts.visibility === 'org') {
-        return opts.visibility;
-    }
-    return 'public';
+    // Delegates to the shared visibility resolver. The library fallback stays
+    // `public` so a lib caller that hasn't opted into the managed `me` default
+    // (e.g. `sessions share --public`, which expresses "public" as the absence of
+    // --unlisted) is never silently flipped. The PRODUCT default (`me` on managed)
+    // is applied by the `agents artifacts share` command surface, which knows the
+    // resolved backend — see `commands/share.ts`.
+    return resolveVisibility(opts);
 }
 /** The bytes of viewer-token entropy the `private` mode mints (128-bit; the
  * base64url form is ~22 URL-safe chars). Well past the 64-bit floor a guessable
@@ -596,7 +594,12 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const put = opts.uploader ??
         (async (u, b, h) => {
             const res = await fetch(u, { method: 'PUT', headers: h, body: new Uint8Array(b) });
-            return { ok: res.ok, status: res.status, url: u };
+            // Read the error body only on failure, so the caller can surface the
+            // Worker's own `{"error":"…"}` + Retry-After (bounded by extractShareHttpError).
+            if (res.ok)
+                return { ok: true, status: res.status, url: u };
+            const body = await res.text().catch(() => undefined);
+            return { ok: false, status: res.status, url: u, body, retryAfter: res.headers.get('retry-after') ?? undefined };
         });
     let coverUrl;
     const isHtml = /\.html?$/i.test(filePath);
@@ -748,7 +751,8 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         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.`);
         }
-        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. 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.`);
     }
     // 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

@@ -1406,7 +1406,11 @@ function isIdentityGated(visibility) {
 
 function managedCoverHeaders(visibility) {
   const headers = new Headers({ 'content-type': 'image/png' });
-  if (isIdentityGated(visibility)) {
+  // Token-gated (private) + identity-gated (me/org) covers must never be
+  // cached by a shared proxy, and never indexed. RFC 9111: public on an
+  // Authorization response authorizes reuse for later unauthenticated
+  // requests keyed on /user/slug.png (PHNX-3676).
+  if (isIdentityGated(visibility) || visibility === 'private') {
     headers.set('cache-control', 'private, no-store');
     headers.set('X-Robots-Tag', 'noindex');
   } else {