Three small fixes: the shared checkout's index lock, the website build, a dead module (#1791)

The daemon's data sync and the scheduler's tick each write .branches/agent-data
from their own process on the same 60-second clock; when their phases align,
git refuses the second with "index.lock: File exists" every minute until they
drift, and the scheduler loses the tick. A write cycle now waits out that one
refusal: reset, half a second, run again, three times at most.

Vike reads every +name.* file beside a page as page configuration, .md
included, so the +config.LOGIC.md and +config.BUG-ANALYSIS.md sidecars broke
the website build, and every deploy since 08-23 failed on it. The site's vite
config tells Vike's crawl to skip them.

cli.ts imported five names from maintenance.ts and used none; nothing else
imported the module. It goes, with its test and their sidecars.

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

Author: suleimansh

packages/agent-data/src/file-branch.LOGIC.md

@@ -28,6 +28,7 @@ Implements a branch of the project's repository used as a file store: files that
 - **The write cycle** - sync with origin, apply the change to the checkout, commit whatever changed under the caller's message, push whenever the branch is ahead of origin's copy.
 - **Sync: rebase onto origin, and origin wins a conflict** - unpushed local commits are rebased onto origin's copy; when the rebase fails, the checkout is reset to origin's copy and those commits are dropped, unreported.
 - **A push that loses a race re-applies the change once** - the attempt's commit is wound back, the cycle re-syncs and re-applies; a second failed push keeps the commit local and reports it, for the next cycle to carry out; never a force push.
+- **Another process holding the index is waited out** - git's refusal to take the checkout's index lock, which two processes on one clone hand each other, resets the checkout, waits half a second and runs the cycle again, three times at most.
 - **A failed change leaves the checkout clean** - any other failure, a timeout included, resets the checkout to its last commit, removes stray files, and is reported rather than thrown.
 - **The pull** - a write cycle with no change, run on the daemon's clock so this machine converges on what others pushed and pushes what an earlier cycle left stranded; a repository with no remote is an error it names.
 - **Reads from anywhere, and never a failure** - a file or a directory listing is read off the checkout, the local branch, or origin's copy, from any directory of the repository, an agent's checkout included; whatever is missing reads as absent.
@@ -116,6 +117,16 @@ Without a remote, a sync does nothing. With one, the branch is fetched from orig
 
 The change is an intent and the commit only its serialization, so the caller's change must be safe to run again. When the push fails on the first attempt, the attempt's commit is wound back to the tip the cycle started from (when a commit was made), the cycle syncs again, bringing in what the other writer pushed, and runs the change again against the fresher files, so the change lands exactly once. When the push fails on the second attempt too (the network, most likely), the commit stays local in the checkout [2] and the cycle reports the failure as "the <branch> branch could not be pushed: <git's reason>", marked as committed: the next write cycle [3] or pull rebases that commit onto whatever origin has by then, and its push carries it out together with the new change. A push killed on its time budget counts as a failed push and may have landed anyway; the next sync's rebase absorbs a commit origin already has. The branch is never force-pushed.
 
+### Another process holding the index is waited out
+
+#### Context
+
+**Problem**: the one-at-a-time rule is a process's own; two processes on one clone (the daemon's pull and a scheduler's, each on its own clock) can run a cycle on the same checkout at once, and git refuses the second with "Unable to create '…/index.lock': File exists" rather than waiting. On the scheduler's side a refused pull loses a whole tick.
+
+#### Business logic
+
+When a cycle fails with git's index-lock refusal, the checkout is reset as for any failure (next section), the cycle waits half a second and runs again, the change included, up to three more times. A lock that never lifts is then reported as the failure it is.
+
 ### A failed change leaves the checkout clean
 
 #### Context

packages/agent-data/src/file-branch.test.LOGIC.md

@@ -5,6 +5,7 @@ What the tests cover, against real git repositories with a bare `origin` and a s
 - **A write** - commits on the branch under the caller's message, pushes it to origin, and leaves `main` untouched; a change that writes nothing commits nothing and reports no change; in a repository with no remote the write lands locally and reports that nothing was pushed.
 - **Stranded commits and conflicts** - a write syncs in what another machine pushed and carries out an earlier local-only commit together with its own; a stranded commit that conflicts with origin's version resolves toward origin, and the change is re-applied on top of origin's version.
 - **A lost race** - a push rejected because another writer landed in between re-runs the change once against the fresher files: the change is on the branch exactly once, next to the other writer's file.
