instar 1.2.39 → 1.2.41

package/upgrades/side-effects/consent-state-machine.md

@@ -0,0 +1,135 @@
+# Side-effects review — consent state machine (PR 5 of tunnel-failure-resilience chain)
+
+**Scope (PR 5 of the chain):** Land the consent state machine inside
+`TunnelManager` and append `LocaltunnelProvider` (from PR 4) to the
+default Tier-2 slot. Adds public `grantConsent` / `declineConsent`
+methods so the upcoming Telegram callback handler (PR 6) can drive the
+owner-approval gate. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
++ approved on main.
+
+**Files touched:**
+- `src/tunnel/TunnelManager.ts` — adds Tier-2 to `buildDefaultPool`;
+  modifies `exhaustedOrBackoff` to branch on Tier-2 availability +
+  consent cooldown; adds `findAvailableTier2`, `requestConsent`,
+  `clearPendingConsent`, `grantConsent`, `declineConsent`,
+  `recordConsentDecline`, and the `pendingConsent` accessor; updates
+  `stop()` to clear the pending consent.
+- `tests/unit/tunnel-consent-state-machine.test.ts` — 11 tests covering
+  the awaiting-consent transition (and its negative cases — no Tier-2
+  available, cooldown active), grantConsent happy path, nonce
+  rejection (wrong nonce, replay), grant-failure paths (unreachable
+  relay, provider.start throws), declineConsent happy path + wrong
+  nonce, stop() clearing pendingConsent.
+
+**Under-block**: None at user-visible runtime. Agents without the
+`localtunnel` npm dep installed continue to fall through to
+`exhausted` exactly as before (the Tier-2 slot's `isAvailable()`
+returns false; `findAvailableTier2` returns null; the branch picks
+the existing `exhausted` path). This is the spec's opt-in posture —
+PR 4's side-effects review documented it explicitly.
+
+**Over-block**: Minimal. Agents that DO have `localtunnel` installed
+WILL see the new `awaiting-consent` transition fire instead of going
+straight to `exhausted` — but the manager has no UX layer to surface
+the prompt yet (PR 6 lands the Telegram callback handler that
+actually calls `grantConsent` / `declineConsent`). For now the
+manager sits in `awaiting-consent` for the 15-minute timeout, then
+auto-declines and falls through to exhausted with the cooldown
+advanced. From the user's perspective this looks identical to
+"exhausted" today — there's just a 15-min delay before the cooldown
+counter ticks the first time.
+
+To explicitly avoid this UX gap during the interim window between
+PR 5 and PR 6, operators who don't want the awaiting-consent state
+can simply not install `localtunnel`. The default ships without it.
+
+**Level-of-abstraction fit**:
+- The state machine lives in `TunnelLifecycle` (PR 1); the manager
+  drives state through the existing CAS-guarded transitions.
+- `_pendingConsent` is private state on the manager (binds nonce +
+  episode + provider). Exposed read-only via the `pendingConsent`
+  accessor that returns a snapshot — callers cannot mutate the
+  manager's state from outside.
+- `grantConsent` / `declineConsent` are the AUTHORITY surface for
+  consent decisions. The Telegram callback handler (PR 6) will be
+  the SIGNAL layer — it validates the click came from the owner and
+  the message id matches, then calls these methods.
+
+**Signal vs authority**: Compliant. The manager is the authority for
+state transitions and the consent record's lifecycle; external
+callers can only ask for grant/decline by presenting the nonce, and
+the manager validates+decides. The Telegram callback handler in PR 6
+will be a thin signal layer above this; it cannot bypass the nonce
+check.
+
+**Interactions**:
+- `_pendingConsent` is single-flight per manager instance — only one
+  consent record can be active at a time (the lifecycle's `episode`
+  invariant: one episode = one consent prompt = one nonce).
+- `clearPendingConsent` is called on every terminal path (grant
+  success, decline, timeout, stop, episode change). The timer is
+  cleared atomically with the record so no stale callback can fire.
+- The consent timeout uses the lifecycle's `recordConsentRefusal`
+  to advance the cross-episode cooldown — same path as a manual
+  decline. The cooldown progression is exponential (1h → 4h → 24h)
+  per PR 1's lifecycle implementation.
+- `rotationPending=true` is set on entering `relay-active` (the
+  crash-safe persisted marker for the upcoming rotation lifecycle
+  in PR 6). The actual rotation work is NOT in this PR — only the
+  marker.
+- Reachability probe on the granted Tier-2 provider follows the
+  same `/health` semantics as Tier-1 — a relay that emits a URL
+  but doesn't actually serve traffic falls through to exhausted +
+  cooldown (so the owner isn't asked again immediately).
+
+**External surfaces**:
+- New public methods: `grantConsent(nonce)`, `declineConsent(nonce)`,
+  `pendingConsent` getter on `TunnelManager`. All require the
+  caller to have the current pending nonce, which is itself only
+  accessible via `pendingConsent.nonce` — there's no broader
+  exposure.
+- No new API endpoint, no new CLI command, no new config field.
+- The default tunnel pool now includes a `LocaltunnelProvider`
+  slot, but the manager only activates it after Tier-1 exhausts +
+  consent is granted, so users who never hit a Tier-1 exhaustion
+  never see Tier-2 attempted.
+
+**Migration parity**: N/A. Server-side code only.
+
+**Rollback cost**: Trivial. Revert `TunnelManager.ts` + the test file.
+The new methods become unused (they're not called from anywhere
+outside the manager + tests yet). LocaltunnelProvider stays in tree
+from PR 4 but is no longer in the default pool.
+
+**Tests**:
+- 11/11 new tests in `tests/unit/tunnel-consent-state-machine.test.ts`.
+- 19/19 tests in `tests/unit/tunnel-manager-rewrite.test.ts` (from
+  PR 2 + 3) still pass.
+- 32/32 lifecycle, 13/13 notifier, 10/10 providers, 7/7 localtunnel-
+  provider — all still pass.
+- `tsc --noEmit` clean. `npm run lint` clean. No existing tests
+  modified.
+
+**Decision-point inventory**:
+1. `_pendingConsent` stores the provider directly (vs. a provider-name
+   key into the pool) — keeps the grant path independent of the pool
+   ordering, and ensures a provider that becomes "unavailable"
+   between request and grant is still the one we attempt (failure
+   surfaces cleanly).
+2. Nonce is 128-bit CSPRNG via `generateNonce` from PR 1 — meets the
+   GPT external review's spec for entropy + atomic compare-and-delete.
+3. Single-use enforced by `clearPendingConsent` BEFORE the provider
+   starts — a replay of the same nonce loses cleanly even if the
+   start is in flight.
+4. Timeout = 15 min (spec Part 4 default, staggered off the 10-min
+   reconnect window per verification finding V1).
+5. Reachability failure on a granted relay → cooldown advanced.
+   Reason: the relay started but doesn't serve; bothering the owner
+   again immediately wouldn't help. The cooldown gates the next ask.
+6. State machine transitions `awaiting-consent → exhausted` directly
+   on decline/timeout/start-failure — same transition the cooldown
+   path uses, so background retry semantics are uniform.
+7. `pendingConsent` accessor returns a defensive snapshot — mutating
+   it does NOT affect the manager. External callers cannot inject
+   their own nonce or change the bound provider.

package/upgrades/side-effects/localtunnel-provider.md

@@ -0,0 +1,95 @@
+# Side-effects review — LocaltunnelProvider (PR 4 of tunnel-failure-resilience chain)
+
+**Scope (PR 4 of the chain):** Add the `LocaltunnelProvider`
+implementation of the `TunnelProvider` interface from PR 1. The class
+is added in isolation — NOT wired into the manager's active pool —
+so PR 5 can ship the consent state machine + inline-button UX +
+relay-active activation path with the provider already in place
+under separate review. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
++ approved on main.
+
+**Files touched:**
+- `src/tunnel/LocaltunnelProvider.ts` — NEW. Implements
+  `TunnelProvider` with `name: 'localtunnel'`, `tier: 2`. Dynamic
+  import of the `localtunnel` npm package; graceful "unavailable"
+  return path when the dep isn't installed. Failure classification
+  preserves the `ProviderFailureReason` enum surface from PR 1
+  (rate-limited / network / process-exit / binary-missing).
+- `tests/unit/localtunnel-provider.test.ts` — NEW. 7 tests covering
+  the provider's surface (name + tier), graceful degradation when
+  the npm package is absent (isAvailable=false; start() rejects
+  binary-missing; verdict cached across calls), and constructor
+  option acceptance.
+
+**Under-block**: None — the provider is added but NOT wired into the
+manager's active pool. The manager's existing `buildDefaultPool`
+returns Cloudflare-named + Cloudflare-quick only, and the driver
+filters Tier-2 providers (`if (provider.tier !== 1) continue;`).
+User-facing behavior is unchanged.
+
+**Over-block**: None. The provider class is purely additive; no
+existing behavior changes.
+
+**Level-of-abstraction fit**: The provider implements the same
+interface as the Cloudflare providers, so PR 5's state-machine
+changes can use it through the existing pool abstraction without
+needing provider-specific code paths. Tier-2 trust classification
+lives on the provider (`tier: 2` field), which is correctly the
+manager's structural signal for "consent required."
+
+**Signal vs authority**: Compliant. The provider raises errors with
+classified reason strings (the SIGNAL); the manager classifies them
+into `ProviderFailureReason` (the AUTHORITY). The consent gate (PR 5)
+will be a separate AUTHORITY layer above the manager's driver — the
+provider never makes consent decisions on its own.
+
+**Interactions**:
+- Dynamic import: the provider does `await import('localtunnel')` at
+  first `isAvailable()` call. On environments without the dep, the
+  import throws and the provider caches the "unavailable" verdict.
+  This is deliberately a runtime check, not a build-time one — instar
+  ships without the `localtunnel` dep in `package.json` (per the
+  spec's supply-chain hardening — Tier-2 backup capability is opt-in,
+  installed explicitly by operators who want it).
+- The `subdomain` constructor option is operator-controlled. The
+  comment documents the privacy posture: never use the agent's
+  identity as a subdomain hint — it would be publicly visible on
+  `*.loca.lt`.
+
+**External surfaces**:
+- New exported class `LocaltunnelProvider` from `src/tunnel/`.
+- No new npm dependency — `localtunnel` is NOT added to
+  `package.json` in this PR. The provider degrades gracefully when
+  the dep is absent. Operators add the dep explicitly to enable the
+  capability. This matches the spec's supply-chain posture (Part 7).
+- No new API endpoint, no new CLI command, no new config field
+  (Part 4 fields land with PR 5 alongside the consent flow).
+
+**Migration parity**: N/A. The provider is server-side code only;
+no agent-installed file change.
+
+**Rollback cost**: Trivial. Delete two files (`src/tunnel/Local-
+tunnelProvider.ts` and the test). The provider is isolated; nothing
+else references it.
+
+**Tests**:
+- 7/7 tests in `tests/unit/localtunnel-provider.test.ts`.
+- 70/70 tunnel-related tests from PRs 1–3 unaffected.
+- `tsc --noEmit` clean. `npm run lint` clean.
+
+**Decision-point inventory**:
+1. Dynamic import (vs. static `import localtunnel from 'localtunnel'`)
+   — keeps `localtunnel` out of the build-time type-check graph so
+   instar can ship without the dep. Operators add it explicitly per
+   the spec's supply-chain stance.
+2. `localtunnel` NOT added to `package.json` in this PR — landing the
+   dep before the consent gate ships would expose users to an
+   unchecked Tier-2 capability. The dep lands in PR 5 alongside the
+   consent flow that gates its use. This is intentional and
+   per-spec — Part 7 frames the capability as opt-in regardless.
+3. `subdomain` is operator-controlled and documented as
+   non-identifying. The provider does not auto-generate one.
+4. Failure classification matches PR 1's enum — no new failure
+   reasons needed; the manager's existing logic handles localtunnel
+   failures the same way as cloudflared failures.

package/upgrades/side-effects/silently-stopped-trio.md

@@ -0,0 +1,115 @@
+# Side-Effects Review — Silently-stopped trio
+
+**Version / slug:** `silently-stopped-trio`
+**Date:** 2026-05-22
+**Author:** echo
+**Second-pass reviewer:** [pending — high-risk: WorktreeManager + new sentinels]
+**Spec:** [docs/specs/silently-stopped-trio.md](../../docs/specs/silently-stopped-trio.md)
+**ELI16:** [docs/specs/silently-stopped-trio.eli16.md](../../docs/specs/silently-stopped-trio.eli16.md)
+
+## Summary of the change
+
+Three independent layers closing the same failure class — "agent silently stopped working without anyone noticing" — diagnosed jointly with the gsd-side echo agent on 2026-05-22.
+
+1. **WorktreeManager clone-default** (`src/core/WorktreeManager.ts`). New private predicate `shouldCloneInsteadOfWorktree()` returns true when source `projectDir` is outside agent home (the sandbox-revocation hazard case). When true, `createBinding` uses `git clone` + `git checkout -b` instead of `git worktree add`, producing a fully self-contained `.git/` directory under agent home. `INSTAR_WORKTREE_FORCE_WORKTREE=1` is the rollback escape hatch. The existing in-tree worktree path (source already under agent home) is preserved unchanged.
+
+2. **SocketDisconnectSentinel** (`src/monitoring/SocketDisconnectSentinel.ts`, new). Detector + recovery for Claude Code's `socket connection closed unexpectedly` family of strings. Mirrors `RateLimitSentinel`'s shape — detect, immediate user notice, backoff staircase, verify, escalate. Patterns are intentionally broad (4 regex variants) because false-positives are cheap nudges and false-negatives are the exact failure class this exists to close.
+
+3. **ActiveWorkSilenceSentinel** (`src/monitoring/ActiveWorkSilenceSentinel.ts`, new). Walks the SessionRegistry every 60s; reports any session whose `lastOutputAt` is older than the silence threshold (default 15 min). One nudge (empty `tmux send-keys`), 30s verify, escalate via tone-gated `/attention` if no advance.
+
+All three escalation payloads route through the existing `MessagingToneGate` B12-B14 ruleset via `/attention` (`category: degradation`).
+
+## Decision-point inventory
+
+- `WorktreeManager.shouldCloneInsteadOfWorktree` — **add** — structural predicate (file shape + env override).
+- `WorktreeManager.createBinding` clone branch — **add** — uses `git clone` + `git checkout -b` for cross-project sources.
+- `SocketDisconnectSentinel.report / scanSession / runAttempt / verifyAttempt / escalate` — **add** — full recovery state machine.
+- `ActiveWorkSilenceSentinel.tick / report / runNudge / verifyNudge / escalate` — **add** — silence-detection state machine.
+- Tone-gated `/attention` POST path — **pass-through** — consumed by both new sentinels' notify functions; the gate (existing authority) is unchanged.
+
+## Deferrals tracked
+
+The v3 Self-Healing Remediator's Tier-3 absorption of these sentinels' detection + recovery surfaces is the only forward note. <!-- tracked: topic-3079-v3-remediator -->
+
+---
+
+## 1. Over-block
+
+- **Worktree decision over-broad.** Any source outside agent home triggers clone. False-positive cost: a `git clone` takes 1-5s on APFS (sub-second with CoW). False-negative cost: the exact incident class we just hit. Acceptable.
+- **Socket-disconnect regex over-broad.** Patterns include generic `connection.*closed.*unexpectedly` — could match unrelated text. False-positive cost: one Ctrl+C+Enter nudge to a healthy session + a "lost its connection" Telegram message that resolves cleanly. False-negative cost: silently frozen session. Trade-off documented.
+- **Silence threshold over-broad.** 15 min is conservative; agents doing slow LLM work (e.g. 5-min generation cycles) could trip if they go quiet during a long thinking pause. Mitigation: the `paused` / `recoveryInFlight` flags let SessionRegistry callers exempt sessions in known-quiet states. Configurable per-deployment.
+
+## 2. Under-block
+
+- **WorktreeManager migration of EXISTING worktrees.** This PR ships the clone-default for NEW bindings. Migration of existing worktrees-on-disk is deferred — the spec discussed it but it requires significant safety work (rsync of uncommitted diffs, fencing during the swap). Tracked: same v3 Remediator absorption point. <!-- tracked: topic-3079-v3-remediator -->
+- **Socket-disconnect pattern coverage.** Claude Code may surface other disconnect strings we don't yet know about. Patterns are extensible; the next observed string adds one line.
+- **Active-work-silence false-negatives.** Sessions that produce minimal output (e.g. a `wait + retry` loop with tiny intervals) might never trip the 15-min threshold even when "stuck" in some other sense. Adjacent watchdogs (SessionWatchdog, PresenceProxy) cover other shapes.
+- **Both sentinels currently fire-and-forget on escalation.** No retry-the-escalation loop. If the notify fails (network blip, tone gate hiccup), the message is lost. Acceptable for v1 — the bigger problem (silent failure) is closed; retry plumbing comes with v3 Remediator.
+
+## 3. Level-of-abstraction fit
+
+- **WorktreeManager** is the right layer — it's the single funnel that decides how to materialize a worktree on disk. Putting the clone-vs-worktree decision anywhere else would skip the existing fencing + binding lifecycle.
+- **Sentinels in `src/monitoring/`** alongside RateLimitSentinel, CompactionSentinel, SessionWatchdog. Same idiom; same wire-up shape via server.ts.
+- **Escalation through `/attention`** uses the existing tone gate — no new judgment authority introduced.
+
+## 4. Signal vs authority compliance
+
+**Reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] **No — this change produces signals consumed by an existing smart gate.**
+
+- `shouldCloneInsteadOfWorktree` is a structural predicate (file path + env). No judgment.
+- `SOCKET_DISCONNECT_PATTERNS` regex is a detector. State machine is a bounded mechanic (fixed attempt count, fixed backoff staircase).
+- `ActiveWorkSilenceSentinel.tick` threshold is deterministic. Nudge is a bounded primitive.
+- All user-facing escalation goes through `MessagingToneGate` via `/attention`'s existing path. No new authority introduced.
+
+## 5. Interactions
+
+- **Shadowing:** SocketDisconnectSentinel and ActiveWorkSilenceSentinel can both fire on the same session (socket dropped → output stopped). The socket sentinel ticks every 15s; the silence sentinel waits 15 min. Socket sentinel virtually always fires first. Idempotency-by-id in `/attention` prevents duplicate topic creation if both ever land.
+- **Double-fire vs existing watchdogs:** SessionWatchdog (long-running child), SessionMonitor (topic-bound output gap), PresenceProxy (user-waits-for-agent). All three handle different shapes; none overlap with the new sentinels in practice. Active-work-silence is the catch-all for what falls through the cracks.
+- **Races:** Sentinel state maps are per-session keys; concurrent ticks on the same server can't race (single-threaded JS event loop). Cross-process safety is N/A — each server instance is a single sentinel owner.
+- **WorktreeManager clone vs worktree-add:** Mutually exclusive code paths; no race.
+
+## 6. External surfaces
+
+- **Other agents:** Bindings created by this PR for shared repos will be clones, not worktrees. `git worktree list` from the source repo won't show them. Documented in CLAUDE.md template (forward).
+- **Other users:** ships in next release. macOS users + Linux users alike. The clone path is OS-agnostic.
+- **External systems:** Telegram (one extra topic class — "disconnect" alerts — though tone-gated). `/attention` route — existing; no change to its contract.
+- **Persistent state:** No new files for the sentinels (in-memory state only — by design, simpler than RateLimitSentinel which persists). WorktreeManager bindings file unchanged.
+- **Timing:** Sentinel ticks (15s + 60s) are negligible overhead per session.
+
+## 7. Rollback cost
+
+- WorktreeManager: revert the diff. `INSTAR_WORKTREE_FORCE_WORKTREE=1` is the in-place rollback toggle without a release.
+- Sentinels: revert each new file + the server.ts wire-up. No persistent state to clean up.
+- Total: ~15 min revert + release cycle.
+
+---
+
+## Addendum 2026-05-23 — Smoke-test interaction with SourceTreeGuard (fixed)
+
+After the initial commit landed, `npm run test:smoke` surfaced 14 failures in the existing WorktreeManager test suite — every test that exercised the clone-default branch failed with `SourceTreeGuardError: Refusing to run src/core/WorktreeManager.ts:clone-default against the instar source tree`. Root cause: `SafeGitExecutor.runSourceTreeChecks` defaults the target list to cwd. The new `git clone` call ran from a cwd that happened to be inside the instar source tree (test fixtures invoking `createBinding` from inside an instar checkout), and the guard correctly flagged the cwd as destructive-against-source even though the clone op itself is non-destructive on the source. **Fix:** pin `cwd: this.worktreesRoot` on the clone call — guaranteed outside the source tree and the same dir the clone destination lives under. All 56 smoke tests pass.
+
+This is a defensible interaction, not a guard regression: the guard is doing exactly what it was built to do (conservative protection of the source tree). The clone-default branch needed explicit cwd because it's the first WorktreeManager codepath to run git from outside the source's own dir.
+
+## Conclusion
+
+Closes the silently-stopped failure class in one PR per the no-deferrals rule. 34 new tests cover the core surfaces. Server-side wire-up + integration tests + CLAUDE.md template update are part of this PR (see commit). Tone-gate compliance asserted at unit level for both sentinels' escalation payloads. Migration of existing worktrees explicitly deferred to v3 Remediator with tracker marker.
+
+Clear to ship pending second-pass review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** [pending]
+
+[awaiting reviewer]
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/silently-stopped-trio.md` + `.eli16.md`.
+- Tests: `tests/unit/monitoring/SocketDisconnectSentinel.test.ts`, `tests/unit/monitoring/ActiveWorkSilenceSentinel.test.ts`, `tests/unit/core/WorktreeManager-clone-default.test.ts` — 34 tests.
+- Incident reference: topic 5447 alignment with gsd-side echo's diagnosis 2026-05-22.