instar 1.3.882 → 1.3.884

package/upgrades/1.3.883.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Threadline reply authorization now recognizes authenticated inbound messages in the modern hash-chained canonical log as well as the legacy listener inbox.
+- Wrong-thread, outbound-only, malformed, unconfined, or unreadable evidence remains fail-closed.
+- Reply evidence cannot authorize a send unless the durable at-most-once claim authority is available.
+
+## What to Tell Your User
+
+Cross-agent conversations no longer stall when a spawned worker replies to a message stored by Threadline's newer canonical history path. The security boundary is unchanged: replies still have to point to the exact authenticated inbound message on the same thread.
+
+## Summary of New Capabilities
+
+- Reliable replies from spawned Threadline sessions across both canonical history generations.
+
+## Evidence
+
+- Feedback: `fb-63d7c1fb-50a`
+- Unit: `tests/unit/threadline/ThreadlineReplyValidation.test.ts`
+- Behavioral route: `tests/integration/threadline-relay-send-priority.test.ts`
+- Wiring: `tests/integration/threadline-reap-recovery-wiring.test.ts`

package/upgrades/1.3.884.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- Telegram reply requests now have finite connection and total deadlines.
+- Transport failures always return an explicit ambiguous outcome with a delivery id and safe retry guidance.
+- Stock installed relay scripts upgrade in place; locally customized scripts remain protected.
+
+## What to Tell Your User
+
+If a Telegram reply loses its connection before Instar can return a result, the agent now sees a clear uncertain-delivery warning instead of an empty tool outcome. It will verify before retrying rather than risk sending the message twice.
+
+## Summary of New Capabilities
+
+- Bounded, observable Telegram reply outcomes even when the transport fails before an HTTP response.
+
+## Evidence
+
+- Feedback: `fb-9c139a25-11e`
+- Behavioral test: `tests/unit/telegram-reply-bounded-outcome.test.ts`
+- Existing recovery/status regression suite remains green.

package/upgrades/side-effects/telegram-reply-bounded-outcome.md

