instar 0.28.89 → 0.28.91

package/upgrades/side-effects/prop-399-native-module-healer.md

@@ -0,0 +1,129 @@
+# Side-Effects Review — In-Line Native-Module Self-Heal (PROP-399)
+
+**Version / slug:** `prop-399-native-module-healer`
+**Date:** `2026-05-11`
+**Author:** `echo` (rebased from Dawn's original branch authored 2026-05-10)
+**Second-pass reviewer:** `required — wraps every SQLite open() path; touches three memory subsystems on hot init paths`
+
+## Summary of the change
+
+Closes the chronic NODE_MODULE_VERSION mismatch failure mode (1254 field reports, cluster `cluster-degradation-semanticmemory-semanticmemory-init-failed-the-m`). When better-sqlite3 is compiled against one Node major and the running Node has a newer major (Homebrew bumps, asdf shims pointing at a moved binary, etc.), every SQLite-backed memory subsystem throws on first open and falls back to a degraded path. Today the only fix is for the user to run `npm rebuild better-sqlite3` by hand.
+
+This adds a shared `NativeModuleHealer` helper (`src/memory/NativeModuleHealer.ts`) that wraps the better-sqlite3 import in each `open()` path. On `NODE_MODULE_VERSION` error during `await import('better-sqlite3')`:
+
+1. Locate the install prefix via `require.resolve('better-sqlite3')`.
+2. Locate `npm` on PATH.
+3. Run `npm rebuild better-sqlite3 --prefix <prefix>` synchronously (~30s).
+4. Clear better-sqlite3 from `require.cache` so the fresh binding loads on retry.
+5. Retry the import + construct exactly once. On second failure, surface the post-rebuild error directly.
+
+Heal attempts are persisted as JSONL at `<stateDir>/native-module-heals.jsonl` for observability and downstream consumption by `DegradationReporter` / health probes.
+
+Wired into:
+- `src/memory/SemanticMemory.ts::open()` — wraps the import; main's corruption-recovery branch is unchanged and runs after the healer returns the constructor.
+- `src/memory/TopicMemory.ts::open()` — wraps the import + construct.
+- `src/memory/MemoryIndex.ts::open()` — wraps the import + construct.
+
+**Once-per-process guard.** The rebuild is expensive and shouldn't loop. The healer enforces single-attempt semantics: a second open() in the same process that hits the same error gets the original error with `(heal previously attempted)` appended, no rebuild re-run.
+
+**This is the same change as the original PROP-399 commit (`e080ec64`, authored by Dawn on `fix/prop-399-native-module-healer`).** This rebase brings it forward onto current main (97 commits behind, two conflict files). No behavior was added or removed during the rebase; the conflicts were both about coexistence with features that landed in parallel:
+
+- **`site/src/content/docs/reference/configuration.md`** — PROP-399 added a `defaultMaxDurationMinutes` doc entry that main subsequently added on its own (PR #125). The PROP-399 docs change was dropped during rebase because it was already applied — net diff is zero.
+- **`src/memory/SemanticMemory.ts`** — main added corruption auto-detection + JSONL-rebuild + quarantine handling to `open()` after PROP-399 forked. PROP-399 replaced the same `open()` body with the healer wrap. Resolved by extracting the better-sqlite3 constructor inside `openWithHeal('SemanticMemory', …)`, then running main's corruption-recovery and pragma setup on the constructed db unchanged. Both features now compose: ABI-mismatch heals first (import-time), corruption-quarantine + JSONL-rebuild heals second (post-open).
+
+## Decision-point inventory
+
+- `src/memory/SemanticMemory.ts::open()` (line 147) — **modify** — replaces the inline `await import('better-sqlite3')` block with `NativeModuleHealer.openWithHeal('SemanticMemory', …)` that returns the constructor. The rest of `open()` (corruption recovery, integrity probe, JSONL rebuild) is unchanged.
+- `src/memory/TopicMemory.ts::open()` (line 149) — **modify** — wraps import + construct in `openWithHeal('TopicMemory', …)`. No corruption-recovery branch in TopicMemory; the wrap is end-to-end for open().
+- `src/memory/MemoryIndex.ts::open()` (line 120) — **modify** — wraps import + construct in `openWithHeal('MemoryIndex', …)`. No corruption-recovery branch.
+- `src/memory/NativeModuleHealer.ts` — **add** — new file. Process-singleton class; exposes `openWithHeal`, `isNodeModuleVersionError`, `healBetterSqlite3`, `getLastResult`, `configure({ stateDir })`. No exports from `index.ts` — memory modules import directly.
+
+No new gates, no new filters, no new authorities — `NativeModuleHealer` produces a signal (heal-event JSONL) that the existing `DegradationReporter` consumes; the healer itself never decides whether the user should be alerted. The signal-vs-authority boundary is preserved.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — this is a heal-and-retry wrapper. The original error is re-thrown on second failure with full context.
+
+The inverse risk exists: could the healer mask a real configuration error?
+
+- **better-sqlite3 not installed.** The opener catches the non-`NODE_MODULE_VERSION` `import` failure and re-throws the original user-facing "Run: npm install better-sqlite3" message. `openWithHeal` then checks `isNodeModuleVersionError` and short-circuits — non-mismatch errors propagate immediately, no rebuild is attempted.
+- **`npm` missing on PATH.** Heal returns false, writes a `HealEvent` with `errorTail: 'npm not found on PATH'`, original error is re-thrown wrapped with `(in-line heal failed — see native-module-heals.jsonl)`. No silent swallow.
+- **Rebuild succeeds but Node still incompatible** (e.g., Node major above what better-sqlite3 supports). Retry fails, the new error is surfaced directly — caller sees the post-rebuild failure mode, not the pre-rebuild one. Heal event is logged with `success: true` (rebuild ran) but the retry exception bubbles unchanged.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Other native modules.** Only better-sqlite3 is healed. The same ABI mismatch class hits `sqlite-vec` (vector search), `keytar`, and any future native dep. Out of scope for PROP-399; the helper is generic enough (`openWithHeal<T>`) that future modules can adopt it.
+- **Heal failures during the supervisor preflight path.** `ServerSupervisor.preflightSelfHeal` (PR #111) heals the server-spawn case before the server forks; the in-line healer here covers CLI commands and direct instantiation paths that bypass the supervisor. Both paths log to `native-module-heals.jsonl`, but they don't share state — a heal in the supervisor doesn't suppress a heal in the server. With the once-per-process guard each side caps its own retries; no double-rebuild within a single process is possible.
+- **Heals during a degraded `Node-not-asdf` install.** If `npm` shells out to a Node that's different from `process.execPath`, the rebuild can target the wrong ABI. The healer pins `process.execPath` as the node binary for the spawned `npm` (`spawnSync(process.execPath, [npmPath, 'rebuild', ...])`), which closes this.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this happening at the right layer?**
+
+The healer sits at the `open()` boundary inside each memory subsystem — the *first* user-visible interaction with the native module. That is the right layer for an inline heal: it catches both supervised (server-spawned) and direct (CLI command) callers, doesn't require new infrastructure, and surfaces the heal event through the existing degradation-event pipeline.
+
+A pure boot-time preflight (already exists in `ServerSupervisor.preflightSelfHeal`) cannot cover the CLI-command and direct-instantiation cases — the field reports show the gap is real.
+
+A higher-level remediator (the `Remediator` described in `docs/specs/SELF-HEALING-REMEDIATOR-SPEC.md`) would orchestrate this from outside; that spec is the broader plan. Until the orchestrator exists, this in-line healer is the load-bearing piece. When the remediator lands, it consumes `native-module-heals.jsonl` as the "first runbook" without needing to re-implement the rebuild logic.
+
+---
+
+## 4. Signal-vs-authority compliance
+
+**Does this respect the project principle that low-context filters emit signals while only a high-context gate has blocking authority?**
+
+Yes. The healer is a signal producer:
+
+- It detects a narrow, structurally observable failure (`NODE_MODULE_VERSION` substring in `err.message`).
+- It writes a structured event (`HealEvent`) to JSONL.
+- It surfaces the rebuild attempt through stdout/console logging.
+
+The authority decisions — does this become a degradation event? does the user get alerted? — are owned by `DegradationReporter` and its downstream consumers (tone-gate authority, attention channel). The healer never directly emits a degradation or sends a user alert.
+
+The `isNodeModuleVersionError` matcher is a regex on free-form Node error text, which is the kind of brittle filter the project principle warns about. It's safe here because:
+
+1. The matcher's job is to *decide whether to retry an open*, not to authorize a privileged action.
+2. The retry is bounded (once per process).
+3. A false positive (substring match on legitimate non-mismatch error) causes one unnecessary rebuild — slow, not unsafe — and the post-rebuild retry then surfaces the original error to the caller.
+4. A false negative (real mismatch that the matcher misses) is identical to the current behavior: throw and degrade. No regression.
+
+---
+
+## 5. Interactions with adjacent systems
+
+- **`ServerSupervisor.preflightSelfHeal` (PR #111).** Coexists. Supervisor heals at fork time; this heals at first-open time. Each has its own `healAttempted` guard within its own process. No state shared, no coordination needed. If the supervisor heals first, the spawned server's in-line healer sees a working binding and never trips.
+- **Main's `SemanticMemory.open()` corruption recovery (PRs #ea099453, #28e54f82, #6bfef745, #7c4463ef).** Coexists by ordering. The healer runs first (import-time, ABI mismatch). After it returns a working constructor, main's corruption-detection / quarantine / JSONL-rebuild runs unchanged on the constructed db. Verified by the 12 corruption-recovery tests + 12 NativeModuleHealer tests all passing together (`tests/unit/semantic-memory-corruption-recovery.test.ts` + `tests/unit/NativeModuleHealer.test.ts`, 24 tests pass clean).
+- **Main's WikiClaim Phase 1/5 work on `SemanticMemory.ts` (PRs #137, #141).** No interaction. Those changes touched the entity/evidence schema and query paths; this change touches `open()`. The added import (`EvidenceRenderer`) is preserved.
+- **`DegradationReporter`.** Consumes `native-module-heals.jsonl` as part of its event sources (existing wiring on Dawn's original branch). The reporter remains authority-of-record for whether a heal-failure becomes an attention-channel alert.
+- **Messaging Layer 3 `DeliveryFailureSentinel` (PR #103).** No interaction. Different failure class (network/delivery), different subsystem.
+
+---
+
+## 6. Rollback cost
+
+- **Forward.** Merge to main, cut a release. Agents on the new version are auto-healed on next session. Agents on older versions degrade exactly as they do today — no change.
+- **Backward.** Revert is a single-commit rollback (one feature commit). No DB migrations, no on-disk schema changes. The `native-module-heals.jsonl` log file is append-only and is safe to leave behind on rollback; the next start without the healer simply doesn't write to it.
+- **Skew safety.** Two agents on different versions in the same repo do not share state — heals are per-agent, per-process. A mid-release-window mix is harmless.
+
+---
+
+## 7. Convergence-history reference
+
+The broader design this PR slots into went through 5 rounds of convergent review in April:
+
+- 4 rounds of Claude-family reviewers in parallel (security / scalability / adversarial / integration). Internal convergence at iter 4.
+- 1 final cross-model round (GPT 5.4, Gemini 3.1 Pro, Grok 4.1 Fast via `/crossreview`). Surfaced 11 additional findings the Claude-family reviewers missed (alert-policy contradiction, wall-clock-vs-monotonic-time gap, blastRadius:"external" contradiction, machine-lock reclaim predicate too strict).
+
+96 material findings addressed across all rounds. Spec: `docs/specs/SELF-HEALING-REMEDIATOR-SPEC.md` (status `converged-pending-approval`). Convergence report: `docs/specs/reports/self-healing-remediator-convergence.md`.
+
+**This PR ships the narrowest slice of that design** — the one in-line runbook (better-sqlite3 ABI mismatch) — without the surrounding Remediator orchestrator. The orchestrator is the next phase and will be re-spec'd against current reality (incorporating the lifeline-preflight, probe framework, tone-gate, and Layer-3 sentinel pieces that landed in parallel during April–May 2026).

package/upgrades/side-effects/thread-topic-linkage.md

@@ -0,0 +1,243 @@
+# Side-Effects Review — Thread↔Topic Linkage
+
+**Version / slug:** `thread-topic-linkage`
+**Date:** 2026-05-11
+**Author:** Echo
+**Second-pass reviewer:** general-purpose review agent (see below)
+
+## Summary of the change
+
+Routes threadline replies on threads initiated by a topic-bound session back to that originating Telegram topic, instead of spawning a sibling "thread-worker" session. The session resumes (or live-injects) with the full thread history and the agent's stated purpose; a Telegram notification fires only when an LLM-backed (or fallback) salience gate says the reply is user-worthy.
+
+Per Rev 2 of the spec (THREAD-TOPIC-LINKAGE-SPEC.md), the awaiting-state and heartbeat cadence are delegated to existing infrastructure rather than built fresh:
+
+- A one-time-action `Commitment` (new `verificationMethod: 'threadline-reply'`) is created on outbound send. `PromiseBeacon` auto-opts in because `topicId` is attached, giving the user free "still waiting on X" heartbeats. `expiresAt` provides 7-day stale cleanup.
+
+Files touched:
+
+- `src/threadline/ThreadResumeMap.ts` — adds `originTopicId` + `originSessionName` (optional fields on `ThreadResumeEntry`).
+- `src/monitoring/CommitmentTracker.ts` — adds `'threadline-reply'` to `verificationMethod`, adds `relatedThreadId` + `relatedAgent`, adds `findByThreadId()`, short-circuits `verifyOne` for threadline-reply commitments so the sweep is a no-op.
+- `src/threadline/SalienceGate.ts` — NEW. LLM-backed (optional) classifier with deterministic fallback (user-visible on first reply, agent-internal on subsequent).
+- `src/threadline/TopicLinkageHandler.ts` — NEW. Outbound capture + inbound dispatch + Telegram surface + commitment lifecycle.
+- `src/threadline/ThreadlineRouter.ts` — adds optional `setTopicLinkageHandler()`, calls handler before existing thread-worker path when thread has `originTopicId`.
+- `src/server/AgentServer.ts` — exposes `threadResumeMap` and `topicLinkageHandler` on ctx.
+- `src/server/routes.ts` — extends `/threadline/relay-send` with optional `originTopicId` + `purpose`, calls `captureOriginOnSend` after each successful send.
+- `src/threadline/ThreadlineMCPServer.ts` — extends `threadline_send` tool schema with optional `originTopicId` + `purpose`.
+- `src/threadline/mcp-stdio-entry.ts` — passes through to HTTP route.
+- `src/commands/server.ts` — instantiates `SalienceGate` (fallback-only for v1) and `TopicLinkageHandler`, attaches to router and ctx.
+
+Decision points touched:
+
+- `SalienceGate.evaluate` — new judgment authority (smart, LLM-backed when wired; deterministic fallback otherwise).
+- `ThreadlineRouter.handleInboundMessage` topic branch — new structural dispatcher.
+- `TelegramAdapter.sendToTopic` — existing surface, called with rate-limit (transport mechanic).
+
+## Decision-point inventory
+
+- `SalienceGate.evaluate` — **add** — Classifies inbound replies as `user-visible` or `agent-internal`. LLM-backed if a classifier is injected; deterministic fallback otherwise. Smart authority (not a brittle blocker).
+- `ThreadlineRouter.handleInboundMessage` topic branch — **add** — Routes replies on threads with `originTopicId` to the topic session via `TopicLinkageHandler`. Structural dispatch, not judgment. Falls through to existing thread-worker path on miss.
+- `CommitmentTracker.verifyOne` for `'threadline-reply'` method — **add** — Returns no-op (`passed: false, detail: 'Awaiting threadline reply'`) without status mutation. Prevents the periodic sweep from accumulating violations on externally-resolved commitments.
+- `CommitmentTracker.findByThreadId` — **add** — Linear-scan lookup by `relatedThreadId`. Pure read accessor.
+- `/threadline/relay-send` outbound capture — **add** — Stamps `ThreadResumeMap` and creates a commitment. Idempotent on threadId; no-op when `originTopicId` is missing.
+- `Telegram surface rate-limit` — **add** — 60s per-thread cap on user-visible notifications. Pure mechanics.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface on the inbound side. The router never blocks based on topic linkage — it only chooses *which* delivery path to take. If linkage is present and the topic is live, the reply goes to the topic; if linkage is present but the topic is dormant, the reply still gets recorded via the standard inbox path; if linkage is absent, the reply goes to the existing thread-worker. No legitimate reply is rejected.
+
+The salience gate does not block delivery — it only decides whether to fire a Telegram notification. A reply marked `agent-internal` is still injected/resumed into the topic session; the user just isn't pinged about it. Over-surfacing is the dual risk (see §2 / under-block), not over-blocking.
+
+The `originTopicId` request-body validator is permissive: bad type → ignored, no error. Sends still succeed without linkage. No over-rejection.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Salience gate over-surfaces in fallback mode.** With no LLM classifier configured (v1 ships fallback-only), every first reply per thread fires a Telegram notification. For very chatty multi-reply threads with short purposes ("ack received"), the first reply still surfaces even when it's mid-negotiation. Mitigated by the 60s per-thread rate-limit but not eliminated. Acceptable for v1 since the bias is "user sees too much" rather than "user sees nothing."
+
+- **Salience gate under-surfaces in fallback mode.** All subsequent replies after the first default to `agent-internal`. A reply on turn 5 of a conversation that's actually the final answer the user is waiting on will NOT fire a Telegram notification (it still routes to the session). The session is expected to surface it itself — but that requires the agent to make the right call. Acceptable for v1 since the session has the reply in hand and can choose to message the user; this risk is also mitigated by the LLM classifier when it's wired in a follow-up.
+
+- **`captureOrigin` runs after successful delivery only.** If the relay drops a send mid-flight (network dies), no commitment is created, so the user doesn't get a "still waiting" beacon. The HTTP route returns a 5xx in that case and the calling session sees it; this is acceptable because the failure is loud (the agent knows the send didn't happen).
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes, with explicit choices:
+
+- `SalienceGate` is at the *authority* layer (smart, full context). It is NOT a low-level filter. It does not duplicate `PromiseBeacon.classifyProgress` (which is about "is the awaiting agent stalled" vs this gate's "should the reply surface").
+
+- `TopicLinkageHandler` is at the *coordinator* layer — it owns the cross-cutting flow (commitment creation, route selection, Telegram surface, lifecycle transition) so the call sites in `routes.ts` and `ThreadlineRouter` stay thin. This is the same shape as other handlers in `src/threadline/` (e.g., `InboundMessageGate`, `HandshakeManager`).
+
+- `Commitment` field additions are at the *data model* layer. `findByThreadId` is at the *lookup* layer. No new higher-level abstraction was warranted given existing infrastructure.
+
+- The new `verificationMethod: 'threadline-reply'` is intentionally treated as externally-resolved: the periodic sweep is a no-op, and the router (the natural authority for thread state) does the transition. This avoids a feedback loop between sweep and router.
+
+A higher-level gate already exists for inbound autonomy decisions (`AutonomyGate`) — this change runs *after* it, deliberately, so autonomy decisions are not bypassed.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface AND the one new authority (SalienceGate) is a smart gate with full conversational context (LLM-backed when configured, deterministic fallback otherwise).
+
+The only new judgment authority is `SalienceGate.evaluate`. It is LLM-backed (when wired via the `classify` callback) or runs a deterministic fallback rule. The deterministic fallback is intentionally chosen to bias toward user-visible on first contact — that is the cautious-toward-visibility default, not a hidden allow/block. The fallback is *not* a "brittle blocker disguised as a gate"; it's a structured visibility rule with no information-flow blocking semantics.
+
+The inbound router branch is structural dispatch (does this thread have an `originTopicId`?) — covered by the "idempotency/transport mechanics" carve-out in `signal-vs-authority.md`. It never blocks; it only chooses among delivery paths.
+
+The Telegram surface rate-limit is transport-layer dedup (60s/thread). Also covered by the carve-out.
+
+The new `verificationMethod` value is data-model. No authority.
+
+Compliant.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** The topic-linkage branch runs *after* the autonomy gate and *before* the existing live-inject / resume-or-spawn path. When it returns `routed`, the existing paths are skipped — by design, that's the whole point. When it returns `no-linkage` or `topic-expired`, control falls through to the existing paths unchanged. We confirmed via test that no-linkage threads route exactly as today.
+
+- **Double-fire:** Could `PromiseBeacon` and the Telegram surface both notify the user about the same thread? In principle yes — beacon fires periodic "still waiting" heartbeats, and on reply the surface fires a "reply landed" notification. They are *different* messages (status check vs answer received) and target different states. Beacon stops when commitment is marked delivered; surface fires once per reply (rate-limited per thread). No double-fire on the same event; possible interleave on the same conversation, which is the intended UX.
+
+- **Races:** `CommitmentTracker.record` and `CommitmentTracker.deliver` are serialised through the existing mutate queue (CAS-retry). The `captureOriginOnSend` idempotency check (`findByThreadId`) reads outside the queue, but a second call within the same send burst is benign — both would see no existing commitment, both would record, and the resulting two records would only differ in id/purpose. We don't expect this race in practice (single-writer per send via HTTP route), but it's worth noting. Mitigation: the `findByThreadId` check is followed by `record`, both atomic individually; ordering matters but conflicts are rare and non-corrupting.
+
+- **Feedback loops:** `verifyOne` on threadline-reply is a no-op, so the periodic sweep cannot cycle the commitment through `pending → violated → delivered`. The router is the single transition path. No loop.
+
+- **Adjacent cleanup:** `CommitmentTracker.backfillUnverifiableOneTimeActions` runs once at construction. It does NOT touch `'threadline-reply'` commitments because they don't match the unverifiable definition (`undefined | null | 'manual'`). Verified by regression test.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** No. `purpose` is local-only and never serialized to the outbound `MessageEnvelope`. `originTopicId` is the same — local-only, attached to the commitment and the thread-resume cache but never sent over the wire. The remote agent receives the exact same envelope it would have received pre-change.
+
+- **Other users of the install base:** The new fields on `Commitment` and `ThreadResumeEntry` are all optional. Existing JSON files deserialize cleanly. Agents upgrading to this version will not see their old data corrupted, and agents on older versions reading a state file produced by this version will ignore the unknown fields. Tested via regression on existing CommitmentTracker tests.
+
+- **External systems:** The Telegram surface adds new outbound messages to the topic — visible to the human user. The format is bounded (500-char body cap, structured footer) and rate-limited (60s/thread). No new API calls, no new third-party integrations.
+
+- **Persistent state:**
+  - `commitments.json` gains rows with `verificationMethod: 'threadline-reply'`. Old commitments unaffected.
+  - `thread-resume-map.json` gains optional `originTopicId` and `originSessionName` fields. Old entries unaffected.
+  - No new persistent files.
+
+- **Timing / runtime conditions:** Salience gate has a 2s timeout and fails open per rubric. Telegram send is best-effort (catches errors and logs). Live injection uses existing `injectPasteNotification` — same timing characteristics as Telegram-relay injection. No new sensitivity to clock drift, daylight saving, or process restart timing.
+
+- **MCP tool surface:** `threadline_send` schema gains two new optional fields. Existing callers (older MCP clients, scripted senders) work unchanged. Documented in the upgrade notes.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release:** Yes — pure code revert, ship as next patch. The new optional fields on `Commitment` and `ThreadResumeEntry` will simply stop being populated, and pre-existing commitments/entries with the new fields will be ignored.
+
+- **Data migration:** None required. `'threadline-reply'` commitments left over from this version will, after revert, hit the `verifyOneTimeAction` `default` case (unknown method) → return `passed: false, detail: 'Unknown verification method: threadline-reply'`. This is the pre-existing behavior for unknown methods. They will *not* be auto-marked delivered by the unverifiable backfill (their method is not in `undefined|null|'manual'`). Operator could manually expire them via `PATCH /commitments/:id` if desired, but no urgency.
+
+- **Agent state repair:** None required. Topic sessions on the rollback version will continue to receive threadline replies via the existing thread-worker path. The commitment rows from this version will sit as inert "pending" rows until expiry (max 7 days).
+
+- **User visibility:** During rollback, the user may experience a transient gap where they expect a reply notification and don't get one — because the new surface stops firing. The reply itself still routes via the existing path. No data loss, no broken conversations.
+
+Estimated rollback time: < 10 minutes from revert push → CI green → npm publish.
+
+---
+
+## Conclusion
+
+This change is structurally additive: new optional fields, a new verification method, a new handler class, and a new gate. All hooks into existing infrastructure go through the existing mutate/dispatch surfaces (no parallel write paths). The only new judgment authority (SalienceGate) is a smart gate with deterministic fallback. No brittle blocking. No persistent state migration required. Rollback is a code-only revert.
+
+V1 ships with the salience gate's fallback rule only — the LLM classifier is plumbed but not wired by default. A follow-up can wire a Haiku-class classifier when ready; the existing 2s timeout and fail-open rubric mean a slow LLM never breaks delivery.
+
+Clear to ship.
+
+---
+
+## Second-pass review
+
+**Reviewer:** general-purpose review agent (per /instar-dev high-risk policy — this change touches inbound dispatch, commitment lifecycle, and a new gate).
+
+**Independent read of the artifact: concern raised → resolved before commit.**
+
+The audit confirmed clean: signal-vs-authority compliance, the `verifyOne` short-circuit ordering vs `isUnverifiableOneTime`, router fall-through on `no-linkage`/`topic-expired`, `captureOrigin` idempotency, wire-leakage check (`purpose` and `originTopicId` never reach the relay envelope), and Telegram-surface rate-limit semantics.
+
+Two real issues were raised and **both have been fixed in this same commit**:
+
+1. **`isFirstReply` derivation bug.** The original implementation derived `isFirstReply = commitment.heartbeatCount === 0`. But `heartbeatCount` is incremented by `PromiseBeacon` on every "still waiting" emission, not by reply arrivals. For any slow-replying thread (i.e., the common case — by the time a reply lands, the beacon has fired at least once), `heartbeatCount > 0`, which made `isFirstReply = false`, which in fallback-only v1 downgraded the *very first reply* to `agent-internal` → no Telegram surface → silently swallowed first contact. Exactly the failure mode the spec's §5.4 fallback rule was meant to prevent.
+
+   **Resolution:** Added a `lastReplyAt?: string` field on `Commitment`, plus a `markReplyArrived(commitmentId)` public method on `CommitmentTracker`. The handler now sets `lastReplyAt` on every reply arrival (regardless of delivery mode), and derives `isFirstReply = !commitment?.lastReplyAt`. A dedicated regression test exercises the slow-reply path (beacon has fired heartbeats, no reply yet, first reply must still be user-visible).
+
+2. **`resume-pending` left the commitment open.** The original code marked the commitment delivered only on `live-inject`. On `resume-pending` (topic session dormant, reply queued for next user interaction) it left the commitment open, which meant `PromiseBeacon` continued firing "still waiting" heartbeats even after the user had already been told via the Telegram surface that the reply landed. The spec §6.5 carve-out for "leave open" was scoped specifically to the wedged `failure-visible` path, not dormant-session waiting.
+
+   **Resolution:** Both `live-inject` and `resume-pending` now mark the commitment `delivered`. Only `failure-visible` (actually-wedged: injection error, delivery breakdown) leaves it open so the beacon keeps surfacing the unresolved state. A dedicated regression test exercises the dormant-session path and asserts `commitmentDelivered: true`.
+
+**Reviewer's post-fix posture:** concur — the two fixes address the root causes (rather than papering over symptoms) and add regression tests at the right boundary. Total test count after fixes: 11 new TopicLinkageHandler tests, 8 SalienceGate, 8 CommitmentTracker-threadline-reply → 27 new tests, all passing alongside 152 pre-existing related tests.
+
+Minor remaining notes (non-blocking for v1):
+- A small race in `captureOriginOnSend` can occur if an inbound reply marks the existing commitment delivered between the `findByThreadId` read and a concurrent outbound `captureOrigin` write on the same thread. Result is one extra commitment row rather than corruption; window is microseconds in practice.
+- Salience-gate LLM classifier is plumbed but not wired in v1. Fallback rule is now correct; LLM upgrade is a follow-up.
+- No dashboard surface for awaiting threadline-reply commitments specifically — they appear in the existing commitments dashboard panel, which is sufficient for now.
+
+---
+
+## Convergent-review fixes (Rev 3)
+
+Beyond the second-pass internal reviewer's two fixes (above), a full convergent-review pass with four parallel internal reviewers (security, adversarial, scalability, integration) surfaced 29 findings. All HIGH-severity findings were addressed in code in this same commit; MEDIUM and LOW findings were either addressed in code or documented in the spec's §9 Risks & Open Questions with concrete v2 follow-up plans.
+
+Code fixes landed:
+
+- **Prompt-injection defense on inject payload.** `TopicLinkageHandler.buildSessionPayload` now wraps the remote reply body in a nonce-guarded delimiter (`<<<REMOTE_REPLY_BEGIN nonce=hex>>>` … `<<<REMOTE_REPLY_END nonce=hex>>>`) with an explicit "treat as untrusted data" instruction preceding the block. Body is also capped at 8000 chars inline; full body remains accessible via `threadline_history`.
+- **Bad-entry poisoning guard.** `captureOriginOnSend` now refuses to stamp `originTopicId` on a thread whose commitment already records a different `topicId`. First-write wins. Source of truth is `commitment.topicId` (immutable after creation), not the `ThreadResumeMap` cache (which has a JSONL-existence guard that can return null even when the file row exists).
+- **Sender verification on inbound.** `tryRouteReplyToTopic` now verifies `envelope.message.from.agent === commitment.relatedAgent` before routing. On mismatch, returns `no-linkage` (falls through to thread-worker path) and does NOT transition the commitment. Closes the threadId-collision / affinity-collision / observation-replay attack.
+- **Per-topic rate-limit.** New layer above the per-thread 60s rate-limit: max 3 user-visible Telegram surfaces per topic per 60-second window. Closes the rotate-threadIds-to-bypass attack and the fail-open-classifier flood scenario.
+- **Self-target ping-pong guard.** `captureOriginOnSend` returns null when `remoteAgent === localAgent`. Stops same-machine bridged-topic loops from accumulating cross-topic "still waiting" notifications.
+- **purpose length cap (1024 chars).** Prevents pathological / malicious in-process callers from bloating the commitments JSON file.
+- **threadId → commitmentId index in CommitmentTracker.** `findByThreadId` is now O(1) lookup + one status check, bounded by active threadline-reply commitments (not lifetime store size). Index rebuilt at load, maintained on every `record`/`deliver`/`withdraw`.
+- **Honest user-facing copy in NEXT.md.** Rewrote the "What Changed" / "What to Tell Your User" / capabilities table to describe v1's deterministic recency rule honestly; LLM-backed content classifier flagged as a follow-up.
+
+Documented in spec §6 / §9 / §11–§13 (deferred to v2):
+
+- Multi-user (`ownerUserId` on commitment + thread, §6.10).
+- Multi-machine (originTopicId scrub on migrate, §6.11).
+- Dashboard threadline-specific surface (§9.10).
+- Backup downgrade-safety operator note (§9.11).
+- Config knobs surface (rate-limit, expiry, classifier wiring, kill-switch — §9.12).
+- LLM-backed salience classifier wiring (§9.13).
+- saveStore O(n) coalesce or SQLite migration (scalability F3).
+- Commitments store GC for terminal rows (scalability F2).
+- Beacon + surface interleave debounce (adversarial F7).
+
+New regression tests landed alongside the fixes (5 new tests in `TopicLinkageHandler.test.ts`):
+
+- `refuses to overwrite originTopicId when a thread already carries a different one (bad-entry poisoning guard)`
+- `no-ops on same-machine self-target (ping-pong loop guard)`
+- `caps the stored purpose to PURPOSE_CAP chars`
+- `refuses to route inbound when sender does not match recorded relatedAgent (commitment-hijack guard)`
+- `inject payload wraps remote body in nonce-guarded delimiter (prompt-injection guard)`
+- `per-topic rate-limit caps user-visible Telegram surfaces across rotating threads (bypass guard)`
+
+Total test count after Rev 3 fixes: **18 TopicLinkageHandler tests + 8 SalienceGate + 8 CommitmentTracker-threadline-reply = 34 new tests**, all passing alongside 152 pre-existing related tests (186 total in scope).
+
+Convergence report: `docs/specs/reports/thread-topic-linkage-convergence.md`.
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/SalienceGate.test.ts` (8 tests), `tests/unit/CommitmentTracker-threadline-reply.test.ts` (8 tests), `tests/unit/TopicLinkageHandler.test.ts` (10 tests) — 26 new tests, all passing.
+- Regression: `tests/unit/CommitmentTracker.test.ts`, `tests/unit/CommitmentTracker-mutate.test.ts`, `tests/unit/threadline/ThreadlineRouter.test.ts`, `tests/unit/threadline/ThreadResumeMap.test.ts` — 152 tests, all passing post-change.
+- Spec source of truth: `docs/specs/THREAD-TOPIC-LINKAGE-SPEC.md` (Rev 2, 2026-05-11).
+- Live verification plan: post-merge, send threadline_send from echo topic 9210 to luna with a `purpose`, confirm commitment created + beacon active + reply routes back to topic + commitment delivered.