@cvr/stacked 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cvr/stacked",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/stacked"

package/skills/stacked/SKILL.md

@@ -45,7 +45,7 @@ What do you need?
 | `stacked down`               | Move down one branch in the stack                                                           |
 | `stacked top`                | Jump to top of stack                                                                        |
 | `stacked bottom`             | Jump to bottom of stack                                                                     |
-| `stacked sync`               | Fetch + rebase + force-push stack on trunk (`--from`, `--dry-run`, `--json`)                |
+| `stacked sync`               | Fetch + sync stack on trunk (`--from`, `--dry-run`, `--rebase-only`, `--json`)              |
 | `stacked detect`             | Detect branch chains and register as stacks (`--dry-run`, `--json`)                         |
 | `stacked clean`              | Remove merged branches + remote branches (`--dry-run`, `--json`)                            |
 | `stacked delete <name>`      | Remove branch from stack + git + remote (`--keep-remote`, `--force`, `--dry-run`, `--json`) |
@@ -143,23 +143,33 @@ All navigation commands support `--json` for structured output. `checkout` falls
 
 ## Syncing / Rebasing / Pushing
 
-Fetch latest trunk, rebase the entire stack bottom-to-top, then force-push each rebased branch (`--force-with-lease`):
+Fetch latest trunk, then incrementally sync the stack bottom-to-top using fork-point tracking:
 
 ```sh
 stacked sync
-stacked sync --dry-run    # preview rebase/push plan without executing
-stacked sync --json       # structured output: { branches: [{ name, action, base }] }
+stacked sync --dry-run       # preview sync plan with predicted actions per branch
+stacked sync --rebase-only   # force rebase path (skip tree-merge)
+stacked sync --json          # structured output: { branches: [{ name, action, base }] }
 ```
 
-After mid-stack changes, rebase only the branches above a specific point:
+**How sync works:**
+
+1. Fetch and rebase trunk onto `origin/trunk`
+2. For each branch, check if parent moved since last sync (`syncedOnto` metadata)
+3. If parent unchanged → skip (no push needed)
+4. If parent changed → try tree-merge fast path (es-git: `mergeTrees`, creates merge commit, no replay)
+5. If tree-merge conflicts → fall back to rebase with corrected fork-point as `oldBase`
+6. Force-push changed branches, update `syncedOnto` metadata
+
+After mid-stack changes, sync only the branches above a specific point:
 
 ```sh
 stacked checkout feat-auth
 # ... make changes, commit ...
-stacked sync --from feat-auth    # rebases only children of feat-auth
+stacked sync --from feat-auth    # syncs only children of feat-auth
 ```
 
