instar 1.3.1321 → 1.3.1322

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-10-06T19:27:33.914Z",
-  "instarVersion": "1.3.1321",
+  "generatedAt": "2026-10-07T02:21:47.208Z",
+  "instarVersion": "1.3.1322",
   "entryCount": 203,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:telegram-origin-guard": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -119,7 +119,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -137,7 +137,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -155,7 +155,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1571,7 +1571,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "1944edf03d572006dca750f8d935cbbfb6982b0527ae7f112abfcd3f94dedda6",
+      "contentHash": "5df4ce7d6ceed28d82a6b096cd952d263178ed7246ff03e9d371928a0060b4b0",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "35448db940d659661ebdfb09761439033f93a15157540ee2f6eecf825488e1e6",
-  "packageVersion": "1.3.1321",
+  "packageVersion": "1.3.1322",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "b1e3523bdc4928248eefaadbf30c38b85fa6bdc0bce7dd8c04f19e2e20a24fc3",
+  "sha256": "88254d7c0e3148acfb13b7fd93df3e8229c19f4d4d74591749e814eb5fdd2df9",
   "registrySha256": "35448db940d659661ebdfb09761439033f93a15157540ee2f6eecf825488e1e6",
-  "packageVersion": "1.3.1321"
+  "packageVersion": "1.3.1322"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "35448db940d659661ebdfb09761439033f93a15157540ee2f6eecf825488e1e6",
   "articleCount": 92,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1321"
+  "packageVersion": "1.3.1322"
 }

package/src/scaffold/templates.ts

