instar 1.3.269 → 1.3.271

package/upgrades/1.3.270.md

@@ -0,0 +1,106 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Implemented Phase 2 of the approved Approval-as-Data design: the **approval ledger**.
+Every operator approval is now recorded as durable, signed data — classified as
+approved-as-is, approved-with-change (with the reason for each change), or rejected — and
+the system computes a per-class agreement ratio and streak from those records. The ledger
+tracks approvals wherever they occur: an official spec sign-off, a decision approved in
+chat, or any other surface. New endpoints record a decision, list the records, and return
+the agreement summary with a breakdown by surface. The ledger is signed, append-only, and
+read-only with respect to all other behavior — it never gates, blocks, or changes anything.
+The authoritative source of whether an approval was as-is or changed is always the
+operator; the agent never self-classifies intent, and any record is operator-correctable.
+
+Implemented the Coordination Mandate enforcement engine (the design the operator
+signed off as A/A/B): a deny-by-default authority gate for autonomous agent-to-agent
+actions. The operator writes one bounded, expiring, revocable "permission slip"
+delegating specific authorities to a specific pair of agents; the slip — not the agent
+— is what authorizes each action, preserving the rule that the one asking is never the
+one authorizing. Issuance and revocation require the operator's dashboard PIN, so an
+agent's API access alone is structurally unable to create or widen a mandate. A signed
+store verifies authorship on every check (a forged or edited mandate fails), risky
+authorities can be tied to objective real-state conditions the agent cannot fake, and
+every decision — allowed and denied alike — lands in a tamper-evident, hash-chained
+audit log. With no mandate issued, the gate denies everything, so this ships inert and
+changes no behavior until the operator issues the first mandate.
+
+Added the Phase-3 invariant-parity monitor for the feedback-factory migration: a
+windowing layer over parity results that computes the objective
+parity-zero-divergence condition (a sustained run of clean passes over a minimum
+real-traffic window) which the future cutover step reads as its go signal. Includes
+a durable, restart-surviving variant (append-only pass journal, torn-line tolerant).
+Internal migration tooling — not yet wired to any live behavior.
+
+Added the Phase-4 data-migration integrity tooling for the feedback-factory
+migration: import-as-is preservation of every curated field, per-row checksums
+(in vs out), fingerprint-uniqueness scanning, auto-increment sequence reset,
+schema-equivalence assertion, and the structural never-re-derive guard (the
+processor refuses to mutate any cluster created before the cutover timestamp or
+carrying governance notes). Internal migration tooling — not yet wired to any
+live behavior.
+
+SessionManager now samples the live tmux pane cwd for enabled development-agent sessions and stores it in a crash-safe sidecar. Resume spawns prepend a restore note only for fresh, existing `.worktrees` paths; home-only sessions remain a no-op.
+
+## What to Tell Your User
+
+Your agent now remembers your approvals instead of forgetting them the moment they happen.
+Each time you approve something — a full spec, or just a choice you make in chat — it can
+record whether you took its recommendation as-is or changed it, and why. Over time this
+builds a simple picture of where the agent already proposes what you would have picked, and
+where it still needs to close the gap. You stay the source of truth: the agent only records
+what you explicitly say, and you can correct any entry. This is an internal, read-only
+record — it never changes what the agent does, it just helps it learn your preferences.
+
+You can now hand your agent a bounded permission slip instead of approving every step
+of a multi-agent project. You write the slip once from your dashboard with your PIN:
+exactly which actions are allowed, within which limits, for which two agents, until
+when. Your agent can act inside those lines without pinging you, and nothing outside
+them — and you can tear the slip up at any moment. Everything done under a slip is
+written to a tamper-evident log you can review. Until you issue a slip, nothing changes
+at all: the system refuses every delegated action by default.
+
+Nothing changes for you. This is internal plumbing for the feedback-system handover:
+a safety meter that has to read "clean for a sustained window" before the one-way
+switch can ever be considered. It ships dormant.
+
+Nothing changes for you. This is internal plumbing for the feedback-system
+handover: the checks that guarantee curated history is copied perfectly and can
+never be silently rewritten afterward. It ships dormant.
+
+Developer-agent respawns can now re-surface the worktree checkout they were building in before the restart. Normal home-only conversations are unchanged.
+
+## Summary of New Capabilities
+
+- Record an approval decision through the new approvals endpoint, tagged as approved-as-is,
+  approved-with-change, or rejected, with the reason for any change.
+- Read a per-class agreement summary (total, approved-as-is count, ratio, streak, and a
+  breakdown by where the approval happened) plus a list of recorded decisions.
+- Maturity: stable for the recording and summary surface; the later auto-approval pilot
+  remains a separate, operator-gated phase that is not part of this change.
+
+- Issue or revoke a coordination mandate from the dashboard surface with your PIN —
+  agent credentials alone cannot do either.
+- Agents check intended agent-to-agent actions against the mandate and get an
+  allow-or-deny answer with the reason; denials are the default with no mandate.
+- Review every mandate decision in a chained, tamper-evident audit trail, including
+  whether each entry's chain verifies.
+- Maturity: stable for the gate, store, and audit; conditioned authorities (objective
+  real-state gates for riskier actions) ship deny-safe and unused by the first mandate.
+
+- Internal: order-independent parity windowing (per-report fingerprint,
+  terminal-status, recurrence/cycling counts) with a conservative
+  cleared-or-blocked gate verdict; survives restarts.
+- Maturity: internal migration tooling, dormant until the dual-forward phase.
+
+- Internal: integrity-safe import core + a guarded store wrapper that makes
+  pre-cutover and governance-noted clusters structurally immutable.
+- Maturity: internal migration tooling, dormant until the import phase.
+
+- SessionManager can record the live pane working directory for running sessions when the development-agent-gated feature is enabled.
+- A resumed respawn receives a `[BUILD-CONTEXT RESTORE]` continuation note only when the prior cwd was a fresh, existing agent worktree.
+- The sidecar state write is crash-safe through the state layer's temp-file plus rename path.

