instar 1.3.163 → 1.3.165

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.163",
+  "version": "1.3.165",
   "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-05-31T11:14:56.836Z",
-  "instarVersion": "1.3.163",
+  "generatedAt": "2026-05-31T11:39:31.391Z",
+  "instarVersion": "1.3.165",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.164.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What to Tell Your User
+
+If you run your agent on more than one machine and move a conversation between them, the
+move now actually sticks — the receiving machine is confirmed as the new owner and your
+following messages route to it, instead of the move quietly failing. This only applies
+when the multi-machine session pool is on; single-machine agents are unaffected. Nothing
+to configure. (Two related pieces are still in progress: ownership surviving a restart,
+and the moved conversation being able to reply — tracked separately.)
+
+## Summary of New Capabilities
+
+- `SessionRouter` gains an optional `confirmClaim(sessionKey, machineId)` dep, invoked
+  after a successful remote `spawnOnMachine`, advancing the ownership record
+  `placing → active`. Self-placement (router keeps it) does not confirm.
+- Wired in the server to the ownership-registry `claim` CAS.
+
+## Evidence
+
+- Found live on 2026-05-31: after a move, every later message logged
+  "route … action=queued owner=?" and was handled back on the origin — the ownership
+  state machine requires place→claim→active and the claim was never issued, so the
+  record stayed "placing".
+- Unit, `tests/unit/SessionRouter.test.ts`: a remote placement now confirms the owner
+  (placing→active); a self-placement does not.
+- Unit, `tests/unit/SessionOwnership.test.ts`: the place→claim→active transition.
+- 47 SessionRouter + ownership + wiring tests pass; tsc --noEmit clean.
+- Spec, `docs/specs/router-confirm-claim-on-place.md` plus the .eli16.md sibling.
+- Side-effects, `upgrades/side-effects/router-confirm-claim-on-place.md`.
+
+## What Changed — a moved conversation now finishes its handoff instead of getting stuck
+
+Another step toward the multi-machine "move this conversation to my other machine"
+feature. The handoff tracks ownership in two steps: the router assigns the conversation
+to the target machine (status "placing"), then the new owner is confirmed (status
+"active"). The confirm step was never being issued, so a moved conversation stayed in
+"placing" limbo forever — and the router's rule of "hold messages while a handoff is in
+progress" then held every later message, so the move silently failed.
+
+This release has the router issue the confirm right after it hands the conversation to
+the target machine, advancing ownership to "active". From then on the router correctly
+forwards your messages to the new owner. The state machine only allows confirming the
+exact machine the conversation was just assigned to, so this stays safe.

