instar 1.3.556 → 1.3.558

package/upgrades/1.3.558.md

@@ -0,0 +1,75 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- **The 5 `multiMachine.seamlessness` coherence flags** — `ws3OneVoice` (one-voice
+  election), `ws13Reconcile` (ownership reconcile), `ws41DurableAck` (durable cross-machine
+  acknowledgement), `ws43RoleGuard` (role-guard-at-spawn), `ws43JournalLease` (journal-lease
+  cutover) — **moved from a hardcoded `false` in `ConfigDefaults` to the developmentAgent
+  gate (live-on-dev / dark-fleet)**, mirroring the already-merged `ws44PoolLinks` /
+  `ws44PoolCache` precedent.
+- **Driver — operator directive (topic 13481, 2026-06-13):** "Nothing should ship dark for
+  development agents. Everything fully functional so it actually gets tested and doesn't
+  just rot." This is PR2 of that directive; PR1 (#1151) moved the 7 cross-machine memory
+  stores.
+- **How it resolves now:** each flag's `ConfigDefaults` block OMITS the literal so
+  `resolveDevAgentGate` decides — LIVE on a development agent, DARK on the fleet. Every
+  consumer read-site (the SpeakerElection, the OwnershipReconciler, the durable remote-ack
+  routes, the scheduler role-guard, the journal-lease cutover gate, and the heartbeat
+  capability advert) was routed through that one gate, and `ws43JournalLeaseDryRun` is
+  computed COHERENTLY with its gate (a dev agent runs the cutover genuinely live, the fleet
+  stays in the safe dry-run posture).
+- **The session-pool master switch is deliberately HELD.** `multiMachine.sessionPool`
+  (the active-active master plus its inbound-queue and hold-for-stability sub-flags) was NOT
+  moved. It carries a second, structurally-enforced rollout gate (`sessionPool.stage`,
+  advanced only through an end-to-end-test-gated ladder); flipping only the dev gate would
+  leave the pool inert, and forcing the stage would bypass that deliberate cutover
+  discipline. It is surfaced for an operator decision instead (advance the stage on the dev
+  mesh if active-active pooling should be dogfooded live).
+- **Fleet + single-machine agents are an unchanged no-op** — every layer resolves dark
+  exactly as before, and each is a strict no-op without a second online machine. An
+  operator's explicit per-flag setting remains the documented force-dark (false) /
+  fleet-flip (true) override.
+
+## What to Tell Your User
+
+Nothing changes for fleet agents — these multi-machine coherence features stay off for
+everyone except development agents. On a development agent that runs across two of your
+machines, the coordination layers that keep the two machines behaving as one agent (one
+voice per conversation, no double-replies, durable acknowledgements that survive a briefly
+offline machine, and a guard that keeps state-writing jobs on the right machine) now run
+live, so they finally get real-world testing before reaching everyone. There is no
+user-facing action and no behavior change on a normal install or any single-machine agent.
+The active-active session pool itself stays off pending a separate operator decision, because
+it has its own staged rollout that should advance deliberately.
+
+## Summary of New Capabilities
+
+- The five cross-machine coherence layers — single outbound voice, ownership reconcile,
+  durable cross-machine acknowledgement, the spawn-time role-guard, and the job journal-lease
+  cutover — now run LIVE on development agents (dark on the fleet) so they are actually
+  exercised across the operator's two machines instead of shipping dark everywhere.
+
+## Evidence
+
+- `tests/unit/seamlessness-dev-gate-wiring.test.ts` (13): each flag resolves live-on-dev /
+  dark-on-fleet through the gate; the dryRun coherence holds; a no-missed-consumer
+  source-string check fails CI if any consumer reverts to the raw read; the registry
+  coherence check confirms the 5 flags are dev-gated and the 3 session-pool flags stay held.
+- `tests/unit/PostUpdateMigrator-seamlessnessDevGate.test.ts` (9): the migrator strips the
+  default-shaped values, leaves operator-touched config alone, and is idempotent.
+- `tests/e2e/attention-remote-ack-alive.test.ts`: two new dev-gate cases prove the durable
+  remote-ack route goes ALIVE on a dev agent with the flag omitted and stays a 503 on the
+  fleet — the gate flips the real route, not just a registry entry.
+- `tests/unit/lint-dev-agent-dark-gate.test.ts`: the EXPECTED attribution map line numbers
+  were recomputed; the 3 session-pool flags remain as held hardcoded defaults.
+
+## Migration
+
+- `PostUpdateMigrator.migrateConfigSeamlessnessDevGate` strips a default-shaped `false` per
+  flag on update (and the paired `ws43JournalLeaseDryRun:true` only alongside a
+  default-shaped `ws43JournalLease:false`) so the gate resolves on already-deployed dev
+  agents. An operator-set value is left entirely alone — reach is not authority. Idempotent.

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/mm-pool-seamlessness-devgate.md