@@ -2002,6 +2002,10 @@ Agent-to-agent delivery is tracked durably so a message can't silently die out.
 - One peer: \`curl http://localhost:${port}/threadline/peers/<fingerprint>/health\`
 - \`stale: true\` (or a non-zero \`staleCount\`) means a message has been awaiting acknowledgement past the threshold — the peer may be dark or unreachable; check the relay and the peer's address before assuming they're ignoring me. **Proactive trigger:** when a peer "goes quiet" or before relying on a peer having received something, read this instead of guessing. Read-only — never gates a send.
 
+### Is my own relay connection up? (displaced vs retrying)
+
+Before blaming a quiet peer, check MY side: \`curl http://localhost:${port}/threadline/health\` → \`relay.state\`. \`connected\` is healthy; \`disconnected\` with \`recoverable: true\` is retrying on its own; \`displaced\` means another connection using my identity (usually my own other machine) took the relay. A displaced machine raises a \`Threadline.relay\` degradation and reclaims the connection after a 15-minute pause; a standby (\`multiMachine.telegramPolling: false\`) never connects at all. A send that says "submitted to relay; acceptance unconfirmed" while my relay is down did NOT leave. **Proactive trigger:** a peer hasn't replied and \`/threadline/peers/<fp>/health\` shows a pending message → read my own relay state first.
+
 ### Threadline Single-Negotiator Lock (one voice per conversation)
 
 Threadline has a per-conversation **negotiator lease**: at most ONE of my sessions owns a conversation's outbound voice at a time. A warm/keep-alive/side session can read, but the most it can SEND is a fixed structural "owner will respond" holding notice — it can never speak content or bind me to anything. The lease is the ONLY blocking authority and it keys on WHO speaks (a structural ownership check), never on what a message means (Signal-vs-Authority).

package/upgrades/1.3.1322.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a second connection using the same identity (usually the agent's own other machine) joined the Threadline relay, the first connection was displaced and stopped retrying for the life of the process. The relay's follow-up 4001 close then emitted a plain `disconnected`, so `/threadline/health` reported `disconnected, recoverable: true` for an agent that would never reconnect. Luna's (sagemind) laptop sat in that state for 40 hours on 2026-10-05/06, unreachable by every peer.
+
+- `RelayClient`: a `displaced` frame now sets the state to `disconnected` at once, so the 4001 close no longer emits a masking `disconnected`. An `auth_error` frame now closes the socket, so the close handler schedules the retry instead of waiting on an open unauthenticated socket.
+- `relayConnectionObserver`: a terminal `displaced` is no longer overwritten by a later plain disconnect; a successful `connected` clears it.
+- `ThreadlineBootstrap`: on displacement the server reports a `Threadline.relay` degradation and, after `relayRearmAfterDisplacedMs` (default 15 min, 0 disables), reclaims the connection. Only the configured relay owner holds a relay client (a standby never connects), so reclaiming is the correct outcome. A failed first connect no longer drops the client: it keeps retrying with backoff instead of leaving the agent local-only until restart.
+- `ThreadlineClient.reconnectRelay()` re-arms the existing relay client with its listeners intact.
+- CLAUDE.md template + migration: "Is my own relay connection up? (displaced vs retrying)".
+
+## What to Tell Your User
+
+If another copy of me on one of your machines briefly takes my connection to other agents, I now say so and take it back on my own after a short pause, instead of going silent to other agents until someone restarts me.
+
+## Summary of New Capabilities
+
+- Displaced relay connections are reported as a degradation and reclaimed after a pause.
+- `/threadline/health` reports `displaced` (not "recoverable") when that is the true state.
+
+## Evidence
+
+- `tests/e2e/threadline/RelayE2E.test.ts`: against a real relay, a displaced client reports `disconnected` at once and emits no follow-up plain disconnect, and `connect()` reclaims the connection (both fail without the fix).
+- `tests/e2e/threadline/relay-displacement-reclaim.test.ts`: the production bootstrap path is displaced, reports the degradation, then reclaims the relay and the intruder is displaced in turn.
+- `tests/unit/relay-connection-observer.test.ts`: a plain disconnect after a displacement does not mask it; a reconnect clears it.

package/upgrades/relay-displaced-reclaim.eli16.md

@@ -0,0 +1,12 @@
+# A machine bumped off the agent relay takes it back (ELI16)
+
+Agents talk to each other through a shared relay, and the relay allows one connection per agent identity. When a second connection with the same identity arrives, the first one is kicked off ("displaced").
+
+Before this change, a displaced connection gave up for good, and its health report still said it would recover. That is what happened to Luna: her Studio briefly connected with her identity, her laptop was kicked off, and for 40 hours no agent could reach her, with nothing raising an alarm.
+
+Now:
+- The health report says "displaced" honestly instead of "will recover".
+- The server raises a degradation alert, so the problem shows up.
+- After a 15-minute pause, the machine takes its connection back. Only the machine that is supposed to own the relay ever holds a connection (a standby never connects), so taking it back is the right outcome. The pause keeps two misconfigured machines from fighting over it every few seconds.
+- Two other ways a connection could stall forever are closed: a rejected login that left the socket hanging, and a failed first connection that the server stopped tracking.
+- Agents learn, through their instructions, to check their own relay before assuming a quiet peer is ignoring them.

package/upgrades/side-effects/relay-displaced-reclaim.md

@@ -0,0 +1,24 @@
+# Side-effects review: relay-displaced-reclaim
+
+## Change
+RelayClient displaced/auth_error state handling; observer keeps terminal events; ThreadlineBootstrap reports a degradation on displacement and reclaims the relay after a pause (default 15 min); a failed first connect keeps the client retrying; ThreadlineClient.reconnectRelay(); CLAUDE.md template + idempotent migration section.
+
+## Over-block / under-block
+No gate added. The reclaim can only reconnect a machine that already held a relay client, i.e. a configured relay owner (relayEnabled and not relayStandby, and no listener daemon owning the relay).
+
+## Self-action bound
+Reclaim is a self-triggered reconnect. Bounded: at most one pending timer per process, one reclaim per displacement, minimum spacing of the configured pause (15 min default). If two machines are both misconfigured as owners they trade the connection at most once per pause each, and every displacement raises a degradation, so the misconfiguration is visible rather than silent. `relayRearmAfterDisplacedMs: 0` restores the pre-fix behaviour.
+
+## Interactions
+- Standby (`relayStandby`) machines never create a relay client, so they never reclaim (unchanged, instar#2122).
+- Listener-daemon mode: the server does not hold the relay client, so no reclaim (unchanged).
+- Keeping the client after a failed first connect: routes that check `relayClient` now see a client in `disconnected` state instead of undefined; sends while disconnected fail visibly as before, and the client reconnects when the relay returns.
+
+## Signal vs authority
+The degradation report is a signal only. The reclaim reconnects this agent's own connection; it takes no action on peers.
+
+## External surfaces
+`/threadline/health` relay.state reports `displaced` accurately. Agent CLAUDE.md gains one section (template + migration, content-sniffed).
+
+## Rollback
+Revert the commit, or set `relayRearmAfterDisplacedMs: 0` to disable the reclaim only.