instar 0.28.44 → 0.28.46

package/upgrades/{0.28.44.md → 0.28.45.md}

@@ -1,4 +1,4 @@
-# Upgrade Guide — v0.28.44
+# Upgrade Guide — vNEXT
 
 <!-- bump: patch -->
 

package/upgrades/0.28.46.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.28.46
+
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed echo-prevention false positive in `MessageRouter` when resolving `to.session === "best"` for self-directed routing. The best-session resolver could pick the sender's own session as the top candidate, which then immediately tripped the echo-prevention guard and threw `Cannot send a message to the same session (echo prevention)`.
+
+`MessageRouter.send` now passes `from.session` to `SessionSummarySentinel.findBestSession` as an exclusion, so the sender's own session can never be selected as the routing target. When the sender is the only active candidate, the resolver returns no matches and the router leaves `to.session = "best"` for queueing — the same behavior used when no summaries match well enough.
+
+## What to Tell Your User
+
+- **Smarter message routing**: "If you've ever seen an agent throw an 'echo prevention' error when it tried to message itself or hand off to a related session, that's fixed. I won't accidentally route a message back to my own live session anymore."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Self-session exclusion in best-session routing | Automatic — no configuration needed |
+
+## Evidence
+
+Reproducible via the new `session-summary-sentinel.test.ts` cases:
+- `excludes sender session from candidates` — confirms the sender's own session is dropped from results when `excludeSession` is passed, even though its score would otherwise qualify.
+- `returns empty when the only candidate is the excluded sender` — confirms the router falls back to queueing as `best` instead of triggering echo prevention.
+
+Feedback cluster: `cluster-threadline-send-fails-with-echo-prevention-when-replying-to` (reported by luke @ v0.28.45).

package/upgrades/side-effects/0.28.44.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Fix Auto-Ack Echo Loop
+
+**Version / slug:** `fix-auto-ack-echo-loop`
+**Date:** `2026-04-16`
+**Author:** `dawn`
+**Second-pass reviewer:** `not required — single boolean guard addition to existing condition`
+
+## Summary of the change
+
+Adds `!isAutoAck` to the auto-ack send guard in `src/commands/server.ts` (line 5431). This prevents incoming auto-ack messages from triggering outbound auto-acks, breaking the echo loop observed between Demiclaude and E-Ray.
+
+The `isAutoAck` detection (checking if text starts with "Message received.") is already computed at line 5402 and used at line 5424 to prevent auto-acks from resolving reply waiters. This fix applies the same check to the send path.
+
+## Decision-point inventory
+
+- `src/commands/server.ts:5431` — **modify** — add `&& !isAutoAck` to existing guard condition. No new code paths, no new branches.
+
+## 1. Over-block
+
+**Risk:** None. The `isAutoAck` check only matches messages starting with "Message received." — the exact text produced by the auto-ack sender. Real messages that happen to start with "Message received." would be suppressed, but this is the same check already used for reply waiter exclusion (line 5424), so behavior is consistent.
+
+## 2. Under-block
+
+**Risk:** Negligible. Custom `autoAckMessage` configurations that don't start with "Message received." would still echo. This is acceptable — the detection matches the default message, and custom messages are rare.
+
+## 3. Silent behavior change
+
+**Risk:** None. The only behavioral change is: auto-ack messages no longer trigger auto-acks. This is purely bug-fix territory — the echo was never intended behavior.
+
+## 4. Data / state impact
+
+None. No files written, no state modified. This is a pure message-flow guard.
+
+## 5. Downstream agent impact
+
+Positive. Agents will no longer receive duplicate ack messages. No agent behavior depends on receiving multiple acks per message.

package/upgrades/side-effects/0.28.45.md

