instar 1.3.861 → 1.3.863

package/dist/lifeline/queuedNotice.js

@@ -0,0 +1,40 @@
+/**
+ * queuedNotice — the user-facing "your message was queued" text the lifeline
+ * sends when it cannot forward a message to the server right now.
+ *
+ * Why this is its own module (bug fix, reported by peer agent Luna/Sagemind
+ * 2026-07-17): the lifeline has TWO distinct "couldn't deliver right now"
+ * states, and they must never be conflated in the user-facing text:
+ *
+ *   - serverHealthy === false → the server is genuinely down / unreachable.
+ *       Historical wording: "Server is temporarily down. …" (accurate).
+ *
+ *   - serverHealthy === true  → the server is confirmed UP, but THIS forward
+ *       failed (a transient 10s timeout / 5xx / 503-boot / connection blip).
+ *       The old code told the user "Server is restarting." — which is false
+ *       and alarming: nothing restarted. This branch is a reconnect, not a
+ *       restart, so the notice must say so.
+ *
+ * Centralizing the wording here (instead of three inline if/else blocks in
+ * TelegramLifeline) makes the healthy-vs-down distinction a single, tested
+ * decision — the message and photo/file handlers all route through it.
+ */
+/**
+ * Build the user-facing queued-notice text.
+ *
+ * @param kind          which noun to use ("message" | "photo" | "file")
+ * @param queueLength   current number of items in the durable queue
+ * @param serverHealthy the supervisor's live health verdict at send time
+ */
+export function buildQueuedNotice(kind, queueLength, serverHealthy) {
+    const noun = kind; // 'message' | 'photo' | 'file' are already the display nouns
+    if (serverHealthy) {
+        // Healthy server + failed forward → reconnecting, NOT restarting.
+        return (`I'm having trouble reaching my server right now — your ${noun} is queued ` +
+            `(${queueLength} in queue) and I'll deliver it as soon as I reconnect.`);
+    }
+    // Genuinely-down server (unchanged wording — preserves the accurate message).
+    return (`Server is temporarily down. Your ${noun} has been queued (${queueLength} in queue). ` +
+        `It will be delivered when the server recovers.`);
+}
+//# sourceMappingURL=queuedNotice.js.map

package/dist/lifeline/queuedNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queuedNotice.js","sourceRoot":"","sources":["../../src/lifeline/queuedNotice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAoB,EACpB,WAAmB,EACnB,aAAsB;IAEtB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,6DAA6D;IAChF,IAAI,aAAa,EAAE,CAAC;QAClB,kEAAkE;QAClE,OAAO,CACL,0DAA0D,IAAI,aAAa;YAC3E,IAAI,WAAW,wDAAwD,CACxE,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,OAAO,CACL,oCAAoC,IAAI,qBAAqB,WAAW,cAAc;QACtF,gDAAgD,CACjD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.861",
+  "version": "1.3.863",
   "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-07-17T08:25:10.761Z",
-  "instarVersion": "1.3.861",
+  "generatedAt": "2026-07-17T20:16:29.908Z",
+  "instarVersion": "1.3.863",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -1594,7 +1594,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "6087c3cab4cf30a3bb11d43df640d8338b6cf45a6c26cf4d16063f7858f6a4b1",
+      "contentHash": "a7a7255d17ab19f681b96dc5334ce44d86ea07a1f285b2bf8f9e19e9a35e19ab",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/upgrades/1.3.862.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When the session pool chooses the current machine for a new conversation, its
+ownership row now advances from `placing` to `active` after the established
+local injection or spawn path succeeds.
+
+## What to Tell Your User
+
+A conversation started on the machine that receives it no longer remains
+stuck in a “starting” ownership state after it is already running.
+
+## Summary of New Capabilities
+
+No new setting. This repairs the existing session-pool placement lifecycle.
+
+## Evidence
+
+- Unit and integration coverage verifies the guarded transition, idempotence,
+  and the no-confirm-on-failed-spawn ordering.
+- A live single-agent CROSS-MACHINE laptop/Mini test advanced a fresh Mini
+  placement from `placing` to `active` at epoch 2.
+- Focused tests and TypeScript build pass.

