@phnx-labs/agents-cli 1.22.66 → 1.22.69

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;
@@ -24,9 +34,12 @@ export interface PublishOptions {
     /**
      * Server-enforced visibility (RUSH-3135). `public` (default) is listed in
      * the gallery; `unlisted` is a capability URL (GET still 200, X-Robots-Tag:
-     * noindex, hidden from gallery/list). `me` requires a Phoenix session and is
-     * visible only to the signed-in owner; `org` requires the same and is visible
-     * to members of the same Phoenix organization.
+     * noindex, hidden from gallery/list — obscurity, NOT authentication);
+     * `private` is token-gated (the Worker serves it only to a request carrying
+     * the matching viewer key, else 404 — the real read-auth fix, PHNX-3654);
+     * `me` requires a Phoenix session and is visible only to the signed-in owner;
+     * `org` requires the same and is visible to members of the same Phoenix
+     * organization.
      */
     visibility?: ShareVisibility;
     /**
@@ -37,6 +50,14 @@ export interface PublishOptions {
      * not break.
      */
     unlisted?: boolean;
+    /**
+     * Token-gate this page (`--protected` → `visibility=private`, PHNX-3654). The
+     * CLI mints a random viewer token, the Worker stores only its SHA-256 hash,
+     * and the published URL carries `?k=<token>`; a request without a matching
+     * `?k=` / `Authorization: Bearer` gets a `404`. Unlike `unlisted` (obscurity),
+     * this is enforced read-auth. Alias of `--visibility private`.
+     */
+    protected?: boolean;
     /**
      * Bypass the pre-publish sensitive-content scan (emails / credential-shaped
      * strings). Required when the page intentionally carries those patterns.
@@ -91,9 +112,17 @@ export interface PublishOptions {
     /** DI seam for tests — override provenance auto-capture (agent/session/host/repo/date). */
     provenance?: ShareProvenance;
 }
-export type ShareVisibility = 'public' | 'unlisted' | 'me' | 'org';
-/** The visibility levels a share may carry — the Worker's own set, used to
- * validate `--visibility` and `share visibility <target> <level>`. */
+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
+ * NOT in {@link SHARE_VISIBILITY_LEVELS} (the in-place `share visibility <level>`
+ * set). */
+export declare const PUBLISH_VISIBILITY_LEVELS: readonly ShareVisibility[];
+/** 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 declare const SHARE_VISIBILITY_LEVELS: readonly ShareVisibility[];
 export interface PublishResult {
     url: string;
@@ -105,19 +134,46 @@ export interface PublishResult {
     visibility?: ShareVisibility;
     /** True when the page was published with `visibility=unlisted`. */
     unlisted?: boolean;
+    /** The raw viewer token minted for a `private` (token-gated) publish, or
+     * undefined for any other visibility. It rides in {@link url} as `?k=<token>`;
+     * only its hash is stored server-side. Treat as a secret. */
+    viewerToken?: string;
     /** The label stored with this share — explicit (`--label`) or derived. */
     label?: string;
     /** Whether `label` came from `--label` or was auto-derived. */
     labelSource?: 'explicit' | 'derived';
 }
 /**
- * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
- * passes through; otherwise `visibility` (default public).
+ * `--protected` / `{ protected: true }` map to `private` (token-gated — it wins
+ * over `--unlisted` when both are set, being the stronger control); `--unlisted`
+ * maps to `unlisted`; `--visibility private|unlisted|me|org` passes through;
+ * otherwise `visibility` (default public).
  */
 export declare function resolveShareVisibility(opts?: {
     visibility?: ShareVisibility;
     unlisted?: boolean;
+    protected?: boolean;
 }): ShareVisibility;
