Skip to content

Commit 7ee4ff4

Browse files
committed
merge: bound the global.db write-ahead log and idle VACUUM without waits
2 parents d2bce2a + 7228f28 commit 7ee4ff4

8 files changed

Lines changed: 889 additions & 20 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ All notable changes to Token-Goat are documented in this file. Format follows Ke
1212
### Fixed
1313

1414
- **A report that claims a change on a clean tree no longer makes git run twice for the same stop.** The stop warning and the report receipt each asked `git status` for the same stop, so a git that answered took two runs. They now share one answer per stop, and when git is still running at the end of the receipt's 5 seconds, the warning reuses that result instead of asking again, so on Claude Code, Codex and the other hosts the parent waits at most 5 seconds instead of about 5.05. On Copilot CLI the stop warning asks first within the 50 ms hint bound, so a git that never answers is still asked a second time within 5 seconds, and the wait stays at about 5.05 seconds as before. A complete answer is shared on every host, and the clean-tree line still reaches the parent at the end of the report. Tests now pin, for Claude Code, Codex, Copilot CLI and VS Code, that this verdict never comes back as a block, an exit 2 or extra context that would re-prompt the subagent, and a test that read the stats table before anything had created it no longer fails when the suite runs in a different order.
15+
- **The global.db write-ahead log no longer stays at its biggest size, and the idle pass no longer rewrites a database that has nothing to give back.** A 5.0 GB `global.db-wal` was found beside a 5.0 GB `global.db` with only 704 of its 1.2 million frames live. SQLite never shrinks a -wal file by itself, and the worker's idle VACUUM rewrote the whole database through it every six hours, even with no free pages. When a reader refused the truncating checkpoint after it, the file stayed at that size for as long as any process (the hook server, for days) kept the database open. Now, while a reader holds the log open, the idle pass asks again each cycle without waiting, and the log is truncated as soon as the reader leaves. The idle VACUUM does not wait for a lock held elsewhere either, and is retried on a later cycle. Every connection that writes global.db, the shared one and the short-lived telemetry one alike, now sets a 64 MB `journal_size_limit`, so the first write that restarts the log after its frames have been folded back cuts an oversized -wal to that size; a -wal that is already oversized shrinks the same way on a later index run or hook call, provided no reader is still pinning it. The idle pass vacuums only when at least a tenth of the file is free pages, and otherwise only runs a truncating checkpoint, which rewrites no page. A reader that keeps the log open now shows in the worker error log as two lines, one when the first idle pass is refused and one, with the number of refused passes, when the log is finally truncated, and the idle pass no longer waits out the 15 second busy timeout for that reader on each of its checkpoints. A missing `global.db` is not counted as a refused pass and writes no line, and the closing line says "1 refused poll" for one and "N refused polls" for more.
1516
- **The pre-push focus decision and the lock-file commit check no longer do nothing when their script is started through a symlinked folder.** Four helper scripts decide whether they were run directly by comparing the module's real path with the path they were started by, which differ when the folder is a symlink (every macOS temp folder is one, as `/var` and `/tmp` point into `/private`). The script then exited 0 without doing anything: the pre-push step read an empty record of failing tests and fell back to the full leg with a blank commit in its message, and the commit-msg check let a `package-lock.json` change through under any subject. They now resolve the path first through one shared check, `scripts/is-main-module.mjs`, which also covers the scripts that compared the paths without resolving them and falls back to the plain path instead of crashing when the entry path does not exist, and a guard fails any script that compares the bare paths.
1617
- **The pre-compact manifest no longer runs git in a folder that is not inside a git repository.** When the manifest outgrew its size cap it asked git whether the working tree was dirty, even for a folder with no repository, where the answer could only be "nothing". On a slow machine that git run was cut off at the 50 ms limit, and the probe was likely still holding the folder when a Windows test tried to delete its scratch folder (`EBUSY`); this cause was not reproduced locally. The probe now looks for a `.git` entry in the folder or a parent (following a junction or symlink to the real folder), and skips git when there is none. A set `GIT_DIR` still counts as a repository.
1718
- **A git command that times out on Windows no longer leaves a git process running.** With Git for Windows first on PATH, token-goat started the small launcher `cmd/git.exe`, and a timeout ended only that launcher, so the real git kept running with its folder open, which could block deleting the folder. It now starts the real git directly, for older installs and Scoop shims too, and for Git for Windows 2.56, which keeps its real git in a `ucrt64` folder instead of `mingw64` (on that version the first fix still started the launcher), and for a folder name it does not know. Helpers that git itself starts (such as a git-lfs filter) are not yet ended on a timeout.

‎src/db.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -500,6 +500,12 @@ function walSwitchError(lastError: unknown): Error {
500500
return new Error(`db: failed to enable WAL mode (${lastError instanceof Error ? lastError.message : String(lastError)})`, { cause: lastError })
501501
}
502502