package/upgrades/1.3.165.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What to Tell Your User
+
+If you run your agent across more than one machine and move a conversation to another
+one, that conversation can now reply to you — its replies are relayed through the
+machine that owns your messaging bot, so you hear back without any risk of the two
+machines clashing over the bot. Only relevant when the multi-machine session pool is
+on; single-machine agents are unaffected. Nothing to configure.
+
+## Summary of New Capabilities
+
+- `TelegramAdapter` gains an `outboundRelay` hook. When the adapter has no bot token,
+  `sendToTopic` routes the send through it (the server wires it to POST the
+  Telegram-owning lease holder's `/telegram/reply`), instead of failing silently. A
+  token-holding adapter sends directly as before; a relay that can't deliver throws
+  rather than dropping the message.
+
+## Evidence
+
+- Found live: the backup machine's Telegram adapter had no bot token, so a moved
+  session's reply was sent with no token and silently vanished.
+- Unit, `tests/unit/TelegramAdapter.test.ts`: a tokenless adapter routes the send
+  through the relay (the Telegram API is not hit, the relayed id is returned); a
+  token-holding adapter sends directly and never consults the relay; a relay that
+  returns nothing throws instead of silently dropping the reply.
+- 19 TelegramAdapter tests pass; tsc --noEmit clean.
+- Spec, `docs/specs/standby-telegram-outbound-relay.md` plus the .eli16.md sibling.
+- Side-effects, `upgrades/side-effects/standby-telegram-outbound-relay.md`.
+
+## What Changed — a conversation moved to your other machine can now reply to you
+
+The final piece of the multi-machine "move this conversation to my other machine"
+feature. Telegram only allows one program to use a given bot at a time, so in a
+two-machine setup only the main machine holds the bot, and the backup deliberately
+holds none (to avoid two programs fighting over the same bot — a real failure we fixed
+earlier). That meant a conversation moved to the backup machine could run there but
+couldn't actually send a reply — it came out silent.
+
+This release adds a relay: when the backup machine wants to reply but has no bot, it
+hands the message to the machine that does hold the bot, which sends it normally. So
+your reply comes through, and there's still only ever one program using the bot — no
+fighting, no duplicate messages. A machine that holds its own bot is completely
+unaffected.

package/upgrades/side-effects/router-confirm-claim-on-place.md

@@ -0,0 +1,96 @@
+# Side-Effects Review — Router confirms remote placement (bug #11)
+
+**Version / slug:** `router-confirm-claim-on-place`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`SessionRouter` gains an optional `confirmClaim(sessionKey, machineId)` dep, called in
+`placeAndClaim` right after a successful `spawnOnMachine` on a REMOTE target. `server.ts`
+wires it to `ownReg.cas({ type: 'claim', machineId }, …)`, advancing the ownership
+record `placing → active`. Without it the record stayed `placing` and every later
+message for the session queued (bug #11).
+
+## Decision-point inventory
+
+- **remote branch only** — `confirmClaim` is called only in `placeAndClaim`'s
+  remote-spawn path (after `spawnOnMachine`). Self-placement returns handled-locally
+  and never confirms. Both covered by tests.
+- **FSM gate** — `claim` is permitted only when the record's `ownerMachineId` equals the
+  claimed `machineId` (the placed owner). Covered in `SessionOwnership.test.ts`.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** Nothing. It only ADDS a confirm after a
+remote placement. Self-placement, forwarding to an existing owner, owner-dead
+re-placement, and queue paths are unchanged. A `confirmClaim` that fails (e.g. CAS
+contention) is best-effort and leaves the placement to recover via the normal fences.
+
+## 2. Under-block
+
+**What does this still miss?** It does not make ownership durable across restarts (the
+store is per-machine in-memory — the shared Track-H store is separate). It confirms
+optimistically once the spawn is DISPATCHED (the deliverMessage/spawn RPC resolved); if
+the target's session later dies, the existing owner-dead detection re-places it. It does
+not address bug #7 (standby outbound mute).
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The confirm lives in `SessionRouter.placeAndClaim` — the exact
+place that owns the place→spawn lifecycle and already does the `place` CAS. The dep is
+injected (testable, same pattern as `casClaimOwnership`/`spawnOnMachine`). The FSM
+transition itself stays in `SessionOwnership.ts`.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+This advances an ownership record through its designed FSM (`place → claim`), gated by
+the FSM's own legal-transition check (claim machineId must equal the placed owner). It
+adds no user-facing authority and blocks nothing. It RELAXES nothing about who may own a
+session — it completes a transition that was already supposed to happen.
+
+## 5. Interactions
+
+Consumes the existing `ownReg` CAS (the same registry `place`/`transfer`/`release` use).
+Pairs with `placeAndClaim`'s `place` CAS (the two halves of a new-session handoff). After
+the confirm, `dispatchOne` sees `active` (not `placing`) and forwards subsequent messages
+to the owner instead of queueing. Idempotent at the FSM level (a duplicate claim on an
+already-active record is rejected `claim-out-of-sequence`, harmless). No interaction with
+the lease or the shared-state read-only guard.
+
+## 6. External surfaces
+
+None. No HTTP routes, config, or notifications. The visible effect is a moved session's
+ownership reaching `active` (so `/pool` + routing reflect the new owner).
+
+## 7. Rollback cost
+
+Low. Remove the `confirmClaim` dep + call + wiring; transfers revert to stuck-`placing`
+(bug #11). No schema, no persisted state, no migration (the dep is optional + in-memory).
+
+## Conclusion
+
+Minimal, FSM-gated completion of a handoff transition that was missing, scoped to the
+remote-placement branch, both branches + the FSM transition unit-tested, no new
+authority, no external surface, cheap revert. Makes the live single-router transfer's
+ownership finalize instead of sticking. Durable cross-machine ownership (Track-H) and
+the reply relay (#7) remain separate.
+
+## Second-pass review (if required)
+
+Not required — completes an existing FSM transition via its own legality gate, remote-
+branch-only, both sides tested, no shared-state authority changed, reversible. The live
+two-machine re-test (fresh topic) is the Tier-3 gate that follows.
+
+## Evidence pointers
+
+- `tests/unit/SessionRouter.test.ts` — remote placement calls `confirmClaim('s1','m_remote')`;
+  self-placement does not.
+- `tests/unit/SessionOwnership.test.ts` — `place(placing) → claim(active)` transition.
+- 47 SessionRouter + ownership + wiring tests green; `tsc --noEmit` clean.
+- Found live: `route … action=queued owner=?` on every post-move message; the ownership
+  FSM requires place→claim→active and the claim was never issued.
+- Spec: `docs/specs/router-confirm-claim-on-place.md` (+ `.eli16.md`).

package/upgrades/side-effects/standby-telegram-outbound-relay.md

@@ -0,0 +1,100 @@
+# Side-Effects Review — Tokenless standby Telegram outbound relay (bug #7)
+
+**Version / slug:** `standby-telegram-outbound-relay`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`TelegramAdapter` gains a settable `outboundRelay` callback. In `sendToTopic`, when
+the adapter has NO bot token AND a relay is wired, the send routes through the relay
+instead of the Telegram API (the relayed id feeds the same log/stall/promise
+bookkeeping); a relay returning null throws. `server.ts` wires the relay to POST the
+lease holder's `/telegram/reply/:topicId` (Bearer authToken + the holder's peer URL),
+refusing to relay to self/unknown. Closes bug #7 (a session moved to a tokenless
+standby was mute).
+
+## Decision-point inventory
+
+- **sendToTopic branch** — `!this.config.token && this.outboundRelay` → relay; else →
+  the unchanged API path. Both covered by tests.
+- **relay closure** — `holder` is self or unknown, or no URL → return null (no
+  relay); else POST and return the id (or null on non-ok / throw). Self-relay guard
+  + null-on-failure tested via the adapter-level null case.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** Nothing for a token-holding machine — its
+send path is byte-identical (the relay branch is skipped). For a tokenless standby, a
+send that previously failed silently (no token) now either relays successfully or
+throws a clear error (better than the silent mute). No legitimate send is dropped.
+
+## 2. Under-block
+
+**What does this still miss?** It does not sync conversation CONTEXT to the moved
+session (audit #2 — the reply may lack prior history). It relays to the current lease
+holder only (correct for the single-Telegram-owner model); if the holder is
+unreachable it returns null → `sendToTopic` throws (surfaced, not silent). It does not
+retry/queue a failed relay (the caller/​session sees the throw); a durable relay queue
+is possible later but out of scope.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The send decision lives in `TelegramAdapter.sendToTopic` (the
+one outbound chokepoint), expressed as an injected callback (same pattern as the
+adapter's other `on*` hooks). The cross-machine resolution (holder → URL → POST) lives
+in `server.ts` where the mesh/coordinator/authToken are already in scope. The relay
+reuses the existing `/telegram/reply` route rather than a new mesh command.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No new blocking authority. It changes HOW a tokenless adapter sends (relay vs direct),
+not WHETHER. It preserves the single-Telegram-owner safety invariant (the standby
+never sends on the bot directly), which is the 409-conflict guard — strengthening, not
+weakening, a safety property.
+
+## 5. Interactions
+
+The relay POSTs the holder's `/telegram/reply` — the same route used for normal
+replies — so the message goes out the one bot the holder owns; no second poller/sender
+(no 409). Pairs with the lease coordinator (`getSyncStatus().leaseHolder` picks the
+target) and peer presence (`peerUrl`). On a token-holding router the callback is wired
+but never invoked. Idempotent per call; a failed relay throws (the session's reply
+attempt errors rather than silently vanishing).
+
+## 6. External surfaces
+
+One cross-machine HTTP POST from a tokenless standby to the holder's existing
+`/telegram/reply` (Bearer-authed). No new route, config, or notification. The visible
+effect: a moved session's replies reach the user (via the holder's bot).
+
+## 7. Rollback cost
+
+Low. Remove the `outboundRelay` callback + the `sendToTopic` branch + the wiring; a
+tokenless standby's sends revert to silent failure (bug #7). No schema, no state, no
+migration (the callback is in-memory, default null).
+
+## Conclusion
+
+Minimal, injected-callback change scoped to the tokenless-send path, reusing the
+existing reply route, preserving the single-owner 409-guard, both branches + the
+null-failure case unit-tested, no change for token-holding machines, cheap revert.
+The completion gate for the live transfer — a moved session can now reply.
+
+## Second-pass review (if required)
+
+Not required — scoped to the no-token send path, reuses a battle-tested route,
+strengthens (not weakens) the single-owner invariant, both branches + failure tested,
+reversible. The live two-machine re-test (a reply landing) is the Tier-3 gate.
+
+## Evidence pointers
+
+- `tests/unit/TelegramAdapter.test.ts` — tokenless adapter relays (API not hit, relayed
+  id returned); token-holding adapter sends directly (relay not consulted); relay→null
+  throws (no silent mute).
+- 19 TelegramAdapter tests green; `tsc --noEmit` clean.
+- Found live: mini telegram adapter `botToken=MISSING` → a moved session's reply muted.
+- Spec: `docs/specs/standby-telegram-outbound-relay.md` (+ `.eli16.md`).