package/upgrades/1.3.271.md

@@ -0,0 +1,154 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+One additive line in the mentor autoloop prompt (`src/scheduler/MentorAutonomousGuardian.ts`), locked by three new unit-test assertions. Earned from PR #792's no-silent-fallbacks CI failure, where a spec's "best-effort, never throws" wording invited the swallowed catch the ratchet counts.
+
+The dashboard sessions list now shows EVERY session across ALL machines in the
+multi-machine pool, and every session row states which machine it runs on
+(a machine-nickname badge). Sessions on the machine you're viewing stay fully
+interactive (live terminal, close button); sessions on other machines appear
+as informational rows with a tooltip pointing at the owning machine's
+dashboard.
+
+Under the hood: `GET /sessions` self-tags sessions with `machineId` /
+`machineNickname` when the pool is wired, and a new `GET /sessions?scope=pool`
+aggregates every reachable peer's session list (existing cross-machine Bearer
+auth, 5s timeout per peer). A dead or slow peer degrades to a `pool.failed`
+entry — the page never breaks. The plain `/sessions` route keeps its
+back-compatible array shape.
+
+Added the ReviewExchange protocol — the structured way two mandate-named agents complete
+a mutual code-review sign-off without the operator relaying messages between them. One
+exchange tracks one review package (content-addressed by checksum, fixed at creation)
+through a strict linear lifecycle: proposed, delivered, verdict recorded, complete — or
+changes-requested, which is terminal so a stale approval can never be replayed onto
+reworked code. Both sign-offs — the reviewing peer's authenticated approval and the
+owner's countersignature — are checked against the operator's coordination mandate
+before acceptance, and every accepted signature stores the audit reference of the gate
+decision that authorized it. With no mandate issued, every sign-off refuses: the
+protocol inherits deny-by-default and ships inert.
+
+A submitted Secret Drop is now persisted store-first to the durable
+AES-256-GCM encrypted SecretStore the instant it is received, instead of
+living only in the server's in-memory `received` map. The retrieve route
+transparently falls back to the durable copy when the in-memory one is gone
+(server restart, compaction, cross-machine handoff), and a successful consume
+deletes both copies — one-time semantics are preserved. Opt out with
+`secrets.persistDrops: false` in `.instar/config.json`.
+
+This closes the recurring "the user dropped a secret and the agent lost it"
+failure: with the fleet shipping many releases a day, every release restarted
+the server and evaporated any un-consumed submission.
+
+Also: the SecretStore master-key manager now forces file-key mode during test
+runs (`VITEST` / `NODE_ENV=test`). The OS keychain entry is machine-global —
+a test constructing a SecretStore against a fresh stateDir used to generate a
+new master key and silently overwrite that shared entry, making every real
+agent vault on the machine undecryptable for keychain-resolving readers. No
+test can touch the real keychain anymore. A `secrets.forceFileKey` config
+plumb is also available for operators who want to pin the key source.
+
+The CLAUDE.md template's Secret Drop "Security" bullet is rewritten (the old
+"in-memory only, never written to disk" claim is no longer true), and an
+idempotent migration updates existing agents' CLAUDE.md in place.
+
+Two fixes for the 2026-06-05 "move this to the laptop" noise incident, where
+one user message produced contradictory "Moving to Laptop" / "I can't move
+this right now (rate-limited)" replies and executed multiple times.
+
+1. **Idempotent topic transfer.** The transfer planner now recognizes a move
+   request targeting the machine the topic is already on — or already pinned
+   to — BEFORE the rate limit. Duplicates of an already-satisfied move answer
+   "This conversation is already running on X — nothing to move" instead of a
+   rate-limit rejection. The rate limit keeps its real job: damping rapid
+   flip-flops between DIFFERENT machines.
+
+2. **Exactly-once ingress turns on with the pool.** The exactly-once inbound
+   message gate (the dedupe ledger that stops retried/replayed messages from
+   re-executing commands) shipped default-OFF — even on machines whose
+   multi-machine session pool was live. The default is now stage-aware: a pool
+   at `live-transfer` or `rebalance` gets `exactlyOnceIngress` ON
+   automatically. An explicit `multiMachine.exactlyOnceIngress: false` still
+   wins.
+
+## What to Tell Your User
+
+Nothing user-visible. The autonomous mentor loop's instructions now include how to satisfy the repo's ratchet CI gates, so mentor-driven fixes stop tripping no-silent-fallbacks.
+
+Open the dashboard on any of your machines and you'll see all your sessions in
+one list — each with a badge saying which machine it's running on. No more
+opening one dashboard per machine to find a session.
+
+Your agent can now run a real code review with a partner agent under the permission
+slip you issue — no more relaying review messages between them yourself. The agents
+deliver the code package, record the reviewer's verdict, and counter-sign, and every
+step is checked against your permission slip and written to the same tamper-evident
+log. If you revoke the slip mid-review, the review stops on the spot. Until you issue
+a slip, nothing changes — every review step refuses by default.
+
+If you hand me a secret through a drop link, it now survives my server
+restarting, updating, or the conversation moving between machines. You should
+never have to re-send a secret because "I lost it" again. Secrets are stored
+encrypted and are deleted as soon as they're consumed.
+
+Asking me to move a conversation to a machine it's already on (or repeating
+the request) now gets a calm "already running there" instead of a confusing
+"rate-limited" error. And if my internals retry a message under load, the
+command runs once — not four times.
+
+## Summary of New Capabilities
+
+- `buildAutoloopGoal` includes a gate-compliance paragraph: intentional fail-open catches must report via DegradationReporter or carry an inline `@silent-fallback-ok` justification — never a ratchet baseline bump.
+- The mentor is instructed to spell out these gate notes in any task brief or spec it authors for another agent.
+
+- Dashboard sessions list shows every session across the pool with a machine badge per row.
+- `GET /sessions?scope=pool` → `{ sessions, pool: { peersOk, failed, ... } }` (agents can answer "what's running across my machines?").
+- `GET /sessions` sessions carry `machineId`/`machineNickname` on pooled installs.
+- CLAUDE.md template bullet + idempotent migration so existing agents learn the capability.
+
+- Create a review exchange for an artifact under a mandate, content-addressed so the
+  signatures bind to exactly the code that was reviewed.
+- Record delivery, the peer's authenticated verdict, and the owner's countersignature —
+  with both sign-offs evaluated through the mandate gate and refused on any deny.
+- Inspect exchanges and their signatures, each carrying the audit reference of the
+  gate decision that authorized it.
+- Maturity: stable engine and routes; ships inert (deny-by-default) until the operator
+  issues a mandate with the sign-code-review authority.
+
+- Secret Drop submissions persist store-first to the encrypted SecretStore and survive server churn.
+- Retrieval transparently falls back to the durable copy; consume deletes both copies.
+- `secrets.persistDrops: false` opts out (default ON).
+- Tests can never pollute the machine-global SecretStore keychain entry (structural guard).
+- `secrets.forceFileKey` pins the master-key source to the per-agent file key.
+
+- Duplicate "move to X" requests no-op as "already there" — never "rate-limited."
+- The transfer planner accepts an optional `currentPinOf` hook (pin-aware idempotency).
+- `exactlyOnceIngress` defaults ON whenever the session pool routes real traffic.
+
+## Evidence
+
+Three tiers green: `tests/unit/dashboard-sessionMachineBadge.test.ts` (8),
+`tests/unit/PostUpdateMigrator-poolSessionsVisibility.test.ts` (3),
+`tests/integration/sessions-pool-scope.test.ts` (5 — including a REAL second
+HTTP server as the peer and a dead-peer degradation case), and
+`tests/e2e/sessions-pool-scope-lifecycle.test.ts` (3 — real AgentServer,
+feature alive single-machine). tsc + lint clean.
+
+`tests/integration/secret-drop-store-first.test.ts` (5 route-level tests, both
+sides of every boundary), `tests/unit/secret-store.test.ts` (keychain
+pollution guard), `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts`
+(+3 migration tests), and the Tier-3 e2e
+`tests/e2e/secret-drop-store-first-lifecycle.test.ts` — which boots two REAL
+AgentServers on one stateDir and proves a secret submitted to process 1 is
+retrievable from process 2 after a true restart. tsc + lint clean.
+
+`tests/unit/TransferByNickname.test.ts` (+5, including the verbatim incident
+case: already-on-target inside the rate window → noop) and
+`tests/unit/seamlessnessConfig.test.ts` (+4, stage coupling both ways +
+explicit-override both ways). tsc + lint clean. Production logs
+(2026-06-05T04:20Z double pin, zero `exactly-once` lines on a live-transfer
+pool) are the incident evidence.

