instar 1.3.821 → 1.3.823

package/upgrades/1.3.823.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+When a Telegram message arrives while a dead session is already being respawned, Instar now tells the user that this particular message was not queued or delivered and asks them to resend it after the restart. This closes the remaining single-machine silent-loss path without adding another queue.
+
+## What to Tell Your User
+
+If a message collides with an in-progress session restart, you will now receive an honest resend instruction instead of waiting indefinitely for a message that was never accepted into custody.
+
+## Summary of New Capabilities
+
+- Detects both normal and context-exhaustion respawn collisions.
+- Routes one deterministic custody notice through the existing Telegram topic-send funnel.
+- Preserves sentinel-before-dedup ordering and all existing emergency-stop, pause, and exactly-once behavior.
+
+## Evidence
+
+- `tests/unit/respawn-collision-notice.test.ts`
+- `tests/integration/telegram-forward-sentinel-intercept.test.ts`
+- `tests/integration/exactly-once-ingress.test.ts`

package/upgrades/eli16/cartographer-streaming-ls-tree.md

@@ -0,0 +1,7 @@
+# Streaming cartographer tree reads — ELI16
+
+The cartographer compares its index with Git's view of every file and directory. Previously Git had to finish producing that entire list before Instar could begin reading it, and the complete output lived in one large memory buffer. A sufficiently large repository could exceed that buffer and make the sweep refuse.
+
+Instar now reads each piece as Git produces it. Complete NUL-separated records are parsed immediately; only a record split between chunks is carried forward. The resulting path-to-object map has the same records and ordering as before, so candidate selection and authoring behavior do not change.
+
+The detector trusts the map only after Git exits successfully. A spawn error, non-zero exit, signal, or incomplete final record rejects the whole partial result through the existing `detect-git-error` refusal path. The work still runs in the established detect worker by default. The old `gitMaxBuffer` setting remains accepted for compatibility but no longer controls this stream.

package/upgrades/eli16/silent-respawn-collision-notice.md

@@ -0,0 +1,6 @@
+# Silent respawn collision notice — ELI16
+
+Imagine a session is broken and Instar is already starting its replacement. If another message arrives during that small window, the old code noticed that a restart was underway and simply returned. The message was neither queued nor delivered, and the user received no warning.
+
+Instar now sends a precise notice for that collision: the message was not queued or delivered, so resend it after the restart finishes. The first message still follows the existing durable pending-injection machinery. This change does not invent a second queue and does not alter emergency-stop, pause, or duplicate-message safety ordering.
+

package/upgrades/side-effects/cartographer-streaming-ls-tree.md

