instar 1.3.555 → 1.3.557

package/upgrades/1.3.557.md

@@ -0,0 +1,61 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The session age-limit reaper (`SessionManager`'s wall-clock timeout in `monitorTick`) now
+consults the session's live transcript before judging it idle enough to kill. Previously the
+age-gate's "truly idle?" check looked only at the tmux pane (idle prompt) and the process tree
+(no non-baseline child process) — both BLIND to MCP/tool work, which runs out of the pane's
+process tree (the Playwright MCP server) with only short-lived bash calls in between. A session
+actively driving a browser therefore looked idle between tool calls and was terminal-killed at
+the ~5h age cap with `midWork:false` (no resume).
+
+The other reap path — the `SessionReaper` (pressure/idle) — already cross-checks transcript
+growth and would not have killed it. This change brings the age-kill path to parity:
+`SessionManager.isTranscriptRecentlyActive(session, withinMs)` resolves the per-framework
+transcript via the core `resolveFrameworkTranscriptPath` and treats a session whose transcript
+was written within `AGE_GATE_TRANSCRIPT_ACTIVE_MS` (2 min) as actively working — the kill is held
+off, exactly as it already is for a session with a live child process. The idle decision is
+extracted into a pure, exported `isAgeGateTrulyIdle(idleAtPrompt, hasActiveProcs, transcriptActive)`.
+An unresolvable transcript (no session id, missing file, or a framework with no resolver case like
+pi-cli) returns false and the gate falls back to exactly today's pane/procs behavior — safe
+degradation, no regression. Machine-local; no config key, route, or migration.
+
+## What to Tell Your User
+
+- **Long-running sessions don't get killed while they're busy**: "If one of my longer sessions was
+  ever shut down while I was actually in the middle of real work — especially driving a browser or
+  an automation tool — that shouldn't happen anymore. I now tell whether I'm still working from my
+  live activity, not just whether the terminal looks quiet, so the watchdog leaves me alone until I
+  genuinely stop."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Age-reaper recognizes browser/tool work as "active" | automatic |
+
+## Evidence
+
+This fixes a real production incident, verified two ways:
+
+**Before (the actual failure, from `logs/reap-log.jsonl`):** the session
+`Self-Coherence — Knowing My Own Parallel Work` (topic 25660), which was actively driving the
+Playwright MCP server to provision a GitHub identity, was reaped at `2026-06-14T03:34:55Z` with
+`reason:"age-limit"`, `disposition:"terminal"`, `midWork:false` — killed mid-work, no resume, at
+the ~5h cap, because between tool calls the pane looked idle and no child process existed.
+
+**After (decision-boundary reproduction):** the extracted `isAgeGateTrulyIdle` is unit-tested over
+all 8 input combinations. The exact incident inputs — idle pane + no child process + a transcript
+written in the last 2 minutes — now resolve to `false` (held off, not killed), while the
+genuine-zombie inputs (idle pane + no process + a quiet transcript) still resolve to `true` (still
+reaped — no regression to the real zombie-cleanup). Behavioral tests also cover
+`isTranscriptRecentlyActive` for recent/stale/no-id/missing-file/cross-framework cases.
+
+**Why not a full live before/after:** reproducing the original end-to-end requires a >5h wall-clock
+wait plus a live MCP session, so it is not practical to exercise in dev; the decision-boundary
+repro over the captured incident inputs is the faithful, deterministic substitute, and the real
+reap-log entry above is the production "before."

package/upgrades/side-effects/age-kill-transcript-aware-resume.md

@@ -0,0 +1,115 @@
+# Side-Effects Review — Age-Kill Transcript-Awareness
+
+**Version / slug:** `age-kill-transcript-aware-resume`
+**Date:** `2026-06-14`
+**Author:** `echo`
+**Second-pass reviewer:** spec-convergence panel (6 internal reviewers + Standards-Conformance gate; external non-Claude pass degraded — see convergence report)
+
+## Summary of the change
+
+The session age-limit reaper (`SessionManager.monitorTick`, the `elapsed > limit` block) decides
+whether an over-age session is "truly idle" and therefore age-kill-eligible. Before this change
+that decision used only two signals — the tmux pane shows an idle prompt, and there is no
+non-baseline child process — both BLIND to MCP/tool work (the Playwright MCP server runs out of
+the pane's process tree; bash tool calls are short-lived). On 2026-06-13 an actively-working
+session was terminal-killed because, between tool calls, it looked idle. This change adds a third
+signal: `isTranscriptRecentlyActive(session, 120_000)` — true when the session's framework
+transcript (JSONL) was modified within the last 2 minutes. The idle decision is extracted into a
+pure, exported `isAgeGateTrulyIdle(idleAtPrompt, hasActiveProcs, transcriptActive)` so the exact
+incident is reproducible at the decision boundary in a unit test. Files: `src/core/SessionManager.ts`
+(constant `AGE_GATE_TRANSCRIPT_ACTIVE_MS`, the `isAgeGateTrulyIdle` function, the
+`isTranscriptRecentlyActive` method, the import of `resolveFrameworkTranscriptPath`, and the
+age-gate wiring); tests in `tests/unit/session-timeout-activity-aware.test.ts` and
+`tests/unit/session-manager-behavioral.test.ts`.
+
+## Decision-point inventory
+
+- `SessionManager.monitorTick age-gate (ageGateTrulyIdle)` — **modify** — adds a transcript-activity
+  defer condition; the kill now requires idle-pane AND no-child-proc AND transcript-not-recently-active.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+In reap terms, "over-block" = wrongly DEFERRING a kill. A genuinely-finished session whose
+transcript was touched <2 min before the check is held off for up to one 2-minute window. This is
+harmless: the idle-detection block immediately below the age gate still reaps it once its
+transcript goes quiet. No session is kept alive indefinitely on a stale signal — only real,
+ongoing transcript writes (which require real model activity) sustain the defer.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The change ONLY adds a defer condition; it removes no kill. A session with NO resolvable transcript
+(an unknown framework, or pi-cli which has no resolver case) gets `isTranscriptRecentlyActive ===
+false` and the age gate falls back to EXACTLY today's pane/procs verdict — so such a session is no
+better protected than before (safe degradation, no NEW under-block). The deliberate non-coverage:
+the age gate does not try to be a hard resource ceiling for runaway-but-active sessions — that is
+owned by SessionWatchdog (stuck-process), the context-wedge sentinel, and the CPU/memory-pressure
+reaper, all unchanged.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The SessionReaper (the pressure/idle reap path) ALREADY layers transcript-growth awareness
+(`probeTranscript`/`transcriptDelta`). This change brings the parallel age-kill path to parity at
+the SAME layer using the SAME core resolver (`resolveFrameworkTranscriptPath` from
+`core/FrameworkSessionStore`). It is a cheap detector feeding an existing defer, not a new
+authority and not a re-implementation of an existing primitive. It deliberately does NOT depend on
+`monitoring/transcriptProber` (that would invert core→monitoring layering); it uses the core
+resolver directly.
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or produce a signal that feeds a smart gate?**
+
+It produces a SIGNAL that ADDS a defer (keep) condition to an existing authority. It grants no new
+blocking authority and moves strictly in the safe direction (fewer kills of active sessions). The
+probe is brittle (a single statSync) but its failure mode is bounded by the fail-to-`false`
+contract: a probe error never keeps a session alive — it only declines to add the new defer
+reason, falling through to the existing pane/procs verdict. (Ref: `docs/signal-vs-authority.md`.)
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, or race with adjacent cleanup?**
+
+Consistent with the SessionReaper's existing transcript gate (same resolver, same intent). The
+single-point mtime check vs the SessionReaper's cross-tick delta is an intentional, benign
+asymmetry (the SessionReaper requires repeated positive-idle confirmations before it reaps, so the
+two never produce a contradictory kill on the same tick). The idle-detection block below the age
+gate still owns genuinely-idle reaping (the held off path falls through, no `continue`). No new
+kill/revive loop: the change does NOT touch `WorkEvidence`/`ReapGuard.evaluate()`/`workEvidence()`,
+so the documented evaluate-vs-workEvidence disagreement class (2026-06-13 13-session loop) is
+untouched. Adversarial review confirmed loop-safety. The `overAgeButActiveLogged` set already
+prevents log spam on the held off path.
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents/users/systems? Timing/state dependence?**
+
+No API route, no config key, no hook, no template, no dashboard surface. The only externally
+observable effect: a long-running, actively-working session is no longer terminal-killed at ~5h —
+which is the intended, operator-requested behavior. The new constant is code-level (not a config
+surface). The change reads only a local file's mtime; it depends on the framework runtime writing
+its transcript on activity (true for claude-code, codex-cli, gemini-cli; pi-cli safely degrades).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** Each machine's `SessionManager` reaps only its OWN sessions and reads
+only its OWN local transcripts. There is no shared/replicated/proxied state: the decision is a
+per-session, per-machine read of a local file. No cross-machine surface is introduced or needed —
+a reap decision is inherently local to the machine running the session. No user-facing notice is
+added (so no one-voice gating concern); no durable cross-machine state (so no topic-transfer
+strand); no generated URL.
+
+## 8. Rollback cost
+
+Revert the PR — a single-file behavior change plus its tests; no data migration, no agent-state
+repair, no config rollback. As an interim dial without a revert, setting
+`AGE_GATE_TRANSCRIPT_ACTIVE_MS` to 0 makes the new defer condition inert (reverts to the prior
+two-signal behavior). Ships with the dist on update (no PostUpdateMigrator entry needed — the
+change is internal runtime behavior, not an agent-installed file).

package/upgrades/side-effects/feedback-receiver-persistence.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Feedback-factory receiver persistence (Option-B receiving end)
+
+**Version / slug:** `feedback-receiver-persistence`
+**Date:** `2026-06-11`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `required (receiver/intake decision surface) — see appended response`
+
+## Summary of the change
+
+Implements the receiving end of the migration spec's Option-B write seam (docs/specs/feedback-factory-migration.md, Amendment A1 / Q2b, Dawn-confirmed 2026-06-11): the canonical front (feedback-front/ on Vercel) durably persists each ACCEPTED fleet report into a cloud Vercel-Blob inbox, and a new `InboxDrainer` on the operated machine ingests them into a new durable `JsonlFeedbackStore` (format-compatible with the proven AS-IS import artifacts). Files: `src/feedback-factory/inbox/BlobInboxClient.ts` (new — pinned Blob REST, zero deps), `src/feedback-factory/inbox/InboxDrainer.ts` (new), `src/feedback-factory/store/JsonlFeedbackStore.ts` (new), `src/feedback-factory/receiver/BlobInboxStore.ts` (new), `src/feedback-factory/receiver/handlers.ts` (handler made async over a narrow `ReceiverStore` seam — decision logic untouched), `feedback-front/src/feedback.ts` + rebundled `api/feedback.js` (persistence mode behind a deploy-time env token; byte-equivalent Phase-0 behavior without it), server wiring (`AgentServer.ts`, `routes.ts` GET /feedback-inbox/status, `CapabilityIndex.ts`), config type (`types.ts feedbackFactory.receiverPersistence`, dark default), Agent Awareness (`templates.ts`, `PostUpdateMigrator.migrateClaudeMd` + shadow marker). All three test tiers added.
+
+## Decision-point inventory
+
+- `handleFeedbackSubmit` intake defense chain (rate limit / fingerprint / honeypot / HMAC / validation / dedup) — **pass-through** — made async-capable; decision ORDER, status codes, and messages unchanged (existing unit tests re-asserted as async; the front's HMAC round-trip harness re-run green against the rebuilt bundle).
+- Front mode selection (`inboxToken()` present ⇒ persistence mode, absent ⇒ Phase-0 verify-only) — **add** — a deploy-time structural gate, not a per-request heuristic; no content-based decision.
+- `parseInboxItem` quarantine boundary in the drainer — **add** — classifies an inbox object as ingestable vs malformed. Malformed is PRESERVED (quarantine/), never dropped; no user-visible block.
+- `feedbackFactory.receiverPersistence.enabled` config gate — **add** — dark default; enabled-without-token degrades to dark with a loud boot log line.
+
+---
+
+## 1. Over-block
+
+The intake defense chain is untouched, so no new rejection of legitimate reports. The new quarantine boundary could over-classify: a future receiver writing a richer shape would still pass (extra fields flow through `[k: string]: unknown`); only a missing/empty `feedbackId`, `title`, or `description` quarantines — and the receiver structurally always writes those (it validated them two layers earlier). Residual: an operator hand-seeding the inbox with a malformed object gets a quarantined (preserved) object, which is the intended behavior. Precision note (second-pass finding): the validator only empty-checks `feedbackId`; an empty-STRING title/description passes ingest — the safe, less-quarantine direction, and the receiver validated both two layers earlier. No issue identified beyond that.
+
+## 2. Under-block
+
+- The per-IP rate limiter on Vercel is per-warm-instance, so a multi-instance burst admits more than 10/hr/IP (the reference's limiter has the same scope on its single deployment; fingerprint + honeypot + HMAC layers are instance-independent). Known accepted gap, flagged in the Phase-0 deploy runbook; durable backing is a deploy-time follow-up. <!-- tracked: topic-12476 -->
+- Front-side dedup (`hasFeedback` = inbox prefix list) cannot see already-DRAINED ids — a retransmit after drain re-enters the inbox. By design: the drainer's canonical-store dedup drops it at ingest (integration test pins this), so end-to-end idempotency holds.
+
+## 3. Level-of-abstraction fit
+
+The front is stateless HTTP at the edge (Vercel — correct per spec §2.2); durability is a storage primitive at the platform layer (Blob — correct: a stateless function cannot host a durable buffer, which is exactly why the "forward + buffer in the function" alternative was rejected); the drainer is lightweight always-on at the operated-machine layer (Mini — matches §2.2's own placement taxonomy); the canonical store is data at the disk layer, format-aligned with the import machinery it inherits from. The drainer FEEDS the existing FeedbackStore seam rather than re-implementing any receiver logic. No layer inversion identified.
+
+## 4. Signal vs authority compliance
+
+No new blocking authority anywhere. Every accept/reject decision stays in the already-shipped, already-reviewed ported defense chain; the new components are pure transport/persistence; the status route is read-only observability; the quarantine path preserves rather than discards. Compliant with docs/signal-vs-authority.md — this change adds zero brittle checks with authority.
+
+## 5. Interactions
+
+- `cutoverReadiness` and the import machinery are untouched; the JsonlFeedbackStore deliberately READS the same JSONL shape `PersistedShadowImportTarget` writes, so the cutover import artifact seeds the canonical store without a translation step (unit test pins alias-id adoption).
+- The handler's async change touches its one existing consumer (its unit test, updated). The front imported only defense fns before; it now also imports the handler — bundled at dev time, no runtime dep added.
+- No double-fire risk: the drainer is single-instance (one server), `drainOnce` is reentrancy-guarded (`ticking`), and delete-after-commit + dedup makes overlap with a retransmit benign.
+- Server boot: the init block is try/caught and null-on-failure (deny-safe 503), so it cannot cascade into adjacent component init.
+
+## 6. External surfaces
+
+- New Bearer-gated read-only route `GET /feedback-inbox/status` (+ CapabilityIndex + CLAUDE.md template/migration). No unauthenticated surface added.
+- The front's PERSISTENCE mode changes what a fleet sender sees ONLY in that accepted reports now return the reference receiver's exact response shapes (it runs the faithful handler) — and the mode is unreachable until a Blob token reaches the function's env. Note (second-pass finding): the fallback to the store-injected `BLOB_READ_WRITE_TOKEN` means CONNECTING a Blob store to the Vercel project is itself the enabling act — deliberate, dashboard-gated, on a dedicated project, but it is the precise activation boundary, not "only the cutover deploy". Until a token exists the deployed front's no-token behavior is byte-identical Phase-0 (the 405/503 pre-gate bodies were restored to the original shape after the second-pass caught a dropped cosmetic `phase: 0` field; verify script re-run green against the rebuilt bundle).
+- Blob objects are public-but-unguessable URLs (random suffix ON, pinned by unit test). Report bodies are fleet bug reports — same sensitivity class as today's POST-to-Portal path; pathnames are never predictable, and the drainer reads URLs from list results only. Token lives in env (front: Vercel env; operated machine: `FEEDBACK_INBOX_BLOB_TOKEN`), never in config.json or source.
+- Timing dependence: the drainer is poll-based; a down machine only delays ingestion — the durable inbox is the buffer. That asymmetry is the design's point.
+
+## 7. Rollback cost
+
+- Dark by default: fleet installs see only an inert 503 route; no behavior change anywhere until BOTH the config flag and the token exist.
+- Operated instance back-out: set `enabled: false` (or drop the token) and restart — the inbox simply accumulates durably until re-enabled; nothing is lost, nothing dangles.
+- Front back-out: remove the token env from the Vercel project → next invocation is Phase-0 verify-only again. No deploy needed beyond an env change.
+- Full revert of the PR is clean: no migrations of durable data, no schema, no external state created at merge time. The PostUpdateMigrator section-append is idempotent and harmless if orphaned (documentation text only).
+
+---
+
+## Second-pass review response (independent reviewer subagent, 2026-06-11)
+
+Concern raised: the artifact's "byte-equivalent Phase-0 behavior without the token" claim was overstated — two responses in the front's no-token path changed. `feedback-front/src/feedback.ts` (405 method-not-allowed) and (503 receiver-not-configured) both dropped the `phase: 0` field that origin/main includes, and these two checks run BEFORE the token gate, so the change was live in today's no-token deployment. Materiality is low: the fleet sender never hits either path (POST-only, secret configured), the verify harness asserts neither, and dropping `phase: 0` there is arguably correct since those responses are now mode-independent — but the artifact asserted byte-equivalence twice and it was checkably false.
+
+Everything else audited independently checked out:
+- **Intake chain identical**: the `handlers.ts` diff vs origin/main touches only the new `ReceiverStore` interface, the async signature, and two awaited store calls — decision order, status codes, and messages unchanged; the handlers.test.ts diff reduces to pure async-call-shape edits.
+- **Delete-after-commit + reentrancy real**: `drainOnce` guards on `ticking` (cleared in `finally`); `drainBlob` commits via a synchronous `appendFileSync` before `await client.del`; the quarantine path preserves-then-clears; pagination re-lists the first page with zero-progress and maxBatches guards; the integration test pins retransmit-after-drain dedup.
+- **Dark default holds at all three gates**: server requires `rp?.enabled === true` AND the token env (warns + stays null otherwise); the route 503s on null; the front requires `inboxToken()`. Nuance: the `BLOB_READ_WRITE_TOKEN` fallback means connecting a Blob store to the Vercel project auto-enables persistence mode — deliberate, dashboard-gated, acceptable, but it weakens "unreachable until the cutover deploy".
+- **Signal-vs-authority compliant**: no new blocking authority — `parseInboxItem` is a boundary structural validator whose failure path preserves rather than drops; all accept/reject judgment stays in the pre-existing ported defense chain. Minor imprecision (no action): §1's "empty title/description quarantines" — the code only empty-checks `feedbackId`; empty-string title/description pass (the safe direction).
+
+**Resolution (author, same session):** the concern was fixed in the design's favor of byte-identity — `phase: 0` restored on both pre-gate responses (the no-token deployment is now literally byte-identical to origin/main), the front rebundled, and the verify harness re-run green. The two nuances were folded into §1 and §6 above. Iterated and closed.
+
+---
+
+## Post-merge live-API verification (2026-06-13, activation build)
+
+Bringing the operated receiver live against the **real** Vercel Blob API surfaced one external-dependency defect not catchable by the stubbed unit tier (§6 follow-up):
+
+- **`BlobInboxClient` x-api-version 9 → 7.** The hand-rolled client declared `x-api-version: 9` (carried over from the @vercel/blob source it was pinned against). The production Blob API REJECTS this client's v7-era request shape (pathname-in-URL, simple PUT body) with `400 bad_request "Invalid pathname"` once the declared version is 9+; the newer protocol versions expect a different request format the hand-rolled client does not build. Verified live against PUT/LIST/DELETE: all succeed at `7`, all fail at `9`/`11`. Pinned to `7` (the version whose wire contract matches the request this client builds). One-line fix in the shared client → corrects BOTH the front bundle and the operated-machine drainer. Adopting the @vercel/blob 2.x (`BLOB_API_VERSION=12`) protocol is a larger rewrite, tracked as receiver hardening. **Side-effect class:** external-API contract only — no data-shape, auth, dedup-key, or rollback impact (inbox object layout + drain semantics unchanged). This is the wire-version a request declares, not what it stores.
+- **Activation evidence:** a signed HMAC POST to `https://feedback.dawn-tunnel.dev/api/feedback` returns `200 {received:true}` and the report lands durably in the Blob inbox as `inbox/<feedbackId>.json` with `verified:true, status:unprocessed` — the full §6 external surface exercised end-to-end against the live store.
+- **Operator-env note (§6):** the operated receiver's webhook secret must be set with no trailing bytes — a prod env value of `instar-rising-tide-v1` + a literal backslash-n (NOT a real newline) was found and corrected. `normalizeWebhookSecret`/`trim()` strips real whitespace but NOT a literal `\n`, so a corrupt env value silently fails the HMAC. Set via `printf` (no trailing newline).