package/upgrades/approval-ledger-phase2.eli16.md

@@ -0,0 +1,56 @@
+# Approval-as-Data — the approval ledger (Phase 2), explained simply
+
+## What this is
+
+Until now, when Justin approved something, that approval vanished the moment it
+happened. "Approved" — and no memory of it. So the agent could never learn the
+pattern of *when Justin agrees with its recommendation as-is* versus *when he changes
+it*, and could never get better at recommending the thing he'd have picked anyway.
+
+This change builds the **approval ledger**: every approval becomes a durable, signed
+record. Each one is tagged as one of three things:
+
+- **approved-as-is** — Justin took the recommendation exactly.
+- **approved-with-change** — Justin approved, but changed something (and we record
+  *why* — the single most useful bit).
+- **rejected** — Justin said no (also with the why).
+
+From those records, the system computes a simple score per *kind* of decision: out of
+all the decisions of this kind, what fraction did Justin take as-is? That fraction (the
+"agreement ratio"), plus a "current streak" of consecutive as-is approvals, is the
+signal that — much later, and only if Justin opts in — could let a class of low-risk
+decisions auto-approve. That auto-approval part is NOT in this change; this is just the
+memory + the scoreboard.
+
+## The restaurant analogy
+
+Think of the agent as a sous-chef proposing dishes to the head chef (Justin). Today,
+each "yes" or "change the sauce" is said out loud and then forgotten. The ledger is a
+notebook where the sous-chef writes down every proposal and what the head chef did with
+it — took it as-is, tweaked it (and the tweak), or sent it back. Over weeks, the notebook
+reveals: "For pasta dishes he almost always takes my call; for desserts he usually
+adjusts the sweetness." That's how the sous-chef learns to propose what the chef would
+pick — and which calls the chef trusts him to just make.
+
+## The one rule that keeps it honest
+
+The agent must **never decide for Justin** whether he agreed. Only Justin's *explicit*
+words count: "go with your picks" = as-is; "change X because Y" = a change with that
+reason. If Justin is silent or vague, nothing is recorded. And Justin can correct any
+entry later (a correction is a new signed line, never a quiet edit). This is what stops
+the agent from flattering itself by marking everything "approved-as-is."
+
+## What Justin asked for, and what changed mid-build
+
+Justin asked for this, then made one correction while it was being built: the original
+written design only tracked *official spec sign-offs*, but most of his approvals (like
+picking A/A/B in chat) happen in conversation. So the ledger was generalized to track
+approvals **wherever they occur** — a spec, a chat, anywhere — each tagged with where it
+happened. Fittingly, that very correction became the ledger's first recorded
+"change" entry: the first real data point is the feedback that shaped the feature.
+
+## What's safe about it
+
+It only *reads and records* — it never blocks or changes any behavior. If the agent has
+nowhere to store state, the feature simply isn't there (the API politely says
+"unavailable") rather than breaking anything. Every record is signed so tampering shows.

