instar 1.3.587 → 1.3.589

package/upgrades/1.3.589.md

@@ -0,0 +1,68 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A new constitutional standard — **"Live-User-Channel Proof Before Done"** — plus its
+structural enforcement, plus the first feature held to it: the cross-machine topic-transfer
+fix.
+
+- **The standard** (`docs/STANDARDS-REGISTRY.md`): a user-facing feature is not "done"
+  until a user-role session has driven it end-to-end through its real user surface
+  (Telegram AND Slack for a channel feature) before the operator is ever asked to test.
+  Migrated to existing agents via the CLAUDE.md template + `PostUpdateMigrator`.
+- **The completion gate** (`LiveTestGate` + `LiveTestArtifactStore`, wired into
+  `POST /autonomous/evaluate-completion`): refuses a "done" verdict for a user-facing
+  feature without a verified, signed live-test artifact. Ships DARK + dev-gated
+  (`monitoring.liveTestGate`, mode dry-run) — it COMPUTES the veto and logs it, but only
+  `mode:veto` overrides a verdict, and even then the only effect is keeping the run
+  working (the safe direction).
+- **The user-role harness core** (`LiveTestHarness`): runs a scenario matrix as the user
+  over an injected channel driver, writes the signed artifact the gate reads, and refuses
+  volatile/permission scenarios on a non-demo channel.
+- **The transfer fix** (`LocalSessionOwnershipStore` + `OwnershipApplier`, wired DARK
+  behind `multiMachine.durableOwnership`): the cross-machine ownership store is now durable
+  and replicated (it materializes ownership on the target from the replicated placement
+  journal), so a topic seat genuinely moves between machines. `POST /pool/transfer` now
+  reports an honest `seatMoved` instead of a bare `ok:true`.
+
+## What to Tell Your User
+
+Nothing changes in normal use yet — everything ships dark behind flags and is dogfooded on
+development agents first. The point of the work: I should never again report a feature
+"done" without having tested it the way *you* would — by acting as you, through the real
+channels — so you stop being the one who discovers a broken feature. The first feature held
+to that bar is the "move a conversation between my machines" fix.
+
+## Summary of New Capabilities
+
+- `GET`/route surface: the completion gate post-checks `/autonomous/evaluate-completion`
+  (dark/dev-gated, dry-run default).
+- `POST /pool/transfer` now returns `seatMoved` (+ a reason when false).
+- New dev-gated flags: `monitoring.liveTestGate.{enabled,mode}`,
+  `multiMachine.durableOwnership.enabled` (both omit `enabled` → live-on-dev / dark-fleet).
+- The constitution carries the "Live-User-Channel Proof Before Done" standard, migrated to
+  existing agents.
+
+## Evidence
+
+**The bug being fixed (transfer):** 2026-06-15, the operator ran `POST /pool/transfer
+{topic, to:"Mini"}` on a live Telegram topic. Observed BEFORE: response `ok:true`, but the
+seat never moved — the next message routed back to the Laptop (the operator found it on the
+first live interaction). Root cause, grounded in the running code (v1.3.586):
+`SessionOwnershipRegistry` used `InMemorySessionOwnershipStore` with no cross-machine
+replication — the placement was written into the source machine's in-memory Map and never
+materialized on the target (`server.ts:16002` owner-resolution reads null → `SessionRouter`
+treats it as unowned → places locally instead of forwarding).
+
+**Observed AFTER (in tests — live hardware proof is the tracked next phase):** the durable
+store + `OwnershipApplier` converge a transferred topic to exactly one owner (the target)
+across a simulated crash mid-move (`tests/integration/ownership-transfer-crash-safety.test.ts`);
+`POST /pool/transfer` now returns `seatMoved:false` with a reason when ownership did not
+move. The gate's anti-hallucination check rejects a hand-edited artifact (hash-mismatch),
+and the wired completion route overrides a `met:true` verdict for a user-facing feature with
+no verified artifact (`tests/integration/live-test-gate-completion-route.test.ts`). 49 new
+tests across 8 files, all green; full pre-commit lint suite + tsc clean. The end-to-end LIVE
+Laptop↔Mini proof is the explicitly-tracked next phase (this ships the foundation dark).

package/upgrades/side-effects/autonomous-registration-guarantee.md

