One triage at a time through a routine lock on tf-data, not a pinned branch (#1659)

The pinned branch stopped guarding anything once a triage committed nothing
on it (#1644): it never reached origin, and locally it was a name the agent
checked from its prompt — every false abort spent a started agent.

The sweep now takes routines/<name>.lock.md on the data branch before a
triage starts, through the same write funnel as ticket claims, and drops it
when the run ends, whatever the ending. A held lock stands the routine down
naming the holder (machine + mint time) with no agent started. Fixed 4 h
expiry, no heartbeat; a daemon frees its own locks on boot when their runs
are gone. Run now reaches the same path via { lock } (was { pinned }).

Gone with it: the prompts' "branch already exists → abort" line,
stale-branch.ts and its sweep release, the pinnedBranch plumbing.

Author: suleimansh

FEATURES-SPEC.md

@@ -129,9 +129,9 @@ 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 — and the run-id branch it started on goes too, once the branch it moved to holds everything the run-id branch did
+- An agent that committed nothing leaves no branch behind: its empty branch goes with its checkout, never pushed — 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
+- One triage at a time, across machines: a routine lock (`routines/<name>.lock.md` on the data branch) taken by the daemon before the run starts and released when it ends, whatever the ending; a held lock stands the routine down naming the machine holding it, with no agent spent; a lock left by a dead machine expires after four hours, and a daemon frees its own on boot
 - The agent drains its own TODO backlog, one entry per turn
 
 ## Spending

packages/the-framework/dashboard/components/RoutineWork.test.tsx

@@ -194,22 +194,21 @@ describe('RoutineWork (#1159)', () => {
     expect((await hoverTooltip(await runNowOf(PLAN_JOB))).textContent).toMatch(/Starts up to 1 agent in gemstack/)
   })
 
-  // #1643: a routine pinned to a branch goes through the sweep too — one agent still, but the
-  // sweep releases a stale copy of its branch before the start, and a plain start never did: the
-  // agent read the leftover as a triage already pending and aborted, on every click.
-  test("a pinned routine's Run now asks the sweep for it by its branch, not a plain start (#1643)", async () => {
-    const pinned = AUTO_PM_ROUTINES.filter(job => job.pinnedBranch !== undefined)
-    expect(pinned.length).toBeGreaterThan(0)
-    renderCard()
-    for (const job of pinned) {
+  // #1643/#1659: a routine that holds a lock goes through the sweep too — one agent still, but
+  // the sweep takes the lock before the start, and a plain start would run unguarded.
+  test("a locked routine's Run now asks the sweep for it by its lock, not a plain start (#1643/#1659)", async () => {
+    const locked = AUTO_PM_ROUTINES.filter(job => job.lock !== undefined)
+    expect(locked.length).toBeGreaterThan(0)
+    renderCard()
+    for (const job of locked) {
       fireEvent.click(await runNowOf(job))
-      // By the branch the job declares, never its name, and scoped to the picked project like
+      // By the lock the job declares, never its name, and scoped to the picked project like
       // the plan click: the routine is that project's own work.
       await waitFor(() =>
-        expect(sendAutoPmSweep).toHaveBeenCalledWith({ only: { pinned: job.pinnedBranch }, projectId: 'p1' }),
+        expect(sendAutoPmSweep).toHaveBeenCalledWith({ only: { lock: job.lock }, projectId: 'p1' }),
       )
     }
-    expect(sendAutoPmSweep).toHaveBeenCalledTimes(pinned.length)
+    expect(sendAutoPmSweep).toHaveBeenCalledTimes(locked.length)
     expect(start).not.toHaveBeenCalled()
   })
 

packages/the-framework/dashboard/components/RoutineWork.tsx

@@ -53,22 +53,21 @@ const NO_PROJECTS: ProjectSummary[] = []
 /**
  * The sweep a routine's Run now asks for, when it is a sweep rather than a plain start — or
  * nothing, for the routine a plain start serves exactly. Decided by what the job declares about
- * itself (it drains, fans out, or pins a branch), never by its name, so a renamed routine keeps
+ * itself (it drains, fans out, or holds a lock), never by its name, so a renamed routine keeps
  * its path.
  *
  * The two that fan out (#1204) go because only the sweep can: it claims the work before each
  * agent starts — a queue entry for a drain, a ticket lock for planning — and a plain start could
- * only ever be one agent. A routine pinned to a branch (#1643) goes for the sweep's other
- * preparation: it releases a stale copy of that branch before the start, and without it the
- * agent read the leftover as a triage already pending and aborted, on every click.
+ * only ever be one agent. A routine that holds a lock (#1643/#1659) goes for the same claim: the
+ * sweep takes `routines/<name>.lock.md` before the start, and a plain start would run unguarded.
  *
  * The drain visits every project, which is what its tooltip says and why it sends no id. The
  * rest are the picked project's own work, so they carry one.
  */
 function narrowedSweep(job: AutoPmJob, projectId: string): { only: AutoPmOnly; projectId?: string } | undefined {
   if (job.drains) return { only: 'drain' }
   if (job.fansOut) return { only: 'plan', projectId }
-  if (job.pinnedBranch !== undefined) return { only: { pinned: job.pinnedBranch }, projectId }
+  if (job.lock !== undefined) return { only: { lock: job.lock }, projectId }
   return undefined
 }
 

packages/the-framework/prompts/presets/triage_consensual.md

@@ -3,4 +3,3 @@
 2. Add tickets to TODO_AGENTS.md
 
 Always set <SESSION_NAME> to triage-consensual
-- If branch tf-<SESSION_NAME> already exists, abort and tell user that the branch already exists and that triage is already pending.

packages/the-framework/prompts/presets/triage_quick.md

@@ -4,4 +4,3 @@ Look at `tickets/*` and choose tickets to work on next:
   - With sensible prioritization, and consider bumping the priority of lowest effort tickets (e.g. to make `effort: 0` the next tasks agents work on)
 
 Always set <SESSION_NAME> to triage-quick
-- If branch tf-<SESSION_NAME> already exists, abort and tell user the branch already exists and triage is already pending.

packages/the-framework/src/auto-pm.test.ts

@@ -1476,115 +1476,202 @@ test('a drain-only sweep works the queue and never borrows the tick for the rota
   assert.equal(empty.report().outcomes[0]?.message, 'the queue is empty, so there is nothing to drain')
 })
 
-test('a pinned job has its stale branch released before it fires (#1293)', async () => {
-  const order: string[] = []
+// #1659: the routine lock. A triage rewrites the shared queue and may take hours, so the sweep
+// takes `routines/<name>.lock.md` on the data branch before the start — the daemon decides, and
+// no agent is spent finding out — and gives it back when the run ends, whatever the ending.
+
+const LOCKED_JOB: AutoPmJob = {
+  name: 'triage-quick',
+  prompt: 'Triage.',
+  label: 'Triage quick wins',
+  lock: 'triage-quick',
+}
+
+/** A lock that behaves like the real one: taken once, standing every later taker down until released. */
+function fakeLock(order: string[] = []) {
+  let held = false
+  const lockRoutine: AutoPmDeps['lockRoutine'] = async (_project, lock) => {
+    order.push(`lock:${lock}`)
+    if (held) return { ok: false, reason: `${lock} is already running on laptop (since T0)` }
+    held = true
+    return { ok: true }
+  }
+  const releaseRoutine: AutoPmDeps['releaseRoutine'] = async (_project, lock) => {
+    order.push(`release:${lock}`)
+    held = false
+    return true
+  }
+  return { order, lockRoutine, releaseRoutine, isHeld: () => held }
+}
+
+test('a locked job takes its lock before it starts, and releases it when the run ends (#1659)', async () => {
+  const lock = fakeLock()
+  let settled = false
   const { loop } = harness({
-    jobs: [{ name: 'triage-quick', prompt: 'p', pinnedBranch: 'the-framework/triage-quick' }],
-    releasePinned: async (_project, branch) => {
-      order.push(`release:${branch}`)
-    },
+    jobs: [LOCKED_JOB],
+    cooldownMs: 0,
+    lockRoutine: lock.lockRoutine,
+    releaseRoutine: lock.releaseRoutine,
     start: async (_project, job) => {
-      order.push(`start:${job.name}`)
+      lock.order.push(`start:${job.name}`)
       return 'run-1'
     },
+    promote: async () => ({ settled, promoted: false }),
+  })
+  await loop.tick()
+  assert.deepEqual(lock.order, ['lock:triage-quick', 'start:triage-quick'])
+  // Still running: the lock stands, and the next sweep stands down on it rather than starting another.
+  await loop.tick()
+  assert.deepEqual(lock.order, ['lock:triage-quick', 'start:triage-quick', 'lock:triage-quick'])
+  assert.equal(loop.report().outcomes[0]?.message, 'triage-quick is already running on laptop (since T0)')
+  settled = true
+  await loop.tick()
+  loop.stop()
+  // Released on the ending itself — no `no-commits` condition, no PR: a triage never opens one —
+  // and the same sweep may take it again.
+  assert.deepEqual(lock.order.slice(3), ['release:triage-quick', 'lock:triage-quick', 'start:triage-quick'])
+})
+
+test('a held lock stands the job down naming its holder, with no agent started (#1659)', async () => {
+  const { loop, ran } = harness({
+    jobs: [LOCKED_JOB],
+    cooldownMs: 0,
+    lockRoutine: async () => ({ ok: false, reason: 'triage-quick is already running on other-machine (since 2026-08-23T10:00:00.000Z)' }),
   })
   await loop.tick()
   loop.stop()
-  assert.deepEqual(order, ['release:the-framework/triage-quick', 'start:triage-quick'])
+  assert.deepEqual(ran, [])
+  assert.equal(loop.report().outcomes[0]?.started, false)
+  assert.equal(loop.report().outcomes[0]?.message, 'triage-quick is already running on other-machine (since 2026-08-23T10:00:00.000Z)')
 })
 
-test('an unpinned job never asks for a release, and a failing release does not stop the start (#1293)', async () => {
+test('a refused start gives the lock back, and a failed release is retried next sweep (#1659)', async () => {
   const releases: string[] = []
-  const unpinned = harness({
-    releasePinned: async (_project, branch) => {
-      releases.push(branch)
+  const refused = harness({
+    jobs: [LOCKED_JOB],
+    cooldownMs: 0,
+    lockRoutine: async () => ({ ok: true }),
+    releaseRoutine: async (_project, lock) => {
+      releases.push(lock)
+      return true
     },
+    start: async () => undefined,
   })
-  await unpinned.loop.tick()
-  unpinned.loop.stop()
-  assert.deepEqual(releases, [])
-  assert.deepEqual(unpinned.ran, ['first'])
-
-  // A release that could not happen leaves the routine exactly as jammed as it was; the job's own
-  // abort guard decides, exactly as before the seam existed.
-  const failing = harness({
-    jobs: [{ name: 'triage-quick', prompt: 'p', pinnedBranch: 'the-framework/triage-quick' }],
-    releasePinned: async () => {
-      throw new Error('gh is down')
+  await refused.loop.tick()
+  refused.loop.stop()
+  assert.deepEqual(releases, ['triage-quick'], 'no run will ever release a lock taken for a start that never happened')
+
+  let ok = false
+  const lock = fakeLock()
+  const flaky = harness({
+    jobs: [LOCKED_JOB],
+    cooldownMs: 0,
+    lockRoutine: lock.lockRoutine,
+    releaseRoutine: async (project, name) => (ok ? lock.releaseRoutine!(project, name) : false),
+    promote: async () => ({ settled: true, promoted: false }),
+  })
+  await flaky.loop.tick()
+  await flaky.loop.tick()
+  assert.deepEqual(flaky.ran, ['triage-quick'], 'the lock still stands while its release has not landed')
+  assert.ok(lock.isHeld())
+  ok = true
+  await flaky.loop.tick()
+  flaky.loop.stop()
+  assert.deepEqual(flaky.ran, ['triage-quick', 'triage-quick'], 'the retried release lands, and the routine may run again')
+})
+
+test('an unlocked job never asks for a lock, and a loop wired without the seam starts unguarded (#1659)', async () => {
+  const locks: string[] = []
+  const unlocked = harness({
+    lockRoutine: async (_project, lock) => {
+      locks.push(lock)
+      return { ok: true }
     },
   })
-  await failing.loop.tick()
-  failing.loop.stop()
-  assert.deepEqual(failing.ran, ['triage-quick'])
+  await unlocked.loop.tick()
+  unlocked.loop.stop()
+  assert.deepEqual(locks, [])
+  assert.deepEqual(unlocked.ran, ['first'])
+
+  const unwired = harness({ jobs: [LOCKED_JOB] })
+  await unwired.loop.tick()
+  unwired.loop.stop()
+  assert.deepEqual(unwired.ran, ['triage-quick'])
 })
 
-// #1643: Run now on a pinned routine reaches the same release-then-start the sweep does. It used
-// to be a plain start outside the sweep, so a leftover copy of the branch — which the sweep
-// releases before firing — made the agent abort as "triage already pending" on every click.
+test("a previous daemon's dead locks are released on the project's first sweep only (#1659)", async () => {
+  const boots: string[] = []
+  const { loop } = harness({
+    releaseDeadLocks: async project => {
+      boots.push(project.id)
+    },
+  })
+  await loop.tick()
+  await loop.tick()
+  loop.stop()
+  assert.deepEqual(boots, ['p1'])
+})
 
-const PINNED_JOB: AutoPmJob = {
-  name: 'triage-quick',
-  prompt: 'Triage.',
-  label: 'Triage quick wins',
-  pinnedBranch: 'the-framework/triage-quick',
-}
+// #1643: Run now on a locked routine reaches the same lock-then-start the sweep does. It used to
+// be a plain start outside the sweep, which ran unguarded.
 
-test('a sweep narrowed to a pinned job releases its branch, then starts exactly one agent (#1643)', async () => {
+test('a sweep narrowed to a locked job takes its lock, then starts exactly one agent (#1643/#1659)', async () => {
   const order: string[] = []
   const { loop } = harness({
     // The rotation is on another job's turn, so a tick that ignored the narrowing would start
-    // that one instead — the release-then-start below is the click's doing, not the cycle's.
-    jobs: [{ name: 'update', prompt: 'Update.' }, PINNED_JOB],
+    // that one instead — the lock-then-start below is the click's doing, not the cycle's.
+    jobs: [{ name: 'update', prompt: 'Update.' }, LOCKED_JOB],
     cooldownMs: 0,
     // Room for three, so a single start is the routine's own shape and not the cap's doing.
     concurrency: async () => 3,
-    releasePinned: async (_project, branch) => {
-      order.push(`release:${branch}`)
+    lockRoutine: async (_project, lock) => {
+      order.push(`lock:${lock}`)
+      return { ok: true }
     },
     start: async (_project, job) => {
       order.push(`start:${job.name}`)
       return `run-${order.length}`
     },
   })
-  await loop.tick({ onDemand: true, only: { pinned: 'the-framework/triage-quick' }, projectId: 'p1' })
+  await loop.tick({ onDemand: true, only: { lock: 'triage-quick' }, projectId: 'p1' })
   loop.stop()
-  assert.deepEqual(order, ['release:the-framework/triage-quick', 'start:triage-quick'])
+  assert.deepEqual(order, ['lock:triage-quick', 'start:triage-quick'])
 })
 
-test('a switched-off pinned routine stands the click down, and so does every other gate (#1643)', async () => {
-  const off = harness({ jobs: [PINNED_JOB], cooldownMs: 0, optedOut: async () => ['triage-quick'] })
-  await off.loop.tick({ onDemand: true, only: { pinned: 'the-framework/triage-quick' }, projectId: 'p1' })
+test('a switched-off locked routine stands the click down, and so does every other gate (#1643)', async () => {
+  const off = harness({ jobs: [LOCKED_JOB], cooldownMs: 0, optedOut: async () => ['triage-quick'] })
+  await off.loop.tick({ onDemand: true, only: { lock: 'triage-quick' }, projectId: 'p1' })
   off.loop.stop()
   assert.deepEqual(off.ran, [], 'an unticked box is not overridden by the click')
   assert.equal(off.loop.report().outcomes[0]?.message, 'Triage quick wins is switched off')
 
-  // A branch nothing pins is said as such, not as a setting the user could go and undo.
-  const unknown = harness({ jobs: [PINNED_JOB], cooldownMs: 0 })
-  await unknown.loop.tick({ onDemand: true, only: { pinned: 'the-framework/nobody' }, projectId: 'p1' })
+  // A lock nothing holds is said as such, not as a setting the user could go and undo.
+  const unknown = harness({ jobs: [LOCKED_JOB], cooldownMs: 0 })
+  await unknown.loop.tick({ onDemand: true, only: { lock: 'nobody' }, projectId: 'p1' })
   unknown.loop.stop()
   assert.deepEqual(unknown.ran, [])
-  assert.equal(unknown.loop.report().outcomes[0]?.message, 'no routine is pinned to the-framework/nobody')
+  assert.equal(unknown.loop.report().outcomes[0]?.message, 'no routine holds the nobody lock')
 
   // The click skips the master switch and the cooldown, not the cap (#1204/#1642).
-  const capped = harness({ jobs: [PINNED_JOB], cooldownMs: 0, activeAgents: () => ['run-live (pid 111)'] })
-  await capped.loop.tick({ onDemand: true, only: { pinned: 'the-framework/triage-quick' }, projectId: 'p1' })
+  const capped = harness({ jobs: [LOCKED_JOB], cooldownMs: 0, activeAgents: () => ['run-live (pid 111)'] })
+  await capped.loop.tick({ onDemand: true, only: { lock: 'triage-quick' }, projectId: 'p1' })
   capped.loop.stop()
   assert.deepEqual(capped.ran, [], 'a live agent at the cap holds the click like it holds the sweep')
 })
 
-test('a sweep narrowed to a pinned job never falls through to the drain or another rotation job (#1643)', async () => {
+test('a sweep narrowed to a locked job never falls through to the drain or another rotation job (#1643)', async () => {
   // The queue is full, so the queue-picked mode would drain; the rotation is on another job's
-  // turn, so the index would fire that one. The click named the pinned routine and gets it alone
+  // turn, so the index would fire that one. The click named the locked routine and gets it alone
   // — and the scheduled tick after it still gets the rotation job it was owed.
   const other: AutoPmJob = { name: 'update', prompt: 'Update.' }
   let entries = ['work one']
   const { loop, ran } = harness({
-    jobs: [other, PINNED_JOB],
+    jobs: [other, LOCKED_JOB],
     cooldownMs: 0,
     queue: async () => entries,
     drainJob: { name: 'drain', prompt: 'Work the queue.', drains: true },
   })
-  await loop.tick({ onDemand: true, only: { pinned: 'the-framework/triage-quick' }, projectId: 'p1' })
+  await loop.tick({ onDemand: true, only: { lock: 'triage-quick' }, projectId: 'p1' })
   assert.deepEqual(ran, ['triage-quick'], 'neither the full queue nor the rotation index took the click')
   entries = []
   await loop.tick()
@@ -1602,15 +1689,12 @@ test('only the drain job lands its own PRs (#1216)', () => {
   }
 })
 
-test('the triage jobs declare exactly the branch their prompts pin (#1293)', () => {
-  const pinned = AUTO_PM_JOBS.filter(job => job.pinnedBranch !== undefined)
-  assert.deepEqual(pinned.map(job => job.name), ['triage-quick', 'triage-consensual'])
-  for (const job of pinned) {
-    // The release targets the branch the prompt's abort guard tests, so the two must not drift.
-    assert.equal(job.pinnedBranch, `tf-${job.name}`)
-    assert.ok(
-      job.prompt.includes(`Always set <SESSION_NAME> to ${job.name}`),
-      `${job.name} must pin the session name its release targets`,
-    )
+test('the triage jobs hold a lock named after them, and their prompts no longer abort on a branch (#1659)', () => {
+  const locked = AUTO_PM_JOBS.filter(job => job.lock !== undefined)
+  assert.deepEqual(locked.map(job => job.name), ['triage-quick', 'triage-consensual'])
+  for (const job of locked) {
+    assert.equal(job.lock, job.name)
+    // The daemon decides; the prompt's "branch already exists → abort" spent an agent to find out.
+    assert.ok(!job.prompt.includes('already exists'), `${job.name} must not carry the branch abort`)
   }
 })