fix(update): add --if-version CAS guard, close the lost-update gap on both stores

[andrei-hasna]

Summary

Fixes a measured P1 data-loss defect (todos 97d26f1b): knowledge update --content was an unconditional whole-content overwrite, and a write computed from a stale read could silently destroy an intervening write from another agent.

• Root cause 1 — local store had no version tracking at all. LocalItemStore.update ignored expectedVersion (didn't even accept the parameter), and local items carried no version field, so any concurrency guard was a no-op on the on-box JSON store.
• Root cause 2 — the CLI's existing auto-guard only protects one invocation's own internal read-then-write window. update already re-reads the item and sends expectedVersion: current.version, but that re-read happens fresh at write time, so it can never catch a decision an agent made from an earlier, separate get — by write time the freshly re-read version already reflects any intervening edit, so the guard trivially "passes" against itself.

Fix

• LocalItemStore now tracks a lock-protected version counter (bumped on every successful write, check-and-write inside one file-lock acquisition). This is distinct from version history — supportsVersions stays false, no prior bodies are retained; that's still Postgres-only.
• knowledge update gains an optional --if-version <n> flag. Pass the version a prior get returned; the write is rejected (nothing written) if the store has moved to a different version since. Omitting it preserves the exact previous behaviour on both backends.
• A version conflict (KnowledgeVersionConflictError, already used by the cloud/Postgres path) is now surfaced as a distinct exit code (2), separate from the CLI's generic error exit (1), with code/expected/current fields in --json output.

Regression test

tests/knowledge-update-cas.test.ts reproduces the exact repro from the bug report (two reads at the same version, two writes, second clobbers first) at both the ItemStore layer (fast, in-process) and the CLI layer (real subprocess, real local JSON file), plus:

• a legacy-item case (no version field yet) is read as version 1, not silently unguardable
• a positive control (fresh version accepted)
• backward-compat (omitting --if-version still works)
• flag validation (non-integer --if-version rejected before touching the store)
• an isolation test: an explicit --store plus a fully-selected postgres mode pointed at a guard-refused non-loopback host still resolves local, and the default store location is never created

Confirmed failing (7/9) against the unfixed store before the fix, passing (9/9) after.

Test plan

• Regression test written first, confirmed failing against the unfixed code (created.version undefined, no KnowledgeVersionConflictError thrown, clobber not prevented)
• Same test passing after the fix (9/9)
• Full suite run (bun test) with ambient HASNA_KNOWLEDGE_* vars unset: 400 pass / 2 skip / 13 fail — all 13 failures reproduce on a pristine pre-fix baseline run under the same conditions (11 baseline fails, same test names; the 2 extra are cli.test.ts/smoke-script timeouts under full-suite CPU contention, confirmed passing when run in isolation)
• tsc --noEmit clean
• Directly related test files (entry-versioning*.test.ts, cloud-store.test.ts, knowledge-mode.test.ts, serve.test.ts) all green (99/99) run in isolation
• Isolation constraint honoured: every test either drives ItemStore directly with storePathOverridden: true, or spawns the CLI with a fresh temp HOME + explicit --store, stripping ambient *KNOWLEDGE* env

Notes for reviewers

• This PR is opened as a draft and is not to be merged by the author.
• Scope is intentionally narrow: --if-version is added to update only, per the task. archive/restore/untag/upsert keep their existing auto-derived expectedVersion (unchanged behaviour, still real protection for the single-invocation race).

---

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