-**Note:** `sync` requires a clean working tree — commit or stash before running (except with `--dry-run`). On rebase conflict, the rebase is left in progress so you can resolve it:
+**Note:** `sync` requires a clean working tree — commit or stash before running (except with `--dry-run`). On rebase conflict (fallback path), the rebase is left in progress so you can resolve it:
 
 ```sh
 # On conflict:
@@ -311,10 +321,11 @@ Usage errors (invalid args, bad state) exit code 2. Operational errors (git/gh f
 
 ## Data Model
 
-Stack metadata lives in `.git/stacked.json`. Each branch's parent is implied by array position:
+Stack metadata lives in `.git/stacked.json`. Each branch record stores:
 
-- `branches[0]` → parent is trunk
-- `branches[n]` → parent is `branches[n-1]`
+- `stack` — which stack it belongs to
+- `parent` — parent branch name (null for root)
+- `syncedOnto` — (optional) the parent branch tip SHA at last sync, used for incremental sync
 
 Trunk is auto-detected on first use from `origin/HEAD` when available, then falls back to local `main`, `master`, or `develop`. Override with `stacked trunk <name>`.
 
@@ -356,8 +367,10 @@ stacked down  # go to previous branch
 ## Gotchas
 
 - `stacked sync` requires a clean working tree — commit or stash first (except `--dry-run`)
-- `stacked sync` rebases bottom-to-top and force-pushes each rebased branch with lease
-- `stacked sync` leaves rebase in progress on conflict — resolve with `git rebase --continue`, then resume with `stacked sync --from <parent>`
+- `stacked sync` uses tree-merge by default (es-git); falls back to rebase on conflict or CLI backend
+- `stacked sync` skips branches whose parent hasn't moved since last sync
+- `stacked sync` leaves rebase in progress on conflict (fallback path) — resolve with `git rebase --continue`, then resume with `stacked sync --from <parent>`
+- `syncedOnto` metadata may become stale if branches are rebased outside `stacked` — first sync after that falls back to `merge-base`
 - `stacked submit` force-pushes by default (use `--no-force` to disable)
 - `stacked submit` and `stacked clean` require `gh` CLI authenticated (`gh auth login`)
 - PRs target parent branches, not trunk — this is intentional for stacked review
@@ -369,4 +382,5 @@ stacked down  # go to previous branch
 - Detached HEAD is detected and produces a clear error — checkout a branch first
 - Stack file writes are atomic (write to tmp, then rename) to prevent corruption
 - `create` and `adopt` are idempotent — safe to re-run after transient failures
-- Use `stacked doctor` to detect and fix metadata drift (stale branches, missing trunk)
+- Use `stacked doctor` to detect and fix metadata drift (stale branches, missing trunk, stale syncedOnto)
+- `stacked doctor --fix` clears stale `syncedOnto` entries pointing at non-existent commits

package/src/commands/adopt.ts

@@ -87,6 +87,15 @@ export const adopt = Command.make("adopt", {
         yield* stacks.addBranch(result.name, branch, afterBranch);
       }
 
+      // Record fork-point for incremental sync based on the branch's merge-base with its parent
+      const parentRef = Option.isSome(after) ? after.value : yield* git.currentBranch();
+      const parentTip = yield* git
+        .mergeBase(branch, parentRef)
+        .pipe(Effect.catchTag("GitError", () => git.revParse(parentRef)));
+      yield* stacks
+        .updateSyncedOnto(branch, parentTip)
+        .pipe(Effect.catchTag("StackError", () => Effect.void));
+
       if (json) {
         const stackResult = yield* stacks.currentStack();
         const stackName = stackResult?.name ?? branch;

package/src/commands/amend.ts

@@ -61,34 +61,70 @@ export const amend = Command.make("amend", {
         return;
       }
 
-      // Rebase children
+      // Sync children using fork-point-aware algorithm
       const children = branches.slice(idx + 1);
       const synced: string[] = [];
+      const data = yield* stacks.load();
+      const mergedSet = new Set(data.mergedBranches);
 
       yield* Effect.gen(function* () {
         for (let i = 0; i < children.length; i++) {
           const branch = children[i];
           if (branch === undefined) continue;
-          const newBase = i === 0 ? fromBranch : (children[i - 1] ?? fromBranch);
+          // Compute effective base, skipping merged branches (same as sync)
+          let newBase = fromBranch;
+          for (let j = i - 1; j >= 0; j--) {
+            const candidate = children[j];
+            if (candidate !== undefined && !mergedSet.has(candidate)) {
+              newBase = candidate;
+              break;
+            }
+          }
 
-          const oldBase = yield* git
-            .mergeBase(branch, newBase)
-            .pipe(Effect.catchTag("GitError", () => Effect.succeed(newBase)));
+          const newBaseTip = yield* git.revParse(newBase);
+          const branchHead = yield* git.revParse(branch);
+          const syncedOnto = yield* stacks.getSyncedOnto(branch);
 
-          yield* git.checkout(branch);
-          yield* withSpinner(
-            `Rebasing ${branch} onto ${newBase}`,
-            git.rebaseOnto(branch, newBase, oldBase),
-          ).pipe(
-            Effect.catchTag("GitError", (e) =>
-              Effect.fail(
-                new StackError({
-                  code: ErrorCode.REBASE_CONFLICT,
-                  message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue`,
-                }),
+          // Resolve old base: prefer recorded fork-point, fall back to merge-base
+          const oldBase =
+            syncedOnto ??
+            (yield* git
+              .mergeBase(branch, newBase)
+              .pipe(Effect.catchTag("GitError", () => Effect.succeed(newBase))));
+
+          // Try tree-merge fast path
+          const mergeResult = yield* git
+            .treeMergeSync({
+              branch,
+              branchHead,
+              oldBase,
+              newBase: newBaseTip,
+              message: `sync: incorporate changes from ${newBase}`,
+            })
+            .pipe(
+              Effect.catchTag("GitError", () => Effect.succeed({ action: "conflict" as const })),
+            );
+
+          if (mergeResult.action === "merged" || mergeResult.action === "up-to-date") {
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+          } else {
+            // Conflict — fall back to rebase with corrected oldBase
+            yield* git.checkout(branch);
+            yield* withSpinner(
+              `Rebasing ${branch} onto ${newBase}`,
+              git.rebaseOnto(branch, newBase, oldBase),
+            ).pipe(
+              Effect.catchTag("GitError", (e) =>
+                Effect.fail(
+                  new StackError({
+                    code: ErrorCode.REBASE_CONFLICT,
+                    message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue`,
+                  }),
+                ),
               ),
-            ),
-          );
+            );
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+          }
           synced.push(branch);
         }
       }).pipe(

package/src/commands/create.ts

@@ -99,6 +99,10 @@ export const create = Command.make("create", {
         yield* stacks.addBranch(stackName, name, baseBranch === trunk ? undefined : baseBranch);
       }
 
+      // Record the fork-point for incremental sync
+      const baseTip = yield* git.revParse(baseBranch);
+      yield* stacks.updateSyncedOnto(name, baseTip);
+
       if (json) {
         // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
         yield* Console.log(

package/src/commands/doctor.ts

@@ -8,7 +8,7 @@ const fixFlag = Flag.boolean("fix").pipe(Flag.withDescription("Auto-fix issues w
 const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"));
 
 interface Finding {
-  type: "stale_branch" | "missing_trunk" | "duplicate_branch" | "parse_error";
+  type: "stale_branch" | "missing_trunk" | "duplicate_branch" | "stale_fork_point" | "parse_error";
   message: string;
   fixed: boolean;
 }
@@ -109,6 +109,33 @@ export const doctor = Command.make("doctor", { fix: fixFlag, json: jsonFlag }).p
         }
       }
 
+      // Check 4: syncedOnto entries point at valid commits
+      for (const [branch, record] of Object.entries(data.branches)) {
+        if (record.syncedOnto == null) continue;
+        const valid = yield* git.revParse(record.syncedOnto).pipe(
+          Effect.as(true),
+          Effect.catchTag("GitError", () => Effect.succeed(false)),
+        );
+        if (!valid) {
+          if (fix) {
+            yield* stacks
+              .updateSyncedOnto(branch, null)
+              .pipe(Effect.catchTag("StackError", () => Effect.void));
+            findings.push({
+              type: "stale_fork_point",
+              message: `Cleared stale syncedOnto for "${branch}" (commit ${record.syncedOnto.slice(0, 7)} no longer exists)`,
+              fixed: true,
+            });
+          } else {
+            findings.push({
+              type: "stale_fork_point",
+              message: `Branch "${branch}" has stale syncedOnto (commit ${record.syncedOnto.slice(0, 7)} no longer exists)`,
+              fixed: false,
+            });
+          }
+        }
+      }
+
       if (json) {
         // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
         yield* Console.log(JSON.stringify({ findings }, null, 2));

package/src/commands/sync.ts

@@ -21,10 +21,13 @@ const jsonFlag = Flag.boolean("json").pipe(Flag.withDescription("Output as JSON"
 const dryRunFlag = Flag.boolean("dry-run").pipe(
   Flag.withDescription("Show rebase plan without executing"),
 );
+const rebaseOnlyFlag = Flag.boolean("rebase-only").pipe(
+  Flag.withDescription("Force rebase path (skip tree-merge)"),
+);
 
 interface SyncResult {
   name: string;
-  action: "rebased" | "skipped" | "up-to-date";
+  action: "rebased" | "merged" | "skipped" | "up-to-date";
   base: string;
 }
 
@@ -33,6 +36,7 @@ export const sync = Command.make("sync", {
   from: fromFlag,
   json: jsonFlag,
   dryRun: dryRunFlag,
+  rebaseOnly: rebaseOnlyFlag,
 }).pipe(
   Command.withDescription(
     "Fetch, rebase, and force-push stack branches. Use --from to start from a branch.",
@@ -41,8 +45,9 @@ export const sync = Command.make("sync", {
     { command: "stacked sync", description: "Sync local trunk, then rebase entire stack on trunk" },
     { command: "stacked sync --from feat-auth", description: "Resume from a specific branch" },
     { command: "stacked sync --dry-run", description: "Preview rebase plan" },
+    { command: "stacked sync --rebase-only", description: "Force rebase (skip tree-merge)" },
   ]),
-  Command.withHandler(({ trunk: trunkOpt, from: fromOpt, json, dryRun }) =>
+  Command.withHandler(({ trunk: trunkOpt, from: fromOpt, json, dryRun, rebaseOnly }) =>
     Effect.gen(function* () {
       const git = yield* GitService;
       const gh = yield* GitHubService;
@@ -105,18 +110,43 @@ export const sync = Command.make("sync", {
       const results: SyncResult[] = [];
 
       if (dryRun) {
-        results.push({ name: trunk, action: "skipped", base: originTrunk });
+        results.push({ name: trunk, action: "rebased", base: originTrunk });
         if (!json) {
-          yield* Console.error(`Would fetch and rebase ${trunk} onto ${originTrunk}`);
+          yield* Console.error(`${trunk}: rebase onto ${originTrunk}`);
         }
 
         for (let i = startIdx; i < branches.length; i++) {
           const branch = branches[i];
           if (branch === undefined) continue;
           const base = effectiveBase(i, originTrunk);
-          results.push({ name: branch, action: "skipped", base });
+
+          const newBaseTip = yield* git.revParse(base);
+          const branchHead = yield* git.revParse(branch);
+          const syncedOnto = yield* stacks.getSyncedOnto(branch);
+
+          let action: SyncResult["action"];
+          if (syncedOnto !== null && syncedOnto === newBaseTip) {
+            action = "up-to-date";
+          } else {
+            const alreadyIncorporated = yield* git
+              .isAncestor(newBaseTip, branchHead)
+              .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+            if (alreadyIncorporated) {
+              action = "up-to-date";
+            } else {
+              action = !rebaseOnly && git.supportsTreeMerge() ? "merged" : "rebased";
+            }
+          }
+
+          results.push({ name: branch, action, base });
           if (!json) {
-            yield* Console.error(`Would rebase and force-push ${branch} onto ${base}`);
+            const verb =
+              action === "up-to-date"
+                ? "up-to-date"
+                : action === "merged"
+                  ? `tree-merge onto ${base}`
+                  : `rebase onto ${base}`;
+            yield* Console.error(`${branch}: ${verb}`);
           }
         }
 
@@ -124,9 +154,12 @@ export const sync = Command.make("sync", {
           // @effect-diagnostics-next-line effect/preferSchemaOverJson:off
           yield* Console.log(JSON.stringify({ branches: results }, null, 2));
         } else {
-          yield* Console.error(
-            `\n${results.length} branch${results.length === 1 ? "" : "es"} would be rebased`,
-          );
+          const changed = results.filter((r) => r.action !== "up-to-date").length;
+          const skipped = results.filter((r) => r.action === "up-to-date").length;
+          const parts: string[] = [];
+          if (changed > 0) parts.push(`${changed} to sync`);
+          if (skipped > 0) parts.push(`${skipped} up-to-date`);
+          yield* Console.error(`\n${parts.join(", ")}`);
         }
         return;
       }
@@ -151,29 +184,79 @@ export const sync = Command.make("sync", {
           if (branch === undefined) continue;
           const newBase = effectiveBase(i, originTrunk);
 
-          // Compute old base (merge-base of this branch and its parent) before rebasing
-          const oldBase = yield* git
-            .mergeBase(branch, newBase)
-            .pipe(Effect.catchTag("GitError", () => Effect.succeed(newBase)));
-
-          yield* git.checkout(branch);
-          yield* withSpinner(
-            `Rebasing ${branch} onto ${newBase}`,
-            git.rebaseOnto(branch, newBase, oldBase),
-          ).pipe(
-            Effect.catchTag("GitError", (e) => {
-              const hint =
-                i === 0 ? "stacked sync" : `stacked sync --from ${branches[i - 1] ?? trunk}`;
-              return Effect.fail(
-                new StackError({
-                  code: ErrorCode.REBASE_CONFLICT,
-                  message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue\n  ${hint}`,
-                }),
-              );
-            }),
-          );
-          yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: true }));
-          results.push({ name: branch, action: "rebased", base: newBase });
+          const newBaseTip = yield* git.revParse(newBase);
+          const branchHead = yield* git.revParse(branch);
+          const syncedOnto = yield* stacks.getSyncedOnto(branch);
+
+          // Skip if parent hasn't moved since last sync
+          if (syncedOnto !== null && syncedOnto === newBaseTip) {
+            results.push({ name: branch, action: "up-to-date", base: newBase });
+            continue;
+          }
+
+          // Skip if parent is already an ancestor of branch (manually synced)
+          const alreadyIncorporated = yield* git
+            .isAncestor(newBaseTip, branchHead)
+            .pipe(Effect.catchTag("GitError", () => Effect.succeed(false)));
+          if (alreadyIncorporated) {
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+            results.push({ name: branch, action: "up-to-date", base: newBase });
+            continue;
+          }
+
+          // Resolve old base: prefer recorded fork-point, fall back to merge-base
+          const oldBase =
+            syncedOnto ??
+            (yield* git
+              .mergeBase(branch, newBase)
+              .pipe(Effect.catchTag("GitError", () => Effect.succeed(newBase))));
+
+          // Try tree-merge fast path first (unless --rebase-only)
+          const mergeResult = rebaseOnly
+            ? ({ action: "conflict" } as const)
+            : yield* git
+                .treeMergeSync({
+                  branch,
+                  branchHead,
+                  oldBase,
+                  newBase: newBaseTip,
+                  message: `sync: incorporate changes from ${newBase}`,
+                })
+                .pipe(
+                  Effect.catchTag("GitError", () =>
+                    Effect.succeed({ action: "conflict" as const }),
+                  ),
+                );
+
+          if (mergeResult.action === "merged") {
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+            yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: true }));
+            results.push({ name: branch, action: "merged", base: newBase });
+          } else if (mergeResult.action === "up-to-date") {
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+            results.push({ name: branch, action: "up-to-date", base: newBase });
+          } else {
+            // Conflict or unsupported backend — fall back to rebase with corrected oldBase
+            yield* git.checkout(branch);
+            yield* withSpinner(
+              `Rebasing ${branch} onto ${newBase}`,
+              git.rebaseOnto(branch, newBase, oldBase),
+            ).pipe(
+              Effect.catchTag("GitError", (e) => {
+                const hint =
+                  i === 0 ? "stacked sync" : `stacked sync --from ${branches[i - 1] ?? trunk}`;
+                return Effect.fail(
+                  new StackError({
+                    code: ErrorCode.REBASE_CONFLICT,
+                    message: `Rebase conflict on ${branch}: ${e.message}\n\nResolve conflicts, then run:\n  git rebase --continue\n  ${hint}`,
+                  }),
+                );
+              }),
+            );
+            yield* stacks.updateSyncedOnto(branch, newBaseTip);
+            yield* withSpinner(`Pushing ${branch}`, git.push(branch, { force: true }));
+            results.push({ name: branch, action: "rebased", base: newBase });
+          }
         }
       }).pipe(
         Effect.ensuring(

package/src/services/Git.ts

@@ -37,6 +37,14 @@ export class GitService extends ServiceMap.Service<
     readonly commitAmend: (options?: { edit?: boolean }) => Effect.Effect<void, GitError>;
     readonly fetch: (remote?: string) => Effect.Effect<void, GitError>;
     readonly deleteRemoteBranch: (branch: string) => Effect.Effect<void, GitError>;
+    readonly treeMergeSync: (opts: {
+      branch: string;
+      branchHead: string;
+      oldBase: string;
+      newBase: string;
+      message: string;
+    }) => Effect.Effect<{ action: "merged" | "up-to-date" | "conflict" }, GitError>;
+    readonly supportsTreeMerge: () => boolean;
   }
 >()("@cvr/stacked/services/Git/GitService") {
   static layer: Layer.Layer<GitService> = Layer.sync(GitService, () => {
@@ -223,6 +231,9 @@ export class GitService extends ServiceMap.Service<
 
       deleteRemoteBranch: (branch) =>
         run(["push", "origin", "--delete", branch]).pipe(Effect.asVoid),
+
+      treeMergeSync: () => Effect.succeed({ action: "conflict" as const }),
+      supportsTreeMerge: () => false,
     };
   });
 
@@ -249,6 +260,8 @@ export class GitService extends ServiceMap.Service<
       commitAmend: () => Effect.void,
       fetch: () => Effect.void,
       deleteRemoteBranch: () => Effect.void,
+      treeMergeSync: () => Effect.succeed({ action: "conflict" as const }),
+      supportsTreeMerge: () => false,
       ...impl,
     });
 }

