instar 1.3.339 → 1.3.340

package/src/scaffold/templates.ts

@@ -419,6 +419,12 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Also: when a session is autonomously shut down, you get a "your session was shut down — <reason>" notice (recovery-bounces and your own operator kills stay silent). Turn the notice off with \`{"monitoring": {"reapNotify": {"enabled": false}}}\`.
 - Proactive: user asks "where did my session go?" / "why did X disappear?" / "did something get killed?" → GET /sessions/reap-log and explain the most recent reaped/skipped entries for that session.
 
+**Coherence Journal** — The durable "what happened where, and where are the files?" answer for a multi-machine agent. Every machine writes append-only event streams (topic placement + why it moved, session open/close/reap, autonomous runs + their artifact paths); the read API serves a merged view so you answer placement/artifact questions from local disk instead of grepping rotating logs on the right machine.
+- Read it: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/coherence/journal?topic=N&kind=topic-placement&limit=50"\` → \`{ entries: [...], streams: {...}, skippedCorrupt }\` (+ a partial-result flag when a read bound was hit). Filters: \`topic\`, \`kind\` (\`topic-placement\`|\`session-lifecycle\`|\`autonomous-run\`), \`machine\`, \`limit\`, \`cursor\`. Read-only; 503 when the journal is not enabled on this agent.
+- TRUST NOTE: entries tagged \`source: "replica"\` are another machine's copied history — always a little stale (\`stalenessMs\` says how much). NEVER make a kill/spawn/move decision off journal data; it answers questions, the live systems decide.
+- Degraded mode: the streams are plain JSONL under \`state/coherence-journal/\` — readable directly when HTTP is starved.
+- Proactive: user asks "which machine was topic N on?" / "why did this conversation move?" / "where are the overnight run's files?" / "did the old machine close its session after the move?" → GET /coherence/journal with the topic filter and answer from the entries.
+
 **🩺 Agent Health lane (calm self-health notices)** — Routine notices about MY OWN internal state (a session that looks stuck, a peer I can't reach) land in ONE calm, named "🩺 Agent Health" Telegram topic — never topic-after-topic. Each is normal-priority (not a user-critical alert), names the topic in plain language (e.g. "the 'EXO 3.0' session", never \`topic-19077\`), ends with a next step you can just reply to, and same-session re-escalations are de-duped so the lane stays quiet. Ships **default-on, no config** (it's a delivery-shaper in code — it never gates or drops anything; every notice is still in the attention store). Tune via \`messaging[].config.agentHealthLane\` = \`{ "enabled": true, "topicName": "🩺 Agent Health", "dedupWindowMs": 1800000 }\` (set \`enabled:false\` for the old per-item-topic behavior). Proactive: user asks "what's this Agent Health topic?" / "why are my stale-session notices grouped?" → explain the calm lane (the StaleSessionBackstop now routes its "looks stuck" heads-up here at normal priority instead of spawning a topic each time).
 
 **Applying config & hook changes to running sessions** — A running session keeps the config it was *spawned* with. Claude Code loads \`.claude/settings.json\` (hooks, model) **once, at session start** — so a config change (default model, a disabled feature) or a newly-added hook does NOT reach an already-running session. It only takes effect on the next session, OR when you restart the existing one. (This is why a UserPromptSubmit hook added mid-session never fires for that live session — the session was launched before the hook existed.)
@@ -843,6 +849,7 @@ I maintain registries that are the source of truth for specific categories. Thes
 | What have I learned? | \`.instar/MEMORY.md\` |
 | What jobs do I have? | \`.instar/jobs.json\` or \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/jobs\` |
 | Who have I interacted with? | \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/relationships\` |
+| Which machine was topic N on / where are a run's artifacts? | \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/coherence/journal?topic=N"\` (multi-machine placement + artifact history; 503 = journal not enabled) |
 | My configuration? | \`.instar/config.json\` |
 | My identity/principles? | \`.instar/AGENT.md\` |
 | My past learnings about X? | \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/memory/search?q=X"\` |

package/upgrades/1.3.340.md

@@ -0,0 +1,132 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+**Coherence Journal P1.1** (COHERENCE-JOURNAL-SPEC, converged + approved):
+every machine now writes per-kind append-only event streams under
+`state/coherence-journal/` — `topic-placement` (emitted at all 8
+ownership-CAS sites with caller-known reasons, paired by a new CI lint),
+`session-lifecycle` (derived at the saveSession funnel; `reaped` emitted
+beside the reap-log), `autonomous-run` (60s observer + stop-funnel seam —
+no phantom-live runs). Writer is non-blocking (memory enqueue + 250ms
+flusher; zero sync I/O in caller stacks), crash-safe (repair-counted
+truncation, incarnation-fenced restore detection), single-process-locked,
+schema-typed with artifactPath jail. Plus: the State-Coherence Registry is
+now machine-readable (`src/data/state-coherence-registry.json`, 66
+categories) with `lint-state-registry` failing CI on undeclared durable
+stores. Dark-ship: `multiMachine.coherenceJournal.enabled ?? developmentAgent`.
+
+**Coherence Journal P1.2** — the read API. `GET /coherence/journal` serves
+the merged placement / session-lifecycle / autonomous-run history from
+local disk: skew-proof `(epoch,ts)` ordering for placement, replica entries
+labeled with `source:"replica"` + `stalenessMs`, `(topic,epoch)` dedupe,
+bounded reverse-tail reads (byte ceiling + archive caps; placement stays
+answer-complete), opaque keyset cursors, corrupt lines skipped + counted.
+New `lint-journal-actuation-ban` build-enforces §3.9 (actuators may not
+import the reader). CLAUDE.md template teaches every agent the capability.
+TelegramAdapter emergency-stop now reports its journal line instantly.
+
+**Coherence Journal P1.3 (apply/serve engine)** — `JournalSyncApplier`,
+the pure mesh-independent receive+serve engine for journal replication
+(COHERENCE-JOURNAL-SPEC §3.4): first-hop sender binding, schema-validated
+apply with suspect-self-clear, incarnation-fenced restore detection with
+bounded quarantine, truncation gap signals, ack-after-fdatasync on receive,
+and durably-flushed-only own-stream serve. The `journal-sync` mesh verb +
+session-status advert + the live two-machine proof are the closing wiring
+step (the engine ships ahead of the network exposure, fully tested).
+
+Adds a **learning-velocity metric** — Salim Ismail's EXO 3.0 KPI inversion (from
+*Your KPI System Is Training You to Miss the Future*). Backward-looking
+operational KPIs (throughput, utilization, efficiency) reward the existing model
+and suppress the weak signals where the future shows up. The EXO 3.0 answer is to
+measure how fast you're **learning** — adaptability, experimentation, capability
+creation.
+
+Instar already emits the raw learning events (registered learnings, captured
+corrections, evolution actions); this turns them into a signal:
+
+- `GET /metrics/learning-velocity?windowDays=30` → `{ totalEvents, eventsPerDay,
+  byType, typeDiversity, trend, adaptabilityScore, reason }`.
+- `trend` is `accelerating` | `steady` | `declining` | `insufficient-data`
+  (first-half vs second-half of the window).
+- `adaptabilityScore` (0–100) blends velocity (saturating) with category
+  diversity.
+
+Read-only + advisory — it never gates anything. A flat or declining trend is the
+EXO 3.0 warning sign that the org is optimizing the old model instead of learning.
+
+## What to Tell Your User
+
+Nothing user-visible yet — this is the foundation layer. Your agent's
+machines have started keeping reliable local "diaries" of where
+conversations live, when sessions open/close, and where autonomous runs
+put their files. The pieces that let you ASK about that history from any
+machine arrive in the next two updates (the query API, then
+machine-to-machine sync).
+
+If your agent runs on more than one machine, you can now ask it "which
+machine was this conversation on last night, and why did it move?" or
+"where did the overnight run put its files?" — and it answers from a
+durable history instead of guessing. (Multi-machine sync of those
+histories lands in the next update; today each machine answers from what
+it holds.)
+
+Nothing user-visible changes yet — this is the engine that will let your
+agent's machines safely exchange their diaries. Once the final wiring lands,
+asking ANY machine "where did this conversation live / where are the
+overnight files?" will answer from a synced history. Today the engine is in
+place and proven; the cross-machine exchange turns on with the next step.
+
+Your agent can now answer "are we actually learning, or just running?" with real numbers. Ask it for its learning velocity and you get a trend — accelerating, steady, or declining — built from its genuine learning events (lessons it recorded, corrections it absorbed, capabilities it grew) instead of backward-looking activity stats. The EXO 3.0 idea behind it: traditional KPIs measure how well the OLD model runs; learning velocity measures whether you're building the next one. A flat or declining trend is your early warning that things are coasting.
+
+## Summary of New Capabilities
+
+- None user-invocable yet (P1.2 ships `GET /coherence/journal` + the
+  agent-facing docs). Internal: `CoherenceJournal` writer,
+  `StateManager.guardJournalWrite`, machine-readable state registry, two
+  new CI lints.
+
+- `GET /coherence/journal?topic=N&kind=...&machine=...&limit=...&cursor=...`
+  — merged journal view; read-only; 503 when the journal is not enabled.
+- Agents proactively reach for it on "where did topic N live / where are
+  the artifacts?" questions (CLAUDE.md template entry ships in this
+  release).
+
+- None user-invocable yet (the engine is internal; the `journal-sync`
+  transport that drives it is the closing wiring step). Internal:
+  `JournalSyncApplier` (receive+serve engine for §3.4 replication).
+
+- `GET /metrics/learning-velocity?windowDays=30` — `{ totalEvents, eventsPerDay, byType, typeDiversity, trend, adaptabilityScore (0-100), reason }`, computed from registered learnings, corrections, and evolution actions. Read-only + advisory — never gates.
+- PROACTIVE trigger: "are we learning/adapting?" → read this metric and contrast it with operational throughput.
+
+## Evidence
+
+- 56 new tests (writer 33 incl. fault-injected non-blocking emit +
+  kill-9-window re-mint precision; wiring 9 with independent oracles;
+  guard 7; registry lint 7); 357 tests green across the affected surface;
+  both lints clean on the real tree; tsc clean.
+- The cas-pairing lint caught a real unpaired site (POST /pool/transfer
+  release) during development — the structural guard works.
+
+- 22 new reader/route tests + Tier-3 e2e lifecycle (feature-alive, 503
+  when dark); actuation-ban lint clean over 8 actuator modules; tsc + full
+  lint chain clean.
+
+- 26 new tests covering every §3.4 rule (seq-gating, forged-entry reject,
+  suspect→self-clear, incarnation quarantine bounds + reset-flapping,
+  truncation fast-forward, ack-after-fsync ordering via injected spy,
+  guardWrite refusal). tsc + full lint chain clean.
+
+Three-tier coverage, all green, `tsc --noEmit` clean:
+
+- Unit — `LearningVelocityScorer.test.ts` (6): empty, window exclusion,
+  accelerating, declining, insufficient-data, and byType/diversity/adaptability.
+- Integration — `learning-velocity-routes.test.ts` (3): the route reads a real
+  `learning-registry.json` + corrections over HTTP and computes.
+- E2E — `learning-velocity-lifecycle.test.ts` (1): a real server on a real port,
+  feature alive end-to-end (200, not 404/503).
+
+CLAUDE.md scaffold template documents the endpoint.

package/upgrades/coherence-journal-p1-1.eli16.md

@@ -0,0 +1,11 @@
+# The diary starts writing (P1.1 of the coherence journal)
+
+This is the build half of the spec you approved tonight: every machine now actually KEEPS the diary. Three kinds of entries get written automatically — "this conversation was placed/moved here (and why)", "a work session opened/closed/was reaped", and "an autonomous run started/stopped here, its files are at these paths". Nothing reads them across machines yet (that's the next two PRs: the question-answering API, then machine-to-machine swapping) — this PR is the foundation that makes those possible: reliable, cheap, tamper-resistant local diaries.
+
+The seatbelts from the review are all real code now, each with a named test: writing a diary line never touches the disk in the hot path (it's an instant memory hand-off; a background helper saves batches four times a second — a fault-injection test wedges the disk and proves the hand-off still returns instantly). A crash can only lose the last quarter-second, and a half-written line is repaired and COUNTED on restart. Restore-from-backup is detected precisely (the "edition number" mechanism — an ordinary crash can never false-trigger it, proven by a test that kills the writer at the exact worst moment). Only one process on a machine may write (a second one locks out, loudly — visible in status, not silently). Every line must match a strict template; free text, secrets, oversized entries, and path-escape tricks are rejected at the door.
+
+Three things make the wiring trustworthy rather than hopeful: (1) session open/close events are derived at the ONE place every status change already passes through, so no future code can forget to record one; (2) every one of the 8 places that can change "which machine owns this conversation" is paired with its diary write, and a NEW build-time check fails CI if anyone ever adds a 9th without the pairing — it caught a site I'd missed within seconds of existing; (3) autonomous runs are watched by a small once-a-minute observer, so even a run that dies by crash or reboot gets its "stopped" line — no phantom forever-running jobs.
+
+Also in this PR: the census from P0 becomes machine-readable (all 66 state categories) with its own CI check — new code that writes durable state without declaring it in the registry fails the build. That's the "nothing becomes invisible-machine-local by accident again" guarantee, live.
+
+Ships dark on the fleet, live on me. Existing agents get the config automatically on update. One honest note: a stop issued through the Telegram path gets its diary line from the observer (up to a minute late) rather than instantly — the direct hookup there needs a wider change that rides the next PR.

package/upgrades/coherence-journal-p1-2.eli16.md

@@ -0,0 +1,11 @@
+# The diary becomes answerable (P1.2 of the coherence journal)
+
+P1.1 made every machine KEEP the diaries; this makes them ANSWERABLE. One new read endpoint serves the question this project was born from: "which machine was conversation X on last night, why did it move, and where did the overnight run put its files?" — answered from local disk, merged across every diary the machine holds.
+
+The answers are engineered not to lie. Cross-machine ordering uses the placement epoch (a counter that can't disagree between machines) instead of wall-clocks, so two machines with slightly different clocks can't make history look like a conversation was in two places at once — the exact confusion you'd be diagnosing. Copied diaries from other machines are labeled as copies with their staleness in milliseconds, so nothing ever mistakes a replica for live truth. Duplicate move records (from operation retries) collapse to one. A corrupted line degrades the answer and says so — it never crashes the query.
+
+The reads can't hurt a loaded box: newest-first with hard ceilings on bytes scanned, an honest "partial result" flag when a bound is hit, and the one exemption the review demanded — placement history (tiny, kept forever) is always answer-complete, so old history doesn't become unreachable just because it's old.
+
+Two structural guards ride along. First, the reader is a deliberately separate module from the writer, and a new CI lint BANS every session-killing/spawning/moving module from importing it — "the diary never drives actions" is now build-enforced, not promised. Second, every agent's own documentation teaches the new endpoint (capability awareness rule): the moment this ships, agents know to reach for it when you ask "where did this conversation live?"
+
+Also closed: the one stop-path from P1.1 that relied on the once-a-minute observer (emergency stops via Telegram) now reports instantly. Tier-3 boot test proves the feature is genuinely alive in a production-shaped server, not just in unit tests.

package/upgrades/coherence-journal-p1-3.eli16.md

@@ -0,0 +1,13 @@
+# The diaries start syncing between machines (P1.3 — the apply engine)
+
+This is the piece that finally answers your EXO question from EITHER machine. P1.1 made each machine keep its diaries; P1.2 made them readable; P1.3 lets machines safely exchange copies — so when you ask the Laptop "where did the Mini's overnight run put its files?", the Laptop actually knows, because it holds a copy of the Mini's diary.
+
+The hard part of syncing isn't the copying — it's not getting fooled. This is the receive-and-serve ENGINE, built with every defense the review demanded as real, tested code:
+
+- **A machine can only hand over ITS OWN diary.** Every incoming line must be signed (at the transport layer) by the same machine it claims to be from; a machine trying to pass off a third machine's history is rejected and counted. So one confused or compromised machine cannot rewrite everyone's records.
+- **Every line is checked before it's saved** — right size, right sequence number (exactly the next one expected), valid shape. A corrupted line marks that one peer's stream "suspect" and stops there; it self-clears once the peer sends 20 clean lines in a row. A torn line from one peer can never poison the whole picture.
+- **Restore-from-backup is caught.** If a machine comes back from an old backup with its diary rewound, the "edition number" changes, the old copy is set aside (at most two kept, so a flapping machine can't fill the disk), and it's flagged loudly — instead of silently swallowing the machine's real new history forever.
+- **Gone-history is honest.** If a machine asks for diary lines that have aged out, it gets told "those were pruned" and records a visible gap, rather than asking forever for something that no longer exists.
+- **A copy isn't trusted until it's truly on disk.** The receiver saves and force-flushes a batch BEFORE it reports success — so a crash mid-sync can never leave a machine believing it has lines it actually lost.
+
+This PR is the engine and its 26 tests; the last wiring step — actually carrying the little "I'm at line N" notes on the existing 30-second machine check-in and pulling deltas — plus the live two-machine proof on your Laptop+Mini, is the closing step. The engine is deliberately built to be driven by that wiring without knowing anything about the network: pure, testable, and impossible to make the mistakes the review caught on paper.

package/upgrades/side-effects/coherence-journal-p1-1.md

@@ -0,0 +1,68 @@
+# Side-Effects Review — Coherence Journal P1.1 (writer core + emission wiring + registry lint)
+
+**Version / slug:** `coherence-journal-p1-1`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required as a PR-time pass — the DESIGN went through 4-round multi-reviewer convergence (security/scalability/adversarial/integration/lessons + codex-cli:gpt-5.5 external, report at docs/specs/reports/coherence-journal-convergence.md) and this implementation tracks that converged spec section-by-section; deviations are enumerated below`
+
+## Summary of the change
+
+Implements P1.1 of `docs/specs/COHERENCE-JOURNAL-SPEC.md` (converged, `approved: true`, Justin 2026-06-05): `CoherenceJournal` writer class (non-blocking enqueue-assigned seq, 250ms flusher, advisory lock, typed per-kind schemas, artifactPath jail, restart-proof op-key dedupe, incarnation + crash-safe highWaterSeq, per-kind rotation incl. rotate-never-delete); emission wiring — `StateManager.saveSession` status-diff funnel (session-lifecycle), `emitPlacement` paired at all 8 ownership-CAS call sites (server.ts ownAction ×4, router place/claim, transfer-planner release, POST /pool/transfer release), reaper `reaped` emit beside the reap-log append, autonomous-run scanner (60s) + stop-funnel seam; `StateManager.guardJournalWrite` (standby-safe, prefix-allowlisted); `src/data/state-coherence-registry.json` (66 census categories) + `scripts/lint-state-registry.js` and `scripts/lint-cas-emit-placement.js`, both chained in `package.json` lint; ConfigDefaults + types (dark-ship: `enabled ?? !!developmentAgent`).
+
+## Decision-point inventory
+
+- `StateManager.guardJournalWrite` — ADD — permits journal-prefix writes on a read-only standby (independent of `_sessionPoolActive`); REFUSES paths escaping the canonicalized journal prefix. Spec §3.1; 7 tests.
+- `lint-state-registry` / `lint-cas-emit-placement` — ADD — CI-time guardrails (build fails, never runtime).
+- The journal writer itself holds NO runtime decision authority: emits are observational, never gate the observed operation (§3.9), and every emit path is wrapped so a journal failure cannot throw into or slow its caller.
+
+## 1. Over-block
+
+`guardJournalWrite` could over-block only by mis-canonicalizing a legitimate journal path — covered by tests (own streams, peers/, meta/lock sidecars all permitted; sibling-prefix dirs refused). The CI lints can over-block future PRs on false positives: `lint-state-registry` accepts the `/* state-registry: <category> */` inline annotation as the documented escape; `lint-cas-emit-placement` pairs per-token within ±12 lines (calibrated against all 8 real sites). No runtime over-block surface.
+
+## 2. Under-block
+
+The lints are guardrails, not proofs (stated in their headers + the spec): wrapper-hidden writes/CAS calls can evade the pattern sweep. The declared duty ("new store registers itself"; "every ownership mutation pairs an emit") remains the authority. Accepted per the converged spec §3.3/§3.6.
+
+## 3. Level-of-abstraction fit
+
+One refinement over the spec letter, at a STRONGER layer: §3.3 prescribed a `recordLifecycle(sessionId, status)` funnel that the (eleven) SessionManager status-transition sites call. Implemented instead INSIDE `StateManager.saveSession` as a status-diff (prev-on-disk vs next): every transition already passes through saveSession, so no call site exists to forget — the exact drift the spec's own convergence flagged about "naming three sites". The spec's intent (single funnel, no per-site wiring, per-transition wiring tests) is preserved and strengthened; the letter (a SessionManager method) is deviated from, recorded here.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no runtime block/allow surface (the journal is signal-only by spec §3.9; the lints act at CI, the documented place for structural guards).
+
+## 5. Interactions
+
+- **saveSession funnel:** adds one small read-before-write per save (non-hot path); a journal emit failure is swallowed (tested: throwing journal, saveSession still persists). No emit on metadata-only saves (status unchanged) — tested.
+- **Double-fire:** scanner observed-stopped + funnel-stop emit for the same run collapse via the shared `(topic, runId, action)` op key and the shared `autonomousRunId()` formula (exported, single source). placement emit retries collapse via `(topic, epoch)`.
+- **Races:** two server processes — the advisory lock makes the second writer a surfaced no-op (tested: no torn lines, no forked seq). Reaper + funnel both touching a session: 'reaped' is emitted ONLY at the reap event (funnel maps killed/completed/failed), no double-status.
+- **Shadowing:** `guardJournalWrite` is additive; the existing private `guardWrite` and its `sessionScoped` semantics are untouched.
+- **Feedback loops:** the journal subsystem emits nothing about itself (writer excluded; scanner reads `.local.md` files only).
+
+## 6. External surfaces
+
+- **Other agents/fleet:** dark-ship — `enabled ?? !!developmentAgent`; fleet agents get inert config via `migrateConfig`'s applyDefaults backfill (Migration Parity §3.8). The two lints run for every CONTRIBUTOR build (CI-time, not agent-runtime).
+- **Persistent state:** new files only under `state/coherence-journal/` (registered as the registry's first entry). Stored session records unchanged.
+- **Spec deviations recorded:** (1) funnel-at-saveSession (above, stronger); (2) journal SessionStatus enum gains `'failed'` — Session records carry a real terminal `failed` the spec's §3.2 enum missed; recording it as killed/completed would misstate history (additive; readers ignore unknowns); (3) TelegramAdapter's emergency-stop `stopAutonomousTopic` call site is NOT directly seamed (the adapter holds no StateManager) — covered by the scanner's observed-stopped within ≤60s per the spec's own defense-in-depth; direct seam rides P1.2 when the adapter is touched anyway <!-- tracked: multimachine-coherence-topic-placement-history-api -->; (4) Agent-Awareness CLAUDE.md template entry ships with the READ API in P1.2 per spec §3.8 (no route exists yet to document).
+- **The cas-pairing lint caught a real miss during development:** the `POST /pool/transfer` release half had no emit until the lint flagged it — the structural guard demonstrably works.
+
+## 7. Rollback cost
+
+Code revert + patch release. Journal files left on disk are inert and plain-JSONL readable (spec §3.7 rollback semantics). Lint + registry JSON revert together (same PR, same revert). No data migration; no agent state repair.
+
+## Conclusion
+
+Implementation tracks the converged spec with four recorded, rationale-carrying deviations (none weakening a safety property; two strengthening). The riskiest surface — hot-path cost — is structurally bounded (memory-only emit, fault-injection tested). 56 new tests green + 357 across the affected surface; both new lints clean on the real tree; tsc clean. Clear to ship dark.
+
+## Second-pass review (if required)
+
+**Reviewer:** design-level convergence panel (4 rounds, 5 perspectives + external cross-model)
+**Independent read of the artifact:** the convergence report stands as the design review; PR CI + operator spot-check per Tier-2 process.
+
+## Evidence pointers
+
+- `tests/unit/CoherenceJournal.test.ts` (33), `coherence-journal-wiring.test.ts` (9, independent oracles), `state-manager-guard-journal-write.test.ts` (7), `lint-state-registry.test.ts` (7)
+- `node scripts/lint-state-registry.js` → clean (66 categories); `node scripts/lint-cas-emit-placement.js` → clean (8 sites)
+- Affected surface: 29 files / 357 tests green; `tsc --noEmit` clean

package/upgrades/side-effects/coherence-journal-p1-2.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — Coherence Journal P1.2 (read API + awareness + actuation-ban lint)
+
+**Version / slug:** `coherence-journal-p1-2`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required as a PR-time pass — design converged in the 4-round spec review (docs/specs/reports/coherence-journal-convergence.md); implementation tracks §3.5/§3.8/§3.9`
+
+## Summary of the change
+
+P1.2 of the approved COHERENCE-JOURNAL-SPEC: `CoherenceJournalReader` (standalone module; bounded merged reads per §3.5 — reverse-tail via the writer's shared tolerant reader, 4MB per-query byte ceiling, 8-archive generic cap with the topic-placement answer-complete exemption, `(epoch,ts)` placement ordering vs `(ts,machineId,seq)` otherwise, opaque keyset cursor matching the query's order key, `(topic,epoch)` first-seen collapse, replica/staleness tagging, param-hygiene by enumeration); `GET /coherence/journal` route (Bearer, 503-when-dark, 400 on malformed cursor); `lint-journal-actuation-ban` (§3.9 — actuator modules may not import the reader; chained in `lint`); CLAUDE.md template Capabilities entry + Registry-First row + proactive triggers (Agent Awareness); site docs coverage; TelegramAdapter emergency-stop seam (closing the P1.1 deviation); Tier-3 e2e lifecycle test.
+
+## Decision-point inventory
+
+- `GET /coherence/journal` — ADD — read-only; 503 when dark; no actuation surface.
+- `lint-journal-actuation-ban` — ADD — CI-time guard (build fails; never runtime).
+- No runtime block/allow decisions added or modified.
+
+## 1. Over-block
+Read path: a malformed cursor returns a clean 400 (tested); traversal-shaped `machine`/`kind` filters match nothing rather than erroring (tested). The actuation-ban lint could over-block a legitimate future consumer inside an actuator file — that is the DESIGN (the consumer should read the live store; §3.9), and the lint message says so.
+
+## 2. Under-block
+The lint bans imports of the reader module in an enumerated actuator list — a new actuator file or a hand-rolled JSONL read evades it (stated guardrail framing; the §3.9 duty is the authority). The enumerated-list shape is deliberate: growable, reviewable.
+
+## 3. Level-of-abstraction fit
+Reader as a separate module (not writer methods) exists precisely so the import-ban lint has a clean target; route is a thin adapter over it. Right layers.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+- [x] No — this change has no runtime block/allow surface. (The journal remains signal-only; this PR adds the structural enforcement OF that.)
+
+## 5. Interactions
+- Reads share `readTailTolerant` with the writer (single tolerant-parse implementation, no drift).
+- `recvTs` for replicas uses replica-file mtime as best-effort until P1.3's apply path stamps real receipt times — recorded limitation, surfaced in the field's semantics, not hidden.
+- Stream `status` is `current` for all streams in P1.2; the replication states (`behind/gapped/suspect/reset/writer-locked-out`) arrive with P1.3's apply machinery. The shape is already in the response so consumers build against it now.
+- The TelegramAdapter seam is injection-only (setter); absent → previous behavior (scanner coverage within ≤60s).
+
+## 6. External surfaces
+- New GET route behind the standard Bearer middleware; 503 when dark — fleet agents (dark) expose a clean "not enabled" rather than a 404 that reads as "wrong version".
+- CLAUDE.md template + migrateClaudeMd: existing agents' docs gain the capability block on update (Agent Awareness + Migration Parity).
+- No persistent-state changes beyond reads.
+
+## 7. Rollback cost
+Code revert + patch. No state, no migration. Template section removal rides the same revert.
+
+## Conclusion
+Read-side honesty (staleness labels, partial-result flags, skew-proof ordering) implemented exactly as converged; the §3.9 ban is now structural. Clear to ship dark.
+
+## Second-pass review (if required)
+**Reviewer:** convergence panel (design-time)
+**Independent read of the artifact:** PR CI + operator spot-check per process.
+
+## Evidence pointers
+- `tests/unit/CoherenceJournalReader.test.ts` (15) + `tests/integration/coherence-journal-route.test.ts` (7) green; e2e lifecycle test (agent-built, see PR); writer/wiring/guard suites unaffected (46 adjacent tests green).
+- `node scripts/lint-journal-actuation-ban.js` → clean (8 actuator modules).

package/upgrades/side-effects/coherence-journal-p1-3.md

@@ -0,0 +1,49 @@
+# Side-Effects Review — Coherence Journal P1.3 (replication apply/serve engine)
+
+**Version / slug:** `coherence-journal-p1-3`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required as a PR-time pass — design converged in the 4-round spec review; this is the §3.4 engine, mesh-independent and pure`
+
+## Summary of the change
+
+`JournalSyncApplier` — the RECEIVE + own-stream SERVE engine for journal replication, implementing COHERENCE-JOURNAL-SPEC §3.4 rules 1-4 as a pure module (no mesh/server dependency; the mesh wiring is the closing step). `apply(senderMachineId, batch)`: first-hop sender binding (entry.machine===sender or reject+count; replica path derived from sender, never payload), schema-validated apply (size/seq/ts/kind/typed-data; failure→suspect+stop, self-clear after K=20), incarnation fencing (new incarnation→quarantine ≤2 + coalesced divergence signal + reset-flapping past 3), truncation signals (oldestRetainedSeq→gap sentinel+fast-forward+gapped). `buildServeBatch`: own-stream, durably-flushed-only (reads the file), byte-capped, oldestRetainedSeq after rotation. Ack-after-fdatasync on the receive side (§4.1). Plus `getAdvertState`/`getStreamStatus`/`getDegradation`.
+
+## Decision-point inventory
+
+- The applier is pure logic with NO runtime actuation surface — it appends replica files and reports status. It makes no kill/spawn/place/transfer decision. Per §3.9, replica data it writes is read-only signal; the actuation-ban lint (shipped P1.2) guarantees no actuator imports the reader that serves it.
+
+## 1. Over-block
+The validation can reject a legitimate entry only if it genuinely violates seq-order/schema/sender-binding — each is the spec's required gate, and a rejection is counted + surfaced (suspect/forgedEntries), never silent.
+
+## 2. Under-block
+First-hop-only means a 3rd machine's genuine history that arrives via a relay is rejected — accepted P1 limitation (transitive relay needs per-entry signatures, explicitly out of P1). Documented.
+
+## 3. Level-of-abstraction fit
+Pure engine, mesh-injected by the caller — the right seam: it is unit-testable without a two-machine setup (26 tests prove every §3.4 rule deterministically), and the network layer can't smuggle logic past it.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+- [x] No — the applier writes signal data (replica streams); it holds no block/allow authority. The §3.9 actuation ban (lint, P1.2) keeps it signal-only structurally.
+
+## 5. Interactions
+- Writes replica files + `peers/<machine>.meta.json` that `CoherenceJournalReader` already reads (incarnation top-level, per-kind lastHeldSeq/status) — verified shape-compatible.
+- Quarantine eviction routes through `SafeFsExecutor.safeRmSync` (destructive-fs funnel) — not raw unlink.
+- Ack-after-fsync: an fsync failure reports 0 applied and does NOT advance lastHeldSeq (no false-durable claim that could desync a peer).
+- guardWrite refusal (standby/prefix) → batch skipped + counted, never thrown.
+
+## 6. External surfaces
+- No route, no mesh verb yet (this is the engine; the `journal-sync` verb + session-status advert ride the closing wiring step). No external surface change in THIS PR beyond new replica files under `state/coherence-journal/peers/` when the engine is eventually driven.
+
+## 7. Rollback cost
+Pure code revert + patch. Replica files are inert plain JSONL. No migration.
+
+## Conclusion
+The §3.4 trust model — the load-bearing reason replication can't become a new incoherence source — is implemented as deterministic, fault-injected-tested code ahead of any network exposure. Recorded deviations: forged entries reject+count without marking suspect (rule 1 = trust violation, distinct from rule 2 torn-write); buildServeBatch takes explicit ownMachineId (keeps the module symmetric/pure); incarnation is a per-stream-set token (reconciles the prompt phrasing to the spec). Clear to ship as the engine; the wiring + live two-machine proof is the closing step.
+
+## Second-pass review (if required)
+**Reviewer:** convergence panel (design-time §3.4)
+**Independent read of the artifact:** PR CI + the live two-machine proof (approved) as the closing verification.
+
+## Evidence pointers
+- `tests/unit/JournalSyncApplier.test.ts` (26) — every §3.4 rule incl. ack-after-fsync ordering (injected fs spy), guardWrite refusal, quarantine bounds.

package/upgrades/1.3.339.md

@@ -1,48 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: minor -->
-
-## What Changed
-
-Adds a **learning-velocity metric** — Salim Ismail's EXO 3.0 KPI inversion (from
-*Your KPI System Is Training You to Miss the Future*). Backward-looking
-operational KPIs (throughput, utilization, efficiency) reward the existing model
-and suppress the weak signals where the future shows up. The EXO 3.0 answer is to
-measure how fast you're **learning** — adaptability, experimentation, capability
-creation.
-
-Instar already emits the raw learning events (registered learnings, captured
-corrections, evolution actions); this turns them into a signal:
-
-- `GET /metrics/learning-velocity?windowDays=30` → `{ totalEvents, eventsPerDay,
-  byType, typeDiversity, trend, adaptabilityScore, reason }`.
-- `trend` is `accelerating` | `steady` | `declining` | `insufficient-data`
-  (first-half vs second-half of the window).
-- `adaptabilityScore` (0–100) blends velocity (saturating) with category
-  diversity.
-
-Read-only + advisory — it never gates anything. A flat or declining trend is the
-EXO 3.0 warning sign that the org is optimizing the old model instead of learning.
-
-## What to Tell Your User
-
-Your agent can now answer "are we actually learning, or just running?" with real numbers. Ask it for its learning velocity and you get a trend — accelerating, steady, or declining — built from its genuine learning events (lessons it recorded, corrections it absorbed, capabilities it grew) instead of backward-looking activity stats. The EXO 3.0 idea behind it: traditional KPIs measure how well the OLD model runs; learning velocity measures whether you're building the next one. A flat or declining trend is your early warning that things are coasting.
-
-## Summary of New Capabilities
-
-- `GET /metrics/learning-velocity?windowDays=30` — `{ totalEvents, eventsPerDay, byType, typeDiversity, trend, adaptabilityScore (0-100), reason }`, computed from registered learnings, corrections, and evolution actions. Read-only + advisory — never gates.
-- PROACTIVE trigger: "are we learning/adapting?" → read this metric and contrast it with operational throughput.
-
-## Evidence
-
-Three-tier coverage, all green, `tsc --noEmit` clean:
-
-- Unit — `LearningVelocityScorer.test.ts` (6): empty, window exclusion,
-  accelerating, declining, insufficient-data, and byType/diversity/adaptability.
-- Integration — `learning-velocity-routes.test.ts` (3): the route reads a real
-  `learning-registry.json` + corrections over HTTP and computes.
-- E2E — `learning-velocity-lifecycle.test.ts` (1): a real server on a real port,
-  feature alive end-to-end (200, not 404/503).
-
-CLAUDE.md scaffold template documents the endpoint.