package/upgrades/autoloop-gate-compliance.eli16.md

@@ -0,0 +1,11 @@
+# Mentor autoloop prompt: gate-compliance line
+
+Instar has an automated "mentor loop" — a prompt that tells a developer agent how to run one cycle of dogfooding a mentee agent: check its health, assign it a real task, observe, and fix what breaks as a proper PR.
+
+That prompt already teaches the ship discipline (three test tiers, the dev gate, verify-before-claim). But it said nothing about the repo's *ratchet gates* — CI checks like no-silent-fallbacks that count known-bad patterns and fail if the count ever goes UP.
+
+We learned why that matters the hard way: a spec told the builder a helper should be "best-effort, never throws." The builder did exactly that — wrapped it in a catch that swallowed the error — and CI went red, because a swallowed catch is exactly what the no-silent-fallbacks ratchet counts. The spec's own wording invited the failure.
+
+This change adds one paragraph to the mentor-loop prompt: an intentional fail-open catch must either report the failure (through DegradationReporter) or carry an inline `@silent-fallback-ok` justification — and you never bump a ratchet baseline just to get CI green. It also tells the mentor to spell these notes out whenever it authors a task brief or spec for another agent, so the next builder doesn't get trapped by well-meaning "never throws" guidance.
+
+One prompt paragraph, three new test assertions locking it in. No behavior change anywhere else.

