instar 1.3.490 → 1.3.492

package/src/data/state-coherence-registry.json

@@ -1,5 +1,5 @@
 {
-  "$schema-note": "Machine form of docs/specs/STATE-COHERENCE-REGISTRY.md (the approved census, census-date 2026-06-05). AUTHORED, NOT build-generated (committed-generated-manifest conflict-loop lesson, COHERENCE-JOURNAL-SPEC \u00a73.6). One entry per durable state category the census enumerates. Consumed by scripts/lint-state-registry.js: every direct durable-write site targeting a state dir / .instar/ must match an entry's `paths` (or carry an inline `/* state-registry: <category> */` annotation). Fields: category (kebab-case id) | description | scope (machine-local | must-be-coherent | derived-cache | coherent-on-demand) | freshness (real-time | eventual | session-boundary | n/a) | conflictShape (single-writer | append-only | lww | n/a) | transport (git | peer-http | none | deferred) | paths (glob-ish hints) | grandfathered (census marked uncertainty, \u00a74e). New state declares its class here at birth.",
+  "$schema-note": "Machine form of docs/specs/STATE-COHERENCE-REGISTRY.md (the approved census, census-date 2026-06-05). AUTHORED, NOT build-generated (committed-generated-manifest conflict-loop lesson, COHERENCE-JOURNAL-SPEC §3.6). One entry per durable state category the census enumerates. Consumed by scripts/lint-state-registry.js: every direct durable-write site targeting a state dir / .instar/ must match an entry's `paths` (or carry an inline `/* state-registry: <category> */` annotation). Fields: category (kebab-case id) | description | scope (machine-local | must-be-coherent | derived-cache | coherent-on-demand) | freshness (real-time | eventual | session-boundary | n/a) | conflictShape (single-writer | append-only | lww | n/a) | transport (git | peer-http | none | deferred) | paths (glob-ish hints) | grandfathered (census marked uncertainty, §4e). New state declares its class here at birth.",
   "version": 1,
   "censusDate": "2026-06-05",
   "sourceDoc": "docs/specs/STATE-COHERENCE-REGISTRY.md",
@@ -18,7 +18,7 @@
     },
     {
       "category": "pending-pulls",
-      "description": "Durable working-set pending-pull ledger - outstanding fetches whose producer was offline/unreachable/revoked/mid-run; re-fired on reappearance/run-stopped (WORKING-SET-HANDOFF-SPEC P2 \u00a73.4). Machine-local: records describe THIS machine's outstanding fetches; single-writer serialized mutate() funnel.",
+      "description": "Durable working-set pending-pull ledger - outstanding fetches whose producer was offline/unreachable/revoked/mid-run; re-fired on reappearance/run-stopped (WORKING-SET-HANDOFF-SPEC P2 §3.4). Machine-local: records describe THIS machine's outstanding fetches; single-writer serialized mutate() funnel.",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -30,7 +30,7 @@
     },
     {
       "category": "pull-opkeys",
-      "description": "Durable (topic,epoch) operation-key window for working-set pull dedupe - restart-proof at-most-once scheduling per move (WORKING-SET-HANDOFF-SPEC P2 \u00a73.3). Machine-local, bounded window (200 keys), single-writer (the coordinator).",
+      "description": "Durable (topic,epoch) operation-key window for working-set pull dedupe - restart-proof at-most-once scheduling per move (WORKING-SET-HANDOFF-SPEC P2 §3.3). Machine-local, bounded window (200 keys), single-writer (the coordinator).",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -42,7 +42,7 @@
     },
     {
       "category": "visibility-guard",
-      "description": "Peer-visibility guard dedupe state - which improper revocations were already surfaced (keyed on revokedAt, cross-boot) + per-machine disappearance episodes for flap bounding (WORKING-SET-HANDOFF-SPEC P2 \u00a73.6). Machine-local notice hygiene, never authority.",
+      "description": "Peer-visibility guard dedupe state - which improper revocations were already surfaced (keyed on revokedAt, cross-boot) + per-machine disappearance episodes for flap bounding (WORKING-SET-HANDOFF-SPEC P2 §3.6). Machine-local notice hygiene, never authority.",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -66,7 +66,7 @@
     },
     {
       "category": "commitment-replicas",
-      "description": "Per-peer read-only replicas of other machines' commitment stores (COMMITMENTS-COHERENCE-SPEC P1.5 \u00a73.2). Derived cache - rebuilt by a full re-pull; written ONLY by the commitments-sync receive path; first-hop sender-bound; incarnation-fenced.",
+      "description": "Per-peer read-only replicas of other machines' commitment stores (COMMITMENTS-COHERENCE-SPEC P1.5 §3.2). Derived cache - rebuilt by a full re-pull; written ONLY by the commitments-sync receive path; first-hop sender-bound; incarnation-fenced.",
       "scope": "derived-cache",
       "freshness": "eventual",
       "conflictShape": "single-writer",
@@ -78,7 +78,7 @@
     },
     {
       "category": "commitment-pending-mutations",
-      "description": "Durable owner-routed mutation intents awaiting an offline owner (COMMITMENTS-COHERENCE-SPEC P1.5 \u00a73.4). Stores INTENT only - a FRESH signed envelope is re-issued at fire time; single-writer serialized funnel; per-(origin,id) and per-owner enqueue bounds; TTL 7d with one honest expiry notice.",
+      "description": "Durable owner-routed mutation intents awaiting an offline owner (COMMITMENTS-COHERENCE-SPEC P1.5 §3.4). Stores INTENT only - a FRESH signed envelope is re-issued at fire time; single-writer serialized funnel; per-(origin,id) and per-owner enqueue bounds; TTL 7d with one honest expiry notice.",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -90,7 +90,7 @@
     },
     {
       "category": "commitment-opkeys",
-      "description": "Owner-side durable opKey replay window for commitment-mutate (COMMITMENTS-COHERENCE-SPEC P1.5 \u00a73.4) - the replay control beyond the 60s envelope nonce window; records verdicts, survives restarts, TTL >= pending-mutation TTL.",
+      "description": "Owner-side durable opKey replay window for commitment-mutate (COMMITMENTS-COHERENCE-SPEC P1.5 §3.4) - the replay control beyond the 60s envelope nonce window; records verdicts, survives restarts, TTL >= pending-mutation TTL.",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -246,7 +246,7 @@
     },
     {
       "category": "job-definitions",
-      "description": "Declarative job definitions (cron / prompt / supervision). The coherent half of jobs.json plus markdown job specs; run state is machine-local (see job-run-state). Field split required before whole-file sync (census \u00a75).",
+      "description": "Declarative job definitions (cron / prompt / supervision). The coherent half of jobs.json plus markdown job specs; run state is machine-local (see job-run-state). Field split required before whole-file sync (census §5).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "lww",
@@ -344,7 +344,7 @@
     },
     {
       "category": "fleet-config",
-      "description": "Fleet-wide config: feature flags, messaging[] config, monitoring tunables, multiMachine policy. SHARES config.json with machine-local fields (port, paths) -- split-required before whole-file sync (census \u00a75).",
+      "description": "Fleet-wide config: feature flags, messaging[] config, monitoring tunables, multiMachine policy. SHARES config.json with machine-local fields (port, paths) -- split-required before whole-file sync (census §5).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "lww",
@@ -561,7 +561,7 @@
     },
     {
       "category": "audit-destructive-ops",
-      "description": "Destructive-ops audit stream (411M live -- needs rotation, census \u00a77). Append-only per-machine.",
+      "description": "Destructive-ops audit stream (411M live -- needs rotation, census §7). Append-only per-machine.",
       "scope": "machine-local",
       "freshness": "n/a",
       "conflictShape": "append-only",
@@ -806,7 +806,7 @@
     },
     {
       "category": "derived-semantic-memory",
-      "description": "semantic.db / memory.db / episodes -- rebuildable from evidence. (Live-disk: stale since Jun 1 -- investigate separately, census \u00a71.6/\u00a77.)",
+      "description": "semantic.db / memory.db / episodes -- rebuildable from evidence. (Live-disk: stale since Jun 1 -- investigate separately, census §1.6/§7.)",
       "scope": "derived-cache",
       "freshness": "eventual",
       "conflictShape": "n/a",
@@ -909,7 +909,7 @@
     },
     {
       "category": "uncertain-instructions-tracking",
-      "description": "state/instructions-tracking/ (59M, 15,180 UUID-keyed JSONL files). Census did not map an owner; volume says it matters. Owner + rotation + class needed (census \u00a74e).",
+      "description": "state/instructions-tracking/ (59M, 15,180 UUID-keyed JSONL files). Census did not map an owner; volume says it matters. Owner + rotation + class needed (census §4e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -921,7 +921,7 @@
     },
     {
       "category": "uncertain-topic-intent-store",
-      "description": "TopicIntentStore. Code references it; on-disk location unverified (census \u00a74e).",
+      "description": "TopicIntentStore. Code references it; on-disk location unverified (census §4e).",
       "scope": "derived-cache",
       "freshness": "eventual",
       "conflictShape": "n/a",
@@ -934,7 +934,7 @@
     },
     {
       "category": "uncertain-shared-state-ledger",
-      "description": "shared-state.jsonl (SharedStateLedger). Nominally the git-synced cross-machine ledger -- is anything consuming it on real machines? May be the vestigial ancestor of the P1 journal (census \u00a74e).",
+      "description": "shared-state.jsonl (SharedStateLedger). Nominally the git-synced cross-machine ledger -- is anything consuming it on real machines? May be the vestigial ancestor of the P1 journal (census §4e).",
       "scope": "must-be-coherent",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -947,7 +947,7 @@
     },
     {
       "category": "uncertain-correction-capture-backlog",
-      "description": "correction-capture-backlog.db vs correction-ledger.db: two stores, one sentinel -- which is canonical? (census \u00a74e).",
+      "description": "correction-capture-backlog.db vs correction-ledger.db: two stores, one sentinel -- which is canonical? (census §4e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "append-only",
@@ -959,7 +959,7 @@
     },
     {
       "category": "uncertain-project-round-worktrees",
-      "description": "ProjectRoundWorktrees / TaskFlow stores. Routes-managed; durable form unverified (census \u00a74e).",
+      "description": "ProjectRoundWorktrees / TaskFlow stores. Routes-managed; durable form unverified (census §4e).",
       "scope": "machine-local",
       "freshness": "eventual",
       "conflictShape": "single-writer",
@@ -972,7 +972,7 @@
     },
     {
       "category": "legacy-singletons",
-      "description": "Stale legacy singletons (anti-patterns.json, quick-facts.json, project-registry.json, May 20 vintage, no live writers found). Retire per census \u00a77.",
+      "description": "Stale legacy singletons (anti-patterns.json, quick-facts.json, project-registry.json, May 20 vintage, no live writers found). Retire per census §7.",
       "scope": "machine-local",
       "freshness": "n/a",
       "conflictShape": "single-writer",
@@ -998,7 +998,7 @@
     },
     {
       "category": "stream-tickets",
-      "description": "Pool Dashboard Streaming single-use bearer tickets (POOL-DASHBOARD-STREAM-SPEC \u00a72.3). Minted by the pool-stream-ticket mesh verb, consumed once on the /pool-stream WS upgrade. Persisted so a captured ticket cannot replay across a serving-machine restart (consumed-set survives). Machine-local; single-writer (the store's own funnel); TTL-bounded + GC'd.",
+      "description": "Pool Dashboard Streaming single-use bearer tickets (POOL-DASHBOARD-STREAM-SPEC §2.3). Minted by the pool-stream-ticket mesh verb, consumed once on the /pool-stream WS upgrade. Persisted so a captured ticket cannot replay across a serving-machine restart (consumed-set survives). Machine-local; single-writer (the store's own funnel); TTL-bounded + GC'd.",
       "scope": "machine-local",
       "freshness": "live",
       "conflictShape": "single-writer",
@@ -1007,6 +1007,42 @@
         "state/stream-tickets.json"
       ],
       "grandfathered": false