@@ -0,0 +1,80 @@
+# Side-Effects Review — Cartographer streaming ls-tree
+
+**Version / slug:** `cartographer-streaming-ls-tree`  
+**Date:** `2026-07-11`  
+**Author:** `instar-codey`  
+**Second-pass reviewer:** `framework_guard_review`
+
+## Summary
+
+The cartographer detect module replaces its buffered `git ls-tree` read with a guarded streaming child process and incremental NUL parser. `runDetect` is now asynchronous so both the default worker and the in-process rollback can await subprocess completion. No scaffold writer, index storage, heap ordering, writer ownership, or rollout setting changes.
+
+## Decision-point inventory
+
+- Git completion — modify — the map is accepted only on clean exit with a fully terminated NUL stream.
+- Git failure — pass-through — every failure shape still becomes `detect-git-error` and feeds the existing breaker.
+- `gitMaxBuffer` — pass-through — accepted and plumbed for config compatibility, intentionally ignored by the streaming reader.
+
+## Over-block / under-block
+
+Malformed output with an unterminated last record now refuses rather than accepting an ambiguous tail. Valid empty-tree output remains successful. The parser's carry can grow to one Git path record; the unavoidable output map remains O(tree entries) because downstream status comparison requires it, but there is no second whole-output string or split array.
+
+## Level of abstraction
+
+`SafeGitExecutor.readStream` extends the existing guarded Git funnel so classification, source-tree protection, environment scrubbing, and audit behavior are preserved. Incremental record parsing remains in `cartographerDetect`, the owner of ls-tree semantics. The worker boundary remains unchanged and default-on.
+
+## Signal vs authority
+
+No new authority is introduced. Git failure remains a named refusal signal consumed by the existing sweep breaker; partial data never reaches candidate selection.
+
+## Judgment-point check
+
+No new static heuristic at a competing-signals decision point. Child-process success is an enumerable protocol invariant: clean zero exit, no signal, and complete NUL framing.
+
+## Interactions
+
+- Ordering and shape: real-fixture parity freezes the same insertion order and OIDs as the former buffered parser.
+- Backpressure/memory: every stdout chunk is synchronously reduced into complete records; only the current record carry remains between chunks. Stderr capture is capped at 8 KiB.
+- Failure atomicity: the local map is returned only after `close` reports exit code zero and no signal. Mid-stream SIGKILL, non-zero exit, spawn error, and malformed tail reject it.
+- Lifetime: the read-only stream retains the former 30-second subprocess bound and kills on expiry. On worker timeout, the parent requests cooperative child teardown, retains the reported child PID as a fallback, and force-terminates after a 250 ms grace bound.
+- Configuration: `gitMaxBuffer` remains accepted at `ConfigDefaults`, server plumbing, engine config, and `DetectInput`; removing it would be a needless compatibility break.
+- Scope: #1073 items 1 (scaffold writer) and 2 (SQLite/sharding) are untouched and remain open.
+
+## External surfaces
+
+The exported `runDetect` helper now returns a Promise; all repository call sites are updated. Runtime output, snapshot schema, candidate ordering, and persistent state are unchanged. No operator action or external API is added. Timing improves for large Git trees because stdout is reduced as it arrives.
+
+## Operator-surface quality
+
+No operator surface — not applicable.
+
+## Multi-machine posture
+
+Machine-local by design: each machine compares its own checked-out Git tree inside its own detect worker. It emits no user-facing notice, holds no new durable state, strands no topic state, and generates no URL. Existing snapshot behavior is unchanged.
+
+## Rollback
+
+Pure code rollback. No persistent schema or state migration is involved. Reverting restores the explicit 64 MiB buffered floor and its refusal-on-overflow behavior.
+
+## Conclusion
+
+The transport upgrade is contained to #1073 item 3 and preserves the existing authority, writer, worker, ordering, and configuration contracts. Independent review found the first draft had lost the buffered executor's subprocess timeout and could orphan Git when a worker was terminated; the shared timeout and explicit two-level reap protocol now close that gap.
+
+## Second-pass review
+
+**Reviewer:** `framework_guard_review`  
+**Independent read:** concur. The revised stream retains bounded subprocess lifetime in both in-process and worker modes; the real-worker reap proof and funnel/stream suites are green.
+
+## Class-Closure Declaration
+
+`defectClass: unbounded-self-action`, `closure: n/a` — one bounded kill attempt is tied to a single detect-worker timeout; this adds no autonomous retry, respawn, notification, or recurring control loop.
+
+## Evidence
+
+- CI correction: the no-silent-fallbacks heuristic initially counted four
+  intentional error-propagation/terminal-state catches. Each is now explicitly
+  annotated in place; the baseline remains 492 and the exact ratchet is green.
+- Unit: chunk-edge NUL, a Unicode record split across four chunks, real-tree parity, empty tree, output beyond a one-byte legacy setting, mid-stream SIGKILL refusal, and hung-stream timeout.
+- Funnel: read-only streaming succeeds; destructive use is rejected before spawn.
+- Dist worker: forced timeout against a fake hung Git process proves the pass refuses and the reported OS PID is no longer alive.
+- Existing detect refusal, bounded heap, routes, config, and dist-worker suites remain green.

