instar 1.2.38 → 1.2.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.38",
+  "version": "1.2.40",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-23T01:12:37.544Z",
-  "instarVersion": "1.2.38",
+  "generatedAt": "2026-05-23T02:31:36.933Z",
+  "instarVersion": "1.2.40",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -1064,7 +1064,7 @@
       "type": "template",
       "domain": "safety",
       "sourcePath": "src/templates/hooks/telegram-topic-context.sh",
-      "contentHash": "8a80976731dd5dd6b981834f0c4e18d495ee0efd350adc7b88a65c1aa6356b5d",
+      "contentHash": "57cfb744bbffcd21f6290c5f38726b105b93258bf09cc539c24d66aebed9c40e",
       "since": "2025-01-01"
     },
     "template:convergence-check.sh": {
@@ -1440,7 +1440,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "d8d019cc9691191bca75fabd916fa5a4400bb614abcd48b49afa4f650d533fdd",
+      "contentHash": "0c4f63b37d72bc85415e464e181507b66bb247df1e903da2fe27c5d6539dab0f",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/src/templates/hooks/telegram-topic-context.sh

@@ -65,6 +65,25 @@ else
     "http://localhost:${PORT}/telegram/topics/${TOPIC_ID}/messages?limit=30" 2>/dev/null)
 fi
 
+# Layer 2: prepend the topic intent briefing if anything has accumulated.
+# Returns empty body when nothing tracked yet — we silently skip injection.
+# Degrades open: any failure here (server down, route 503'd, network blip)
+# leaves recent-history-only output unchanged.
+TOPIC_BRIEFING=""
+if [ -n "$AUTH_TOKEN" ]; then
+  TOPIC_BRIEFING=$(curl -s --max-time 2 \
+    -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    "http://localhost:${PORT}/topic-intent/${TOPIC_ID}/briefing" 2>/dev/null)
+else
+  TOPIC_BRIEFING=$(curl -s --max-time 2 \
+    "http://localhost:${PORT}/topic-intent/${TOPIC_ID}/briefing" 2>/dev/null)
+fi
+
+if [ -n "$TOPIC_BRIEFING" ]; then
+  echo "$TOPIC_BRIEFING"
+  echo ""
+fi
+
 # Format and output context with unanswered message detection
 echo "$RECENT_MSGS" | python3 -c "
 import sys, json

