The run-id branch an agent branched away from goes with its checkout (#1657) (#1658)

* The run-id branch an agent branched away from goes with its checkout (#1657)

A run starts on `tf-agent-<id>`; the system prompt then has the agent create
`tf-<name>` and check it out, so the rename never applies and the run-id
branch stays behind at the commit the run began from — one per run, forever.
The rig had nine after two days, two of them pushed to origin by the old
teardown.

Removal now judges the run-id branch alongside the checkout's: when the
checkout ended on another branch that contains it, everything it holds is held
again, and it goes with the checkout. One carrying a commit the kept branch
lacks stays. Decided before either delete, since the containment reads both
refs. The result and the removal lines name every branch that went.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* The guard test branches from the init commit, not from a branch named main (#1657)

CI's git init names its first branch master.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: suleimansh

FEATURES-SPEC.md

@@ -129,7 +129,7 @@ happens while nobody is at the keyboard.
 - CI watch: merge a PR once its checks pass
 - CI watch: one fix agent per red head commit, max two attempts
 - Reclaim the checkout of an agent whose work is on the remote — never by publishing what a `handoff: local` agent refused to
-- An agent that committed nothing leaves no branch behind: its empty branch goes with its checkout, never pushed, so a pinned routine is not stood down by its own last run
+- An agent that committed nothing leaves no branch behind: its empty branch goes with its checkout, never pushed, so a pinned routine is not stood down by its own last run — and the run-id branch it started on goes too, once the branch it moved to holds everything the run-id branch did
 - A directory under `branches/` that git does not know as a worktree is never committed, pushed, linked or deleted through — it is reported and left alone, so a leftover can never stand in for your own checkout
 - Release a pinned routine branch left behind by a closed PR — before the schedule fires the routine, and before its "Run now" does
 - The agent drains its own TODO backlog, one entry per turn

packages/the-framework/src/daemon-runtime.ts

@@ -40,6 +40,7 @@ import { tailEvents, tailAgentEvents } from './dashboard-rpc/events-tail.js'
 import { resolveUserDir } from './agent-archive.js'
 import { withDataBranch } from './data-branch.js'
 import { removeProjectWorktree } from './worktrees.js'
+import { describeDeleted } from './merged-worktrees.js'
 import { reconcileBranchLinks } from './branch-links.js'
 import { scopedKey, parseScopedKey, keyBelongsTo } from './runtime-keys.js'
 import { addProject, listProjects, projectId } from './registry.js'
@@ -607,8 +608,8 @@ export function createProjectRuntime({ cwd, env, binPath, retryDelayMs, driverPr
         // never depends on the caller having one.
         const outcome = await removeProjectWorktree(projectCwd, agentId ?? agentIdFromWorktreeDir(basename(worktree)))
         if (!outcome.ok) console.log(`[framework] keeping worktree ${worktree}: ${outcome.error}`)
-        else if (outcome.branchDeleted)
-          console.log(`[framework] removed worktree ${worktree} and its branch ${outcome.branchDeleted}: the branch held nothing the remote lacks`)
+        else if (outcome.branchesDeleted)
+          console.log(`[framework] removed worktree ${worktree} and ${describeDeleted(outcome.branchesDeleted)}: nothing on it is missing elsewhere`)
       } catch {
         // A worktree we could not retire is a worktree left on disk, which is the safe direction.
       }

packages/the-framework/src/merged-worktrees.test.ts

@@ -106,7 +106,7 @@ test('the sweep says what it removed and what it kept, per project (#1036)', asy
   const lines: string[] = []
   const results: Record<string, MergedSweepResult> = {
     '/a': { removed: [{ agentId: 'r1' }], failed: [] },
-    '/b': { removed: [{ agentId: 'r2', branchDeleted: 'tf-triage-quick' }], failed: [{ agentId: 'r3', error: 'not on the remote' }] },
+    '/b': { removed: [{ agentId: 'r2', branchesDeleted: ['tf-triage-quick', 'tf-agent-r2'] }], failed: [{ agentId: 'r3', error: 'not on the remote' }] },
   }
   const sweep = startMergedWorktreeSweep({
     projects: async () => [{ path: '/a' }, { path: '/b' }],
@@ -117,7 +117,7 @@ test('the sweep says what it removed and what it kept, per project (#1036)', asy
   sweep.stop()
   assert.match(lines[0] ?? '', /removed the worktree for session r1: its branch is on the remote/)
   assert.match(lines[0] ?? '', /The branch and the session are kept/, 'a checkout vanishing silently reads as a bug')
-  assert.match(lines[1] ?? '', /removed the worktree for session r2 and its branch tf-triage-quick: the branch held nothing/, 'a branch going says so (#1650)')
+  assert.match(lines[1] ?? '', /removed the worktree for session r2 and its branches tf-triage-quick and tf-agent-r2: nothing on it is missing elsewhere/, 'branches going say so (#1650, #1657)')
   assert.match(lines[2] ?? '', /kept the worktree for session r3: not on the remote/)
 })
 

packages/the-framework/src/merged-worktrees.ts

@@ -23,8 +23,8 @@ import { repoHasRemote, worktreePath } from './store/index.js'
 export interface RemovedWorktree {
   /** The agent id, which is also the worktree's directory name. */
   agentId: string
-  /** The run branch that went with it, when it held nothing the remote lacks (#1650). */
-  branchDeleted?: string
+  /** Branches that went with it: one holding nothing the remote lacks (#1650), a run-id branch the kept branch contains (#1657). */
+  branchesDeleted?: string[]
 }
 
 /** A worktree the sweep tried to reclaim and could not, and why. */
@@ -87,12 +87,17 @@ export async function removeMergedWorktrees(cwd: string, deps: MergedSweepDeps =
   }
   for (const row of rows) {
     const outcome = await withAgentLock(worktreePath(cwd, row.agentId), () => remove(cwd, row.agentId))
-    if (outcome.ok) result.removed.push({ agentId: row.agentId, ...(outcome.branchDeleted ? { branchDeleted: outcome.branchDeleted } : {}) })
+    if (outcome.ok) result.removed.push({ agentId: row.agentId, ...(outcome.branchesDeleted ? { branchesDeleted: outcome.branchesDeleted } : {}) })
     else result.failed.push({ agentId: row.agentId, error: outcome.error })
   }
   return result
 }
 
+/** `its branch x` / `its branches x and y`, for the removal line. */
+export function describeDeleted(branches: readonly string[]): string {
+  return branches.length === 1 ? `its branch ${branches[0]}` : `its branches ${branches.join(' and ')}`
+}
+
 /** A running sweep, in the shape the daemon's other background services use. */
 export interface MergedWorktreeSweep {
   /** Run one sweep now, awaiting it. Exposed for tests and for a caller that wants it on demand. */
@@ -144,8 +149,8 @@ export function startMergedWorktreeSweep(opts: MergedSweepOptions): MergedWorktr
       for (const item of removed) {
         announced.delete(item.agentId)
         opts.log(
-          item.branchDeleted
-            ? `[framework] removed the worktree for session ${item.agentId} and its branch ${item.branchDeleted}: the branch held nothing the remote lacks. The session is kept.`
+          item.branchesDeleted
+            ? `[framework] removed the worktree for session ${item.agentId} and ${describeDeleted(item.branchesDeleted)}: nothing on it is missing elsewhere. The session is kept.`
             : `[framework] removed the worktree for session ${item.agentId}: its branch is on the remote. The branch and the session are kept.`,
         )
       }

packages/the-framework/src/worktrees.test.ts

@@ -217,7 +217,7 @@ test('a run branch holding nothing the remote lacks goes with its checkout, unpu
     const now = new Date().toISOString()
     await mkdir(join(path, '.the-framework'), { recursive: true })
     await writeFile(join(path, '.the-framework', 'agent.json'), JSON.stringify({ status: 'done', id: RUN_ID, startedAt: now, updatedAt: now }))
-    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true, branchDeleted: branch })
+    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true, branchesDeleted: [branch] })
     await assert.rejects(() => stat(path), 'the checkout is gone')
     await assert.rejects(() => git(['rev-parse', '--verify', `refs/remotes/origin/${branch}`], repo), 'nothing reached origin')
     await assert.rejects(() => git(['rev-parse', '--verify', `refs/heads/${branch}`], repo), 'and the branch went with the checkout')
@@ -276,7 +276,9 @@ test("a leftover checkout on a branch the framework did not mint keeps that bran
     await git(['checkout', '-q', '-b', 'release'], path)
     await mkdir(join(repo, '.git', 'info'), { recursive: true })
     await writeFile(join(repo, '.git', 'info', 'exclude'), '.the-framework/\n')
-    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true })
+    // The user's branch stays; the run-id branch it was cut from is ours and holds nothing
+    // `release` does not, so that one goes (#1657).
+    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true, branchesDeleted: [agentBranchName(RUN_ID)] })
     await assert.rejects(() => stat(path), 'the checkout is gone')
     await git(['rev-parse', '--verify', 'refs/heads/release'], repo)
   } finally {
@@ -311,6 +313,75 @@ test("a branches/ directory that is not a git worktree is refused before any git
   }
 })
 