@@ -0,0 +1,76 @@
+# Side-Effects Review — Telegram reply bounded outcome
+
+**Version / slug:** `telegram-reply-bounded-outcome`
+**Date:** `2026-07-19`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `/root/cross_engine_completion` (independent reviewer subagent)
+
+## Summary of the change
+
+The shipped Telegram reply template bounds its final HTTP request and explicitly renders transport ambiguity. This closes `fb-9c139a25-11e` at the outcome-observability class level.
+
+## Decision-point inventory
+
+- Final relay curl — modified transport boundary — limits connection to 3 seconds and total time to 125 seconds.
+- Curl transport-status branch — new — reports an ambiguous outcome and prevents automatic recovery classification when no HTTP status exists.
+
+## 1. Over-block
+
+No valid HTTP response is rejected. The overall client window is five seconds longer than the server's 120-second outbound route budget, so the server retains authority to return a structured success, timeout, or tone rejection. A transport failure exits as ambiguity rather than falsely blocking the message.
+
+## 2. Under-block
+
+The helper cannot prove whether the server accepted a request before a network failure. It therefore makes no delivered/not-delivered claim. The delivery id is surfaced for durable investigation, and the caller is explicitly told to verify before retrying.
+
+## 3. Level-of-abstraction fit
+
+The boundary belongs in the caller that owns curl lifecycle and transcript output. The server already owns semantic tone review and delivery; moving transport-process interpretation into that server would not help a caller that never receives an HTTP response.
+
+## 4. Signal vs authority compliance
+
+Per `docs/signal-vs-authority.md`, curl exit status is exact transport evidence, not a semantic heuristic. It has authority only to classify the HTTP outcome as unavailable. It does not claim delivery failure or authorize a retry.
+
+## 4b. Judgment-point check
+
+No competing-signals judgment. A nonzero curl exit with no completed HTTP response deterministically means the caller lacks an HTTP outcome; delivery remains explicitly ambiguous.
+
+## 5. Interactions
+
+HTTP 200, 408, 422, and recoverable status handling is unchanged. The new transport branch runs before HTTP parsing, so a synthetic `000` from a completed curl remains in the existing recovery matrix while an actual curl failure never gets blindly enqueued. The original shell did not enable errexit; the change preserves that state.
+
+## 6. External surfaces
+
+Agents now receive a non-empty, actionable ambiguity message after a bounded transport failure. Normal user-visible Telegram messages and tone rejection text are unchanged.
+
+## 6b. Operator-surface quality
+
+The output names uncertainty, prohibits blind retry, and includes the delivery id without exposing credentials or raw response internals.
+
+## 7. Multi-machine posture
+
+Machine-local by design: the helper calls the owning agent server resolved from the owning agent home. The reported delivery id is the same id sent to that server, so investigation remains tied to the correct machine-local ledger. No URL or replicated state is introduced.
+
+## 8. Rollback cost
+
+Pure template and test change. Revert and ship a patch; existing installed scripts will be refreshed by the normal template migrator. No data repair or schema migration is needed.
+
+## Conclusion
+
+The missing standard was outcome-bearing-call completeness: external calls must be bounded and must render success, rejection, or ambiguity. The process gap was HTTP-status coverage without transport-exit coverage. The behavioral curl-timeout test closes the class. Independent review is required because this changes an outbound messaging decision path.
+
+## Second-pass review
+
+**Reviewer:** `/root/cross_engine_completion`
+**Independent read:** concur after correction. The reviewer initially found that the immediately prior shipped template SHA was absent from the safe migration allowlist, so existing agents would receive only a `.new` candidate, and that the emergency inline fallback retained an unbounded curl. Both were required corrections. The migration now recognizes the exact prior SHA and behaviorally proves in-place stock upgrade while preserving customized scripts; the fallback now has equivalent finite transport bounds and explicit non-HTTP ambiguity handling. The reviewer independently re-inspected both closures and reported no remaining over/under-block, timeout, dedup/recovery, shell, or signal-vs-authority concern.
+
+## Evidence pointers
+
+- `tests/unit/telegram-reply-bounded-outcome.test.ts`
+- `tests/unit/PostUpdateMigrator-telegramReply.test.ts`
+- `tests/unit/telegram-reply-recoverable-classification.test.ts`
+- `tests/unit/telegram-reply-port-resolution.test.ts`
+- Feedback `fb-9c139a25-11e`
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: claim-vs-evidence`, `closure: guard`, `guardEvidence: { enforcementType: gate, citation: src/templates/scripts/telegram-reply.sh#CURL_STATUS, howCaught: the helper makes no delivery claim without a completed HTTP result; every final request has finite bounds and every nonzero transport exit renders explicit ambiguity on stdout and stderr without authorizing retry }`.

package/upgrades/side-effects/threadline-canonical-reply-validation.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Threadline canonical reply validation
+
+**Version / slug:** `threadline-canonical-reply-validation`
+**Date:** `2026-07-19`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `/root/threadline_review` (independent reviewer subagent)
+
+## Summary of the change
+
+The `/threadline/relay-send` reply authorization gate now validates `inReplyTo` against the union of the legacy HMAC listener inbox and the modern hash-chained per-thread log, while requiring the durable reply-claim authority before either source can authorize. A dedicated helper contains the fail-closed policy; unit and behavioral production-route tests pin it. This closes `fb-63d7c1fb-50a`.
+
+## Decision-point inventory
+
+- `isAuthenticatedThreadlineInbound` — added authority helper — decides whether a reply pointer names a durable authenticated inbound on the claimed thread.
+- `/threadline/relay-send` — modified — delegates its existing reply-authorization decision to the union helper.
+
+## 1. Over-block
+
+Valid messages absent from both evidence stores remain rejected. A modern entry with an invalid/unconfined thread id is rejected even if bytes exist, preserving traversal safety. A log read failure rejects unless the legacy store independently proves the pointer. Evidence also fails closed when `ListenerSessionManager`, the durable at-most-once claim authority, is unavailable.
+
+## 2. Under-block
+
+The new path accepts only `direction: inbound`; an outbound leg cannot authorize a reply. `ThreadLog` is populated through the authenticated inbound recording funnels. A local attacker able to rewrite the agent's state directory is outside the existing ThreadLog trust boundary; chain verification is an observability check rather than a per-send hot-path scan.
+
+## 3. Level-of-abstraction fit
+
+The helper sits at the reply authorization chokepoint and consumes the two existing canonical persistence authorities. It does not duplicate authentication or message recording. The migration union belongs here because the decision is specifically “does durable canonical evidence contain this inbound?”
+
+## 4. Signal vs authority compliance
+
+[docs/signal-vs-authority.md](../../docs/signal-vs-authority.md) applies. This gate has deterministic authority over an enumerable security invariant: exact thread id + exact message id + inbound direction in an authenticated canonical store. No semantic judgment or brittle content heuristic is involved.
+
+## 4b. Judgment-point check
+
+No competing-signals judgment. Store membership, direction, and thread confinement are exact invariants.
+
+## 5. Interactions
+
+The helper runs after the warm-worker current-inbound check and before the at-most-once reply claim. It broadens only the evidence source and explicitly couples authorization to availability of claim ownership. Legacy traffic remains byte-for-byte eligible. Modern E2E relay traffic now reaches the same claim gate. The production route test proves acceptance claims then releases after delivery, while an active claim returns 409 without delivery.
+
+## 6. External surfaces
+
+Valid spawned Threadline workers can reply to authenticated inbound messages persisted only in the modern log. Invalid replies still receive the same 400 error shape. No operator action, new endpoint, or external credential is added.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Machine-local by design under Threadline's single-holder model: both canonical stores belong to the receiving holder and the reply route runs there. Cross-machine relay ingestion writes the modern log before the worker replies. No user notice or URL is generated; durable reply claims remain on the holder.
+
+## 8. Rollback cost
+
+Pure code change. Revert and ship a patch; no schema, migration, or state cleanup is required. Rollback would restore the valid-reply rejection for modern-only inbounds.
+
+## Conclusion
+
+The missing standard was migration-consumer completeness: a new canonical authority must be adopted by every authorization consumer or exposed through an explicit compatibility union. The process gap was a wiring test that pinned the legacy implementation string rather than the semantic two-store contract. The helper and tests close both gaps. Pending required independent review because this touches a messaging authorization gate.
+
+## Second-pass review
+
+**Reviewer:** `/root/threadline_review`
+**Independent read:** concur. The reviewer first blocked the change because modern evidence could authorize when the at-most-once claim authority was absent. After the correction, they independently inspected the diff and reran the focused suite (21/21): authorization now requires claim authority, modern-only evidence reaches claim and post-delivery release, and an active claim returns 409 with no delivery.
+
+## Evidence pointers
+
+- `tests/unit/threadline/ThreadlineReplyValidation.test.ts`
+- `tests/integration/threadline-relay-send-priority.test.ts`
+- `tests/integration/threadline-reap-recovery-wiring.test.ts`
+- Feedback `fb-63d7c1fb-50a`
+
+## Class-Closure Declaration (display-only mirror)
+
+`defectClass: claim-vs-evidence`, `closure: guard`, `guardEvidence: { enforcementType: gate, citation: src/threadline/ThreadlineReplyValidation.ts#isAuthenticatedThreadlineInbound, howCaught: the live reply gate requires exact inbound evidence from either canonical generation and the regression suite reproduces a modern-only authenticated inbound }`.

package/upgrades/telegram-reply-bounded-outcome.eli16.md

@@ -0,0 +1,9 @@
+# Telegram reply bounded outcome
+
+The Telegram reply helper makes an HTTP request to the local Instar server, which may spend time reviewing the message before it sends. The final request previously had no client deadline and did not inspect the transport exit status. If the caller's tool yielded while the review was running and curl later ended without a normal HTTP response, the helper could finish without printing any useful result. The agent then could not tell whether the message was blocked, delivered, or still uncertain.
+
+The repair treats a terminal outcome as part of delivery correctness. The final request now has a three-second connection limit and a 125-second overall limit, slightly longer than the server's 120-second outbound budget. Normal HTTP results are unchanged, including the detailed 422 tone-review explanation. If transport ends without an HTTP result, the helper prints an explicit AMBIGUOUS result to both standard output and standard error, includes the pre-minted delivery id for investigation, and tells the caller not to retry blindly. The emergency inline fallback follows the same rule.
+
+This does not claim that an interrupted request failed. The server may have received it and may still complete the send, so automatically queueing or retrying would risk a duplicate. The behavioral regression replaces curl with a controlled timeout and proves the helper is bounded, produces non-empty output on both channels, exits without triggering a blind retry, and preserves the delivery identifier.
+
+The CLASS review found the missing standard: every outcome-bearing external call needs a bounded transport and an explicit terminal rendering for success, rejection, and ambiguity. The process gap was that existing tests covered HTTP status classification but not a transport process that exits before producing an HTTP status—or whether the repaired template actually reaches already-installed agents. This adds both failure-mode and in-place-migration ratchets and closes feedback `fb-9c139a25-11e`.

package/upgrades/threadline-canonical-reply-validation.eli16.md

@@ -0,0 +1,9 @@
+# Threadline canonical reply validation
+
+When one Instar agent receives a message from another, its reply must point back to the exact authenticated inbound message. That prevents a worker from inventing a message id or replying across the wrong thread. A recent Threadline migration introduced a newer canonical, hash-chained log that every modern relay path writes, while retaining the older HMAC listener inbox for compatibility. The reply gate accidentally kept checking only the older inbox.
+
+That split produced a bad outcome: the message was authenticated, delivered, and durably present in the new canonical log, but the spawned worker's reply was rejected as unauthenticated. Thread history could therefore look empty to the worker and a valid cross-agent conversation stalled.
+
+This repair defines one fail-closed validation helper over the union of both canonical generations. A reply pointer is accepted when either the legacy HMAC inbox proves the message belongs to that thread or the modern confined hash-chained log proves that exact id exists as an inbound leg, and only when the durable at-most-once claim ledger is available. Outbound legs never qualify. Wrong-thread pointers, malformed ids, path escapes, absent stores, and read failures remain rejected.
+
+The CLASS review found a migration-coherence gap: adding a canonical store is incomplete until every authorization consumer moves to it or explicitly reads a compatibility union. It also found that evidence and at-most-once claiming must remain one invariant. The fix addresses that class in one chokepoint and adds unit tests for both stores and failure modes, plus a behavioral live-route test proving modern-only acceptance, claim release after delivery, and rejection of duplicate claims. This closes feedback `fb-63d7c1fb-50a` without weakening Threadline's authenticated-reply boundary.