feat(update): add --if-version so the caller's read guards the write

[andrei-hasna]

Todos task 5d45a037.

What this changes

Adds knowledge update --if-version <n>: an optimistic-concurrency guard the caller supplies, refusing the write with a non-zero exit when the entry has moved past version n. Omitted, behaviour is unchanged.

Why the existing guard is not enough

update already passes expectedVersion: current.version (landed in #45). That is necessary and not sufficient, and the distinction is the whole point of this PR.

current.version is read microseconds before the write, by the write itself. It therefore closes only the gap inside one invocation. The race that actually loses fleet edits is wider:

1. Agent B reads an entry at v1.
2. Agent B spends minutes composing a new body against what it read.
3. Agent A writes → the entry is now v2.
4. Agent B runs update --content <composed>. The CLI re-reads, sees v2, passes v2 as the guard — it matches — and B's write lands at exit 0.

A's edit is gone, silently. The version B actually read is never expressed anywhere, and a guard derived from the write cannot detect staleness in the read that produced the content. Only the caller knows that number.

This matches the standard -t/--tag already sets in this same command: tags are added rather than replaced, and the count of what actually changed is reported so a no-op cannot be misread as success. One field got that care; the field carrying all the content did not.

Two refusals, so the flag cannot become a guard that enforces nothing

Both are the "check that cannot fail" shape, which is worse than no flag because the caller believes they are protected:

• Non-numeric value → rejected before any write. Number('abc') is NaN, which serialises into the If-Match header as null; the server would read that as no guard and accept the write at exit 0.
• Local JSON store → refused, naming the way to a store that can honour it. LocalItemStore.update takes no options at all, so expectedVersion is dropped on the floor and every --if-version there would report success while enforcing nothing. The message mirrors the existing VersionHistoryUnsupportedError.

Tests

tests/entry-versioning-client.test.ts — a real CLI process against a live loopback server on real Postgres (no stubs):

test	asserts
stale writer refused	B is refused, A's content survives and B's never lands
current version accepted	positive control — the guard is not simply always-on
flag omitted	existing callers still write (back-compat)
non-numeric value	refused, and the entry is byte-unchanged
local JSON store	refused, and the file is unchanged

The two refusal tests additionally assert stderr does not contain Unknown flag. Without that they passed while the flag did not exist, because Unknown flag: --if-version contains the string they were matching — they were vacuous, and are now discriminating.

Red-then-green was confirmed: 4 failing before implementation, 5 passing after.

Regression check

Full suite compared against pristine origin/main on the same machine. Baseline 32 fail / 406 tests; this branch 35 fail / 411 tests (+5 = exactly the new tests). Set difference is 3 tests, all in cli.test.ts, all timeouts overshooting a 5000ms budget by 52–174ms on a box at load 17.8/20 cores.

Each was then measured individually rather than assumed:

• ingest manifest… and context pack… — pass in isolation.
• machines topology… — run 3× on each side: baseline 2 fail / 1 pass, this branch 2 fail / 1 pass. Identical distribution, so it is a pre-existing load-dependent flake, not a regression. It sits right at its budget and flips on noise.

bunx tsc --noEmit clean. Both versioning suites: 52 pass, 0 fail.

Not done here, deliberately

Per-agent actor attribution was investigated and skipped as out of scope. Every retained version records agent:fleet because serve.ts derives it server-side from the authenticated principal (principalActor: agent:${principal.agent}), and the whole fleet shares one API key minted with agent: 'fleet'. Fixing it means either minting per-agent API keys (credential issuance) or trusting a caller-supplied actor header — and a self-declared, forgeable attribution field is arguably worse than an honest constant, because it reads as authoritative. That is a security and credential decision, not a small CLI change, and it does not belong bundled with a concurrency fix. It needs its own row.

Agent: Silvanus

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[andrei-hasna]

Closing in favour of #65, which implements the same flag with a strictly better contract.

Why this one loses, in one line: #66 REFUSES --if-version against the local JSON store; #65 adds a real version counter to LocalItemStore so the flag works on both backends. One flag name with two behaviours across two stores is the defect class this fix exists to remove.

My fixer refused on local because LocalItemStore.update took no options, so expectedVersion would be silently dropped — a guard that cannot fail. That reasoning was sound about the code as it stood and stops applying the moment someone builds the plumbing, which #65 does.

I verified the primitive #65 relies on before conceding, reading src/store.ts from the remote at main (blob 08bac7c4d64e556a1248556a3389b3ec2321e36e): acquireLock is a bounded wait over an exclusive-create (wx) lock file with staleness detection and break, and releaseLock only unlinks when the recorded owner matches. Cross-process, sound, and predating both PRs.

Refusing on local would leave the default backend — what an agent gets when cloud config is absent — carrying the identical lost-update defect with no remedy.

The regression tests here may still be worth grafting into #65. One of them earned its keep: three of five initially passed for the wrong reason, matching a substring of Unknown flag: --if-version, and the fix was asserting stderr does NOT contain Unknown flag. If #65's refusal tests match on the flag name in stderr they have the same hole.

Diagnosis was reached independently by both authors: the pre-existing guard sources its expected version from its own read, microseconds before the write, so it cannot detect staleness in the read that produced the content.

Agent: Silvanus