instar 1.3.269 → 1.3.270

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/coordination-mandate-enforcement.md

@@ -0,0 +1,86 @@
+# Side-effects review — Coordination Mandate enforcement (spec §4, G2.2)
+
+Spec: `docs/specs/coordination-mandate.md` (approved by Justin, A/A/B, 2026-06-05).
+Change: new `src/coordination/` module (types, MandateStore, MandateGate, MandateAudit,
+ConditionsRegistry) + six `/mandate*` routes wired through `AgentServer` → `RouteContext`.
+
+## 1. Blast radius
+Additive only. No existing route, gate, sentinel, or store is modified. The engine is
+**deny-by-default and inert**: with no mandate issued (the universal state at deploy),
+every `/mandate/evaluate` call denies — so shipping this changes NO behavior anywhere
+until the operator issues the first mandate through the PIN-gated route. It never
+weakens an existing safety check; it adds a controlled delegation surface beside them.
+
+## 2. State / data
+Two new files under the `.instar/state/` convention, created on first use:
+`coordination-mandates.json` (the signed mandates) and `mandate-audit.jsonl`
+(append-only, hash-chained). No schema migration; absent files mean an empty store and
+an empty audit. Torn-trailing-line tolerant reads.
+
+## 3. Security model (the load-bearing dimension)
+- **requester ≠ authorizer preserved:** the human-authored mandate is the authorizer.
+  The agent's Bearer token CANNOT issue or revoke — `/mandate/issue` and
+  `/mandate/:id/revoke` require the operator's dashboard PIN (sha256 + timingSafeEqual +
+  per-IP attempt limiting, mirroring `/dashboard/unlock`). Tested at all three tiers.
+- **Authorship proof (T1/T2):** HMAC over the canonical authored bytes (key-order-stable
+  serialization), produced only at issuance. A forged or widened mandate fails
+  `verifyAuthorship` → the gate denies. `revoked` is excluded from the proof so the
+  kill switch works post-issuance; revocation is checked on every evaluation (T5).
+- **Conditions (T7/T10):** objective resolvers from real state; an unregistered or
+  throwing resolver evaluates FALSE (deny-safe). The first mandate (per decision 3B)
+  carries no conditioned authority; `integrity-gate-pass` and `parity-zero-divergence`
+  are registered deny-safe stubs until the real state is wired for a future cutover
+  authority — which per decision 1A is not delegated anyway.
+- **Audit (T3/T8):** every decision (allow AND deny) appends a hash-chained entry;
+  `verifyChain()` detects any edit/deletion and is surfaced on `GET /mandate/audit`.
+- **Stated trust boundary (T12):** an attacker with local disk write access could edit
+  server-managed state — the same trust root as today; the proof stops forged AUTHORED
+  content, and the audit chain makes tamper detectable. Out of scope per the spec.
+
+## 4. Failure modes
+- No `stateDir` → engine is null → all `/mandate*` routes 503 (tested).
+- Engine init failure → own try/catch, never cascades to other inits.
+- Malformed issuance body → 400 with a specific reason (agents pair, non-empty
+  authorities, future expiry — each tested both sides).
+- No `dashboardPin` configured → issuance/revocation 503 (PIN auth unavailable) — the
+  gate cannot be bypassed by the PIN simply being absent.
+
+## 5. Interactions
+- `RouteContext` gains a required `coordination` field; the only production assembler
+  (`AgentServer`) is updated. Route tests use partial `ctx: any` → unaffected (tsc green).
+- Express route-order hazard handled: `/mandate/audit` and `/mandate/evaluate` are
+  registered BEFORE `/mandate/:id` (tested explicitly).
+- No locks, queues, LLM calls, or budgets shared with other components.
+
+## 6. Performance
+O(mandates) reads of a small JSON file per evaluation + one appendFileSync per decision.
+Evaluation volume is a handful of A2A actions per migration step — negligible.
+
+## 7. Migration parity
+No `.claude/settings.json` hook, config default, or hook-script change → no
+`PostUpdateMigrator` entry needed. Server-side code activates on the next server start
+after update. Agent-Awareness satisfied: CLAUDE.md template gains a Coordination
+Mandate blurb (`generateClaudeMd`). The feature is inert-by-default everywhere (deny
+without a mandate), so fleet exposure is zero until an operator issues one.
+
+## Tests
+- Unit (`tests/unit/coordination-mandate.test.ts`, 17): authorship valid/forged/widened,
+  revoke-preserves-proof, canonical key-order stability, audit chain intact/tampered,
+  conditions (true/false/unknown/compound/throwing), the gate's FULL deny ladder
+  (missing, forged, expired, revoked, non-party, unlisted action, out-of-bounds params,
+  unmet condition) + both allow paths, bounds helper both sides.
+- Integration (`tests/integration/mandate-routes.test.ts`, 9): PIN-less issue refused,
+  wrong PIN refused, issue/list/evaluate/revoke round-trip, deny-by-default audited,
+  route order, validation 400s, 503s.
+- E2E (`tests/e2e/coordination-mandate-lifecycle.test.ts`, 5): real AgentServer boot,
+  alive + Bearer-gated, deny-by-default on fresh boot, full PIN-issue→allow→deny→
+  revoke→deny lifecycle with chain-verified audit, and the production-HMAC
+  wiring-integrity proof (persisted authProof verifies; a widened mandate fails).
+
+## Post-review amendment (same PR, pre-merge)
+
+- **Discoverability:** the `/mandate` prefix is classified in `CapabilityIndex.ts`
+  (CAPABILITY_INDEX → surfaced in `/capabilities` with all six endpoints + the
+  evaluate-before-acting + PIN-gating semantics), satisfying the
+  capabilities-discoverability gate. Agents discover the gate; they still cannot
+  issue through it.

