* feat(sync): migration v98 last_refreshed_at + deleteLockRowIfStale helper
Schema foundation for v0.41.15.0's `gbrain sync --break-lock --max-age <s>`
flag. Adds `gbrain_cycle_locks.last_refreshed_at TIMESTAMPTZ` as the
heartbeat signal that distinguishes wedged-but-alive lock holders from
healthy long-running syncs that are actively refreshing.
Why last_refreshed_at not acquired_at: `withRefreshingLock` already bumps
`ttl_expires_at` every ~5 min while work runs, but leaves `acquired_at` at
the original timestamp. A 35-min media-corpus sync that's healthy has
`acquired_at` 35 min ago but `last_refreshed_at` 30 seconds ago. Using
acquired_at for --max-age would steal healthy locks; last_refreshed_at
correctly identifies only holders whose JS interval has stopped firing.
D-V4-1 rollout safety: migration v98 backfills `last_refreshed_at = NOW()`
(NOT `= acquired_at`) so pre-upgrade holders running the old binary get a
30-min protection window. After that window all pre-upgrade syncs are
either complete (lock released) OR genuinely wedged (--max-age does the
right thing). Documented as a known caveat in CHANGELOG.
D-V4-mech-4 SQL cast: deleteLockRowIfStale uses `$N * INTERVAL '1 second'`
not `$N::interval` (Postgres does not cast integer to interval the latter
way). Atomic DELETE keyed on (id, holder_pid, last_refreshed_at < NOW() -
$N * INTERVAL '1 second') RETURNING id, last_refreshed_at — no TOCTOU
between inspect + delete.
D-V4-mech-3 schema-snapshot parity: column added to all 3 snapshots so
fresh init paths (pglite-schema.ts, schema.sql) initialize correctly
without depending on the migration runner. schema-embedded.ts regenerated
via `bun run build:schema`.
Pinned by 13 PGLite cases in test/sync-break-lock-all.test.ts:
tryAcquireDbLock writes on INSERT, withRefreshingLock refresh bumps both
columns, inspectLock surfaces the new field, deleteLockRowIfStale refuses
fresh / breaks stale / safe on holder_pid mismatch / refuses NULL
(pre-v98). R1 + R6 regression invariants from the v4 plan.
Closes#1472 (RFC from @garrytan-agents) — schema foundation only;
performSync abort threading + CLI flags + consumer threading land in
follow-up commits in this PR.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(sync): --timeout + --max-age + partial status + per-source AbortController
The CLI surface for v0.41.15.0. Wires `gbrain sync --timeout <s>` (graceful
self-termination) and `gbrain sync --break-lock --all --max-age <s>`
(cron-self-heal) end-to-end through `performSync`, `runOne`, `runBreakLock`,
and all `SyncResult.status` consumers.
Surface 1: `gbrain sync --timeout <s>`
- New `SyncOpts.signal?: AbortSignal` threads through `performSync` →
`withRefreshingLock` work callback → `performSyncInner`.
- D-V3-1 honest scope: abort checks fire ONLY in pre-bookmark phases
(pull, delete, rename, import). Extract + embed run to completion if
reached. The `last_commit` bookmark write at sync.ts:1261 is the
invariant boundary — partial CANNOT advance the bookmark because the
abort checkpoints sit strictly before that write.
- D-V3-2 per-iteration: abort check at top of every loop iteration
(delete, rename, serial import, each parallel worker's while loop)
matches the per-file granularity the existing loops already have.
- D-V3-3 per-source AbortController: `--timeout --all` creates ONE
controller inside runOne per source so each gets its own budget;
NOT a shared global controller (which would starve later sources).
try/finally + timer.unref() guarantees cleanup on throw.
- D-V4-mech-7 pull error.cause: pullRepo wraps execFileSync errors in
GitOperationError. The catch inspects e.cause.code === 'ETIMEDOUT'
and e.cause.signal === 'SIGTERM' (NOT the top-level error) to
distinguish timeout (partial reason='pull_timeout') from ordinary
pull failure (existing warn-and-continue, R2 invariant preserved).
Surface 2: `gbrain sync --break-lock [--all] [--max-age <s>]`
- Drops the --all refusal at sync.ts:1610. When combined with --all,
runBreakLock iterates every active source and prints per-source verdict.
- --max-age routes through the new deleteLockRowIfStale helper from
db-lock.ts (atomic age-gated DELETE; no TOCTOU). Healthy refreshing
holders survive by construction; only wedged-but-alive holders trip.
D-V3-5 partial-status consumer threading (conservative posture matching
blocked_by_failures):
- printSyncResult: new `case 'partial':` arm reports filesImported +
reason; tells operator to re-run to continue.
- manageGitignore (both single-source and parallel runOne sites,
plus watch mode): excludes partial from the gate. A partial sync's
db_only path set isn't fully reconciled.
- Auto-embed-backfill enqueue inside runOne: excludes partial. The
next clean sync will re-walk and re-decide.
CLI flag parsing (T16):
- parseDurationSeconds in sync-concurrency.ts: accepts 60s/10m/1h/bare
int; rejects 0/negatives/decimals/garbage. Names the failing flag in
the error message.
- --timeout requires --source OR --all (validation rejects bare
`gbrain sync --timeout`).
- --max-age requires --break-lock; mutually exclusive with
--force-break-lock.
Coverage:
- 15 unit cases (test/sync-timeout.test.ts) pin parseDurationSeconds +
SyncResult union additivity.
- 2 E2E cases (test/e2e/sync-parallel.test.ts) pin the abort-mid-import
contract against real Postgres: status='partial', last_commit
unchanged, filesImported bounded.
Closes#1472 (RFC from @garrytan-agents) — CLI surface; schema foundation
landed in the previous commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(heavy): sync_timeout_rescue.sh reproducer for the cron-cascade
10K-page seed × 4 sources × deliberately tight --timeout × 3 sequential
cron emulations. Asserts every source reaches `last_commit === HEAD`
within 3 waves. Proves the v0.41.15.0 fix breaks the cascade the
PR #1472 RFC documented.
Workload (tests/heavy/_sync_timeout_rescue_workload.ts) is PGLite-only
because the PGLite engine forces serial sync internally (parallelEligible
excludes it). The parallel-fan-out + per-source AbortController case
lives in test/e2e/sync-parallel.test.ts against real Postgres. This
heavy test pins the contract that matters for cron: aborts → partial
returns → next wave content_hash-short-circuits + makes new progress.
Smoke-tested locally at PAGES=50 WAVES=2 TIMEOUT_SECONDS=2: every
source converges within 2 waves.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(v0.41.15.0): CHANGELOG + README + TODOS + version bump
Bumps VERSION + package.json to 0.41.15.0 (next slot after master's
v0.41.14.0). CHANGELOG entry leads ELI10 per gstack voice rules and
documents the 3 intentional honest gaps:
1. --timeout covers pull + delete + rename + import only; extract +
embed run to completion (D-V3-1 honest scope).
2. First 30 min after migration v98, --max-age cannot identify wedged
pre-upgrade holders (D-V4-1 rollout trade-off).
3. Full-sync triggers (first sync, --full, chunker-version rewalk)
don't respect --timeout yet (deferred to v0.42+).
README troubleshooting section: paste-ready cron pattern with shell
timeout(1) for OS-level process isolation + gbrain's --timeout for
graceful self-termination half-a-minute earlier.
TODOS.md: v0.42+ entries for subprocess fan-out (revisit if shell
timeout(1) proves insufficient), full-sync --timeout coverage via
AbortSignal in runImport, and runFactsBackstop microtask-queue
process-alive caveat.
llms-full.txt regenerated via `bun run build:llms`.
Closes#1472 (RFC from @garrytan-agents). Credit to @garrytan-agents
in the CHANGELOG for surfacing the production cron-failure data that
motivated the work.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(test-isolation): rewrite JSDoc to not match mock.module() lint regex
scripts/check-test-isolation.sh greps for the literal string `mock.module(`
to flag top-level module mocks (R2 rule — top-level mocks leak across files
in the shard process). The regex doesn't know about comments, so my two new
test files tripped the lint with JSDoc lines literally describing the rule:
test/sync-timeout.test.ts:11 "* `mock.module()` (R2). Engine ..."
test/sync-break-lock-all.test.ts:15 "* mock.module(), no process.env ..."
Both files had ZERO actual mock.module() calls — only the comment text
matched. Rewrote both JSDocs to refer to "top-level module mocks" instead
of the literal token. Same meaning; doesn't trip the regex.
`bun run check:test-isolation` now passes (714 non-serial unit files
scanned). `bun run verify` clean (22/22 checks pass).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
