instar 0.28.88 → 0.28.90

package/dist/core/SessionRefresh.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SessionRefresh — orchestrates an agent-initiated session respawn.
+ *
+ * When an agent installs a new MCP server or skill mid-session, Claude Code
+ * only attaches the new tools at session start. The agent triggers this class
+ * to kill its current tmux session and respawn it with `claude --resume <uuid>`,
+ * which loads the freshly installed tools while preserving full conversation
+ * state.
+ *
+ * The respawn lifecycle is owned end-to-end here:
+ *   detect    — sanity-check session, topic binding, resume UUID exist
+ *   attempt   — apply rate guard, persist resume UUID, kill tmux, respawn
+ *   verify    — new session is registered for the topic
+ *   finalize  — return structured result
+ *
+ * Rate guard is a structural rate-counter (allowed-detector category per
+ * docs/signal-vs-authority.md "safety guards on irreversible actions"
+ * carve-out) — prevents infinite-respawn loops. Not a judgment call.
+ *
+ * v1 scope: Telegram-bound sessions only. Non-Telegram-bound respawn is a
+ * v2 follow-up — returns { ok: false, code: 'not_telegram_bound' } for now.
+ */
+import type { SessionManager } from './SessionManager.js';
+import type { StateManager } from './StateManager.js';
+import type { TelegramAdapter } from '../messaging/TelegramAdapter.js';
+import type { TopicResumeMap } from './TopicResumeMap.js';
+export interface SessionRefreshDeps {
+    sessionManager: SessionManager;
+    state: StateManager;
+    telegram: TelegramAdapter | null;
+    topicResumeMap: TopicResumeMap | null;
+    /**
+     * Respawn callback. Wired by server bootstrap to call
+     * respawnSessionForTopic with the right closure (sessionManager,
+     * telegram, topicMemory, etc). Kept as a callback to keep this class
+     * decoupled from the server-internal respawn helper.
+     *
+     * IMPORTANT: respawnSessionForTopic does NOT kill the old tmux session
+     * — it only spawns a new one and re-registers the topic mapping.
+     * SessionRefresh.refreshSession is responsible for killing the old
+     * session via sessionManager.killSession BEFORE calling the respawner,
+     * which also triggers the beforeSessionKill listener that persists
+     * the resume UUID.
+     *
+     * Resolves to the new tmux session name on success.
+     */
+    respawner: (sessionName: string, topicId: number, followUpPrompt: string | undefined) => Promise<string>;
+    /** Rate-guard config. Defaults: 5 refreshes per 10-minute rolling window. */
+    rateLimit?: {
+        maxPerWindow: number;
+        windowMs: number;
+    };
+    /** Injectable clock for tests. Defaults to Date.now. */
+    clock?: () => number;
+}
+export type RefreshResult = {
+    ok: true;
+    newSessionName: string;
+    topicId: number;
+} | {
+    ok: false;
+    code: RefreshFailureCode;
+    message: string;
+};
+export type RefreshFailureCode = 'rate_limited' | 'session_not_found' | 'not_telegram_bound' | 'no_telegram_adapter' | 'refresh_in_progress';
+export interface RefreshOptions {
+    sessionName: string;
+    followUpPrompt?: string;
+    reason?: string;
+}
+export declare class SessionRefresh {
+    private readonly deps;
+    private readonly maxPerWindow;
+    private readonly windowMs;
+    private readonly clock;
+    private readonly recentRefreshes;
+    /** In-flight refresh guard — prevents the race where a second call
+     *  fires before the first's kill+spawn completes, which would spawn
+     *  two parallel sessions for the same topic. */
+    private readonly inFlight;
+    constructor(deps: SessionRefreshDeps);
+    /**
+     * Refresh a session: kill its tmux session (which fires beforeSessionKill
+     * so the existing listener persists the Claude UUID via TopicResumeMap),
+     * then respawn via the injected respawner which spawns a fresh tmux that
+     * runs `claude --resume <uuid>` — picking up newly installed MCPs/skills
+     * while preserving the full conversation.
+     *
+     * Returns a structured result; never throws on the expected failure modes
+     * (rate-limit, session-not-found, non-Telegram-bound). Throws only on
+     * unexpected internal errors from the respawner callback.
+     */
+    refreshSession(opts: RefreshOptions): Promise<RefreshResult>;
+    /**
+     * Returns true if a fresh refresh is allowed under the rolling window cap.
+     * Pure read of the recent-refresh ledger; does not mutate.
+     */
+    private checkRateLimit;
+    /** Append a timestamp to the rolling window for this session. */
+    private recordRefresh;
+    /**
+     * Structured log when the rate guard blocks a request. Logged at warn
+     * level so over-blocks are detectable in operations (per
+     * docs/signal-vs-authority.md "Authorities must log their decisions").
+     */
+    private logRateLimit;
+}
+//# sourceMappingURL=SessionRefresh.d.ts.map