+/** Mint a fresh random viewer token for a `private` (token-gated) publish. The
+ * raw token rides ONLY in the returned URL's `?k=`; the Worker stores just its
+ * SHA-256 hash, so the object metadata never carries the secret. */
+export declare function generateViewerToken(): string;
+/** SHA-256 hex of a viewer token — the form the Worker also computes and stores,
+ * so a CLI-side preview of the stored hash matches. Exported for tests. */
+export declare function hashViewerToken(token: string): string;
+/** A 64-bit random slug tail (16 lowercase hex chars) for a capability-URL
+ * publish, so the slug can never be derived/guessed from the title (PHNX-3654).
+ * `unlisted` leans on this for obscurity; `private` uses it as defense-in-depth
+ * behind the viewer token. */
+export declare function randomSlugTail(): string;
+/**
+ * The loud stderr warning printed on an `unlisted` / `--private` publish
+ * (PHNX-3654): `unlisted` is obscurity, NOT read-authentication — anyone with
+ * the URL can read it. Points the user at the real controls (`--protected`,
+ * `--expire`, `me`/`org`). Lives here beside the visibility logic; `share.ts`
+ * prints it so the lib layer stays free of `console.*`.
+ */
+export declare function unlistedNotPrivateWarning(): string;
 export interface ShareProvenance {
     /** Harness/agent name (`AGENTS_AGENT_NAME`), when publishing from an agent run. */
     agent?: string;
@@ -136,7 +192,7 @@ export interface ShareProvenance {
  * provenance the CLI sets automatically, plus `expires-at` / `visibility` /
  * `owner` which the Worker stamps itself.
  */
-export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source", "og-title", "og-description", "og-generated", "og-source-etag"];
+export declare const RESERVED_META_KEYS: readonly ["expires-at", "published-at", "visibility", "viewer-token-hash", "owner", "org_domain", "agent", "session", "host", "repo", "date", "avatar", "label", "label-source", "og-title", "og-description", "og-generated", "og-source-etag"];
 /**
  * Auto-capture publish provenance from the exec env, git, and the local clock.
  * Every field is present only when the environment genuinely carries it — a

package/dist/lib/share/publish.js

@@ -9,28 +9,78 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { hostname as osHostname } from 'node:os';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { readSession } from '../identity/client.js';
 import { readShareConfig } from './config.js';
 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 share may carry — the Worker's own set, used to
- * validate `--visibility` and `share visibility <target> <level>`. */
-export const SHARE_VISIBILITY_LEVELS = ['public', 'unlisted', 'me', 'org'];
+/** 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
+ * NOT in {@link SHARE_VISIBILITY_LEVELS} (the in-place `share visibility <level>`
+ * set). */
+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 = EDITABLE_VISIBILITY_LEVELS;
 /**
- * `--unlisted` / `{ unlisted: true }` map to `unlisted`; `--visibility me|org`
- * passes through; otherwise `visibility` (default public).
+ * `--protected` / `{ protected: true }` map to `private` (token-gated — it wins
+ * over `--unlisted` when both are set, being the stronger control); `--unlisted`
+ * maps to `unlisted`; `--visibility private|unlisted|me|org` passes through;
+ * otherwise `visibility` (default public).
  */
 export function resolveShareVisibility(opts = {}) {
-    if (opts.unlisted === true)
-        return 'unlisted';
-    if (opts.visibility === 'unlisted' || 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
+ * capability URL would fall to. */
+const VIEWER_TOKEN_BYTES = 16;
+/** Mint a fresh random viewer token for a `private` (token-gated) publish. The
+ * raw token rides ONLY in the returned URL's `?k=`; the Worker stores just its
+ * SHA-256 hash, so the object metadata never carries the secret. */
+export function generateViewerToken() {
+    return randomBytes(VIEWER_TOKEN_BYTES).toString('base64url');
+}
+/** SHA-256 hex of a viewer token — the form the Worker also computes and stores,
+ * so a CLI-side preview of the stored hash matches. Exported for tests. */
+export function hashViewerToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/** A 64-bit random slug tail (16 lowercase hex chars) for a capability-URL
+ * publish, so the slug can never be derived/guessed from the title (PHNX-3654).
+ * `unlisted` leans on this for obscurity; `private` uses it as defense-in-depth
+ * behind the viewer token. */
+export function randomSlugTail() {
+    return randomBytes(8).toString('hex');
+}
+/**
+ * The loud stderr warning printed on an `unlisted` / `--private` publish
+ * (PHNX-3654): `unlisted` is obscurity, NOT read-authentication — anyone with
+ * the URL can read it. Points the user at the real controls (`--protected`,
+ * `--expire`, `me`/`org`). Lives here beside the visibility logic; `share.ts`
+ * prints it so the lib layer stays free of `console.*`.
+ */
+export function unlistedNotPrivateWarning() {
+    return ('unlisted is NOT private — anyone with the URL can read it (a capability link, ' +
+        'hidden from the gallery and marked noindex, but not authenticated).\n' +
+        '  For sensitive content use --protected (a token-gated link that returns 404 ' +
+        'without the key), and/or --expire to bound the window; --visibility me|org ' +
+        'gates on your Phoenix login.');
 }
 /**
  * Reserved `customMetadata` keys a `--meta key=value` may not target (see
@@ -42,6 +92,7 @@ export const RESERVED_META_KEYS = [
     'expires-at',
     'published-at',
     'visibility',
+    'viewer-token-hash',
     'owner',
     'org_domain',
     'agent',
@@ -516,11 +567,26 @@ export async function publishFile(filePath, opts = {}) {
 export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     const username = await resolveShareUsername(opts);
     let body = readFileSync(filePath);
-    const slugPart = (opts.slug ?? defaultSlug(filePath, body)).replace(/^\/+/, '');
-    const key = buildShareKey(username, slugPart);
     const expiresAt = resolveExpire(opts.expire);
     const visibility = resolveShareVisibility(opts);
     const unlisted = visibility === 'unlisted';
+    // A capability-URL publish (unlisted / token-gated private) must not have a
+    // guessable slug — that was the PHNX-3654 hole. Without an explicit --slug the
+    // slug always carries a 64-bit random tail (a title-derived prefix may lead it,
+    // but the random suffix is what makes the whole URL unguessable); an explicit
+    // --slug is the caller's own choice (e.g. republishing to a known URL) and is
+    // honored verbatim.
+    const capabilityUrl = visibility === 'unlisted' || visibility === 'private';
+    const explicitSlug = typeof opts.slug === 'string' && opts.slug.trim() !== '';
+    const slugPart = (explicitSlug
+        ? opts.slug
+        : capabilityUrl
+            ? `${defaultSlug(filePath, body)}-${randomSlugTail()}`
+            : defaultSlug(filePath, body)).replace(/^\/+/, '');
+    const key = buildShareKey(username, slugPart);
+    // Token-gated read auth (PHNX-3654): mint a random viewer token for a private
+    // publish. Only its hash is sent to the Worker; the raw token rides in ?k=.
+    const viewerToken = visibility === 'private' ? generateViewerToken() : undefined;
     const pageUrl = `${endpoint.baseUrl.replace(/\/+$/, '')}/${key}`;
     const provenance = opts.provenance ?? resolveShareProvenance();
     const avatarUrl = opts.avatar ?? resolveShareAvatar({ session: opts.session });
@@ -528,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);
@@ -598,6 +669,11 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         if (expiresAt)
             h['x-share-expires-at'] = expiresAt;
         h['x-share-visibility'] = visibility;
+        // Token-gated read auth (PHNX-3654): send the RAW viewer token. The Worker
+        // hashes it (SHA-256) and stores only the hash in customMetadata, so the
+        // secret never lands in object metadata. Only present for a private publish.
+        if (viewerToken)
+            h['x-share-viewer-token'] = viewerToken;
         // Two headers per free-text field, backward-compatible by construction
         // (PHNX-2786): `x-share-<field>` always carries the latin1-safe folded value
         // an already-deployed Worker reads verbatim, and — only when the fold is lossy
@@ -675,10 +751,15 @@ 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>.
+    const baseUrl = r.url ?? pageUrl;
+    const url = viewerToken ? `${baseUrl}?k=${encodeURIComponent(viewerToken)}` : baseUrl;
     return {
-        url: r.url ?? pageUrl,
+        url,
         slug: key.slice(key.indexOf('/') + 1),
         expiresAt,
         coverUrl,
@@ -686,5 +767,6 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
         labelSource,
         visibility,
         ...(unlisted ? { unlisted: true } : {}),
+        ...(viewerToken ? { viewerToken } : {}),
     };
 }

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

@@ -137,6 +137,18 @@ export default {
           }
         }
       }
+      // Token-gated read auth (PHNX-3654). A 'private' page is served only to a
+      // request carrying the matching viewer key; we store just its SHA-256 hash
+      // so the secret never lands in R2 metadata. Any write principal (Phoenix or
+      // BYO WRITE_TOKEN) may publish 'private' — the gate is the token, not an
+      // identity, unlike me/org. The token is mandatory: a private page with no
+      // stored hash fails closed on read, so refuse the write instead.
+      let viewerTokenHash = '';
+      if (visibility === 'private') {
+        const rawToken = request.headers.get('x-share-viewer-token') || '';
+        if (!rawToken) return json({ error: 'visibility private requires a viewer token' }, 400);
+        viewerTokenHash = await sha256Hex(rawToken);
+      }
       const segments = path.split('/').filter(Boolean);
       if (auth.kind === 'phoenix') {
         const expected = phoenixHandle(auth);
@@ -225,6 +237,7 @@ export default {
       }
       if (expiresAt) customMetadata['expires-at'] = expiresAt;
       customMetadata['visibility'] = visibility;
+      if (viewerTokenHash) customMetadata['viewer-token-hash'] = viewerTokenHash;
       const owner =
         auth.kind === 'phoenix'
           ? auth.owner
@@ -364,6 +377,11 @@ export default {
         const vis = normalizeVisibility(edit.visibility);
         if (vis.error) return vis.error;
         const visibility = vis.value;
+        // 'private' can't be set via the metadata-edit route: token-gating needs a
+        // fresh viewer key, which only a full publish mints (PHNX-3654). Re-stamping
+        // visibility=private here alone would leave the page gated by a hash that
+        // never got stored — inaccessible to everyone. Fail loud.
+        if (visibility === 'private') return json({ error: 'visibility private must be set at publish time (share --protected)' }, 400);
         if (visibility === 'me' || visibility === 'org') {
           const phoenixBase = typeof env.PHOENIX_ID_BASE === 'string' ? env.PHOENIX_ID_BASE.replace(/\\/+$/, '') : '';
           if (auth.kind !== 'phoenix' || !phoenixBase) return json({ error: 'visibility me/org requires Phoenix identity' }, 400);
@@ -459,23 +477,33 @@ export default {
       // ?revisions=json must not leak that the page exists.
       if (segments.length === 2 && url.searchParams.get('revisions') === 'json') {
         const canonical = await env.BUCKET.get(path);
+        const canonicalVis = canonical ? ((canonical.customMetadata && canonical.customMetadata.visibility) || 'public') : 'public';
         // Only a me/org canonical needs the viewer resolved — and only there does
         // a phoenix_ticket failure gate the response, exactly as before this route
         // shared resolveViewer with the page GET. A public/unlisted revision list
         // never invoked ticket redemption, so a stale ticket must not 401 it.
-        if (canonical && isIdentityGated((canonical.customMetadata && canonical.customMetadata.visibility) || 'public')) {
+        if (canonical && isIdentityGated(canonicalVis)) {
           const viewer = await resolveViewer(request, env, url);
           if (viewer.redirect) return viewer.redirect;
           if (viewer.error) return viewer.error;
           const denied = gateVisibility(url, env, canonical, viewer.identity || null);
           if (denied) return denied;
         }
+        // A private canonical gates its revision list on the viewer key too
+        // (PHNX-3654) — listing session/host/repo of a token-gated page to an
+        // unauthenticated caller would leak the very metadata the gate protects.
+        if (canonical && canonicalVis === 'private') {
+          const viewer = await resolveViewer(request, env, url);
+          if (viewer.redirect) return viewer.redirect;
+          const tokenDenied = await gateTokenRead(request, url, canonical, viewer.identity || null);
+          if (tokenDenied) return tokenDenied;
+        }
         return renderRevisions(
           env.BUCKET,
           url.origin,
           path,
           request.method,
-          canonical && isIdentityGated((canonical.customMetadata && canonical.customMetadata.visibility) || 'public'),
+          !!canonical && (isIdentityGated(canonicalVis) || canonicalVis === 'private'),
         );
       }
 
@@ -498,6 +526,10 @@ export default {
             if (viewer.error && isIdentityGated(pageVisibility)) return viewer.error;
             const denied = gateVisibility(url, env, page, viewer.identity || null);
             if (denied) return denied;
+            // A token-gated page's cover is token-gated too (PHNX-3654): a crawler
+            // fetching <slug>.png without the key gets 404, so no preview leaks.
+            const coverTokenDenied = await gateTokenRead(request, url, page, viewer.identity || null);
+            if (coverTokenDenied) return coverTokenDenied;
 
             if (existingCover && existingCover.customMetadata['og-source-etag'] === page.etag) {
               const current = await env.BUCKET.get(pagePath);
@@ -589,6 +621,12 @@ export default {
       const identity = viewer.identity || null;
       const denied = gateVisibility(url, env, obj, identity);
       if (denied) return denied;
+      // Token-gated read auth (PHNX-3654): a 'private' page is served only to a
+      // request carrying the matching viewer key (?k= or Bearer), or to its owner.
+      // A miss returns 404 — never leaking that the page exists — exactly like a
+      // wrong me/org viewer.
+      const tokenDenied = await gateTokenRead(request, url, obj, identity);
+      if (tokenDenied) return tokenDenied;
       // The owner of the namespace (their handle === the first path segment) gets
       // an interactive visibility control; everyone else keeps the static cue.
       const isOwner = !!identity && handleFromEmail(identity.email) === firstSeg;
@@ -597,7 +635,9 @@ export default {
       obj.writeHttpMetadata(headers);
       headers.set('etag', obj.httpEtag);
       if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8');
-      if (visibility === 'me' || visibility === 'org') {
+      if (visibility === 'me' || visibility === 'org' || visibility === 'private') {
+        // Token-gated + identity-gated reads must never be cached by a shared
+        // proxy, and never indexed.
         headers.set('cache-control', 'private, no-store');
         headers.set('X-Robots-Tag', 'noindex');
       } else {
@@ -647,7 +687,11 @@ export default {
       // without text/html) falls through to raw bytes so embedding is never broken.
       const wantsRaw = url.searchParams.get('raw') != null;
       const kind = viewableAssetKind(ctype);
-      if (!wantsRaw && kind && acceptsHtml(request)) {
+      // A token-gated (private) asset is served as raw bytes, NOT wrapped in the
+      // viewer page (PHNX-3654): the viewer's inner <img src=…?raw> would drop the
+      // ?k= key and 404 (there's no cookie to carry it, unlike me/org), breaking the
+      // media. The gate already passed above, so the raw bytes are safe to serve.
+      if (!wantsRaw && kind && acceptsHtml(request) && visibility !== 'private') {
         const viewerPage = renderAssetViewer(url.pathname, kind, obj.customMetadata || {}, firstSeg, {
           isOwner,
           ownerDomain,
@@ -896,7 +940,7 @@ async function renderRevisions(bucket, origin, key, method, identityGated) {
 // before it ever reaches this Worker; see RESERVED_META_KEYS in publish.ts).
 // One list, reused both to strip a same-named --meta collision on write and
 // to split arbitrary --meta entries back out on read.
-var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source', 'og-title', 'og-description', 'og-generated', 'og-source-etag'];
+var RESERVED_METADATA_KEYS = ['expires-at', 'published-at', 'visibility', 'viewer-token-hash', 'owner', 'org_domain', 'agent', 'session', 'host', 'repo', 'date', 'avatar', 'label', 'label-source', 'og-title', 'og-description', 'og-generated', 'og-source-etag'];
 var PUBLIC_INBOX_DOMAINS = ['gmail.com', 'googlemail.com', 'outlook.com', 'hotmail.com', 'live.com', 'icloud.com', 'me.com'];
 var SHARE_COOKIE = '__Host-phoenix_share';
 var SHARE_COOKIE_MAX_AGE = 604800;
@@ -1025,6 +1069,7 @@ var ASH_OWNER_JS = \`(function(){
 function visibilityChip(visibility, orgDomain) {
   if (visibility === 'me') return { icon: VIS_ICON.me, label: 'Only you', color: '#f59e0b' };
   if (visibility === 'org') return { icon: VIS_ICON.org, label: 'Anyone at ' + escapeHtml(orgDomain || 'your organization'), color: '#5b9dff' };
+  if (visibility === 'private') return { icon: VIS_ICON.me, label: 'Protected (link + key)', color: '#f59e0b' };
   if (visibility === 'unlisted') return { icon: VIS_ICON.unlisted, label: 'Unlisted', color: '#9aa0a6' };
   return { icon: VIS_ICON.public, label: 'Public', color: '#30a46c' };
 }
@@ -1340,8 +1385,8 @@ async function claimHandle(bucket, handle, userId) {
 function normalizeVisibility(raw) {
   const v = (raw || '').trim().toLowerCase();
   if (!v || v === 'public') return { value: 'public' };
-  if (v === 'unlisted' || v === 'me' || v === 'org') return { value: v };
-  return { error: json({ error: 'visibility must be public, unlisted, me, or org' }, 400) };
+  if (v === 'unlisted' || v === 'private' || v === 'me' || v === 'org') return { value: v };
+  return { error: json({ error: 'visibility must be public, unlisted, private, me, or org' }, 400) };
 }
 
 function emailDomain(email) {
@@ -1352,7 +1397,7 @@ function emailDomain(email) {
 }
 
 function isHiddenFromGallery(visibility) {
-  return visibility === 'unlisted' || visibility === 'me' || visibility === 'org';
+  return visibility === 'unlisted' || visibility === 'private' || visibility === 'me' || visibility === 'org';
 }
 
 function isIdentityGated(visibility) {
@@ -1361,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 {
@@ -1384,6 +1433,52 @@ function gateVisibility(url, env, obj, identity) {
   return null;
 }
 
+// SHA-256 hex of a string — the form a 'private' object's stored
+// 'viewer-token-hash' takes. Both the PUT (hash-on-store) and the read gate use
+// this, so a token minted by the CLI matches byte-for-byte (PHNX-3654).
+async function sha256Hex(text) {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(String(text)));
+  return bufToHex(digest);
+}
+
+// The viewer key a reader presents for a token-gated ('private') page: the ?k=
+// query param first (the shape the CLI emits — https://host/<u>/<s>?k=<token>),
+// then an Authorization: Bearer token as an alternative for scripted callers.
+function readViewerKey(request, url) {
+  const q = url.searchParams.get('k');
+  if (q) return q;
+  const bearer = (request.headers.get('authorization') || '').replace(/^Bearer\\s+/i, '');
+  return bearer || '';
+}
+
+// Gate a 'private' (token-gated) read (PHNX-3654). Returns a 404 Response when
+// the request may NOT read, or null when it may. A miss ALWAYS 404s — never a
+// 401 and never a distinct "wrong key" — so a token-gated page never even leaks
+// that it exists, exactly like a wrong me/org viewer. The namespace owner
+// (resolved identity whose userId stamped the object) is let through without the
+// key so 'share open' and the owner's own browsing still work. Constant-time
+// compare (safeEqual) over the stored SHA-256 hash keeps the check timing-safe.
+async function gateTokenRead(request, url, obj, identity) {
+  const meta = obj.customMetadata || {};
+  const visibility = meta.visibility || 'public';
+  if (visibility !== 'private') return null;
+  const notFound = function () {
+    return new Response('not found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  };
+  // Owner bypass: the signed-in owner of the page reads their own private page
+  // without the key (mirrors 'me').
+  if (identity && meta.owner && meta.owner === identity.userId) return null;
+  const stored = meta['viewer-token-hash'] || '';
+  // Fail closed: a private object with no stored hash can never be matched, so it
+  // is unreadable rather than accidentally public.
+  if (!stored) return notFound();
+  const presented = readViewerKey(request, url);
+  if (!presented) return notFound();
+  const presentedHash = await sha256Hex(presented);
+  if (!safeEqual(presentedHash, stored)) return notFound();
+  return null;
+}
+
 // Per-slug view counter, stored as a SEPARATE R2 object under __views/<path> so
 // counting a view never rewrites the page object (which would reset its uploaded
 // timestamp and corrupt "last updated"). Best-effort telemetry: a read/write
@@ -1805,6 +1900,7 @@ async function renderOgCard(input) {
   const visibilityLabels = {
     public: 'PUBLIC',
     unlisted: 'UNLISTED',
+    private: 'PROTECTED',
     me: 'ONLY YOU',
     org: input.orgDomain ? 'ANYONE AT ' + input.orgDomain.toUpperCase() : 'ORGANIZATION',
   };

package/dist/lib/smart-launch.js

@@ -90,15 +90,29 @@ export function formatEmptyAutoPoolError() {
         'mark one with `agents devices role <name> worker`, or widen the pool with `agents config set auto.pool all`.');
 }
 export function formatNoHealthyDeviceError(pool, signals, agent) {
+    let timedOutCount = 0;
     const excluded = pool.map((key) => {
         const signal = signals.get(key);
-        const reason = signal?.reachable !== true
-            ? 'unreachable'
-            : signal.headroom === 'loaded'
+        let reason;
+        if (signal?.reachable === true) {
+            reason = signal.headroom === 'loaded'
                 ? 'overloaded'
                 : signal.installed !== true || signal.signedIn !== true
                     ? 'no ready harness account'
                     : 'ineligible';
+        }
+        else if (signal?.timedOut) {
+            // A slow link is not an offline box. Saying "unreachable" here sent
+            // operators hunting a fleet outage that did not exist (PHNX-3682).
+            timedOutCount++;
+            reason = 'probe timed out';
+        }
+        else if (signal === undefined) {
+            reason = 'no probe signal';
+        }
+        else {
+            reason = 'unreachable';
+        }
         return `${key} (${reason})`;
     }).join(', ');
     const target = agent ? `can run ${agent}` : "for 'run auto'";
@@ -108,7 +122,16 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
     // in this error's own candidate set, not just the ones with a doc.
     const marked = describeAutoPool({ roster: pool });
     const poolNote = marked ? ` [pool: ${marked}]` : '';
-    return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}; earliest window resets unknown`;
+    // Only talk about usage windows when a device was actually turned away for
+    // one. A pool that timed out needs a link/latency hint, not a reset time.
+    const scope = timedOutCount === pool.length
+        ? `every probe (${pool.length}) exceeded`
+        : `${timedOutCount} of ${pool.length} probes exceeded`;
+    const hint = timedOutCount > 0
+        ? `; ${scope} the probe budget — those devices are likely up but slow to answer`
+            + ' (relayed Tailscale paths). Retry, or check `tailscale status` for a direct path.'
+        : '; earliest window resets unknown';
+    return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}${hint}`;
 }
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is

package/dist/lib/ssh-exec.d.ts

@@ -126,6 +126,8 @@ export interface SshExecResult {
     stderr: string;
     timedOut: boolean;
 }
+/** Grace after a timed-out child receives SIGTERM before SIGKILL enforces the bound. */
+export declare const SSH_TIMEOUT_KILL_GRACE_MS = 250;
 /**
  * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
  *