@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/lib/sha256-asset.d.ts

@@ -0,0 +1,26 @@
+/**
+ * sha256 helpers for verifying downloaded release assets.
+ *
+ * These live in their own LEAF module — importing only `node:crypto` and
+ * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
+ * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
+ * pure functions, and importing them from there closed a module-initialization
+ * cycle:
+ *
+ *   helper-download.ts
+ *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
+ *       -> browser/drivers/ssh.ts -> browser/chrome.ts
+ *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
+ *           -> secrets/download-keychain.ts
+ *             -> helper-download.ts    (still evaluating; const not yet bound)
+ *
+ * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
+ * initialization` at `secrets/download-keychain.ts:45` for any entry point that
+ * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
+ * a local import here can reintroduce that cycle.
+ */
+/** Pull the digest out of a `<sha256>  <filename>` release asset. */
+export declare function parseSha256Asset(text: string): string;
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export declare function sha256File(file: string): Promise<string>;

package/dist/lib/sha256-asset.js

@@ -0,0 +1,41 @@
+/**
+ * sha256 helpers for verifying downloaded release assets.
+ *
+ * These live in their own LEAF module — importing only `node:crypto` and
+ * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
+ * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
+ * pure functions, and importing them from there closed a module-initialization
+ * cycle:
+ *
+ *   helper-download.ts
+ *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
+ *       -> browser/drivers/ssh.ts -> browser/chrome.ts
+ *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
+ *           -> secrets/download-keychain.ts
+ *             -> helper-download.ts    (still evaluating; const not yet bound)
+ *
+ * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
+ * initialization` at `secrets/download-keychain.ts:45` for any entry point that
+ * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
+ * a local import here can reintroduce that cycle.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+/** Pull the digest out of a `<sha256>  <filename>` release asset. */
+export function parseSha256Asset(text) {
+    const m = text.trim().match(/^([A-Fa-f0-9]{64})(\s|$)/);
+    if (!m)
+        throw new Error(`malformed .sha256 release asset: ${JSON.stringify(text.slice(0, 80))}`);
+    return m[1].toLowerCase();
+}
+/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
+export function sha256File(file) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        fs.createReadStream(file)
+            .on('error', reject)
+            .on('data', (d) => hash.update(d))
+            .on('end', () => resolve(hash.digest('hex')));
+    });
+}

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

