instar 1.3.605 → 1.3.607

package/upgrades/side-effects/autonomous-progress-heartbeat-ratchet-fix.md

@@ -0,0 +1,36 @@
+# Side-effects review — heartbeat no-silent-fallbacks ratchet fix
+
+## Change
+
+Comment-only. Adds `@silent-fallback-ok` exemption markers (with written
+justifications) to three fail-safe `catch` blocks introduced by the
+autonomous-progress-heartbeat feature:
+
+- `src/monitoring/AutonomousProgressHeartbeat.ts` — heartbeat send-failure catch
+  (already surfaced via `recordSuppressed` + `send-error` event).
+- `src/monitoring/AutonomousProgressHeartbeat.ts` — `mostRecentOutboundAt`
+  history-read catch (fail-closed sentinel return).
+- `src/core/AutonomousSessions.ts` — `readAutonomousRunMarkers` state-file read
+  (a missing `.local.md` is the expected no-run case; null is normal control flow).
+
+## Side effects
+
+- **Runtime behavior:** NONE. The edits are inside comments only; no executable
+  line changed. `tsc` is unaffected (comments).
+- **Tests:** `tests/unit/no-silent-fallbacks.test.ts` count returns from 479 to
+  476 (== baseline), so the ratchet passes. No other test is touched.
+- **Config / migrations:** none. No agent-installed file changes; no
+  CLAUDE.md/template/hook/skill changes; no PostUpdateMigrator change needed.
+- **External operations:** none. No network, no fs writes, no session spawns.
+- **Security:** none. The exemptions document why each catch is fail-safe; they
+  do not weaken any error path — the errors were already surfaced or fail-closed.
+
+## Signal vs authority
+
+N/A — no decision/gating surface changes. The exemption markers are a static
+lint annotation read only by the ratchet test.
+
+## Rollback
+
+Revert the commit; the three comments disappear and the ratchet returns to 479
+(which is exactly the pre-fix CI-red state). No data or state to unwind.

package/upgrades/side-effects/autonomous-progress-heartbeat.md

