canopycms 0.0.65 → 0.0.66-int.82

package/dist/worker/history-rewrite.d.ts

@@ -0,0 +1,129 @@
+import type { WorkerContext } from './worker-context.js';
+/**
+ * [SYNC-H1] The history-rewrite kernel: what happens when the rebase loop
+ * rewrites history that was ALREADY published to `remote.git` (and from there
+ * to GitHub).
+ *
+ * Extracted from cms-worker.ts because it is the one thing all three of the
+ * worker's big clusters touch, and for opposite-looking reasons:
+ *
+ * - rebase.ts ARMS a rewrite (mark -> publish -> queue) and completes an
+ *   interrupted one via `reconcilePendingRewrite`;
+ * - task-runner.ts CONSUMES the marker when `pushBranchToGitHub` leases its
+ *   push, and CLEARS it once GitHub confirms;
+ * - git-sync.ts READS it in `reconcileTrackedBranches`, to tell this worker's
+ *   own in-flight rewrite apart from a genuine cross-deployment collision.
+ *
+ * Leaving these on the class would have made every cluster's module import
+ * every other one. They share no state beyond four resolved paths, so they
+ * belong here.
+ *
+ * THE INVARIANT, since it is spread across those three callers: every force
+ * push leases on a SPECIFIC commit this worker knows its own rebase replaced
+ * -- the marker, or the pre-rebase tip -- never on "whatever remote.git holds
+ * right now". A lease on the current tip is satisfied by a reviewer's direct
+ * push to the PR branch and would delete it, silently, from remote.git and
+ * then from GitHub.
+ */
+export type HistoryRewriteContext = Pick<WorkerContext, 'remoteGitPath' | 'contentBranchesPath' | 'taskDir' | 'taskTimeoutMs'>;
+/**
+ * What `remote.git` currently holds for `branchRef`, or null when this
+ * branch was never published there (never submitted) or the ref is
+ * unreadable.
+ *
+ * Uses the same explicit `--git-dir` shape as verifyBaseBranchExists()
+ * in cms-worker.ts: reading a bare repo that way does not depend on
+ * `safe.bareRepository` being permissive, which is why prod code takes
+ * this route rather than the config override the test-only `openBareRepo`
+ * helper uses.
+ */
+export declare function readPublishedSha(ctx: Pick<HistoryRewriteContext, 'remoteGitPath'>, branchRef: string): Promise<string | null>;
+/**
+ * Record that this worker rewrote `expectedSha` out of a branch's already
+ * published history (see BranchMetadata.historyRewrittenFrom).
+ *
+ * Set-once: if a marker is already present it is LEFT ALONE. Across two
+ * rebases before any GitHub push lands, GitHub still holds the commit the
+ * FIRST rebase replaced, so advancing the marker would aim the lease at a
+ * commit GitHub never had and permanently wedge the branch.
+ *
+ * Re-reads metadata rather than trusting the caller's loop-top snapshot:
+ * the task loop runs concurrently with syncGit() (see scheduleLoop) and may
+ * have cleared the marker while this branch was rebasing.
+ */
+export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchDir: string, expectedSha: string): Promise<void>;
+/**
+ * Clear the marker once GitHub is confirmed to hold the rewritten history.
+ *
+ * Best-effort only in the sense that a failure here destroys nothing: the
+ * lease still refuses anything unexpected, and the plain-push fallback only
+ * ever fast-forwards. It is NOT harmless. A marker that outlives its
+ * episode can wedge the NEXT one -- if the base advances before the stale
+ * marker is revisited, the queued push leases a commit GitHub has already
+ * moved off, falls back to a plain push of a rebased (non-ancestor)
+ * history, and fails permanently with a "something else moved it on
+ * GitHub" diagnosis that is false: we did.
+ *
+ * Tracked, with the concurrent-clear race that can drop a marker
+ * mid-arming, in
+ * .claude/future-tasks/worker-history-rewrite-marker-races.md.
+ */
+export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchDir: string): Promise<void>;
+/**
+ * Publish a branch clone's rebased history into `remote.git`, replacing
+ * EXACTLY `expectedSha` and nothing else.
+ *
+ * The lease is the entire safety argument. `--force-with-lease=<ref>:<sha>`
+ * refuses unless `remote.git` still stands at `<sha>`, so this can only
+ * ever undo the commit our own rebase rewrote away. Callers must never pass
+ * "whatever remote.git currently holds" -- see the arming guard in
+ * rebase.ts's carryForwardRewrittenHistory for the interleaving where that
+ * would silently delete a reviewer's direct push.
+ *
+ * Returns whether the push landed. A refused lease means a concurrent
+ * Lambda push moved the ref; that is logged and retried by the self-heal
+ * pass on a later cycle, never thrown.
+ */
+export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
+/**
+ * Queue the GitHub hop for a branch whose rewritten history now sits in
+ * `remote.git`, so an open PR's head follows the rebase within a cycle
+ * instead of waiting for the editor's next submit.
+ *
+ * Deliberately NOT skipped when a marker is already set: inferring "a task
+ * must already be queued" from the marker starves this hop whenever a task
+ * was lost, failed permanently, or was never written. Duplicate push tasks
+ * are bounded by base-branch advances and are idempotent (a repeat push is
+ * a no-op once GitHub holds the tip).
+ */
+export declare function enqueueGitHubPush(ctx: Pick<HistoryRewriteContext, 'taskDir'>, branchRef: string): Promise<void>;
+/**
+ * Complete a rewrite this worker started but did not finish: get the
+ * rebased history into `remote.git` and queued for GitHub.
+ *
+ * Runs from the rebase loop for any branch carrying a marker, whether or
+ * not it is behind base this cycle, so an interrupted publish converges
+ * without waiting for the next base-branch advance.
+ *
+ * Always leases on the MARKER, never on remote.git's current tip -- the
+ * marker is the one commit we know our own rebase replaced.
+ */
+export declare function reconcilePendingRewrite(ctx: HistoryRewriteContext, options: {
+    branchPath: string;
+    branchDir: string;
+    branchRef: string;
+    headSha: string;
+    marker: string;
+}): Promise<void>;
+/**
+ * Whether this branch carries a pending history rewrite -- the rebase loop
+ * rewrote already-published history and the GitHub push has not landed yet
+ * (see BranchMetadata.historyRewrittenFrom).
+ *
+ * `branchName` is a git ref name; branch workspaces are directories named
+ * with the sanitized form, hence the conversion. Best-effort: a settings
+ * branch (no workspace at all), a missing directory or an unreadable
+ * branch.json all mean "no known rewrite", which is the conservative
+ * answer -- it keeps the branch in the louder `diverged` bucket.
+ */
+export declare function hasPendingHistoryRewrite(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchName: string): Promise<boolean>;

