instar 1.3.1319 → 1.3.1321

package/upgrades/1.3.1320.md

@@ -0,0 +1,47 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A new dark research instrument measures whether Jev (TypeSafe, `jev-1.13.0`)
+can tell which agent replies need the operator's review, without ever showing
+a flag. On a development agent, once a minute the server reads the newest
+agent replies in its own Telegram history (conversational sends only, at most
+30 minutes old), strips secrets from each reply and the operator message it
+answers before cutting anything, and asks Jev: does this reply need review
+(it claims done without evidence, asks the operator to decide or act, reports
+a costly step, or misses the ask), is it fine, or can't it tell? It writes one
+content-free row per reply to `logs/jev-review-flag-shadow.jsonl` (the
+Telegram message ids, the label, P(needs review) in both option orders, and
+whether a flag would have been shown). `GET /jev-review-flag/summary` reports
+the counts. No hook or settings change: it is a server-side timer, so it
+covers every framework that relays through the server.
+
+Dev-gated: live on a development agent, dark on the fleet
+(`intelligence.jevReviewFlagShadow`, `enabled` omitted). Needs the vault
+`typesafe_api_key`. Bounded by a daily call cap (default 3000), a 1.5 s
+timeout and one call at a time; the kill switch is read live at every tick.
+
+## What to Tell Your User
+
+Nothing changes for you. On a development agent, Instar now quietly records
+which of its Telegram replies a fast model thinks you should look at, so we
+can check those guesses against the replies you actually corrected before
+deciding whether to show you a "worth a look" marker.
+
+## Summary of New Capabilities
+
+- `GET /jev-review-flag/summary`: checks, would-flags and per-topic counts from the log-only review-flag shadow (development agents).
+
+## Evidence
+
+- Live through the real module against this agent's real Telegram history and
+  the real vendor: four recent replies judged in 89–169 ms each, all `fine`
+  (P(needs review) 0.07–0.49, both option orders agreeing); the log held no
+  message text.
+- Unit, integration and e2e tests; the e2e builds the shadow with the server's
+  factory reading config.json live, starts the real timer, and shows the
+  feature alive on a development agent, dark on the fleet, and stopped by an
+  explicit `false`.

package/upgrades/1.3.1321.md