package/upgrades/side-effects/feedback-phase3-monitor.md

@@ -0,0 +1,37 @@
+# Side effects — Phase-3 parity monitor + cutover gate
+
+## New files (additive only)
+- `src/feedback-factory/monitor/parityMonitor.ts` — `ParityMonitor` (records passes, tracks
+  the zero-divergence streak, exposes the `gate()` cutover signal) + `DEFAULT_GATE_POLICY`.
+- `tests/unit/feedback-factory/parity-monitor.test.ts` (9 tests).
+
+## Runtime impact
+- **None at boot / on the live server.** Not imported by `server.ts`, any route, job, or
+  hook. No new endpoint, no config key, no `PostUpdateMigrator` entry. No new dependency
+  (pure logic over the existing `ParityResult` type).
+
+## Behavioral guarantees
+- `gate()` clears ONLY when all four conditions hold: ≥ requiredCleanPasses consecutive clean
+  passes, clean window ≥ minWindowMs of real time, ≥ minClustersObserved clusters across the
+  streak, and zero divergence in the streak. Any divergent pass resets the streak.
+- The monitor never mutates anything and never triggers cutover itself — it only computes a
+  cleared/blocked verdict that a downstream executor reads.
+- Conservative failure mode: an over-strict policy keeps the gate BLOCKED longer (cutover
+  waits); it can never clear early.
+
+## Reversibility
+- Fully reversible: delete `monitor/parityMonitor.ts` + its test. Nothing references it yet.
+
+## Follow-on wiring (not in this PR)
+- The Coordination Mandate condition registry (G2.2) maps `parity-zero-divergence` →
+  `monitor.gate(now).cleared`. The Phase-4 cutover executor (G2.4) consults it before the flip.
+- A durable wrapper (persist passes to JSONL so the window survives a restart) + a read-only
+  `/parity/status` route land with the cutover-executor wiring.
+
+## Durability (added)
+- `parityMonitorStore.ts` — `DurableParityMonitor` + `JsonlPassPersistence`. The zero-divergence
+  window spans HOURS; without persistence a restart silently resets the streak. Passes are
+  appended to an append-only JSONL and reloaded on construction, so the window survives a
+  restart. Torn final line (crash mid-append) is skipped on reload, never corrupting the prior
+  window. Injectable `PassPersistence` keeps the logic unit-testable without disk. Still not
+  wired into the running server (the cutover executor constructs it with the live path).

