instar 1.3.575 → 1.3.577

package/upgrades/1.3.577.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**The Agent Carries the Loop (C1+C2)** — the structural enforcement of a new constitution standard (ratified by Justin, 2026-06-13/14): a commitment is the agent's obligation to *act*, never the user's to *remember*. The user is pulled in only for a usable result or a genuine authorization the agent lacks — never to be the agent's memory or to-do list.
+
+Commitments now carry two orthogonal fields — `owner` (agent | user) ⟂ `blockedOn` (none | external | user-input | user-authorization). Agent-owned commitments drive the agent (the PromiseBeacon suppresses status pings to the user via a new `emitUserSend()` chokepoint); the user hears from the agent only on a result. Nothing can park silently forever: an external-blocked commitment must record falsifiable dependency-probes (`POST /commitments/:id/probe`), and a forever-wait raises ONE honest Attention dead-letter past a window/ceiling — never a nag, never silence. A terminal failure is rerouted to the dead-letter, never swallowed. Stale promises auto-close ONLY on objective evidence (a superseder reaching terminal-success); "abandoned" is never auto-closed (the CMT-1101 scar). Two signal-only detectors (B19 parked-on-user, B20 internal-id-leak) feed `MessagingToneGate`. A guarded `POST /commitments/:id/transition` allows in-place state changes that re-run the gate.
+
+Ships **dark on the fleet / live-in-dry-run on the development agent** (`commitments.agentOwnedFollowthrough`): on a dev agent the owner-gate, governor, and reconciler run the full decision loop and *log* what they would do, but suppress/mutate nothing until a deliberate `dryRun:false` flip. The autonomy ratchet ("Blockers Are Autonomy Opportunities") is carved to a tracked follow-on (`agent-autonomy-ratchet`).
+
+## What to Tell Your User
+
+Nothing to announce for fleet users yet — this ships **dark** (off on the fleet) and runs in **dry-run only** on the development agent first (it watches and logs, changing no behavior). It is the groundwork for a real improvement: going forward, when the agent promises to do something, *the agent* owns following through — you'll never be asked to remember or chase it; you'll hear back only when there's a result or a genuine approval only you can give. The behavior change reaches you only after it has soaked safely in dry-run and is deliberately promoted.
+
+## Summary of New Capabilities
+
+- `POST /commitments/:id/probe` — record an external-dependency probe (resets the staleness window).
+- `POST /commitments/:id/transition` — guarded in-place owner/blockedOn change (re-runs the well-formedness gate).
+- `owner` / `blockedOn` / `actionClass` / `supersededBy` fields on commitments (back-filled for existing agents).
+- Config: `commitments.agentOwnedFollowthrough` (dark-on-fleet / live-in-dry-run-on-dev; tuning dials for the staleness window/ceiling/sweep).
+
+## Evidence
+
+- 244 tests green across the C1+C2 suites: unit (state model, owner-gate chokepoint, external-block governor, evidence-gated reconciler, signal detectors, sync-clamp, transitions) + the E2E "feature is alive" test (probe/transition routes return real results through the production AgentServer; owner/blockedOn round-trip; forward gate returns 400 over HTTP).
+- `npx tsc --noEmit`: 0 errors. Existing suites unaffected (beacon, tone-gate, CommitmentsSync, ConfigDefaults, dev-gate wiring, feature-completeness, standards-registry guards).
+- Converged spec (`docs/specs/agent-owned-followthrough.md`, 5 rounds + cross-model codex/gemini) + side-effects review + independent second-pass concur.