@@ -0,0 +1,149 @@
+# Side-Effects — multiMachine.seamlessness coherence flags → dev-gated (topic 13481), sessionPool master HELD
+
+**Change (PR2 of the no-dark-on-dev multi-machine directive):** Re-gate the 5
+`multiMachine.seamlessness` coherence flags — `ws3OneVoice` (one-voice election),
+`ws13Reconcile` (ownership reconcile), `ws41DurableAck` (durable cross-machine /ack),
+`ws43RoleGuard` (role-guard-at-spawn), `ws43JournalLease` (journal-lease cutover) — from
+hardcoded `false` in `ConfigDefaults.ts` to the developmentAgent gate (live-on-dev /
+dark-fleet), mirroring the merged `ws44PoolLinks` / `ws44PoolCache` precedent. The
+`ws43JournalLeaseDryRun` sub-knob is computed COHERENTLY with its gate (dev → live/false,
+fleet → dry-run/true). **The `multiMachine.sessionPool.*` master switch and its
+`inboundQueue` / `holdForStability` sub-flags are deliberately HELD** (see #7).
+
+**Driver:** Operator directive (Justin, topic 13481, 2026-06-13): "NOTHING should ship
+dark on development agents. Everything fully functional so it actually gets tested and
+doesn't just rot." PR1 (#1151) moved the 7 stateSync memory stores; PR2 is the remaining
+dark-on-dev multi-machine seamlessness layers.
+
+**Spec:** `docs/specs/MULTI-MACHINE-SEAMLESSNESS-SPEC.md` (the converged + approved spec the
+seamlessness flags were built against) + `docs/specs/multi-machine-replicated-store-
+foundation.md` (sessionPool context). This is a follow-up gating fix to already-merged
+features, not a new feature.
+
+## What was wrong
+
+The 5 seamlessness flags shipped with a literal `false` in `ConfigDefaults.ts` (e.g.
+`ws3OneVoice: false`). A written literal force-darks even a development agent (the #1001
+anti-pattern), so the coherence layers never ran ANYWHERE — they could never be dogfooded
+on Echo / the Mini and never graduated toward the fleet. ws44PoolLinks/ws44PoolCache had
+already been corrected to the omitted-gate pattern; these five lagged behind.
+
+## What changed
+
+- `src/config/ConfigDefaults.ts` — OMIT the hardcoded `false` for all 5 flags (each carries
+  a ws44-style "DELIBERATELY OMITTED" comment) so `resolveDevAgentGate` decides at runtime.
+  `ws43JournalLeaseDryRun` is ALSO omitted (computed coherently at the consumer). `ws13DryRun`
+  stays a plain hardcoded default `true` (it is the in-component "log intended CAS without
+  performing it" rung, NOT the dev-gate). The sessionPool block is UNTOUCHED.
+- `src/commands/server.ts` — route each consumer read through `resolveDevAgentGate(...)`:
+  - `ws3OneVoice`: `SpeakerElection.enabled` → `resolveDevAgentGate(ws3Cfg().ws3OneVoice, config)`.
+  - `ws13Reconcile`: `OwnershipReconciler.enabled` → gated; `dryRun` stays the plain `ws13DryRun !== false` read.
+  - `ws43RoleGuard`: `scheduler.setRoleGuard().enabled` → gated.
+  - `ws43JournalLease`: `setJournalLeaseCutover().enabled` → gated; `dryRun` →
+    `cfg?.ws43JournalLeaseDryRun ?? !resolveDevAgentGate(undefined, config)` (coherent).
+  - the heartbeat `seamlessnessFlags` advert resolves journal-lease via the gate, not the raw read.
+- `src/server/routes.ts` — `ws41DurableAckEnabled()` reads through
+  `resolveDevAgentGate(..., ctx.config)`, so the route + precedence guard agree.
+- `src/core/devGatedFeatures.ts` — ADD all 5 flags as `DEV_GATED_FEATURES` entries
+  (by-name, each with a non-destructive/no-egress justification). A header comment records
+  WHY the sessionPool master + sub-flags are NOT moved here (the StageAdvancer stage-gate).
+- `src/core/PostUpdateMigrator.ts` — NEW `migrateConfigSeamlessnessDevGate(config)`: strips
+  a default-shaped `false` per flag (and the paired `ws43JournalLeaseDryRun:true` only
+  alongside a default-shaped `ws43JournalLease:false`) so the gate resolves on update. An
+  operator-set value (explicit `true`, a divergent dryRun) is left ENTIRELY alone. Idempotent.
+  Wired into the migrate path with `upgraded`/`skipped` reporting.
+- `tests/unit/lint-dev-agent-dark-gate.test.ts` — EXPECTED attribution map line numbers
+  recomputed via the attributor (the 5 removed literals + comment reflow shift sessionPool
+  786→809 and cartographer 1100→1123). The 3 sessionPool flags STAY in the map (held,
+  hardcoded false). No paths added/removed (the seamlessness flags were never `enabled:`-named).
+
+## Decision-point inventory (Phase-4)
+
+### 1. Over-block
+A gate that resolved live when it shouldn't. Not possible: `resolveDevAgentGate` resolves
+true ONLY when `developmentAgent: true` (or an explicit `true`), so the fleet is byte-for-byte
+unchanged. Each layer is additionally a strict single-machine no-op (the election never
+engages below 2 online machines; the role-guard never fires when this machine holds the lease;
+the journal-lease cutover requires ≥2 flag-coherent peers).
+
+### 2. Under-block
+A consumer left on the raw `=== true` read would keep the feature DARK on a dev agent even
+though ConfigDefaults omits it (the PR1 "still-dark-on-dev = incomplete" failure). Closed by
+grepping ALL consumer sites (5 flags + the heartbeat advert + the dryRun coherence formula)
+and routing every one through the gate, then pinning it with a source-string no-missed-consumer
+wiring test (`tests/unit/seamlessness-dev-gate-wiring.test.ts`, section B) that fails CI if a
+consumer reverts to the raw read.
+
+### 3. Level-of-abstraction fit
+The gate is resolved at the SAME construction/route boundary as the ws44 precedent — one
+funnel (`resolveDevAgentGate`) reads the raw config value and the agent's `developmentAgent`
+flag. No new abstraction; the consumers' downstream `enabled`-true semantics are unchanged.
+
+### 4. Signal vs authority compliance
+Each layer runs in the SAFE direction and none gains authority from going live-on-dev:
+ws3OneVoice only WITHHOLDS a duplicate send (never fabricates one); ws13Reconcile runs in its
+own dry-run (logs intended CAS, performs none); ws43RoleGuard can only REFUSE a spawn (never
+wrongly spawn); ws41DurableAck persists an intent bound to the AUTHENTICATED operator and the
+owner REVALIDATES at apply time; ws43JournalLease coordinates job claims over durable state
+and the cutover gate guarantees the two mechanisms are never both live for a job set.
+
+### 5. Interactions
+- ws43JournalLease ↔ ws43JournalLeaseDryRun: the two MUST resolve coherently or a dev agent
+  would run live-but-dry-run (logged, never exercised) — handled by the `?? !resolveDevAgentGate`
+  formula at the consumer AND the migration's paired strip.
+- The heartbeat `seamlessnessFlags.ws43JournalLease` advert (what peers read to decide
+  coherence) now mirrors the resolved enabled+not-dry-run, so a dev agent honestly advertises
+  the capability to a peer.
+- sessionPool HELD: because the seamlessness flags have NO stage-gate, they are independent of
+  the sessionPool master — flipping them live-on-dev does not activate the (held) session pool.
+
+### 6. External surfaces
+None new. The five features' routes/behaviors already existed; this only changes WHICH agents
+resolve them live. Replication/coordination is between the operator's OWN machines — no
+external egress, no third-party spend, no new API.
+
+### 7. Rollback cost & multi-machine posture (the heart)
+- **Rollback:** trivial and per-flag — set an explicit `multiMachine.seamlessness.<flag>: false`
+  in `.instar/config.json` to force-dark even a dev agent; an explicit `true` is the fleet-flip.
+  No data migration to undo (these are coordination layers, not stores). The 3 sessionPool flags
+  need no rollback — they were never flipped.
+- **Multi-machine posture:** these layers EXIST to make the operator's two machines behave as
+  one agent. Live-on-dev means Echo (laptop) + the Mac Mini now genuinely exercise one-voice
+  election, ownership reconcile, durable cross-machine acks, the spawn-time role-guard, and the
+  journal-lease cutover across the real two-machine mesh — the only way they get tested before
+  fleet. A single-machine dev agent is a strict no-op for all five (no peers).
+- **sessionPool HELD — the deliberate exception:** `multiMachine.sessionPool.{enabled,
+  inboundQueue.enabled, holdForStability.enabled}` were NOT moved to dev-gated. They share a
+  SECOND, structurally-enforced gate: `sessionPool.stage` is **StageAdvancer-write-only** (a
+  module-private `STAGE_WRITE_TOKEN`, rejected by `stageWriteGuard.ts` for any other writer),
+  defaults to `'dark'`, and advances only through an E2E-gated rollout ladder
+  (`dark → shadow → live-transfer → rebalance`). The activation expression EVERYWHERE is
+  `enabled && stage !== 'dark'` (server.ts:1990, 1998, 14351, 15611; boot-sweep gate 7019-7024).
+  So: (a) dev-gating `enabled` alone leaves the pool INERT on a dev agent (`stage` is still
+  dark) — a hollow move that fails the directive's "actually gets tested"; and (b) forcing
+  `stage` past dark in ConfigDefaults would BYPASS the deliberate cutover discipline the
+  StageAdvancer exists to enforce — not a clean, safe-by-default, reversible change. This is a
+  genuine collision between the "nothing dark on dev" directive and an explicit structural
+  safety invariant, so it is surfaced to the operator rather than forced. **Operator decision
+  needed:** advance `sessionPool.stage` on the dev mesh via the StageAdvancer ladder (gated on
+  green E2E) if active-active pooling should be dogfooded live; until then it stays dark.
+
+## Migration parity
+
+`applyDefaults` is add-missing-only deep-merge, so a new agent gets the omitted-flag shape via
+`init`. Existing agents that received the old `false` literals would keep them (explicit values
+are not overwritten) and stay dark even on a dev agent — so `migrateConfigSeamlessnessDevGate`
+strips the exact default-shaped `false` (and paired dryRun) on update. An operator's hand-edited
+value is never touched (reach is not authority). Idempotent (a second run strips nothing).
+
+## Tests
+
+Unit: `seamlessness-dev-gate-wiring` (13 — resolution + no-missed-consumer source-seam +
+registry coherence), `PostUpdateMigrator-seamlessnessDevGate` (9), `lint-dev-agent-dark-gate`
+(line-map recomputed), `devGatedFeatures-wiring` (74), `feature-delivery-completeness` (99),
+`SpeakerElection` / `OwnershipReconciler` / `ws3-one-voice-wiring`. Integration/E2E: the
+existing `scheduler-role-guard`, `scheduler-journal-lease-cutover`, `attention-remote-ack`
+suites stay green; `attention-remote-ack-alive` E2E gains two dev-gate cases (flag OMITTED +
+developmentAgent:true → route ALIVE; fleet → 503) proving the gate flips the route, not just
+the registry. Typecheck clean (`tsc --noEmit` exit 0); full lint suite clean. The full suite is
+left to CI (the authority).