instar 1.3.166 → 1.3.167

package/dist/core/ForwardedTopicContext.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ForwardedTopicContext — build the prior-conversation context block for a session
+ * that has just been MOVED to this machine by the multi-machine session pool (§L4).
+ *
+ * Why this exists (bug #2): when a topic is moved to a standby, the standby spawns the
+ * session locally but its OWN message ledger for that topic is EMPTY (it never polled
+ * the topic) and its TopicMemory has no rows — so `spawnSessionForTopic` builds an
+ * empty context and the moved conversation starts with amnesia. The router (which DID
+ * hold the conversation) is the source of truth; the receiver fetches the recent
+ * history from it and formats it here into the same "Thread History" block the
+ * single-machine JSONL path produces, so the moved session continues the conversation
+ * instead of starting blank.
+ *
+ * Pure + caller-agnostic so it is unit-testable without a live two-machine setup.
+ */
+/** One historical message, matching TelegramAdapter.getTopicHistory()'s shape. */
+export interface ForwardedHistoryMessage {
+    fromUser: boolean;
+    text?: string;
+    senderName?: string;
+    timestamp?: string | number;
+}
+/**
+ * Format fetched router-side history into a Thread History context block, or '' when
+ * there is nothing to inject. Mirrors the single-machine JSONL formatting in
+ * spawnSessionForTopic so a moved session reads identically to a local one.
+ */
+export declare function formatForwardedTopicContext(messages: ForwardedHistoryMessage[] | null | undefined, topicName?: string): string;
+//# sourceMappingURL=ForwardedTopicContext.d.ts.map

package/dist/core/ForwardedTopicContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForwardedTopicContext.d.ts","sourceRoot":"","sources":["../../src/core/ForwardedTopicContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,uBAAuB,EAAE,GAAG,IAAI,GAAG,SAAS,EACtD,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAqBR"}

package/dist/core/ForwardedTopicContext.js

@@ -0,0 +1,46 @@
+/**
+ * ForwardedTopicContext — build the prior-conversation context block for a session
+ * that has just been MOVED to this machine by the multi-machine session pool (§L4).
+ *
+ * Why this exists (bug #2): when a topic is moved to a standby, the standby spawns the
+ * session locally but its OWN message ledger for that topic is EMPTY (it never polled
+ * the topic) and its TopicMemory has no rows — so `spawnSessionForTopic` builds an
+ * empty context and the moved conversation starts with amnesia. The router (which DID
+ * hold the conversation) is the source of truth; the receiver fetches the recent
+ * history from it and formats it here into the same "Thread History" block the
+ * single-machine JSONL path produces, so the moved session continues the conversation
+ * instead of starting blank.
+ *
+ * Pure + caller-agnostic so it is unit-testable without a live two-machine setup.
+ */
+/**
+ * Format fetched router-side history into a Thread History context block, or '' when
+ * there is nothing to inject. Mirrors the single-machine JSONL formatting in
+ * spawnSessionForTopic so a moved session reads identically to a local one.
+ */
+export function formatForwardedTopicContext(messages, topicName) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`--- Thread History (last ${messages.length} messages, relayed from the previous machine) ---`);
+    lines.push(`IMPORTANT: Read this history carefully before taking any action.`);
+    lines.push(`Your task is to continue THIS conversation, not start something new.`);
+    if (topicName)
+        lines.push(`Topic: ${topicName}`);
+    lines.push('');
+    for (const m of messages) {
+        const sender = m.fromUser ? (m.senderName || 'User') : 'Agent';
+        let ts = '??:??';
+        if (m.timestamp != null) {
+            const d = new Date(m.timestamp);
+            if (!Number.isNaN(d.getTime()))
+                ts = d.toISOString().slice(11, 19);
+        }
+        const text = (m.text || '').slice(0, 2000);
+        lines.push(`[${ts}] ${sender}: ${text}`);
+    }
+    lines.push('');
+    lines.push('--- End Thread History ---');
+    return lines.join('\n');
+}
+//# sourceMappingURL=ForwardedTopicContext.js.map

package/dist/core/ForwardedTopicContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForwardedTopicContext.js","sourceRoot":"","sources":["../../src/core/ForwardedTopicContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAsD,EACtD,SAAkB;IAElB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,4BAA4B,QAAQ,CAAC,MAAM,mDAAmD,CAAC,CAAC;IAC3G,KAAK,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;IAC/E,KAAK,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;IACnF,IAAI,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAC/D,IAAI,EAAE,GAAG,OAAO,CAAC;QACjB,IAAI,CAAC,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;gBAAE,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.166",
+  "version": "1.3.167",
   "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-31T12:02:03.497Z",
-  "instarVersion": "1.3.166",
+  "generatedAt": "2026-05-31T12:16:12.192Z",
+  "instarVersion": "1.3.167",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.167.md