package/upgrades/1.3.863.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When the lifeline can't hand a message off to the server but the server is
+confirmed **healthy** (a transient timeout / 5xx / connection blip on a single
+forward), the queued-message notice no longer says the false, alarming
+"Server is restarting." It now reflects the real state: "I'm having trouble
+reaching my server right now — your message is queued (N in queue) and I'll
+deliver it as soon as I reconnect." The genuinely-down message
+("Server is temporarily down…") is unchanged. The message, photo, and file
+handlers all route through one shared helper (`buildQueuedNotice`) so the two
+states can't drift apart again.
+
+## What to Tell Your User
+
+If a message of yours briefly can't be delivered while my server is actually
+up, you'll now see an honest "reconnecting, your message is queued" note
+instead of a scary "Server is restarting" alarm. Nothing about delivery
+changed — your message was never lost; it queues and delivers as before. This
+only fixes the wording so it stops claiming a restart that never happened.
+
+## Summary of New Capabilities
+
+No new setting. This is a bug fix to an existing user-facing notice.
+
+## Evidence
+
+- New unit test (`tests/unit/lifeline/queuedNotice.test.ts`, 8 cases) proves the
+  healthy-but-forward-failed branch never says "restart" or "temporarily down"
+  and always says "reconnect", and that the genuinely-down wording is preserved
+  byte-for-byte.
+- Full lifeline unit suite passes (18 files / 160 tests); TypeScript build and
+  `pnpm build` are clean; exactly one "Server is restarting" string remains in
+  the compiled lifeline (the separate callback-query server-down case, out of
+  scope).
+
+## The problem in one breath
+
+The lifeline is the small always-on process that watches Telegram and hands your messages to my main server. When it can't hand a message off right now, it queues the message and sends you a heads-up. There are two very different reasons a hand-off can fail — the server is genuinely down, OR the server is perfectly healthy and just one hand-off blipped (a brief network timeout). The old code sent the SAME scary "Server is restarting. Your message has been queued…" text for BOTH cases. So when the server was confirmed up and running, you could still get told it was restarting — which never happened. It's harmless (your message is never lost — it queues and delivers) but it erodes trust, because the agent cried "restart" when nothing restarted.
+
+## What already exists
+
+- **The lifeline** — the tiny watchdog process that forwards your Telegram messages to the server and queues them if it can't. Already durable: queued messages survive and replay.
+- **The server health check** — the lifeline always knows whether the server is up (`supervisor.healthy`). That verdict was already available at the exact spot where the wrong message was sent; the code just wasn't using it to pick the right words.
+- **The genuinely-down message** — for a truly-down server the lifeline already said the accurate "Server is temporarily down…", and that wording is unchanged.
+
+## What this adds
+
+One small, tested helper (`buildQueuedNotice`) now decides the notice wording from the live health verdict. When the server is healthy but the hand-off failed, you get: "I'm having trouble reaching my server right now — your message is queued (N in queue) and I'll deliver it as soon as I reconnect." When the server is genuinely down, you get the exact same accurate "temporarily down" message as before. The three places that send this notice (text, photo, file) all route through the one helper, so they can never drift apart again.
+
+## The new pieces
+
+- **`buildQueuedNotice(kind, queueLength, serverHealthy)`** — a pure, side-effect-free function that returns the right notice text. It is NOT allowed to make any decision about delivery or restarts; it only chooses words from a health verdict it is handed. That line matters: the authority to restart still lives entirely in the existing restart machinery — this helper just describes the current state honestly.
+
+## The safeguards
+
+The genuinely-down wording is byte-for-byte identical to before (a test locks that in, so no downstream dedup behavior shifts). A unit test proves the healthy-but-failed branch never contains the words "restart" or "temporarily down", and always mentions "reconnect"; and that the two states always produce different text. Scope is deliberately tight: the drift-promoter threshold question and the callback-query down-message are explicitly out of scope and were left untouched.
+
+## What you actually need to decide
+
+Nothing risky. This is a wording/logic bug fix with no new capability, no config, no state, and no schema change. The only judgment call is the exact replacement wording, which reads in plain language and is honest about what's happening. If it turns out wrong, the back-out is a one-line revert.