@@ -0,0 +1,40 @@
+# Side-Effects Review — AutonomousProgressHeartbeat (liveness backstop for a silent-to-user autonomous run)
+
+**Spec:** docs/specs/autonomous-progress-heartbeat.md (converged — 3 rounds, 6 internal reviewers + GPT-5.5 + Gemini-2.5-pro, review report at docs/specs/reports/autonomous-progress-heartbeat-convergence.md). **Constitutional principle served:** Structure > Willpower (converts "report every ~30m" from a prompt wish into a timer-driven backstop).
+**Ships DARK** behind `monitoring.autonomousProgressHeartbeat.enabled` (omitted in defaults → the dev-agent gate resolves it live-on-dev / dark-on-fleet) **and dryRun-first**. Off everywhere by config until a deliberate flip. Single change of behavior even when live: it may ADD one hedged line to a topic; it never blocks, delays, or rewrites anything.
+**Files:** src/monitoring/AutonomousProgressHeartbeat.ts (new), src/monitoring/autonomousHeartbeatScrub.ts (new), src/commands/server.ts, src/monitoring/sentinelWiring.ts, src/server/routes.ts, src/server/CapabilityIndex.ts, src/config/ConfigDefaults.ts, src/core/devGatedFeatures.ts, src/core/types.ts, src/core/AutonomousSessions.ts, src/core/PostUpdateMigrator.ts, src/scaffold/templates.ts, src/monitoring/ProxyCoordinator.ts, plus 3 test files.
+
+## What changed
+
+1. **AutonomousProgressHeartbeat.ts (new):** the watcher. On a tick it evaluates a cheap-first predicate chain for each active autonomous run: (#1) user-silence elapsed past `userSilenceThresholdMs`; (#2) NOT mid-machine-move (reads `movedTo`/`move_suspended_at` markers via AutonomousSessions); (#3) the run has been active on THIS machine ≥ one window (destination-warmup guard); (#8) the screen frame shows genuinely fresh output (reuses the silence sentinel's existing snapshot — no extra capture). Only when ALL hold does it emit ONE hedged, observational line. Per-run cooldown + widening backoff cap the volume (~handful over a 24h run).
+2. **autonomousHeartbeatScrub.ts (new):** scrubs the "last observed activity" focus text for secrets/paths before it can appear in a user-facing line. Fail-closed: an unscrubable/empty focus suppresses the line rather than risk a leak.
+3. **server.ts / sentinelWiring.ts:** constructs + starts the watcher behind the gate, mirroring the ActiveWorkSilenceSentinel wiring; shares the existing SubagentTracker snapshot rather than taking its own.
+4. **routes.ts / CapabilityIndex.ts:** `GET /autonomous-heartbeat` read-only status (current runs, per-run cooldown/backoff, last-emitted), 503 when dark.
+5. **ConfigDefaults.ts / devGatedFeatures.ts / types.ts:** the `monitoring.autonomousProgressHeartbeat` config block (enabled OMITTED → dev-gate; dryRun default true; thresholds), and the dev-gate registration.
+6. **PostUpdateMigrator.ts / templates.ts:** migrateConfig adds the config block (existence-checked); the CLAUDE.md template gains the agent-awareness section + the proactive trigger.
+
+## Blast radius
+
+- **Config-gated, not wiring-gated.** With `enabled` resolving false (fleet) the watcher is constructed-but-inert — `start()` returns before scheduling a tick, so zero behavior change. On a dev agent it resolves live but `dryRun:true` makes it LOG "would emit" without sending — observe-mode before it speaks.
+- **No new outbound path.** When it does emit, it routes through the EXISTING one-voice/dedupe send plumbing (the same path the other sentinels use), so it cannot spam or talk over another of my messages.
+- **No new capture cost.** Predicate #8 reuses the ActiveWorkSilenceSentinel's existing screen snapshot (a convergence-review fix to an earlier design that took its own).
+- **Reads only run-state files + the existing frame.** No whole-tree walk; cost is O(active runs) per tick, same class as the reaper.
+
+## Risk + mitigation
+
+- **Risk:** re-creating the "still working" filler the honest-progress work deliberately deleted. **Mitigation:** the wording is hedged + observational ("haven't posted in a while — last observed activity was X") and movement-gated (predicate #8) — never a bare-timer "still working" claim. All 8 reviewers flagged the first design; the shipped one is the rebuilt honest version.
+- **Risk:** leaking internal text/secrets into a user line. **Mitigation:** autonomousHeartbeatScrub fail-closed — an unscrubable focus suppresses the line.
+- **Risk:** a duplicate line during a cross-machine handoff (one-voice lock is machine-local). **Mitigation:** accepted bounded low-harm risk, written into the spec; predicate #2/#3 already suppress on a mid-move/just-warmed run, shrinking the window.
+- **Risk:** flooding a long run. **Mitigation:** per-run cooldown + widening backoff cap → a handful of lines over 24h, not fifty.
+
+## Migration parity
+
+- `migrateConfig` adds the `monitoring.autonomousProgressHeartbeat` block (existence-checked; only missing fields). CLAUDE.md template gains the awareness section. No hook/skill/settings change. New agents get it via init; existing agents via the update path.
+
+## Dark-gate line-map
+
+- `ConfigDefaults.ts` adds the `monitoring.autonomousProgressHeartbeat` block with `enabled` OMITTED (resolved by the dev-agent gate) + `dryRun:true`. `node scripts/lint-dev-agent-dark-gate.js` stays clean (no hardcoded `enabled:false`).
+
+## Rollback
+
+- Revert the PR, or set `monitoring.autonomousProgressHeartbeat.enabled:false` (or leave dryRun:true). The watcher goes inert; no durable state to unwind (cooldown/backoff is in-memory). Byte-identical to pre-PR behavior when off.

package/upgrades/side-effects/ws52-account-follow-me-pr1.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — WS5.2 Account Follow-Me, PR1 (shared security primitives + metadata kind)
+
+**Version / slug:** `ws52-account-follow-me-pr1`
+**Date:** `2026-06-17`
+**Author:** Echo (autonomous)
+**Second-pass reviewer:** REQUIRED (high-risk: credentials, mesh verb + RBAC, a replication JournalKind) — verdict appended below.
+**Spec:** `docs/specs/ws52-account-follow-me-security.md` (converged 2026-06-13, approved)
+
+## Summary of the change
+
+PR1 of the WS5.2 build — the SHARED SECURITY PRIMITIVES, with **NO live-credential code path** (spec §9 build-order). It makes cross-machine account/quota sharing possible the ToS-safe way (re-mint per machine; no Claude OAuth token copied). Six primitives + the non-credential metadata kind:
+
+Files added:
+- `src/core/AccountCredentialShare.ts` — the distinct `account-credential-share` mesh verb + `AccountCredentialShareHandler` (RBAC gate BEFORE decrypt: recipient-match → mandate-verify → single-use-grant-consume → fail-closed AAD decrypt). Structurally separate from the permissive `secret-share`.
+- `src/coordination/CrossMachineMandate.ts` — `signMandateIssuance`/`verifyMandateIssuance` (asymmetric Ed25519 issuance signature; the existing HMAC proof is machine-local).
+- `src/core/PairingEpochManager.ts` — de-pair X25519 key-rotation + durable epoch anchor (`secretStoreKeyAnchor`, encrypted/keychain-backed, rollback-resistant).
+- `src/core/AccountFollowMeGrants.ts` — single-use grant ledger + per-account sum-of-leases spend ceiling + failover re-derivation + epoch fencing.
+- `src/core/SubscriptionAccountMetaReplicatedStore.ts` — the `subscription-account-meta` JournalKind schema (strict §6.1a whitelist + clamps), allowlist projection (`projectAccountToMeta` strips configHome + credentials), envelope builders, emit-seam interface, registration const.
+- Unit tests: `account-credential-crypto`, `account-credential-share`, `cross-machine-mandate`, `pairing-epoch-manager`, `account-followme-grants`, `subscription-account-meta-store`, `ws52-account-follow-me-wiring` (61 new tests).
+
+Files modified:
+- `src/core/SecretStore.ts` — NEW `encryptAccountCredential`/`decryptAccountCredential` (AAD-bound, distinct HKDF info, fail-closed). Existing `encryptForSync`/`decryptFromSync` untouched.
+- `src/core/SecretSync.ts` — `SecretShareHandler.handle` now refuses a non-`secret-share` command (credential-class data must use the distinct verb).
+- `src/core/SubscriptionPool.ts` — R0 header correction + the meta emit seam (`setMetaReplicationEmitter` + emitPut on add/update + emitDelete on remove).
+- `src/core/CoherenceJournal.ts` — `subscription-account-meta` added to JournalKind union, JOURNAL_KINDS, DEFAULT_RETENTION + the per-kind `Record<JournalKind>` literals.
+- `src/commands/server.ts` — registers the kind; injects the accountFollowMe-gated store-flag; wires the emit adapter at SubscriptionPool construction.
+- `src/config/ConfigDefaults.ts` + `src/core/devGatedFeatures.ts` — `multiMachine.accountFollowMe` dev-gated (live-on-dev, dark-on-fleet); `credentialTransport` default empty; `maxFollowMachines` 5.
+- `src/scaffold/templates.ts` + `src/core/PostUpdateMigrator.ts` — awareness section (Agent Awareness + Migration Parity).
+
+## The eight side-effect questions
+
+1. **Over-block — what legitimate inputs does this reject that it shouldn't?**
+   The `subscription-account-meta` schema rejects ANY non-whitelisted key (incl. a future `SubscriptionAccount` field). That's deliberate (allowlist), but it means a NEW account field won't replicate until added to both the source-of-truth and this whitelist — a documented, bounded maintenance cost (mirrors every other `*-record` kind). The `SecretShareHandler` now throws on a non-`secret-share` command; the only caller is the legacy secret-sync path which only ever sends `secret-share`, so no legitimate caller is blocked.
+
+2. **Under-block — what failure modes does this still miss?**
+   PR1 ships no live-credential path, so Mechanism A's at-rest plaintext residual (the framework's own config-home token, gap 6) is NOT yet addressed — it is explicitly a later-PR concern (active wipe + TTL + provider rotation). The grant ledger's `now()` is injectable but a wall-clock-only TTL can't defend a machine with a tampered clock (accepted; the AAD epoch + single-use grant are the primary defenses, not the TTL).
+
+3. **Level-of-abstraction fit.**
+   Correct layers: crypto in `SecretStore` (where the sync crypto lives), the mesh verb + handler as a standalone module (parallel to `SecretSync`, not folded into it — the spec's structural-separation mandate), the JournalKind as a `ReplicatedKindRegistry` store (matching the 8 existing kinds), the emit seam on `SubscriptionPool` (the registry owner). No logic placed above/below where it belongs.
+
+4. **Signal vs authority compliance.**
+   The RBAC gate in `AccountCredentialShareHandler` is an AUTHORITY (it gates a credential write), but it is NOT brittle: it delegates the actual authorization to injected seams (`verifyMandate` = the operator-mandate gate; `consumeGrant` = the single-use ledger), and FAILS CLOSED on every uncertainty. It never fabricates an allow. The cross-machine mandate verification is deny-by-default. No brittle check holds blocking authority.
+
+5. **Interactions.**
+   Adding a JournalKind cascades to every `Record<JournalKind>` map — all updated (caught by tsc + the existing CoherenceJournal getOwnAdvert test, which was updated). The emit gate reuses the existing `_stateSyncStoresResolved` map (injected entry) so it shares the generic emitter's dark-by-default discipline. The new verb is structurally disjoint from `secret-share` (no shared handler/decryptor). No double-fire: emit fires once per mutation after `save()`.
+
+6. **External surfaces.**
+   No new HTTP route. No new outbound egress in PR1 (the emit path is dark on the fleet; live only on a dev agent, and even then only emits the non-credential metadata projection). The metadata projection includes `email` (operator/provider PII, "never a secret") which lands at-rest in same-operator peers' plaintext journal replicas — disclosed in the spec §6.1 and the code comment. configHome + every credential field are stripped by allowlist construction.
+
+7. **Multi-machine posture (Cross-Machine Coherence).**
+   This feature IS the multi-machine work. Posture: **replicated** (the `subscription-account-meta` kind over the WS2 journal). The credential itself is **machine-local BY DESIGN** (re-mint per machine; never replicated). Authorization is **operator-rooted, not peer-quorum** — holds at pool size 1/2/N. Single-machine agents are a strict no-op (no peers; the emit gate + dark default). Cross-machine mandate auth uses the asymmetric Ed25519 path (works over the relay where the local HMAC cannot).
+
+8. **Rollback cost.**
+   Low. Everything is dark on the fleet (gate `multiMachine.accountFollowMe`, default off via the dev-gate). The JournalKind addition is additive + forward-compat (an old peer that doesn't know the kind drops it; the receive validator is present so a known peer never suspect-flags). Back-out = revert the PR; no data migration (no live credential ever written), no agent-state repair. The R0 header change is documentation-only.
+
+## What's NOT in PR1 (tracked, not deferred-orphan)
+
+Per spec §9, PR1 is the primitives + the metadata kind ONLY. The following are the spec's own subsequent build-round items, tracked in the WS5.2 spec + the autonomous task list (topic 13481):
+- Mechanism B enroll-drive (re-mint per machine, operator-mandate-gated) — the live account path.
+- The router `locallyExecutable` gate + revocation (R12) + the offline-wipe escalation.
+- The `?scope=pool` offline-fallback read that surfaces the durable replicated meta when a peer is offline (the live `?scope=pool` HTTP fan-out already serves online peers; the meta is correctly received + stored now).
+- The live-channel proof (a real operator message answered FROM the Mini using an account the Mini enrolled itself).
+
+## Second-pass review
+
+**Verdict: Concur with the review.** (Independent reviewer subagent, 2026-06-17.)
+
+The reviewer independently read all eight files, ran the seven WS5.2 test files (63/63 pass) and `tsc --noEmit` (clean), and verified the four security focus areas:
+- **(a) No credential decrypt/store without mandate + consumed grant** — the RBAC gate runs strictly before any crypto (type → expiry → recipient-match → verifyMandate deny-by-default → consumeGrant single-use → fail-closed decrypt); every denial returns `{accepted:false}`, never fail-open. The crypto pair is genuinely domain-separated (distinct HKDF info; AAD bound via setAAD with a timing-safe pre-compare; throws on absent/mismatched AAD); a secret-sync blob cannot decrypt as a credential or vice-versa; `SecretShareHandler` refuses credential-class commands; the cross-machine mandate uses an asymmetric Ed25519 signature binding the issuer fingerprint.
+- **(b) configHome / OAuth token cannot cross via the metadata kind** — `projectAccountToMeta` is a strict build-by-copy 7-key allowlist; the receive validator independently rejects non-whitelisted keys (exempting only RESERVED_ENVELOPE_FIELDS). Enforced both ends.
+- **(c) Dark/fleet default genuinely inert** — `resolveDevAgentGate(undefined, fleetConfig)` is false ⇒ no store-flag entry, emitter not constructed, registration inert, `storeCredential` unwired in PR1.
+- **(d) No fail-open bugs** — every security check defaults to deny/throw-into-deny.
+
+Two non-blocking observations (both safe-direction, acceptable for the PR1 primitive layer): a forged-AAD payload that ALREADY passed the mandate gate burns its single-use grant on the fail-closed decrypt (a self-limited DoS that requires first passing the operator-mandate gate); and `rotateOnDepair` is load-then-save without an explicit lock (serial single-machine de-pair). Both are noted for the live-path PRs; neither blocks PR1.