@@ -0,0 +1,50 @@
+# 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, the moved conversation now remembers what you were talking about — the receiving
+machine pulls the recent history from the machine that was serving it. Only relevant
+when the multi-machine session pool is on; single-machine agents are unaffected. Nothing
+to configure.
+
+## Summary of New Capabilities
+
+- New `formatForwardedTopicContext` helper formats relayed history into the standard
+  thread-history block.
+- `spawnSessionForTopic` accepts an optional pre-computed context, used verbatim when
+  provided (skipping the empty-on-a-standby local sources); single-machine behavior is
+  unchanged when it is absent.
+- The owner-side resume fetches the router's recent topic messages and passes them, so a
+  moved session continues the conversation.
+
+## Evidence
+
+- Confirmed in code: on a standby, a moved session was spawned with no TopicMemory and an
+  empty local message history, so it started with no prior conversation context.
+- Unit, `tests/unit/ForwardedTopicContext.test.ts`: the formatter over empty history,
+  multi-message threads with attribution, sender/timestamp fallbacks, and the
+  per-message length cap.
+- Wiring, `tests/unit/session-pool-activation-wiring.test.ts`: the owner-side bridge
+  still spawns and fails safe with the history fetch wrapped around it.
+- 51 session-pool + adapter tests pass; tsc --noEmit clean.
+- Note: unit-verified; the live confirmation that a moved session retains its context
+  follows once the second machine's CLI is logged in.
+- Spec, `docs/specs/moved-session-context-relay.md` plus the .eli16.md sibling.
+
+## What Changed — a conversation moved to your other machine keeps its memory
+
+A quality step for the multi-machine "move this conversation to my other machine"
+feature. When a conversation moved to the backup machine, that machine started the
+session fresh from its own records — which were empty for that conversation (it had
+never been the one talking to you). So the moved conversation effectively forgot
+everything that came before it.
+
+This release has the receiving machine fetch the recent history from the machine that
+was serving the conversation, and seed the moved session with it. So the conversation
+picks up where it left off instead of resetting. It's best-effort: if the other machine
+can't be reached, the session still starts (just without the prior history, as before),
+so it never blocks the move.

package/upgrades/side-effects/moved-session-context-relay.md

@@ -0,0 +1,94 @@
+# Side-Effects Review — moved session inherits prior conversation (bug #2)
+
+**Version / slug:** `moved-session-context-relay`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+A session moved to a standby now inherits the topic's recent history from the router.
+New pure helper `formatForwardedTopicContext`; `spawnSessionForTopic` gains an optional
+`precomputedContext`; the owner-side resume fetches the router's
+`/telegram/topics/:topicId/messages` and passes it. Best-effort; default-off for
+single-machine. Closes audit #2 (moved session started with no prior context).
+
+## Decision-point inventory
+
+- **spawnSessionForTopic context source** — `precomputedContext` provided → use it,
+  skip the local TopicMemory/JSONL sources; else → unchanged local logic. Both sides
+  covered (the helper tests + the single-machine path is untouched when undefined).
+- **owner-side fetch** — router URL resolvable (`_resolveRouterUrl` → lease holder peer
+  URL, not self) + GET ok → format + pass; any failure → spawn without it. Best-effort.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** None. The single-machine spawn path is
+byte-identical when `precomputedContext` is undefined (no router). The fetch is purely
+additive context; a failure falls back to today's behavior (spawn without prior
+history). Nothing that worked before is rejected.
+
+## 2. Under-block
+
+**What does this still miss?** It fetches up to 50 recent messages (not the entire
+history / no summaries) — sufficient for continuity, not a full replica. It is a
+point-in-time fetch, not a shared/replicated ledger (the broader architectural fix
+remains separate). It is NOT yet live-verified (the moved session can't run until the
+mini's Claude is logged in — bug #12, pending the user). It does not sync userProfile
+(a smaller, separate gap).
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The formatter is a pure module (testable, mirrors the existing
+JSONL format). `precomputedContext` slots into `spawnSessionForTopic`'s existing
+context-resolution as the highest-precedence source. The fetch lives in the owner-side
+resume (the one place a moved session is spawned), using the same `_resolveRouterUrl` /
+authToken plumbing as the outbound relay.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority. It only ADDS context to a spawned session; it gates nothing and
+blocks nothing. A fetch failure is swallowed (best-effort) and the session proceeds.
+
+## 5. Interactions
+
+Reuses the read-only `/telegram/topics/:topicId/messages` route (no new endpoint) and
+the lease-holder resolution (`_resolveRouterUrl`) shared with the outbound relay. Pairs
+with the owner-side resume (#9/#11): the same path that spawns + persists + confirms a
+moved session now also seeds its context. Idempotent (a fresh fetch per spawn). No
+interaction with the lease or shared-state guard.
+
+## 6. External surfaces
+
+One cross-machine GET from the standby to the router's existing messages route
+(Bearer-authed). No new route, config, or notification. The visible effect: a moved
+session continues the conversation instead of resetting.
+
+## 7. Rollback cost
+
+Low. Remove the `precomputedContext` param + the onAccepted fetch + the helper; a moved
+session reverts to starting context-less (audit #2). No schema, no state, no migration.
+
+## Conclusion
+
+Targeted, additive, best-effort context relay; the formatter + the precedence both
+unit-tested; the single-machine path untouched; no new authority/surface; cheap revert.
+Makes a moved session continue its conversation. Honestly scoped: unit-verified, live
+confirmation pending the mini's Claude login.
+
+## Second-pass review (if required)
+
+Not required — additive best-effort context, pure formatter fully tested, single-machine
+path unchanged, reversible, no authority. The live moved-session-retains-context check
+is the Tier-3 gate after the user's mini login.
+
+## Evidence pointers
+
+- `tests/unit/ForwardedTopicContext.test.ts` — formatter over empty/multi/fallback/cap.
+- `tests/unit/session-pool-activation-wiring.test.ts` — owner-side bridge spawns + fails safe.
+- 51 session-pool + adapter tests green; `tsc --noEmit` clean.
+- Confirmed in code: on a standby, `spawnSessionForTopic` got `topicMemory: undefined`
+  and `getTopicHistory` returns `[]` → `contextContent = ''` (no prior history).
+- Spec: `docs/specs/moved-session-context-relay.md` (+ `.eli16.md`).