package/upgrades/side-effects/feedback-phase4-integrity.md

@@ -0,0 +1,35 @@
+# Side effects — Phase-4 feedback-migration integrity tooling
+
+## New files (additive only)
+- `src/feedback-factory/migration/immutableGuard.ts` — `GuardedFeedbackStore` decorator +
+  `isClusterImmutable` / `hasGovernanceNotes` invariants.
+- `src/feedback-factory/migration/importIntegrity.ts` — pure import-gate core (checksums,
+  fingerprint-uniqueness scan, schema-equivalence, referential integrity, sequence reset,
+  `runIntegrityGate`).
+- `tests/unit/feedback-factory/immutable-guard.test.ts` (15 tests).
+- `tests/unit/feedback-factory/import-integrity.test.ts` (21 tests).
+
+## Runtime impact
+- **None at boot / on the live server.** These modules are NOT imported by `server.ts`, any
+  route, job, or hook. They are library building blocks the Phase-4 cutover execution will
+  call. No new endpoint, no new config key, no migration to `PostUpdateMigrator`.
+- No new dependencies (uses `node:crypto` only).
+
+## Behavioral guarantees
+- `GuardedFeedbackStore` only ever REFUSES a mutation of an immutable cluster (pre-cutover
+  createdAt or non-null governance note) and records a `GuardViolation`; it never alters
+  data and passes all reads + non-curated writes straight through to the inner store.
+- A failing `onViolation` audit sink can never break the store or surface as a mutation
+  (try/caught, annotated `@silent-fallback-ok`).
+- Checksums collapse null/undefined/"" so the import gate does not flap on the
+  null-vs-empty governance-note distinction (that distinction is asserted separately by
+  schema-equivalence).
+
+## Reversibility
+- Fully reversible: delete the two `migration/` files + their tests. Nothing else
+  references them yet.
+
+## Follow-on wiring (not in this PR)
+- Phase-4 cutover executor (G2.4) constructs the `GuardedFeedbackStore` around the real
+  Prisma-backed store with the cutover timestamp from config, and runs `runIntegrityGate`
+  over the export/import pair as the Phase-2 gate.