+- **The index held by another process** - git's index-lock refusal is recognized and a plain push failure is not; a change refused twice runs a third time and lands on origin exactly once, as one commit; a lock that never lifts is reported with git's reason and leaves the checkout at its last commit.
 - **The pull** - converges the checkout on what another machine pushed; in a repository with no remote it reports an error naming the missing remote.
 - **One write at a time** - three concurrent writes run one after another, never interleaving, and all three land in order.
 - **Reads** - a file reads off the checkout, from an agent's own checkout of the same repository too, which resolves to the project as its repository; a missing file reads as absent; after another machine moved origin on, a plain read still shows the checkout while a fresh read shows origin; a clone that holds no local branch reads origin's copy and lists a directory off it, and a missing directory lists as empty.

packages/agent-data/src/file-branch.test.ts

@@ -3,11 +3,12 @@ import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promi
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { test } from 'node:test'
-import { nodeGitRunner } from './git.js'
+import { nodeGitRunner, type GitRunner } from './git.js'
 import {
   ensureFileBranch,
   fileBranchPath,
   fileBranchRepo,
+  isIndexLocked,
   listBranchDir,
   pullFileBranch,
   readBranchFile,
@@ -210,6 +211,38 @@ test('a push lost to another writer re-applies the intent once, not twice', asyn
   }
 })
 
