instar 1.3.698 → 1.3.699

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.698",
+  "version": "1.3.699",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-29T23:38:11.629Z",
-  "instarVersion": "1.3.698",
+  "generatedAt": "2026-06-30T05:38:13.079Z",
+  "instarVersion": "1.3.699",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "6d5ddf97c62bce603a06d75a9197e708882fb6dc6925aaec14c855185a84d96a",
+      "contentHash": "0cc2eb0170501a43c818c88863303c7cb20fd905a0cddc0ec57352138c3b004c",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1530,7 +1530,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "32ae3f7ec0dd6a95725dcc3f2773327fddba815d408743914f3b65e11ce80899",
+      "contentHash": "c55b920cb89980f73d9226b5770c63a94170e9fca13c81a501a2664d73c6bd96",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/upgrades/1.3.699.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Closes the cross-machine "stuck move" bug: a conversation pinned to one machine while another still owned it never converged. Three root causes are fixed:
+
+1. **Clock-skew quarantine false-positive** — the pool-refresh fed the coarse, git-synced file heartbeat's timestamp into the live 5-minute clock-skew check, permanently quarantining a peer whose clock was actually fine. A `coarseHeartbeat` flag now makes coarse beats refresh liveness without ever driving the skew FSM.
+2. **The pin (move-instruction) never reached the owning machine** — it was written only on the lease-holder. A new `topic-pin-record` replicated-record kind (on the existing WS2 replicated-record rails: HLC ordering, tombstone-on-clear, quarantine) replicates the pin; the owning machine's reconciler reads it as an HLC-ordered, validated (known + online target) advisory move-intent and starts the cooperative transfer.
+3. **The `transferring` handoff signal never replicated** — `PlacementData` is extended with `status`/`transferTo`/`timestamp`/`drainInFlight`, threaded at the shared `emitPlacement` helper, and `OwnershipApplier` now materializes the transferring state (validated `transferTo`→downgrade, epoch-fenced, timestamp-clamped) so the target machine claims and the handoff completes.
+
+Also: a stuck-transferring `abort-transfer` recovery (a dead-target handoff self-heals back to active instead of freezing), a read-only `GET /pool/reconciler` observability route, and the testing-integrity root fix — the reconciler test harness is rebuilt so every test runs separate-per-machine stores joined only by a journal pump (the shared-store harness had masked this bug class for months).
+
+Ships dark behind `multiMachine.seamlessness.ws13Reconcile` / `ws13DryRun` and an independent `ws13PinReplicate` sub-flag (dev-agent live, fleet dark). A single-machine agent is a strict no-op.
+
+## What to Tell Your User
+
+Nothing yet — this ships **off by default** (infrastructure, fleet-dark). When it is enabled, moving a conversation between your machines will reliably converge instead of silently getting stuck, and a move that can't complete will surface honestly ("still moving / couldn't move") rather than freezing. There is no change to how things work today until it is deliberately turned on.
+
+## Summary of New Capabilities
+
+- (Dark) Reliable cross-machine conversation moves: the owning machine learns it is pinned away and completes the hand-off, with skew-proof ordering, validated targets, and self-healing recovery.
+- `GET /pool/reconciler` — read-only observability for the cross-machine reconciler (last-tick status + per-topic decision explanation).
+
+## Evidence
+
+- Spec converged through 3 review rounds (8 internal reviewers + codex/gemini external each round, ~24 findings folded): `docs/specs/cross-machine-reconciler-convergence.md` (`review-convergence` + `approved: true`); report at `docs/specs/reports/cross-machine-reconciler-convergence-convergence.md`.
+- Unit: full suite `npx vitest run tests/unit` exits 0. New/changed unit coverage: `MachinePoolRegistry.test.ts` (coarse-heartbeat skew abstention, both sides), `OwnershipApplier.test.ts` (transferring materialization, transferTo downgrade, epoch fence, timestamp clamp, owner-anchored tie-break), `OwnershipReconciler.test.ts` (rebuilt to the real two-machine topology + advisory-pin precedence/N3/offline-target + abort-transfer recovery), `TopicPinReplicatedStore.test.ts` (HLC merge, tombstone, malformed-reject).
+- Integration: `tests/integration/topic-pin-replication.test.ts` (pin round-trips the real CoherenceJournal: emit→validate→append→read→merge; tombstone; re-pin HLC; malformed-reject; op-key dedupe) + `tests/integration/pool-reconciler-route.test.ts` (401 / 503-when-dark / 200-status / 200-topic-explain).