package/upgrades/1.2.39.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new feature, requires meaningful user-visible behavior addition -->
+
+## What Changed
+
+**feat(topic-intent-layer): Layers 1-3 — per-topic confidence tracking + resume briefing + ArcCheck pre-send signal.**
+
+A new three-layer feature that gives the agent a real sense of each conversation's arc. When you talk to the agent across many turns (or days, or after a context reset), it now keeps quiet track of what the topic is about, what's settled, and what's still tentative — without you ever typing a command. The agent does the bookkeeping in the background.
+
+- **Layer 1** — a per-topic confidence tracker. Each candidate fact or decision the conversation establishes is tracked with confidence that rises with reinforcement (you re-reference, you affirm) and falls with contradiction or long silence. Authority requires user-authored evidence — the agent cannot silently promote its own guesses to "settled" by re-referencing itself.
+- **Layer 2** — a briefing the agent reads at the top of every session resume. Telegram bootstrap automatically fetches it and prepends it to the recent-history block. Settled items shown unhedged; tentative items shown with confidence; observation tier (background noise) deliberately not surfaced.
+- **Layer 3** — ArcCheck, a pre-send signal that fires when the agent's draft would either act on a tentative item without confirming OR contradict something already settled. Signal-only — the agent decides whether to redraft including a natural-language confirmation question. Never blocks.
+
+Spec: `docs/specs/topic-intent-layer.md` (v14 CLEAN, approved 2026-05-22, 14 internal rounds plus 13 external rounds).
+
+This build was also the test bed for evaluating whether to integrate GSD as a runtime dependency. Verdict: cherry-pick the methodologies into Instar primitives, do not try runtime composition. Comparison report archived at `.planning/SPIKE-FINDINGS.md` plus `.planning/phases/01-layer1/PLAN.md`.
+
+## Evidence
+
+The original failure modes that motivated the feature are documented as canonical incidents in the spec — qalatra topic 9235 (arc drift across a multi-turn investigation) and GCI/Luna topic 365 (decision amnesia where the agent proposed redesigning a settled OAuth architecture mid-debugging, contradicting an earlier decision).
+
+96 tests across all three tiers, all green locally:
+- Decay arithmetic at days 104, 105, 106 matches spec values to 3 decimal places.
+- User-authored-episode authority gating clamps at 0.69 when no qualifying user-authored episode exists.
+- Per-message dedup with larger-delta-wins on collision.
+- Pending-confirm queue depth 3 with silent drop plus telemetry counter.
+- Sharpen-retry up to 2 then abandoned.
+- PII-safe diagnostics endpoint (raw evidence meta allowlist-filtered, never returns user message text).
+- Framework-parity grep gate (zero Claude-Code or Codex-CLI specific tokens in any Layer 1/2/3 source).
+- Tier-3 lifecycle test boots through the real production server path and observes tier transitions through HTTP.
+
+Side-effects review artifact: `upgrades/side-effects/topic-intent-layer.md`.
+
+## What to Tell Your User
+
+In long, multi-day, or multi-topic conversations, the agent stays on-point. It resumes knowing the goal. It stops re-litigating things you already settled together. When it is about to do something based on an assumption that might be wrong, it asks first in plain English, as part of its reply. When you correct it, it actually updates.
+
+In short, simple conversations, nothing changes. The layer only kicks in once a conversation has substance worth tracking, and stays quiet otherwise.
+
+No commands to learn. No configuration to set. The agent does the bookkeeping; you just talk.
+
+A diagnostics view per conversation tells you exactly what the agent is tracking, how confident it is, what signals built that confidence, and whether anything is in conflict.
+
+## Summary of New Capabilities
+
+- New core modules covering confidence tracking, pending-confirmation lifecycle, LLM-backed extraction, resume briefing rendering, and pre-send classifier.
+- New HTTP routes for diagnostics, refs filter, pending state, telemetry, briefing, and ArcCheck.
+- Telegram bootstrap hook auto-fetches the briefing on session resume. Degrades open on any failure.
+- Production server boot path constructs the store and passes it to AgentServer. Mount unconditional (503 stub when store disabled).
+- Out of v1: cross-conversation insight spreading, retroactive backfill of pre-shipped conversations, cross-machine CRDT collaborative state, automatic conversation renaming, rich dashboard editor, user-tunable confidence weights (operator may tune; end user cannot).
+
+Layer 3's outbound-path wiring (the actual every-send-fires-ArcCheck plumbing into the tone-gate and response-review stack) is intentionally separated from this ship. The classifier IS the spec's Layer 3 mechanism; the rollout is best done with care under a dedicated follow-up since it touches the existing outbound gate authority.

package/upgrades/1.2.40.md