package/upgrades/feedback-phase3-monitor.eli16.md

@@ -0,0 +1,51 @@
+# ELI16 — Phase-3 parity monitor + cutover gate
+
+## What problem does this solve?
+
+Before we flip the feedback system from Dawn's Portal to Instar (the "cutover" — a one-way
+door), we run both processors side by side over real traffic for a while and check they
+agree. That side-by-side check ("the parity comparison") already exists. What was missing is
+the part that watches it *over time* and decides when it's genuinely safe to flip.
+
+You can't trust a single green check. Traffic is bursty; one quiet minute proves nothing. We
+need to see a real, sustained window where the two systems agreed on every report — and only
+*then* allow the cutover. And crucially, the decision to flip must not come from an agent
+"feeling confident" — it must come from an objective gate that an agent cannot fake.
+
+## What this change adds
+
+A small, pure `ParityMonitor`:
+
+- You feed it each comparison pass (how many clusters were compared, how many divergences).
+- It tracks the current **zero-divergence streak**. The moment any pass diverges, the streak
+  resets to zero — so a single disagreement, even after a long clean run, sends us back to
+  the start. No "mostly agreed" hand-waving.
+- It exposes one method, `gate(now)`, that returns **cleared** or **blocked** with a reason.
+  It clears only when the trailing run of passes is (a) all clean, (b) at least N passes
+  long, (c) spanning at least a real time window (default one hour), and (d) covering enough
+  clusters to be a meaningful sample. All four must hold.
+
+That `cleared` boolean is the objective `parity-zero-divergence` condition. It's exactly what
+the Coordination Mandate's "execute-cutover" authority reads: the agents can only flip the
+one-way door when this gate — not their judgment — says the window is satisfied.
+
+## Why it's safe
+
+Pure logic, no database, no network, no boot wiring. It only ever *reads* comparison results
+and *computes* a yes/no; it changes nothing and triggers nothing on its own. It's the
+building block the cutover executor will consult. 9 unit tests cover every gate boundary:
+too-few passes, too-short window, too-few clusters, the satisfied window, and the streak
+reset on any divergence (including re-clearing only after a fresh full clean window).
+
+## Plain-language risk
+
+Near-zero, and the failure mode is conservative: if the policy is too strict, the gate just
+stays *blocked* longer (cutover waits) — never the dangerous direction of clearing early.
+
+## Durability note
+
+The "they agreed" window can take hours to build up. If we kept it only in memory, restarting
+the server in the middle would silently wipe the streak and we'd have to start over (or worse,
+mis-measure the window across the restart). So each check result is appended to a small log file
+and reloaded when the monitor starts — the window survives restarts. A half-written final line
+from a crash is skipped cleanly, so one bad line never corrupts the rest of the history.