+    },
+    {
+      "category": "guard-posture-snapshot",
+      "description": "Boot-time guard posture snapshot written by the GuardPostureTripwire at every server boot; read by GET /guards for diverged-pending-restart derivation (GUARD-POSTURE-ENDPOINT-SPEC §2.2). Machine-local observability, never authority.",
+      "scope": "machine-local",
+      "freshness": "boot",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/guard-posture.json"
+      ],
+      "grandfathered": false
+    },
+    {
+      "category": "guard-posture-peers",
+      "description": "Durable last-known guard posture per peer machine with RECEIVER-side receipt time (GUARD-POSTURE-ENDPOINT-SPEC §2.3(c)) - survives local restarts so a dark peer's posture renders with its honest age. Written only at the heartbeat-ingestion chokepoint (registry-keyed identity). Machine-local observability, never authority.",
+      "scope": "machine-local",
+      "freshness": "live",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/guard-posture-peers.json"
+      ],
+      "grandfathered": false
+    },
+    {
+      "category": "guard-posture-episodes",
+      "description": "GuardPostureProbe episode state - per-anomaly first/last-seen for the persist-across-ticks rule, flap windows, and the open-episode marker that keeps alerts to ONE aggregated Attention item per episode (GUARD-POSTURE-ENDPOINT-SPEC §2.4). Machine-local notice hygiene, never authority.",
+      "scope": "machine-local",
+      "freshness": "live",
+      "conflictShape": "single-writer",
+      "transport": "none",
+      "paths": [
+        "state/guard-posture-episodes.json"
+      ],
+      "grandfathered": false
     }
   ]
 }