package/upgrades/side-effects/agent-owned-followthrough.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — The Agent Carries the Loop (agent-owned-followthrough, C1+C2)
+
+**Version / slug:** `agent-owned-followthrough`
+**Date:** 2026-06-14
+**Author:** echo
+**Second-pass reviewer:** required (touches PromiseBeacon / MessagingToneGate / reconciler auto-close) — see Phase 5 appendix.
+
+## Summary of the change
+
+Implements C1+C2 of the "The Agent Carries the Loop" spec (converged + operator-ratified 2026-06-14): a commitment is the agent's obligation to act, never the user's to remember; the user is pinged only for a result or a genuine authorization. Adds an `owner` ⟂ `blockedOn` state model to `Commitment` (`CommitmentTracker.ts`) with `record()`/`transitionState()` well-formedness gates + `loadStore()` back-fill; an owner-gated outbound chokepoint `PromiseBeacon.emitUserSend()` (suppresses agent-owned status sends, reroutes terminal failures to the Attention dead-letter); an external-block staleness governor (`sweepExternalBlocks()`) + `POST /commitments/:id/probe` + absolute ceiling; an evidence-gated graveyard reconciler (`reconcileGraveyard()`); a guarded `POST /commitments/:id/transition` route; a `commitments-sync` receive enum-clamp (`CommitmentsSync.applyPage`); two signal-only detectors (`parked-on-user.ts`, `internal-id-leak.ts`) feeding new `MessagingToneGate` rules B19/B20 + a beacon-local B-IDLEAK pass; server wiring of the `agentOwnedFollowthrough` resolver into `PromiseBeacon` (developmentAgent gate, sweeps lease-gated); config defaults + dev-gate registry entry + `migrateClaudeMd`/`generateClaudeMd` + the ratified constitution article. Ships dark-on-fleet / live-in-dryRun-on-dev.
+
+## Decision-point inventory
+
+- `MessagingToneGate` B19_PARKED_ON_USER / B20_INTERNAL_ID_LEAK — **add** — signal-driven LLM-authority rules; the brittle detectors only flag.
+- `CommitmentTracker.record()/transitionState()` owner/blockedOn well-formedness gates — **add** — structural validation (enum + named-authorization), never semantic prose classification.
+- `PromiseBeacon.emitUserSend()` owner-gate — **add** — suppresses agent-owned status / reroutes terminal; rollout-gated (no-op when off).
+- External-block staleness governor + reconciler auto-close — **add** — mutating sweeps, lease-gated + feature-gated + dry-run-first.
+- `external-operation-gate` (tool-call side-effect authority) — **pass-through, unchanged** — explicitly NOT modified by C1+C2 (its hardening is the C3 follow-on).
+
+---
+
+## 1. Over-block
+
+The two new gate rules are signal-only and favor false-negatives (fail toward sending). **B19 over-block risk:** a legitimate "your call" on a genuine value/taste/spend decision (the human-only set) — explicitly carved out in the rule (do NOT apply when the deferred thing is the user's decision, or is an authorization ask). **B20 over-block risk:** a direct answer to a user who asked for an identifier — carved out (do NOT apply when the user explicitly asked). The owner-gate (`emitUserSend`) only suppresses for `owner:'agent'` commitments AND only when the feature is enabled+live; `owner:'user'` and feature-off always send. No user-facing message is hard-blocked by this change — the gate authority decides with carve-outs, and beacon suppression only drops *agent-owned status pings the user is not supposed to get*.
+
+## 2. Under-block
+
+B19/B20 are brittle regex signals — trivially reworded to evade (e.g. "I'll let you handle the restart" dodges the B-PARK phrase list). This is acceptable: they are SIGNALS, not the authority, and the spec is explicit they are a mitigation, not a complete fix. The owner-gate misses a genuinely-stuck `owner:'agent'` commitment only if the agent mis-declares its state — but the single covering invariant + the §4.4 window dead-letter + the §4.5 reconciler ensure no agent-owned non-terminal commitment stays silent past a bound. B20 does NOT replace `redactSecrets`/`guardProxyOutput` (real secret/path disclosure stays enforced by those).
+
+## 3. Level-of-abstraction fit
+
+Correct. The detectors (`parked-on-user`, `internal-id-leak`) are low-level brittle SIGNALS; `MessagingToneGate` (the existing full-context LLM) is the AUTHORITY (B19/B20 combine signal + conversational context, with carve-outs). The owner-gate lives INSIDE `PromiseBeacon` (not the tone gate) precisely because beacon sends are `isProxy:true` and bypass the gate. The reconciler reuses the existing `verify()`/`isUnverifiableOneTime` scar machinery rather than re-implementing closure. The ratchet's authority (C3) is deliberately NOT built here — the existing tool-call `external-operation-gate` is the unchanged side-effect authority.
+
+## 4. Signal vs authority compliance
+
+**Reference:** docs/signal-vs-authority.md
+
+- [x] **No — this change produces a signal consumed by an existing smart gate.** B19/B20 are signal-driven rules; the brittle `parked-on-user`/`internal-id-leak` detectors flag, the full-context `MessagingToneGate` LLM decides (with carve-outs, fail-toward-sending). The `record()` well-formedness gates are structural (enum validity + named-authorization presence) — a deterministic well-formedness check at the right layer (the store), mirroring the operator-binding "blank uid refused" pattern, never a semantic judgment. The owner-gate suppression is a routing decision on the agent's OWN status output (not a user-message block), gated by the feature flag. No brittle logic holds user-message block authority.
+
+## 5. Interactions
+
+- **Shadowing:** the owner-gate sits at the beacon's send sites (after the existing snapshot/atRisk/liveness logic); it suppresses the send for `owner:'agent'` but does not shadow `verify()` or the escalation ladder (rung3 still surfaces). B20 is additive to the existing jargon/file-path signals (does not shadow `redactSecrets`).
+- **Double-fire:** the governor + reconciler share the beacon's slow sweep timer (lease-gated, one machine) — they don't race the 60s `verify()` sweep. The governor dedupes via `externalBlockDeadLetteredAt`; the reconciler is bounded by `maxClosesPerPass`.
+- **Existing tests:** beacon (90+), tone-gate (36), CommitmentsSync (17), ConfigDefaults (52), dev-gate wiring (52), feature-completeness (99) all stay green — the feature-off default preserves current behavior byte-for-byte.
+
+## 6. External surfaces
+
+New HTTP routes: `POST /commitments/:id/probe`, `POST /commitments/:id/transition` (Bearer-auth, cross-machine routed like `/deliver`). New `Commitment` fields ride the existing `commitments-sync` replication (enum-clamped on receive). The dead-letter reuses the existing `raiseAttention` Attention surface (HIGH-priority, deduped). Mobile-Complete: the user-facing surfaces are an Attention item + plain Telegram messages — phone-complete; no operator CLI/file step introduced. Operator-Surface-Quality: the dead-letter is plain English ("I've been waiting on … want me to keep waiting or drop it?"), no raw internals.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+- `owner`/`blockedOn`/`actionClass`/`lastProbe`/`supersededBy` — **replicated** via the existing `commitments-sync` mesh path (additive on `extends Commitment`), **enum-clamped on receive** (`CommitmentsSync.applyPage`, defaults agent/none). Replicated rows are advisory, never authoritative.
+- The governor + reconciler sweeps — **machine-local execution, lease-gated** (`holdsLease` via `leaseCoordinatorRef`): only the lease-holder runs the mutating sweep, so no cross-machine double-dead-letter / double-close. Single-machine → always runs (safe no-op gate).
+- The probe/transition routes — **proxied to the owning machine** (mirror `/deliver`'s `resolveCommitmentRoute`/`forwardMutation`, new cross-machine `probe`/`transition` ops on `CommitmentMutateOp` + `MeshRpc`).
+- User-facing notices ride the beacon's existing one-voice speakerElection gate.
+
+## 8. Rollback cost
+
+Cheap. Ships dark-on-fleet (the developmentAgent gate resolves `enabled` false for the fleet) and live-in-dryRun-on-dev (`dryRun` defaults true → the owner-gate/governor/reconciler LOG what they would do but suppress/mutate nothing). Off-switch: set `commitments.agentOwnedFollowthrough.enabled: false` (or leave the gate's fleet default). A bad behavioral interaction is reverted by flipping `enabled` off (config, no code revert) or `dryRun: true`. No data migration to undo — the new `Commitment` fields are additive/optional and back-filled idempotently; turning the feature off leaves them inert. No destructive credential/state action anywhere in C1+C2.
+
+---
+
+## Phase 5 — Second-pass review verdict
+
+**Concur with the review.** An independent reviewer verified all six load-bearing safety properties against the actual code (not the artifact's claims):
+1. Signal-vs-Authority — the detectors hold zero block authority; B19/B20 are LLM-gate rules (fail-open, favor false-negatives); the owner-gate suppresses only the agent's own `isProxy` status sends, never a user-message block.
+2. The reconciler closes ONLY on `supersededBy`→terminal-success; no time/"abandoned" auto-close branch exists (CMT-1101 scar intact).
+3. `emitUserSend` reroutes terminal failures to `raiseAttention` (never swallowed); rollout-gated (off/owner:user → unchanged; dryRun → still sends).
+4. The governor + reconciler sweeps are lease-gated (`holdsLease()`) AND feature-gated (off → no-op; dryRun → no mutation/dead-letter).
+5. Genuinely dark-on-fleet / live-in-dryRun-on-dev (`resolveDevAgentGate` + dryRun default true); feature-off path is byte-for-byte prior behavior.
+6. `external-operation-gate` is NOT in the C1+C2 change set — its fail-posture is unchanged (the hardening is the C3 follow-on).
+
+**Non-blocking observation (carried to the C3 follow-on, CMT-1505):** the `CommitmentsSync` receive clamp covers `owner`/`blockedOn` (the routing-significant enums) but not `actionClass`/`lastProbe` — both inert/non-authoritative in C1+C2, so no exploitable branch today; clamp them when `actionClass` becomes load-bearing in the ratchet build.

package/upgrades/side-effects/ws2-send-2b-userregistry.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — WS2-SEND-2b: userRegistry send-side replication
+
+**Version / slug:** `ws2-send-2b-userregistry`
+**Date:** `2026-06-15`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `not required` (no block/allow/lifecycle authority — additive, dark-gated data-replication wiring; see §4)
+
+## Summary of the change
+
+Extends WS2 send-side emission to the `userRegistry` store (the SECOND PII kind; WS2-SEND-2b). Unlike the seamed memory stores, `userRegistry` has NO single canonical UserManager — telegram (send-only mode + normal mode) and slack each construct their OWN long-lived `UserManager` against the same `users.json`. So a single shared attacher (`attachUserReplication`, defined in `src/commands/server.ts` right after the emitter is constructed) wires the journal-backed emitter to each long-lived instance at its construction site (`userManagerSendOnly`, `userManager`, `slackUserManager`). `ws2SendWiring.ts` moves `userRegistry` PENDING→WIRED (leaving only `preferences`). The union reader + projection already shipped (WS2.6). New e2e round-trip.
+
+Channel-keyed identity — the local `userId` NEVER crosses. `upsertUser→persistUsers` fires emitPut for every surviving user; `removeUser` fires the channel-keyed emitDelete tombstone.
+
+## Decision-point inventory
+
+- `ReplicatedRecordEmitter.emit` dark gate (`stateSync.userRegistry.enabled`) — **pass-through** — pre-existing; `userRegistry` becomes a registered emit target. Default false ⇒ no-op.
+- `UserManager.persistUsers` / `removeUser` emit funnels — **pass-through** — already fire; this attaches a real emitter at each long-lived instance.
+- `ws2SendWiring` ratchet — **modify** — `userRegistry` reclassified PENDING→WIRED.
+
+---
+
+## 1. Over-block
+No block/allow surface. The emitter never rejects a user write; null recordKey / null projection / over-cap is a counted no-op and the local write always succeeds.
+
+## 2. Under-block
+Not applicable (no block surface). **Honest capture-scope note** (the load-bearing caveat): the in-process emitter fires on the SERVER-PROCESS user-write paths — telegram (both modes) + slack inbound registration, which are the dominant user-creation paths. TWO secondary paths are NOT covered, by design, and are stated rather than silently dropped:
+  1. The Slack org-permission **admin** route (`buildSlackRegistry` in routes.ts) constructs a per-request UserManager; reaching the emitter there needs RouteContext plumbing disproportionate to a secondary admin flow.
+  2. The `instar user add` **CLI** runs in a SEPARATE PROCESS, so it can never fire the server's in-process emitter; the send-side snapshot reads the journal's own entries, not `users.json`, so a CLI-only user is a known gap.
+This matches the accepted in-process capture scope of relationships/knowledge. A single write funnel (one canonical UserManager) would close both gaps and is a reasonable future refactor; it is out of scope for "identical wiring."
+
+## 3. Level-of-abstraction fit
+Correct layer. A shared attacher at the construction sites is the minimal change that captures the multiple long-lived instances without a refactor. The projection lives in `UserRegistryReplicatedStore` beside the receive-side schema.
+
+## 4. Signal vs authority compliance
+Compliant. No blocking authority. The emitter is additive/best-effort (the funnel swallows + counts faults; a user write can never fail because replication did). **REQ-M14 (Know Your Principal):** a replicated user record is UNTRUSTED peer data and is NEVER the authoritative answer to "who is this inbound sender?" — inbound-principal resolution stays LOCAL-ONLY (the local channel index always wins). The union read is advisory HIGH-tier. Per `docs/signal-vs-authority.md`.
+
+## 5. Interactions
+- Uses server.ts's single `replicatedRecordEmitter` via the shared `attachUserReplication` helper. Distinct store key/kind from the other WS2 stores. No double-fire (each instance rides its own persistUsers funnel; the same person on two instances collapses to one channel-keyed recordKey).
+- Touches `server.ts` + `ws2SendWiring.ts` (the shared WS2-SEND files) → serialized on top of merged topicOperator; no parallel WS2-SEND PRs.
+
+## 6. External surfaces
+Dark by default (`multiMachine.stateSync.userRegistry`). Off ⇒ byte-identical single-machine behavior. On (multi-machine, opt-in): crosses the channel-keyed profile projection (name, channels, permissions) — never the local userId. Same at-rest honesty as relationships (transit encrypted; at-rest plaintext per machine). A received record is quoted `<replicated-untrusted-data>`, advisory only.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+**Replicated.** Path: `upsertUser/removeUser → persistUsers → emit → CoherenceJournal.emitReplicatedRecord → peer serve/apply → ReplicatedPeerStreamReader → userRegistryUnionReader`. Identity = channel set (the same person on two machines collapses to one recordKey). removeUser propagates a channel-keyed tombstone (no resurrection). Verified end-to-end by the new e2e (put round-trip + channel-set collapse + removeUser tombstone resolves to no-record).
+
+## 8. Rollback cost
+Trivial. Dark by default. Back-out = revert the server.ts + ws2SendWiring.ts change or set the flag false (instant, no migration). Receive-side + envelope schema already shipped, unaffected.