+test('another process holding the index is waited out: the cycle runs again and the write lands once', async () => {
+  const { repo, bare, cleanup } = await initSyncedRepos()
+  try {
+    // git's own refusal, as the daemon and the scheduler hand it to each other on one clone.
+    const refusal = new Error("Command failed: git add -A\nfatal: Unable to create '/x/.git/worktrees/store/index.lock': File exists.\n\nAnother git process seems to be running in this repository")
+    assert.equal(isIndexLocked(refusal), true)
+    assert.equal(isIndexLocked(new Error('Command failed: git push')), false)
+    let refusals = 2
+    const locked: GitRunner = (args, cwd) => {
+      if (args[0] === 'add' && refusals-- > 0) return Promise.reject(refusal)
+      return git(args, cwd)
+    }
+    let runs = 0
+    const result = await withFileBranch(repo, BRANCH, 'append', async dir => {
+      runs++
+      await writeFile(join(dir, 'queue.md'), '- once\n')
+    }, { git: locked })
+    assert.deepEqual(result, { ok: true, changed: true, pushed: true })
+    assert.equal(runs, 3, 'the change re-ran after each refusal')
+    assert.equal(await git(['show', `${BRANCH}:queue.md`], bare), '- once\n')
+    assert.equal((await git(['log', '--oneline', BRANCH], repo)).trim().split('\n').length, 2, 'born, then one commit')
+    // A lock that never lifts is reported like any other failure, and the checkout is clean.
+    refusals = Number.POSITIVE_INFINITY
+    const stuck = await withFileBranch(repo, BRANCH, 'again', async dir => writeFile(join(dir, 'queue.md'), '- twice\n'), { git: locked })
+    assert.equal(stuck.ok, false)
+    assert.match((stuck as { error: string }).error, /index\.lock/)
+    assert.equal(await readFile(join(fileBranchPath(repo, BRANCH), 'queue.md'), 'utf8'), '- once\n')
+  } finally {
+    await cleanup()
+  }
+})
+
 test('the eager pull converges a machine on what others pushed, and names a repo with no remote', async () => {
   const { repo, other, cleanup } = await initSyncedRepos()
   try {

packages/agent-data/src/file-branch.ts

@@ -170,11 +170,26 @@ function resolveMessage(message: CommitMessage): string {
   return typeof message === 'function' ? message() : message
 }
 
+/**
+ * git's refusal when another process holds the checkout's index: the one failure two processes
+ * on one clone (a daemon and a scheduler, each with its own in-process chain) hand each other.
+ * git does not wait for the index lock, so the cycle waits instead and runs again.
+ */
+const INDEX_LOCK_RETRIES = 3
+const INDEX_LOCK_WAIT_MS = 500
+export function isIndexLocked(err: unknown): boolean {
+  return /index\.lock['"]?: File exists/.test(errorMessage(err))
+}
+
 /**
  * Apply one change to the branch through its persistent checkout: sync with origin, run `op`
  * against the checkout, commit whatever it changed, push. The single funnel a long-lived
  * process's writes go through.
  *
+ * Another process holding the checkout's index (its `index.lock`) is waited out: the checkout
+ * is reset, the cycle waits half a second and runs again, three times at most, before the
+ * failure is reported like any other.
+ *
  * `op` must be re-runnable: when the push loses a race with another writer, the cycle re-syncs
  * and runs it again against the fresher state rather than force-fitting a stale commit — the op
  * *is* the intent, the commit is just its serialization. Two attempts; a push that still fails
@@ -193,43 +208,59 @@ export async function withFileBranch(
   const r = resolveDeps(deps)
   const path = fileBranchPath(repo, branch)
   return serialize(repo, branch, async () => {
-    try {
-      await ensureCore(repo, branch, r)
-      const remote = await hasRemote(repo, r.git)
-      for (let attempt = 0; ; attempt++) {
-        await syncCore(repo, branch, r)
-        // The tip before this op's commit: what a lost push winds back to before re-applying, so
-        // the op's first serialization is dropped rather than rebased under its second run.
-        const before = (await r.git(['rev-parse', 'HEAD'], path)).trim()
-        await op(path)
-        await r.git(['add', '-A'], path)
-        const staged = (await r.git(['status', '--porcelain'], path)).trim()
-        if (staged) await r.git(['commit', '-m', resolveMessage(message)], path)
-        if (!remote) return { ok: true, changed: Boolean(staged), pushed: false }
-        // Unpushed commits — this cycle's, or an earlier cycle's that the sync just rebased. The
-        // push is owed whenever any exist, even when this op itself wrote nothing new.
-        const ahead = (await refExists(repo, `refs/remotes/origin/${branch}`, r.git))
-          ? (await r.git(['rev-list', '--count', `origin/${branch}..${branch}`], repo)).trim() !== '0'
-          : true
-        if (!ahead) return { ok: true, changed: false, pushed: false }
-        try {
-          await r.git(['push', 'origin', `${branch}:${branch}`], path)
-          return { ok: true, changed: Boolean(staged), pushed: true }
-        } catch (err) {
-          if (attempt >= 1) return { ok: false, committed: true, error: `the ${branch} branch could not be pushed: ${errorMessage(err)}` }
-          if (staged) await r.git(['reset', '--hard', before], path)
-        }
-      }
-    } catch (err) {
-      // The op's half-written files must not ride a later, unrelated commit: put the checkout
-      // back to its committed state before reporting.
-      await r.git(['reset', '--hard'], path).catch(() => {})
-      await r.git(['clean', '-fd'], path).catch(() => {})
-      return { ok: false, committed: false, error: errorMessage(err) }
+    for (let locked = 0; ; locked++) {
+      const outcome = await cycle(repo, branch, path, message, op, r)
+      if (outcome.ok || !isIndexLocked(outcome.error) || locked >= INDEX_LOCK_RETRIES) return outcome
+      await new Promise(resolve => setTimeout(resolve, INDEX_LOCK_WAIT_MS))
     }
   })
 }
 
+/** One write cycle, unserialized: sync, apply, commit, push (twice on a lost race). Never throws. */
+async function cycle(
+  repo: string,
+  branch: string,
+  path: string,
+  message: CommitMessage,
+  op: (dir: string) => Promise<void>,
+  r: Resolved,
+): Promise<FileBranchWrite> {
+  try {
+    await ensureCore(repo, branch, r)
+    const remote = await hasRemote(repo, r.git)
+    for (let attempt = 0; ; attempt++) {
+      await syncCore(repo, branch, r)
+      // The tip before this op's commit: what a lost push winds back to before re-applying, so
+      // the op's first serialization is dropped rather than rebased under its second run.
+      const before = (await r.git(['rev-parse', 'HEAD'], path)).trim()
+      await op(path)
+      await r.git(['add', '-A'], path)
+      const staged = (await r.git(['status', '--porcelain'], path)).trim()
+      if (staged) await r.git(['commit', '-m', resolveMessage(message)], path)
+      if (!remote) return { ok: true, changed: Boolean(staged), pushed: false }
+      // Unpushed commits — this cycle's, or an earlier cycle's that the sync just rebased. The
+      // push is owed whenever any exist, even when this op itself wrote nothing new.
+      const ahead = (await refExists(repo, `refs/remotes/origin/${branch}`, r.git))
+        ? (await r.git(['rev-list', '--count', `origin/${branch}..${branch}`], repo)).trim() !== '0'
+        : true
+      if (!ahead) return { ok: true, changed: false, pushed: false }
+      try {
+        await r.git(['push', 'origin', `${branch}:${branch}`], path)
+        return { ok: true, changed: Boolean(staged), pushed: true }
+      } catch (err) {
+        if (attempt >= 1) return { ok: false, committed: true, error: `the ${branch} branch could not be pushed: ${errorMessage(err)}` }
+        if (staged) await r.git(['reset', '--hard', before], path)
+      }
+    }
+  } catch (err) {
+    // The op's half-written files must not ride a later, unrelated commit: put the checkout
+    // back to its committed state before reporting.
+    await r.git(['reset', '--hard'], path).catch(() => {})
+    await r.git(['clean', '-fd'], path).catch(() => {})
+    return { ok: false, committed: false, error: errorMessage(err) }
+  }
+}
+
 /** How a pull went: converged with origin, or why it could not. */
 export type FileBranchSync = { ok: true } | { ok: false; error: string }
 

packages/framework/src/LOGIC.md

@@ -33,7 +33,7 @@ Everything of The Framework that runs in Node: the `the-framework` command, the
 - **The daemon** (`daemon.ts`, `daemon-runtime.ts`, `daemon-services.ts`, `daemon-tick.ts`, `loopback-host.ts`, `project-hooks.ts`) - one foreground process that serves the dashboard, gives each agent a checkout [5] and a process, runs every background job on one clock, and runs the shell lines each project's own `.the-framework/hooks.yml` names when the dashboard opens and closes.
 - **Projects on this machine** (`registry.ts`, `project.ts`, `install.ts`, `layout.ts`, `framework-gitignore.ts`, `project-errors.ts`, `project-pass.ts`, `pick-directory.ts`, `config.ts`, `config-layers.ts`, `preference-defaults.ts`, `agent-options.ts`) - the one user file listing the projects and the preferences, what activating a repository does to it, the per-repository defaults that travel with the code, and the order in which the layers of a decision are resolved.
 - **Checkouts and what may be removed** (`worktrees.ts`, `merged-worktrees.ts`, `agent-locks.ts`) - one checkout [5] per agent under `.branches/`, and one rule for reclaiming it: only what is already on the remote may go.
-- **Spending** (`quota-boundary.ts`, `quota-poller.ts`, `maintenance.ts`, `handoff-level.ts`, `on-before-mergeable-prompt.ts`) - the share of the quota [6] week that may be spent by now, whether unattended work may start under it, the per-repository record of the last maintenance review, and the ladder a finished agent publishes itself by.
+- **Spending** (`quota-boundary.ts`, `quota-poller.ts`, `handoff-level.ts`, `on-before-mergeable-prompt.ts`) - the share of the quota [6] week that may be spent by now, whether unattended work may start under it, and the ladder a finished agent publishes itself by.
 - **Getting the work out** (`ci-watch.ts`, `update-check.ts`) - the pull requests The Framework opened are merged once their checks pass and fixed by an agent when they go red.
 - **Work that runs somewhere else** (`cloud-work.ts`, `cloud-run-state.ts`, `cloud-scratch-refs.ts`, `bridge-browser.ts`) - a Claude Code cloud session is recognized by the commit its branch descends from, its state is worded the same way on every surface, and the daemon can run its own browser so the bridge works with no Chrome of the user's open.
 - **The agent's browser** (`browser.ts`, `browser-stream.ts`) - a real Chrome an agent can drive, whose page the dashboard shows live and hands to the user at a login wall.

packages/framework/src/cli.ts

@@ -50,13 +50,6 @@ import { AgentMessageQueue } from './agent-messages.js'
 import { createGateKeepalive } from './gate-keepalive.js'
 import { ensureDaemonToken, readDaemonToken, readPreferences } from './registry.js'
 import { DEFAULT_SPEND_OFFSET } from './preference-defaults.js'
-import {
-  planMaintenanceSweep,
-  maintainSweep,
-  mergeMaintenanceState,
-  short,
-  type RepoReview,
-} from './maintenance.js'
 import {
   listProjectWorktrees,
   removeProjectWorktree,