package/upgrades/feedback-phase4-integrity.eli16.md

@@ -0,0 +1,54 @@
+# ELI16 — Phase-4 feedback-migration integrity tooling
+
+## What problem does this solve?
+
+We're moving the "feedback factory" (the thing that catches user bug reports, groups
+duplicates into clusters, and tracks each cluster's lifecycle) from Dawn's Portal over to
+Instar. The cluster records aren't just data — they hold human and AI *judgment*: which
+bug is which, what was already triaged, what was shipped. That curated judgment is
+irreplaceable. If the move corrupts it, or if the new processor later overwrites it, we
+lose work nobody can recreate.
+
+Two specific dangers:
+
+1. **A silent bad copy.** "The row counts match" is far too weak a check — a single
+   cluster could come across with its status flipped or its governance note dropped and a
+   count check would never notice. We need to prove *every curated field of every row*
+   survived the move byte-for-byte.
+
+2. **A wrong-date backfill overwriting curated history.** After cutover, the processor is
+   only supposed to touch *new* reports. But if someone ever re-runs it over old data, it
+   would happily "re-cluster" the curated history and discard every triage decision.
+
+## What this change adds
+
+Two small, pure, well-tested building blocks (no database, no network — just logic, so
+they're fully unit-testable):
+
+- **`importIntegrity.ts`** — the import gate. It computes a per-row checksum over every
+  curated field and compares source-vs-imported (catching silent corruption), scans the
+  source for two clusters sharing a fingerprint *before* importing (which would otherwise
+  abort the transaction or silently merge them), asserts the two schemas accept the same
+  status values and field types, checks that no feedback row points at a missing cluster
+  (referential integrity), and computes the auto-increment sequence reset so the next new
+  insert can't collide. `runIntegrityGate()` rolls all of that into one pass/fail.
+
+- **`immutableGuard.ts`** — the structural "never re-derive" guard. Instead of *trusting*
+  the processor to only run over new traffic, we wrap the store: a cluster that predates
+  cutover, or that carries any governance note, is **immutable**, and any attempt to merge
+  into it, reopen it, or upsert over it is physically refused and recorded. A wrong-date
+  backfill therefore *cannot* overwrite curated state — the write simply does not happen.
+
+## Why it's safe
+
+Both modules are pure functions plus one store decorator. The guard only ever *refuses*
+writes (it never invents or changes data), and reads pass straight through. Nothing is
+wired into the running server yet — these are the building blocks the Phase-4 cutover will
+use. 36 new unit tests cover both sides of every boundary, including the processor running
+over a guarded store and leaving a curated cluster's count, status, and note untouched.
+
+## Plain-language risk
+
+Near-zero. Worst case if the guard is mis-tuned: a *legitimate* post-cutover merge is
+refused and shows up in the violations list (loud, not silent) — far better than the
+alternative of silently overwriting curated judgment.

package/upgrades/respawn-build-context-reestablishment.eli16.md

@@ -0,0 +1,5 @@
+# Respawn build-context restore
+
+Developer agents can now remember the build checkout they were using before a respawn. When the feature is enabled and a resumed session had been working inside an agent worktree, the resumed conversation starts with a `[BUILD-CONTEXT RESTORE]` note pointing back to that worktree.
+
+This is meant for fleet PR build sessions that die or restart mid-task. It does not move the tmux session's home directory, and it does nothing for normal home-only conversations. Stale or removed worktrees are skipped.

package/upgrades/side-effects/approval-ledger-phase2.md

@@ -0,0 +1,82 @@
+# Side-effects review — Approval-as-Data ledger (Phase 2)
+
+Spec: `docs/specs/AUTONOMOUS-OPERATION-JUDGMENT-AND-APPROVAL-AS-DATA-SPEC.md` (Part B).
+Change: new `src/core/ApprovalLedger.ts` + `POST/GET /approvals`, `GET /approvals/summary`
+wired through `AgentServer` → `RouteContext`; Agent-Awareness blurb in the CLAUDE.md template.
+
+## 1. Blast radius
+Additive only. A new module, three new route handlers, one new always-constructed field
+on `AgentServer`, one new `RouteContext` field, one template blurb. No existing route,
+store, sentinel, or gate is modified. The ledger never gates, blocks, throttles, or
+mutates any other state — read paths are pure reads; the one write path appends to its
+own JSONL file.
+
+## 2. State / data
+New on-disk file `.instar/state/approval-ledger.jsonl` (append-only, signed). No schema
+migration — the file is created on first write and absent until then. No existing file is
+touched. Torn-trailing-line tolerant on read. Rows are HMAC-signed over `authToken`; an
+empty/missing file yields an empty summary (no crash).
+
+## 3. Interactions
+- `RouteContext` gains a REQUIRED `approvalLedger` field. The only production assembler is
+  `AgentServer` (updated). Route tests build `ctx: any` partials, so they are unaffected
+  (tsc confirms the whole tree compiles).
+- Construction rides the existing `stateDir` availability (like `tokenLedger`); own
+  try/catch so an init failure can never cascade into the other ledgers.
+- Shares no lock, queue, or budget with any other component.
+
+## 4. Failure modes
+- No `authToken` → falls back to a fixed dev key for signing (integrity-only; documented).
+  Signing is never load-bearing for correctness — the operator-authoritative-source rule is.
+- `stateDir` absent → `approvalLedger` is null → routes 503 (handled + tested).
+- Inconsistent row (as-is WITH a divergence, or a change WITHOUT one) → `recordApproval`
+  throws → the route returns 400, not 500 (tested). Bad data cannot pollute ratios.
+- Disk-full / write error on append → throws to the caller (route 400/500); no partial
+  corrupt state (single `appendFileSync`).
+
+## 5. Security / authority
+- The load-bearing invariant is **operator-authoritative `mode` + `divergences`**: the
+  agent must not self-classify intent. Enforced by documentation + the design (the route
+  records what the caller passes; the caller must pass an explicit operator statement) and
+  backstopped by operator-correctable rows. HMAC signing gives integrity, NOT correctness —
+  it stops tampering, not ratio inflation; the authority rule stops inflation.
+- All routes are Bearer-gated (standard middleware). Read routes never gate behavior.
+
+## 6. Performance
+- O(rows) summary computation over a small append-only file read on each summary call.
+  At realistic volumes (tens to low-hundreds of approvals) this is negligible. No polling,
+  no background work, no LLM calls. Phase-3 (auto-approval, digest) is out of scope here.
+
+## 7. Migration parity
+- No `.claude/settings.json` hook, `.instar/config.json` default, or hook-script change →
+  no `PostUpdateMigrator` entry required. The feature is server-side code that activates on
+  the next server start after update; existing agents get it by updating, with no on-disk
+  migration. Agent-Awareness IS satisfied: the CLAUDE.md template gained an Approval-as-Data
+  blurb (`generateClaudeMd`).
+- Always-on when `stateDir` exists (read-only, low-cost) — no enable flag to migrate.
+
+## Tests
+- Unit (`tests/unit/ApprovalLedger.test.ts`, 18): record/read/verify, tamper-reject, every
+  consistency-guard throw + its passing counterpart, ratio + streak (reset on change/reject),
+  auto-eligibility threshold edges, surface generality, corrections, torn-line tolerance.
+- Integration (`tests/integration/approvals-routes.test.ts`, 6): full HTTP round-trip over a
+  real ledger; summary + surface breakdown; the 400 + 503 paths.
+- E2E (`tests/e2e/approval-ledger-lifecycle.test.ts`, 5): real AgentServer boot, alive
+  (200 not 503), record→summary→list lifecycle, Bearer-gate, and a WIRING-INTEGRITY proof
+  that the production HMAC signer is real (persisted row verifies; a tamper fails).
+
+## Post-review amendments (same PR, pre-merge)
+
+- **State-path fix:** the ledger file follows the `.instar/state/` convention —
+  `config.stateDir` IS `.instar`, durable state lives under `state/`
+  (`.instar/state/approval-ledger.jsonl`, matching the spec's stated path). The e2e
+  wiring-integrity test proves the corrected path end-to-end.
+- **Ratchet exemptions:** the three deny-safe/default-empty catches carry
+  `@silent-fallback-ok` markers INSIDE the catch blocks (missing-file → empty
+  history; malformed signature → verifies false; init failure → reported via
+  console.warn + ledger null → routes 503).
+- **Docs coverage:** the three `/approvals` routes are documented in
+  `site/src/content/docs/reference/api.md` (route-floor gate).
+- **Discoverability:** the `/approvals` prefix is classified in
+  `CapabilityIndex.ts` (CAPABILITY_INDEX → surfaced in `/capabilities` with its
+  three endpoints), satisfying the capabilities-discoverability gate.

package/upgrades/side-effects/autoloop-gate-compliance.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — Mentor autoloop gate-compliance line
+
+**Version / slug:** `autoloop-gate-compliance`
+**Date:** `2026-06-05`
+**Author:** `echo`
+**Second-pass reviewer:** `echo second-pass checklist`
+
+## Summary of the change
+
+Adds one static paragraph to `buildAutoloopGoal()` in `src/scheduler/MentorAutonomousGuardian.ts` — the deterministic prompt assembled for the autonomous mentor dogfooding loop. The paragraph teaches ratchet-gate compliance: intentional fail-open catches must report via DegradationReporter or carry an inline `@silent-fallback-ok` justification (never a baseline bump), and task briefs/specs authored for other agents must spell these notes out explicitly. Earned from PR #792's no-silent-fallbacks CI failure, where the spec's "best-effort, never throws" guidance invited the exact swallowed catch the ratchet counts.
+
+## Decision-point inventory
+
+- `buildAutoloopGoal` — modified — one additional template line appended to the returned prompt string. Pure string assembly; no new branches, no I/O, no config.
+- `tests/unit/MentorAutonomousGuardian.test.ts` — modified — three new content assertions on the assembled prompt.
+
+## 1. Over-block
+
+None possible. The function returns a string; nothing is gated, blocked, or filtered. The added text instructs the *consuming agent*; it cannot prevent any operation by itself.
+
+## 2. Over-permit
+
+None. No permission surface is touched.
+
+## 3. Token/cost impact
+
+The prompt grows by ~430 characters, sent once per autonomous-fix guardian cycle (budget- and min-interval-gated, single-instance). Negligible.
+
+## 4. Behavior change for existing consumers
+
+The only consumer is `MentorAutonomousGuardian` → spawned loop session goal text. Existing assertions on the prompt (cycle steps, discipline line, topics) are unchanged and still pass — the new line is purely additive. The `degrades gracefully when topics are unset` test still passes (the added text contains no topic interpolation).
+
+## 5. Failure modes
+
+A string literal cannot throw at runtime. The TypeScript build verifies the template syntax. If the guidance itself were wrong, the blast radius is advisory-only (an agent following it would still produce gate-passing code — DegradationReporter and `@silent-fallback-ok` are both legitimate, documented paths in `tests/unit/no-silent-fallbacks.test.ts`).
+
+## 6. Migration parity
+
+None required: the prompt is assembled at runtime from shipped code; every agent gets it on its next update through the normal release path. No installed files, hooks, config defaults, or templates change.
+
+## 7. Rollback
+
+Revert the commit. No persisted state references the new text.