@buildinternet/uploads 0.50.1 → 0.51.0

package/dist/client.d.ts

@@ -326,6 +326,22 @@ export interface PromoteSkip {
 export interface PromoteBranchAttachmentsResult {
     promoted: string[];
     skipped: PromoteSkip[];
+    /** Branch-name lineage the sweep covered, current name first (issue #920).
+     * Present only when the branch was renamed at least once. */
+    lineage?: string[];
+}
+/** `POST /v1/workspaces/:workspace/github/branch-rename` request (server contract, issue #920). */
+export interface RegisterBranchRenameOptions {
+    repo: string;
+    /** Previous branch name (`git branch -m <from> <to>`). */
+    from: string;
+    /** Name the branch was renamed to. */
+    to: string;
+}
+/** `POST /v1/workspaces/:workspace/github/branch-rename` response. `recorded:
+ * false` means the pair was already known (or the server has no such route). */
+export interface RegisterBranchRenameResult {
+    recorded: boolean;
 }
 /**
  * `POST /v1/workspaces/:workspace/github/attach` request/response (server
@@ -758,6 +774,15 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * that doesn't have this route yet, as "nothing promoted").
      */
     promoteBranchAttachments(opts: PromoteBranchAttachmentsOptions): Promise<PromoteBranchAttachmentsResult>;
+    /**
+     * Record one `git branch -m` step so promote sweeps the branch's whole
+     * name lineage (issue #920). Degrade-safe on the one failure that is
+     * expected in the wild: a 404 from an older/self-hosted worker without
+     * this route collapses to `{ recorded: false }` — nothing recorded, same
+     * as `promoteBranchAttachments`' callers treat a missing route. Other
+     * failures throw; the CLI's `registerRenamesBestEffort` swallows those.
+     */
+    registerBranchRename(opts: RegisterBranchRenameOptions): Promise<RegisterBranchRenameResult>;
     /**
      * Attach an already-uploaded object to a PR/issue via a server-side copy
      * (issue #702) — see `AttachExistingOptions`. Throws `UploadsError` on

package/dist/client.js

@@ -724,6 +724,27 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Record one `git branch -m` step so promote sweeps the branch's whole
+         * name lineage (issue #920). Degrade-safe on the one failure that is
+         * expected in the wild: a 404 from an older/self-hosted worker without
+         * this route collapses to `{ recorded: false }` — nothing recorded, same
+         * as `promoteBranchAttachments`' callers treat a missing route. Other
+         * failures throw; the CLI's `registerRenamesBestEffort` swallows those.
+         */
+        async registerBranchRename(opts) {
+            try {
+                return await request("POST", `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/github/branch-rename`, {
+                    body: new TextEncoder().encode(JSON.stringify(opts)),
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            catch (err) {
+                if (err instanceof UploadsError && err.status === 404)
+                    return { recorded: false };
+                throw err;
+            }
+        },
         /**
          * Attach an already-uploaded object to a PR/issue via a server-side copy
          * (issue #702) — see `AttachExistingOptions`. Throws `UploadsError` on

package/dist/commands/screenshot.js

@@ -2,7 +2,7 @@ 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, resolveGhPrefixSafe, resolveAutoPrTarget, resolvePutNudgeContext, putNudgeText, autoPrNoteText, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, registerRenamesBestEffort, writeReplacedNote, resolveGhPrefixSafe, resolveAutoPrTarget, resolvePutNudgeContext, putNudgeText, autoPrNoteText, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -351,7 +351,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // maps to exactly one open PR behaves as if --pr <n> had been passed —
     // stable key + managed comment sync — instead of the #469 auto-staging
     // default below. Mirrors put's #700 handling exactly (resolveAutoPrTarget).
-    const autoPrTarget = ghTarget || branchArg !== undefined
+    const autoPrMatch = ghTarget || branchArg !== undefined
         ? undefined
         : resolveAutoPrTarget({
             ghTarget,
@@ -365,6 +365,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
             repoArg: flagString(parsed.flags, "--repo") ?? putDefaults.repo,
             run,
         });
+    const autoPrTarget = autoPrMatch?.target;
     const effectiveGhTarget = ghTarget ?? autoPrTarget;
     // Auto branch staging (issue #469 lever 1): mirrors bare `put`'s auto-staging
     // (issue #403). When no --branch/--pr/--issue/--key/--ref/--prefix/--destination
@@ -428,9 +429,23 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     if (effectiveGhTarget) {
         metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(effectiveGhTarget, run) };
         validateMetaMap(metadata);
+        // The #700 auto-PR match suppresses staging, so the staging branch below
+        // never runs — but this capture still comes from a branch that may have
+        // been renamed while files were staged under the old name. Register the
+        // lineage here too (issue #920), reusing the branch the match already
+        // resolved. Only for the auto-PR match: an explicit --pr/--issue names
+        // no branch of its own.
+        if (autoPrMatch && !dryRun && !noUpload) {
+            await registerRenamesBestEffort(ctx.client, run, autoPrMatch.target.repo, autoPrMatch.branch);
+        }
     }
     else if (stagingTarget !== undefined) {
         metadata = mergeStagingMeta(withFacts, stagingTarget);
+        // Same rename registration as `put`/`attach --branch` staging (issue
+        // #920): best-effort, never fails the capture.
+        if (!dryRun && !noUpload) {
+            await registerRenamesBestEffort(ctx.client, run, stagingTarget.repo, stagingTarget.branch);
+        }
     }
     else if (Object.keys(withFacts).length > 0) {
         validateMetaMap(withFacts);

package/dist/commands.d.ts

@@ -394,6 +394,23 @@ export declare function uploadPuts(opts: {
     width?: number;
     concurrency?: number;
 }): Promise<UploadBatchResult<PutUploadItem>>;
+/**
+ * Best-effort branch-rename registration (issue #920): reads this branch's
+ * reflog for `git branch -m` steps and tells the server about each one, so a
+ * later promote sweeps the branch's whole name lineage instead of only its
+ * current name. No-op when the reflog has no rename (the common case) and
+ * when the client predates the route. Every failure is swallowed — this runs
+ * alongside staging and promote, and must never fail either. Set
+ * `UPLOADS_DEBUG=1` to see what was skipped.
+ *
+ * `opts.explicit` marks a branch the user named themselves (`--from-branch`
+ * / the MCP `fromBranch` argument): that is the manual escape hatch (PR
+ * #919), and its lineage belongs to a different name than the one we are
+ * standing on, so nothing is registered for it.
+ */
+export declare function registerRenamesBestEffort(client: UploadsClient, run: CommandRunner, repo: string, branch: string, opts?: {
+    explicit?: boolean;
+}): Promise<void>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 /**
  * One source of truth for the "staged, but not going to auto-attach" advisory
@@ -465,6 +482,11 @@ export declare function resolvePutNudgeContext(opts: {
     branch: string;
     pr: number | undefined;
 } | undefined;
+/** A #700 auto-PR match: the PR the current branch maps to, plus that branch. */
+export interface AutoPrMatch {
+    target: GhTarget;
+    branch: string;
+}
 /**
  * Auto-PR context (issue #700): when a bare put/screenshot has no explicit
  * destination flag at all (`--pr`/`--issue`/`--key`/`--ref`/`--prefix`/
@@ -481,6 +503,10 @@ export declare function resolvePutNudgeContext(opts: {
  * default branch, or with `--no-git`; any failure (not a repo, detached
  * HEAD, gh missing/unauthenticated/timed out, no open PR) degrades to
  * undefined so the caller falls back to its normal staging/dated behavior.
+ *
+ * The match carries the `branch` it was resolved from, so callers that need
+ * the current branch (the #920 rename registration) reuse it instead of
+ * spawning `git rev-parse` a second time.
  */
 export declare function resolveAutoPrTarget(opts: {
     ghTarget: GhTarget | undefined;
@@ -495,7 +521,7 @@ export declare function resolveAutoPrTarget(opts: {
     noAutoPr: boolean;
     repoArg: string | undefined;
     run: CommandRunner;
-}): GhTarget | undefined;
+}): AutoPrMatch | undefined;
 /**
  * Bare-put branch-staging trigger (issue #403): put on a non-default git
  * branch stages to the branch prefix by default — the branch becomes the

package/dist/commands.js

@@ -15,7 +15,7 @@ import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.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, hasLinkCandidate, extractCandidateUrls, fetchAdoptionCandidateText, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveCurrentBranchSafe, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, hasLinkCandidate, extractCandidateUrls, fetchAdoptionCandidateText, renameLineageFromReflog, } from "./github-gh.js";
 import { deriveRepoFromGit, deriveRepoSlugFromGit } from "./keys.js";
 import { noProjectContextNudge } from "./project-context-nudge.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -809,11 +809,13 @@ takes effect with zero files and cannot combine with --branch/--issue/
 --no-promote. Promotion never applies to issues. Staged files stay findable
 with "uploads find gh.branch=<branch>" either way.
 
-If the branch was renamed or deleted before the PR opened, pass
-"--from-branch <old-name>" with "--pr <num>". With no file arguments, this
-promotes the stale branch prefix and refreshes the managed comment. With file
-or existing-key arguments, it promotes the stale prefix before the normal
-attach flow.
+A branch renamed with "git branch -m" is followed automatically: the rename
+is read from the branch reflog and registered, so promotion sweeps the older
+names too. That needs one uploads run after the rename. If the branch was
+renamed without one, or was deleted, pass "--from-branch <old-name>" with
+"--pr <num>". With no file arguments, this promotes the stale branch prefix
+and refreshes the managed comment. With file or existing-key arguments, it
+promotes the stale prefix before the normal attach flow.
 
 Options:
   --pr <num>            Attach to this pull request
@@ -1174,6 +1176,45 @@ export async function uploadPuts(opts) {
     }
     return { uploads, failures, firstError, sentMetadata };
 }
+/**
+ * Best-effort branch-rename registration (issue #920): reads this branch's
+ * reflog for `git branch -m` steps and tells the server about each one, so a
+ * later promote sweeps the branch's whole name lineage instead of only its
+ * current name. No-op when the reflog has no rename (the common case) and
+ * when the client predates the route. Every failure is swallowed — this runs
+ * alongside staging and promote, and must never fail either. Set
+ * `UPLOADS_DEBUG=1` to see what was skipped.
+ *
+ * `opts.explicit` marks a branch the user named themselves (`--from-branch`
+ * / the MCP `fromBranch` argument): that is the manual escape hatch (PR
+ * #919), and its lineage belongs to a different name than the one we are
+ * standing on, so nothing is registered for it.
+ */
+export async function registerRenamesBestEffort(client, run, repo, branch, opts = {}) {
+    if (opts.explicit)
+        return;
+    let lineage;
+    try {
+        lineage = renameLineageFromReflog(run, branch);
+    }
+    catch {
+        return;
+    }
+    if (lineage.length === 0)
+        return;
+    for (const step of lineage) {
+        try {
+            await client.registerBranchRename({ repo, from: step.from, to: step.to });
+        }
+        catch (err) {
+            if (process.env.UPLOADS_DEBUG === "1") {
+                const detail = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`debug: could not register branch rename ${step.from} -> ${step.to}: ${detail}\n`);
+            }
+            return; // one failure means the route is unavailable; don't retry the rest
+        }
+    }
+}
 /**
  * Best-effort call to `POST /v1/workspaces/:workspace/github/promote` (server contract,
  * PR #310). Degrade-safe like `syncAttachmentsComment`'s bot path: an older
@@ -1189,11 +1230,20 @@ async function attemptPromoteBranch(client, target, branch) {
         return undefined;
     }
 }
-/** Human-mode note for a promotion that actually promoted something. */
+/**
+ * Human-mode note(s) for a promotion that actually promoted something. When
+ * the server-side sweep followed a rename it adds a second line naming the
+ * older branch names (issue #920): `lineage` is current-name-first, so the
+ * older names are its tail.
+ */
 function promotionNote(promotion, branch) {
     const n = promotion.promoted.length;
     const branchSuffix = branch ? ` from branch ${branch}` : "";
-    return `>> promoted ${n} staged attachment${n === 1 ? "" : "s"}${branchSuffix}\n`;
+    const promoted = `>> promoted ${n} staged attachment${n === 1 ? "" : "s"}${branchSuffix}\n`;
+    const older = (promotion.lineage ?? []).slice(1);
+    if (older.length === 0)
+        return promoted;
+    return `${promoted}>> followed rename from ${older.join(", ")}\n`;
 }
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -1344,16 +1394,11 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     let promotion;
     let promotedBranch;
     if (target.kind === "pull" && !parsed.flags.has("--no-promote")) {
-        promotedBranch = fromBranch;
-        if (promotedBranch === undefined) {
-            try {
-                promotedBranch = resolveCurrentBranch(run);
-            }
-            catch {
-                promotedBranch = undefined;
-            }
-        }
+        promotedBranch = fromBranch ?? resolveCurrentBranchSafe(run);
         if (promotedBranch !== undefined) {
+            await registerRenamesBestEffort(ctx.client, run, target.repo, promotedBranch, {
+                explicit: fromBranch !== undefined,
+            });
             promotion = await attemptPromoteBranch(ctx.client, target, promotedBranch);
         }
     }
@@ -1449,6 +1494,9 @@ async function runAttachBranch(ctx, parsed, branch, run) {
         process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"} (staged for branch ${branch})\n`);
     }
     const target = { repo, branch };
+    // Register any `git branch -m` steps behind this name (issue #920) so the
+    // promote that runs when the PR opens sweeps the older names too.
+    await registerRenamesBestEffort(ctx.client, run, repo, branch);
     const { uploads, failures, firstError } = await uploadBranchAttachments({
         client: ctx.client,
         target,
@@ -1567,7 +1615,11 @@ async function runAttachPromoteOnly(ctx, parsed, run) {
     if (target.kind !== "pull") {
         throw new UsageError("--from-branch only promotes into a pull request");
     }
-    const branch = flagString(parsed.flags, "--from-branch") ?? resolveCurrentBranch(run);
+    const explicitFromBranch = flagString(parsed.flags, "--from-branch");
+    const branch = explicitFromBranch ?? resolveCurrentBranch(run);
+    await registerRenamesBestEffort(ctx.client, run, target.repo, branch, {
+        explicit: explicitFromBranch !== undefined,
+    });
     const promotion = await attemptPromoteBranch(ctx.client, target, branch);
     let comment;
     let commentError;
@@ -1656,13 +1708,9 @@ export function resolvePutNudgeContext(opts) {
     try {
         if (deriveRepoFromGit(run) === undefined)
             return undefined; // not a (usable) git repo
-        let branch;
-        try {
-            branch = resolveCurrentBranch(run);
-        }
-        catch {
+        const branch = resolveCurrentBranchSafe(run);
+        if (branch === undefined)
             return undefined; // detached HEAD, or git unavailable
-        }
         const defaultBranch = resolveDefaultBranch(run);
         const onDefaultBranch = defaultBranch
             ? branch === defaultBranch
@@ -1704,6 +1752,10 @@ export function resolvePutNudgeContext(opts) {
  * default branch, or with `--no-git`; any failure (not a repo, detached
  * HEAD, gh missing/unauthenticated/timed out, no open PR) degrades to
  * undefined so the caller falls back to its normal staging/dated behavior.
+ *
+ * The match carries the `branch` it was resolved from, so callers that need
+ * the current branch (the #920 rename registration) reuse it instead of
+ * spawning `git rev-parse` a second time.
  */
 export function resolveAutoPrTarget(opts) {
     const { ghTarget, keyHint, refArg, prefixArg, destinationArg, branchArg, noGit, noAutoPr, repoArg, run, } = opts;
@@ -1716,13 +1768,9 @@ export function resolveAutoPrTarget(opts) {
     try {
         if (deriveRepoFromGit(run) === undefined)
             return undefined; // not a (usable) git repo
-        let branch;
-        try {
-            branch = resolveCurrentBranch(run);
-        }
-        catch {
+        const branch = resolveCurrentBranchSafe(run);
+        if (branch === undefined)
             return undefined; // detached HEAD, or git unavailable
-        }
         const defaultBranch = resolveDefaultBranch(run);
         const onDefaultBranch = defaultBranch
             ? branch === defaultBranch
@@ -1733,7 +1781,7 @@ export function resolveAutoPrTarget(opts) {
         // this must never be felt as a hang.
         const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
         const repo = resolveRepo(repoArg, timed);
-        return resolveCurrentPullRequest(repo, timed);
+        return { target: resolveCurrentPullRequest(repo, timed), branch };
     }
     catch {
         return undefined; // gh/git unavailable, no open PR, or repo unresolvable
@@ -1766,13 +1814,9 @@ export function resolvePutStagingTarget(opts) {
     try {
         if (deriveRepoFromGit(run) === undefined)
             return undefined; // not a (usable) git repo
-        let branch;
-        try {
-            branch = resolveCurrentBranch(run);
-        }
-        catch {
+        const branch = resolveCurrentBranchSafe(run);
+        if (branch === undefined)
             return undefined; // detached HEAD, or git unavailable
-        }
         const defaultBranch = resolveDefaultBranch(run);
         const onDefaultBranch = defaultBranch
             ? branch === defaultBranch
@@ -1993,7 +2037,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     // resolveAutoPrTarget. Supersedes both the #403 staging default and the
     // #393 nudge for this case; computed before the gh.* metadata resolution
     // below since it takes over that resolution entirely.
-    const autoPrTarget = ghTarget
+    const autoPrMatch = ghTarget
         ? undefined
         : resolveAutoPrTarget({
             ghTarget,
@@ -2006,6 +2050,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             repoArg: flagString(parsed.flags, "--repo") ?? defaults.repo,
             run,
         });
+    const autoPrTarget = autoPrMatch?.target;
     const effectiveGhTarget = ghTarget ?? autoPrTarget;
     // Comment sync runs by default with --pr/--issue (matches `attach`); opt
     // out with --no-comment. --comment is accepted as a redundant no-op for
@@ -2137,9 +2182,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         validateMetaMap(merged); // enforce 24-key/8KB caps on the merged map (matches attach)
         metadata = merged;
         attachedRef = merged["gh.ref"];
+        // Auto-PR (#700) suppresses staging, so the staging branch below never
+        // runs — but this put still comes from a branch that may have been
+        // renamed while files were staged under the old name. Register the
+        // lineage here too (issue #920), reusing the branch the match already
+        // resolved. Only for the auto-PR match: an explicit --pr/--issue names
+        // no branch of its own.
+        if (autoPrMatch && !dryRun) {
+            await registerRenamesBestEffort(ctx.client, run, autoPrMatch.target.repo, autoPrMatch.branch);
+        }
     }
     else if (stagingTarget) {
         metadata = mergeStagingMeta(userMeta, stagingTarget);
+        // Branch staging: register any rename behind this name (issue #920) so
+        // the PR-time promote finds files staged under the older names too.
+        if (!dryRun) {
+            await registerRenamesBestEffort(ctx.client, run, stagingTarget.repo, stagingTarget.branch);
+        }
     }
     else {
         // gh.* additionally needs git, which the shared derived gate ignores.

package/dist/github-gh.d.ts

@@ -19,6 +19,31 @@ export declare function resolveRepo(explicit: string | undefined, run?: CommandR
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
 /** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
 export declare function resolveCurrentBranch(run?: CommandRunner): string;
+/**
+ * `resolveCurrentBranch` for best-effort callers: undefined instead of a
+ * throw when the branch can't be determined (detached HEAD, not a git repo,
+ * git unavailable). Use it wherever a missing branch means "skip this step",
+ * not "fail the command".
+ */
+export declare function resolveCurrentBranchSafe(run?: CommandRunner): string | undefined;
+/** One `git branch -m` step read out of a branch's reflog: `from` was renamed to `to`. */
+export interface BranchRenameStep {
+    from: string;
+    to: string;
+}
+/**
+ * Rename lineage for `branch`, read from its own reflog (issue #920). `git
+ * branch -m old new` writes `Branch: renamed refs/heads/old to
+ * refs/heads/new` into the NEW branch's reflog, and chained renames
+ * accumulate there, newest entry first — so the parsed pairs are reversed
+ * into oldest-first order, which is the order the server wants them
+ * registered.
+ *
+ * Best-effort by construction: any git failure (not a repo, no reflog for
+ * the branch, git missing) and any non-rename reflog line yield an empty
+ * array. Callers must treat "no lineage" as the normal case.
+ */
+export declare function renameLineageFromReflog(run?: CommandRunner, branch?: string): BranchRenameStep[];
 /**
  * Best-effort default-branch name via the local `origin/HEAD` ref (no
  * network call — just reads the ref git already cached from the last

package/dist/github-gh.js

@@ -114,6 +114,55 @@ export function resolveCurrentBranch(run = execRunner) {
     }
     return branch;
 }
+/**
+ * `resolveCurrentBranch` for best-effort callers: undefined instead of a
+ * throw when the branch can't be determined (detached HEAD, not a git repo,
+ * git unavailable). Use it wherever a missing branch means "skip this step",
+ * not "fail the command".
+ */
+export function resolveCurrentBranchSafe(run = execRunner) {
+    try {
+        return resolveCurrentBranch(run);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Rename lineage for `branch`, read from its own reflog (issue #920). `git
+ * branch -m old new` writes `Branch: renamed refs/heads/old to
+ * refs/heads/new` into the NEW branch's reflog, and chained renames
+ * accumulate there, newest entry first — so the parsed pairs are reversed
+ * into oldest-first order, which is the order the server wants them
+ * registered.
+ *
+ * Best-effort by construction: any git failure (not a repo, no reflog for
+ * the branch, git missing) and any non-rename reflog line yield an empty
+ * array. Callers must treat "no lineage" as the normal case.
+ */
+export function renameLineageFromReflog(run = execRunner, branch) {
+    if (!branch)
+        return [];
+    let out;
+    try {
+        out = run("git", ["reflog", "show", "--format=%gs", `refs/heads/${branch}`]);
+    }
+    catch {
+        return []; // no reflog, not a repo, git unavailable — nothing to follow
+    }
+    const steps = [];
+    for (const line of out.split("\n")) {
+        const match = /^Branch: renamed refs\/heads\/(.+) to refs\/heads\/(.+)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const from = match[1].trim();
+        const to = match[2].trim();
+        if (!from || !to || from === to)
+            continue;
+        steps.push({ from, to });
+    }
+    return steps.reverse(); // reflog is newest-first; register oldest-first
+}
 /**
  * Best-effort default-branch name via the local `origin/HEAD` ref (no
  * network call — just reads the ref git already cached from the last

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
-import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveAutoPrTarget, resolveGhPrefixSafe, resolvePutNudgeContext, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, autoPrNoteText, putNudgeText, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { createUploadsClient, } from "../client.js";
+import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveAutoPrTarget, resolveGhPrefixSafe, resolvePutNudgeContext, registerRenamesBestEffort, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, autoPrNoteText, putNudgeText, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -9,7 +9,7 @@ import { safeCaptureFacts } from "../capture-facts.js";
 import { deriveRepoSlugFromGit } from "../keys.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
-import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentBranchSafe, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { appProp, canonicalMetaFromArgs, METADATA_PATH_CUE, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
 import { batchFailureMessage, mcpDestroyPublic, mcpNoAuth, mcpOAuthAny, mcpOAuthDelete, mcpOAuthRead, mcpOAuthWrite, mcpRead, mcpWriteInternal, mcpWritePublic, stdioOutputSchemas, withOutputSchemas, ToolBatchError, } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
@@ -131,6 +131,25 @@ export function createUploadsMcpTools(opts) {
         }
         return { comment, commentError };
     };
+    /**
+     * Best-effort branch promote for the stdio `attach` tool (CLI `attach --pr`
+     * parity, issue #920). Registers any `git branch -m` steps first so the
+     * sweep follows renames, then promotes. Never throws: a failure surfaces as
+     * `promoteError` so the uploads themselves still return.
+     */
+    const attemptPromote = async (client, target, branch) => {
+        try {
+            const promotion = await client.promoteBranchAttachments({
+                repo: target.repo,
+                num: target.num,
+                branch,
+            });
+            return { promotion };
+        }
+        catch (err) {
+            return { promoteError: err instanceof Error ? err.message : String(err) };
+        }
+    };
     const tools = [
         {
             name: "gallery_create",
@@ -466,7 +485,7 @@ export function createUploadsMcpTools(opts) {
                 // had been passed (stable key + managed comment sync) instead of
                 // the #403 staging default below. Never throws — see
                 // resolveAutoPrTarget.
-                const autoPrTarget = target
+                const autoPrTarget = (target
                     ? undefined
                     : resolveAutoPrTarget({
                         ghTarget: target,
@@ -478,7 +497,7 @@ export function createUploadsMcpTools(opts) {
                         noAutoPr,
                         repoArg: optString(args, "repo") ?? defaults.repo,
                         run,
-                    });
+                    }))?.target;
                 const effectiveTarget = target ?? autoPrTarget;
                 // Bare-put branch staging (issue #403): local stdio MCP put mirrors
                 // the CLI default — no pr/issue/key/ref/prefix/destination, not
@@ -858,7 +877,7 @@ export function createUploadsMcpTools(opts) {
                 // behaves as if `pr` had been passed (stable key + managed comment
                 // sync) instead of the #469 auto-staging default below. Never
                 // throws — see resolveAutoPrTarget.
-                const autoPrTarget = target
+                const autoPrTarget = (target
                     ? undefined
                     : resolveAutoPrTarget({
                         ghTarget: target,
@@ -870,7 +889,7 @@ export function createUploadsMcpTools(opts) {
                         noAutoPr,
                         repoArg: optString(args, "repo") ?? defaults.repo,
                         run,
-                    });
+                    }))?.target;
                 const effectiveTarget = target ?? autoPrTarget;
                 // Auto branch staging (issue #469 lever 1): mirrors the CLI screenshot
                 // command and the put tool above (issue #403) — no pr/issue/key/ref/
@@ -1064,7 +1083,7 @@ export function createUploadsMcpTools(opts) {
             title: "Attach to GitHub",
             annotations: mcpDestroyPublic,
             securitySchemes: mcpOAuthWrite,
-            description: "Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR. Attachments are public and keys are predictable; upload only non-sensitive media.",
+            description: "Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR, and files already staged for that branch are promoted into it (`promotion`/`promoteError`; renamed branches are followed automatically, or name the old branch with fromBranch). Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1078,6 +1097,14 @@ export function createUploadsMcpTools(opts) {
                         type: "boolean",
                         description: "Upload only; don't create/update the managed comment.",
                     },
+                    noPromote: {
+                        type: "boolean",
+                        description: "Skip promoting files staged for the current branch into the PR.",
+                    },
+                    fromBranch: {
+                        type: "string",
+                        description: "Promote files staged under this branch name instead of the current branch (for a branch renamed before the PR opened).",
+                    },
                     contentType: {
                         type: "string",
                         description: "Override the Content-Type (applied to every file; ignored when optimize rewrites).",
@@ -1109,6 +1136,7 @@ export function createUploadsMcpTools(opts) {
                 examples: [
                     { files: ["./after.png"], pr: 12, state: "after" },
                     { files: ["./before.png", "./after.png"], pr: 12 },
+                    { files: ["./after.png"], pr: 12, fromBranch: "old-branch-name" },
                 ],
             },
             async handler(args) {
@@ -1118,6 +1146,13 @@ export function createUploadsMcpTools(opts) {
                 const explicitTarget = ghTargetFromArgs(args, run);
                 const target = explicitTarget ??
                     resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
+                const fromBranch = optString(args, "fromBranch");
+                if (fromBranch !== undefined && optBool(args, "noPromote")) {
+                    usage("fromBranch cannot be combined with noPromote");
+                }
+                if (fromBranch !== undefined && target.kind !== "pull") {
+                    usage("fromBranch only promotes into a pull request");
+                }
                 const { config, client } = await clientFor(args);
                 const contentType = optString(args, "contentType");
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
@@ -1154,10 +1189,30 @@ export function createUploadsMcpTools(opts) {
                         failures,
                     });
                 }
+                // Auto-promote (CLI `attach --pr` parity, issue #920): before the
+                // comment sync, best-effort promote this workspace's branch-staged
+                // files into the PR, following any `git branch -m` rename. Never for
+                // issues, never with noPromote, and silently skipped when the current
+                // branch can't be resolved — this must not fail the attach.
+                let promotion;
+                let promoteError;
+                if (target.kind === "pull" && !optBool(args, "noPromote")) {
+                    const branch = fromBranch ?? resolveCurrentBranchSafe(run);
+                    if (branch !== undefined) {
+                        await registerRenamesBestEffort(client, run, target.repo, branch, {
+                            explicit: fromBranch !== undefined,
+                        });
+                        ({ promotion, promoteError } = await attemptPromote(client, target, branch));
+                    }
+                }
+                const promoteFields = {
+                    ...(promotion ? { promotion } : {}),
+                    ...(promoteError ? { promoteError } : {}),
+                };
                 if (optBool(args, "noComment"))
-                    return { target, uploads, failures };
+                    return { target, uploads, failures, ...promoteFields };
                 const { comment, commentError } = await syncComment(client, target, config.workspace);
-                return { target, uploads, failures, comment, commentError };
+                return { target, uploads, failures, ...promoteFields, comment, commentError };
             },
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.50.1",
+  "version": "0.51.0",
   "mcpName": "sh.uploads/mcp",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",