package/src/services/GitEs.ts

@@ -359,6 +359,43 @@ export const GitEsLayer = Layer.effect(
           },
           catch: (error) => makeGitError(`es-git.deleteRemoteBranch ${branch}`, error),
         }).pipe(Effect.asVoid),
+
+      treeMergeSync: ({ branch, oldBase, newBase }) =>
+        Effect.try({
+          try: () => {
+            const oldBaseOid = resolveOid(repo, oldBase);
+            const newBaseOid = resolveOid(repo, newBase);
+            const branchRef = refName(branch);
+
+            // Pre-flight: check for conflicts via mergeTrees
+            const oldBaseTree = repo.getCommit(oldBaseOid).tree();
+            const newBaseTree = repo.getCommit(newBaseOid).tree();
+            const branchHeadOid = repo.getReference(branchRef).resolve().target();
+            if (branchHeadOid === null) {
+              return { action: "conflict" as const };
+            }
+            const branchTree = repo.getCommit(branchHeadOid).tree();
+
+            const index = repo.mergeTrees(oldBaseTree, newBaseTree, branchTree);
+            if (index.hasConflicts()) {
+              return { action: "conflict" as const };
+            }
+
+            // Check if anything actually changed
+            if (newBaseOid === oldBaseOid) {
+              return { action: "up-to-date" as const };
+            }
+
+            // Clean merge — execute via rebase (which handles tree writing properly)
+            performRebase(repo, branchRef, oldBaseOid, newBaseOid);
+
+            return { action: "merged" as const };
+          },
+          catch: (error) =>
+            makeGitError(`es-git.treeMergeSync ${branch} ${oldBase} ${newBase}`, error),
+        }),
+
+      supportsTreeMerge: () => true,
     };
   }),
 );