package/upgrades/side-effects/lifeline-reconnect-notice.md

@@ -0,0 +1,121 @@
+# Side-Effects Review — Lifeline "reconnecting" notice (fix false "Server is restarting")
+
+**Version / slug:** `lifeline-reconnect-notice`
+**Date:** `2026-07-17`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `Echo (Phase-5 self-review — see below)`
+
+## Summary of the change
+
+The lifeline forwards inbound Telegram messages to the server and, when it cannot forward right now, queues the message and sends the user a heads-up. There are two distinct "couldn't deliver right now" states — the server is genuinely **down** (`supervisor.healthy === false`) versus the server is **healthy but this one forward failed** (transient 10s timeout / 5xx / 503-boot / connection blip, `supervisor.healthy === true` and `forwardToServer()` returned non-`ok`). The healthy-but-failed branch was sending the user the false, alarming `Server is restarting. Your message has been queued…` even though the server was confirmed up. Reported by peer agent Luna (Sagemind) 2026-07-17, verified against source; it also hit operator Justin directly.
+
+Files touched:
+- `src/lifeline/queuedNotice.ts` (new) — a pure helper `buildQueuedNotice(kind, queueLength, serverHealthy)` that centralizes the notice wording.
+- `src/lifeline/TelegramLifeline.ts` — the four queue-ack call sites (text healthy-fail, text down, photo, file/document) now route through the helper; the two photo/file inline `if/else` blocks collapse to one call each.
+- `tests/unit/lifeline/queuedNotice.test.ts` (new) — unit coverage.
+
+## Decision-point inventory
+
+- `TelegramLifeline` queue-ack wording (text/photo/file handlers) — **modified (wording/logic only)** — picks the user-facing notice string from the live `supervisor.healthy` verdict. This is a message-*wording* decision, not a message *block/allow* or delivery decision. No gating authority added, removed, or changed.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The change never suppresses, delays, or rejects a message; it only chooses the text of a heads-up that is already being sent (still gated by the unchanged `shouldSendQueueAck` rate-limiter). Message queueing/delivery is entirely unchanged.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The queued message still enqueues and replays exactly as before; the only behavioral delta is the words in the notice.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The wording decision belongs precisely where the send happens — the lifeline handler that already holds the `supervisor.healthy` verdict and the queue length. The new helper is a pure string builder (lowest sensible level: no I/O, no decision authority). It does not re-implement or run parallel to any existing gate; it consumes a health verdict the caller already computed. Centralizing the three previously-duplicated sites into one tested function is a strict simplification (DRY), not a new abstraction competing with an existing one.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface.
+
+`buildQueuedNotice` holds ZERO authority: it neither restarts anything, nor decides whether to send, nor gates delivery. It is handed a health SIGNAL (`supervisor.healthy`, computed by the existing supervisor) and returns descriptive text. The authority to restart the lifeline remains entirely with the existing `RestartOrchestrator` / `LifelineDriftPromoter`; this change deliberately stops the notice from *asserting* a restart the system did not perform — i.e. it makes the user-facing text HONEST about the current state rather than claiming an action. No brittle logic gains blocking authority.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The wording is chosen from a single, enumerable boolean (`serverHealthy` true/false) — an invariant two-state fork, not a point where multiple live signals conflict. There is no arbiter needed and none added.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. The notice send sits after `shouldSendQueueAck` (unchanged) and does not run before/after any gate whose outcome it could mask.
+- **Double-fire:** none introduced. The version-skew path (`handleVersionSkew`, fired on a 426) is a separate code path and is untouched; this change does not add a second notice.
+- **Races:** none new. `this.queue.length` is read at send time exactly as before; no new shared state is introduced (the helper is stateless/pure).
+- **Feedback loops:** none. The text is terminal output to the user; it feeds nothing back into the forward/queue machinery.
+- **Down-branch wording preserved byte-for-byte:** the `serverHealthy === false` output is identical to the previous inline strings (locked by a test), so any downstream that keys on that exact text (e.g. the duplicate-message dedup window) sees no change.
+
+---
+
+## 6. External surfaces
+
+- **Other agents / install base:** ships in the instar package `dist/`; every agent gets the corrected wording when it updates and its lifeline restarts onto the new version. No migration needed — the lifeline is compiled package code, not an agent-installed file (`.claude/settings.json`, config defaults, CLAUDE.md template, hook scripts, or built-in skills), so `PostUpdateMigrator` is not involved.
+- **Telegram:** the only external-visible change is the improved notice text a user reads when a forward transiently fails. No API shape, topic, or delivery-path change.
+- **Persistent state:** none. No schema, ledger, or state-file change.
+- **Timing/runtime:** the branch is selected from the live `supervisor.healthy` at send time — same input the old code had at the same spot.
+- **Operator surface (Mobile-Complete):** no operator-facing actions added or touched. This is a USER-facing message, not an operator action/approval/grant surface.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. This change touches a **user-facing** Telegram notice, not a dashboard renderer, approval page, or grant/revoke/secret-drop form. (For completeness on the user-facing text quality: the new notice leads with the real state in plain language — "I'm having trouble reaching my server right now — your message is queued (N in queue) and I'll deliver it as soon as I reconnect." — exposes no raw internals, and is honest rather than alarming.)
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The lifeline is a per-machine process: each machine's lifeline forwards to that machine's own server and its `supervisor.healthy` verdict is about the local server. The notice is emitted by whichever machine actually received and tried to forward the user's message, so there is no cross-machine state to replicate or proxy. It emits a user-facing notice, but one-voice gating is not newly needed: the send is already governed by the existing per-topic `shouldSendQueueAck` rate-limiter and the pre-existing duplicate-message suppression window — this change alters only the words, not the send cadence or the number of voices. No durable state (nothing to strand on topic transfer) and no generated URLs.
+
+---
+
+## 8. Rollback cost
+
+Pure code change — revert the two source files (and the new helper/test) and ship as the next patch. No persistent state, no data migration, no agent-state repair, no user-visible regression during the rollback window (worst case is the old wording returns). One-line-scale back-out.
+
+---
+
+## Conclusion
+
+The review confirms a tightly-scoped, low-risk wording/logic fix with no decision-point authority, no block/allow surface, no persistent state, and no multi-machine coherence hazard. The design change made during review was to extract the wording into a single pure helper (rather than edit three inline strings), which both makes the fix unit-testable in isolation and removes the duplicated photo/file `if/else` — closing the "three copies drift apart" failure mode structurally. The genuinely-down wording is preserved byte-for-byte to avoid any downstream dedup/text-matching side effect. Scope was deliberately held to the three reported sites; the drift-promoter threshold question and the callback-query down-message were left untouched (flagged to the reporter as separate items). Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** Echo (self, Phase-5 — the change touches the messaging/lifeline path)
+**Independent read of the artifact: concur**
+
+Concur with the review. Re-verified independently: (1) the only remaining `Server is restarting` string in `TelegramLifeline.ts` is the callback-query genuine-`!supervisor.healthy` branch (out of scope, and at least plausibly-true in a down state); (2) all four queue-ack sites now route through `buildQueuedNotice`; (3) the down-branch bytes are unchanged (test-locked); (4) no self-triggered action is added — the notice is a one-shot response to an inbound user message, not a self-firing loop. No concern raised.
+
+---
+
+## Evidence pointers
+
+- `npx tsc --noEmit` — clean (exit 0).
+- `npx vitest run tests/unit/lifeline/queuedNotice.test.ts` — 8/8 pass.
+- `npx vitest run tests/unit/lifeline/` — 18 files / 160 tests pass (no regression).
+- `pnpm build` — dist compiles; `dist/lifeline/queuedNotice.js` present; exactly 1 `Server is restarting` remains in `dist/lifeline/TelegramLifeline.js` (the intentional callback-down site).
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+Not a self-triggered controller and not a fix to an agent-authored artifact (prompt/hook/config/skill/standards text). This is a fix to compiled TypeScript runtime behavior — a one-shot, user-message-driven notice, not a loop/monitor/sentinel/reaper/scheduler/recovery path. `unbounded-self-action` class: `n/a` — one-shot user-driven action, not a self-triggered loop.