503+
/** Size a -wal file is cut back to once its log has been folded into the database and the next write restarts it. A WAL never shrinks on its own: SQLite reuses the file from its start and leaves it at the largest size it ever reached, and `journal_size_limit` is its only setting that truncates one, per connection and not stored in the database, so every read-write connection sets it. Without it one whole-database rewrite (a VACUUM in WAL mode writes every page through the log) whose truncating checkpoint was refused by a concurrent reader left a 5.0 GB -wal beside a 5.0 GB global.db for as long as any process held the database open, the hook server being one for days; all but 704 of its 1.2 million frames were stale. The limit is a floor for the file after a restart, not a cap: a transaction larger than it still writes what it must. */
504+
export const WAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024
505+
506+
/** The pragma that sets {@link WAL_SIZE_LIMIT_BYTES}. The setting belongs to the connection, so each read-write opener runs it: {@link initConnection} for the shared connection, and the per-call telemetry connection in stats.ts that opens the file without it. A string and not a function, so the pre-dispatch call graph that tests/guards/pre_handler_fs_touches_are_gated.test.ts counts gains no member. Read-only and in-memory connections never write a log and skip it. */
507+
export const WAL_SIZE_LIMIT_PRAGMA = `journal_size_limit = ${WAL_SIZE_LIMIT_BYTES}`
508+
503509
/** How long a connection opened by a one-shot hook process waits on another process's lock, and how long its WAL switch is retried, in milliseconds. The hook is the agent's tool call: every wait here is wall-clock the agent sits through, and every write a hook makes is a hint, a stat or a session note that is fail-soft by contract, so a lost row costs far less than the 15 s a wedged lock holder charged per write (measured 32.8-38.3 s for one Read whose hint made two ledger writes). Sized like {@link PROBE_BUSY_TIMEOUT_MS}, the other pre-tool read bound. */
504510
const HOOK_DB_WAIT_MS = 250
505511
let _hookWaits = false
@@ -520,6 +526,7 @@ function initConnection(conn: SqliteDatabase, walStopOn?: (e: unknown) => boolea
520526
conn.pragma(`busy_timeout = ${waits.busyMs}`)
521527
enableWalWithRetry(conn, waits.walSwitchMs, walStopOn)
522528
conn.pragma('synchronous = NORMAL')
529+
conn.pragma(WAL_SIZE_LIMIT_PRAGMA)
523530
conn.pragma('cache_size = -32000')
524531
conn.pragma('temp_store = MEMORY')
525532
conn.pragma('mmap_size = 134217728')

‎src/index_reclaim.ts‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,10 @@ function tableExists(db: ReturnType<typeof getDb>, table: string): boolean {
7575
return row?.present === 1
7676
}
7777

78-
/** Reclaim space in the index DB, optionally rebuilding derived rows first. Returns before/after sizes so the caller can report what was actually recovered rather than asserting success blindly. */
79-
export function reclaimIndex(dbPath: string, opts: { rebuild?: boolean; embeddingsOnly?: boolean } = {}): ReclaimResult {
78+
/** Reclaim space in the index DB, optionally rebuilding derived rows first. Returns before/after sizes so the caller can report what was actually recovered rather than asserting success blindly. `waitForReaders: false` makes both checkpoints and the VACUUM answer busy at once instead of waiting out the connection's busy_timeout for a reader or writer to leave, for a caller that asks again on a later cycle (the worker's idle pass); the default waits. */
79+
export function reclaimIndex(dbPath: string, opts: { rebuild?: boolean; embeddingsOnly?: boolean; waitForReaders?: boolean } = {}): ReclaimResult {
80+
const noWait = opts.waitForReaders === false
81+
const checkpoint = noWait ? walCheckpointBusyNoWait : walCheckpointBusy
8082
const rebuild = opts.rebuild === true
8183
const embeddingsOnly = opts.embeddingsOnly === true
8284
const beforeBytes = indexSizeBytes(dbPath)
@@ -109,10 +111,10 @@ export function reclaimIndex(dbPath: string, opts: { rebuild?: boolean; embeddin
109111
}
110112

111113
// Fold the WAL back into the main DB first. VACUUM rewrites the main file only, so an unchecked WAL (88 MB, in the case that motivated this command) would otherwise survive the vacuum and understate the reclaim. wal_checkpoint returns a busy indicator instead of throwing when a reader blocks truncation, so read it rather than assuming success.
112-
const checkpointBusy = walCheckpointBusy(db)
114+
const checkpointBusy = checkpoint(db)
113115
// VACUUM cannot run inside a transaction, hence its position outside the block above.
114-
const vacuumDeferred = !vacuumOrDefer(db)
115-
const finalCheckpointBusy = walCheckpointBusy(db)
116+
const vacuumDeferred = !vacuumOrDefer(db, { noWait })
117+
const finalCheckpointBusy = checkpoint(db)
116118

117119
return {
118120
beforeBytes,
@@ -127,10 +129,11 @@ export function reclaimIndex(dbPath: string, opts: { rebuild?: boolean; embeddin
127129
}
128130
}
129131

130-
/** Run VACUUM, returning whether it succeeded rather than throwing on lock contention. Deliberately a single attempt. SQLite's own `busy_timeout` (set on the shared connection) already retries internally for its full window, so an extra retry loop here would not add patience -- it would multiply an already-long wait by the attempt count while the user stares at a hung command. What is actually missing is the honest outcome: VACUUM runs *after* the `--rebuild` deletes have committed, so throwing would abandon a successful, irreversible recovery behind a stack trace over its freely-repeatable final step. Only lock contention is absorbed; any other SQLite error is a real fault and rethrows. */
131-
function vacuumOrDefer(db: ReturnType<typeof getDb>): boolean {
132+
/** Run VACUUM, returning whether it succeeded rather than throwing on lock contention. Deliberately a single attempt. SQLite's own `busy_timeout` (set on the shared connection) already retries internally for its full window, so an extra retry loop here would not add patience -- it would multiply an already-long wait by the attempt count while the user stares at a hung command. What is actually missing is the honest outcome: VACUUM runs *after* the `--rebuild` deletes have committed, so throwing would abandon a successful, irreversible recovery behind a stack trace over its freely-repeatable final step. Only lock contention is absorbed; any other SQLite error is a real fault and rethrows. With `noWait` the VACUUM runs at busy_timeout 0 and is deferred at once on contention, for a caller that asks again on a later cycle. */
133+
function vacuumOrDefer(db: ReturnType<typeof getDb>, opts: { noWait: boolean }): boolean {
132134
try {
133-
db.exec('VACUUM')
135+
if (opts.noWait) withoutBusyWait(db, () => db.exec('VACUUM'))
136+
else db.exec('VACUUM')
134137
return true
135138
} catch (err) {
136139
const code = (err as { code?: string }).code ?? ''
@@ -141,11 +144,27 @@ function vacuumOrDefer(db: ReturnType<typeof getDb>): boolean {
141144
}
142145

143146
/** Run a truncating WAL checkpoint, reporting whether SQLite declined it. `pragma wal_checkpoint(TRUNCATE)` yields `busy = 1` (not an exception) when a concurrent reader prevents truncation. Swallowing that would let the command report a reclaim that silently left the WAL in place. */
144-
function walCheckpointBusy(db: ReturnType<typeof getDb>): boolean {
147+
export function walCheckpointBusy(db: ReturnType<typeof getDb>): boolean {
145148
const rows = db.pragma('wal_checkpoint(TRUNCATE)') as Array<{ busy?: number }>
146149
return rows[0]?.busy === 1
147150
}
148151

152+
/** {@link walCheckpointBusy} that answers busy at once instead of waiting out the connection's busy_timeout for the reader to leave (15 s on the shared connection), for a caller that retries on a later cycle. The timeout is set to 0 for this one checkpoint and put back in a finally; the driver is synchronous and nothing else runs on this connection in between, so the swap cannot be seen by another statement. */
153+
export function walCheckpointBusyNoWait(db: ReturnType<typeof getDb>): boolean {
154+
return withoutBusyWait(db, () => walCheckpointBusy(db))
155+
}
156+
157+
/** Run `body` with the connection's busy_timeout at 0, so a lock held elsewhere is refused at once instead of waited for, and put the prior value back in a finally on every path. The driver is synchronous and nothing else runs on this connection in between, so the swap cannot be seen by another statement. */
158+
function withoutBusyWait<T>(db: ReturnType<typeof getDb>, body: () => T): T {
159+
const priorWaitMs = Number(db.pragma('busy_timeout', { simple: true }))
160+
db.pragma('busy_timeout = 0')
161+
try {
162+
return body()
163+
} finally {
164+
db.pragma(`busy_timeout = ${priorWaitMs}`)
165+
}
166+
}
167+
149168
/** Format a byte count as MB with one decimal, for human-readable reporting. */
150169
function mb(bytes: number): string {
151170
return `${(bytes / (1024 * 1024)).toFixed(1)} MB`

‎src/stats.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import * as fs from 'node:fs'
44
import * as path from 'node:path'
55
import type { SqliteDatabase } from './sqlite_driver.js'
66
import Database from './sqlite_driver.js'
7-
import { getDb, isReadOnlyDb } from './db.js'
7+
import { getDb, isReadOnlyDb, WAL_SIZE_LIMIT_PRAGMA } from './db.js'
88
import { dataDir, dataDirForHome } from './constants.js'
99
import { VERSION } from './version.js'
1010
import type { ContentClass } from './token_estimate.js'
@@ -745,6 +745,7 @@ export function withTelemetryWriteDb(write: (db: SqliteDatabase) => void): void
745745
if (isReadOnlyDb(dbPath)) return
746746
const db = new Database(dbPath, { timeout: STATS_WRITE_BUSY_TIMEOUT_MS })
747747
try {
748+
db.pragma(WAL_SIZE_LIMIT_PRAGMA)
748749
// A telemetry row under WAL: NORMAL drops the flush to disk on every commit, measured at 1.4ms of each hook's 1.45ms insert, and can lose only the latest rows to a power cut, never corrupt the file. Outside WAL it could, so the default stays there.
749750
if (String(db.pragma('journal_mode', { simple: true })).toLowerCase() === 'wal') db.pragma('synchronous = NORMAL')
750751
write(db)

0 commit comments

Comments
 (0)