instar 1.2.37 → 1.2.39

package/dist/tunnel/TunnelNotifier.js

@@ -29,6 +29,7 @@
 export class TunnelNotifier {
     sink;
     clock;
+    credentialProvider;
     stateChangeMinIntervalMs;
     flapThreshold;
     // Dedup state. The lifecycle's epoch is monotonic per manager instance,
@@ -49,6 +50,7 @@ export class TunnelNotifier {
     constructor(opts) {
         this.sink = opts.sink;
         this.clock = opts.clock ?? { now: () => Date.now() };
+        this.credentialProvider = opts.credentialProvider;
         this.stateChangeMinIntervalMs = opts.stateChangeMinIntervalMs ?? 15 * 60_000;
         this.flapThreshold = opts.flapThreshold ?? 3;
     }
@@ -147,7 +149,7 @@ export class TunnelNotifier {
                     messages.push({
                         channel: 'owner-dm',
                         class: 'state-change',
-                        text: `__OWNER_DM_RESTORED_URL_PLACEHOLDER__`,
+                        text: this.composeRestoredDM(),
                         episodeId: ep,
                         epoch: e.epoch,
                     });
@@ -164,7 +166,7 @@ export class TunnelNotifier {
                     messages.push({
                         channel: 'owner-dm',
                         class: 'state-change',
-                        text: `__OWNER_DM_RECOVERED_URL_PLACEHOLDER__`,
+                        text: this.composeRecoveredDM(),
                         episodeId: ep,
                         epoch: e.epoch,
                     });
@@ -183,7 +185,7 @@ export class TunnelNotifier {
                 messages.push({
                     channel: 'owner-dm',
                     class: 'action-required',
-                    text: `__OWNER_DM_CONSENT_PROMPT_PLACEHOLDER__`,
+                    text: this.composeConsentPromptDM(),
                     episodeId: ep,
                     epoch: e.epoch,
                 });
@@ -200,7 +202,7 @@ export class TunnelNotifier {
                 messages.push({
                     channel: 'owner-dm',
                     class: 'state-change',
-                    text: `__OWNER_DM_RELAY_URL_PLACEHOLDER__`,
+                    text: this.composeRelayActiveDM(),
                     episodeId: ep,
                     epoch: e.epoch,
                 });
@@ -250,6 +252,38 @@ export class TunnelNotifier {
             return true;
         return this.clock.now() - lastAt >= this.stateChangeMinIntervalMs;
     }
+    // ── Owner-DM message composers ───────────────────────────────────
+    /** Snapshot of credentials at compose time (safely degrades when no provider). */
+    creds() {
+        if (!this.credentialProvider)
+            return { url: null };
+        try {
+            return this.credentialProvider();
+        }
+        catch {
+            return { url: null };
+        }
+    }
+    renderLink() {
+        const { url, pin } = this.creds();
+        if (!url)
+            return `(link not available yet — I'll send it as soon as the tunnel is up)`;
+        if (pin)
+            return `Link: ${url}\nPIN: ${pin}`;
+        return `Link: ${url}`;
+    }
+    composeRecoveredDM() {
+        return `Cloudflare is back. Your dashboard link:\n\n${this.renderLink()}`;
+    }
+    composeRestoredDM() {
+        return `Your permanent Cloudflare link is back — switched off the backup. New link:\n\n${this.renderLink()}\n\nIf you had your dashboard open, you may need to re-enter the PIN.`;
+    }
+    composeRelayActiveDM() {
+        return `Backup tunnel is up and serving your dashboard. New link below.\n\nHeads up: this routes through a third-party server, so your dashboard traffic is briefly going through their machines while Cloudflare is down. The agent will switch you back to your normal link automatically as soon as Cloudflare recovers.\n\n${this.renderLink()}`;
+    }
+    composeConsentPromptDM() {
+        return `Cloudflare is unavailable and I can't get you a dashboard link through the usual path.\n\nI can try a backup that routes through a third-party server. This means your dashboard PIN and any private view links would briefly be visible to whoever operates that backup while it's in use — and your auth token will be rotated after the backup is no longer needed, which will sign you out of any open dashboard tabs and invalidate any previously-shared private view links.\n\nReply "yes, use a backup" to approve, or "no" to keep waiting for Cloudflare. If you don't reply, I'll keep waiting for Cloudflare and won't use a backup.`;
+    }
 }
 function throttleKey(state, channel) {
     return `${state}::${channel}`;

package/dist/tunnel/TunnelNotifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"TunnelNotifier.js","sourceRoot":"","sources":["../../src/tunnel/TunnelNotifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TunnelNotifier.js","sourceRoot":"","sources":["../../src/tunnel/TunnelNotifier.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.37",
+  "version": "1.2.39",
   "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:00:34.909Z",
-  "instarVersion": "1.2.37",
+  "generatedAt": "2026-05-23T02:07:34.437Z",
+  "instarVersion": "1.2.39",
   "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.38.md

@@ -0,0 +1,103 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = owner-DM channel + notifier sink wiring; no public API breakage -->
+
+## What Changed
+
+**feat(tunnel,telegram): owner-DM channel + two-channel notifier wired into the tunnel manager.**
+
+PR 3 of the tunnel-failure-resilience chain. Lands the owner-DM
+messaging surface that the upcoming consent UX + relay providers
+(PR 4) and credential rotation lifecycle (PR 5) depend on. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
+and approved on main.
+
+What's new:
+
+- `TelegramAdapter.ownerUserId` config field — the single Telegram
+  user id who controls security-sensitive decisions for this
+  instance (consent gate for backup tunnels, credential exposure).
+  Separate from the broader `authorizedUserIds` allowlist per the
+  GPT external review's CRITICAL finding that consent decisions
+  must not trust the broader set. Falls back to
+  `promptGate.ownerId` for back-compat when not set explicitly.
+- `TelegramAdapter.getOwnerUserId()` — returns the configured owner
+  principal (or the back-compat fallback).
+- `TelegramAdapter.sendToOwnerDM(text)` — sends a private DM to the
+  owner's direct bot chat. Failure modes ("no owner configured",
+  "owner hasn't messaged the bot yet", network error) log a warning
+  and return null; never throw into the caller. Telegram bots can
+  only initiate a DM after the user has messaged the bot at least
+  once, so an early forbidden response is expected and non-fatal.
+- `TunnelManager.attachTelegram(adapter, dashboardPin)` — wires the
+  notifier sink. Group messages route to the Dashboard topic (with
+  Lifeline fallback); owner-DM messages route to
+  `sendToOwnerDM`. A credentialProvider callback returns the live
+  URL + current PIN at compose time, so the notifier never holds
+  stale credentials in its own state. `server.ts` calls
+  `attachTelegram` after the Dashboard topic is ensured.
+- `TunnelNotifier` composers — the four owner-DM messages
+  (recovered, restored, consent prompt, relay activated) now render
+  real English text with credentials substituted. Group-channel
+  messages continue to carry status text only — credentials NEVER
+  appear in group messages.
+
+What's NOT new yet (deliberate, future PRs in this chain):
+
+- Inline-button consent UX + callback handler (PR 4).
+- Tier-2 relay providers (localtunnel) + the actual consent-driven
+  transition into `relay-active` (PR 4).
+- `authToken` / PIN rotation on relay-episode end + boot recovery
+  (PR 5).
+- Full N-consecutive-success self-heal stability gate (PR 6).
+- The auth-gated `/tunnel` route (PR 7).
+
+The lifecycle state machine already supports all of these; the
+manager just doesn't transition into the relevant states yet.
+
+## Evidence
+
+3 new unit tests in `tests/unit/tunnel-manager-rewrite.test.ts`:
+
+- `attachTelegram` routes the "couldn't reach" group message to the
+  Dashboard topic id.
+- `attachTelegram` falls back to the Lifeline topic when no Dashboard
+  topic is configured.
+- `attachTelegram` owner-DM message carries the live URL and current
+  PIN (credential substitution at compose time).
+
+1 new + updated tests in `tests/unit/tunnel-notifier.test.ts`:
+
+- The credential-snapshot test now uses a real credentialProvider and
+  asserts the URL + PIN appear in owner-DM messages AND that they
+  NEVER appear in group messages.
+- New "renders a graceful 'link not available' placeholder when no
+  credentialProvider is wired" test for the test-injection /
+  partial-wire-up path.
+
+All 71 tunnel-related unit tests pass (32 lifecycle + 10 providers +
+13 notifier + 19 manager). Typescript and lint clean.
+
+## What to Tell Your User
+
+This release adds the plumbing for owner-only private messages from
+the agent to you, separate from the group topics where everyone
+sees the same messages. Nothing visible to you yet — the upcoming
+release uses this plumbing to message you directly when Cloudflare
+goes down and asks whether to use a backup. The release after that
+uses the same channel to send you new dashboard credentials after a
+backup tunnel finishes its work and your auth token rotates.
+
+If you want to set the owner explicitly, the relevant config field
+is your Telegram user id. The agent falls back to your prompt-gate
+owner id if it's already set, so most existing installs don't need
+to change anything.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Owner-DM channel | Automatic — the agent picks up your owner id from existing config and uses it for security-sensitive messages |
+| Live credential substitution in DMs | Automatic — when the tunnel sends you a link, the URL + PIN are always the current ones |
+| Group-vs-DM channel separation | Structural — credentials never appear in group messages regardless of how the tunnel layer wires up |

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/side-effects/owner-dm-channel.md

@@ -0,0 +1,152 @@
+# Side-effects review — owner-DM channel + notifier sink wiring (PR 3 of tunnel-failure-resilience chain)
+
+**Scope (PR 3 of the chain):** Add the owner-DM messaging surface and
+wire it into the tunnel manager's two-channel notifier. Spec
+`specs/dev-infrastructure/tunnel-failure-resilience.md` is converged
++ approved on main. Public API: `TelegramAdapter.getOwnerUserId()` and
+`TelegramAdapter.sendToOwnerDM(text)` are new; `TunnelManager.attachTelegram()`
+is new; the notifier now substitutes live URL + PIN credentials into
+owner-DM messages via a `credentialProvider` callback.
+
+**Files touched:**
+- `src/messaging/TelegramAdapter.ts` — adds `ownerUserId?: number` to
+  `TelegramConfig`; adds `getOwnerUserId()` accessor (falls back to
+  `promptGate?.ownerId` for back-compat); adds `sendToOwnerDM(text)`
+  which posts to the owner's private bot chat via `sendMessage` with
+  `chat_id: ownerUserId`. The DM send is fire-and-forget: failure paths
+  ("no owner configured", "owner hasn't messaged the bot", network
+  error) log-not-throw and return `null` so callers can degrade
+  gracefully.
+- `src/tunnel/TunnelNotifier.ts` — adds `credentialProvider?: () =>
+  CredentialSnapshot` to `TunnelNotifierOptions`. The four owner-DM
+  message variants (recovered, restored, consent prompt, relay
+  activated) now compose real English text with the credentials
+  substituted at compose time. The four group-channel variants
+  continue to carry status text only — credentials NEVER appear in
+  group messages.
+- `src/tunnel/TunnelManager.ts` — new `attachTelegram(adapter,
+  dashboardPin)` method builds a notifier sink from a duck-typed
+  `TunnelMessagingAdapter` (group → Dashboard topic with Lifeline
+  fallback; owner DM → `sendToOwnerDM`) and a credentialProvider that
+  returns `{ url: this.url, pin: dashboardPin() }`. Holds the notifier
+  in a mutable field so callers can wire it AFTER tunnel construction
+  (the messaging adapter is constructed later in server.ts).
+- `src/commands/server.ts` — calls `tunnel.attachTelegram(telegram,
+  () => liveConfig.get(...) || config.dashboardPin)` after the
+  Dashboard topic is ensured. The wire is non-fatal: if attachTelegram
+  throws, the catch around `ensureDashboardTopic` already swallows it.
+- `tests/unit/tunnel-notifier.test.ts` — replaces the placeholder
+  assertions with real-credential assertions: a DM with a credential
+  provider contains the URL + PIN; a DM without a provider renders a
+  graceful "link not available yet" placeholder; group messages NEVER
+  contain credentials.
+- `tests/unit/tunnel-manager-rewrite.test.ts` — 3 new tests for
+  `attachTelegram`: Dashboard-topic routing, Lifeline fallback when
+  Dashboard isn't ensured, owner-DM credential snapshot includes the
+  live URL and current PIN.
+
+**Under-block**: None. The owner-DM channel adds NEW capability;
+existing behavior is unchanged when no `ownerUserId` is configured
+(`sendToOwnerDM` logs a warning and returns null; the notifier's DM
+sink call is a no-op). Existing Telegram group flows are untouched.
+
+**Over-block**: None — but note the existing
+`config.promptGate?.ownerId` continues to serve as a back-compat
+fallback when `ownerUserId` isn't set explicitly. Operators who used
+`promptGate.ownerId` to mark their session-prompt owner will see that
+same user receiving the tunnel-DM messages, which is consistent with
+the spec's "owner principal" intent. New deployments should set
+`ownerUserId` explicitly.
+
+**Level-of-abstraction fit**:
+- TunnelManager remains the single owner of the lifecycle; the
+  notifier sink is a thin pass-through to the messaging adapter.
+- The `TunnelMessagingAdapter` duck-typed interface keeps the tunnel
+  module from importing `TelegramAdapter` directly — preserves the
+  layered architecture (tunnel does not depend on messaging type).
+- Credential substitution happens in the notifier's composer methods.
+  The notifier never holds credentials in its own state; it calls
+  the provider at compose time so the credentials are always fresh.
+
+**Signal vs authority**: Compliant. The credentialProvider returns a
+SIGNAL (current URL + PIN); the notifier remains the AUTHORITY for
+deciding when an owner-DM message goes out and what it says. The
+sink is the routing layer (executes the send); the messaging adapter
+is the platform layer. No new authority introduced at the wrong
+layer.
+
+**Interactions**:
+- `TunnelManager` constructed in server.ts BEFORE telegram, so the
+  manager initially has no notifier. The wire-up happens AFTER
+  telegram + Dashboard topic are ready (one-shot call to
+  `attachTelegram`). Until then, transitions go through the lifecycle
+  but no user-facing messages fire — preserving the boot-time
+  ordering established in PR 2.
+- The credentialProvider closes over `this._legacyState.url` and
+  the dashboardPin accessor; both are read at each compose, so a
+  PIN rotation (PR 5) will be visible to subsequent messages without
+  re-attaching.
+- `sendToOwnerDM` failure modes are absorbed inside the adapter — the
+  sink wrapper never throws into the notifier path. Preserves the
+  fire-and-forget invariant.
+
+**External surfaces**:
+- New config field: `messaging.config.ownerUserId` (number). Optional.
+  Falls back to `messaging.config.promptGate.ownerId`. Documented in
+  the spec.
+- No new API endpoint. No new CLI command.
+- `TelegramAdapter.sendToOwnerDM(text)` is a new public method but
+  intended for in-process callers only (the tunnel manager is the
+  first caller; future PRs may add more).
+
+**Migration parity**:
+- No agent-installed file change in this PR. Existing agents pick up
+  the new behavior the moment they update — the `ownerUserId` field
+  remains optional with the documented fallback.
+- A future PR in the chain (the ConfigDefaults / migration PR) will
+  add a ConfigDefaults entry for `ownerUserId` and a CLAUDE.md
+  template note so the agent surfaces the new capability
+  conversationally. For now the manager's behavior degrades
+  gracefully when the field is absent.
+
+**Rollback cost**: Trivial. Revert four source files + the test
+updates. The two new public methods (`getOwnerUserId`,
+`sendToOwnerDM`, `attachTelegram`) become unused; the
+`TunnelMessagingAdapter` interface becomes dead code. Nothing else
+breaks.
+
+**Tests**:
+- 19/19 `tests/unit/tunnel-manager-rewrite.test.ts` (3 new for
+  `attachTelegram`).
+- 13/13 `tests/unit/tunnel-notifier.test.ts` (placeholder assertions
+  replaced with credential assertions; 1 new "no-credential
+  gracefully renders 'link not available'" test).
+- 32/32 `tests/unit/tunnel-lifecycle.test.ts` (no change).
+- 10/10 `tests/unit/tunnel-providers.test.ts` (no change).
+- `tsc --noEmit` clean. `npm run lint` clean.
+
+**Decision-point inventory**:
+1. Owner principal modeled as `ownerUserId` separate from
+   `authorizedUserIds` (vs. reusing the broader set) — the GPT
+   external review specifically flagged that consent / credential
+   exposure decisions must NOT trust the broader authorized-users
+   set. A separate single-principal field is the structural fix.
+2. `sendToOwnerDM` returns null on failure (vs. throwing) — preserves
+   the fire-and-forget contract callers expect for outbound
+   messaging. The bot can't initiate a DM until the user has messaged
+   the bot first, so an early "forbidden" response is expected during
+   onboarding; treating it as fatal would block tunnel notifications
+   indefinitely.
+3. `attachTelegram` is a post-construction method (vs. constructor
+   parameter) — the messaging adapter is constructed later than the
+   tunnel manager in server.ts. Putting the sink in the constructor
+   would require restructuring boot order. The post-attach pattern
+   keeps the existing boot sequence and is testable.
+4. `TunnelMessagingAdapter` duck-typed interface (vs. direct
+   `TelegramAdapter` import) — keeps the tunnel module from depending
+   on the messaging layer's concrete types; future PRs can add Slack
+   / iMessage variants without modifying tunnel/.
+5. credentialProvider returns a snapshot (vs. holding the URL/PIN as
+   notifier state) — the notifier composes messages over time; a
+   stale PIN cached in notifier state would leak after rotation. The
+   provider pattern keeps credential freshness in one place.

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).