@@ -0,0 +1,119 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = consent state machine + grantConsent/declineConsent API; no Telegram wire-up yet -->
+
+## What Changed
+
+**feat(tunnel): consent state machine — Tier-1 exhaustion → awaiting-consent → relay-active.**
+
+PR 5 of the tunnel-failure-resilience chain. Lands the consent state
+machine inside `TunnelManager` so an exhausted Tier-1 path can offer
+the Tier-2 relay (LocaltunnelProvider from PR 4) behind an
+owner-approval gate.
+
+What's new:
+
+- `TunnelManager.buildDefaultPool` now appends a `LocaltunnelProvider`
+  as the Tier-2 slot. `isAvailable()` returns false when the
+  `localtunnel` npm package isn't installed (per the spec's opt-in
+  posture), so the slot is silently skipped on agents without the
+  dep — behavior is unchanged for them.
+- `TunnelManager.exhaustedOrBackoff` now checks for an available
+  Tier-2 provider AND that the cross-episode consent cooldown isn't
+  active before deciding between `exhausted` and `awaiting-consent`.
+  When both conditions hold, the manager transitions to
+  `awaiting-consent` and generates a one-time CSPRNG nonce stored in
+  a new `_pendingConsent` record.
+- `TunnelManager.grantConsent(nonce)` — public API. Validates the
+  nonce matches the pending record AND the state is still
+  `awaiting-consent` (replay-safe single-use), starts the Tier-2
+  provider, runs the post-start reachability probe, and transitions
+  to `relay-active` with `rotationPending=true` (the persisted
+  marker for the upcoming mandatory PIN+authToken rotation in PR 6).
+  Returns true on success; false on any validation failure or
+  start/probe failure.
+- `TunnelManager.declineConsent(nonce)` — public API. Validates the
+  nonce, advances the cross-episode cooldown counter, and
+  transitions to `exhausted` + background retry.
+- Consent timeout (15 min, per spec Part 4 default) — fires
+  automatically; same effect as decline.
+- `stop()` clears the pending consent + its timer so a torn-down
+  manager can't have a stale timeout fire.
+- `TunnelManager.pendingConsent` accessor — returns a defensive
+  snapshot (episodeId, provider name, nonce, issuedAt) for the
+  upcoming Telegram callback handler (PR 6) to embed the nonce in
+  the inline-button payload.
+
+What's NOT new yet (deliberate, future PRs in the chain):
+
+- Telegram `callback_query` handler that invokes `grantConsent` /
+  `declineConsent` on owner button clicks (PR 6).
+- Inline-button payload in the consent prompt (PR 6).
+- `authToken` / PIN rotation lifecycle on relay-episode end (PR 6+).
+- Full N-consecutive-success self-heal stability gate (PR 7).
+- The auth-gated `/tunnel` route + `ConfigDefaults` migration +
+  CLAUDE.md template (PR 8).
+- The `localtunnel` npm dep itself (PR 6, alongside the consent
+  wire-up — keeps the capability opt-in until the gate is fully
+  live).
+
+Behavior change for users today: **none** at runtime. Agents without
+the `localtunnel` dep installed continue exactly as before (Tier-2
+slot is unavailable, manager falls through to exhausted). The
+plumbing is in place; PR 6 makes it user-facing.
+
+## Evidence
+
+11 new unit tests in `tests/unit/tunnel-consent-state-machine.test.ts`:
+
+- Tier-1 exhausts + Tier-2 available + cooldown inactive →
+  `awaiting-consent` + pendingConsent populated with 128-bit hex nonce.
+- Tier-1 exhausts + NO Tier-2 available → `exhausted` (baseline path).
+- Tier-1 exhausts + consent cooldown active → `exhausted` (cooldown
+  wins).
+- `grantConsent` with matching nonce → `relay-active` + URL emitted +
+  rotationPending=true + pendingConsent cleared (single-use).
+- `grantConsent` with wrong nonce → returns false, state unchanged,
+  provider.start NOT called.
+- `grantConsent` replay of a used nonce → returns false, state
+  unchanged.
+- `grantConsent` + reachability probe fails → `exhausted` + cooldown
+  advanced.
+- `grantConsent` + provider.start throws → `exhausted` + cooldown
+  advanced.
+- `declineConsent` with matching nonce → `exhausted` + cooldown
+  advanced + pendingConsent cleared.
+- `declineConsent` with wrong nonce → returns false, state unchanged,
+  no cooldown change.
+- `stop()` clears pendingConsent + the timeout timer.
+
+All 92 tunnel-related unit tests pass (11 new + 81 from PRs 1–4).
+`tsc --noEmit` clean. `npm run lint` clean.
+
+## What to Tell Your User
+
+This release puts the security gate for backup tunnels into place.
+Nothing visible to you yet — the gate needs a button to click, and
+that's the next release. Once that lands, when Cloudflare goes fully
+down, you'll get a private message from your agent asking permission
+to use a backup. Until you approve, the agent stays link-less and
+keeps retrying Cloudflare. If you decline or don't reply, the agent
+won't ask again for a while (the wait window grows the more you
+decline, so the agent stops bothering you about something you've
+already decided).
+
+If you want the backup capability to actually work when the next
+release lands, install the localtunnel npm package alongside your
+agent. Without it the backup option is silently skipped and the
+agent continues with Cloudflare only — which is fine if that's your
+preference.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Consent state machine (Tier-1 → awaiting-consent → relay-active) | Internal — exposed via grantConsent / declineConsent APIs that the upcoming Telegram callback handler will call |
+| Single-use CSPRNG nonce binding | Automatic — pendingConsent.nonce embeds in the inline button in the next release |
+| Cross-episode consent cooldown | Automatic — exponential back-off on decline/timeout (1h → 4h → 24h) |
+| Mandatory rotation marker on relay-active entry | Automatic — rotationPending=true is the crash-safe flag the upcoming rotation lifecycle reads |

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/topic-intent-layer.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Topic Intent Layer (Layers 1-3)
+
+**PR:** https://github.com/JKHeadley/instar/pull/332
+**Spec:** `docs/specs/topic-intent-layer.md` (v14 CLEAN, approved 2026-05-22)
+**Author:** Echo · autonomous run · 2026-05-22
+**Process:** Per `feedback_side_effects_review.md` — seven-dimension review before ship.
+
+## 1. Over-block
+
+The feature could over-block if a hook surfaces tentative items as if settled, or if ArcCheck started blocking sends.
+
+**Mitigations in place:**
+- ArcCheck verdict shape never includes a `block` or `authority` field. Signal-only by spec and by test (`tests/unit/TopicIntent-arccheck.test.ts` asserts this).
+- Tentative items in the Layer 2 briefing are explicitly hedged with the word "TENTATIVE" + confidence value. Settled items in a separate "SETTLED" section.
+- Observation tier (< 0.30) is NOT surfaced in the briefing at all — no noise leak.
+- The briefing endpoint returns empty body when nothing has accumulated, so bootstrap hooks can skip injection cleanly without distorting normal session start.
+
+## 2. Under-block
+
+The feature could under-block if it lets a single LLM extraction silently launder its own guesses to authoritative tier (the canonical GCI failure mode).
+
+**Mitigations in place:**
+- Authority hard rule (spec section "Authority gating"): confidence cannot reach the authoritative tier (≥0.7) unless at least one evidence event qualifies as a user-authored episode. Enforced in `projectConfidence` with a clamp at 0.69.
+- Per-message dedup: multiple signals about the same refId from the same source message count as ONE episode with the larger applicable delta — agent cannot fork its own message into multiple episodes.
+- Affirmation safety: per-refId per-24h cap of 1 affirmation bonus, plus per-single-user-message max of 3 distinct refIds affirmed, defends against a single "yes" mass-promoting.
+- Signal-specific caps: `agent-reref` capped at +0.05 cumulative, `extract-agent` at +0.10. Even an unbounded loop of agent-origin signals cannot accumulate to authority.
+
+## 3. Level-of-abstraction fit
+
+Is the feature implemented at the right layer of the stack?
+
+**Assessment:**
+- Storage at `.instar/topic-intent/<topicId>.json` parallels the existing `.instar/topic-resume-map.json` convention — same level, same JSON-first approach, same file-per-topic granularity.
+- Routes mounted via the same `createXxxRoutes` factory pattern as `worktreeRoutes`, `fileRoutes`, `machineRoutes` — consistent with the codebase's idiom.
+- AgentServer options pattern mirrors existing optional dependencies (e.g., `worktreeManager?`). DI is uniform.
+- Telegram bootstrap hook modification is minimal — one curl call with degrade-open semantics. Slack bootstrap hook is NOT modified (slack channel IDs are string-keyed, not numeric topic IDs; the cleanest adapter pattern for Slack is a follow-up).
+
+## 4. Signal-vs-authority compliance
+
+Per `feedback_signal_vs_authority`: brittle/low-context filters detect signals; only higher-level intelligent gates with full context block.
+
+**Assessment:**
+- ArcCheck is the signal layer. It returns verdicts that include `kind`, `refId`, `currentTier`, `currentConfidence`, `reason`, `suggestedRewriteHint` — no authority claim.
+- The agent itself is the authority layer. The agent reads the ArcCheck signal in its draft preparation and chooses to either redraft (with a conversational confirmation question) or proceed.
+- The existing outbound gates (tone-gate, response-review, outbound-dedup) retain their blocking authority and are unaffected by this change.
+
+## 5. Cross-feature interactions
+
+What other Instar systems could this affect?
+
+- **CompactionSentinel** — the briefing prepended on every bootstrap may slightly increase context-window usage at session start. Mitigation: maxPerSection cap (default 8) + overflow note keeps it bounded; observation tier deliberately omitted. The briefing is empty body when nothing tracked.
+- **Tone-gate / response-review** — Layer 3 does NOT integrate into the outbound path in this ship. The classifier exists and is reachable; the actual every-send wiring is a deliberate follow-up so we can think carefully about whether ArcCheck signals should be routed through the existing gate or augment them.
+- **Telegram bootstrap hook** — modified, but failure modes are degrade-open (any error → empty briefing, recent-history output unchanged). The 2-second timeout (`curl --max-time 2`) bounds latency.
+- **Slack bootstrap hook** — NOT modified. Slack channel IDs are string-keyed; topic-intent is numeric-keyed. Adapter pattern for Slack is a v1.1 follow-up.
+- **iMessage / WhatsApp** — same situation as Slack, deferred.
+
+## 6. Rollback cost
+
+If this needs to revert, what's the blast radius?
+
+- All new files (`src/core/TopicIntent*.ts`, `src/server/topicIntentRoutes.ts`, all `tests/unit/TopicIntent-*.test.ts`, `tests/integration/topic-intent-routes.test.ts`, `tests/e2e/topic-intent-lifecycle.test.ts`) can be deleted without affecting any other system.
+- Modified files (`src/server/AgentServer.ts`, `src/commands/server.ts`, `src/templates/hooks/telegram-topic-context.sh`) have small surgical additions that can be reverted independently — store construction, route mount, optional briefing-fetch with degrade-open.
+- Storage at `.instar/topic-intent/<topicId>.json` is per-topic JSON files; deleting them has no effect on any other Instar state.
+- No new dependencies in `package.json`. No DB migrations. No config-format changes.
+
+**Net rollback cost: low.** A clean revert of the feature commit + deleting the storage directory is sufficient.
+
+## 7. Migration parity
+
+Per `feedback_migration_parity_standard` (built into CLAUDE.md): changes to agent-installed files must reach existing agents via the update path.
+
+**Files in this PR that need migration handling:**
+- `src/templates/hooks/telegram-topic-context.sh` — built-in hook script. Per the Migration Parity Standard, built-in hooks are **always overwritten** on every migration run via `installBuiltinHooks()`. No additional migration code needed — the script will reach existing agents on their next `instar upgrade`.
+
+**No other agent-installed files changed** in this PR. CLAUDE.md template is unchanged in this PR; Agent Awareness Standard update (so agents know about the new `/topic-intent/*` endpoints) is the recommended next follow-up before the cherry-pick v1.3.x project.
+
+## Conclusion
+
+Ship. Seven-dimension review clean. Rollback cost low. No new external dependencies. All three test tiers green. PII boundary explicitly tested. Framework-parity grep gate in place.
+
+Follow-up scoped for future work (in priority order):
+1. Layer 3 outbound-path wiring (the every-send ArcCheck integration with tone-gate / response-review).
+2. Slack / iMessage / WhatsApp bootstrap parity for Layer 2 briefing.
+3. CLAUDE.md template update for Agent Awareness Standard.
+4. Daily probe job that replays the qalatra-9235 and GCI/Luna-365 fixtures against the live extractor.
+5. The seven cherry-pick recommendations from the GSD spike (separate v1.3.x project).