@@ -0,0 +1,153 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`TelegramAdapter.createOrReopenAgentHealthAttentionItem` rethrew a `duplicate-content` hold on its "returned after recovery" post, so callers (the Threadline spawn drain's give-up handler) treated an alert the operator already had as a failed Attention write and retried every 30 s for the whole dedup window (ACT-1304 fault 2, Luna/sagemind log 2026-10-04 12:05-12:18Z). That one hold reason now counts as delivered; every other hold still throws.
+
+After `instar pair` externalizes secrets, `.instar/config.json` holds `{ "secret": true }` for `authToken`. Instar's hooks and scripts already read `$INSTAR_AUTH_TOKEN` first, but the CLAUDE.md "API Authentication" instruction still read the config directly and turned the placeholder into a rejected Bearer value (ACT-1303, reported by Luna/sagemind).
+
+- `generateClaudeMd` (both auth sections): `$INSTAR_AUTH_TOKEN` → `node .instar/scripts/secret-get.mjs authToken` → config value only when it is a string.
+- `PostUpdateMigrator.migrateClaudeMd` rewrites the old line in existing agents' CLAUDE.md (content-sniffed, idempotent).
+
+Codex rollout discovery, file reads, and full parsing now run in a worker thread. The worker relocates the prior scan without changing its selection or results: `listAllRollouts` still selects 500 files by default in descending modification-time order, every selected file is read on every poll, the optional age and project-directory filters are unchanged, and duplicate session IDs retain final-upsert-wins behavior in discovery order. The poller keeps its existing 30-day age window.
+
+Worker timeout, error, unexpected-exit, shutdown termination, and overlapping-poll guards prevent a stuck or duplicate scan. The main thread applies compact parsed results with the legacy per-file SQLite upserts.
+
+`instar join` installs a standby's LaunchAgent with `server start` (its scaffolded config has no Telegram, and the lifeline needs one), and nothing revisited that once Telegram was configured; join's closing text also told the operator to `instar server start` a second, unsupervised server (instar#2122, Luna/sagemind).
+
+- Server boot's auto-start self-heal (macOS) now regenerates the LaunchAgent with the lifeline when Telegram is configured but the plist starts the bare server (`autoStartNeedsLifeline` in `src/commands/setup.ts`).
+- `instar join` no longer suggests starting a server when auto-start was installed.
+
+`instar join` used any existing `.instar/machine/identity.json`, so a second machine set up from a copied agent home claimed the first machine's id (ACT-1302, Luna/sagemind's Studio booted as the laptop).
+
+- `POST /api/pair` refuses `409 joiner-identity-is-inviter` when the joiner presents the inviter's own machine id, before the pairing code is checked (no attempt spent, no state change).
+- `instar join`: an identity whose private signing key is not on this machine is first offered to boot identity recovery (keychain-authenticated key rebuild keeps the id). If recovery does not restore it, the identity and key files (current and legacy names) are renamed `*.copied-<timestamp>` and a fresh standby identity is minted. On the inviter's 409 the joiner does the same and retries once.
+
+Fixes instar#2120. When the quota read from Anthropic fails, `QuotaCollector` estimates usage from the last 7 days of Claude JSONL transcripts. It read each file whole and parsed every line synchronously on the event loop; on ~1.8 GB of transcripts the server stopped answering for 3-20 s every 1-2.5 minutes.
+
+- `JsonlParser.parseFileAsync` streams each file line by line; `collectFromJsonl` is async and yields between files.
+- `JsonlParser.accumulateLine` holds the per-line rule for both the sync and streamed paths, so they count identically.
+- Lines without `assistant` are skipped before `JSON.parse`; every counted entry contains it, so totals are unchanged.
+
+Fixes the blocker in instar#2122, found while bringing Luna up on a second machine.
+
+- **Copied Claude path** (`src/core/Config.ts` → `resolveConfiguredClaudePath`). `sessions.claudePath` that provably does not exist on this machine is replaced by the detected Claude binary, with a warning naming both paths; with none detected the configured value is kept. Previously it was used verbatim, every Claude session died at spawn, and each death revoked the session's Telegram sending credential (`invalid-origin-token`). An existing path, a bare command name, or an unprobeable path is kept as configured — the rule `sessions.frameworkBinaryPaths` already follows.
+- **Half-revoked machine entries** (`src/core/MachineIdentity.ts` → `isRegistryEntryActive`). A registry entry is active only with `status: 'active'` and no `revokedAt`. Used by the active-machine list, awake lookup, nickname lookup, `instar machine` views, the passkey cell-state check and the origin pool audit. A removed identity whose endpoints were this machine's own no longer receives this machine's cross-machine calls (`wrong-recipient`).
+
+The server's SIGTERM/SIGINT teardown awaited ~10 subsystem stops with no overall bound, so one hang kept the process alive until SIGKILL (instar#2122: Luna's Studio standby ignored SIGTERM).
+
+- `src/core/shutdownDeadline.ts`: `armShutdownDeadline` arms an unref'd timer at teardown start (default 20 s; `INSTAR_SHUTDOWN_DEADLINE_MS` override, floor 2 s); on expiry it logs the step in flight, closes SQLite handles, releases the single-instance lock and exits 1.
+- A second signal during teardown exits at once with the same cleanup.
+- The awaited steps are labelled in the log (`telegram-origin`, `notification-flush`, `tunnel`, `threadline`, `telegram`, `http-server`, `sqlite`).
+
+Builds the legacy single-file migration named in the approved spec `subscription-pool-authority-foundation.md` (operation `legacy-migrate`), prompted by instar#2122 (a joined machine inherited the first machine's login locations through the git-shared `.instar/subscription-pool.json`).
+
+- `SubscriptionPoolAuthorityStore.migrateLegacy` + `recoverLegacyMigrate`: witness bound to the untouched source's SHA-256+size; staging, finalize, rebuild-from-matching-source, fail-closed recovery per the spec table.
+- `SubscriptionPool.migrateLegacyToMachineLocal`: drops rows whose login home is not on this machine; `persist()` writes to the authority once one is published, even with a legacy file still present.
+- `PostUpdateMigrator.migrateSubscriptionPoolToMachineLocal`: `.gitignore` entry, one-time publication, legacy file removed only when untracked (a tracked copy stays — deleting it would propagate to peers). `GITIGNORE_ENTRIES` gains `.instar/subscription-pool.json`.
+
+The relay admits one connection per agent identity, so two machines of one agent displaced each other (instar#2122). `bootstrapThreadline` gains `relayStandby`; `server.ts` passes `!shouldOwnTelegramPoll(config)` — the per-machine `multiMachine.telegramPolling: false` flag the lifeline already uses. A standby logs `relay connection SUPPRESSED (standby: …)` and keeps local Threadline. CLAUDE.md template + migration gain one awareness bullet.
+
+`POST /threadline/relay-send` (relay path) recorded `threadId ?? messageId` when the caller passed no thread, while `ThreadlineClient` put its own affinity/minted `thread-…` id on the wire. The outbox, thread log, bridge mirror, delivery tracker, reply waiter and the origin-topic binding were all keyed on the `msg-…` id, so the peer's reply on `thread-…` matched nothing and cold-spawned — refused at a full session cap and held (ACT-1304 fault 3, reported by Luna/sagemind).
+
+- New `ThreadlineClient.sendAutoWithThread()` returns `{ messageId, threadId }` with the id that went on the wire.
+- The relay-send route uses it for every record and for its response; `threadline_send` now returns the real conversation id.
+
+`wakeup()` named the awake machine from the registry's lagging role field and posted the handoff challenge to its OWN server, which verified the signature with itself as receiver and answered `Invalid challenge signature` (instar#2122).
+
+- `resolveAwakeMachine`: live lease holder from the local server's `/health` (`multiMachine.syncStatus.leaseHolder`, active non-revoked entry), else the registry role.
+- `resolveAwakeServerUrl`: probes the awake machine's advertised endpoints + last-known URL with `/health`; never localhost.
+
+## What to Tell Your User
+
+If something I warned you about in the Agent Health topic comes back, I no longer keep retrying the same heads-up in the background every 30 seconds.
+
+If you've connected a second machine, I no longer get locked out of my own controls when I follow my setup notes. The notes now find my access key wherever it's kept.
+
+If you use Codex a lot, I no longer freeze for several seconds every minute or so while counting its usage. The numbers I report are the same.
+
+If you add a second machine, once Telegram is set up there it starts at login the same way as the first machine, with my watchdog keeping the server running. The join steps no longer tell you to start a second copy of the server.
+
+If you set up a second machine by copying my folder from the first, it now creates its own identity instead of pretending to be the first machine. A machine that has only lost its keys still recovers its own identity.
+
+When I can't get my usage numbers straight from Anthropic and have to estimate them from my own logs, I no longer freeze for several seconds while doing it. The estimate itself is the same.
+
+If you add a second machine by copying settings from the first, I no longer go silent on the new machine when my settings name a Claude program that only exists on the old one — I find the right one and note the mismatch. A machine you removed also stays removed, even if an old copy of the machine list still calls it active.
+
+When my server is asked to stop, it now always stops within about 20 seconds, even if one part of it is stuck, and the log says which part. Updates and restarts no longer have to force-kill it.
+
+My list of which Claude or Codex logins live on which machine is now kept separately on each machine. A second machine no longer inherits the first one's login locations, and a login that only exists on the other machine is left off this machine's list. Nothing is deleted on any other machine.
+
+When I run on two machines, only the one in charge connects to the agent network; the other stays quiet instead of knocking it off the relay every few seconds.
+
+When I message another agent and it answers, the answer now comes back to the conversation where I asked, instead of sometimes getting stuck waiting for a free session.
+
+Moving me to another machine with "instar wakeup" now talks to the machine that is really in charge, so the hand-over no longer fails with a signature error.
+
+## Summary of New Capabilities
+
+None — a retry loop is removed.
+
+None — a broken instruction is corrected for new and existing agents.
+
+None — the same token totals, gathered without freezing the server.
+
+None — an auto-start repair and corrected join instructions.
+
+- `/api/pair` names a copied identity (`joiner-identity-is-inviter`) instead of accepting it.
+
+None — the same estimate, without the freeze.
+
+- A copied `sessions.claudePath` that is missing on this machine falls back to the detected Claude program, with a boot warning.
+- A machine-list entry carrying a removal date is always treated as removed.
+
+- `INSTAR_SHUTDOWN_DEADLINE_MS` sets the teardown bound.
+
+None user-visible — the per-machine store the spec already promised is now populated automatically on update.
+
+None — a connection gate on an existing flag.
+
+- `threadline_send` returns the real conversation id on relay sends, so `threadline_history` on it works.
+
+None — a CLI fix.
+
+## Evidence
+
+`tests/unit/attention-single-topic-routing.test.ts`: a `duplicate-content` hold on reopen resolves with the item OPEN; an `origin-display-authority-unavailable` hold still rejects. The new test fails on main and passes with the fix; all 21 tests pass.
+
+- `tests/unit/auth-read-after-secret-migration.test.ts`: the generated instruction resolves a plain string token, never emits the `{ secret: true }` placeholder (the old line does), and the migration rewrites an existing CLAUDE.md once.
+- Live on this machine with no session env: a vault-externalized agent and a plain-config agent both get `200` from `/jobs` using the new lines; the old read gave `400`.
+- 40 template/migration test files pass; the secret-externalization lint stays green.
+
+`TokenLedgerPoller-codex.test.ts` covers responsiveness, repeated full reads, preserved-mtime rewrites, legacy duplicate-session ordering, the 500-file default, worker timeout/error/exit/close, and overlapping polls. The focused Vitest suites and TypeScript build validate the change.
+
+- `tests/unit/autostart-needs-lifeline.test.ts`: server plist + Telegram configured → switch; lifeline plist → leave; server plist without Telegram → leave.
+- The predicate matches the real LaunchAgent format on this machine (`<string>lifeline</string>` in the ProgramArguments of Echo's and Luna's plists).
+
+- `tests/e2e/multi-machine-http.test.ts`: on the real server path, the inviter's own id is refused with 409 and the code is not spent.
+- `tests/integration/pool-noninteractive-pairing.test.ts`: the inviter's own id is refused with 409, the code is not spent, the registry is unchanged; all 8 pass.
+- `tests/unit/join-copied-identity.test.ts`: a copied identity is set aside (renamed, kept) including legacy key names, and a fresh identity with a different id is minted.
+- Independent second-pass review: two concerns raised and fixed (see `upgrades/side-effects/join-refuses-copied-identity.md`).
+
+- `tests/unit/quota-collector.test.ts`: streamed and sync parsing return identical totals on mixed input (CRLF, malformed, out-of-window, non-assistant, missing timestamp); a 20 MB file lets a 1 ms timer fire during the read; all 56 tests pass.
+- Original CPU profiles (in instar#2120) attribute the stalls to `collectFromJsonl` → `parseFile` → `readFileSync`.
+
+- Luna's Mac Studio log: 34 sessions "died during startup" while `sessions.claudePath` was `/opt/homebrew/bin/claude` (absent on the Studio); none after it was corrected by hand. Continuous `[mesh-rpc] rejected telegram-origin from <self>: wrong-recipient` from a registry entry with `revokedAt` set and `status: 'active'`.
+- `tests/unit/second-machine-copied-config.test.ts` (8 tests), `tests/unit/Config.test.ts`, `tests/unit/machine-identity.test.ts` and 165 related unit files pass.
+
+`tests/unit/shutdown-deadline.test.ts`: the deadline fires with the in-flight step name at exactly the bound, a cancelled timer never fires and is unref'd, and the env override/floor/default resolve as documented.
+
+- `tests/unit/subscription-pool-legacy-migrate.test.ts` (7): publish + witness binding + legacy removal; tracked copy kept; refusals; recovery (finalize, rebuild from matching source, fail closed on a mutated source); pool-level drop/keep and persist-to-authority.
+- `tests/unit/PostUpdateMigrator-subscription-pool-machine-local.test.ts` (3): tracked / untracked / no-repo; idempotent.
+- `tests/e2e/subscription-pool-lifecycle.test.ts`: production update path + server boot serve only this machine's logins.
+- 166 related unit files pass.
+
+`tests/unit/threadline/ThreadlineBootstrap.test.ts`: with the relay enabled and `relayStandby: true`, no relay client is created, the suppression line is logged, and local components still bootstrap. 148 template/migrator test files pass.
+
+- `tests/unit/ThreadlineClient-wire-thread.test.ts`: plaintext and encrypted paths return the wire thread (not the message id); affinity reuse and explicit ids preserved.
+- Relay-send integration suites (nickname, priority, canonical remote agent, negotiator gate, local roundtrip) pass; 141 Threadline unit files (2,335 tests) pass.
+
+`tests/unit/wakeup-targets-awake-machine.test.ts` (5): live lease wins over the registry; registry fallback; a revoked/unknown lease holder is ignored; endpoint probing picks the first rope that answers and never localhost; null when none answer.

package/upgrades/luna-stack-ci-ratchets.eli16.md

@@ -0,0 +1,9 @@
+# Combined Luna fixes: two CI checks made green (ELI16)
+
+The combined submission of Luna's multi-machine fixes failed two automatic checks on GitHub.
+
+1. **The "no silent fallbacks" counter.** The repository counts every place where an error is caught and quietly ignored, and refuses any change that raises the count. Three new error handlers in the login-list migration ignore errors on purpose: a machine that has no identity yet, a migration record that does not exist, and a legacy file that cannot be read. Each of these is a normal, expected state, and each already falls back in the safe direction. They now carry the required explanatory note inside the handler, so the counter is back at its baseline. No behavior changes.
+
+2. **Documentation coverage.** The repository requires a minimum share of its code classes to be mentioned in the public docs. A new background worker that scans Codex usage files had no mention, which pushed the share just below the floor. The token-ledger section of the observability docs page now names the Codex rollout parser and the worker and says what they do.
+
+Nothing about how the agent runs changes; these are comments and documentation only.

package/upgrades/side-effects/agent-health-reopen-duplicate.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — a reopened agent-health notice held as a duplicate counts as delivered
+
+**Version / slug:** `agent-health-reopen-duplicate`
+**Date:** `2026-10-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (narrow error classification on one notice path)`
+
+## Summary of the change
+
+ACT-1304 fault 2 (reported by Luna/sagemind). Luna's laptop log, 2026-10-04 12:05-12:18Z: `Threadline.SpawnDrainAttention: Attention write failed: Telegram message held: duplicate-content`, every 30 s for 13+ minutes. The spawn drain's give-up handler calls `TelegramAdapter.createOrReopenAgentHealthAttentionItem`; once the item exists, each call reposts a fixed "returned after recovery" line to the Agent Health topic. The outbound dedup held each repost as a duplicate of the copy already accepted in that topic, the adapter rethrew the hold, and the spawn manager treated it as a failed Attention write and retried. Now a `TelegramOriginHoldError` with reason `duplicate-content` on that reopen post is treated as delivered; every other hold still throws so the caller retries as before.
+
+## Decision-point inventory
+
+None added. The dedup gate's decision is unchanged; this changes how one caller interprets "already delivered".
+
+## 1. Over-block
+
+Nothing new is refused.
+
+## 2. Under-block
+
+`duplicate-content` is returned only when the same text to the same topic was platform-accepted within the dedup window (`OriginContentDedup` returns `content-reservation-pending` for an in-flight copy, which still throws), so the operator has the notice. Other holds (for example `origin-display-authority-unavailable`) still fail and retry.
+
+## 3. Level-of-abstraction fit
+
+The adapter owns this send and knows the hold reason; the spawn manager stays generic.
+
+## 4. Signal vs authority compliance
+
+No authority added; the dedup gate keeps its authority.
+
+## 4b. Judgment-point check
+
+Not a decision point.
+
+## 5. Interactions
+
+Ends the 30 s retry loop and its degradation-log noise. The first-creation path already swallowed send errors. Other `sendToTopic` callers are untouched.
+
+## 6. External surfaces
+
+No new message is sent; a duplicate stays suppressed.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local; the Agent Health lane and the dedup are per machine.
+
+## 8. Rollback cost
+
+Revert; no state change.
+
+## Conclusion
+
+A one-branch error classification that stops a retry loop on a notice the operator already has.
+
+## Class-Closure Declaration (display-only mirror)
+
+`{defectClass: "unbounded-self-action", closure: "n/a", reason: "Adds no self-triggered action: it classifies a duplicate-content hold on one notice as already delivered, which REMOVES the trigger for the callers 30s retry loop. Other holds still throw, bounded by the spawn drain existing give-up latch."}`

package/upgrades/side-effects/auth-read-after-secret-migration.md

@@ -0,0 +1,56 @@
+# Side-Effects Review — the CLAUDE.md API-auth instruction survives secret externalization
+
+**Version / slug:** `auth-read-after-secret-migration`
+**Date:** `2026-10-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (instruction text + idempotent CLAUDE.md migration)`
+
+## Summary of the change
+
+ACT-1303 (reported by Luna/sagemind on Threadline, 2026-10-03): "instar pair moving secrets to {secret:true} breaks scripts that read them." After `SecretMigrator` externalizes `authToken`, `.instar/config.json` holds `{ "secret": true }`. Instar's shipped hooks and scripts were already migrated to read `$INSTAR_AUTH_TOKEN` first with a string-type guard, but the CLAUDE.md template's "API Authentication" section still told every agent to run `AUTH=$(python3 -c "...get('authToken',''))")`, which prints the placeholder object. Every curl an agent built from it was rejected (reproduced in this session: `400` with the config read, `200` with the env token).
+
+The template (both occurrences in `generateClaudeMd`) now reads `$INSTAR_AUTH_TOKEN`, then `node .instar/scripts/secret-get.mjs authToken`, then the config only when the value is a string. `PostUpdateMigrator.migrateClaudeMd` rewrites the old line in existing agents' CLAUDE.md (content-sniffed, idempotent).
+
+## Decision-point inventory
+
+None. Instruction text and a text migration.
+
+## 1. Over-block
+
+Nothing is refused.
+
+## 2. Under-block
+
+Agent-authored custom scripts that copied the old one-liner are not rewritten (custom files are never touched); the corrected CLAUDE.md instruction is what agents copy from going forward.
+
+## 3. Level-of-abstraction fit
+
+CLAUDE.md is where agents learn this; the migration path is the documented one for CLAUDE.md sections.
+
+## 4. Signal vs authority compliance
+
+No authority involved.
+
+## 4b. Judgment-point check
+
+Not a decision point.
+
+## 5. Interactions
+
+Matches the env-first, string-guarded pattern Instar's hooks already use. The secret-externalization lint over `PostUpdateMigrator.ts` stays green: the old line is assembled from pieces because it is the text being removed.
+
+## 6. External surfaces
+
+CLAUDE.md text for new and updated agents. Verified live: on a vault-externalized agent and on a plain-config agent, with no session env, the new lines produce a token the server accepts (`200`).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Each machine's CLAUDE.md is migrated on its own update; the instruction resolves per machine (session env / local secret store / local config).
+
+## 8. Rollback cost
+
+Revert; the migration only rewrites one known line.
+
+## Conclusion
+
+Closes the last place Instar itself told agents to read a secret that pairing had moved.

package/upgrades/side-effects/codex-rollout-scan-yield.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — Codex rollout scan runs on a worker thread
+
+**Version / slug:** `codex-rollout-scan-yield`
+**Date:** `2026-10-05`
+**Author:** `Luna (sagemind) drafted; echo completed`
+**Second-pass reviewer:** `independent subagent (see below)`
+
+## Summary of the change
+
+instar#2121. `TokenLedger.scanCodexRolloutsAsync` read and parsed up to 500 Codex rollout files synchronously on the server event loop; on a 14 GB / ~54k-file store that blocked the server 8-12 s about once a minute (a CPU profile put ~84% of frozen time here). Discovery, reads and parsing now run in `src/monitoring/CodexRolloutScan.worker.ts`; the main thread only applies the legacy per-file SQLite upserts in the worker's discovery order. Same `listAllRollouts` selection (500, descending mtime), same age cutoff and cwd attribution, same latest-upsert-wins behavior, no cache.
+
+## Decision-point inventory
+
+None. Observability-only scan (read-only over Codex files, writes only the token ledger).
+
+## 1. Over-block
+
+Nothing is refused. An overlapping poll while a scan runs reports zero and starts no second worker; the next poll scans normally.
+
+## 2. Under-block
+
+SQLite upserts stay synchronous on the main thread and can pause behind a competing writer; the rows are small. Selected files are still reread every poll, as before.
+
+## 3. Level-of-abstraction fit
+
+The fix sits at the one place that did the blocking work. The poller and its cadence are unchanged.
+
+## 4. Signal vs authority compliance
+
+No authority. Token observability never gates anything.
+
+## 4b. Judgment-point check
+
+Not a decision point.
+
+## 5. Interactions
+
+A worker error, unexpected exit or 120 s timeout now rejects the scan (logged by the poller's `onError`) where an in-process failure returned zeros; a later poll retries. `close()` terminates an active worker; `finally` resets the running flag. No heap cap on the worker, so one large rollout cannot fail the whole scan (the in-process scan had the main heap). Starting a worker per poll costs roughly 30-50 ms and ~10 MB briefly.
+
+## 6. External surfaces
+
+None visible. `/tokens/*` returns the same totals.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design: each machine scans its own Codex store into its own ledger.
+
+## 8. Rollback cost
+
+Revert the commit; no schema or data change.
+
+## Conclusion
+
+A relocation of existing work off the event loop with parity preserved, covered by ordering, re-read, timeout, overlap, failure, shutdown and responsiveness tests.
+
+## Second-pass review (if required)
+
+Two passes on Luna's draft (astra) found three parity breaks (a size/mtime skip cache, changed processing order, batching/limit changes); all were removed. Independent subagent review on the final diff, 2026-10-05: promise settling, close-during-scan, data copy (`ParsedCodexSession` is strings/numbers/nulls) and parity all check out. **Concern raised:** the 512 MB worker heap cap let one oversized rollout fail every file in the scan. Resolved by removing the cap. A second note — the `src`-run fallback to `dist/` could test a stale worker — is covered by `tests/setup/build-dist.globalSetup.ts`, which rebuilds `dist` before every vitest run. Concur after the fix.

package/upgrades/side-effects/jev-review-flag-shadow.md

@@ -0,0 +1,175 @@
+# Side-Effects Review — Jev review-flag shadow (log-only "does this reply need review?" measurement)
+
+**Version / slug:** `jev-review-flag-shadow`
+**Date:** `2026-10-05`
+**Author:** `echo`
+**Second-pass reviewer:** `independent review subagent + codex-cli gpt-5.5 (one 80/20 round on the spec)`
+
+## Summary of the change
+
+A dark, log-only research instrument (spec `docs/specs/jev-review-flag-shadow.md`).
+A 60-second unref'd server timer reads the last 512 KB of the agent's own
+Telegram history, selects each agent conversational reply (provenance
+`agent`, at most 30 minutes old, newer than its topic's watermark), pairs it
+with the operator message it answers (same topic, earlier, within 6 hours),
+secret-scrubs both before cutting them (reply 2,000, request 600 characters,
+cuts disclosed in band), asks Jev (`jev-1.13.0`) one three-label question
+(`needs_review` / `fine` / `cannot_tell`) in both option orders, and appends a
+content-free row to `logs/jev-review-flag-shadow.jsonl`.
+`GET /jev-review-flag/summary` reads the log. Files:
+`src/core/JevReviewFlagShadow.ts` (new), `src/server/routes.ts` (one read
+route), `src/commands/server.ts` (construction + start),
+`src/config/ConfigDefaults.ts`, `src/core/types.ts`,
+`src/core/devGatedFeatures.ts`, `src/scaffold/templates.ts` +
+`src/core/PostUpdateMigrator.ts` (awareness card, both paths),
+`src/server/CapabilityIndex.ts` (internal prefix).
+
+## Decision-point inventory
+
+No decision-point surface. Nothing is blocked, allowed, filtered, delivered or
+routed. No code path reads the log except the summary route, which a person
+reads.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. Measurement blind spots,
+named in the spec: Slack replies (not in this history); desk messages sent
+through the operator's account can be picked as the request; replies logged
+more than 30 minutes before the timer sees them (only possible if the server
+was down) are not judged.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Right layer. The operator corrects what reaches Telegram, and the server
+already keeps that history; reading it server-side needs no hook, no settings
+migration and no per-framework work. It reuses `readJsonlTailLines`,
+`scrubForStore`, `resolveDevAgentGate` and the feature-metrics recorder, and
+follows the jev-circles-shadow shape (vault key, closed reason enums, daily
+cap seeded from the log). It does not feed a gate: the point is to measure
+before anything is shown.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+It produces a logged signal that nothing consumes. It holds no authority.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The 0.5
+threshold only labels rows in a research log; both orders' probabilities are
+kept so the threshold can be moved after the fact. No action follows.
+
+---
+
+## 5. Interactions
+
+- **Shadowing / double-fire:** none. It reads the Telegram history (append-only,
+  written by TelegramAdapter) and writes only its own log. The other Jev
+  shadows have separate logs, feature names and daily bounds.
+- **Event loop:** one synchronous bounded read of at most 512 KB per minute
+  (the same helper the 2026-06-22 event-loop fixes introduced), off every
+  request path; nothing when disabled. Calls are sequential, so at most one is
+  in flight.
+- **Races:** a reply logged after a tick is seen at the next tick. Ticks never
+  overlap (a `running` latch). Watermarks advance only past replies that were
+  judged or failed at the vendor/scrub, so the daily cap never drops an
+  eligible reply silently; seeding from the log at start means a restart
+  judges nothing twice.
+- **Feedback loops:** none. It never sends, so it never adds to the history it
+  reads.
+
+---
+
+## 6. External surfaces
+
+- **Other agents:** fleet agents get the code and the config block; the
+  feature stays dark (dev gate) and they hold no TypeSafe key.
+- **External systems:** on the development agent, a scrubbed reply (≤2,000
+  characters) and request (≤600) go to TypeSafe (`api.typesafe.ai`), the
+  vendor the other Jev shadows already use. Bounded by the daily cap (default
+  3000 calls ≈ $0.45/day worst case; ~$0.05/day expected), one call at a time,
+  and a 1.5 s abort.
+- **Persistent state:** one append-only JSONL log (~300 bytes/row, a few
+  hundred rows/day); the summary reads only the last 5 MB.
+- **Operator surface:** none. The read route is informational (Bearer).
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local BY DESIGN: each machine judges the replies its own Telegram
+history holds (the sends relayed through it), and the measurement is a rate
+that per-machine logs answer; scoring joins each machine's log to the same
+machine's history by message id. No notices, no topic-following state, no
+generated URLs.
+
+---
+
+## 8. Rollback cost
+
+Pure code change. Kill switch: `intelligence.jevReviewFlagShadow.enabled:
+false` (read live at the next tick, no restart). Full back-out: revert and
+ship a patch; the log file can be left or deleted. No user-visible effect in
+either direction.
+
+---
+
+## Conclusion
+
+Clear to ship behind the dev gate. The review round moved the trigger from
+the Stop hook to a server-side tail of the Telegram history, which removed a
+hook change, a reply-logging race, a session-name mismatch and the
+Claude-only limit; the remaining findings were local and are tested.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent review subagent + codex-cli gpt-5.5 (one 80/20 round, 2026-10-05)
+**Independent read: concur, after the trigger change and local fixes above**
+
+Full record: `docs/specs/reports/jev-review-flag-shadow-convergence.md`.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/jev-review-flag-shadow.test.ts`, `tests/integration/jev-review-flag-shadow-routes.test.ts`, `tests/e2e/jev-review-flag-shadow-lifecycle.test.ts`.
+- Live smoke through the real module, real history and real vendor
+  (2026-10-05): 4 replies judged, 89–169 ms, all `fine`, both orders agreeing;
+  no message text in the log.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable. Not a self-triggered
+controller in the `unbounded-self-action` sense: it never fires a restart,
+retry, respawn, spawn, notify or kill; its only action is one bounded, capped
+vendor call and a log row per agent reply.

package/upgrades/side-effects/join-autostart-lifeline.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — a joined machine ends up supervised by the lifeline, like the first
+
+**Version / slug:** `join-autostart-lifeline`
+**Date:** `2026-10-05`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (auto-start self-heal extends an existing check; join output text)`
+
+## Summary of the change
+
+instar#2122 (Luna/sagemind second-machine bring-up): "`instar join` installed a `server start` LaunchAgent instead of `lifeline start` (unlike the first machine and Echo's Studio), and it started a stray server outside the supervisor."
+
+`instar join` scaffolds a machine-local config with `messaging: []` (the Telegram token is machine-local), so `installAutoStart` correctly picks `server start` at join time — the lifeline refuses to run without Telegram config. Nothing ever revisited that once Telegram was configured on the standby. And join's closing text told the operator to run `instar server start`, though auto-start had already launched one, producing a second, unsupervised server.
+
+1. Server boot's existing auto-start self-heal (which already regenerates stale plist formats) now also regenerates the LaunchAgent with the lifeline when Telegram is configured but the plist starts the bare server (`autoStartNeedsLifeline` in `setup.ts`).
+2. `instar join` no longer tells the operator to start a server when auto-start was installed.
+
+## Decision-point inventory
+
+One added condition in the boot self-heal: "Telegram configured AND plist lacks `lifeline`" → reinstall.
+
+## 1. Over-block
+
+Nothing is refused. An agent with Telegram configured that deliberately runs a server-only LaunchAgent is switched to the lifeline — the same outcome the self-heal already produces whenever it reinstalls for any other reason (it passes the Telegram flag).
+
+## 2. Under-block
+
+macOS only (the plist check lives in the darwin branch, like the existing format checks). Linux systemd units are unchanged. The standby lifeline's own Telegram-polling behaviour is unchanged (it already suppresses polling under `multiMachine.telegramPolling: false`).
+
+## 3. Level-of-abstraction fit
+
+Extends the one place that already repairs auto-start drift at boot.
+
+## 4. Signal vs authority compliance
+
+No new authority over agent behaviour; an install-time repair.
+
+## 4b. Judgment-point check
+
+Not a competing-signals decision.
+
+## 5. Interactions
+
+Reinstalling reloads the LaunchAgent, which restarts the server once under the lifeline — the same one-time restart the existing format self-heals cause. On the next boot the plist matches and nothing further happens.
+
+## 6. External surfaces
+
+One boot log line when it switches; `instar join` closing text.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design: each machine's LaunchAgent is its own.
+
+## 8. Rollback cost
+
+Revert; a switched plist keeps running the lifeline, which is the intended state.
+
+## Conclusion
+
+A joined standby converges on the same supervision as the first machine once it can, and join stops inviting a duplicate server.