@@ -0,0 +1,95 @@
+/**
+ * ShareBackend — the token-source seam for `agents artifacts share`.
+ *
+ * Two legitimate principals, picked once at publish time:
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is
+ *     the already-live `share.agents-cli.sh`. Zero Cloudflare setup.
+ *   - **byo**: the existing static WRITE_TOKEN path (`readShareConfig()` +
+ *     `readWriteToken()`). Unchanged for power users / custom domains / fleet
+ *     injection of `SHARE_WRITE_TOKEN`.
+ *
+ * Dispatch is not a fallback: signed-in AND no BYO override → managed;
+ * otherwise BYO. Fail loud when neither principal can authenticate.
+ *
+ * Explicit BYO override (any one is enough):
+ *   - `opts.byo === true`
+ *   - `opts.writeToken` (a caller-supplied static token, including tests)
+ *   - `AGENTS_SHARE_BACKEND=byo`
+ */
+import { type PhoenixSession } from '../identity/client.js';
+import { type ShareConfig } from './config.js';
+export type ShareBackendKind = 'managed' | 'byo';
+export interface ShareBackend {
+    kind: ShareBackendKind;
+    /** Public base URL of the share Worker, no trailing slash. */
+    baseUrl: string;
+    /** Bearer sent as `Authorization`. Phoenix access_token or WRITE_TOKEN. */
+    token: string;
+    /** URL namespace prefix (`<namespace>/<slug>`). Phoenix handle (email local-part) or GitHub username. */
+    namespace: string;
+}
+export interface ResolveShareBackendOpts {
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
+    /** Override the namespace (BYO: GitHub username; ignored on managed — the
+     * worker 403s a Phoenix PUT whose first segment is not the verified handle). */
+    githubUser?: string;
+    /** DI seam — a static write token selects BYO. */
+    writeToken?: string;
+    /** DI seam — persisted BYO endpoint config. */
+    config?: ShareConfig;
+    /** DI seam — override `readSession()`. `null` means signed out. */
+    session?: PhoenixSession | null;
+    /**
+     * When false, BYO may resolve without a WRITE_TOKEN. Public GET routes
+     * (list / revisions / status) don't need one; publish and delete do.
+     * Default true.
+     */
+    requireToken?: boolean;
+}
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export declare const SHARE_BACKEND_ENV = "AGENTS_SHARE_BACKEND";
+/** URL-safe namespace: lowercase `[a-z0-9-]+`. Matches the Worker's sanitize.
+ *
+ * This is URL-safety, not collision-resistance: two values that differ only
+ * in case or punctuation share a prefix. */
+export declare function sanitizeShareNamespace(s: string): string;
+/**
+ * Public managed-share handle from a verified email.
+ *
+ * `muqsitnawaz@gmail.com` → `muqsitnawaz`. Plus-tags are dropped
+ * (`muqsitnawaz+dev@gmail.com` → `muqsitnawaz`) so the URL stays the
+ * account's default name. Empty / missing email → `''` (caller falls
+ * back to userId). Must match the Worker `handleFromEmail`.
+ */
+export declare function handleFromEmail(email: string | undefined): string;
+/** Managed URL namespace: email handle, else sanitized userId (never empty if either is set). */
+export declare function managedShareHandle(session: Pick<PhoenixSession, 'email' | 'userId'>): string;
+export declare function managedShareBaseUrl(): string;
+/**
+ * True when this config is the platform managed endpoint (`share.agents-cli.sh`).
+ * The deploy path uses this — not "the caller is signed in" — to decide whether
+ * to bind `PHOENIX_ID_BASE` on the Worker.
+ */
+export declare function isManagedShareEndpoint(cfg: {
+    baseUrl?: string;
+    domain?: string;
+}): boolean;
+/**
+ * Phoenix ID URL to bind on a managed Worker deploy. `undefined` for a
+ * pure-BYO Worker (WRITE_TOKEN only). Fail loud if this is a managed deploy
+ * but the base is empty — never skip-set a blank secret.
+ */
+export declare function phoenixIdBaseForDeploy(opts?: {
+    managed?: boolean;
+}, cfg?: {
+    baseUrl?: string;
+    domain?: string;
+}): string | undefined;
+/**
+ * Pick the principal. Signed-in (`readSession() != null`) 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

@@ -0,0 +1,139 @@
+/**
+ * ShareBackend — the token-source seam for `agents artifacts share`.
+ *
+ * Two legitimate principals, picked once at publish time:
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is
+ *     the already-live `share.agents-cli.sh`. Zero Cloudflare setup.
+ *   - **byo**: the existing static WRITE_TOKEN path (`readShareConfig()` +
+ *     `readWriteToken()`). Unchanged for power users / custom domains / fleet
+ *     injection of `SHARE_WRITE_TOKEN`.
+ *
+ * Dispatch is not a fallback: signed-in AND no BYO override → managed;
+ * otherwise BYO. Fail loud when neither principal can authenticate.
+ *
+ * Explicit BYO override (any one is enough):
+ *   - `opts.byo === true`
+ *   - `opts.writeToken` (a caller-supplied static token, including tests)
+ *   - `AGENTS_SHARE_BACKEND=byo`
+ */
+import { PHOENIX_ID_BASE, readSession } from '../identity/client.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';
+/** URL-safe namespace: lowercase `[a-z0-9-]+`. Matches the Worker's sanitize.
+ *
+ * This is URL-safety, not collision-resistance: two values that differ only
+ * in case or punctuation share a prefix. */
+export function sanitizeShareNamespace(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/**
+ * Public managed-share handle from a verified email.
+ *
+ * `muqsitnawaz@gmail.com` → `muqsitnawaz`. Plus-tags are dropped
+ * (`muqsitnawaz+dev@gmail.com` → `muqsitnawaz`) so the URL stays the
+ * account's default name. Empty / missing email → `''` (caller falls
+ * back to userId). Must match the Worker `handleFromEmail`.
+ */
+export function handleFromEmail(email) {
+    if (!email)
+        return '';
+    const local = email.split('@')[0] ?? '';
+    const beforePlus = local.split('+')[0] ?? local;
+    return sanitizeShareNamespace(beforePlus);
+}
+/** Managed URL namespace: email handle, else sanitized userId (never empty if either is set). */
+export function managedShareHandle(session) {
+    return handleFromEmail(session.email) || sanitizeShareNamespace(session.userId ?? '');
+}
+export function managedShareBaseUrl() {
+    return `https://${DEFAULT_SHARE_DOMAIN}`;
+}
+function shareEndpointHost(value) {
+    return value.replace(/^https?:\/\//i, '').replace(/\/+$/, '').toLowerCase();
+}
+/**
+ * True when this config is the platform managed endpoint (`share.agents-cli.sh`).
+ * The deploy path uses this — not "the caller is signed in" — to decide whether
+ * to bind `PHOENIX_ID_BASE` on the Worker.
+ */
+export function isManagedShareEndpoint(cfg) {
+    const managedHost = DEFAULT_SHARE_DOMAIN.toLowerCase();
+    if (cfg.domain && shareEndpointHost(cfg.domain) === managedHost)
+        return true;
+    if (cfg.baseUrl && shareEndpointHost(cfg.baseUrl) === managedHost)
+        return true;
+    return false;
+}
+/**
+ * Phoenix ID URL to bind on a managed Worker deploy. `undefined` for a
+ * pure-BYO Worker (WRITE_TOKEN only). Fail loud if this is a managed deploy
+ * but the base is empty — never skip-set a blank secret.
+ */
+export function phoenixIdBaseForDeploy(opts = {}, cfg) {
+    const managed = opts.managed === true || (cfg != null && isManagedShareEndpoint(cfg));
+    if (!managed)
+        return undefined;
+    const base = PHOENIX_ID_BASE.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+/**
+ * Pick the principal. Signed-in (`readSession() != null`) AND no explicit BYO
+ * override → managed; otherwise BYO.
+ */
+export function shouldUseManaged(opts = {}) {
+    if (opts.byo === true)
+        return false;
+    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;
+}
+export function resolveShareBackend(opts = {}) {
+    if (shouldUseManaged(opts)) {
+        const session = opts.session === undefined ? readSession() : opts.session;
+        if (!session) {
+            throw new Error("Not signed in. Run 'agents auth login'.");
+        }
+        return resolveManagedBackend(session);
+    }
+    return resolveByoBackend(opts);
+}
+function resolveManagedBackend(session) {
+    if (!session.access_token) {
+        throw new Error("Not signed in. Run 'agents auth login'.");
+    }
+    const namespace = managedShareHandle(session);
+    if (!namespace) {
+        throw new Error("Signed in but the session has no email or user id. Run 'agents auth login' again.");
+    }
+    return {
+        kind: 'managed',
+        baseUrl: managedShareBaseUrl(),
+        token: session.access_token,
+        namespace,
+    };
+}
+function resolveByoBackend(opts) {
+    const cfg = opts.config ?? readShareConfig();
+    if (!cfg) {
+        throw new Error("Not set up yet. Run 'agents auth login' to publish on the managed endpoint (zero Cloudflare setup), or 'agents artifacts setup' / 'agents artifacts share join' for your own Cloudflare.");
+    }
+    const token = opts.writeToken ??
+        (opts.requireToken === false ? (readWriteTokenEnv() ?? '') : readWriteToken());
+    // Namespace is the GitHub username. An explicit --github-user is sanitized
+    // here; otherwise publish fills it via resolveShareUsername (gh/git config).
+    const namespace = opts.githubUser ? sanitizeShareNamespace(opts.githubUser) : '';
+    return {
+        kind: 'byo',
+        baseUrl: cfg.baseUrl.replace(/\/+$/, ''),
+        token,
+        namespace,
+    };
+}

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

@@ -68,7 +68,7 @@ export interface DeleteShareOptions {
     /** Skip deleting the target's retained revisions (`<key>/rev-*`, RUSH-2683
      * revision retention) — default: delete them too. A republished-then-deleted
      * share would otherwise leave its prior world-readable versions live for up
-     * to the bucket's lifecycle max-age (see docs/share.md §Revisions). */
+     * to the bucket's lifecycle max-age (see docs/distribution.md). */
     keepRevisions?: boolean;
     /** Treat an already-missing target as a no-op success instead of an error
      * (mirrors SQL's `DROP ... IF EXISTS`). Default: missing target is an error. */
@@ -77,8 +77,12 @@ export interface DeleteShareOptions {
     githubUser?: string;
     /** DI seam for tests — override the persisted share endpoint config. */
     config?: ShareConfig;
-    /** DI seam for tests — override the keychain-backed write token. */
+    /** DI seam for tests — override the keychain-backed write token. Selects BYO. */
     writeToken?: string;
+    /** DI seam for tests — override `readSession()`. `null` means signed out. */
+    session?: import('../identity/client.js').PhoenixSession | null;
+    /** Force the BYO Cloudflare path even when signed in. */
+    byo?: boolean;
     /** DI seam for tests — override the real HTTP DELETE. */
     deleter?: DeleteFn;
     /** DI seam for tests — override the real HTTP existence check. */

package/dist/lib/share/delete.js

@@ -7,7 +7,7 @@
 // returns `{"ok":true}` — so `{"ok":true}` alone is never proof of a takedown.
 // Every delete here is followed by a status check that must observe 404 before
 // the operation is reported as successful.
-import { readShareConfig, readWriteToken } from './config.js';
+import { resolveShareBackend } from './backend.js';
 import { buildShareKey, resolveShareUsername } from './publish.js';
 /**
  * Normalize any of the three accepted target forms to the R2 key that publish
@@ -103,7 +103,7 @@ 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 write token, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the bearer (Phoenix session or WRITE_TOKEN), or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;
@@ -113,13 +113,12 @@ export async function deleteObject(endpoint, key, opts = {}) {
  * are gone. Throws on an unverified takedown — never reports success for an
  * object that still resolves. */
 export async function deleteShare(target, opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    const token = opts.writeToken ?? readWriteToken();
-    const resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
-    const endpoint = { baseUrl: cfg.baseUrl, token };
+    const backend = resolveShareBackend(opts);
+    const githubUser = backend.kind === 'managed'
+        ? backend.namespace
+        : opts.githubUser || backend.namespace || undefined;
+    const resolved = await resolveDeleteTarget(target, { githubUser });
+    const endpoint = { baseUrl: backend.baseUrl, token: backend.token };
     const page = await deleteObject(endpoint, resolved.key, { deleter: opts.deleter, checker: opts.checker });
     if (!page.existedBefore) {
         if (opts.ifExists) {

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

@@ -0,0 +1,22 @@
+/**
+ * Make an HTML page self-contained enough to view on share.agents-cli.sh.
+ *
+ * Chrome "Save as" (and some renderers) leave `file:///…html#section` TOC
+ * links and sibling image paths. Those work on disk and 404 on the share
+ * Worker, which only stores the one PUT body. Rewrite same-document file
+ * anchors to `#section`, and inline local image files as data URIs.
+ *
+ * https citations, data: URIs already in the page, and missing files are
+ * left alone. This is not a bundler — it only fixes what would otherwise
+ * render as a broken page after a single-file publish.
+ */
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export declare const MAX_INLINE_BYTES: number;
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export declare function rewriteFileAnchors(html: string): string;
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export declare function inlineLocalAssets(html: string, htmlPath: string): string;
+export declare function prepareShareHtml(html: string, htmlPath: string): string;

package/dist/lib/share/html.js

@@ -0,0 +1,88 @@
+/**
+ * Make an HTML page self-contained enough to view on share.agents-cli.sh.
+ *
+ * Chrome "Save as" (and some renderers) leave `file:///…html#section` TOC
+ * links and sibling image paths. Those work on disk and 404 on the share
+ * Worker, which only stores the one PUT body. Rewrite same-document file
+ * anchors to `#section`, and inline local image files as data URIs.
+ *
+ * https citations, data: URIs already in the page, and missing files are
+ * left alone. This is not a bundler — it only fixes what would otherwise
+ * render as a broken page after a single-file publish.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Skip inlining a sibling that would bloat the page past a reasonable PUT. */
+export const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+const IMAGE_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+};
+/**
+ * `href="file:///tmp/page.html#purpose"` → `href="#purpose"`.
+ * Bare `file:///tmp/page.html` (no hash) becomes `href="#"`.
+ */
+export function rewriteFileAnchors(html) {
+    return html.replace(/\b(href\s*=\s*["'])file:\/\/[^"'#]*(#[^"']*)?(["'])/gi, (_m, attr, hash, quote) => `${attr}${hash ?? '#'}${quote}`);
+}
+function isRemoteOrSpecial(url) {
+    return (url.startsWith('data:') ||
+        url.startsWith('http://') ||
+        url.startsWith('https://') ||
+        url.startsWith('//') ||
+        url.startsWith('#') ||
+        url.startsWith('mailto:') ||
+        url.startsWith('javascript:') ||
+        url.startsWith('agents:'));
+}
+function localImagePath(url, htmlDir) {
+    if (!url || isRemoteOrSpecial(url))
+        return null;
+    const withoutHash = url.split('#')[0] ?? url;
+    let fsPath;
+    if (withoutHash.startsWith('file:')) {
+        try {
+            fsPath = fileURLToPath(withoutHash);
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        fsPath = resolve(htmlDir, withoutHash);
+    }
+    if (!existsSync(fsPath))
+        return null;
+    const mime = IMAGE_MIME[extname(fsPath).toLowerCase()];
+    if (!mime)
+        return null;
+    return { path: fsPath, mime };
+}
+/** Replace local image src/href with a data URI when the file exists next to the page. */
+export function inlineLocalAssets(html, htmlPath) {
+    const dir = dirname(htmlPath);
+    return html.replace(/\b((?:src|href)\s*=\s*["'])([^"']+)(["'])/gi, (full, pre, url, post) => {
+        const local = localImagePath(url, dir);
+        if (!local)
+            return full;
+        try {
+            const buf = readFileSync(local.path);
+            if (buf.length > MAX_INLINE_BYTES)
+                return full;
+            return `${pre}data:${local.mime};base64,${buf.toString('base64')}${post}`;
+        }
+        catch {
+            return full;
+        }
+    });
+}
+export function prepareShareHtml(html, htmlPath) {
+    return inlineLocalAssets(rewriteFileAnchors(html), htmlPath);
+}

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

@@ -61,6 +61,18 @@ export interface UpdateWorkerResult {
     /** True when the upload was skipped because `previousHash` already matched. */
     skipped: boolean;
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export declare const WORKER_PHOENIX_ID_BASE_SECRET = "PHOENIX_ID_BASE";
+export type UpdateWorkerOpts = ProvisionOptions & {
+    force?: boolean;
+    /**
+     * Phoenix ID base URL to bind as `PHOENIX_ID_BASE` after the script upload.
+     * Pass this for a managed deployment; omit it for a pure-BYO Worker (which
+     * authenticates only via WRITE_TOKEN). An empty string is a caller bug and
+     * fails loud — do not pass a blank to "skip".
+     */
+    phoenixIdBase?: string;
+};
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -78,7 +90,9 @@ export interface UpdateWorkerResult {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -86,9 +100,9 @@ export interface UpdateWorkerResult {
  * re-setting the secret to its own value after every deploy gets the same
  * outcome without depending on an unverified upload-time flag.
  */
-export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: ProvisionOptions & {
-    force?: boolean;
-}): Promise<UpdateWorkerResult>;
+export declare function updateWorker(apiToken: string, accountId: string, workerName: string, bucketName: string, script: string, writeToken: string, previousHash: string | undefined, opts?: UpdateWorkerOpts): Promise<UpdateWorkerResult>;
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export declare function putWorkerSecret(apiToken: string, accountId: string, workerName: string, name: string, text: string, opts?: ProvisionOptions): Promise<void>;
 /** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
 export declare function setWorkerSecret(apiToken: string, accountId: string, workerName: string, writeToken: string, opts?: ProvisionOptions): Promise<void>;
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */

package/dist/lib/share/provision.js

@@ -101,6 +101,8 @@ export async function deployWorker(apiToken, accountId, workerName, script, buck
 export function hashWorkerScript(script) {
     return createHash('sha256').update(script, 'utf8').digest('hex');
 }
+/** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
+export const WORKER_PHOENIX_ID_BASE_SECRET = 'PHOENIX_ID_BASE';
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -118,7 +120,9 @@ export function hashWorkerScript(script) {
  * API right after the upload — the same two-call sequence first-time
  * provisioning already uses (`deployWorker` then `setWorkerSecret`), except
  * `writeToken` here is the caller's EXISTING token, never a freshly generated
- * one. Cloudflare's own docs describe exactly this "secrets survive a
+ * one. A managed deploy also re-applies `PHOENIX_ID_BASE` the same way (the
+ * Worker reads it to verify Phoenix bearers); a pure-BYO deploy omits it.
+ * Cloudflare's own docs describe exactly this "secrets survive a
  * subsequent write" contract for the sibling `wrangler versions upload
  * --secrets-file` flow ("Secrets not included in the file are preserved from
  * the previous version" —
@@ -129,6 +133,13 @@ export function hashWorkerScript(script) {
 export async function updateWorker(apiToken, accountId, workerName, bucketName, script, writeToken, previousHash, opts = {}) {
     const templateHash = hashWorkerScript(script);
     if (!opts.force && previousHash === templateHash) {
+        // Script is current so we skip the upload (which would wipe secrets). A
+        // managed Worker still needs PHOENIX_ID_BASE present — a prior upload from
+        // a CLI that never set it left the secret missing, and this is the heal
+        // that does not require --force or a dummy template bump.
+        if (opts.phoenixIdBase !== undefined) {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
         return { templateHash, skipped: true };
     }
     await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
@@ -143,18 +154,41 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
         const detail = e instanceof Error ? e.message : String(e);
         throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents artifacts share update\` to fix this before publishing/deleting anything. (${detail})`);
     }
+    if (opts.phoenixIdBase !== undefined) {
+        try {
+            await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`Worker deployed but PHOENIX_ID_BASE failed to re-apply — Phoenix-bearer publishes will 401 until you re-run \`agents artifacts share update\`. (${detail})`);
+        }
+    }
     return { templateHash, skipped: false };
 }
-/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
-export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+/** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
+export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;
     await request({
         apiToken,
         method: 'PUT',
         pathname: `/accounts/${accountId}/workers/scripts/${workerName}/secrets`,
-        body: { name: 'WRITE_TOKEN', text: writeToken, type: 'secret_text' },
+        body: { name, text, type: 'secret_text' },
     });
 }
+/** Add/update the WRITE_TOKEN binding using Cloudflare's Workers Secrets API. */
+export async function setWorkerSecret(apiToken, accountId, workerName, writeToken, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, 'WRITE_TOKEN', writeToken, opts);
+}
+function normalizePhoenixIdBase(phoenixIdBase) {
+    const base = phoenixIdBase.replace(/\/+$/, '').trim();
+    if (!base) {
+        throw new Error('Managed share deploy requires a non-empty PHOENIX_ID_BASE so the Worker can verify Phoenix bearers. Set the PHOENIX_ID_BASE env var.');
+    }
+    return base;
+}
+async function applyPhoenixIdBaseSecret(apiToken, accountId, workerName, phoenixIdBase, opts = {}) {
+    await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, normalizePhoenixIdBase(phoenixIdBase), opts);
+}
 /** Enable the free `*.workers.dev` route for the script, and return the account subdomain. */
 export async function enableWorkersDev(apiToken, accountId, workerName, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;