package/dist/worker/history-rewrite.js

@@ -0,0 +1,216 @@
+import path from 'node:path';
+import { simpleGit } from 'simple-git';
+import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { gitChildEnv } from '../git-manager.js';
+import { sanitizeBranchName } from '../paths/branch-name.js';
+import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { isStaleLeaseRejection } from '../utils/git.js';
+import { enqueueTask, listTasks } from './task-queue.js';
+import { workerLog, workerLogWarn } from './log.js';
+/**
+ * What `remote.git` currently holds for `branchRef`, or null when this
+ * branch was never published there (never submitted) or the ref is
+ * unreadable.
+ *
+ * Uses the same explicit `--git-dir` shape as verifyBaseBranchExists()
+ * in cms-worker.ts: reading a bare repo that way does not depend on
+ * `safe.bareRepository` being permissive, which is why prod code takes
+ * this route rather than the config override the test-only `openBareRepo`
+ * helper uses.
+ */
+export async function readPublishedSha(ctx, branchRef) {
+    try {
+        const out = await simpleGit().raw([
+            '--git-dir',
+            ctx.remoteGitPath,
+            'rev-parse',
+            '--verify',
+            `refs/heads/${branchRef}`,
+        ]);
+        const sha = out.trim();
+        return sha.length > 0 ? sha : null;
+    }
+    catch {
+        // Absent from remote.git: this branch was never submitted, so none of
+        // its history was ever published. Not an error.
+        return null;
+    }
+}
+/**
+ * Record that this worker rewrote `expectedSha` out of a branch's already
+ * published history (see BranchMetadata.historyRewrittenFrom).
+ *
+ * Set-once: if a marker is already present it is LEFT ALONE. Across two
+ * rebases before any GitHub push lands, GitHub still holds the commit the
+ * FIRST rebase replaced, so advancing the marker would aim the lease at a
+ * commit GitHub never had and permanently wedge the branch.
+ *
+ * Re-reads metadata rather than trusting the caller's loop-top snapshot:
+ * the task loop runs concurrently with syncGit() (see scheduleLoop) and may
+ * have cleared the marker while this branch was rebasing.
+ */
+export async function markHistoryRewritten(ctx, branchPath, branchDir, expectedSha) {
+    const current = await BranchMetadataFileManager.loadOnly(branchPath);
+    if (typeof current?.branch.historyRewrittenFrom === 'string')
+        return;
+    const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
+    await meta.save({ branch: { name: branchDir, historyRewrittenFrom: expectedSha } });
+}
+/**
+ * Clear the marker once GitHub is confirmed to hold the rewritten history.
+ *
+ * Best-effort only in the sense that a failure here destroys nothing: the
+ * lease still refuses anything unexpected, and the plain-push fallback only
+ * ever fast-forwards. It is NOT harmless. A marker that outlives its
+ * episode can wedge the NEXT one -- if the base advances before the stale
+ * marker is revisited, the queued push leases a commit GitHub has already
+ * moved off, falls back to a plain push of a rebased (non-ancestor)
+ * history, and fails permanently with a "something else moved it on
+ * GitHub" diagnosis that is false: we did.
+ *
+ * Tracked, with the concurrent-clear race that can drop a marker
+ * mid-arming, in
+ * .claude/future-tasks/worker-history-rewrite-marker-races.md.
+ */
+export async function clearHistoryRewrittenMarker(ctx, branchPath, branchDir) {
+    try {
+        const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
+        // Explicit undefined clears the key -- save()'s merge only overwrites
+        // keys present in the update (same pattern as rebaseFailure).
+        await meta.save({ branch: { name: branchDir, historyRewrittenFrom: undefined } });
+    }
+    catch (err) {
+        workerLogWarn(`  Failed to clear history-rewrite marker for ${branchDir}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Publish a branch clone's rebased history into `remote.git`, replacing
+ * EXACTLY `expectedSha` and nothing else.
+ *
+ * The lease is the entire safety argument. `--force-with-lease=<ref>:<sha>`
+ * refuses unless `remote.git` still stands at `<sha>`, so this can only
+ * ever undo the commit our own rebase rewrote away. Callers must never pass
+ * "whatever remote.git currently holds" -- see the arming guard in
+ * rebase.ts's carryForwardRewrittenHistory for the interleaving where that
+ * would silently delete a reviewer's direct push.
+ *
+ * Returns whether the push landed. A refused lease means a concurrent
+ * Lambda push moved the ref; that is logged and retried by the self-heal
+ * pass on a later cycle, never thrown.
+ */
+export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expectedSha) {
+    // A dedicated instance rather than the caller's: `.env()` replaces the
+    // whole child environment, and the rebase loop's instance must keep its
+    // ambient one. gitChildEnv (not gitNetworkChildEnv) because this push
+    // targets the local bare repo -- and the locale pin is what keeps
+    // isStaleLeaseRejection below from silently becoming a no-op.
+    const pushGit = simpleGit({ baseDir: branchPath, timeout: { block: ctx.taskTimeoutMs } });
+    pushGit.env(gitChildEnv({}));
+    try {
+        await pushGit.raw([
+            'push',
+            `--force-with-lease=${branchRef}:${expectedSha}`,
+            // Real flags must precede --end-of-options; everything after it is
+            // positional (see GitManager.push() for the same guard).
+            '--end-of-options',
+            'origin',
+            `${branchRef}:${branchRef}`,
+        ]);
+        workerLog(`  Published rebased ${branchRef} into remote.git`);
+        return true;
+    }
+    catch (err) {
+        const message = redactCredentials(getErrorMessage(err));
+        workerLogWarn(isStaleLeaseRejection(message)
+            ? `  Did not publish rebased ${branchRef} into remote.git: it moved since this cycle read it (concurrent submit?) -- retrying next cycle`
+            : `  Failed to publish rebased ${branchRef} into remote.git: ${message}`);
+        return false;
+    }
+}
+/**
+ * Queue the GitHub hop for a branch whose rewritten history now sits in
+ * `remote.git`, so an open PR's head follows the rebase within a cycle
+ * instead of waiting for the editor's next submit.
+ *
+ * Deliberately NOT skipped when a marker is already set: inferring "a task
+ * must already be queued" from the marker starves this hop whenever a task
+ * was lost, failed permanently, or was never written. Duplicate push tasks
+ * are bounded by base-branch advances and are idempotent (a repeat push is
+ * a no-op once GitHub holds the tip).
+ */
+export async function enqueueGitHubPush(ctx, branchRef) {
+    try {
+        // Dedupe against tasks actually in flight rather than against the
+        // marker: a branch whose GitHub push keeps failing would otherwise
+        // gain one task per sync cycle forever.
+        for (const status of ['pending', 'processing']) {
+            const inFlight = await listTasks(ctx.taskDir, status);
+            if (inFlight.some((t) => t.action === 'push-branch' && t.payload.branch === branchRef)) {
+                return;
+            }
+        }
+        await enqueueTask(ctx.taskDir, { action: 'push-branch', payload: { branch: branchRef } });
+        workerLog(`  Queued GitHub push for ${branchRef}`);
+    }
+    catch (err) {
+        workerLogWarn(`  Failed to queue GitHub push for ${branchRef}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Complete a rewrite this worker started but did not finish: get the
+ * rebased history into `remote.git` and queued for GitHub.
+ *
+ * Runs from the rebase loop for any branch carrying a marker, whether or
+ * not it is behind base this cycle, so an interrupted publish converges
+ * without waiting for the next base-branch advance.
+ *
+ * Always leases on the MARKER, never on remote.git's current tip -- the
+ * marker is the one commit we know our own rebase replaced.
+ */
+export async function reconcilePendingRewrite(ctx, options) {
+    const { branchPath, branchDir, branchRef, headSha, marker } = options;
+    const publishedSha = await readPublishedSha(ctx, branchRef);
+    if (publishedSha === null) {
+        workerLogWarn(`  ${branchDir}: a rewritten history is recorded but ${branchRef} is gone from remote.git -- nothing to publish`);
+        return;
+    }
+    if (publishedSha === headSha) {
+        // remote.git already carries the rewrite; only the GitHub hop is left
+        // (a crash between the push and the queue, or a task that was lost).
+        await enqueueGitHubPush(ctx, branchRef);
+        return;
+    }
+    if (publishedSha === marker) {
+        // The publish into remote.git never landed -- a crash right after the
+        // marker was written, or a lease refused by a concurrent submit.
+        if (await forcePublishToLocalRemote(ctx, branchPath, branchRef, marker)) {
+            await enqueueGitHubPush(ctx, branchRef);
+        }
+        return;
+    }
+    // Neither this branch's rebased tip nor the commit its rewrite replaced:
+    // something else moved remote.git. Never force over that.
+    workerLogWarn(`  ${branchDir}: remote.git is at ${publishedSha} for ${branchRef}, which is neither the ` +
+        `rebased tip nor the commit the rewrite replaced -- left untouched`);
+}
+/**
+ * Whether this branch carries a pending history rewrite -- the rebase loop
+ * rewrote already-published history and the GitHub push has not landed yet
+ * (see BranchMetadata.historyRewrittenFrom).
+ *
+ * `branchName` is a git ref name; branch workspaces are directories named
+ * with the sanitized form, hence the conversion. Best-effort: a settings
+ * branch (no workspace at all), a missing directory or an unreadable
+ * branch.json all mean "no known rewrite", which is the conservative
+ * answer -- it keeps the branch in the louder `diverged` bucket.
+ */
+export async function hasPendingHistoryRewrite(ctx, branchName) {
+    try {
+        const branchPath = path.join(ctx.contentBranchesPath, sanitizeBranchName(branchName));
+        const metaFile = await BranchMetadataFileManager.loadOnly(branchPath);
+        return typeof metaFile?.branch.historyRewrittenFrom === 'string';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/worker/rebase.d.ts

@@ -0,0 +1,171 @@
+import { type BranchMetadataFile } from '../branch-metadata.js';
+import { type ContentId } from '../paths/types.js';
+import type { WorkerContext } from './worker-context.js';
+/**
+ * The rebase loop: the largest and most safety-critical of the four call trees
+ * that used to share cms-worker.ts, and the deepest leaf of the git-sync
+ * cluster. `syncGit` (git-sync.ts) calls `runRebaseCycle` once per cycle.
+ *
+ * Every branch workspace that is behind the base branch is rebased onto it,
+ * keeping the BRANCH's version of any conflicting file. Three things make this
+ * the part of the worker most likely to misbehave under real EFS and spot
+ * conditions, and all three are documented at the point they happen rather
+ * than here:
+ *
+ * - it holds the [SYNC-C1] cross-host content-write lock for the whole rebase,
+ *   so an editor's save cannot be destroyed mid-replay;
+ * - it recovers a rebase INTERRUPTED by a crash, OOM or spot interruption,
+ *   which is lossy in a specific, logged way;
+ * - it carries a rewritten history forward into remote.git and GitHub under a
+ *   lease keyed to the exact commit it replaced ([SYNC-H1], history-rewrite.ts).
+ *
+ * `pollMergeState` lives here rather than in git-sync.ts because the rebase
+ * loop is its only caller: submitted/approved branches are skipped for rebasing
+ * but still need their PR's resolution polled, and this loop is the only thing
+ * that walks every branch workspace.
+ */
+export type RebaseContext = Pick<WorkerContext, 'githubOwner' | 'githubRepo' | 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'octokit' | 'afterConflictDetectedForTesting' | 'afterRebaseCompletedForTesting'>;
+/**
+ * Per-cycle outcome of `rebaseActiveBranches()` (PR-W1). Folded by `syncGit()`
+ * into the worker's self-reported status (`WorkerStatusReport.lastGitSync`,
+ * see worker-status.ts) alongside a `durationMs` measured around the whole
+ * sync cycle.
+ */
+export interface RebaseSummary {
+    /**
+     * Branches that were behind and completed a rebase onto the base branch
+     * (successfully, whether or not conflicts were resolved via --theirs).
+     * Branches that were already up to date are NOT listed here.
+     */
+    rebased: string[];
+    /** Branches skipped this cycle because their working tree had uncommitted changes. */
+    skippedDirty: string[];
+    /**
+     * [SYNC-C1] Branches skipped this cycle for a content-write-lock reason,
+     * either of which is a RETRY rather than a failure:
+     *
+     * - a content write already held the branch's cross-host content-write lock
+     *   (utils/content-write-lock.ts) -- the worker yields on contention, since
+     *   the editor on the other side is a person waiting on a save; or
+     * - the lock was LOST mid-rebase (compromised), so the worker stopped before
+     *   the next destructive git step. Only when the rebase had not completed:
+     *   a completed rebase must still run its completion path, or it strands the
+     *   [SYNC-H1] marker on a branch nothing will revisit.
+     */
+    skippedLocked: string[];
+    /** Branches whose rebase attempt failed (fetch error, unexpected rebase error, or MAX_REBASE_ROUNDS exceeded). */
+    failed: {
+        branch: string;
+        error: string;
+    }[];
+}
+/**
+ * Poll GitHub for a submitted/approved branch's PR resolution.
+ *
+ * submitted/approved branches sit outside the rebase loop and get no
+ * other signal that their PR resolved on GitHub -- nothing pushes a
+ * merge/close webhook back into the branch workspace. merged ->
+ * auto-archive via buildMergedBranchUpdate (shared with the manual
+ * markAsMerged API so both paths produce identical archived-branch
+ * metadata). closed-without-merge -> record pullRequestState only; an
+ * admin decides the workflow transition from there. Best-effort: any
+ * failure here is logged and swallowed, retried next sync cycle.
+ */
+export declare function pollMergeState(ctx: RebaseContext, branchDir: string, branchPath: string, metaFile: BranchMetadataFile | null): Promise<void>;
+/**
+ * Persist a per-branch rebase failure to branch.json (PR-W2), bounded to
+ * roughly one save per failing branch per hour: a branch stuck failing
+ * every cycle must not turn into unbounded save-per-cycle x N-failing-
+ * branches write amplification -- save() eager-regenerates the branch
+ * registry (branch-metadata.ts's invalidateRegistry(), O(branch count) EFS
+ * reads), the same concern the `alreadyClean` no-op guard above exists
+ * for.
+ *
+ * Best-effort and non-fatal like every other metadata write in this
+ * loop's error paths: a corrupt branch.json, a lock-contention error, or
+ * any other save failure here must never abort the per-branch iteration.
+ * This matters doubly at the two call sites -- one is inside the outer
+ * per-branch catch, with no further catch of its own around this call --
+ * so the whole method is wrapped, not just the load.
+ */
+export declare function recordRebaseFailure(ctx: RebaseContext, branchPath: string, branchDir: string, message: string): Promise<void>;
+/**
+ * Map the file paths a rebase resolved --theirs onto the ContentIds the editor
+ * shows as conflicted, deduplicated.
+ *
+ * IDs rather than paths because they are immutable: a later slug rename must
+ * not orphan a conflict marker. Paths that carry no recoverable ID are dropped
+ * rather than guessed at.
+ *
+ * Pure -- the one piece of this loop that can be tested without a git repo.
+ */
+export declare function conflictFilesToContentIds(conflictedFiles: readonly string[], contentRoot: string): ContentId[];
+/**
+ * What one branch contributed to the cycle summary -- the return type that
+ * replaced `continue` when the per-branch body moved into
+ * {@link rebaseOneBranch}.
+ *
+ * The original loop expressed this by pushing to one of four arrays in scope
+ * and then `continue`-ing; there were nine such exits and each pushed to a
+ * different array (or to none), which is exactly the sort of thing that is
+ * easy to get wrong when the body is 640 lines long. Making it a return value
+ * means the compiler checks that every path produces one.
+ */
+export type BranchRebaseOutcome = 
+/** Nothing to do: a skipped status, or already up to date. Not reported. */
+{
+    kind: 'none';
+}
+/** Was behind and completed a rebase, with or without conflict resolution. */
+ | {
+    kind: 'rebased';
+}
+/** Working tree had uncommitted changes. Retried next cycle. */
+ | {
+    kind: 'skippedDirty';
+}
+/** [SYNC-C1] Content-write lock busy or lost mid-rebase. Retried next cycle. */
+ | {
+    kind: 'skippedLocked';
+} | {
+    kind: 'failed';
+    error: string;
+    /**
+     * True when the rebase itself COMPLETED and the branch was already
+     * counted as rebased before the failure. Only reachable from the
+     * [SYNC-H1] carry-forward block, which is the sole code that runs after
+     * that point and can still throw (via markHistoryRewritten's metadata
+     * save).
+     *
+     * Not a tidying-up detail: the original loop pushed to `rebased` and
+     * THEN to `failed` in that interleaving, so the branch appeared in both
+     * buckets -- and it genuinely is both, because its history moved and
+     * publishing the move failed. Collapsing it to `failed` alone would drop
+     * a real rebase from worker-status.json.
+     *
+     * KNOWN COVERAGE GAP, stated rather than hidden: only the `false`
+     * direction is exercised (the fetch-error path in cms-worker.test.ts).
+     * Reaching the `true` direction needs `markHistoryRewritten`'s metadata
+     * save to fail AFTER a completed rebase, and there is no seam for that --
+     * the save sits between two other saves with no hook between them.
+     * Adding a production hook purely to reach it would cost more than the
+     * gap. The placement was instead verified by hand against the pre-split
+     * method: `didRebase = true` sits exactly where `rebased.push` sat, after
+     * the conflictStatus save and before the carry-forward, so a failing
+     * conflictStatus save still yields `failed` alone.
+     */
+    rebased?: boolean;
+};
+/**
+ * Rebase every branch workspace that is behind the base branch, one cycle.
+ *
+ * The per-branch work is {@link rebaseOneBranch}; what stays here is the walk
+ * over `content-branches/`, the structural pre-filter (entries that are not
+ * branch workspaces at all, plus the base branch's own clone), and folding
+ * each branch's outcome into the summary.
+ *
+ * Deliberately sequential rather than concurrent: each branch's rebase holds
+ * that branch's cross-host content-write lock and runs a series of git
+ * subprocesses against a shared filesystem.
+ */
+export declare function runRebaseCycle(ctx: RebaseContext): Promise<RebaseSummary>;