+test('the run-id branch the agent branched away from goes with the checkout when the kept branch contains it (#1657)', async () => {
+  // The system prompt has the agent create `tf-<name>` rather than be renamed onto it, so every
+  // run leaves `tf-agent-<id>` behind at the commit it started from — nine of them on the rig.
+  const { repo, path, branch: runBranch } = await repoWithDirtyWorktree()
+  const git = nodeGitRunner()
+  try {
+    await git(['push', '-q', 'origin', 'HEAD:main'], repo)
+    await git(['checkout', '-q', '-b', 'tf-cool-name'], path)
+    await git(['config', 'user.email', 't@t'], path)
+    await git(['config', 'user.name', 't'], path)
+    await git(['add', '-A'], path)
+    await git(['commit', '-q', '-m', 'work'], path)
+    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true, branchesDeleted: [runBranch] })
+    assert.match(await git(['show', 'tf-cool-name:index.html'], repo), /Welcome!/, 'the work branch stays, pushed')
+    assert.match(await git(['show', 'refs/remotes/origin/tf-cool-name:index.html'], repo), /Welcome!/)
+    await assert.rejects(() => git(['rev-parse', '--verify', `refs/heads/${runBranch}`], repo), 'the run-id branch is gone')
+    await assert.rejects(() => git(['rev-parse', '--verify', `refs/remotes/origin/${runBranch}`], repo), 'and was never pushed')
+  } finally {
+    await rm(repo, { recursive: true, force: true })
+  }
+})
+
+test('a commitless triage leaves neither its pinned branch nor its run-id branch (#1650, #1657)', async () => {
+  // The rig case in full: the checkout ends on an empty `tf-triage-quick`, branched off an
+  // equally empty run-id branch. Both hold nothing; both go; nothing is pushed.
+  const { repo, path, branch: runBranch } = await repoWithDirtyWorktree()
+  const git = nodeGitRunner()
+  try {
+    await git(['push', '-q', 'origin', 'HEAD:main'], repo)
+    await git(['checkout', '--', '.'], path)
+    await git(['checkout', '-q', '-b', 'tf-triage-quick'], path)
+    await mkdir(join(repo, '.git', 'info'), { recursive: true })
+    await writeFile(join(repo, '.git', 'info', 'exclude'), '.the-framework/\n')
+    const now = new Date().toISOString()
+    await mkdir(join(path, '.the-framework'), { recursive: true })
+    await writeFile(join(path, '.the-framework', 'agent.json'), JSON.stringify({ status: 'done', id: RUN_ID, startedAt: now, updatedAt: now }))
+    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true, branchesDeleted: ['tf-triage-quick', runBranch] })
+    assert.equal((await git(['branch', '--list', 'tf-*'], repo)).trim(), '', 'no tf- branch is left')
+    assert.equal((await git(['ls-remote', '--heads', 'origin', 'tf-*'], repo)).trim(), '', 'and none reached origin')
+  } finally {
+    await rm(repo, { recursive: true, force: true })
+  }
+})
+
+test('a run-id branch carrying a commit the kept branch lacks stays (#1657)', async () => {
+  // The agent committed on the run-id branch, then branched from main and went on from there.
+  // The run-id branch holds something the kept branch does not, so it is not the framework's
+  // to delete.
+  const { repo, path, branch: runBranch } = await repoWithDirtyWorktree()
+  const git = nodeGitRunner()
+  try {
+    await git(['push', '-q', 'origin', 'HEAD:main'], repo)
+    await git(['config', 'user.email', 't@t'], path)
+    await git(['config', 'user.name', 't'], path)
+    await git(['add', '-A'], path)
+    await git(['commit', '-q', '-m', 'early work on the run-id branch'], path)
+    // From the init commit, not from `main`: CI's `git init` names its branch `master`.
+    const init = (await git(['rev-parse', 'HEAD'], repo)).trim()
+    await git(['checkout', '-q', '-b', 'tf-other', init], path)
+    await writeFile(join(path, 'other.txt'), 'later\n')
+    await git(['add', '-A'], path)
+    await git(['commit', '-q', '-m', 'later work elsewhere'], path)
+    assert.deepEqual(await removeProjectWorktree(repo, RUN_ID), { ok: true })
+    assert.match(await git(['show', `${runBranch}:index.html`], repo), /Welcome!/, 'the early commit is still on the run-id branch')
+  } finally {
+    await rm(repo, { recursive: true, force: true })
+  }
+})
+
 test('a worktree whose work cannot be committed is refused, not force-removed (#982)', async () => {
   const { repo, path } = await repoWithDirtyWorktree()
   try {

packages/the-framework/src/worktrees.ts

@@ -10,6 +10,7 @@ import {
   worktreeClean,
   isWorktreeRoot,
   currentBranch,
+  agentBranchName,
   removeWorktree,
   deleteBranch,
   pruneWorktrees,
@@ -57,8 +58,12 @@ export interface PruneResult {
 export type RemoveResult =
   | {
       ok: true
-      /** The run branch went with the checkout, because it held nothing the remote lacks (#1650). */
-      branchDeleted?: string
+      /**
+       * Branches that went with the checkout: the branch it was on, when that held nothing the
+       * remote lacks (#1650); the run-id branch the agent branched away from, when everything on
+       * it is in the branch that stays (#1657). Absent when nothing went.
+       */
+      branchesDeleted?: string[]
     }
   | { ok: false; error: string }
 
@@ -231,11 +236,25 @@ export async function removeProjectWorktree(
     await removeWorktree(cwd, path)
     await pruneWorktrees(cwd)
     // After the checkout: git refuses to delete a branch a worktree still has checked out.
+    // The run-id branch the run started on (#1657). The system prompt has the agent *create*
+    // `tf-<name>` rather than be renamed onto it, so the checkout ends elsewhere and the run-id
+    // branch stays behind at the commit the run began from — one per run, forever. It goes when
+    // the checkout's branch contains it: then everything it holds is held again by a branch that
+    // either stays or (an empty one, above) is itself inside the remote. A run-id branch the agent
+    // committed on and then abandoned for a branch from elsewhere is not contained, and stays.
+    // Decided before anything is deleted: the containment reads both refs.
+    const runBranch = agentBranchName(agentId)
+    const runBranchGoes = runBranch !== branch && (await branchContains(cwd, branch, runBranch))
+    const deleted: string[] = []
     if (emptyBranch) {
       await deleteBranch(cwd, branch)
-      return { ok: true, branchDeleted: branch }
+      deleted.push(branch)
     }
-    return { ok: true }
+    if (runBranchGoes) {
+      await deleteBranch(cwd, runBranch)
+      deleted.push(runBranch)
+    }
+    return deleted.length ? { ok: true, branchesDeleted: deleted } : { ok: true }
   } catch (err) {
     return { ok: false, error: errorMessage(err) }
   }
@@ -276,6 +295,15 @@ async function branchHoldsNothing(cwd: string, path: string, branch: string): Pr
   )
 }
 
+/** Whether `inner` exists and is an ancestor of (or equal to) `outer` — everything on it is on `outer` too. */
+async function branchContains(cwd: string, outer: string, inner: string): Promise<boolean> {
+  const git = nodeGitRunner()
+  return git(['merge-base', '--is-ancestor', `refs/heads/${inner}`, `refs/heads/${outer}`], cwd).then(
+    () => true,
+    () => false,
+  )
+}
+
 /**
  * The meta the keep decision reads: the live copy in the checkout, else the archived one.
  *