package/dist/core/SessionRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionRefresh.d.ts","sourceRoot":"","sources":["../../src/core/SessionRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,cAAc,CAAC;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzG,6EAA6E;IAC7E,SAAS,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,mBAAmB,GACnB,oBAAoB,GACpB,qBAAqB,GACrB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IACpE;;oDAEgD;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,IAAI,EAAE,kBAAkB;IAOpC;;;;;;;;;;OAUG;IACG,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAoFlE;;;OAGG;IACH,OAAO,CAAC,cAAc;IAWtB,iEAAiE;IACjE,OAAO,CAAC,aAAa;IAOrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAKrB"}

package/dist/core/SessionRefresh.js

@@ -0,0 +1,157 @@
+/**
+ * SessionRefresh — orchestrates an agent-initiated session respawn.
+ *
+ * When an agent installs a new MCP server or skill mid-session, Claude Code
+ * only attaches the new tools at session start. The agent triggers this class
+ * to kill its current tmux session and respawn it with `claude --resume <uuid>`,
+ * which loads the freshly installed tools while preserving full conversation
+ * state.
+ *
+ * The respawn lifecycle is owned end-to-end here:
+ *   detect    — sanity-check session, topic binding, resume UUID exist
+ *   attempt   — apply rate guard, persist resume UUID, kill tmux, respawn
+ *   verify    — new session is registered for the topic
+ *   finalize  — return structured result
+ *
+ * Rate guard is a structural rate-counter (allowed-detector category per
+ * docs/signal-vs-authority.md "safety guards on irreversible actions"
+ * carve-out) — prevents infinite-respawn loops. Not a judgment call.
+ *
+ * v1 scope: Telegram-bound sessions only. Non-Telegram-bound respawn is a
+ * v2 follow-up — returns { ok: false, code: 'not_telegram_bound' } for now.
+ */
+const DEFAULT_MAX_PER_WINDOW = 5;
+const DEFAULT_WINDOW_MS = 10 * 60 * 1000;
+export class SessionRefresh {
+    deps;
+    maxPerWindow;
+    windowMs;
+    clock;
+    recentRefreshes = new Map();
+    /** In-flight refresh guard — prevents the race where a second call
+     *  fires before the first's kill+spawn completes, which would spawn
+     *  two parallel sessions for the same topic. */
+    inFlight = new Set();
+    constructor(deps) {
+        this.deps = deps;
+        this.maxPerWindow = deps.rateLimit?.maxPerWindow ?? DEFAULT_MAX_PER_WINDOW;
+        this.windowMs = deps.rateLimit?.windowMs ?? DEFAULT_WINDOW_MS;
+        this.clock = deps.clock ?? Date.now;
+    }
+    /**
+     * Refresh a session: kill its tmux session (which fires beforeSessionKill
+     * so the existing listener persists the Claude UUID via TopicResumeMap),
+     * then respawn via the injected respawner which spawns a fresh tmux that
+     * runs `claude --resume <uuid>` — picking up newly installed MCPs/skills
+     * while preserving the full conversation.
+     *
+     * Returns a structured result; never throws on the expected failure modes
+     * (rate-limit, session-not-found, non-Telegram-bound). Throws only on
+     * unexpected internal errors from the respawner callback.
+     */
+    async refreshSession(opts) {
+        const { sessionName, followUpPrompt, reason } = opts;
+        // ── detect ─────────────────────────────────────────────────────────
+        if (!this.deps.telegram) {
+            return {
+                ok: false,
+                code: 'no_telegram_adapter',
+                message: 'No Telegram adapter wired — self-refresh requires a Telegram-bound session in v1.',
+            };
+        }
+        const topicId = this.deps.telegram.getTopicForSession(sessionName);
+        if (topicId === null) {
+            // TODO(v2): handle non-Telegram-bound sessions (Slack, iMessage,
+            // headless). Today only Telegram-bound is supported because the
+            // respawn path is built around topicId → context routing.
+            return {
+                ok: false,
+                code: 'not_telegram_bound',
+                message: `Session "${sessionName}" is not bound to a Telegram topic; cannot self-refresh in v1.`,
+            };
+        }
+        // Look up the state session by tmux name — needed for killSession,
+        // which takes the state session id, not the tmux session name.
+        const stateSession = this.deps.state.listSessions({ status: 'running' })
+            .find(s => s.tmuxSession === sessionName);
+        if (!stateSession) {
+            return {
+                ok: false,
+                code: 'session_not_found',
+                message: `No running session found for tmux name "${sessionName}".`,
+            };
+        }
+        // ── in-flight guard ────────────────────────────────────────────────
+        if (this.inFlight.has(sessionName)) {
+            return {
+                ok: false,
+                code: 'refresh_in_progress',
+                message: `A refresh is already in progress for "${sessionName}".`,
+            };
+        }
+        // ── rate guard ─────────────────────────────────────────────────────
+        if (!this.checkRateLimit(sessionName)) {
+            this.logRateLimit(sessionName, reason);
+            return {
+                ok: false,
+                code: 'rate_limited',
+                message: `Refresh rate limit exceeded (${this.maxPerWindow} per ${Math.round(this.windowMs / 60000)} minutes) for session "${sessionName}".`,
+            };
+        }
+        // ── attempt ────────────────────────────────────────────────────────
+        // Record the attempt against the rate guard window BEFORE the work —
+        // we count attempts, not successes, so a flapping respawner can't
+        // bypass the cap. Also mark in-flight so a parallel call refuses.
+        this.recordRefresh(sessionName);
+        this.inFlight.add(sessionName);
+        try {
+            // Kill via sessionManager so the beforeSessionKill listener fires
+            // and persists the resume UUID using session.claudeSessionId. This
+            // replaces the previous SessionRefresh-side findUuidForSession+save
+            // dance, which would silently no-op (findUuidForSession requires
+            // claudeSessionId as second arg; without it, the mtime fallback was
+            // removed deliberately and the call returns null).
+            this.deps.sessionManager.killSession(stateSession.id);
+            // The respawner spawns a fresh tmux session that runs `claude
+            // --resume <uuid>` (resolved by spawnSessionForTopic via the saved
+            // TopicResumeMap entry) and re-registers the topic mapping.
+            const newSessionName = await this.deps.respawner(sessionName, topicId, followUpPrompt);
+            // ── verify + finalize ────────────────────────────────────────────
+            console.log(`[SessionRefresh] Refreshed "${sessionName}" → "${newSessionName}" (topic ${topicId})${reason ? ` reason="${reason}"` : ''}`);
+            return { ok: true, newSessionName, topicId };
+        }
+        finally {
+            this.inFlight.delete(sessionName);
+        }
+    }
+    /**
+     * Returns true if a fresh refresh is allowed under the rolling window cap.
+     * Pure read of the recent-refresh ledger; does not mutate.
+     */
+    checkRateLimit(sessionName) {
+        const now = this.clock();
+        const recent = this.recentRefreshes.get(sessionName) ?? [];
+        const fresh = recent.filter(ts => now - ts < this.windowMs);
+        if (fresh.length !== recent.length) {
+            // Prune stale entries opportunistically.
+            this.recentRefreshes.set(sessionName, fresh);
+        }
+        return fresh.length < this.maxPerWindow;
+    }
+    /** Append a timestamp to the rolling window for this session. */
+    recordRefresh(sessionName) {
+        const now = this.clock();
+        const recent = this.recentRefreshes.get(sessionName) ?? [];
+        recent.push(now);
+        this.recentRefreshes.set(sessionName, recent);
+    }
+    /**
+     * Structured log when the rate guard blocks a request. Logged at warn
+     * level so over-blocks are detectable in operations (per
+     * docs/signal-vs-authority.md "Authorities must log their decisions").
+     */
+    logRateLimit(sessionName, reason) {
+        console.warn(`[SessionRefresh] rate_limited sessionName=${sessionName} window=${this.windowMs}ms cap=${this.maxPerWindow}${reason ? ` reason=${reason}` : ''}`);
+    }
+}
+//# sourceMappingURL=SessionRefresh.js.map

