@phnx-labs/agents-cli 1.22.66 → 1.22.69

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

@@ -9,9 +9,13 @@ import { machineId, normalizeHost } from '../../machine-id.js';
 import { SSH_OPTS, controlOpts, shellQuote } from '../../ssh-exec.js';
 import { buildWindowsAgentsCommand, remoteShellFor } from '../../hosts/remote-cmd.js';
 import { isReapableOrphan } from '../active.js';
+import { querySessions } from '../db.js';
+import { linearIssueUrl } from '../linear.js';
+import { sessionAgentSupportsResume } from '../recovery.js';
 import { activeSessionsJournalPath, activeSessionJournalIdentity, readActiveSessionsCache, noteActiveSessionsJournalReader, } from '../session-cache.js';
 export const SESSION_WATCH_VERSION = 1;
 export const SESSION_WATCH_HEARTBEAT_MS = 15_000;
+export const SESSION_WATCH_PREVIOUS_LIMIT = 50;
 /** Stable, opaque identity for one row within one device scope. */
 export function sessionWatchRowKey(scope, row) {
     const identity = activeSessionJournalIdentity(row);
@@ -24,6 +28,9 @@ export function toSessionWatchRow(scope, row) {
     // leaked --device tunnel sessions (RUSH-3011 / issue #3b). A live or
     // recently-exited session stays resumable.
     const resumable = Boolean(row.sessionId) && !isReapableOrphan(row);
+    const previous = row.status === 'closed'
+        || row.status === 'crashed'
+        || (row.status === 'abandoned' && row.pidAlive === false);
     const viewingIn = row.viewingIn
         ? [row.viewingIn.app, row.viewingIn.tab ? `tab ${row.viewingIn.tab}` : undefined].filter(Boolean).join(' ')
         : null;
@@ -31,6 +38,7 @@ export function toSessionWatchRow(scope, row) {
         ...row,
         rowKey,
         sourceDevice: scope,
+        previous,
         resumable,
         unwatched: !viewingIn,
         viewingIn,
@@ -39,6 +47,88 @@ export function toSessionWatchRow(scope, row) {
             : null,
     };
 }
+function epochMs(value) {
+    const parsed = value ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** Stable identity for a durable Previous row. It is deliberately distinct
+ * from the live row key for the same session id: both may coexist on the one
+ * stream, and the presentation layer lets the live row win while it exists. */
+export function previousSessionWatchRowKey(scope, sessionId) {
+    return createHash('sha256').update(`${scope}\0previous\0${sessionId}`).digest('base64url').slice(0, 22);
+}
+/** Project one durable indexed session into the same canonical watch contract
+ * as live sessions. This is the only history backfill consumed by AGI EXT. */
+export function toPreviousSessionWatchRow(scope, session) {
+    const resumable = sessionAgentSupportsResume(session.agent);
+    const sourceDevice = normalizeHost(session.machine ?? scope);
+    const startedAtMs = epochMs(session.timestamp);
+    const lastActivityMs = epochMs(session.lastActivity) || startedAtMs;
+    const worktree = session.worktreeSlug && session.cwd
+        ? { slug: session.worktreeSlug, path: session.cwd, ...(session.gitBranch ? { branch: session.gitBranch } : {}) }
+        : undefined;
+    return {
+        context: 'recent',
+        kind: session.agent,
+        ...(session.harness ? { harness: session.harness } : {}),
+        sessionId: session.id,
+        ...(session.cwd ? { cwd: session.cwd } : {}),
+        ...(session.project ? { project: session.project } : {}),
+        ...(session.label ? { label: session.label, title: session.label } : session.topic ? { title: session.topic } : {}),
+        ...(session.topic ? { topic: session.topic } : {}),
+        ...(session.firstUserMessage ? { firstUserMessage: session.firstUserMessage } : {}),
+        ...(session.version ? { version: session.version } : {}),
+        ...(session.account ? { account: session.account } : {}),
+        ...(session.prUrl ? { pr: { url: session.prUrl, number: session.prNumber } } : {}),
+        ...(worktree ? { worktree } : {}),
+        ...(session.gitBranch ? { branch: session.gitBranch } : {}),
+        ...(session.ticketId ? { ticket: { id: session.ticketId, url: linearIssueUrl(session.ticketId) } } : {}),
+        ...(session.createdTickets ? { createdTickets: session.createdTickets } : {}),
+        ...(session.spawnedTeam ? { spawnedTeam: session.spawnedTeam } : {}),
+        ...(session.tokenCount != null ? { tokenCount: session.tokenCount } : {}),
+        ...(session.durationMs != null ? { durationMs: session.durationMs } : {}),
+        ...(session.subAgentCount != null ? { subAgentCount: session.subAgentCount } : {}),
+        startedAtMs,
+        lastActivityMs,
+        status: 'closed',
+        phase: 'done',
+        pidAlive: false,
+        rowKey: previousSessionWatchRowKey(scope, session.id),
+        sourceDevice,
+        previous: true,
+        resumable,
+        unwatched: true,
+        viewingIn: null,
+        recovery: resumable
+            ? { command: 'agents', args: ['sessions', 'resume', session.id, '--device', sourceDevice], ...(session.cwd ? { cwd: session.cwd } : {}) }
+            : null,
+    };
+}
+function demoteWatchRow(scope, row) {
+    if (!row.sessionId || row.rowKey === previousSessionWatchRowKey(scope, row.sessionId))
+        return null;
+    const sourceDevice = row.sourceDevice || scope;
+    return {
+        ...row,
+        context: 'recent',
+        status: 'closed',
+        phase: 'done',
+        pidAlive: false,
+        rowKey: previousSessionWatchRowKey(scope, row.sessionId),
+        previous: true,
+        unwatched: true,
+        viewingIn: null,
+        recovery: row.resumable
+            ? { command: 'agents', args: ['sessions', 'resume', row.sessionId, '--device', sourceDevice], ...(row.cwd ? { cwd: row.cwd } : {}) }
+            : null,
+    };
+}
+function isDurablePreviousRow(scope, row) {
+    return Boolean(row.sessionId) && row.rowKey === previousSessionWatchRowKey(scope, row.sessionId);
+}
+function rowRecency(row) {
+    return row.lastActivityMs ?? row.startedAtMs ?? 0;
+}
 function sameRow(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
@@ -51,24 +141,77 @@ export class SessionWatchState {
     base(type) {
         return { version: SESSION_WATCH_VERSION, type, streamId: this.streamId, sequence: ++this.sequence, capturedAt: Date.now() };
     }
-    reset(scope, sourceRows) {
-        const rows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        this.rows.set(scope, new Map(rows.map((row) => [row.rowKey, row])));
-        return { ...this.base('reset'), scope, rows };
+    /** Keep one visible Previous row per session and the newest bounded window.
+     * Returns removed keys so delta callers can converge already-connected clients. */
+    prunePrevious(scope, rows) {
+        const removed = [];
+        const bySession = new Map();
+        for (const row of rows.values()) {
+            if (!row.previous || !row.sessionId)
+                continue;
+            const existing = bySession.get(row.sessionId);
+            if (!existing) {
+                bySession.set(row.sessionId, row);
+                continue;
+            }
+            const keepRow = rowRecency(row) > rowRecency(existing)
+                || (rowRecency(row) === rowRecency(existing) && isDurablePreviousRow(scope, row));
+            const drop = keepRow ? existing : row;
+            const keep = keepRow ? row : existing;
+            if (rows.delete(drop.rowKey))
+                removed.push(drop.rowKey);
+            bySession.set(row.sessionId, keep);
+        }
+        const previous = [...bySession.values()].sort((a, b) => rowRecency(b) - rowRecency(a));
+        for (const row of previous.slice(SESSION_WATCH_PREVIOUS_LIMIT)) {
+            if (rows.delete(row.rowKey))
+                removed.push(row.rowKey);
+        }
+        return removed;
+    }
+    reset(scope, sourceRows, indexedRows = []) {
+        const liveRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
+        const sourceIds = new Set(liveRows.map((row) => row.sessionId).filter((id) => Boolean(id)));
+        const rows = new Map(liveRows.map((row) => [row.rowKey, row]));
+        for (const indexed of indexedRows) {
+            if (sourceIds.has(indexed.id))
+                continue;
+            const row = toPreviousSessionWatchRow(scope, indexed);
+            rows.set(row.rowKey, row);
+        }
+        this.prunePrevious(scope, rows);
+        this.rows.set(scope, rows);
+        return { ...this.base('reset'), scope, rows: [...rows.values()] };
     }
     update(scope, sourceRows) {
         const previous = this.rows.get(scope) ?? new Map();
         const nextRows = sourceRows.map((row) => toSessionWatchRow(scope, row));
-        const next = new Map(nextRows.map((row) => [row.rowKey, row]));
+        const activeIds = new Set(nextRows.filter((row) => !row.previous).map((row) => row.sessionId).filter((id) => Boolean(id)));
+        const next = new Map([...previous.values()]
+            .filter((row) => isDurablePreviousRow(scope, row) && (!row.sessionId || !activeIds.has(row.sessionId)))
+            .map((row) => [row.rowKey, row]));
+        for (const row of nextRows)
+            next.set(row.rowKey, row);
         const events = [];
         for (const [rowKey, row] of next) {
             if (!previous.has(rowKey) || !sameRow(previous.get(rowKey), row)) {
                 events.push({ ...this.base('upsert'), scope, rowKey, row });
             }
         }
-        for (const rowKey of previous.keys()) {
-            if (!next.has(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
+        for (const [rowKey, row] of previous) {
+            if (next.has(rowKey))
+                continue;
+            if (isDurablePreviousRow(scope, row) && (!row.sessionId || !activeIds.has(row.sessionId)))
+                continue;
+            events.push({ ...this.base('remove'), scope, rowKey });
+            const demoted = demoteWatchRow(scope, row);
+            if (demoted && (!next.has(demoted.rowKey) || !sameRow(next.get(demoted.rowKey), demoted))) {
+                next.set(demoted.rowKey, demoted);
+                events.push({ ...this.base('upsert'), scope, rowKey: demoted.rowKey, row: demoted });
+            }
+        }
+        for (const rowKey of this.prunePrevious(scope, next)) {
+            events.push({ ...this.base('remove'), scope, rowKey });
         }
         this.rows.set(scope, next);
         return events;
@@ -78,6 +221,11 @@ export class SessionWatchState {
         const events = [];
         for (const source of upserts) {
             const row = toSessionWatchRow(scope, source);
+            if (!row.previous && row.sessionId) {
+                const previousKey = previousSessionWatchRowKey(scope, row.sessionId);
+                if (current.delete(previousKey))
+                    events.push({ ...this.base('remove'), scope, rowKey: previousKey });
+            }
             if (!current.has(row.rowKey) || !sameRow(current.get(row.rowKey), row)) {
                 current.set(row.rowKey, row);
                 events.push({ ...this.base('upsert'), scope, rowKey: row.rowKey, row });
@@ -85,8 +233,18 @@ export class SessionWatchState {
         }
         for (const identity of removes) {
             const rowKey = createHash('sha256').update(`${scope}\0${identity}`).digest('base64url').slice(0, 22);
-            if (current.delete(rowKey))
-                events.push({ ...this.base('remove'), scope, rowKey });
+            const removed = current.get(rowKey);
+            if (!current.delete(rowKey))
+                continue;
+            events.push({ ...this.base('remove'), scope, rowKey });
+            const demoted = removed ? demoteWatchRow(scope, removed) : null;
+            if (demoted && (!current.has(demoted.rowKey) || !sameRow(current.get(demoted.rowKey), demoted))) {
+                current.set(demoted.rowKey, demoted);
+                events.push({ ...this.base('upsert'), scope, rowKey: demoted.rowKey, row: demoted });
+            }
+        }
+        for (const rowKey of this.prunePrevious(scope, current)) {
+            events.push({ ...this.base('remove'), scope, rowKey });
         }
         this.rows.set(scope, current);
         return events;
@@ -100,6 +258,24 @@ export class SessionWatchState {
         return { ...this.base('heartbeat'), scope, capturedAt };
     }
 }
+/** One bounded index read when the watch starts. The stream then owns this
+ * projection: active rows update through the journal, and removals demote into
+ * Previous rows without another transcript/index poll. */
+export function readPreviousSessionsForWatch(scope) {
+    try {
+        return querySessions({
+            machine: normalizeHost(scope),
+            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 [];
+    }
+}
 /**
  * Keep one local subscription alive. Startup reads one canonical reset snapshot;
  * steady state tails the canonical writer journal and never invokes a gather.
@@ -107,6 +283,7 @@ export class SessionWatchState {
 export async function watchLocalSessions(options) {
     const state = new SessionWatchState();
     const readCache = options.readCache ?? readActiveSessionsCache;
+    const readPrevious = options.readPrevious ?? readPreviousSessionsForWatch;
     const journal = options.journalPath ?? activeSessionsJournalPath();
     const heartbeatMs = options.heartbeatMs ?? SESSION_WATCH_HEARTBEAT_MS;
     let offset = 0;
@@ -115,7 +292,7 @@ export async function watchLocalSessions(options) {
     }
     catch { /* first publication */ }
     const initial = readCache('local');
-    options.emit(state.reset(options.scope, initial?.sessions ?? []));
+    options.emit(state.reset(options.scope, initial?.sessions ?? [], readPrevious(options.scope)));
     // Known gap (out of scope for RUSH-2484): a present cache alone marks
     // 'available' with no staleness/age check, so a reconnect can briefly render
     // a stale snapshot as live before the out-of-band gather this file triggers

package/dist/lib/session/session-cache.d.ts

@@ -32,6 +32,7 @@ export declare function activeSessionJournalIdentity(row: ActiveSession): string
  */
 export interface ImmutableSessionFields {
     topic?: string;
+    firstUserMessage?: string;
     label?: string;
     name?: string;
     cwd?: string;
@@ -51,7 +52,7 @@ export interface ImmutableSessionFields {
     context?: ActiveSession['context'];
 }
 /** Keys stored in the immutable memo (transcript-stable). */
-export declare const IMMUTABLE_FIELD_KEYS: readonly ["topic", "label", "name", "cwd", "project", "attachments", "startedAtMs", "version", "pr", "worktree", "ticket", "createdTickets", "spawnedTeam", "sessionFile", "owner", "assignedTask", "kind", "context"];
+export declare const IMMUTABLE_FIELD_KEYS: readonly ["topic", "firstUserMessage", "label", "name", "cwd", "project", "attachments", "startedAtMs", "version", "pr", "worktree", "ticket", "createdTickets", "spawnedTeam", "sessionFile", "owner", "assignedTask", "kind", "context"];
 /**
  * Live / volatile fields that MUST NOT be served from the immutable memo.
  * They either change without a transcript write (pid death, attach state) or

package/dist/lib/session/session-cache.js

@@ -51,6 +51,7 @@ const activeSnapshotMemory = createMemoryCache({
 /** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',
+    'firstUserMessage',
     'label',
     'name',
     'cwd',

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/session/types.d.ts

@@ -232,6 +232,8 @@ export interface SessionMeta {
     /** Effective normalized launch mode captured by the SessionStart hook. */
     mode?: SessionRunMode;
     topic?: string;
+    /** Full, cleaned first genuine user turn; distinct from the one-line topic. */
+    firstUserMessage?: string;
     /**
      * The session's human-readable name — one field, several sources with a plain
      * priority: an agent-generated title / Claude `/rename` wins; else the launch

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('; ')}` : '';
+}