@buildinternet/uploads 0.40.0 → 0.41.0

package/dist/cli-catalog.js

@@ -164,6 +164,10 @@ export const ROOT_COMMANDS = [
         subcommands: [
             { name: "link", summary: "Claim or inspect the repo binding" },
             { name: "doctor", summary: "Check the GitHub App's webhook event subscriptions" },
+            {
+                name: "rotate-prefix",
+                summary: "Rotate a private repo's randomized attachment URL prefix",
+            },
         ],
     },
     {

package/dist/client.d.ts

@@ -256,6 +256,41 @@ export type GithubCommentResult = {
     fixUrl?: string;
     required?: string[];
 };
+/** `POST /v1/workspaces/:workspace/github/private-prefix` request (server contract, issue #631/#613). */
+export interface ResolveGhPrefixOptions {
+    repo: string;
+    branch?: string;
+    target?: {
+        kind: "pull" | "issues";
+        num: number;
+    };
+}
+/** `POST /v1/workspaces/:workspace/github/private-prefix` response (server contract, issue #631/#613). */
+export type ResolveGhPrefixResult = {
+    mode: "plain";
+} | {
+    mode: "private";
+    prefixId: string;
+    activePrefixIds?: string[];
+};
+/** `POST /v1/workspaces/:workspace/github/private-prefix/rotate` request (server contract, issue #631/#613). */
+export interface RotateGhPrefixOptions {
+    repo: string;
+    /** Mutually exclusive with `repoLevel`: rotate one branch's id. */
+    branch?: string;
+    /** Mutually exclusive with `branch`: rotate the repo-level id shared by
+     * issue attachments and ingested assets. */
+    repoLevel?: boolean;
+}
+/** `POST /v1/workspaces/:workspace/github/private-prefix/rotate` response (server contract, issue #631/#613). */
+export type RotateGhPrefixResult = {
+    rotated: false;
+    reason: string;
+} | {
+    rotated: true;
+    prefixId: string;
+    moved: number;
+};
 /** `POST /v1/workspaces/:workspace/github/promote` request/response (server contract, PR #310). */
 export interface PromoteBranchAttachmentsOptions {
     repo: string;
@@ -567,10 +602,12 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
     /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
     patchMetadata(key: string, opts: PatchMetadataOptions): Promise<GetMetadataResult>;
     /**
-     * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
-     * over queryable metadata and/or a case-insensitive filename substring.
-     * At least one of non-empty `filters` or `opts.name` is required.
-     * `filters` must be pre-validated when present (see `metadata.ts`).
+     * `GET /v1/workspaces/:workspace/files/search?meta.<k>=<v>&…&name=…` —
+     * ANDed equality filter over queryable metadata and/or a case-insensitive
+     * filename substring. At least one of non-empty `filters` or `opts.name`
+     * is required. `filters` must be pre-validated when present (see
+     * `metadata.ts`). The canonical search route is non-paginated (server cap
+     * 100, narrowable via `limit`), so `cursor` is always null.
      */
     findFiles(filters?: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
     /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
@@ -606,6 +643,26 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         kind: "pull" | "issues";
         resync?: boolean;
     }): Promise<GithubCommentResult>;
+    /**
+     * Resolve the GitHub-key mode (plain vs. randomized private prefix, issue
+     * #631) a caller should stage/list attachments under for `repo`. Fail-open:
+     * ANY failure — a 404 from an older/self-hosted server, a network error, a
+     * non-2xx response, or a malformed body — resolves to `{ mode: "plain" }`
+     * silently (no stderr noise), never throws. Cached per-process, keyed by
+     * repo+branch+target, so repeated calls for the same coordinate (e.g. the
+     * gh-fallback comment gather re-checking on every sync) cost one request.
+     */
+    resolveGhPrefix(opts: ResolveGhPrefixOptions): Promise<ResolveGhPrefixResult>;
+    /**
+     * Rotate the active private-repo attachment prefix for `opts.repo` +
+     * (`opts.branch` or `opts.repoLevel`) (issue #631). Unlike
+     * `resolveGhPrefix`, this is NOT fail-open: it's an explicit, caller-
+     * initiated action, so a failure (including a 404 from an older/self-
+     * hosted server without this route) throws `UploadsError` — the CLI
+     * command decides how to present that, rather than this method silently
+     * degrading to a shape that would look like success.
+     */
+    rotateGhPrefix(opts: RotateGhPrefixOptions): Promise<RotateGhPrefixResult>;
     /**
      * Promote a workspace's branch-staged attachments into a PR's stable
      * attachment prefix (server contract, PR #310 — degrade-safe callers

package/dist/client.js

@@ -186,13 +186,12 @@ export function mintWorkspaceToken(apiUrl, accessToken, input) {
 function encodeKeyPath(key) {
     return key.split("/").map(encodeURIComponent).join("/");
 }
-// Stays on the legacy `/v1/:workspace/files` wildcard for now (issue #613):
-// the canonical files vertical has no upload PUT, POST /sign, or GET/PATCH
-// /:key metadata yet, and its list/search adopted the session response shape
-// rather than the bearer one. Move this once the canonical vertical grows
-// those routes and the bearer list shape is reconciled.
-function filesBase(config) {
-    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/files`;
+// Canonical files surface (issue #613): every file operation now goes to
+// `/v1/workspaces/:workspace/files`. Per-key ops share handlers with the
+// legacy wildcard (#636); list/find/facets adapt the canonical envelopes in
+// their wrappers below (#613 shape reconciliation).
+function canonicalFilesBase(config) {
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/files`;
 }
 function usageBase(config) {
     return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/usage`;
@@ -311,18 +310,30 @@ export function createUploadsClient(config) {
         if (opts.metadata)
             params.set("metadata", "1");
         const qs = params.toString();
-        const page = await request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        // Canonical list envelope is `{files, prefixes, cursor}` with queryable
+        // metadata always hydrated (issue #613 — the session shape won the
+        // reconciliation). This client keeps its historical `{items, cursor}`
+        // contract: rename the array and honor `opts.metadata` by stripping the
+        // hydrated maps when the caller didn't ask for them.
+        const page = await request("GET", `${canonicalFilesBase(config)}${qs ? `?${qs}` : ""}`);
         return {
-            ...page,
-            items: page.items.map((item) => ({
-                ...item,
-                embedUrl: resolveEmbedUrl(item.url, item.embedUrl),
-            })),
+            cursor: page.cursor,
+            items: page.files.map((item) => {
+                const { metadata, ...rest } = item;
+                return {
+                    ...rest,
+                    ...(opts.metadata && metadata !== undefined ? { metadata } : {}),
+                    embedUrl: resolveEmbedUrl(item.url, item.embedUrl),
+                };
+            }),
         };
     }
     async function getGallery(id) {
         return request("GET", `${galleriesBase(config)}/${encodeURIComponent(id)}`);
     }
+    // Per-process cache for resolveGhPrefix, keyed by repo+branch+target — see
+    // that method's doc.
+    const resolveGhPrefixCache = new Map();
     return {
         async put(body, opts) {
             const key = opts.key ??
@@ -337,7 +348,7 @@ export function createUploadsClient(config) {
             const contentType = opts.contentType ?? inferContentType(opts.filename);
             if (opts.dryRun) {
                 const qs = opts.replace ? "dryRun=1&replace=1" : "dryRun=1";
-                const preview = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}?${qs}`);
+                const preview = await request("PUT", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}?${qs}`);
                 if (preview.url == null) {
                     throw new UploadsError("workspace has no publicBaseUrl (cannot resolve a public URL)", "NO_PUBLIC_URL");
                 }
@@ -369,7 +380,7 @@ export function createUploadsClient(config) {
                         headers[`X-Uploads-Meta-${k}`] = v;
                 }
             }
-            const result = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+            const result = await request("PUT", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`, {
                 body,
                 headers,
             });
@@ -396,24 +407,26 @@ export function createUploadsClient(config) {
             return items;
         },
         async delete(key) {
-            return request("DELETE", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            return request("DELETE", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`);
         },
         /** `GET /v1/:workspace/files/:key?metadata=1` — the object's queryable metadata. */
         async getMetadata(key) {
-            return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}?metadata=1`);
+            return request("GET", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}?metadata=1`);
         },
         /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
         async patchMetadata(key, opts) {
-            return request("PATCH", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+            return request("PATCH", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`, {
                 body: new TextEncoder().encode(JSON.stringify(opts)),
                 headers: { "Content-Type": "application/json" },
             });
         },
         /**
-         * `GET /v1/:workspace/files?meta.<k>=<v>&…&name=…` — ANDed equality filter
-         * over queryable metadata and/or a case-insensitive filename substring.
-         * At least one of non-empty `filters` or `opts.name` is required.
-         * `filters` must be pre-validated when present (see `metadata.ts`).
+         * `GET /v1/workspaces/:workspace/files/search?meta.<k>=<v>&…&name=…` —
+         * ANDed equality filter over queryable metadata and/or a case-insensitive
+         * filename substring. At least one of non-empty `filters` or `opts.name`
+         * is required. `filters` must be pre-validated when present (see
+         * `metadata.ts`). The canonical search route is non-paginated (server cap
+         * 100, narrowable via `limit`), so `cursor` is always null.
          */
         async findFiles(filters = {}, opts = {}) {
             const params = new URLSearchParams();
@@ -425,18 +438,19 @@ export function createUploadsClient(config) {
                 params.set("prefix", opts.prefix);
             if (opts.limit != null)
                 params.set("limit", String(opts.limit));
-            return request("GET", `${filesBase(config)}?${params.toString()}`);
+            const result = await request("GET", `${canonicalFilesBase(config)}/search?${params.toString()}`);
+            return { items: result.items, cursor: null, truncated: result.truncated };
         },
         /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
         async listMetadataKeys() {
-            return request("GET", `${filesBase(config)}/facets`);
+            return request("GET", `${canonicalFilesBase(config)}/facets`);
         },
         /** `GET /v1/:workspace/files/facets?key=` — distinct values for one key. */
         async listMetadataValues(key) {
-            return request("GET", `${filesBase(config)}/facets?${new URLSearchParams({ key })}`);
+            return request("GET", `${canonicalFilesBase(config)}/facets?${new URLSearchParams({ key })}`);
         },
         async head(key) {
-            const result = await request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            const result = await request("GET", `${canonicalFilesBase(config)}/${encodeKeyPath(key)}`);
             return { ...result, embedUrl: resolveEmbedUrl(result.url, result.embedUrl) };
         },
         async createGallery(opts) {
@@ -509,6 +523,53 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Resolve the GitHub-key mode (plain vs. randomized private prefix, issue
+         * #631) a caller should stage/list attachments under for `repo`. Fail-open:
+         * ANY failure — a 404 from an older/self-hosted server, a network error, a
+         * non-2xx response, or a malformed body — resolves to `{ mode: "plain" }`
+         * silently (no stderr noise), never throws. Cached per-process, keyed by
+         * repo+branch+target, so repeated calls for the same coordinate (e.g. the
+         * gh-fallback comment gather re-checking on every sync) cost one request.
+         */
+        async resolveGhPrefix(opts) {
+            const cacheKey = JSON.stringify([
+                opts.repo.toLowerCase(),
+                opts.branch ?? "",
+                opts.target ?? null,
+            ]);
+            const cached = resolveGhPrefixCache.get(cacheKey);
+            if (cached)
+                return cached;
+            const resolved = await (async () => {
+                try {
+                    return await request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/private-prefix`, {
+                        body: new TextEncoder().encode(JSON.stringify(opts)),
+                        headers: { "Content-Type": "application/json" },
+                    });
+                }
+                catch {
+                    return { mode: "plain" };
+                }
+            })();
+            resolveGhPrefixCache.set(cacheKey, resolved);
+            return resolved;
+        },
+        /**
+         * Rotate the active private-repo attachment prefix for `opts.repo` +
+         * (`opts.branch` or `opts.repoLevel`) (issue #631). Unlike
+         * `resolveGhPrefix`, this is NOT fail-open: it's an explicit, caller-
+         * initiated action, so a failure (including a 404 from an older/self-
+         * hosted server without this route) throws `UploadsError` — the CLI
+         * command decides how to present that, rather than this method silently
+         * degrading to a shape that would look like success.
+         */
+        async rotateGhPrefix(opts) {
+            return request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/private-prefix/rotate`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
         /**
          * Promote a workspace's branch-staged attachments into a PR's stable
          * attachment prefix (server contract, PR #310 — degrade-safe callers

package/dist/commands/screenshot.js

@@ -2,12 +2,11 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { extractDashValue, flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, writeReplacedNote, resolveGhPrefixSafe, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
-import { ghBranchAttachmentKey } from "../github.js";
 import { deriveRepoSlugFromGit } from "../keys.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
@@ -448,15 +447,28 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
-    const branchKey = stagingTarget !== undefined
-        ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
-        : undefined;
+    // Resolved once (issue #631), only when it's actually needed for the
+    // upload about to happen (never for the noUpload/no-target bailouts
+    // above) — never per file (screenshot only ever uploads one).
+    const ghPrefix = ghTarget
+        ? await resolveGhPrefixSafe(ctx.client, {
+            repo: ghTarget.repo,
+            target: { kind: ghTarget.kind, num: ghTarget.num },
+        })
+        : stagingTarget !== undefined
+            ? await resolveGhPrefixSafe(ctx.client, {
+                repo: stagingTarget.repo,
+                branch: stagingTarget.branch,
+            })
+            : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, finalPng, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
         ghTarget,
-        key: keyHint ?? branchKey,
+        ghBranchTarget: stagingTarget,
+        ghPrefix,
+        key: keyHint,
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
-import { type PutResult, type UploadsClient } from "./client.js";
+import { type PutResult, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, type UploadsClient } from "./client.js";
 import { type CommandFlags } from "./cli-args.js";
 import { type ResolvedConfig } from "./config.js";
 import { type GhTarget } from "./github.js";
@@ -11,6 +11,42 @@ import type { DetectRoots } from "./screenshot-local.js";
 export declare const UPLOAD_BATCH_CONCURRENCY = 8;
 /** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
 export declare const ATTACH_CONCURRENCY = 8;
+/**
+ * Fail-open wrapper around `client.resolveGhPrefix` (issue #631): resolves to
+ * `{ mode: "plain" }` on ANY failure — an HTTP/network error (already handled
+ * inside `resolveGhPrefix` itself), or a self-hosted/older server or test
+ * double that lacks the method entirely (the outer try/catch here). Never
+ * blocks an upload or a read-back, and never logs — this is not an error.
+ * Call once per command invocation and thread the resolved mode through
+ * (uploadPuts/uploadAttachments/uploadBranchAttachments each do this once
+ * internally, ahead of their per-file loop); `resolveGhPrefix` itself also
+ * caches per-process by repo+branch+target, so repeat callers in the same
+ * process (e.g. attach's promote + comment-sync + upload, all for the same
+ * target) cost one request total.
+ */
+export declare function resolveGhPrefixSafe(client: UploadsClient, opts: ResolveGhPrefixOptions): Promise<ResolveGhPrefixResult>;
+/**
+ * The list of prefixes to fan a multi-prefix list/gather across (issue
+ * #631): the plain prefix plus every active private prefix, if any — a
+ * repo's history can be split across the plain shape and MULTIPLE private
+ * prefixes (e.g. a prefix rotation, or the repo went private after some
+ * files were uploaded), not just the currently-resolved one. Falls back to
+ * `[prefixId]` when the server omits `activePrefixIds` (optional field — an
+ * older/self-hosted worker), so a private repo is never listed as zero
+ * private prefixes. Collapses to `[plainPrefix]` in plain mode, so callers
+ * that special-case a single-prefix array stay byte-identical to pre-#631.
+ */
+export declare function ghListPrefixes(plainPrefix: string, ghPrefix: ResolveGhPrefixResult, privatePrefixFor: (prefixId: string) => string): string[];
+/**
+ * Merge-list helper for a multi-prefix fan-out: runs `fetchItems` per prefix
+ * concurrently and concatenates in prefix order. Encodes the first-prefix-
+ * only cursor rule once — a cursor is opaque and scoped to the prefix it was
+ * minted against, so a multi-prefix merge only ever hands it to the FIRST
+ * prefix; every other prefix always starts from its own beginning (undefined
+ * cursor), or a cursor minted for one prefix's keyspace would get replayed
+ * against a different one.
+ */
+export declare function ghMergedList<T>(prefixes: readonly string[], cursor: string | undefined, fetchItems: (prefix: string, cursor: string | undefined) => Promise<T[]>): Promise<T[]>;
 export { formatUsageHuman } from "./format-usage.js";
 export interface CliContext {
     config: ResolvedConfig;
@@ -90,6 +126,14 @@ export interface UploadPreparedImageOptions {
      * --branch` for the same filename via `ghBranchAttachmentKey`.
      */
     ghBranchTarget?: BranchTarget;
+    /**
+     * Resolved GitHub-key mode (issue #631), from a single upstream
+     * `resolveGhPrefixSafe` call — never resolved here. Passed straight to
+     * `ghAttachmentKeyForMode`/`ghBranchAttachmentKeyForMode`, which own the
+     * plain-vs-private branch. Ignored when neither `ghTarget` nor
+     * `ghBranchTarget` is set.
+     */
+    ghPrefix?: ResolveGhPrefixResult;
     key?: string;
     prefix?: string;
     repo?: string;

package/dist/commands.js

@@ -13,7 +13,7 @@ import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
+import { ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, ghBranchKeyPrefix, ghKeyPrefix, ghPrivateKeyPrefix, ghPrivateBranchKeyPrefix, ghMetadataFromTarget, parseGhKey, parseGhPrivateKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { deriveRepoFromGit, deriveRepoSlugFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -28,6 +28,56 @@ import { colorEnabled, writeCommandHelp } from "./cli-style.js";
 export const UPLOAD_BATCH_CONCURRENCY = 8;
 /** @deprecated Use UPLOAD_BATCH_CONCURRENCY. */
 export const ATTACH_CONCURRENCY = UPLOAD_BATCH_CONCURRENCY;
+/**
+ * Fail-open wrapper around `client.resolveGhPrefix` (issue #631): resolves to
+ * `{ mode: "plain" }` on ANY failure — an HTTP/network error (already handled
+ * inside `resolveGhPrefix` itself), or a self-hosted/older server or test
+ * double that lacks the method entirely (the outer try/catch here). Never
+ * blocks an upload or a read-back, and never logs — this is not an error.
+ * Call once per command invocation and thread the resolved mode through
+ * (uploadPuts/uploadAttachments/uploadBranchAttachments each do this once
+ * internally, ahead of their per-file loop); `resolveGhPrefix` itself also
+ * caches per-process by repo+branch+target, so repeat callers in the same
+ * process (e.g. attach's promote + comment-sync + upload, all for the same
+ * target) cost one request total.
+ */
+export async function resolveGhPrefixSafe(client, opts) {
+    try {
+        return await client.resolveGhPrefix(opts);
+    }
+    catch {
+        return { mode: "plain" };
+    }
+}
+/**
+ * The list of prefixes to fan a multi-prefix list/gather across (issue
+ * #631): the plain prefix plus every active private prefix, if any — a
+ * repo's history can be split across the plain shape and MULTIPLE private
+ * prefixes (e.g. a prefix rotation, or the repo went private after some
+ * files were uploaded), not just the currently-resolved one. Falls back to
+ * `[prefixId]` when the server omits `activePrefixIds` (optional field — an
+ * older/self-hosted worker), so a private repo is never listed as zero
+ * private prefixes. Collapses to `[plainPrefix]` in plain mode, so callers
+ * that special-case a single-prefix array stay byte-identical to pre-#631.
+ */
+export function ghListPrefixes(plainPrefix, ghPrefix, privatePrefixFor) {
+    if (ghPrefix.mode !== "private")
+        return [plainPrefix];
+    return [plainPrefix, ...(ghPrefix.activePrefixIds ?? [ghPrefix.prefixId]).map(privatePrefixFor)];
+}
+/**
+ * Merge-list helper for a multi-prefix fan-out: runs `fetchItems` per prefix
+ * concurrently and concatenates in prefix order. Encodes the first-prefix-
+ * only cursor rule once — a cursor is opaque and scoped to the prefix it was
+ * minted against, so a multi-prefix merge only ever hands it to the FIRST
+ * prefix; every other prefix always starts from its own beginning (undefined
+ * cursor), or a cursor minted for one prefix's keyspace would get replayed
+ * against a different one.
+ */
+export async function ghMergedList(prefixes, cursor, fetchItems) {
+    const pages = await Promise.all(prefixes.map((prefix, i) => fetchItems(prefix, i === 0 ? cursor : undefined)));
+    return pages.flat();
+}
 export { formatUsageHuman } from "./format-usage.js";
 /** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
 export function readFileArg(fileArg) {
@@ -385,10 +435,11 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         frameFit: opts.frame.frameFit,
         optimize: opts.optimize,
     });
+    const ghMode = opts.ghPrefix ?? { mode: "plain" };
     let key = opts.ghTarget
-        ? ghAttachmentKey(opts.ghTarget, prepared.filename)
+        ? ghAttachmentKeyForMode(ghMode, opts.ghTarget, prepared.filename)
         : opts.ghBranchTarget
-            ? ghBranchAttachmentKey(opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
+            ? ghBranchAttachmentKeyForMode(ghMode, opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
             : opts.key;
     if (key && prepared.optimized)
         key = rewriteKeyExtension(key, prepared.filename);
@@ -510,9 +561,21 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
     // always links to the file page and always shows metadata here, matching the
     // defaults. This only diverges from the bot-posted comment for a workspace
     // that both sets one of those flags false and falls through to this path.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target), metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
-        // The list endpoint returns every metadata key; the comment renders only
-        // these two. Narrowing here keeps both render paths byte-identical.
+    //
+    // Also list every active private prefix for this repo (issue #631): a
+    // private repo's attachments can live under a randomized prefix instead of
+    // the plain one. `resolveGhPrefixSafe` is fail-open (any resolve failure,
+    // including a client that lacks the method entirely) — plain-only listing,
+    // silently, matching pre-#631 behavior exactly.
+    const ghPrefix = await resolveGhPrefixSafe(client, {
+        repo: target.repo,
+        target: { kind: target.kind, num: target.num },
+    });
+    const prefixes = ghListPrefixes(ghKeyPrefix(target), ghPrefix, (id) => ghPrivateKeyPrefix(id, target));
+    const items = await ghMergedList(prefixes, undefined, async (prefix) => (await client.listAll({ prefix, metadata: true })).map(({ key, url, embedUrl, pageUrl, metadata }) => {
+        // The list endpoint returns every metadata key; the comment
+        // renders only these two. Narrowing here keeps both render paths
+        // byte-identical.
         const path = metadata?.path;
         const state = metadata?.state;
         return {
@@ -524,7 +587,7 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
                 ? { meta: { ...(path ? { path } : {}), ...(state ? { state } : {}) } }
                 : {}),
         };
-    });
+    }));
     const galleries = [];
     let cursor;
     do {
@@ -791,9 +854,14 @@ async function uploadAttachmentBatch(opts) {
  * original cause of the first failure — for rethrowing single-file CLI paths.
  */
 export async function uploadAttachments(opts) {
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = await resolveGhPrefixSafe(opts.client, {
+        repo: opts.target.repo,
+        target: { kind: opts.target.kind, num: opts.target.num },
+    });
     return uploadAttachmentBatch({
         ...opts,
-        keyFor: (filename) => ghAttachmentKey(opts.target, filename),
+        keyFor: (filename) => ghAttachmentKeyForMode(ghPrefix, opts.target, filename),
     });
 }
 /**
@@ -804,9 +872,14 @@ export async function uploadAttachments(opts) {
  * `syncAttachmentsComment` for a branch target.
  */
 export async function uploadBranchAttachments(opts) {
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = await resolveGhPrefixSafe(opts.client, {
+        repo: opts.target.repo,
+        branch: opts.target.branch,
+    });
     return uploadAttachmentBatch({
         ...opts,
-        keyFor: (filename) => ghBranchAttachmentKey(opts.target.repo, opts.target.branch, filename),
+        keyFor: (filename) => ghBranchAttachmentKeyForMode(ghPrefix, opts.target.repo, opts.target.branch, filename),
     });
 }
 function errorDetail(err) {
@@ -828,6 +901,18 @@ export async function uploadPuts(opts) {
     if (opts.files.length > 1 && opts.nameOverride) {
         throw new UsageError("--name cannot be combined with multiple files");
     }
+    // Resolved once for the whole batch (issue #631) — never per file.
+    const ghPrefix = opts.ghTarget
+        ? await resolveGhPrefixSafe(opts.client, {
+            repo: opts.ghTarget.repo,
+            target: { kind: opts.ghTarget.kind, num: opts.ghTarget.num },
+        })
+        : opts.ghBranchTarget
+            ? await resolveGhPrefixSafe(opts.client, {
+                repo: opts.ghBranchTarget.repo,
+                branch: opts.ghBranchTarget.branch,
+            })
+            : undefined;
     const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
         try {
             const sourceName = opts.nameOverride ??
@@ -845,6 +930,7 @@ export async function uploadPuts(opts) {
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
                 ghBranchTarget: opts.ghBranchTarget,
+                ghPrefix,
                 key: opts.explicitKey,
                 prefix: opts.prefix,
                 repo: opts.repo,
@@ -1447,18 +1533,28 @@ async function resolveStagedBinding(client, repo) {
  */
 export async function resolveStaged(opts) {
     const { client, repo, branch } = opts;
-    const prefix = ghBranchKeyPrefix(repo, branch);
-    const [list, binding] = await Promise.all([
-        client.list({ prefix, metadata: true }),
+    const plainPrefix = ghBranchKeyPrefix(repo, branch);
+    // Also list every active private prefix, if any (issue #631) — mirrors
+    // syncAttachmentsComment's gh-fallback gather above: a repo's staged
+    // history can be split across the plain shape and MULTIPLE private
+    // prefixes (e.g. a prefix rotation, or the repo went private after some
+    // files were staged), not just the currently-resolved one. Fail-open: any
+    // resolve failure degrades to plain-only, byte-identical to pre-#631.
+    const ghPrefix = await resolveGhPrefixSafe(client, { repo, branch });
+    const prefixes = ghListPrefixes(plainPrefix, ghPrefix, (id) => ghPrivateBranchKeyPrefix(id));
+    const [files, binding] = await Promise.all([
+        ghMergedList(prefixes, undefined, async (prefix) => {
+            const list = await client.list({ prefix, metadata: true });
+            return list.items.map((item) => ({
+                key: item.key,
+                filename: item.key.slice(prefix.length),
+                size: item.size,
+                stagedAt: item.metadata?.["gh.staged-at"],
+                url: item.url,
+            }));
+        }),
         resolveStagedBinding(client, repo),
     ]);
-    const files = list.items.map((item) => ({
-        key: item.key,
-        filename: item.key.slice(prefix.length),
-        size: item.size,
-        stagedAt: item.metadata?.["gh.staged-at"],
-        url: item.url,
-    }));
     return { repo, branch, files, binding };
 }
 const STAGED_HELP = `uploads staged [--branch <name>] [--repo <owner/name>] [--format json] [--workspace <name>]
@@ -2236,16 +2332,31 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     const prefixFlag = flagString(parsed.flags, "--prefix");
     let prefix = prefixFlag ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    // Also list every active private prefix, if any (issue #631) — mirrors
+    // syncAttachmentsComment's gh-fallback gather: a repo's attachment
+    // history can be split across the plain shape and MULTIPLE private
+    // prefixes, not just the currently-resolved one. `prefixes` stays
+    // undefined outside --pr/--issue (unchanged behavior); when defined it
+    // collapses to just `[prefix]` in plain mode, so the single-request path
+    // below is byte-identical to pre-#631 output there.
+    let prefixes;
     if (ghTarget) {
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
         prefix = ghKeyPrefix(ghTarget);
+        const ghPrefix = await resolveGhPrefixSafe(ctx.client, {
+            repo: ghTarget.repo,
+            target: { kind: ghTarget.kind, num: ghTarget.num },
+        });
+        prefixes = ghListPrefixes(prefix, ghPrefix, (id) => ghPrivateKeyPrefix(id, ghTarget));
     }
     const limit = flagInt(parsed.flags, "--limit", "--limit");
     const cursor = flagString(parsed.flags, "--cursor");
     if (flagBool(parsed.flags, "--all")) {
         // --all may start from a caller-provided --cursor and drains from there.
-        const items = await ctx.client.listAll({ prefix, limit, cursor });
+        const items = prefixes && prefixes.length > 1
+            ? await ghMergedList(prefixes, cursor, (p, c) => ctx.client.listAll({ prefix: p, limit, cursor: c }))
+            : await ctx.client.listAll({ prefix, limit, cursor });
         if (ctx.json)
             await writeJson({ items, cursor: null });
         else
@@ -2253,7 +2364,16 @@ export async function runList(ctx, args, help = false, run = execRunner) {
                 await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
         return 0;
     }
-    const result = await ctx.client.list({ prefix, limit, cursor });
+    // Merged multi-prefix pages don't have a meaningful combined cursor —
+    // dropped (null) only when there's more than one prefix to merge; the
+    // single-prefix path (every non-private call, plus every call before
+    // #631) is untouched. Same first-prefix-only cursor guard as --all above.
+    const result = prefixes && prefixes.length > 1
+        ? {
+            items: await ghMergedList(prefixes, cursor, async (p, c) => (await ctx.client.list({ prefix: p, limit, cursor: c })).items),
+            cursor: null,
+        }
+        : await ctx.client.list({ prefix, limit, cursor });
     if (ctx.json)
         await writeJson(result);
     else {
@@ -2451,10 +2571,37 @@ const COMMENT_RENDERED_META_KEYS = ["path", "state"];
  * metadata tweak, not an explicit comment command); any failure degrades to
  * a stderr hint instead of failing the metadata write that already landed.
  */
+/**
+ * Resolve the `{repo, kind, num}` target for a key, whether plain
+ * (`parseGhKey`) or private-prefixed (issue #631, `parseGhPrivateKey` —
+ * cannot recover the repo from the key alone, since the randomized prefix
+ * deliberately omits it). For a private key, reads `gh.repo` metadata — the
+ * attach/put that created this key already wrote it — via the same metadata
+ * client call `meta get` uses. Fail-open: any read failure, or a key that
+ * isn't gh-managed at all, resolves to undefined (nothing to resync).
+ */
+async function resolveGhTargetForResync(client, key) {
+    const plain = parseGhKey(key);
+    if (plain)
+        return plain;
+    const priv = parseGhPrivateKey(key);
+    if (!priv)
+        return undefined;
+    try {
+        const { metadata } = await client.getMetadata(key);
+        const repo = metadata["gh.repo"];
+        if (!repo)
+            return undefined;
+        return { repo, kind: priv.kind, num: priv.num };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function resyncCommentAfterMetaSet(ctx, key, touchedKeys) {
     if (!touchedKeys.some((k) => COMMENT_RENDERED_META_KEYS.includes(k)))
         return;
-    const target = parseGhKey(key);
+    const target = await resolveGhTargetForResync(ctx.client, key);
     if (!target)
         return;
     try {
@@ -2614,6 +2761,7 @@ export async function runIngest(ctx, args, help = false, run = execRunner) {
 const GITHUB_HELP = `uploads github link [--repo <owner/name>] [--status] [--workspace <name>]
 uploads github unlink [--repo <owner/name>] [--workspace <name>]
 uploads github doctor [--workspace <name>]
+uploads github rotate-prefix [--repo <owner/name>] [--branch <name> | --repo-level] [--workspace <name>]
 
 Claim, inspect, or release this workspace's binding to a GitHub repo (see the
 managed attachments comment / webhook auto-promotion, which use this
@@ -2635,12 +2783,22 @@ subscription is the classic silent failure: the App's ping stays green
 while webhook auto-promotion and title-cache invalidation quietly do
 nothing.
 
+\`rotate-prefix\` mints a fresh randomized URL prefix for a private repo's
+attachments and moves everything under the old one to it, so the old URLs
+404 at origin immediately (see docs/private-attachments.md). --branch
+defaults to the current git branch; --repo-level rotates the id shared by
+issue attachments and ingested assets instead of a branch's id. Rotation
+is an explicit action — an unauthorized caller gets an error, not a silent
+no-op.
+
 Examples:
   uploads github link
   uploads github link --repo buildinternet/uploads
   uploads github link --status
   uploads github unlink --repo buildinternet/uploads
   uploads github doctor
+  uploads github rotate-prefix --branch feature-x
+  uploads github rotate-prefix --repo-level
 `;
 /** Older servers' health payload predates recommendedEvents/missingRecommendedEvents — treat as no recommendations rather than crashing. */
 function missingRecommendedEventsOf(result) {
@@ -2760,6 +2918,34 @@ async function runGithubUnlink(ctx, repo) {
         : `${repo} was not bound to any workspace — nothing to unlink\n`);
     return 0;
 }
+function formatGithubRotatePrefix(repo, branchLabel, result) {
+    if (!result.rotated) {
+        return `nothing to rotate for ${repo} (${branchLabel}): ${result.reason}\n`;
+    }
+    return `rotated ${repo} (${branchLabel}): moved ${result.moved} object${result.moved === 1 ? "" : "s"} to a new prefix (${result.prefixId})\n`;
+}
+async function runGithubRotatePrefix(ctx, repo, branch, repoLevel) {
+    let result;
+    try {
+        result = await ctx.client.rotateGhPrefix(repoLevel ? { repo, repoLevel: true } : { repo, branch });
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support private-prefix rotation yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        if (err instanceof UploadsError && err.status === 403) {
+            throw new UsageError(`not authorized to rotate ${repo}'s attachment prefix (${err.message})`);
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return result.rotated ? 0 : 1;
+    }
+    const branchLabel = repoLevel ? "repo-level" : (branch ?? "");
+    await writeStdout(formatGithubRotatePrefix(repo, branchLabel, result));
+    return result.rotated ? 0 : 1;
+}
 export async function runGithub(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     const action = parsed.positionals[0];
@@ -2767,14 +2953,24 @@ export async function runGithub(ctx, args, help = false, run = execRunner) {
         writeCommandHelp(GITHUB_HELP);
         return help || parsed.help ? 0 : 2;
     }
-    if (action !== "link" && action !== "unlink" && action !== "doctor") {
-        throw new UsageError(`unknown github subcommand: ${action} (expected link or doctor)`, {
-            example: "uploads github link",
-        });
+    if (action !== "link" &&
+        action !== "unlink" &&
+        action !== "doctor" &&
+        action !== "rotate-prefix") {
+        throw new UsageError(`unknown github subcommand: ${action} (expected link, unlink, doctor, or rotate-prefix)`, { example: "uploads github link" });
     }
     if (action === "doctor")
         return runGithubDoctor(ctx);
     const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    if (action === "rotate-prefix") {
+        const repoLevel = flagBool(parsed.flags, "--repo-level");
+        const branchFlag = flagString(parsed.flags, "--branch");
+        if (repoLevel && branchFlag !== undefined) {
+            throw new UsageError("pass either --branch or --repo-level, not both");
+        }
+        const branch = repoLevel ? undefined : (branchFlag ?? resolveCurrentBranch(run));
+        return runGithubRotatePrefix(ctx, repo, branch, repoLevel);
+    }
     if (action === "unlink")
         return runGithubUnlink(ctx, repo);
     const statusOnly = flagBool(parsed.flags, "--status");

package/dist/github.d.ts

@@ -19,8 +19,47 @@ export declare function normalizeGithubCoordinate(value: string): GithubCoordina
  * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
  * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
  * undefined for any other key shape.
+ *
+ * A real GitHub owner CAN be named `private`, so the strict private-repo
+ * shape (`gh/private/<32-hex-id>/...`, see `parseGhPrivateKey`) is checked
+ * first and rejected here — otherwise a private-prefixed key would
+ * misparse as an ordinary key with owner "private". The accepted ambiguity:
+ * a key whose second segment is NOT 32-lowercase-hex (e.g.
+ * `gh/private/realrepo/pull/5/x.png`) still parses here as owner "private",
+ * repo "private/realrepo" — that's an ordinary public-repo key for a repo
+ * actually named "private", not a private-prefix key.
  */
 export declare function parseGhKey(key: string): GhTarget | undefined;
+/** Literal root under which every private-repo attachment key lives. */
+export declare const GH_PRIVATE_ROOT = "gh/private/";
+/**
+ * Private-repo key prefix: `gh/private/<32-hex-id>/<kind>/<num>/`.
+ * Deliberately omits the repo (unlike `ghKeyPrefix`) — the id is a random,
+ * unguessable per-repo prefix rather than an owner/name path, so callers
+ * that need the repo back must read `gh.repo` metadata (see
+ * `parseGhPrivateKey`, which cannot recover it from the key alone).
+ */
+export declare function ghPrivateKeyPrefix(prefixId: string, target: GhTarget): string;
+/** Private-repo attachment key: `ghPrivateKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateAttachmentKey(prefixId: string, target: GhTarget, filename: string): string;
+/**
+ * Private-repo branch-staged key prefix: `gh/private/<32-hex-id>/branch/`.
+ * Unlike `ghBranchKeyPrefix`, there is deliberately NO branch-name segment —
+ * the branch name itself is not embedded in a private-repo key.
+ */
+export declare function ghPrivateBranchKeyPrefix(prefixId: string): string;
+/** Private-repo branch-staged attachment key: `ghPrivateBranchKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateBranchAttachmentKey(prefixId: string, filename: string): string;
+/**
+ * Inverse of `ghPrivateKeyPrefix`: parse the prefix id/kind/number back out
+ * of a private-repo attachment key, or undefined for any other key shape.
+ * Cannot recover the repo — callers that need it read `gh.repo` metadata.
+ */
+export declare function parseGhPrivateKey(key: string): {
+    prefixId: string;
+    kind: GhTargetKind;
+    num: number;
+} | undefined;
 export declare function ghKeyPrefix(target: GhTarget): string;
 /**
  * Stable attachment key: same filename → same key → same public URL, so
@@ -37,6 +76,29 @@ export declare function ghAttachmentKey(target: GhTarget, filename: string): str
 export declare function ghBranchKeyPrefix(repo: string, branch: string): string;
 /** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
 export declare function ghBranchAttachmentKey(repo: string, branch: string, filename: string): string;
+/**
+ * Structural stand-in for `ResolveGhPrefixResult` (defined in client.ts) —
+ * kept local so these key builders don't need to import client types just
+ * to own the plain-vs-private branch.
+ */
+export type GhKeyMode = {
+    mode: "plain";
+} | {
+    mode: "private";
+    prefixId: string;
+};
+/**
+ * Mode-owning attachment key builder: collapses the
+ * `mode === "private" ? ghPrivateAttachmentKey(...) : ghAttachmentKey(...)`
+ * ternary repeated across call sites into one place.
+ */
+export declare function ghAttachmentKeyForMode(mode: GhKeyMode, target: GhTarget, filename: string): string;
+/**
+ * Mode-owning branch-staged attachment key builder. The private form
+ * ignores `repo`/`branch` (a private-repo key has no branch-name segment,
+ * see `ghPrivateBranchKeyPrefix`) and uses the prefix id instead.
+ */
+export declare function ghBranchAttachmentKeyForMode(mode: GhKeyMode, repo: string, branch: string, filename: string): string;
 /**
  * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
  * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional

package/dist/github.js

@@ -57,14 +57,78 @@ export function normalizeGithubCoordinate(value) {
  * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
  * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
  * undefined for any other key shape.
+ *
+ * A real GitHub owner CAN be named `private`, so the strict private-repo
+ * shape (`gh/private/<32-hex-id>/...`, see `parseGhPrivateKey`) is checked
+ * first and rejected here — otherwise a private-prefixed key would
+ * misparse as an ordinary key with owner "private". The accepted ambiguity:
+ * a key whose second segment is NOT 32-lowercase-hex (e.g.
+ * `gh/private/realrepo/pull/5/x.png`) still parses here as owner "private",
+ * repo "private/realrepo" — that's an ordinary public-repo key for a repo
+ * actually named "private", not a private-prefix key.
  */
 export function parseGhKey(key) {
+    if (parseGhPrivateKey(key))
+        return undefined;
     const match = /^gh\/([^/]+)\/([^/]+)\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
     if (!match)
         return undefined;
     const [, owner, name, kind, num] = match;
     return { repo: `${owner}/${name}`, kind: kind, num: Number(num) };
 }
+/** Literal root under which every private-repo attachment key lives. */
+export const GH_PRIVATE_ROOT = "gh/private/";
+/** Strict shape for a randomized private-repo prefix id: 32 lowercase hex chars. */
+const PRIVATE_PREFIX_ID_RE = /^[0-9a-f]{32}$/;
+/**
+ * Guard every private-key builder against a malformed `prefixId` — a
+ * caller bug here must never silently produce a guessable-ish key.
+ */
+function assertPrivatePrefixId(prefixId) {
+    if (!PRIVATE_PREFIX_ID_RE.test(prefixId)) {
+        throw new Error(`invalid private prefix id: "${prefixId}" must be 32 lowercase hex characters`);
+    }
+}
+/**
+ * Private-repo key prefix: `gh/private/<32-hex-id>/<kind>/<num>/`.
+ * Deliberately omits the repo (unlike `ghKeyPrefix`) — the id is a random,
+ * unguessable per-repo prefix rather than an owner/name path, so callers
+ * that need the repo back must read `gh.repo` metadata (see
+ * `parseGhPrivateKey`, which cannot recover it from the key alone).
+ */
+export function ghPrivateKeyPrefix(prefixId, target) {
+    assertPrivatePrefixId(prefixId);
+    return `${GH_PRIVATE_ROOT}${prefixId}/${target.kind}/${target.num}/`;
+}
+/** Private-repo attachment key: `ghPrivateKeyPrefix` + the sanitized filename. */
+export function ghPrivateAttachmentKey(prefixId, target, filename) {
+    return `${ghPrivateKeyPrefix(prefixId, target)}${sanitizeKeySegment(filename)}`;
+}
+/**
+ * Private-repo branch-staged key prefix: `gh/private/<32-hex-id>/branch/`.
+ * Unlike `ghBranchKeyPrefix`, there is deliberately NO branch-name segment —
+ * the branch name itself is not embedded in a private-repo key.
+ */
+export function ghPrivateBranchKeyPrefix(prefixId) {
+    assertPrivatePrefixId(prefixId);
+    return `${GH_PRIVATE_ROOT}${prefixId}/branch/`;
+}
+/** Private-repo branch-staged attachment key: `ghPrivateBranchKeyPrefix` + the sanitized filename. */
+export function ghPrivateBranchAttachmentKey(prefixId, filename) {
+    return `${ghPrivateBranchKeyPrefix(prefixId)}${sanitizeKeySegment(filename)}`;
+}
+/**
+ * Inverse of `ghPrivateKeyPrefix`: parse the prefix id/kind/number back out
+ * of a private-repo attachment key, or undefined for any other key shape.
+ * Cannot recover the repo — callers that need it read `gh.repo` metadata.
+ */
+export function parseGhPrivateKey(key) {
+    const match = /^gh\/private\/([0-9a-f]{32})\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
+    if (!match)
+        return undefined;
+    const [, prefixId, kind, num] = match;
+    return { prefixId, kind: kind, num: Number(num) };
+}
 export function ghKeyPrefix(target) {
     const [owner, name] = target.repo.split("/");
     return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/${target.kind}/${target.num}/`;
@@ -91,6 +155,26 @@ export function ghBranchKeyPrefix(repo, branch) {
 export function ghBranchAttachmentKey(repo, branch, filename) {
     return `${ghBranchKeyPrefix(repo, branch)}${sanitizeKeySegment(filename)}`;
 }
+/**
+ * Mode-owning attachment key builder: collapses the
+ * `mode === "private" ? ghPrivateAttachmentKey(...) : ghAttachmentKey(...)`
+ * ternary repeated across call sites into one place.
+ */
+export function ghAttachmentKeyForMode(mode, target, filename) {
+    return mode.mode === "private"
+        ? ghPrivateAttachmentKey(mode.prefixId, target, filename)
+        : ghAttachmentKey(target, filename);
+}
+/**
+ * Mode-owning branch-staged attachment key builder. The private form
+ * ignores `repo`/`branch` (a private-repo key has no branch-name segment,
+ * see `ghPrivateBranchKeyPrefix`) and uses the prefix id instead.
+ */
+export function ghBranchAttachmentKeyForMode(mode, repo, branch, filename) {
+    return mode.mode === "private"
+        ? ghPrivateBranchAttachmentKey(mode.prefixId, filename)
+        : ghBranchAttachmentKey(repo, branch, filename);
+}
 /**
  * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
  * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
-export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, } from "./client.js";
+export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -7,7 +7,11 @@ export { UploadsError } from "./errors.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, 
+// Private-repo randomized-prefix builders (issue #631) — needed by the
+// hosted MCP (apps/mcp), which builds keys in-process rather than via
+// the CLI's own commands.ts.
+GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, } from "./github-gh.js";

package/dist/mcp/tools.js

@@ -1,9 +1,9 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, mergeStagingMeta, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveGhPrefixSafe, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghBranchAttachmentKey, ghKeyPrefix } from "../github.js";
+import { ghKeyPrefix, ghPrivateKeyPrefix } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { deriveRepoSlugFromGit } from "../keys.js";
 import { validateMetaMap } from "../metadata.js";
@@ -801,14 +801,26 @@ export function createUploadsMcpTools(opts) {
                     }
                     throw err;
                 }
-                const branchKey = stagingTarget
-                    ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
-                    : undefined;
+                // Resolved once (issue #631), only now that upload is actually
+                // about to happen — never per file (screenshot uploads exactly one).
+                const ghPrefix = target
+                    ? await resolveGhPrefixSafe(client, {
+                        repo: target.repo,
+                        target: { kind: target.kind, num: target.num },
+                    })
+                    : stagingTarget
+                        ? await resolveGhPrefixSafe(client, {
+                            repo: stagingTarget.repo,
+                            branch: stagingTarget.branch,
+                        })
+                        : undefined;
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
                     ghTarget: target,
-                    key: keyArg ?? branchKey,
+                    ghBranchTarget: stagingTarget,
+                    ghPrefix,
+                    key: keyArg,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
@@ -980,16 +992,35 @@ export function createUploadsMcpTools(opts) {
                 const prefixArg = optString(args, "prefix");
                 let prefix = prefixArg ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
                 const target = ghTargetFromArgs(args, run);
+                const { client } = clientFor(args);
+                // Also list every active private prefix, if any (issue #631) —
+                // mirrors syncAttachmentsComment's gh-fallback gather: a repo's
+                // attachment history can be split across the plain shape and
+                // MULTIPLE private prefixes, not just the currently-resolved one.
+                // `prefixes` stays undefined outside pr/issue (unchanged behavior);
+                // collapses to `[prefix]` in plain mode, so the single-request path
+                // below is byte-identical to pre-#631.
+                let prefixes;
                 if (target) {
                     if (prefixArg)
                         usage("prefix cannot be combined with pr/issue");
                     prefix = ghKeyPrefix(target);
+                    const ghPrefix = await resolveGhPrefixSafe(client, {
+                        repo: target.repo,
+                        target: { kind: target.kind, num: target.num },
+                    });
+                    prefixes = ghListPrefixes(prefix, ghPrefix, (id) => ghPrivateKeyPrefix(id, target));
                 }
                 const limit = optPosInt(args, "limit");
                 const cursor = optString(args, "cursor");
-                const { client } = clientFor(args);
                 if (optBool(args, "all")) {
-                    const items = await client.listAll({ prefix, limit, cursor });
+                    const items = prefixes && prefixes.length > 1
+                        ? await ghMergedList(prefixes, cursor, (p, c) => client.listAll({ prefix: p, limit, cursor: c }))
+                        : await client.listAll({ prefix, limit, cursor });
+                    return { items, cursor: null };
+                }
+                if (prefixes && prefixes.length > 1) {
+                    const items = await ghMergedList(prefixes, cursor, async (p, c) => (await client.list({ prefix: p, limit, cursor: c })).items);
                     return { items, cursor: null };
                 }
                 return client.list({ prefix, limit, cursor });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,