package/upgrades/side-effects/session-pool-self-placement-confirmation.md

@@ -0,0 +1,99 @@
+# Side-Effects Review — Session-pool self-placement confirmation
+
+**Version / slug:** `session-pool-self-placement-confirmation`
+**Date:** `2026-07-17`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `continuation_impl_review` (independent Codex reviewer) — CONCUR after two correction rounds
+
+## Summary
+
+Successful local session delivery now confirms a self-owned `placing` row as
+`active`. Confirmation remains outside `SessionRouter`, after the real local
+inject/spawn seam. Failed spawns do not confirm.
+
+## Decision-point inventory
+
+- Post-local-delivery ownership transition — **modified** — a successful local
+  tail may confirm only its own still-placing row.
+
+## 1. Over-block
+
+No message is newly blocked. Missing, active, or remotely-owned rows are no-ops.
+
+## 2. Under-block
+
+The transition cannot run before delivery because every callsite is after a
+synchronous injection that returned true or inside a spawn/respawn success
+continuation. A rejected injection or spawn does not confirm.
+Registry confirmation failure is diagnostic-only after delivery and cannot fall
+into the delivery-failure handler. If the transition commits but observer
+emission fails, the committed outcome remains true and diagnostics avoid
+claiming an unknowable row state.
+
+## 3. Level-of-abstraction fit
+
+The state predicate is a small pure core. Server wiring owns the timing because
+it alone knows when the legacy local delivery tail has actually succeeded.
+
+## 4. Signal vs authority compliance
+
+The ownership registry remains the sole transition authority. Local delivery
+success is evidence supplied to that authority, not a parallel ownership store.
+
+## 4b. Judgment-point check
+
+No heuristic is introduced. The enumerable rule is `status=placing AND
+owner=self AND local delivery succeeded`.
+
+## 5. Interactions
+
+Ordinary traffic to an active local session calls the helper but performs no
+write. Remote placement confirmation remains unchanged. SpawnAdmission still
+runs before every local spawn and a refusal cannot reach confirmation.
+
+## 6. External surfaces
+
+`GET /pool/ownership-view` now reports `active` after a successful self-placement.
+No schema, authentication, configuration, or user command changes.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Replicated.** The transition is written to the existing ownership registry
+and propagated by its existing replication path. A live laptop/Mini test proved
+the receiving Mini's row reached `active`.
+
+## 8. Rollback cost
+
+Pure code rollback with no migration. Rollback restores stuck `placing` rows
+for new self-placements.
+
+## Evidence
+
+- `tests/unit/SessionPoolLocalClaim.test.ts`
+- `tests/unit/session-pool-activation-wiring.test.ts`
+- `tests/integration/session-pool-local-claim.integration.test.ts`
+- `tests/unit/no-silent-fallbacks.test.ts` (both contained error paths are
+  explicitly annotated and continue to report through `onError`)
+- Live single-agent CROSS-MACHINE topic 3462 placement: owner Mini, epoch 2,
+  status `active`.
+
+## Conclusion
+
+The change is narrow and preserves honest failure semantics. It should ship
+with the independent session-lifecycle second pass concurred.
+
+## Second-pass review
+
+The first pass found that live injection's boolean result was ignored and that
+confirmation exceptions could falsely enter delivery-failure handling. Both
+were fixed and regression-tested. The second pass found a post-commit honesty
+edge: observer emission could throw after CAS committed while diagnostics
+claimed the row remained placing. The authoritative CAS result is now separate
+from best-effort observation; committed confirmation stays true, diagnostics
+make no unverified state claim, and the observer-failure regression is pinned.
+The reviewer then concurred with no remaining findings.
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect or self-triggered controller is added or
+modified — not applicable.