package/upgrades/side-effects/respawn-build-context-reestablishment.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Respawn build-context re-establishment
+
+**Version / slug:** `respawn-build-context-reestablishment`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `instar-codey second-pass checklist`
+
+## Summary of the change
+
+This change hardens the interactive SessionManager respawn path for developer build sessions. A new sidecar store records each running session's live tmux pane working directory, using the generic state layer's temp-file-plus-rename atomic write. When a resumed interactive session has a fresh saved cwd under an agent worktree, SessionManager prepends a `[BUILD-CONTEXT RESTORE]` continuation note to the resumed message. Normal home-only sessions, stale records, missing worktrees, and non-enabled agents receive no note.
+
+The feature is dark by default for normal agents. Server boot resolves the session-level feature flag as an explicit override if present, otherwise the standard development-agent gate.
+
+## Decision-point inventory
+
+- `SessionBuildContextStore` — add — owns sidecar state validation, crash-safe persistence through StateManager, cwd eligibility, staleness, missing-path checks, branch enrichment, and restore-note formatting.
+- `SessionManager.monitorTick` — modified — records pane cwd after liveness is confirmed, without changing session lifecycle decisions.
+- `SessionManager.spawnInteractiveSession` — modified — prepends a restore note only for resume spawns with an eligible saved worktree context.
+- `server` startup wiring — modified — resolves the feature dark by default and live for development agents unless explicitly overridden.
+- Session-management e2e — modified — proves a real tmux pane under a fixture worktree gets the restore note while a home-only control stays unchanged.
+
+## 1. Over-block
+
+The restore can skip a legitimate build context if the tmux cwd is not under a `.worktrees` path. That is intentional. The spec's blast-radius guard is more important than restoring every possible hand-navigated directory. Agents can still recover manually from conversation context; the automated note is limited to the known build-worktree convention.
+
+The restore can also skip when the sidecar is stale or the worktree directory was removed. That prevents a respawn from sending the agent back into a deleted or long-finished checkout.
+
+## 2. Under-block
+
+The sidecar records cwd for running sessions when the feature is enabled, including home-only sessions. Home-only records are not eligible for restore, so this is additional local state but not additional behavior. The record contains local paths and an optional branch name; it does not include prompt content or credentials.
+
+The branch name is best-effort enrichment. If Git cannot read the branch, the restore note still works with the worktree path alone. Failure to read branch never blocks monitoring or respawn.
+
+## 3. Level-of-abstraction fit
+
+SessionManager owns tmux lifecycle, liveness checks, interactive respawn, and initial-message injection, so it is the correct place to sample pane cwd and prepend the resume note. The sidecar store keeps persistence and eligibility logic out of the large SessionManager class and makes the boundary unit-testable.
+
+The change does not force tmux to spawn inside the worktree. That matches the design spec: the session home remains stable, and the resumed agent receives deterministic instruction to return to the build checkout only when appropriate.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Not applicable to conversational/product judgment — this is structural session lifecycle restoration.
+
+The cwd sample is a mechanical tmux fact. The restore decision is a deterministic filesystem/scope guard: fresh, existing, different from spawn cwd, and under a worktree path. It does not judge user intent or message meaning.
+
+## 5. Interactions
+
+- **Shadowing:** The restore note is prepended before the normal initial-message injection. Existing InputGuard and injection mechanics still handle the resulting message through the same path.
+- **Double-fire:** The note is computed once per resumed spawn. Reusing an already-live tmux session does not inject a restore note.
+- **Races:** A worktree can be removed between sidecar read and agent acting on the note. The respawn path checks existence immediately before injecting; after that, the note is advisory and the agent can report if the path disappears.
+- **Feedback loops:** Monitoring persists only when cwd changes, avoiding a write every tick for steady sessions.
+
+## 6. External surfaces
+
+The visible behavior is a new continuation preamble for eligible resumed developer sessions. The preamble is intentionally plain text and starts with `[BUILD-CONTEXT RESTORE]` so the agent can act on it deterministically. Normal topic sessions that remain in agent home see no new text.
+
+The persistent surface is a local sidecar state record keyed by tmux session name. It stores spawn cwd, current cwd, optional branch, and update time.
+
+## 7. Rollback cost
+
+Rollback is a code revert of the sidecar store, SessionManager wiring, server gate wiring, tests, and artifacts. The sidecar state file can remain harmlessly on disk; without the code path it is ignored. No migration or state repair is required.
+
+## Conclusion
+
+The change addresses the respawn amnesia failure without changing normal spawn cwd, without broadening behavior for home-only sessions, and without relying on conversation memory to rediscover the checkout. The test set covers pure eligibility/staleness behavior, mocked tracker-to-respawn wiring, and a real tmux e2e with both worktree and home-only controls.
+
+## Second-pass review
+
+**Reviewer:** `instar-codey separate pass`
+**Independent read of the artifact:** concur
+
+The risky surface is SessionManager. The implementation keeps the new behavior behind a feature gate, samples only after liveness is confirmed, writes through crash-safe state persistence, and injects only a continuation note for eligible resumed spawns. The scope guard is the core safety property and is covered in all three test tiers.
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/session-build-context-store.test.ts tests/integration/session-build-context-respawn.test.ts` passed.
+- `npm test -- --run tests/e2e/session-management-e2e.test.ts -t "restores a worktree build context"` passed.
+- `npm test -- --run tests/unit/no-silent-fallbacks.test.ts tests/unit/session-build-context-store.test.ts` passed after marking best-effort branch enrichment as an intentional fail-open.
+- `npm run lint` passed.