[liuchao-001]

Part of #29. Stacked on #28 (which includes #27); retarget to main after those merge.

Summary

• Fetch freshness window. sync skips the network when the same branch of the repository cache was fetched within the last 60 seconds by any process on the machine, and resolves from the local ref. The fetch time is recorded per remote-tracking ref in repositories/<id>.git.fetched.json under the cache lock. sync --max-age <seconds> changes the window; --max-age 0 always fetches.
• connect and write prepare always fetch, so a write starts from the remote head.
• Wait instead of BUSY. Repository-cache and snapshot locks wait up to two minutes for a live owner (withLockWait), so concurrent agents share one clone or fetch instead of failing. Dead owners are still reclaimed; snapshot eviction keeps non-waiting locks and skips busy snapshots.
• Spec updated.

Tests

• New tests/fetch-freshness.test.ts: a recent fetch is reused, --max-age 0 fetches, an expired record fetches, and write prepare fetches despite a recent sync.
• tests/state.test.ts: a sync waits for a live lock owner and proceeds once it exits; withLockWait reports busy after its timeout.
• Tests that push and immediately expect new content now pass maxAge 0.
• pnpm check, pnpm typecheck, pnpm test (125 tests), pnpm check:package pass. Under heavy local load some unrelated tests exceeded the default 5 s timeout once and passed on rerun.

Parallel fetch across sources is not in this PR: syncTrees is synchronous. OpenTag's command gateway runs one CLI call per source and can run them concurrently.

🤖 Generated with Claude Code

[yuezengwu]

Reviewed 49873d4, including the corrected parent eviction behavior. No additional defect was found in fetch freshness, forced connect/write refresh, per-ref metadata, or bounded cache-lock waiting. All 126 tests passed at this exact head with HTTPS Git transport prohibited, along with repository checks, typecheck and real package smoke.

The PR has now been retargeted to main. Actual main 997a68c still conflicts in docs/specification.md and tests/snapshot-eviction.test.ts; my local integration attempt was aborted. This is a code approval, not a successful integration result. Resolve those conflicts on the author branch and validate the resulting head/main combination before merge.

[liuchao-001]

Merged current main (with squashed #28) in a882727. main's tree equals the final feat/snapshot-gc tree, so the conflicts in docs/specification.md and tests/snapshot-eviction.test.ts resolve to this branch's side; the diff against main is unchanged from the diff you approved (10 files, +147/−31). pnpm check, typecheck, test, check:package pass locally (three tests hit the 5s timeout under host load and pass at a 30s timeout).

[yuezengwu]

Re-reviewed a882727 against actual main 997a68c. This successor merges main, resolves the integration conflict, and is tree-identical to the independently verified 49873d4. Actual main is now an ancestor of this head; no source, tests, package manifests or lockfile changed in the merge. The prior 126 passing tests (HTTPS Git transport prohibited), repository check, typecheck and real package smoke therefore apply to this exact tree; repeating them would not add coverage. No remaining code finding in the shared 60-second fetch window, per-ref freshness metadata, forced refresh or bounded cache-lock waiting.