package/src/scaffold/templates.ts

@@ -419,6 +419,15 @@ 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.
 
+### Guard Posture — which safety systems are genuinely on (\`GET /guards\`)
+
+Every guard (monitoring sentinels, reapers, the scheduler, …) is graded by what can be VERIFIED, never by what the config wishes: \`on-confirmed\` / \`on-unverified\` / \`on-stale\` / \`on-dry-run\` / \`off\` (\`dark-default\` = ships-dark, quiet vs \`diverged-from-default\` = default-on but currently off — the load-shed signature) / \`diverged-pending-restart\` / \`errored\` / \`missing\` / \`off-runtime-divergent\`. Only the "off that shouldn't be off" and runtime-contradiction classes alert — a ships-dark feature that is off is normal, never noise.
+- This machine: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/guards\`
+- Every machine (heartbeat-fresh, or last-known posture with its age for a dark peer): \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/guards?scope=pool"\`
+- **When to use** (PROACTIVE — this is the trigger): "are my guards on?" / "why didn't the watchdog/reaper fire on machine X?" / a post-incident sweep after ANY load-shed → read \`/guards?scope=pool\` and report the deviant rows instead of guessing from config memory. The Machines dashboard tab shows each machine's last-known posture with its age — even for a peer that is currently dark.
+- **HAZARD — re-enabling a guard via \`PATCH /config\`**: send the guard's FULL config block (the merge is one-level-deep and a partial block erases sibling tuning); read the current block from the source machine first (\`GET /guards\` shows posture; the config block itself comes from that machine's config).
+- Three complementary layers, one shared inventory: the Guard-Posture Tripwire covers enabled→disabled transitions at boot (\`logs/guard-posture.jsonl\`); \`/guards\` is the steady-state read; the GuardPostureProbe raises ONE aggregated Attention item when an anomaly persists across consecutive probes.
+
 **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.

package/upgrades/1.3.491.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Implements `docs/specs/GUARD-POSTURE-ENDPOINT-SPEC.md` (converged 5 iterations, operator-approved 2026-06-12, topic 13481 — GAP-001: the Mac Mini's SessionReaper stayed disabled for a week because no API exposed a machine's guard posture).
+
+- **`GET /guards`** (Bearer-auth, read-only, always-on — deliberately no config gate): the full guard inventory (shared extractor ∪ declared manifest, one definition shared with the boot tripwire) with verification-graded effective states: `on-confirmed` / `on-unverified` / `on-stale` (dead tick loop — `enabled:true, lastTickAt:0` can never read green again) / `on-dry-run` / `off{dark-default | diverged-from-default}` / `diverged-pending-restart` (disk edit not yet live) / `errored` / `missing` (expected runtime never registered) / `off-runtime-divergent` (runtime contradicts an on-config — the in-memory load-shed class). Strict closed-field projection (sensitive guard config values like `alertTopicId` can never leak; Tier-1 leak tests).
+- **`GET /guards?scope=pool`**: every registered machine accounted for by name — a posture row or a classified failure row (`timeout | unreachable | unauthorized | route-missing | no-known-url | offline | url-rejected | error`), never a silent omission, never a 500. The Bearer token is only attached to https/allowlisted peer URLs (`src/server/peerUrlGuard.ts`, operator-extensible via `multiMachine.peerUrlAllowlist`); non-recursive; rate-limited.
+- **Heartbeat piggyback + durability**: the capacity heartbeat carries a compact posture block, bound to the authenticated sender at ingestion, aged by the RECEIVER's clock, persisted durably (`GuardPostureStore`) and reloaded at boot — a dark peer's last-known posture renders with its real age on the **Machines tab** ("guards: N on (M confirmed) · ⚠ … · as of 2d ago").
+- **GuardPostureProbe** (SystemReviewer family): persisting anomalies (deviant offs, runtime divergence, stale, missing, errored, flapping) raise ONE aggregated, episode-deduped Attention item; dark-default offs stay quiet; offline peers evaluated from durable last-known posture, never a doomed fan-out.
+- **Runtime self-registration**: SessionReaper, JobScheduler, SessionWatchdog, SocketDisconnect/ActiveWorkSilence/ContextWedge sentinels (+ the wedge's autoRecovery sub-row) register cheap sync `guardStatus()` getters into a boot `GuardRegistry`, reconciled against the declared manifest (`src/monitoring/guardManifest.ts` + `NOT_A_GUARD` classifications).
+- **CI ratchet**: `scripts/lint-guard-manifest.js` — every guard-shaped boot component must be classified in the manifest or `NOT_A_GUARD` with a real reason; ships with the complete backfill (a real finding: `WorktreeReaper` is dormant/unwired).
+- **Agent awareness + migration parity**: `generateClaudeMd()` Guards block (including the `PATCH /config` full-block warning — the one-level-deep merge erases sibling tuning) + content-sniffed `migrateClaudeMd()` migration; `/guards` registered in CAPABILITY_INDEX.
+- Remote guard FLIPPING is deliberately out of scope (authority expansion — tracked follow-up spec `GAP-001-remote-guard-flip`).
+
+## What to Tell Your User
+
+- "You can now see which safety systems are genuinely working on every machine — 'on in the settings' no longer counts as 'working'. The Machines tab shows each machine's guards with honest freshness, and I get one grouped alert if something that should be on stays off."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Honest guard posture, one machine | `GET /guards` (Bearer) — or ask the agent "are my guards on?" |
+| Fleet-wide posture sweep | `GET /guards?scope=pool` — every machine accounted by name |
+| Dark-peer last-known posture | Machines dashboard tab — posture line with real age |
+| Persisting-anomaly alert | Automatic (GuardPostureProbe → one aggregated Attention item per episode) |
+
+## Evidence
+
+- Tier-1: `tests/unit/monitoring/guard-posture-view.test.ts` (29 — every precedence-table edge incl. the `lastTickAt:0 → on-stale` Mini pin + projection/leak allowlists), `guard-posture-snapshot.test.ts` (10 — one-disk-read pin, dev-gate resolution), `guard-posture-probe.test.ts` (18 — episode/flap/data-source rules), `peer-url-guard.test.ts` (7), `lint-guard-manifest.test.ts` (11), `PostUpdateMigrator-guardsCapabilitySection.test.ts`.
+- Tier-2: `tests/integration/guards-route.test.ts` (15 — auth pins, classified peer failures over real ephemeral peer servers, token-never-attached on url-rejected, receiver-clock ingestion + durable reload).
+- Tier-3: `tests/e2e/guards-endpoint-lifecycle.test.ts` (17 — feature-alive 200 with the runtime-enrichment floor, disk-flip → `diverged-pending-restart` over real files, HTTP-level leak pin, wired source guards on every server.ts registration).
+- Side-effects artifact: `upgrades/side-effects/guard-posture-endpoint.md` (second-pass reviewed).

package/upgrades/1.3.492.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed instar#1069 — the cartographer doc-freshness sweep freezing the server. On a real tree (366,757 nodes; a 67MB `index.json`), enabling the sweep starved the server's event loop for ~35s at a stretch: `/health` stopped answering, and the lifeline supervisor (correctly) kill-looped the server every 10–15 minutes. Convergence review found the freeze was reachable through **six** distinct main-thread whole-tree operations, and this ships the complete close: the "what's stale?" detect now runs in a **worker thread** (the codebase's first) returning only a bounded candidate list + counts; every `/cartographer/*` read route serves a small **per-host snapshot** (with honest `snapshot`/`snapshotStale`/`lastDetectStatus` provenance) instead of recomputing live; the request-path lazy scaffold is gone (a chunked, yielding **boot-path** build replaces it — including a streamed index write, never one 67MB stringify); the under-sized `git ls-tree` buffer that would crash on a big tree got an explicit 64MB + named refusal; and the author path's per-node 67MB index rewrites became two bounded off-thread writes per pass. The worker is bounded in time (`detectTimeoutMs` → terminate + refuse) AND memory (heap cap + pre-parse byte guard, co-sized so the intended tree parses), runs with an env allowlist (no secrets), and every failure path is a named refusal feeding the existing signal-only breaker — never a silent fall-back to the old walk. A new build-time lint (`lint-no-mainthread-cartographer-walk`) plus an event-loop-lag test harness (<250ms over the real dist worker AND the boot scaffold) make the regression structurally hard to reintroduce. Bonus: `cartographer.freshnessSweep.framework` is now actually honored (explicit-set-only precedence, boot-logged) — it was decorative, which helped the bug hide.
+
+Rollback levers: `freshnessSweep.detectInWorker: false` runs the SAME bounded detect synchronously (never the legacy walk); `freshnessSweep.enabled: false` remains the master kill-switch. Migration parity: new config fields backfill via defaults; `.instar/cartographer/` becomes gitignored; the CLAUDE.md template gains the snapshot-semantics section.
+
+## What to Tell Your User
+
+If you turned on the background "keep the code map fresh" job and your agent's server started dying every few minutes — that's fixed. The heavy map-scanning work now runs off to the side where it can't freeze the server, and the map's health numbers are served from a cached snapshot with an honest age stamp ("as of N minutes ago") instead of being recomputed live. Nothing to configure; the fix applies on update. The sweep itself stays off until you choose to enable it.
+
+## Summary of New Capabilities
+
+- `/cartographer/health` + `/cartographer/stale` now carry snapshot provenance: `snapshot` (`present`/`absent`/`detect-failing`), `snapshotStale`, `ageMs`, `headSha`, `lastDetectStatus` — a broken or never-run detect is visible on the route, not silent.
+- `/cartographer/stale` serves a bounded sample with an honest `total` + `truncated` flag (secret-bearing path names filtered out).
+- `cartographer.freshnessSweep.framework` is the supported off-Claude routing knob (no manual `componentFrameworks` override needed); the boot log shows what resolved and why.
+- New event-loop-safety dials (all with safe defaults): `detectInWorker`, `detectTimeoutMs`, `detectWorkerHeapMb`, `maxIndexBytes`, `snapshotSampleMax`, `gitMaxBuffer`, `detectCandidateHeadroom`, `maxRequestNodes`, `scaffoldChunkNodes`.
+
+## Evidence
+
+- Event-loop-lag harness: detect over a 60,000-entry index in the REAL compiled dist worker AND a ~6,000-file boot scaffold both hold max sampled main-thread lag **< 250ms** (`tests/integration/cartographer-eventloop-worker.test.ts`, 5/5).
+- Unit: pure detect module 12/12 (bounded heap ordering w/ frozen golden, zero node-file reads, full refusal taxonomy, secret-filtered sample, index-sourced anti-starvation); refusal→breaker 1/1; routing precedence + Claude-floor 8/8; engine suite 16/16 against the rewritten pass.
+- Integration: snapshot-backed routes 11/11 (incl. "no lazy scaffold on request" assertions); refresh/navigate routes 21/21.
+- E2E: cartographer lifecycle, freshness lifecycle, dev-gate lifecycle all green on the snapshot contract.
+- Full unit suite: 31,778+ passed; the 9 initially-failing files all resolved (3 ratchet updates for this change, 1 dev-gate e2e contract update, 1 exec-bit fix, 1 REAL pre-existing test-isolation bug fixed at root in `emptyPromptCanary-llmFallback` (it polluted `~/.instar` with a persisted signature), 2 machine-env repairs, 1 standalone-green tmux-contention flake).
+- Side-effects review + REQUIRED second-pass review: `upgrades/side-effects/cartographer-sweep-eventloop-safety.md` — the reviewer raised 2 material concerns (boot scaffold's final 67MB stringify; the missing boot-scaffold lag test), both fixed before commit.
+- Spec: `docs/specs/CARTOGRAPHER-SWEEP-EVENTLOOP-SAFETY.md` (converged 5 rounds, zero material findings final round, approved by Justin). Deferred follow-ups tracked: instar#1073.

package/upgrades/side-effects/cartographer-sweep-eventloop-safety.md

@@ -0,0 +1,110 @@
+# Side-Effects Review — Cartographer Sweep Event-Loop Safety (fix instar#1069)
+
+**Version / slug:** `cartographer-sweep-eventloop-safety`
+**Date:** `2026-06-12`
+**Author:** `echo`
+**Second-pass reviewer:** `required` (touches a sentinel/breaker, a recovery/boot path, and HTTP route shapes)
+
+## Summary of the change
+
+Closes the complete class of O(nodeCount)/67MB synchronous cartographer operations that ran on the AgentServer's main event loop and put it into a supervisor kill-loop when the doc-freshness sweep was enabled on a real tree (366,757 nodes / 67MB `index.json`). The "what's stale?" detect, the revalidation re-parse, the request-path lazy scaffold, the health-route freshness walk, the under-buffered `git ls-tree`, and the per-node author-path index write all moved OFF the main thread. New: `src/core/cartographerDetect.ts` (pure, bounded detect/index-write module — heap-pass ordering, byte-guard, explicit 64MB git buffer, refusal taxonomy, zero node-file reads) + `src/core/cartographerDetect.worker.ts` (trivial worker entrypoint). `CartographerSweepEngine.runPass` now runs detect in a `worker_threads` worker (rollback: `detectInWorker:false` runs the same bounded module synchronously), batches all index updates into one off-thread write, single-flights, and remains lease-gated. Every `/cartographer/*` read route serves a per-host snapshot (`CartographerTree.readSnapshot`) or a byte-bounded load (`loadIndexBounded`), never a walk; the lazy `scaffold()`/`loadIndex()` preamble is gone and a boot-path chunked `scaffoldChunked` builds the index off-request. `CartographerIndexEntry` gained three optional mirrored fields (`staleSincePass`/`firstSeenAt`/`authorFailed`) so detect needs no node-file reads. A new path-allowlist lint (`scripts/lint-no-mainthread-cartographer-walk.js`) forbids the heavy calls in `routes.ts` + `CartographerSweepEngine.ts`. Migrations: config defaults (9 new `freshnessSweep` fields via `applyDefaults` backfill), `.instar/cartographer/` gitignore (init + repo + `PostUpdateMigrator`), and a `migrateClaudeMd` block. `cartographer.freshnessSweep.framework` is now honored as the sweep's routing (`resolveSweepFrameworkRouting`, explicit-set-only, boot-logged).
+
+## Decision-point inventory
+
+- `CartographerSweepEngine.probeRouting` — pass-through — unchanged; the off-Claude refusal floor (resolve-to-default + `!allowClaudeFallback` → refuse) is preserved verbatim.
+- `CartographerSweepPoller` breaker — pass-through — the poller is unmodified; detect refusals now arrive as `refused:true` and feed the existing breaker via the existing `classifyProgress` branch (they increment `zeroProgressTicks`, not `consecutiveZeroCandidate`).
+- New refusal reasons on the sweep (`detect-timeout`/`detect-worker-start-failure`/`detect-index-too-large`/`detect-index-unreadable`/`detect-git-error`) — add — all signal-only, all feed the existing breaker; no new user-facing gate.
+- Sweep routing precedence (`resolveSweepFrameworkRouting`) — modify — `freshnessSweep.framework` becomes the effective override **explicit-set-only** (a pre-existing `overrides.CartographerSweep` or an explicitly-set `categories.job` is never overridden); boot-logged.
+- `/cartographer/{health,stale,tree,node,navigate,node/refresh}` — modify — serve snapshot / byte-bounded / single-node-read; additive response fields; lazy scaffold removed.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The only new "rejections" are the detect refusal reasons, none of which block a user action — they are signal-only feeds to the sweep breaker (a backoff + degradation, never a hard stop, recovers on the next good tick). The `/tree` (full) route returns `indexState:'too-large-for-request'` above `maxRequestNodes` (default 50000) instead of serving the whole index — a deliberate bound, not an over-block: the data is still reachable via the already-bounded `/cartographer/navigate`, and the response says so. No message/dispatch/outbound block surface is touched.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- The inline `/cartographer/node/refresh` route still calls `setSummary` (one 67MB index parse+serialize) on a pathological tree — it is rate-limited (30/min) and agent-initiated, not the sweep, and is out of the six-starver inventory; the durable fix is the deferred index-format rework (sharding/SQLite), filed off #1069.
+- `git ls-tree` is buffered at an explicit 64MB rather than streamed; a tree whose `ls-tree` output exceeds 64MB refuses cleanly (`detect-git-error`) rather than streaming — the streaming upgrade is the documented deferred follow-up; the explicit buffer is the floor that stops today's ENOBUFS throw.
+- A genuinely too-large tree (over `maxIndexBytes`) leaves detect permanently refusing and the snapshot stale — the **accepted, honest** failure mode: `/health` surfaces `lastDetectStatus` + `snapshotStale`, and recovery is operator action (raise the cap / shard the index), by design.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The heavy work is a pure module (`cartographerDetect.ts`) that runs in a worker (off the loop) or synchronously (rollback) — the bounded logic lives once, in the right place, and is unit-testable in-process. The routes became thin snapshot/byte-bounded readers (the request thread should never compute, only serve). The boot scaffold lives off any request handler. The lint enforces the invariant structurally rather than by review. The schema fields were promoted onto the index (the layer detect actually reads) rather than re-derived. No logic was duplicated: the rollback path and the worker share the same module; the snapshot type is defined once and read by both `CartographerTree` (route) and the engine (write).
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change produces a signal consumed by an existing smart gate.
+
+The detect refusals are signals into the existing `CartographerSweepPoller` breaker, which is itself signal-only (it backs off cadence + emits a degradation + re-escalates; it never permanently disables the feature or blocks a user action, and recovers on the next successful tick). No new blocking authority is introduced. The lint is a build-time guard, not a runtime authority. The routes' `too-large-for-request` / `not-built` / snapshot-`absent` states are honest read responses, not gates.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The lazy scaffold preamble was removed from all `/cartographer/*` routes; nothing downstream relied on the routes building the index (verified: the CI ratchet `scripts/cartographer-freshness.mjs` re-derives staleness from git directly and never reads the snapshot/routes). The boot scaffold builds it instead.
+- **Double-fire:** Engine-level single-flight (`inflight`) plus the poller's existing reentrancy guard ensure at most one detect worker alive at a time; the boot scaffold is gated on the index not already existing.
+- **Races:** The two-writer race (defer-increment write vs author-summary write) is resolved by single-writer ordering within a pass (lease + single-flight make detect-phase write (a) and author-phase write (b) strictly sequential). Node files (small) are written on the main thread, bounded to `maxNodesPerPass`; a failed batched index write fails soft (node files are momentarily ahead; the next detect re-derives from git and re-converges).
+- **Feedback loops:** None. The snapshot is read-only state; detect re-derives from git each pass, so a stale/partial snapshot self-heals on the next tick.
+
+---
+
+## 6. External surfaces
+
+- **Other agents/users (fleet):** New `freshnessSweep` config fields backfill via `applyDefaults` (additive, existence-checked). `.instar/cartographer/` is now gitignored (init + repo + migrator) so the 67MB index/snapshot stop being committable. `migrateClaudeMd` adds one idempotent section. The boot scaffold now runs once at boot for any agent with `cartographer.enabled` and no index — matching the prior build-once behavior (the old routes only scaffolded when no index existed), just moved off the request path.
+- **HTTP route shapes:** `/health` + `/stale` gain additive snapshot-provenance fields (`snapshot`, `snapshotStale`, `headSha`, `lastDetectStatus`, `generatedAt`, plus `/stale`'s `total`/`truncated`); legacy field names/semantics (`nodeCount`, `authoredCount`, `staleCount`, `freshness.*`, `count`, `nodes`) are preserved. `/tree` (full) gains an `indexState` ceiling branch. No dashboard consumer of these routes exists (verified).
+- **Persistent state:** new per-host `snapshot.json` under `.instar/cartographer/` (gitignored, mode 0600, per-host tmp suffix); index entries gain optional fields (a v1 index parses unchanged — no rewrite migration, no loader version-gate).
+- **Timing:** the `/health` + `/stale` numbers are now last-known (age-stamped) rather than always-live — a deliberate "never freeze the server" trade, disclosed on the route via `snapshotStale`/`ageMs`.
+
+---
+
+## 7. Rollback cost
+
+Pure code change at the feature level; revert and ship a patch. No data migration needed to back out: the new optional index fields are ignored by old code (they coalesce), and the snapshot file is gitignored disposable per-host state. Two in-product rollback levers ship with the change: `freshnessSweep.detectInWorker:false` (run the bounded detect synchronously if the worker misbehaves) and `freshnessSweep.enabled:false` (the master kill-switch — the sweep was already shipped OFF, so the blast radius today is only agents that explicitly enabled it). No user-visible regression during a rollback window: the routes degrade to `absent`/`not-built` honestly rather than erroring.
+
+---
+
+## Conclusion
+
+The review produced no design changes beyond what the spec convergence already folded in; it confirmed the invariant is closed across all six starvers and that the only blocking surface (the sweep breaker) remains signal-only. Two honest residuals are documented (the rate-limited inline-refresh index write; the buffered-not-streamed `git ls-tree`), both out of the #1069 inventory and tracked to the deferred index-format rework. The change is clear to ship pending the second-pass review (required: it touches a breaker, a recovery/boot path, and route shapes).
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent subagent (general-purpose, adversarial read of artifact + code)
+**Independent read of the artifact: concern raised → resolved**
+
+The reviewer raised two material concerns and one nit; all were addressed before commit:
+
+- **CONCERN (resolved): boot-scaffold's final index serialization was a synchronous 67MB `JSON.stringify` on the main loop.** `scaffoldChunked` yielded during the walk + node-file writes but its final `buildIndex(nodes)` did one unbroken serialize — violating the boot half of the invariant. **Fix:** `scaffoldChunked` Pass 3 now STREAMS the index to a tmp file incrementally (bounded per-`chunkNodes`, yielding between chunks) and atomic-renames; no single full-index `JSON.stringify` on the loop. (`src/core/CartographerTree.ts` Pass 3.)
+- **CONCERN (resolved): the promised boot-scaffold lag test was missing.** **Fix:** added `tests/integration/cartographer-eventloop-worker.test.ts` → "boot scaffold (scaffoldChunked) does NOT starve the event loop on a large real tree (lag < 250ms)" (generates ~6000 real files, samples setInterval drift during `scaffoldChunked`, asserts max lag < 250ms + a readable index ≥ 6000 nodes).
+- **NIT (resolved): worker heap not co-sized to let a near-byte-guard index parse.** **Fix:** `detectWorkerHeapMb` default raised to 1536 and `maxIndexBytes` lowered to 200MB (200×6 ≈ 1200MB < 1536MB heap) across ConfigDefaults + engine/server fallbacks; comments corrected.
+
+The reviewer independently confirmed sound: the worker env allowlist omits all secrets; the worker's transitive imports drag no secret/server modules; every detect failure sets `refused:true` and feeds the breaker via `zeroProgressTicks`; no `catch` silently falls back to `staleNodes()`/`loadIndex()`; `timeout → await terminate()` reaps the child git; the two off-thread index writes are strictly sequential under single-flight + lease; new optional index fields coalesce with no loader version-gate; the heap ordering keeps peak O(maxCandidates) on cold + stale paths; routes preserve legacy fields additively; the breaker stays signal-only; routing precedence is explicit-set-only and boot-logged.
+
+---
+
+## Evidence pointers
+
+- Spec + convergence report: `docs/specs/CARTOGRAPHER-SWEEP-EVENTLOOP-SAFETY.md`, `docs/specs/reports/cartographer-sweep-eventloop-safety-convergence.md`, ELI16 `docs/specs/cartographer-sweep-eventloop-safety.eli16.md`.
+- Unit: `tests/unit/cartographerDetect.test.ts` (bounded/golden-order/zero-node-reads/refusal-taxonomy/secret-filter/defer/applyDeltas), `tests/unit/cartographer-sweep-poller-breaker.test.ts` (refusal→breaker), `tests/unit/cartographer-sweep-routing.test.ts` (framework precedence + claude-floor).
+- Integration: `tests/integration/cartographer-eventloop-worker.test.ts` (REAL dist worker; event-loop lag < 250ms on a 60k-entry index; timeout refusal; rollback), `tests/integration/cartographer-routes.test.ts` (snapshot-backed routes, no lazy scaffold).
+- E2E: `tests/e2e/cartographer-lifecycle.test.ts`, `tests/e2e/cartographer-freshness-lifecycle.test.ts` (author lifecycle + routes alive via snapshot).
+- Lint: `scripts/lint-no-mainthread-cartographer-walk.js` (clean; wired into `npm run lint`).
+- Build dist for the dist-backed test: `tests/setup/build-dist.globalSetup.ts` (wired into the integration + e2e vitest configs).

package/upgrades/side-effects/guard-posture-endpoint.md

@@ -0,0 +1,101 @@
+# Side-Effects Review — Guard-Posture Endpoint (GET /guards)
+
+**Version / slug:** `guard-posture-endpoint`
+**Date:** `2026-06-12`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `required (feature has "guard" in its name + touches monitoring surface) — pending, appended below before ship`
+
+## Summary of the change
+
+Implements the approved converged spec `docs/specs/GUARD-POSTURE-ENDPOINT-SPEC.md`: a read-only, Bearer-authenticated `GET /guards` endpoint reporting every shipped guard's honest effective state (on-confirmed / on-unverified / on-stale / on-dry-run / off{dark-default, diverged-from-default} / diverged-pending-restart / errored / missing / off-runtime-divergent), a static guard manifest + runtime GuardRegistry reconciled at boot, a compact posture block riding the existing capacity heartbeat with durable last-known persistence, a pool-scope fan-out accounting for every registered machine, a GuardPostureProbe raising one episode-deduped Attention item for persisting anomalies, a repo-CI manifest lint with complete component backfill, and the CLAUDE.md template/migration + CAPABILITY_INDEX awareness updates. Files: `src/monitoring/guardPosture.ts` (shared extractor lifted from GuardPostureTripwire — single funnel), `guardManifest.ts`, `GuardRegistry.ts`, `guardPostureView.ts`, `probes/GuardPostureProbe.ts`, routes/boot wiring, heartbeat types/sender/receiver, `scripts/lint-guard-manifest.js`, scaffold template + PostUpdateMigrator, three test tiers.
+
+## Decision-point inventory
+
+- `GET /guards` route — **add** — read-only projection; no block/allow decisions on any flow.
+- `GuardPostureProbe` — **add** — detector producing Attention-queue SIGNALS (episode-deduped); takes no action, re-enables nothing.
+- `scope=pool` rate limit — **add** — transport-layer mechanics (anti-amplification), not a judgment decision.
+- `peerUrlGuard` (https/allowlist before Bearer forward) — **add** — hard safety guard on credential egress; refusal is VISIBLE (`url-rejected` failure row), never silent.
+- `GuardPostureTripwire` — **pass-through** — extraction logic moved to the shared module; behavior unchanged (its tests still pass unmodified).
+- Heartbeat ingestion — **modify** — adds a posture block bound to the AUTHENTICATED sender; never a new accept/reject decision.
+
+## 1. Over-block
+
+No block/allow surface on message or agent-behavior flow. Two narrow rejection surfaces exist and are scoped:
+- The peer-URL allowlist can refuse a LEGITIMATE peer URL if an operator uses an unusual tunnel domain → the peer renders as a named `url-rejected` failure row (visible, diagnosable), and the heartbeat path still carries its posture. Mitigation documented; allowlist is a shared helper so a domain fix lands once.
+- The pool rate limit can briefly defer a rapid sweep — partial results semantics, never a 500.
+
+## 2. Under-block
+
+- Posture is self-attested telemetry: a compromised machine can report all-confirmed (spec §3(g) accepted; cross-check = deep read vs heartbeat disagreement, which the probe flags).
+- `on-unverified` covers every non-instrumented guard — a crashed non-instrumented guard is indistinguishable from a healthy one (grey, honestly labeled; instrumentation grows over time; the E2E floor pins sessionReaper + scheduler enrichment so the headline guards can't regress to grey).
+- Staleness detection only applies to guards declaring `expectedTickMs` — an event-driven guard with a dead event loop is not detected (stated scope line, spec §2.2).
+
+## 3. Level-of-abstraction fit
+
+Read surface sits at the route layer over pure derivation modules (`guardPostureView.ts`) — same layering as reap-log/TokenLedger (always-on read-only observability precedent). The extraction lives in ONE shared module consumed by both the tripwire and the endpoint (single-funnel; prevents inventory drift). The probe consumes the same inventory rather than re-deriving. No parallel-to-a-smarter-gate structure exists: nothing here blocks.
+
+## 4. Signal vs authority compliance
+
+**Reference:** docs/signal-vs-authority.md
+
+- [x] No — this change produces signals (posture rows, probe Attention items) consumed by humans/agents; it holds no blocking authority over any flow.
+
+The two block-shaped pieces fall in the doc's exempt classes: the rate limit is transport-layer mechanics ("idempotency/transport" class), and the peer-URL allowlist is a hard safety guard on credential egress ("safety guards on irreversible actions" class — sending a Bearer token to a hostile URL is irreversible) whose refusals are visible rows. The spec's §2.5 de-scope keeps the WRITE lever (real authority) out of this change entirely.
+
+## 5. Interactions
+
+- **Tripwire:** shares the extractor; tripwire behavior unchanged (tests pass unmodified). The endpoint READS the tripwire's boot snapshot (`state/guard-posture.json`) but never writes it — no write race (tripwire writes once at boot).
+- **Heartbeat:** posture block is additive on `MachineCapacity`; older peers ignore unknown fields (verified shape is additive). Ingestion binds to authenticated sender identity — cannot shadow another machine's row (the merge-identity rule both fan-out and heartbeat already follow).
+- **Attention queue:** probe emits through the existing budgeted funnel with a stable `healthKey` (episode dedup) — aggregated single item, P17-compliant; cannot topic-flood (the breaker is upstream of every attention emit).
+- **Double-fire with tripwire:** tripwire alarms on boot TRANSITIONS; probe alarms on persisting STEADY-STATE anomalies. Distinct triggers, complementary by design (spec §2.6); both reference the same inventory so they can't disagree about what a guard is.
+- **No shadowing:** `/guards` adds no middleware ahead of existing checks; Bearer middleware unchanged.
+
+## 6. External surfaces
+
+- New authenticated API surface (`GET /guards`) — operationally sensitive (attack-timing oracle); contained per spec §3: Bearer-only, never on exemption lists, never on /health//ping/signed-URL surfaces; pool fan-out forwards the token ONLY to https/allowlisted peer URLs. The `scope=pool` rate limit answers 429 when exceeded (transport mechanics); per-guard getter errors surface in-process messages only (never peer/TLS internals — those are enum-normalized in failure rows).
+- Heartbeat payload grows by a few hundred bytes (bounded by manifest size); replicated to operator-paired machines only — accepted, contained exposure (spec §3(f)). The sender computes the block per 30s beat (one disk config read + in-memory inventory build, try/caught; a failed compute omits the block for that beat).
+- TWO new durable machine-local state files (both registered in the State-Coherence Registry + annotated at their write sites, per second-pass review): `state/guard-posture-peers.json` (GuardPostureStore — durable last-known peer posture with receiver-side receipt time) and `state/guard-posture-episodes.json` (GuardPostureProbe episode state). The pre-existing tripwire snapshot `state/guard-posture.json` was registered alongside. The `guardPosture`/`guardPostureReceivedAt` fields are additive on the in-memory/API `MachineCapacity` view only — older readers ignore them.
+- CLAUDE.md template grows a Guards block; existing agents receive it via content-sniffed `migrateClaudeMd()` (Migration Parity); includes the PATCH /config full-block warning (interim hazard containment for the de-scoped write lever).
+- Dashboard Machines tab shows posture summary + age.
+
+## 7. Rollback cost
+
+Pure code change at the route/probe/dashboard layer: revert and ship a patch. Heartbeat block is additive — peers on the old version ignore it; durable record fields are ignored by old readers (no data migration needed either way). The CLAUDE.md template section requires a removal migration if rolled back (stated in spec §7 — Migration Parity cuts both ways). No agent state repair.
+
+## Conclusion
+
+The build implements a read-only observability surface whose design center is honesty layering (config-on ≠ working). The review confirms: no brittle logic holds blocking authority; both rejection surfaces are exempt-class with visible refusals; the heaviest risks are information-disclosure-shaped and carry shipping-dependency mitigations (projection allowlist + leak tests, URL allowlist before token forward, sender-bound ingestion). Clear to ship once all three test tiers are green and the second-pass reviewer concurs.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent (adversarial audit, 2026-06-12)
+**Independent read of the artifact: concern raised → resolved → concur**
+
+Initial verdict raised three concerns, all resolved before ship:
+- *Unregistered durable state files* — `state/guard-posture-peers.json` and `state/guard-posture-episodes.json` were not in the State-Coherence Registry (the lint's documented variable-path blind spot). RESOLVED: both registered + inline `/* state-registry: ... */` annotations at the write sites; the pre-existing tripwire snapshot registered alongside.
+- *§6 wording misdescribed durability* (claimed durable-machine-record fields; actually a separate store file). RESOLVED: §6 corrected to name both files and the in-memory-only capacity fields.
+- *`deepReadPeer` implemented but unwired* (a silent scope reduction). RESOLVED: wired in server.ts — plain `GET /guards` against the peer, token only past the peerUrlGuard, online-peers-with-stale/missing-posture only.
+
+Reviewer affirmation on the core questions: "No brittle logic holds blocking authority over message flow, session lifecycle, or dispatch — the only two rejection surfaces are exactly the exempt classes the artifact claims. All §3 shipping dependencies are genuinely implemented AND tested, not just claimed. Once the state-registry registration and the §6 wording fix land, I concur with shipping." Both landed; concurrence stands.
+
+## Verification phase (LARGE build, 5 independent reviewers)
+
+- **Spec-correctness**: all 8 acceptance criteria VERIFIED with code+test locations; precedence table matches §2.2 exactly. No findings.
+- **Security**: IPv6 private ranges were over-blocked (safe direction) — now granted LAN trust (loopback/ULA/link-local) with boundary tests; redirect-safety rationale documented (Fetch strips Authorization cross-origin — deliberate). All ten threat-model rows verified implemented+tested.
+- **Scalability**: REAL BUG fixed — store write-on-change compared `generatedAt` (always fresh → wrote every beat); now field-wise semantic comparison. Heartbeat posture compute now mtime-caches the resolved-config snapshot (was 2× structuredClone per 30s beat). 90-day TTL bounds the durable store; deep merge depth-capped at 64.
+- **Test-quality**: added getter-invocation wiring spy, route-level one-read pin, async-getter-structurally-unusable pin (the sync-enforcement mechanism behind <100ms), staleness boundary at exactly 5×, dryRun override precedence, snapshot-unavailable+runtime-divergent combination.
+- **Integration/regression**: no blockers; single-machine no-op verified; boot-order/TDZ verified safe. Fixes: first-failure logging for the heartbeat posture compute, explicit pool-not-wired return in deepReadPeer, defensive dashboard math on partial posture blocks.
+
+## Evidence pointers
+
+- `.instar/state/build/must-haves.md` (truths T1–T18), `threats.md` (STRIDE T-01…T-10), `plan.md`
+- Tier-1: `tests/unit/monitoring/guard-posture-view.test.ts`, `guard-posture-snapshot.test.ts` (48+10 green at step 2)
+- Spec: `docs/specs/GUARD-POSTURE-ENDPOINT-SPEC.md` (approved 2026-06-12, topic 13481)
+
+## Addendum — agent-awareness migration collision fix
+
+The pool-sessions-visibility CLAUDE.md migration's idempotency sniff was the bare string `scope=pool`; the new Guards section (which mentions `/guards?scope=pool`) would have permanently satisfied it, silently blocking that migration for any agent carrying the Guards block. Tightened to the route-qualified `sessions?scope=pool` with its test updated — found by the awareness-block test pass.
+
+## Addendum — CI lint + ratchet compliance
+
+`scripts/lint-guard-manifest.js` (+ unit test) wired into the composite lint chain; complete NOT_A_GUARD backfill (33 entries; one real finding: WorktreeReaper has no importer — dormant code, tracked). PrincipalGuard's reason reworded to dodge an llm-attribution-ratchet scanner false positive; the four new guard-path catch blocks carry @silent-fallback-ok justifications (no-silent-fallbacks ratchet stays at baseline).