package/dist/core/SessionRefresh.js.map

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

package/dist/monitoring/CommitmentTracker.d.ts

@@ -56,9 +56,26 @@ export interface Commitment {
     /** For behavioral/one-time: when this commitment expires (null = forever) */
     expiresAt?: string;
     /** For one-time-action: verification method */
-    verificationMethod?: 'config-value' | 'file-exists' | 'manual';
+    verificationMethod?: 'config-value' | 'file-exists' | 'manual' | 'threadline-reply';
     /** For one-time-action with file-exists: the path to check */
     verificationPath?: string;
+    /**
+     * For verificationMethod === 'threadline-reply': the thread we're waiting on.
+     * Resolved externally by ThreadlineRouter when the awaited reply arrives —
+     * the periodic verify sweep is a no-op for this method.
+     * Per THREAD-TOPIC-LINKAGE-SPEC.md.
+     */
+    relatedThreadId?: string;
+    /** For verificationMethod === 'threadline-reply': the remote agent. */
+    relatedAgent?: string;
+    /**
+     * For verificationMethod === 'threadline-reply': ISO timestamp of the most
+     * recently delivered reply on this thread. Used by the salience gate's
+     * first-reply detection (a thread is "first contact" iff no `lastReplyAt`
+     * has been recorded yet). Distinct from `heartbeatCount`, which counts
+     * beacon emissions, not reply arrivals.
+     */
+    lastReplyAt?: string;
     /** Number of times auto-correction has fired for this commitment */
     correctionCount: number;
     /** Timestamps of recent corrections (for pattern detection) */
@@ -167,6 +184,13 @@ export declare class CommitmentTracker extends EventEmitter {
      */
     private mutateQueues;
     private mutateRunning;
+    /**
+     * Bounded thread→commitment index for fast O(1) findByThreadId lookups.
+     * Keyed by relatedThreadId, value is the commitment id. Only includes
+     * threadline-reply commitments in non-terminal states. Rebuilt on load,
+     * maintained on every mutate.
+     */
+    private threadIdIndex;
     constructor(config: CommitmentTrackerConfig);
     /**
      * One-shot migration: any pre-existing one-time-action that is stuck
@@ -192,8 +216,10 @@ export declare class CommitmentTracker extends EventEmitter {
         configExpectedValue?: unknown;
         behavioralRule?: string;
         expiresAt?: string;
-        verificationMethod?: 'config-value' | 'file-exists' | 'manual';
+        verificationMethod?: 'config-value' | 'file-exists' | 'manual' | 'threadline-reply';
         verificationPath?: string;
+        relatedThreadId?: string;
+        relatedAgent?: string;
         beaconEnabled?: boolean;
         cadenceMs?: number;
         nextUpdateDueAt?: string;
@@ -214,6 +240,43 @@ export declare class CommitmentTracker extends EventEmitter {
      * heartbeats, no more verify attempts.
      */
     deliver(id: string, deliveryMessageId?: string): Commitment | null;
+    /**
+     * Record that a reply arrived on a threadline-reply commitment. Updates
+     * `lastReplyAt` without transitioning status. Used by the salience gate's
+     * first-reply detection — `heartbeatCount` is incremented by PromiseBeacon
+     * for "still waiting" emissions, not by reply arrivals, so we need a
+     * separate signal here.
+     *
+     * No-op on missing commitment or wrong type. Goes through mutateSync so
+     * concurrent writes serialize cleanly.
+     */
+    markReplyArrived(id: string, replyAt?: string): Commitment | null;
+    /**
+     * Find the active threadline-reply commitment for a given threadId.
+     *
+     * Used by ThreadlineRouter when an inbound reply arrives: looks up the
+     * commitment so the router can transition it to `delivered` and pull the
+     * stated purpose / topicId. Skips terminal states (delivered/expired/
+     * withdrawn) so late replies don't reopen closed commitments. Returns
+     * null on miss.
+     *
+     * Uses a thread→commitment-id index maintained alongside the store so the
+     * lookup is O(1) plus one O(commitment) status check, bounded by active
+     * threadline-reply commitments (not lifetime commitment count). Per
+     * scalability review F1 — the lifetime store can grow unboundedly while
+     * the index stays bounded by active threads.
+     */
+    findByThreadId(threadId: string): Commitment | null;
+    /**
+     * Maintain the threadId→commitmentId index. Called after any mutation that
+     * affects a threadline-reply commitment's state. Bounded by active count.
+     */
+    private refreshThreadIdIndex;
+    /**
+     * Build the threadId→commitmentId index from the persisted store. Called
+     * once at startup. Linear in store size, but only runs at load time.
+     */
+    private rebuildThreadIdIndex;
     /**
      * Get all active commitments (pending or verified, not expired).
      *

package/dist/monitoring/CommitmentTracker.d.ts.map

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

package/dist/monitoring/CommitmentTracker.js

@@ -41,6 +41,13 @@ export class CommitmentTracker extends EventEmitter {
      */
     mutateQueues = new Map();
     mutateRunning = new Set();
+    /**
+     * Bounded thread→commitment index for fast O(1) findByThreadId lookups.
+     * Keyed by relatedThreadId, value is the commitment id. Only includes
+     * threadline-reply commitments in non-terminal states. Rebuilt on load,
+     * maintained on every mutate.
+     */
+    threadIdIndex = new Map();
     constructor(config) {
         super();
         this.config = config;
@@ -49,6 +56,7 @@ export class CommitmentTracker extends EventEmitter {
         this.store = this.loadStore();
         this.nextId = this.computeNextId();
         this.backfillUnverifiableOneTimeActions();
+        this.rebuildThreadIdIndex();
     }
     /**
      * One-shot migration: any pre-existing one-time-action that is stuck
@@ -151,6 +159,8 @@ export class CommitmentTracker extends EventEmitter {
             expiresAt: input.expiresAt,
             verificationMethod: input.verificationMethod,
             verificationPath: input.verificationPath,
+            relatedThreadId: input.relatedThreadId,
+            relatedAgent: input.relatedAgent,
             correctionCount: 0,
             correctionHistory: [],
             escalated: false,
@@ -174,6 +184,7 @@ export class CommitmentTracker extends EventEmitter {
         if (input.type === 'behavioral') {
             this.writeBehavioralRules();
         }
+        this.refreshThreadIdIndex(commitment);
         console.log(`[CommitmentTracker] Recorded ${id}: "${input.userRequest}" (${input.type})`);
         this.emit('recorded', commitment);
         // Run immediate verification for config-change commitments.
@@ -202,6 +213,7 @@ export class CommitmentTracker extends EventEmitter {
         if (updated.type === 'behavioral') {
             this.writeBehavioralRules();
         }
+        this.refreshThreadIdIndex(updated);
         console.log(`[CommitmentTracker] Withdrawn ${id}: ${reason}`);
         this.emit('withdrawn', updated);
         return true;
@@ -225,10 +237,97 @@ export class CommitmentTracker extends EventEmitter {
             resolvedAt: new Date().toISOString(),
             deliveryMessageId: deliveryMessageId ?? c.deliveryMessageId,
         }));
+        this.refreshThreadIdIndex(updated);
         console.log(`[CommitmentTracker] Delivered ${id}`);
         this.emit('delivered', updated);
         return updated;
     }
+    /**
+     * Record that a reply arrived on a threadline-reply commitment. Updates
+     * `lastReplyAt` without transitioning status. Used by the salience gate's
+     * first-reply detection — `heartbeatCount` is incremented by PromiseBeacon
+     * for "still waiting" emissions, not by reply arrivals, so we need a
+     * separate signal here.
+     *
+     * No-op on missing commitment or wrong type. Goes through mutateSync so
+     * concurrent writes serialize cleanly.
+     */
+    markReplyArrived(id, replyAt) {
+        const existing = this.store.commitments.find(c => c.id === id);
+        if (!existing)
+            return null;
+        if (existing.type !== 'one-time-action')
+            return null;
+        if (existing.verificationMethod !== 'threadline-reply')
+            return null;
+        return this.mutateSync(id, c => ({
+            ...c,
+            lastReplyAt: replyAt ?? new Date().toISOString(),
+        }));
+    }
+    /**
+     * Find the active threadline-reply commitment for a given threadId.
+     *
+     * Used by ThreadlineRouter when an inbound reply arrives: looks up the
+     * commitment so the router can transition it to `delivered` and pull the
+     * stated purpose / topicId. Skips terminal states (delivered/expired/
+     * withdrawn) so late replies don't reopen closed commitments. Returns
+     * null on miss.
+     *
+     * Uses a thread→commitment-id index maintained alongside the store so the
+     * lookup is O(1) plus one O(commitment) status check, bounded by active
+     * threadline-reply commitments (not lifetime commitment count). Per
+     * scalability review F1 — the lifetime store can grow unboundedly while
+     * the index stays bounded by active threads.
+     */
+    findByThreadId(threadId) {
+        if (!threadId)
+            return null;
+        const idxId = this.threadIdIndex.get(threadId);
+        if (idxId) {
+            const c = this.store.commitments.find(x => x.id === idxId);
+            if (c &&
+                c.type === 'one-time-action' &&
+                c.verificationMethod === 'threadline-reply' &&
+                c.status !== 'delivered' &&
+                c.status !== 'withdrawn' &&
+                c.status !== 'expired') {
+                return c;
+            }
+            // Stale index entry — drop it so the next call doesn't re-fetch.
+            this.threadIdIndex.delete(threadId);
+        }
+        return null;
+    }
+    /**
+     * Maintain the threadId→commitmentId index. Called after any mutation that
+     * affects a threadline-reply commitment's state. Bounded by active count.
+     */
+    refreshThreadIdIndex(commitment) {
+        if (commitment.type !== 'one-time-action' ||
+            commitment.verificationMethod !== 'threadline-reply' ||
+            !commitment.relatedThreadId) {
+            return;
+        }
+        if (commitment.status === 'delivered' ||
+            commitment.status === 'withdrawn' ||
+            commitment.status === 'expired') {
+            this.threadIdIndex.delete(commitment.relatedThreadId);
+        }
+        else {
+            this.threadIdIndex.set(commitment.relatedThreadId, commitment.id);
+        }
+    }
+    /**
+     * Build the threadId→commitmentId index from the persisted store. Called
+     * once at startup. Linear in store size, but only runs at load time.
+     */
+    rebuildThreadIdIndex() {
+        this.threadIdIndex.clear();
+        for (const c of this.store.commitments) {
+            this.refreshThreadIdIndex(c);
+        }
+    }
     /**
      * Get all active commitments (pending or verified, not expired).
      *
@@ -382,6 +481,15 @@ export class CommitmentTracker extends EventEmitter {
             commitment.status === 'expired' ||
             commitment.status === 'delivered')
             return null;
+        // Threadline-reply commitments are externally resolved by ThreadlineRouter
+        // when the awaited reply arrives. The periodic verify sweep is a no-op —
+        // we neither increment violations nor mark delivered. Per
+        // THREAD-TOPIC-LINKAGE-SPEC.md §4.1. The `expiresAt` handler still applies
+        // and will mark the commitment `expired` if no reply arrives within window.
+        if (commitment.type === 'one-time-action' &&
+            commitment.verificationMethod === 'threadline-reply') {
+            return { passed: false, detail: 'Awaiting threadline reply' };
+        }
         // One-time-actions with no automated verification path cannot keep
         // being "violated" on every sweep — that's how a single commitment
         // accumulated 51,000+ violation ticks. Transition once to
@@ -554,6 +662,11 @@ export class CommitmentTracker extends EventEmitter {
             case 'manual':
                 // Manual commitments stay pending until explicitly resolved
                 return { passed: false, detail: 'Awaiting manual verification' };
+            case 'threadline-reply':
+                // Externally resolved by ThreadlineRouter. verifyOne() short-circuits
+                // before reaching this switch (see verifyOne); included here as a
+                // belt-and-braces fallback so the `default` branch can't be hit.
+                return { passed: false, detail: 'Awaiting threadline reply' };
             default:
                 return { passed: false, detail: `Unknown verification method: ${commitment.verificationMethod}` };
         }