@@ -0,0 +1,51 @@
+# Side-Effects Review — Autonomous-Registration Guarantee (GAP-B)
+
+**Spec:** `docs/specs/autonomous-registration-guarantee.md` (CONVERGED 2 rounds + Part-D focused re-converge, approved:true) · P1 GAP-B
+**Change:** revive an UNregistered-but-actively-working autonomous run after an age-limit reap, by injecting commitment-evidence into the reaper's existing eligibility path (Part B, DARK) + promoting the inert `recentUserMessage` KEEP-predicate to real (Part D, the one live part) + an observe-only attention surface (Part A). Part C was already shipped (#1186).
+
+## Phase 1 — Principle check (signal vs authority)
+Touches the reaper eligibility decision, so the principle applies. **No new brittle blocking authority:** Part B injects a *signal* (a fresh qualifying open-commitment) into the **existing** `evidenceEligible`/ResumeQueue authority — it never decides revival itself. Part A is observe-only (an aggregated attention signal). Part D promotes a KEEP-*predicate* (a signal ReapGuard already consults). The load-bearing safety is the **D8 agreement-invariant**: KEEP and the new eligibility compute from ONE shared `recentUserMessage` predicate, so they cannot disagree (the 2026-06-13 13-session loop came from disagreement). Compliant (`docs/signal-vs-authority.md`).
+
+## Phase 2 — Plan
+Built in `.worktrees/gapb-autonomous-registration` (rebased onto current `JKHeadley/main c41b27db5`). Decision points: the `sessionReaped` evidence wiring (gains an additive, dark, corroborated source) + ReapGuard/SessionReaper KEEP behavior (Part D un-stub). Rollback: dark by default (Part B needs explicit `enabled:true`) + revert the PR.
+
+## 1. Over-block
+The change does not block — it injects evidence to REVIVE. The inverse risk is **over-revive** (resurrecting a finished/idle run). Bounded by: the D2 qualifying filter (pending + agent-driven + this-machine + not-beacon-paused), D1 createdAt-freshness (6h), the **D8 agreement** (also needs a recent user message — a stale-per-KEEP commitment can't revive), drain-time D9 re-validation (`commitmentStillActiveForTopic` — a since-closed commitment is invalidated), the existing **resurrection cap** (≤2 resumes/24h/topic, then gives up loudly), and — decisively — Part B ships **DARK** (no injection ⇒ no revival) until `enabled:true`.
+
+## 2. Under-block
+A genuinely-working unregistered run with **no open commitment AND no recent user message** is not revived — the structural registration guarantee (make "go autonomous" always write the state file) is the root fix, an explicitly tracked follow-up (Follow-ups section), not this PR. Part B is a *corroborated* backstop (commitment + recent activity), not a universal catch.
+
+## 3. Level-of-abstraction fit
+Correct layer. The evidence feeds the **existing** `evidenceEligible`/ResumeQueue authority (no parallel revival path; no new WorkEvidence enum value — reuses `build-or-autonomous-active` + a distinct reason tag). Part D shares ONE predicate across all consumers (`gapBCommitmentEvidence.recentUserMessageFromHistory`), so KEEP and eligibility are computed identically — the right place to enforce agreement.
+
+## 4. Signal vs authority compliance
+See Phase 1. No brittle check gains blocking authority. Part B = signal → existing gate; Part A = observe-only; Part D = a shared predicate. Fail-open throughout (D7). Compliant.
+
+## 5. Interactions
+- **The D8 loop-prevention** is the central interaction: ReapGuard's KEEP (`ReapGuard.ts:149`, 8h) and the new eligibility both call the same `recentUserMessage` — verified by the anti-loop regression test (a stale-per-KEEP commitment is NOT eligible).
+- **Part D un-stubs FIVE live sites consistently** via one shared closure spread into the single `reapGuardDeps` object backing BOTH `ReapGuard` (:137 standalone 30min, :149 commitment 8h, :221/:239 terminate-path) AND `SessionReaper` (:489 `staleIdle` inversion). All safe-direction (keep-more) — none makes the reaper kill more.
+- **Drain-time D9** re-checks liveness for `COMMITMENT_ACTIVE_RUN_REASON` (state-file source is untouched, routed by the distinct reason).
+- No double-fire: the commitment branch is mutually exclusive with the state-file branch (PRESENT vs ABSENT).
+
+## 6. External surfaces
+- Part A: ONE aggregated attention signal (`unregistered-autonomous:<topic>`, dedup'd via the existing chokepoint) — only when Part B fires LIVE. No new HTTP route.
+- Reap-log gains an optional `evidenceSource` field (additive, back-compat, no PII — D3).
+- Observable via the existing reap-log; dark by default so no user-visible behavior change until enabled.
+
+## 7. Multi-machine posture
+**Machine-local by design.** Part B's qualifying filter requires `originMachineId` is this machine or absent — a *replicated peer* commitment is advisory data, never revival authority (it can't revive a session on the wrong machine). `recentUserMessage` reads THIS machine's `TelegramAdapter.getTopicHistory`. No replicated/persisted state introduced; the per-topic state file source is unchanged. No generated URL, no cross-machine notice.
+
+## 8. Rollback cost
+Cheap and dark. (a) **Dark by default:** Part B is inert unless `monitoring.resumeQueue.commitmentEvidence.enabled === true`; even when armed it defaults to `dryRun:true` (no spawn). (b) **The one live change** (Part D `recentUserMessage` promotion) is safe-direction (keep-more) and bounded by the window — to revert just that, restore the stub. (c) **Full back-out:** revert the PR — additive code, no data migration, no state repair. The config keys are code-defaulted (absent from ConfigDefaults) so removal is clean.
+
+## No-deferrals (Phase 4.5)
+The structural registration guarantee (root fix) and the stopGate per-topic plumbing are explicitly **tracked** follow-ups (Follow-ups section, `<!-- tracked -->` markers) — Part B is a deliberate *corroborated backstop*, the honest scope, not a partial fix papering over the root.
+
+## Phase 5 — Second-pass review
+*(appended below)*
+**Concur with the review.** An independent reaper-class reviewer verified the load-bearing safety against the real code (file:line), not the artifact:
+- D8 agreement: the SAME closure `recentUserMessageShared` backs both GAP-B eligibility (`gapBCommitmentEvidence.ts:150`) and ReapGuard's commitment KEEP (`ReapGuard.ts:149`/:239), with a single-sourced window (`staleCommitmentWindowMinutes ?? 480`); GAP-B's `commitmentQualifies` is a strict superset-filter of ReapGuard's, so a GAP-B revive structurally implies KEEP would have fired — the 2026-06-13 loop is impossible.
+- Dark containment airtight: armed only on `enabled===true`, dryRun-default-true; dryRun fires the Part A surface only, tags/injects nothing; disarmed skips the cost-bearing eligibility entirely.
+- All 5 `recentUserMessage` sites (ReapGuard 137/149/221/239 + SessionReaper 489) consume the real shared predicate (stub at server.ts removed); tsc-clean proves no mismatch; all safe-direction (keep-more).
+- Fail-open (D7) + D9 drain-revalidation verified both sides (`safeBool(..., true)` → throw resolves still-active, never a wrong drop); multi-machine strand closed by the `originMachineId` local-origin filter.
+- No new failure mode, double-fire (commitment vs state-file branches mutually exclusive), or cross-machine revival risk.

package/upgrades/side-effects/live-user-channel-proof-standard.md

@@ -0,0 +1,54 @@
+# Side-Effects Review — Live-User-Channel Proof standard + multi-machine transfer fix
+
+**Spec:** docs/specs/live-user-channel-proof-standard.md (CONVERGED iter 6, cross-model external review, self-approved under standing autonomous pre-approval — Justin topic 13481). **Tracking:** CMT-1568. **Parent principle:** Structure beats Willpower / Observation Needs Structure.
+**Ships DARK + dev-gated:** `monitoring.liveTestGate` (mode dry-run) and `multiMachine.durableOwnership` — both OMIT `enabled` so `resolveDevAgentGate` flips them live-on-dev / dark-on-fleet. Single-machine installs are a strict no-op for the transfer fix.
+**Files:** src/core/LocalSessionOwnershipStore.ts (new), src/core/OwnershipApplier.ts (new), src/core/LiveTestArtifactStore.ts (new), src/core/LiveTestGate.ts (new), src/core/LiveTestHarness.ts (new), src/core/devGatedFeatures.ts, src/commands/server.ts, src/server/AgentServer.ts, src/server/routes.ts, src/scaffold/templates.ts, src/core/PostUpdateMigrator.ts, docs/STANDARDS-REGISTRY.md, docs/specs/live-user-channel-proof-standard.md (+ .eli16.md + report), tests/unit/* + tests/integration/* (8 new test files, 49 tests).
+
+## What changed
+
+1. **LocalSessionOwnershipStore.ts (new):** a DURABLE per-session ownership substrate implementing the existing store-agnostic `SessionOwnershipStore` interface (read + casWrite). Per-session JSON files, atomic tmp+rename, in-memory hot-path cache, fast-forward CAS. Replaces the in-memory-only store (the transfer bug's root) behind the dev-gate.
+2. **OwnershipApplier.ts (new):** off-hot-path tick that materializes durable LOCAL ownership from the REPLICATED coherence-journal placement entries (read via `CoherenceJournalReader.query({kind:'topic-placement'})`), so the machine a topic moved TO resolves the right owner. Fast-forward CAS only (a stale replicated entry can never clobber a fresher local decision).
+3. **server.ts:** behind `resolveDevAgentGate(multiMachine.durableOwnership.enabled)`, swaps `InMemorySessionOwnershipStore` → `LocalSessionOwnershipStore` and ticks the `OwnershipApplier` (interval + boot). Off → today's exact behavior.
+4. **routes.ts (`POST /pool/transfer`):** adds an honest `seatMoved` field computed from the real post-transfer owner (+ `seatMoveReason` when false). `ok:true` now means "request processed", `seatMoved` means "the conversation actually runs on the target". Closes the 2026-06-15 `ok:true`-but-never-moved lie.
+5. **LiveTestArtifactStore.ts (new):** the §4.4 signed, hash-chained artifact contract. Canonical serialization → sha256 → Ed25519 signature; per-machine ledger segments (`state/live-test-ledger.<machineId>.jsonl`, union-on-read — no cross-machine concurrent append). The gate re-reads + recomputes the hash, so a hand-edited "I tested it" record fails (the anti-hallucination core). Threat model: drift-correction, NOT an adversarial-runner security boundary (git-commit anchor is the backstop).
+6. **LiveTestGate.ts (new):** the §4 completion-gate brain. allow/veto/nudge over surfaces (§4.5) + risk categories (§4.6) + BLOCKED taxonomy + the seatMoved poison rule. Signal-vs-Authority: the keyword classifier holds NO standalone blocking authority — a HARD veto requires a DECLARED `userFacing:true` + no verified artifact; an undeclared-but-classified goal gets a soft return-to-work NUDGE.
+7. **server.ts + AgentServer.ts + routes.ts (gate wiring):** server.ts constructs the gate dev-gated (mode dry-run default), signing+verifying with the machine-identity keypair (`idMgr.loadSigningKey()` + derived public key). Threaded through `AgentServer` options → `RouteContext`. `POST /autonomous/evaluate-completion` post-checks a `met:true` verdict: veto-mode overrides `met:true`→`met:false`; dry-run/warn surface the would-block but honor the verdict; a gate error falls through (completion judge stays primary authority).
+8. **LiveTestHarness.ts (new):** the §5 user-role scenario runner over an injected `ChannelDriver` (send/awaitReply/isDemoChannel). §5.3 structural guard refuses volatile/permission scenarios on a non-demo channel BEFORE any send. Deterministic verdicts off captured protocol evidence (reply text + responder machine id). §5.5 timeout=FAIL after bounded retries. (Real Telegram/Slack/dashboard drivers + the live proof are the tracked follow-on phase.)
+9. **devGatedFeatures.ts:** two new entries — `liveTestGate` (monitoring.liveTestGate.enabled) and `durableOwnership` (multiMachine.durableOwnership.enabled), each with a non-destructive justification.
+10. **STANDARDS-REGISTRY.md + templates.ts + PostUpdateMigrator.ts:** the "Live-User-Channel Proof Before Done" standard article + the CLAUDE.md awareness section (generateClaudeMd + content-sniffed migrateClaudeMd), registered in the feature-delivery-completeness parity gate (legacyMigratorSections).
+
+## Blast radius
+
+- **Config-gated, not wiring-gated.** With both flags dark (fleet default), every seam is a strict no-op: server.ts keeps `InMemorySessionOwnershipStore` + never constructs the applier; the gate is never constructed (`ctx.liveTestGate` null) so `/autonomous/evaluate-completion` returns the raw verdict exactly as today. On a dev agent the durable store + applier go live (no destructive write — atomic per-session JSON, reversible to InMemory) and the gate runs in dry-run (computes + logs, never overrides).
+- **The gate cannot cause a false "done."** It only ever turns a `met:true` into `met:false` (keep working — the safe direction) and only in `mode:veto`; it can NEVER turn `met:false` into `met:true`. A gate error falls through to the original verdict.
+- **The transfer fix changes cross-machine routing authority but only on dev.** The applier adopts only strictly-newer placements (epoch fast-forward), so it can't strand a topic ownerless or create a second owner (crash-safety proven by the integration test). Single-machine = no peer placements = no-op.
+- **No new HTTP route.** The gate post-checks an EXISTING route; the transfer fix adds a field to an EXISTING route. No new MeshRpc verb, no broadcast.
+
+## Risk + mitigation
+
+- **Risk:** the durable store / applier mis-routes on a dev agent. **Mitigation:** dev-gated + 18 tests (durable persistence, restart-survival, fast-forward CAS, crash-safety single-owner convergence, no-split-brain). Reversible by flipping the flag (the journal remains the source of truth).
+- **Risk:** the gate wrongly vetoes a legitimate completion. **Mitigation:** dry-run default (never overrides); HARD veto only on the objective `userFacing:true` + no-artifact; a gate error falls through; 11 gate-logic tests + 6 route wiring-integrity tests cover both sides of every boundary.
+- **Risk:** an agent hand-writes an artifact to buy the exit. **Mitigation:** the artifact is canonical-hashed + Ed25519-signed + re-verified from disk at gate time; a hand-edit fails the hash check (proven). Honest threat model: drift-correction, not adversarial-runner.
+- **Risk:** a gate/store error fails the completion route or server boot. **Mitigation:** every new path is try/catch-guarded toward the safe direction (no veto / today's verdict / InMemory store); server boot never fails on a gate-wiring error.
+
+## Migration parity
+
+- New dev-gated flags OMIT `enabled` in config (resolveDevAgentGate handles them) — no `migrateConfig` change needed; registered in `DEV_GATED_FEATURES` (the wiring test guards them).
+- The "Live-User-Channel Proof Before Done" CLAUDE.md section ships in `generateClaudeMd` (new agents) + an idempotent content-sniffed `migrateClaudeMd` patcher (existing agents), and is tracked in `feature-delivery-completeness` `legacyMigratorSections`.
+- The STANDARDS-REGISTRY.md article ships with the package (auto-distributed to existing agents).
+
+## Dark-gate line-map
+
+- UNCHANGED. No new inline `enabled: false` line was added to `ConfigDefaults.ts` — both new flags rely on OMISSION (the dev-gate convention), so no `enabled:` line shifted. Verified: `node scripts/lint-dev-agent-dark-gate.js` → clean.
+
+## Rollback
+
+- Revert the branch, OR leave the flags dark (fleet default = no behavior change). The durable-ownership flag is reversible to `InMemorySessionOwnershipStore` with no data loss (the coherence journal remains authoritative). The gate flag dark = the completion route returns the raw verdict as today.
+
+## Evidence
+
+- 49 new tests across 8 files (unit + integration), all green. Full unit suite green (the one transient passes in isolation — a flaky port race, not a regression). tsc clean; the full pre-commit lint suite (14 lints) clean; dark-gate lint, dev-gate wiring test, no-silent-fallbacks ratchet, feature-delivery-completeness all green.
+- Spec converged through 6 rounds (6 internal reviewers + cross-model GPT + Gemini external); convergence report at docs/specs/reports/live-user-channel-proof-standard-convergence.md.
+- **NOT yet done by its own standard:** the live Laptop↔Mini proof (the real-channel drivers + the deploy) is the tracked next phase; this PR ships the structural foundation DARK, with the flag flip gated on that live proof.
+
+<!-- decision-audit trace anchor: CMT-1568 -->