package/src/services/Stack.ts

@@ -22,6 +22,7 @@ const StackRecordSchema = Schema.Struct({
 const BranchRecordSchema = Schema.Struct({
   stack: Schema.String,
   parent: Schema.NullOr(Schema.String),
+  syncedOnto: Schema.optional(Schema.NullOr(Schema.String)),
 });
 
 const StackFileV2Schema = Schema.Struct({
@@ -54,7 +55,14 @@ interface CanonicalStackFile {
   readonly trunk: string;
   readonly stacks: Readonly<Record<string, { readonly root: string }>>;
   readonly branches: Readonly<
-    Record<string, { readonly stack: string; readonly parent: string | null }>
+    Record<
+      string,
+      {
+        readonly stack: string;
+        readonly parent: string | null;
+        readonly syncedOnto?: string | null | undefined;
+      }
+    >
   >;
   readonly mergedBranches: readonly string[];
 }
@@ -224,7 +232,10 @@ const rewriteStackBranches = (
   stackName: string,
   branches: readonly string[],
 ): CanonicalStackFile => {
-  const nextBranches: Record<string, { stack: string; parent: string | null }> = {
+  const nextBranches: Record<
+    string,
+    { stack: string; parent: string | null; syncedOnto?: string | null }
+  > = {
     ...data.branches,
   };
 
@@ -237,9 +248,11 @@ const rewriteStackBranches = (
   for (let i = 0; i < branches.length; i++) {
     const branch = branches[i];
     if (branch === undefined) continue;
+    const existing = data.branches[branch];
     nextBranches[branch] = {
       stack: stackName,
       parent: i === 0 ? null : (branches[i - 1] ?? null),
+      ...(existing?.syncedOnto != null ? { syncedOnto: existing.syncedOnto } : {}),
     };
   }
 
@@ -274,7 +287,10 @@ const renameStackRefs = (
   if (stackRecord === undefined) return data;
 
   const { [oldName]: _, ...restStacks } = data.stacks;
-  const branches: Record<string, { stack: string; parent: string | null }> = {};
+  const branches: Record<
+    string,
+    { stack: string; parent: string | null; syncedOnto?: string | null }
+  > = {};
 
   for (const [branch, record] of Object.entries(data.branches)) {
     branches[branch] = {
@@ -584,6 +600,33 @@ const makeStackService = ({
       });
     }),
 
+    getSyncedOnto: Effect.fn("StackService.getSyncedOnto")(function* (branch: string) {
+      const data = yield* loadData();
+      const record = data.branches[branch];
+      if (record === undefined) return null;
+      return record.syncedOnto ?? null;
+    }),
+
+    updateSyncedOnto: Effect.fn("StackService.updateSyncedOnto")(function* (
+      branch: string,
+      oid: string | null,
+    ) {
+      const data = yield* loadData();
+      const record = data.branches[branch];
+      if (record === undefined) {
+        return yield* new StackError({
+          message: `Branch "${branch}" not found in stack metadata`,
+        });
+      }
+      yield* saveData({
+        ...data,
+        branches: {
+          ...data.branches,
+          [branch]: { ...record, syncedOnto: oid },
+        },
+      });
+    }),
+
     getTrunk: Effect.fn("StackService.getTrunk")(function* () {
       const data = yield* loadData();
       return data.trunk;
@@ -630,6 +673,11 @@ export class StackService extends ServiceMap.Service<
       branch: string,
     ) => Effect.Effect<{ name: string; stack: Stack } | null, StackError>;
     readonly detectTrunkCandidate: () => Effect.Effect<Option.Option<string>, never>;
+    readonly getSyncedOnto: (branch: string) => Effect.Effect<string | null, StackError>;
+    readonly updateSyncedOnto: (
+      branch: string,
+      oid: string | null,
+    ) => Effect.Effect<void, StackError>;
     readonly getTrunk: () => Effect.Effect<string, StackError>;
     readonly setTrunk: (name: string) => Effect.Effect<void, StackError>;
   }