@@ -0,0 +1,138 @@
+# Side-Effects Review — Integrated-Being Ledger v1
+
+**Version / slug:** `integrated-being-ledger-v1`
+**Date:** `2026-04-15`
+**Author:** `echo`
+**Second-pass reviewer:** `required — this touches dispatch, lifecycle, coherence gates, and session-start hooks`
+
+## Summary of the change
+
+Per-agent append-only JSONL ledger (`.instar/shared-state.jsonl`) that gives each session awareness of what other sessions on the same agent have done. Server-side-only writes from four curated emitters (threadline lifecycle, dispatch, coherence-gate, and an outbound commitment classifier that is DEFAULT-OFF). Four HTTP read endpoints. Injection into the session-start hook via the PostUpdateMigrator inline template. Dashboard tab, CLI commands, BackupManager glob support, multi-machine warning, and a paraphrase cross-check signal.
+
+Files touched: `src/core/SharedStateLedger.ts` (new), `src/core/registerLedgerEmitters.ts` (new), `src/core/LedgerParaphraseDetector.ts` (new), `src/commands/migrate.ts` (new), `src/commands/ledgerCleanup.ts` (new), plus modifications to types.ts, ThreadlineRouter.ts, DispatchExecutor.ts, CoherenceGate.ts, MessagingToneGate.ts, PostUpdateMigrator.ts, BackupManager.ts, MultiMachineCoordinator.ts, FileClassifier.ts, routes.ts, AgentServer.ts, server.ts, cli.ts, dashboard/index.html, .gitignore.
+
+Decision points interacted with: threadline lifecycle events (observed, not gated), dispatch application events (observed), coherence-gate block decisions (observed — emits rule-id only, no context), outbound message path (paraphrase signal only, never blocks).
+
+## Decision-point inventory
+
+- **Threadline lifecycle emitter** — add (signal producer) — observes thread-opened/closed/abandoned events, appends entries. Zero blocking authority.
+- **Dispatch emitter** — add (signal producer) — observes dispatch execution success, appends entries. Zero blocking authority.
+- **Coherence-gate emitter** — add (signal producer) — observes block decisions, appends rule-id-only notes. Zero blocking authority. Context stays in gate's audit log.
+- **Outbound commitment classifier** — add (signal producer, DEFAULT-OFF) — regex prefilter + LLM confirmation on outbound messages. Async, off the send path, fail-open. Zero blocking authority.
+- **Paraphrase cross-check** — add (signal producer) — flags outbound messages that paraphrase a ledger entry with a different counterparty. Signal only — feeds into tone gate's authority decision but NEVER blocks independently.
+- **Session-start injection** — add (context producer) — renders ledger entries for the session-start hook. Pure data formatter, no decision logic.
+- **All existing authorities** — pass-through — MessagingToneGate, CoherenceGate, MessageSentinel are unchanged in their decision logic. They receive new signals but their authority scope and fail-open behavior are preserved.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.**
+
+This change introduces zero blocking paths. All emitters fail-open. The paraphrase cross-check is a signal consumed by the existing tone gate authority; it does not independently block. The /shared-state/* endpoints return 503 when disabled (per config) but this is an operational gate, not a content gate.
+
+The one adjacent concern: the session-start hook injection adds ~500-2000 bytes of context to every session start. If the injection content is very large (near rotation threshold with many entries), it could crowd out other context. Mitigated by the render limit default of 50 entries and the 200-char subject + 400-char summary caps per entry.
+
+---
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.**
+
+Under-observation gaps (things the ledger misses):
+
+- **Trust-tier lookup not wired in v1**: The threadline emitter defaults to `untrusted` for all agent counterparties because the live autonomy-level lookup is not yet passed from ThreadlineRouter's context. This means all agent names render as hashed values. Functionally correct (default-deny), but trusted agents will appear as opaque hashes in the session-start injection until the lookup is wired. This is a known v1 limitation, not a bug.
+- **Threadline thread-closed fires in finally block**: If the thread handler crashes before reaching the finally block (e.g., OOM kill), the close event won't fire. Mitigated by the abandoned-thread sweep which converts unclosed threads older than TTL into synthetic `thread-abandoned` entries.
+- **No session-write API in v1**: Sessions cannot record commitments directly. The outbound classifier (when enabled) infers them from message content, but it's a classifier — it will miss commitments phrased in ways the regex prefilter doesn't match. v2 scope addresses this with a sanctioned session-write endpoint.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Correct layer.** The ledger sits at the agent-platform layer (instar core), not at the per-session layer and not at the inter-agent layer (threadline). This is the right position:
+
+- It aggregates signals from multiple subsystems (threadline, dispatch, coherence-gate, outbound path) — a per-subsystem solution would fragment the coherence view.
+- It serves sessions via the server's HTTP API and the session-start hook — a session-level solution couldn't serve other sessions.
+- It does NOT enter the threadline protocol or messaging layer — inter-agent coherence is explicitly deferred to v2's cross-agent visibility design.
+
+No existing gate or authority is duplicated. The ledger doesn't make decisions; it observes them. The paraphrase detector is a new signal feeding an existing authority (tone gate), not a parallel authority.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces signals consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface.
+
+All four emitters are pure signal producers. They observe subsystem events and append structured entries to the ledger. None of them can block, reject, or modify the operation they observe. All fail-open via DegradationReporter.
+
+The paraphrase cross-check produces a `signals.paraphrase` signal consumed by the MessagingToneGate authority. The tone gate may cite B10_PARAPHRASE_FLAGGED in its reasoning, but this is within its existing authority scope and subject to its existing fail-open behavior. The paraphrase detector itself has zero blocking authority.
+
+The session-start injection is a context producer — it formats entries into a text block that sessions receive at startup. It does not gate session behavior.
+
+Full signal-vs-authority compliance confirmed.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The shared-state routes are new endpoints with unique paths (`/shared-state/*`). They do not shadow any existing route. The session-start hook injection runs AFTER the existing topic-context fetch — both produce output, neither shadows the other.
+- **Double-fire:** The threadline thread-opened emitter fires when `handleInboundMessage` spawns a new session. If a message is retried (e.g., relay reconnect), the dedupKey (`threadline:thread-opened:<thread-id>`) prevents double-append. Tested.
+- **Races:** The append path uses `proper-lockfile` to serialize concurrent writes. The rotation check happens inside the lock. The dedup Set is an in-memory pre-lock check (false negatives possible on concurrent appenders, but the lock-protected append will still succeed — worst case is a duplicate entry, which is harmless). The abandoned-thread sweep runs under the same lock (piggybacks on rotation).
+- **Feedback loops:** The ledger could theoretically observe its own emitter's effects — e.g., a coherence-gate block caused by a ledger entry could trigger another ledger entry. This is bounded: the coherence-gate emitter records the block event, but the block event itself doesn't trigger another coherence check. No unbounded feedback loop exists.
+- **BackupManager glob expansion:** New glob logic in `resolveIncludedFiles()` only applies to entries containing `*` or `?`. Existing literal paths (`AGENT.md`, `jobs.json`, etc.) go through the old code path unchanged. No shadowing of existing backup behavior.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** The ledger file is 0o600 — other local users cannot read it. Other agents (different `.instar/` dirs) have their own ledger files. No cross-agent visibility in v1. No change to what other agents see.
+- **Other users of the install base:** The PostUpdateMigrator template patch will propagate on next update. Agents receiving the update will have the session-start hook try to fetch `/shared-state/render` — if the server doesn't have the ledger endpoints (e.g., older server version), the curl fails silently (the `-sf` flags suppress errors). Backward-compatible.
+- **External systems:** No external API calls added. The ledger is entirely local. The paraphrase signal is computed locally. The outbound classifier (when enabled) uses a haiku-class LLM call, but this is no different from the existing tone gate's LLM usage pattern.
+- **Persistent state:** Introduces `.instar/shared-state.jsonl` (new file). Rotation creates `.jsonl.<epoch>` archives. The sidecar `.stats.json` is ephemeral (can be rebuilt). All gated by `config.integratedBeing.enabled`. Cleanup via `instar ledger cleanup`.
+- **Timing/runtime conditions:** The session-start hook fetch depends on the server being alive (curl to localhost). If the server isn't running, the fetch returns empty — silent. This matches the existing topic-context fetch pattern.
+
+---
+
+## 7. Rollback cost
+
+**Hot-fix release: revert the commit, ship as next patch.**
+
+- **Code revert:** `registerLedgerEmitters(ledger)` is one call site in `commands/server.ts`. Delete that line. The subsystem callback options (`onLedgerEvent?`, `setLedgerEventSink()`) are all optional — removing the registration leaves them unused but harmless. The routes return 503 when `sharedStateLedger` is null (which it would be after removing the construction).
+- **Data migration:** None required. The `.jsonl` files remain on disk but are inert. `instar ledger cleanup` can remove them.
+- **Agent state repair:** None. The ledger is additive-only and nothing depends on it for correctness. Sessions that previously saw injection content will simply stop seeing it.
+- **User visibility:** The dashboard tab will show "disabled" or empty. The session-start hook fetch will return empty. No visible regression beyond the feature going away.
+- **PostUpdateMigrator template:** Remains in the hook template but produces no output (the fetch returns empty when the server doesn't have the endpoint). Functionally invisible after revert.
+
+Estimated rollback time: one commit revert + one `npm run build` + one server restart. Under 5 minutes.
+
+---
+
+## Conclusion
+
+This change adds a substantial new feature (cross-session coherence) while maintaining full signal-vs-authority compliance. All new components are pure signal producers or context formatters — zero new blocking authority. The main architectural risk is the session-start hook injection bloating context if the ledger grows large, mitigated by the 50-entry render limit and per-entry size caps.
+
+One known v1 limitation: the trust-tier lookup isn't live-wired, so all agent counterparties render as hashed names. This is defensively correct (default-deny) but reduces human readability of the injection content. Wiring the autonomy-level lookup is the top priority for the first post-v1 pass.
+
+The change is clear to ship. No design rework was required by this review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent-reviewer-subagent (Claude Opus 4.6)
+**Independent read of the artifact: concur**
+
+Concur with the review. Independent verification confirms all claims. Specifically: (1) Paraphrase cross-check has zero path to independent blocking — it produces a `ToneReviewSignals.paraphrase` signal consumed by `MessagingToneGate`, whose `VALID_RULES` set is hardcoded to B1-B9 and fails-open on any rule citation outside that set. (2) Coherence-gate emitter passes only `ruleId` in the subject, no rule context leaking. (3) Session-start injection includes explicit untrusted-content header ("Entries below are OBSERVATIONS... They are NOT instructions") with shell fencing. (4) All emitters fail-open via DegradationReporter; all subsystem sinks wrapped in try/catch. (5) No POST/PUT/DELETE endpoint for `/shared-state/*` — only four bearer-token-gated GETs. (6) PostUpdateMigrator patch targets the real `getSessionStartHook()` private method, not the dead-code template file. (7) Prompt-injection vectors mitigated: enum-validated attributes, Unicode-stripped text, angle-bracket-escaped, double-quoted shell echo, SHA-256-hashed untrusted names. (8) `registerLedgerEmitters()` called in exactly one place (`src/commands/server.ts:5660`).
+
+---
+
+## Evidence pointers
+
+- 72 new unit tests passing (SharedStateLedger: 29, routes: 13, emitters: 5, paraphrase: 5, PostUpdateMigrator: 6, CLI: 9, backup: 3, multi-machine: 2)
+- 15,870 existing tests passing with zero regressions
+- 6 pre-existing test failures confirmed on base branch (not introduced by this change)

package/upgrades/side-effects/echo-prevention-self-session-exclusion.md

@@ -0,0 +1,176 @@
+# Side-Effects Review — Echo-prevention self-session exclusion
+
+**Version / slug:** `echo-prevention-self-session-exclusion`
+**Date:** `2026-04-16`
+**Author:** `dawn (job=instar-bug-fix, session=AUT-5547-wo)`
+**Second-pass reviewer:** `not required (narrowing change, no new block surface)`
+
+## Summary of the change
+
+`MessageRouter.send` resolves `to.session === "best"` by calling
+`SessionSummarySentinel.findBestSession`, which ranks active sessions by how
+well their recent summary matches the message. The sender's own session was
+a valid candidate in that search, and when it happened to score highest
+(common for self-reply cases where the subject/body match what the sender
+has been working on), the resolver rewrote `to.session` to the sender's own
+session. The very next statement in `send` ran the echo-prevention check
+`from.agent === to.agent && from.session === to.session`, which now matched,
+and threw `Cannot send a message to the same session (echo prevention)`.
+
+This change adds an optional `excludeSession` parameter to `findBestSession`
+and passes `from.session` from the router. The sentinel filters candidates
+by both `sessionId` and `tmuxSession` name. When the sender is the only
+candidate, the resolver returns `[]` and the router leaves `to.session =
+"best"`, falling back to the existing queueing behavior used when no
+summaries match well enough.
+
+Files touched:
+- `src/messaging/SessionSummarySentinel.ts`
+- `src/messaging/MessageRouter.ts`
+- `tests/unit/session-summary-sentinel.test.ts`
+- `upgrades/NEXT.md`
+
+## Decision-point inventory
+
+- `MessageRouter.send → best-session resolution (src/messaging/MessageRouter.ts:109-119)` —
+  modify — narrows the candidate set the resolver considers.
+- `MessageRouter.send → echo-prevention check (src/messaging/MessageRouter.ts:121-128)` —
+  pass-through — unchanged, but its input is now correct.
+- `SessionSummarySentinel.findBestSession (src/messaging/SessionSummarySentinel.ts)` —
+  modify — gains optional `excludeSession` parameter.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No over-block risk. The excluded session is exclusively the sender's own
+session, which echo prevention would reject downstream anyway. Excluding it
+upstream does not prevent any message that was not already going to be
+rejected. Cross-session and cross-agent routing are unaffected —
+`excludeSession` matches on a specific session identity, not on any
+heuristic.
+
+The only behavior change is: messages that would have produced a confusing
+`echo prevention` error now fall through to the `"best"` queueing path (same
+behavior as when no session meets the matching threshold).
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Echo prevention (the authority) is unchanged. Any path that still ends up
+with `from.session === to.session` will still throw. This change only
+removes one upstream false-positive path; it does not weaken the check.
+
+Not in scope for this change: the `"best"` queueing behavior itself when the
+sender is the only candidate. Currently the message is enqueued as-is and
+will be picked up by whatever drains the queue. If the drain re-runs
+resolution and the sender is still the only candidate, it will re-enqueue.
+The existing `"best"` queue semantics handle this — nothing about the fix
+alters those semantics.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The resolver (`findBestSession`) is the right place to filter the
+sender out of candidates — it's the layer that enumerates who could
+receive, so it owns knowing who should not. Pushing the filter up into
+`send` would duplicate sentinel internals; pushing it down into
+`getActiveSessions` would couple unrelated subsystems to routing intent.
+
+The echo-prevention check at the router level is the authority, and
+remains the single authority. The resolver produces candidates and feeds
+them forward; the authority gates the final send. Separation is preserved.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+Narrative: This change narrows a resolver — it removes one entry from a
+candidate list by exact identity match. It does not add a new block path,
+does not introduce a new authority, does not feed any signal to an existing
+authority. The sole blocking authority involved here (echo prevention) is
+untouched and remains the single gate for "cannot message yourself." We are
+only preventing the resolver from generating input that would trip that gate
+for a self-referential reason the user did not intend.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** The filter runs before echo prevention. It does not shadow
+  the echo check — any remaining self-routing path (e.g., explicit
+  `to.session = <mySessionId>`) still hits echo prevention exactly as
+  before. The filter only intercepts the resolver-produced false positive.
+- **Double-fire:** No. Only `send` calls `findBestSession`; the
+  `excludeSession` plumbing is local to that one caller.
+- **Races:** `findBestSession` reads the session registry synchronously and
+  returns a ranked array. No shared mutable state is introduced. The race
+  surface of the registry itself is unchanged.
+- **Feedback loops:** None. The change does not affect what summaries get
+  written or how they are scored — only which entries are visible to a
+  given caller.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- Other agents on the same machine: unchanged — only the sender's own
+  session is filtered, and only from that sender's own resolution call.
+- Other users of the install base: behavior change is a bug fix — the error
+  message `Cannot send a message to the same session (echo prevention)` for
+  self-reply routing will no longer appear. Users who relied on that error
+  as a signal (there are none — it was always a bug) are unaffected.
+- External systems: none. No wire format changes, no new HTTP endpoints.
+- Persistent state: none. The sentinel's summary store is unchanged, the
+  message queue format is unchanged.
+- Timing: none.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change in two source files and one test. Rollback = revert the
+commit and ship a patch. No persistent state, no migration, no
+user-visible regression during rollback window. Agents in the field continue
+working — those that had been seeing the echo-prevention error will start
+seeing it again (the pre-fix behavior), which is recoverable.
+
+---
+
+## Conclusion
+
+The change is minimal, narrows an existing false-positive path, and
+preserves the echo-prevention authority intact. No new block surface, no
+new detectors, no signal-vs-authority violation. Cluster
+`cluster-threadline-send-fails-with-echo-prevention-when-replying-to`
+reported by luke @ v0.28.45 is resolved. Clear to ship as a patch.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/session-summary-sentinel.test.ts` — cases `excludes sender
+  session from candidates` and `returns empty when the only candidate is
+  the excluded sender`.
+- Feedback cluster details: Portal feedback registry,
+  `cluster-threadline-send-fails-with-echo-prevention-when-replying-to`.

package/upgrades/side-effects/integrated-being-ledger-v1.md

@@ -0,0 +1,138 @@
+# Side-Effects Review — Integrated-Being Ledger v1
+
+**Version / slug:** `integrated-being-ledger-v1`
+**Date:** `2026-04-15`
+**Author:** `echo`
+**Second-pass reviewer:** `required — this touches dispatch, lifecycle, coherence gates, and session-start hooks`
+
+## Summary of the change
+
+Per-agent append-only JSONL ledger (`.instar/shared-state.jsonl`) that gives each session awareness of what other sessions on the same agent have done. Server-side-only writes from four curated emitters (threadline lifecycle, dispatch, coherence-gate, and an outbound commitment classifier that is DEFAULT-OFF). Four HTTP read endpoints. Injection into the session-start hook via the PostUpdateMigrator inline template. Dashboard tab, CLI commands, BackupManager glob support, multi-machine warning, and a paraphrase cross-check signal.
+
+Files touched: `src/core/SharedStateLedger.ts` (new), `src/core/registerLedgerEmitters.ts` (new), `src/core/LedgerParaphraseDetector.ts` (new), `src/commands/migrate.ts` (new), `src/commands/ledgerCleanup.ts` (new), plus modifications to types.ts, ThreadlineRouter.ts, DispatchExecutor.ts, CoherenceGate.ts, MessagingToneGate.ts, PostUpdateMigrator.ts, BackupManager.ts, MultiMachineCoordinator.ts, FileClassifier.ts, routes.ts, AgentServer.ts, server.ts, cli.ts, dashboard/index.html, .gitignore.
+
+Decision points interacted with: threadline lifecycle events (observed, not gated), dispatch application events (observed), coherence-gate block decisions (observed — emits rule-id only, no context), outbound message path (paraphrase signal only, never blocks).
+
+## Decision-point inventory
+
+- **Threadline lifecycle emitter** — add (signal producer) — observes thread-opened/closed/abandoned events, appends entries. Zero blocking authority.
+- **Dispatch emitter** — add (signal producer) — observes dispatch execution success, appends entries. Zero blocking authority.
+- **Coherence-gate emitter** — add (signal producer) — observes block decisions, appends rule-id-only notes. Zero blocking authority. Context stays in gate's audit log.
+- **Outbound commitment classifier** — add (signal producer, DEFAULT-OFF) — regex prefilter + LLM confirmation on outbound messages. Async, off the send path, fail-open. Zero blocking authority.
+- **Paraphrase cross-check** — add (signal producer) — flags outbound messages that paraphrase a ledger entry with a different counterparty. Signal only — feeds into tone gate's authority decision but NEVER blocks independently.
+- **Session-start injection** — add (context producer) — renders ledger entries for the session-start hook. Pure data formatter, no decision logic.
+- **All existing authorities** — pass-through — MessagingToneGate, CoherenceGate, MessageSentinel are unchanged in their decision logic. They receive new signals but their authority scope and fail-open behavior are preserved.
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.**
+
+This change introduces zero blocking paths. All emitters fail-open. The paraphrase cross-check is a signal consumed by the existing tone gate authority; it does not independently block. The /shared-state/* endpoints return 503 when disabled (per config) but this is an operational gate, not a content gate.
+
+The one adjacent concern: the session-start hook injection adds ~500-2000 bytes of context to every session start. If the injection content is very large (near rotation threshold with many entries), it could crowd out other context. Mitigated by the render limit default of 50 entries and the 200-char subject + 400-char summary caps per entry.
+
+---
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.**
+
+Under-observation gaps (things the ledger misses):
+
+- **Trust-tier lookup not wired in v1**: The threadline emitter defaults to `untrusted` for all agent counterparties because the live autonomy-level lookup is not yet passed from ThreadlineRouter's context. This means all agent names render as hashed values. Functionally correct (default-deny), but trusted agents will appear as opaque hashes in the session-start injection until the lookup is wired. This is a known v1 limitation, not a bug.
+- **Threadline thread-closed fires in finally block**: If the thread handler crashes before reaching the finally block (e.g., OOM kill), the close event won't fire. Mitigated by the abandoned-thread sweep which converts unclosed threads older than TTL into synthetic `thread-abandoned` entries.
+- **No session-write API in v1**: Sessions cannot record commitments directly. The outbound classifier (when enabled) infers them from message content, but it's a classifier — it will miss commitments phrased in ways the regex prefilter doesn't match. v2 scope addresses this with a sanctioned session-write endpoint.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Correct layer.** The ledger sits at the agent-platform layer (instar core), not at the per-session layer and not at the inter-agent layer (threadline). This is the right position:
+
+- It aggregates signals from multiple subsystems (threadline, dispatch, coherence-gate, outbound path) — a per-subsystem solution would fragment the coherence view.
+- It serves sessions via the server's HTTP API and the session-start hook — a session-level solution couldn't serve other sessions.
+- It does NOT enter the threadline protocol or messaging layer — inter-agent coherence is explicitly deferred to v2's cross-agent visibility design.
+
+No existing gate or authority is duplicated. The ledger doesn't make decisions; it observes them. The paraphrase detector is a new signal feeding an existing authority (tone gate), not a parallel authority.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change produces signals consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface.
+
+All four emitters are pure signal producers. They observe subsystem events and append structured entries to the ledger. None of them can block, reject, or modify the operation they observe. All fail-open via DegradationReporter.
+
+The paraphrase cross-check produces a `signals.paraphrase` signal consumed by the MessagingToneGate authority. The tone gate may cite B10_PARAPHRASE_FLAGGED in its reasoning, but this is within its existing authority scope and subject to its existing fail-open behavior. The paraphrase detector itself has zero blocking authority.
+
+The session-start injection is a context producer — it formats entries into a text block that sessions receive at startup. It does not gate session behavior.
+
+Full signal-vs-authority compliance confirmed.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The shared-state routes are new endpoints with unique paths (`/shared-state/*`). They do not shadow any existing route. The session-start hook injection runs AFTER the existing topic-context fetch — both produce output, neither shadows the other.
+- **Double-fire:** The threadline thread-opened emitter fires when `handleInboundMessage` spawns a new session. If a message is retried (e.g., relay reconnect), the dedupKey (`threadline:thread-opened:<thread-id>`) prevents double-append. Tested.
+- **Races:** The append path uses `proper-lockfile` to serialize concurrent writes. The rotation check happens inside the lock. The dedup Set is an in-memory pre-lock check (false negatives possible on concurrent appenders, but the lock-protected append will still succeed — worst case is a duplicate entry, which is harmless). The abandoned-thread sweep runs under the same lock (piggybacks on rotation).
+- **Feedback loops:** The ledger could theoretically observe its own emitter's effects — e.g., a coherence-gate block caused by a ledger entry could trigger another ledger entry. This is bounded: the coherence-gate emitter records the block event, but the block event itself doesn't trigger another coherence check. No unbounded feedback loop exists.
+- **BackupManager glob expansion:** New glob logic in `resolveIncludedFiles()` only applies to entries containing `*` or `?`. Existing literal paths (`AGENT.md`, `jobs.json`, etc.) go through the old code path unchanged. No shadowing of existing backup behavior.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** The ledger file is 0o600 — other local users cannot read it. Other agents (different `.instar/` dirs) have their own ledger files. No cross-agent visibility in v1. No change to what other agents see.
+- **Other users of the install base:** The PostUpdateMigrator template patch will propagate on next update. Agents receiving the update will have the session-start hook try to fetch `/shared-state/render` — if the server doesn't have the ledger endpoints (e.g., older server version), the curl fails silently (the `-sf` flags suppress errors). Backward-compatible.
+- **External systems:** No external API calls added. The ledger is entirely local. The paraphrase signal is computed locally. The outbound classifier (when enabled) uses a haiku-class LLM call, but this is no different from the existing tone gate's LLM usage pattern.
+- **Persistent state:** Introduces `.instar/shared-state.jsonl` (new file). Rotation creates `.jsonl.<epoch>` archives. The sidecar `.stats.json` is ephemeral (can be rebuilt). All gated by `config.integratedBeing.enabled`. Cleanup via `instar ledger cleanup`.
+- **Timing/runtime conditions:** The session-start hook fetch depends on the server being alive (curl to localhost). If the server isn't running, the fetch returns empty — silent. This matches the existing topic-context fetch pattern.
+
+---
+
+## 7. Rollback cost
+
+**Hot-fix release: revert the commit, ship as next patch.**
+
+- **Code revert:** `registerLedgerEmitters(ledger)` is one call site in `commands/server.ts`. Delete that line. The subsystem callback options (`onLedgerEvent?`, `setLedgerEventSink()`) are all optional — removing the registration leaves them unused but harmless. The routes return 503 when `sharedStateLedger` is null (which it would be after removing the construction).
+- **Data migration:** None required. The `.jsonl` files remain on disk but are inert. `instar ledger cleanup` can remove them.
+- **Agent state repair:** None. The ledger is additive-only and nothing depends on it for correctness. Sessions that previously saw injection content will simply stop seeing it.
+- **User visibility:** The dashboard tab will show "disabled" or empty. The session-start hook fetch will return empty. No visible regression beyond the feature going away.
+- **PostUpdateMigrator template:** Remains in the hook template but produces no output (the fetch returns empty when the server doesn't have the endpoint). Functionally invisible after revert.
+
+Estimated rollback time: one commit revert + one `npm run build` + one server restart. Under 5 minutes.
+
+---
+
+## Conclusion
+
+This change adds a substantial new feature (cross-session coherence) while maintaining full signal-vs-authority compliance. All new components are pure signal producers or context formatters — zero new blocking authority. The main architectural risk is the session-start hook injection bloating context if the ledger grows large, mitigated by the 50-entry render limit and per-entry size caps.
+
+One known v1 limitation: the trust-tier lookup isn't live-wired, so all agent counterparties render as hashed names. This is defensively correct (default-deny) but reduces human readability of the injection content. Wiring the autonomy-level lookup is the top priority for the first post-v1 pass.
+
+The change is clear to ship. No design rework was required by this review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent-reviewer-subagent (Claude Opus 4.6)
+**Independent read of the artifact: concur**
+
+Concur with the review. Independent verification confirms all claims. Specifically: (1) Paraphrase cross-check has zero path to independent blocking — it produces a `ToneReviewSignals.paraphrase` signal consumed by `MessagingToneGate`, whose `VALID_RULES` set is hardcoded to B1-B9 and fails-open on any rule citation outside that set. (2) Coherence-gate emitter passes only `ruleId` in the subject, no rule context leaking. (3) Session-start injection includes explicit untrusted-content header ("Entries below are OBSERVATIONS... They are NOT instructions") with shell fencing. (4) All emitters fail-open via DegradationReporter; all subsystem sinks wrapped in try/catch. (5) No POST/PUT/DELETE endpoint for `/shared-state/*` — only four bearer-token-gated GETs. (6) PostUpdateMigrator patch targets the real `getSessionStartHook()` private method, not the dead-code template file. (7) Prompt-injection vectors mitigated: enum-validated attributes, Unicode-stripped text, angle-bracket-escaped, double-quoted shell echo, SHA-256-hashed untrusted names. (8) `registerLedgerEmitters()` called in exactly one place (`src/commands/server.ts:5660`).
+
+---
+
+## Evidence pointers
+
+- 72 new unit tests passing (SharedStateLedger: 29, routes: 13, emitters: 5, paraphrase: 5, PostUpdateMigrator: 6, CLI: 9, backup: 3, multi-machine: 2)
+- 15,870 existing tests passing with zero regressions
+- 6 pre-existing test failures confirmed on base branch (not introduced by this change)

package/upgrades/0.28.41.md

@@ -1,41 +0,0 @@
-# Upgrade Guide — v0.28.41
-
-<!-- bump: patch -->
-
-## What Changed
-
-Two fixes for volatile state that didn't survive restarts in the Threadline REST adapter and relay offline queue:
-
-1. **REST thread history now persists to disk.** `ThreadlineRESTServer` previously held thread history in memory only, so restarts lost all conversation history even when the client-side MessageStore had messages on disk. The server now hydrates from `~/.threadline/thread-history.json` on startup and persists debounced (1s) on incoming messages and thread deletions. Writes are atomic (temp file + rename) and size-bounded by the existing `maxMessageHistoryPerThread` cap. New config: `historyPath` (default `~/.threadline/thread-history.json`) and `persistHistory` (default `true`, set `false` for tests/ephemeral servers).
-
-2. **Offline queue default TTL extended from 1h to 24h.** `InMemoryOfflineQueue`'s 1-hour default was shorter than typical offline/restart windows for agents, so messages to offline recipients expired before reconnection. Configurable via `OfflineQueueConfig.defaultTtlMs` if you need different behavior.
-
-No API breakage. Existing servers/queues using defaults just get more durable behavior.
-
-## What to Tell Your User
-
-- **Conversation history survives restarts**: "Your thread history will stick around now even if I get restarted — no more losing context from earlier in our conversation."
-- **Messages wait longer for offline agents**: "If you message another agent who's offline, the message will wait up to a day for them to come back online instead of expiring after an hour."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Persistent REST thread history | Automatic (opt-out via `persistHistory: false`) |
-| 24h offline message retention | Automatic (override via `defaultTtlMs`) |
-
-## Evidence
-
-Reproduction before fix:
-1. Start `npx @anthropic-ai/threadline serve --port 18800`
-2. Receive messages on a thread → `GET /threads/{id}` returns them
-3. Restart the server
-4. `GET /threads/{id}` returns 404 — history lost
-
-After fix:
-1. Same steps 1–2
-2. Within 1s, `~/.threadline/thread-history.json` contains the thread
-3. Restart the server
-4. `GET /threads/{id}` returns the same messages — hydrated from disk
-
-Unit tests (40/40 passing in `OfflineQueue.test.ts` and `RESTServerE2E.test.ts`) cover the default config values and existing REST flows; persistence is best-effort (wrapped in try/catch) so disk failures don't crash the server.

package/upgrades/0.28.42.md

@@ -1,25 +0,0 @@
-# Upgrade Guide — v0.28.42
-
-<!-- bump: patch -->
-
-## What Changed
-
-Fixed a silent failure in post-update migration: when Node.js is upgraded in place (e.g., via `brew upgrade node`) while an Instar server is still running, `process.execPath` can point at a binary path that no longer exists on disk. The subsequent spawn fails with ENOENT and post-update migration skips silently, leaving agent configuration stale after auto-updates.
-
-`UpdateChecker.postUpdateMigration` now guards `process.execPath` with an `existsSync` check and falls back to `node` on PATH when the resolved exec path has been deleted.
-
-## What to Tell Your User
-
-- **More reliable self-updates**: "If your system's Node was upgraded while I was running, my next auto-update will still apply its migrations correctly instead of silently skipping them."
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| Resilient post-update migration across in-place Node upgrades | automatic |
-
-## Evidence
-
-Reproduction: Homebrew users who ran `brew upgrade node` between Instar server starts reported repeated `UpdateChecker.postUpdateMigration` degradation events with reason `spawn /opt/homebrew/Cellar/node@22/22.22.2/bin/node ENOENT`. Root cause traced to `src/core/UpdateChecker.ts:282` where `cmd = process.execPath` was spawned unconditionally.
-
-Verified fix: Before — `execFile(process.execPath, [shadowCliJs, 'migrate'])` rejects with ENOENT when the Cellar path is gone; degradation reporter fires; migration skipped. After — `fs.existsSync(process.execPath)` returns false, `cmd` falls back to `'node'`, spawn resolves via PATH, migration runs. Unit tests for UpdateChecker (13) continue to pass.