package/upgrades/side-effects/silent-respawn-collision-notice.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Silent respawn collision notice
+
+**Version / slug:** `silent-respawn-collision-notice`
+**Date:** `2026-07-11`
+**Author:** `instar-codey`
+**Second-pass reviewer:** framework_guard_review (Banach)
+
+## Summary of the change
+
+The two dead-session respawn collision guards in `wireTelegramRouting` no longer return silently. They send a deterministic, honest custody notice through the existing Telegram topic-send funnel before returning. No queue, persistence format, config, or authority surface is added.
+
+## Decision-point inventory
+
+- Context-exhaustion dead-session respawn collision — modified — sends the loss notice, then preserves the existing return.
+- Ordinary dead-session respawn collision — modified — sends the loss notice, then preserves the existing return.
+- Initial respawn and durable pending-inject paths — pass-through — unchanged.
+- Sentinel kill/pause intercept and exactly-once ingress gate — pass-through — unchanged and remain in their existing order.
+
+---
+
+## 1. Over-block
+
+No new block/allow surface exists. The colliding message was already rejected by the active-spawn guard; the change only makes that pre-existing lack of custody visible. The notice does not suppress, deduplicate, pause, or kill any message or session.
+
+## 2. Under-block
+
+The notice is dispatched asynchronously through the existing adapter. If Telegram delivery itself fails, the existing adapter failure behavior and error logging apply; this change does not claim external delivery succeeded. It also intentionally does not retry or queue the colliding user message, avoiding duplicate injection into a session whose startup ownership is already in flight.
+
+## 3. Level-of-abstraction fit
+
+The collision guard is the only layer that knows the message was refused specifically because another respawn owns the topic. The wording and injectable send helper live beside the existing cold-start fallback reply machinery, keeping user-facing spawn failure notices in one messaging module.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The notice is a truthful signal about custody already declined by existing control flow. It creates no authority and makes no semantic inference about the user's message.
+
+## 5. Interactions
+
+- **Shadowing:** Both reachable dead-session collision guards receive identical behavior; neither shadows the other.
+- **Double-fire:** Each inbound traverses only one of the mutually exclusive dead-session branches, so at most one notice is attempted.
+- **Races:** The existing `spawningTopics` ownership remains unchanged. The notice does not mutate it or wait on the spawn.
+- **Feedback loops:** The notice asks for an explicit resend after restart; it does not self-trigger another spawn or injection.
+
+## 6. External surfaces
+
+Telegram users may see one new message: “I got this message while the session was already restarting, so it was not queued or delivered. Please resend it once the restart finishes.” No dashboard, API, config, schema, URL, or other external surface changes.
+
+## 6b. Operator-surface quality
+
+The wording distinguishes receipt by the bridge from custody by the session, states exactly what failed, and gives one concrete recovery action. It does not falsely promise that the message is queued.
+
+## 7. Multi-machine posture
+
+Machine-local by design and fully functional with `multiMachine.sessionPool.inboundQueue` dark. It uses the local respawn ownership set and the existing Telegram adapter. No cross-machine state or dark feature is required.
+
+## 8. Rollback cost
+
+Pure code rollback: revert the helper, two call sites, tests, and release artifacts. No durable state or data migration requires repair.
+
+## Conclusion
+
+Clear to ship. The change closes the reachable silent-loss collision without changing queue semantics or safety authority.
+
+## Second-pass review (required: messaging/information-flow path)
+
+**Reviewer:** framework_guard_review (Banach)
+**Independent read:** Concurred after requesting an executable routing regression. The final test holds the first respawn unresolved, drives a second inbound through `wireTelegramRouting`, and proves exactly one loss notice, one spawn total, and zero injection. The reviewer confirmed both production guards preserve the existing return and that `src/server/routes.ts` safety ordering is untouched.
+
+## Evidence pointers
+
+- `tests/unit/respawn-collision-notice.test.ts`
+- `tests/unit/cold-start-fallback-reply.test.ts`
+- `tests/unit/cold-start-fallback-wiring.test.ts`
+- `tests/integration/telegram-forward-sentinel-intercept.test.ts`
+- `tests/integration/exactly-once-ingress.test.ts`
+- `tests/unit/no-silent-fallbacks.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+- **Defect class:** `unbounded-self-action`
+- **Closure:** `n/a`
+- **Reason:** One-shot user-driven custody notice emitted only when an inbound message collides with an already-running respawn; not a self-triggered loop.