package/upgrades/side-effects/cross-machine-reconciler-convergence.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — Cross-Machine Ownership-Reconciler Convergence
+
+**Version / slug:** `cross-machine-reconciler-convergence`
+**Date:** 2026-06-30
+**Author:** echo (autonomous pre-approved run, topic 28744)
+**Second-pass reviewer:** echo second-pass subagent (high-risk: ownership/routing decision surface)
+
+## Summary of the change
+
+Closes the cross-machine "stuck move" bug: a conversation pinned to machine T while machine S still owns it never converged. Three root causes, all live-verified Laptop↔Mini: (1) a false-positive **clock-skew quarantine** — `refreshPool()` fed the coarse git-synced file heartbeat's timestamp into the live 5-min clock-skew FSM, permanently quarantining the peer (fix: a `coarseHeartbeat` flag so coarse beats refresh liveness but never drive the skew FSM); (2) the **pin (move-intent) never replicated** to the owning machine (fix: a new `topic-pin-record` replicated-record kind on the WS2 rails + `TopicPinReplicatedStore` advisory consumer + reconciler HLC-precedence between local and advisory pins, validated known+online); (3) the **`transferring` handoff signal never replicated** (fix: extend `PlacementData` with `status`/`transferTo`/`timestamp`/`drainInFlight`, thread it at the shared `emitPlacement` helper, and have `OwnershipApplier` materialize the transferring state — validated `transferTo`, epoch-fenced, timestamp-clamped — so the target machine claims). Plus a stuck-transferring `abort-transfer` recovery case, the `/pool/reconciler` observability route, and the **testing-integrity root fix**: `makeSim` rebuilt so every reconciler test runs separate-per-machine stores joined only by a journal pump (the shared-store harness masked this bug for months). Files: `MachinePoolRegistry.ts`, `CoherenceJournal.ts`, `OwnershipApplier.ts`/`ownershipApplierWiring.ts`, `OwnershipReconciler.ts`, `TopicPlacementPinStore.ts`, new `TopicPinReplicatedStore.ts`, `server.ts`, `routes.ts`, `AgentServer.ts`, tests. Decision points touched: the WS1.3 OwnershipReconciler (ownership transfer/claim/abort), the OwnershipApplier (cross-machine ownership materialization), the clock-skew quarantine FSM.
+
+## Decision-point inventory
+
+- `OwnershipReconciler.tick()` (ownership transfer/claim/force-claim/abort) — **modify** — now reads an effective pin (local + HLC-ordered advisory) + a new abort-transfer recovery case; still epoch-fenced + death-evidence-gated, never a brittle timer steal.
+- `OwnershipApplier.tick()` (materializes replicated ownership) — **modify** — now materializes `transferring` (validated `transferTo`→downgrade, epoch-fenced, timestamp-clamped), not only `active`.
+- `MachinePoolRegistry.recordHeartbeat()` clock-skew FSM — **modify** — a `coarseHeartbeat` beat no longer drives the FSM (abstains; liveness only).
+- `topic-pin-record` replicated kind + `TopicPinReplicatedStore` — **add** — advisory move-intent replication (HLC, tombstone, quarantine via the WS2 envelope).
+- `GET /pool/reconciler` — **add** — read-only observability (status + per-topic explain); 503 when absent.
+
+## 1. Over-block
+
+No block/allow message surface. The closest "reject" behaviors are protective and tightly scoped: a replicated `transferring` whose `transferTo` is unknown/offline/==owner is DOWNGRADED to `active(owner)` (never materialized as un-claimable) — it does not reject a legitimate handoff, it falls back to the safe state; an advisory pin toward an offline/unknown machine is ignored (the move waits, never misroutes). A legitimate handoff to a known+online machine is never downgraded. Over-rejection risk: a brief window where a just-joined machine isn't yet in `machines()` could make a valid advisory pin/transferTo read as "unknown" → the move waits one tick until membership populates (self-healing, not a permanent block).
+
+## 2. Under-block
+
+A genuinely STALE peer stream is the in-scope adversary (single-agent model — no hostile tenant). Residual misses, all bounded: a corrupt future-dated `timestamp` is clamped (can't defeat the deadline); a corrupt huge epoch is fenced; a stale pin is HLC-ordered out by a fresher one AND requires an online target. What it does NOT yet cover (documented follow-ups, tracked): `pendingReplacement` honest-pending surfacing for a not-yet-converged advisory move, and an explicit tombstone-on-clear emit from `/pool/transfer` (today a clear relies on a re-pin's higher HLC). These are additive surfacing/cleanup, not correctness holes — convergence still completes; the gap is only the "still moving" UX cue and faster clear propagation. <!-- tracked: CMT-1829 -->
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The fixes sit exactly where the decisions already live: the clock-skew abstention is in the registry that owns the FSM; the pin replication rides the EXISTING WS2 replicated-record machinery (HLC envelope, tombstone, quarantine, retention) rather than a new bespoke transport (Round-1 review explicitly rejected a wall-clock `topic-pin` kind); the transferring replication extends the EXISTING placement journal + applier rather than a parallel path. The reconciler consumes signals (advisory pins, machine liveness) and acts within the existing FSM/CAS authority — it does not add a new authority.
+
+## 4. Signal vs authority compliance
+
+Compliant. A replicated pin is a **signal** (advisory move-intent). The reconciler's effective-pin merge IS read by every branch (including force-claim Case C when the pin names self), but the force-claim DECISION is gated on death-evidence + quorum derived from machine LIVENESS (`machines()`), never on the advisory pin — a stale/corrupt pin cannot manufacture death evidence, so it can never cause a LIVE-owner seat-steal. The only thing an advisory pin can trigger is the owner's OWN cooperative transfer (owner-gated FSM action). The clock-skew change REMOVES a brittle authority (a coarse file timestamp was wrongly gating placement eligibility). `/pool/reconciler` is observe-only. No brittle check gains blocking authority.
+
+## 5. Interactions
+
+The transferring extension threads through the SHARED `emitPlacement` helper so every CAS site (reconciler, drain runner, user-move) emits coherently — avoids the "only the reconciler path threads it" shadow. The applier's owner-anchored equal-epoch tie-break prevents a forged peer `active(e)` from shadowing the true owner's `transferring(e)`. The advisory pin is unioned with the local pin (HLC precedence) so a stale local self-pin can't shadow a fresher replicated intent (the N3 recurrence). No double-fire: the journal op-key dedupes a same-(recordKey,hlc) retry. The abort-transfer is owner-only (FSM-gated), so two machines can't both abort.
+
+## 6. External surfaces
+
+New: `GET /pool/reconciler` (Bearer-gated, credential-free — topic ids/machine ids/epochs/decision reasons only). New journal kind `topic-pin-record` (additive — older peers ignore unknown kinds; the feature converges only when BOTH machines are new, a degrade to the pre-fix stuck-move, never a regression). New config flag `multiMachine.seamlessness.ws13PinReplicate` (dev-live/fleet-dark). The cross-machine convergence latency is eventually-consistent (~45–90s) — surfaced honestly. Timing/runtime dependence: convergence depends on the journal replicating (best-effort HTTP pull) — a lost pin record delays (never corrupts) a move; the reconciler retries each tick.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+This change IS the multi-machine feature. Posture per surface: `topic-pin-record` = **replicated** (WS2 rails, HLC; advisory-on-receive, local pin write stays router-authenticated); `topic-placement` status/transferTo = **replicated** (existing placement journal + applier); `TopicPinReplicatedStore` = **machine-local view of replicated data**; `/pool/reconciler` = **proxied-on-read** via the standby (503 when dark); reconciler tick / appliers = **machine-local BY DESIGN** (each reconciles its own view; the journal is the shared arbiter). No single-machine assumption — a single-machine agent is a strict no-op (no peers → no advisory pins, the reconciler `machines()<2` no-ops). User-facing: a non-converging move surfaces via the reconciler explain + (follow-up) pendingReplacement — no silent stuck state.
+
+## 8. Rollback cost
+
+Cheap and layered. Everything ships dark behind `ws13Reconcile`/`ws13DryRun` (dev-live/fleet-dark) + `ws13PinReplicate` (independent sub-flag for the pin-replicator). Back-out paths, in order: set `ws13PinReplicate` off (stops pin emission — the topic-pin store entry is absent → the emitter no-ops); set `ws13DryRun` true (reconciler logs but lands no CAS); set `ws13Reconcile` off (reconciler strict no-op). No data migration needed — the new `topic-pin-record` stream is additive and self-prunes (retention rotateKeep:4); the `TopicPin.hlc` field is optional (absent ⇒ derived-from-updatedAt fallback). No agent-state repair. A bad release is a config flip, not a hot-fix.
+
+---
+
+## Second-pass reviewer response
+
+**Concur with the review.** An independent reviewer verified every load-bearing safety claim against the code: (1) signal-vs-authority — a replicated pin can only yield a `preferredMachine` the owner transfers TOWARD; Case A fires only when `owner === self` (the owner releasing its own topic), and the force-claim Case C is gated independently on death-evidence + quorum from `machines()` liveness, so a stale/corrupt pin cannot manufacture a live-owner steal (confirmed OwnershipReconciler.ts effectivePins + Case A/C); (2) the applier's `transferTo` validation→downgrade, epoch fence, and timestamp clamp match the code exactly; (3) the coarse-heartbeat abstention genuinely never drives the skew FSM while still refreshing liveness; (4) the threading + route + multi-machine posture + rollback all check out. The one concern raised was a §4 phrasing imprecision ("never reads the advisory store") — corrected above to credit the death-evidence+quorum gate (the actual safety mechanism) rather than overstating store isolation. Not a correctness or safety defect; the code's behavior was already safe.