@achieveai/hitl-mcp-server 2.9.6 → 2.11.2

package/dist/ntfy-transport.js

@@ -1,16 +1,315 @@
+import { randomBytes } from 'crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
 import { encrypt, decrypt, isEncryptedEnvelope } from './crypto.js';
 import { shouldChunk, splitIntoChunks } from './chunking.js';
+import { assertNoChunk } from './payload.js';
+/**
+ * Pull ntfy's own attachment metadata off a raw event.
+ *
+ * Shape confirmed live against ntfy.sh:
+ *   {"name":"…","type":"application/octet-stream","size":5000,
+ *    "expires":1786514937,"url":"https://ntfy.sh/file/qurRQchLV1Fb.bin"}
+ *
+ * This is plaintext metadata outside our encryption — `name` echoes the
+ * Filename header, so senders must use random hex there and never a real path.
+ */
+export function parseAttachment(ntfyEvent) {
+    const att = ntfyEvent?.attachment;
+    if (!att || typeof att.url !== 'string')
+        return undefined;
+    return {
+        name: typeof att.name === 'string' ? att.name : '',
+        url: att.url,
+        type: typeof att.type === 'string' ? att.type : undefined,
+        size: typeof att.size === 'number' ? att.size : undefined,
+        expires: typeof att.expires === 'number' ? att.expires : undefined,
+    };
+}
+// -----------------------------------------------------------
+// ntfy error classification
+//
+// Verified live: the error envelope is
+//   {"code":42901,"http":429,"error":"…","link":"…"}
+// where `code` is <http-status><2-digit subcode>. An oversized X-Message is
+// answered by the nginx in front of ntfy with an HTML body instead, so nothing
+// here may assume the body parses as JSON.
+// -----------------------------------------------------------
+/** 429 subcodes that a delay can actually clear. */
+const RETRYABLE_NTFY_CODES = new Set([
+    42901, // too many requests — burst / visitor throttle
+    42911, // too many new topics, please wait
+]);
+/** Codes where retrying is pointless; the reason names how to actually recover. */
+const FATAL_NTFY_CODES = new Map([
+    [42908, 'daily ntfy message quota reached — resets at UTC midnight, or self-host'],
+    [42905, 'daily ntfy attachment bandwidth reached — resets at UTC midnight, or self-host'],
+    [42903, 'too many active ntfy subscriptions for this IP'],
+    [41301, 'attachment rejected by ntfy as oversized'],
+]);
+/** Raised when publishing failed and retrying cannot help. */
+export class NtfyPublishError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'NtfyPublishError';
+    }
+}
+/**
+ * Raised when ntfy refuses the subscription itself.
+ *
+ * `retryable` decides whether the reconnect loop keeps trying. A 403 from an
+ * auth-required topic or a mistyped `ntfyUrl` never becomes a 200, and
+ * reconnecting forever at 30 s hides a diagnosable cause behind a call that
+ * simply never returns.
+ */
+export class NtfySubscribeError extends Error {
+    status;
+    retryable;
+    code;
+    constructor(message, status, retryable, code) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+        this.code = code;
+        this.name = 'NtfySubscribeError';
+    }
+}
+/** Raised when the X-Message header would exceed the proxy's header buffer. */
+export class XMessageTooLargeError extends Error {
+    byteLength;
+    constructor(byteLength) {
+        super(`Plan metadata header is ${byteLength} bytes, over the ${X_MESSAGE_MAX_BYTES}-byte limit. ` +
+            `ntfy sits behind an nginx whose header buffer is 8 KB; this cap is half of it.`);
+        this.byteLength = byteLength;
+        this.name = 'XMessageTooLargeError';
+    }
+}
+/** Raised when an attachment URL 404s — ntfy expires attachments after 3 h. */
+export class AttachmentExpiredError extends Error {
+    url;
+    constructor(url) {
+        super(`Attachment has expired or was never stored: ${url}`);
+        this.url = url;
+        this.name = 'AttachmentExpiredError';
+    }
+}
+/**
+ * Half of nginx's default 8 KB `large_client_header_buffers`. Measured live:
+ * 7317 bytes still returned 200, 16317 returned an nginx 400. Our encrypted
+ * metadata runs ~600–900 bytes, so this is a wide margin against proxies with
+ * smaller defaults rather than a tight fit.
+ */
+export const X_MESSAGE_MAX_BYTES = 4096;
+/**
+ * Decide whether a failed publish is worth retrying.
+ *
+ * Unknown 429s are treated as retryable — the burst throttle is the common case
+ * and it clears on its own. Everything else in the 4xx range is a request the
+ * server will reject identically forever.
+ */
+export function classifyNtfyError(status, body) {
+    let code;
+    let detail = body.trim().slice(0, 500);
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed.code === 'number')
+            code = parsed.code;
+        if (typeof parsed.error === 'string')
+            detail = parsed.error;
+    }
+    catch {
+        // nginx answers an oversized header with HTML. Keep the raw text.
+    }
+    if (code !== undefined) {
+        const fatal = FATAL_NTFY_CODES.get(code);
+        if (fatal) {
+            return { retryable: false, code, message: `${fatal} (ntfy ${code}: ${detail})` };
+        }
+        if (RETRYABLE_NTFY_CODES.has(code)) {
+            return { retryable: true, code, message: `ntfy ${code}: ${detail}` };
+        }
+    }
+    if (status === 429) {
+        return {
+            retryable: true,
+            code,
+            message: `ntfy returned 429 with no recognizable code — treating as a burst throttle. ` +
+                `If this persists it may be the daily quota, which resets at UTC midnight. Body: ${detail}`,
+        };
+    }
+    if (status >= 500) {
+        return { retryable: true, code, message: `ntfy server error ${status}: ${detail}` };
+    }
+    return { retryable: false, code, message: `ntfy rejected the request (${status}): ${detail}` };
+}
+const DEFAULT_RETRY = {
+    maxAttempts: 5,
+    totalBudgetMs: 60_000,
+    initialDelayMs: 500,
+    maxDelayMs: 8_000,
+};
+const DEFAULT_SUBSCRIPTION = {
+    initialBackoffMs: 1_000,
+    maxBackoffMs: 30_000,
+    healthyConnectionMs: 5_000,
+};
+/**
+ * Records what this process is still waiting for, at `~/.hitl/pending/<pid>.json`.
+ *
+ * `waitForAnswer` streams forward-only, so a server that dies mid-wait loses the
+ * answer permanently even though ntfy holds it for 12 h. Persisting the
+ * outstanding IDs lets a restarted process recognize a retried review as the
+ * same one and pull the already-submitted response out of the cache instead of
+ * asking the human again (D-8).
+ */
+export class PendingStore {
+    pid;
+    dir;
+    file;
+    entries = [];
+    constructor(pid = process.pid) {
+        this.pid = pid;
+        this.dir = path.join(process.env.HITL_HOME ?? path.join(homedir(), '.hitl'), 'pending');
+        this.file = path.join(this.dir, `${pid}.json`);
+    }
+    record(entry) {
+        this.entries = this.entries.filter((e) => e.id !== entry.id);
+        this.entries.push(entry);
+        this.flush();
+    }
+    clear(id) {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.id !== id);
+        if (this.entries.length !== before)
+            this.flush();
+    }
+    /**
+     * Find a still-unanswered review of the same plan at the same content hash,
+     * left behind by this or an earlier process. Reusing its reviewId means a
+     * review window that is still open on the human's device resolves this call.
+     *
+     * Entries this process is *currently* waiting on are excluded. Those are not
+     * abandoned work to resume, they are a concurrent call — handing back its
+     * reviewId would point two live waits at one response.
+     */
+    findResumableReview(planId, snapshotHash) {
+        const stillWaiting = new Set(this.entries.map((e) => e.id));
+        for (const entry of this.readAll()) {
+            if (stillWaiting.has(entry.id))
+                continue;
+            if (entry.kind === 'plan_review' && entry.planId === planId && entry.snapshotHash === snapshotHash) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    /** Every entry on disk, this process's and any predecessor's. */
+    readAll() {
+        if (!existsSync(this.dir))
+            return [];
+        const all = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                const parsed = JSON.parse(readFileSync(path.join(this.dir, name), 'utf8'));
+                if (Array.isArray(parsed))
+                    all.push(...parsed);
+            }
+            catch {
+                // A truncated file from a killed process is not worth failing a call over.
+            }
+        }
+        return all;
+    }
+    flush() {
+        try {
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            if (this.entries.length === 0) {
+                if (existsSync(this.file))
+                    unlinkSync(this.file);
+                return;
+            }
+            writeFileSync(this.file, JSON.stringify(this.entries, null, 2) + '\n', {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+        }
+        catch (err) {
+            // Losing durability degrades D-8 to "no resume"; it must not fail the call.
+            console.error(`Could not persist pending waits for pid ${this.pid}: ${err}`);
+        }
+    }
+}
+/** Cap on remembered messageIds. Only guards against a reconnect replaying events. */
+const SEEN_IDS_LIMIT = 512;
+/** A bounded FIFO set of messageIds, so a long-lived process cannot grow one without limit. */
+class RecentIds {
+    limit;
+    set = new Set();
+    order = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    has(id) {
+        return this.set.has(id);
+    }
+    add(id) {
+        if (this.set.has(id))
+            return;
+        this.set.add(id);
+        this.order.push(id);
+        if (this.order.length > this.limit) {
+            const evicted = this.order.shift();
+            if (evicted)
+                this.set.delete(evicted);
+        }
+    }
+}
 /**
  * Transport layer for communicating with ntfy.sh.
  *
- * - Publishes messages (HTTP POST)
- * - Subscribes for answer messages (SSE stream)
+ * One SSE subscription is shared by every outstanding wait and ref-counted, so
+ * a ReviewPlan and an AskUserQuestion running in the same agent turn resolve
+ * over a single connection (C-9) instead of clobbering each other's
+ * AbortController. The subscription reconnects on clean end as well as on
+ * error, resuming from the last event timestamp (C-8).
  */
 export class NtfyTransport {
     config;
-    abortController = null;
-    constructor(config) {
+    /**
+     * Registrations are keyed by a private counter, never by the caller's key.
+     *
+     * Two calls can legitimately arrive on the same key — two ReviewPlan calls
+     * that resolve to the same reviewId, most obviously. Keying the map by the
+     * caller's string let the second `set` silently displace the first, leaving
+     * a promise nobody could ever settle, and let either one's cleanup delete
+     * the other's live registration.
+     */
+    waiters = new Map();
+    watchers = new Map();
+    nextRegistrationId = 1;
+    subscriptionAbort = null;
+    subscriptionRefs = 0;
+    /** Unix seconds. Where a reconnect resumes from. */
+    lastEventTs = 0;
+    /** Delivered to a waiter. Gates both re-delivery and the replay backstop. */
+    consumedIds = new RecentIds(SEEN_IDS_LIMIT);
+    /** Shown to a watcher. Kept apart so observing never suppresses replay (H3). */
+    observedIds = new RecentIds(SEEN_IDS_LIMIT);
+    retry;
+    subscriptionPolicy;
+    pending;
+    constructor(config, options = {}) {
         this.config = config;
+        this.retry = { ...DEFAULT_RETRY, ...options.retry };
+        this.subscriptionPolicy = { ...DEFAULT_SUBSCRIPTION, ...options.subscription };
+        this.pending = new PendingStore();
     }
     /** Full URL for the ntfy topic. */
     get topicUrl() {
@@ -18,8 +317,11 @@ export class NtfyTransport {
         return `${base}/${this.config.topicId}`;
     }
     /**
-     * Publish any HITL message to the ntfy topic.
-     * If an encryption key is configured, the message payload is encrypted.
+     * Publish one of the four shipping message types.
+     *
+     * Their wire format is frozen: plain JSON, optionally encrypted, chunked when
+     * oversized. The type signature is what keeps a plan message off this path —
+     * a chunked plan_review would break the one-message-per-review guarantee.
      */
     async publish(msg) {
         let body;
@@ -37,16 +339,149 @@ export class NtfyTransport {
             await this.publishRaw(JSON.stringify(chunk));
         }
     }
+    /**
+     * Publish a plan-review message. Never chunks.
+     *
+     * When `attachmentCipher` is given, the outer message rides along in the
+     * `X-Message` header of the attachment PUT, so a plan of any size is still
+     * exactly one ntfy message (C-1).
+     */
+    async publishPlan(msg, attachmentCipher) {
+        const body = this.config.encryptionKey
+            ? encrypt(JSON.stringify(msg), this.config.encryptionKey)
+            : JSON.stringify(msg);
+        assertNoChunk(body);
+        if (attachmentCipher === undefined) {
+            await this.publishRaw(body);
+            return;
+        }
+        await this.uploadAttachment(attachmentCipher, body);
+    }
+    /**
+     * Publish a `sender_identity` companion message. Never chunks.
+     *
+     * Sibling of `publishPlan` — same encrypt -> assertNoChunk ->
+     * publishRaw/uploadAttachment shape, but for the small decoration message
+     * that follows a question or notification rather than a `PlanMessage`.
+     */
+    async publishSenderIdentity(msg, attachmentCipher) {
+        const body = this.config.encryptionKey
+            ? encrypt(JSON.stringify(msg), this.config.encryptionKey)
+            : JSON.stringify(msg);
+        assertNoChunk(body);
+        if (attachmentCipher === undefined) {
+            await this.publishRaw(body);
+            return;
+        }
+        await this.uploadAttachment(attachmentCipher, body);
+    }
+    /**
+     * PUT the payload as an ntfy attachment with the outer message in `X-Message`.
+     *
+     * The filename is random hex: ntfy echoes it verbatim as plaintext metadata
+     * on the event, outside our encryption, so a real path there would leak the
+     * absolute location of the plan (F-9).
+     */
+    async uploadAttachment(cipher, outerJson) {
+        const headerBytes = Buffer.byteLength(outerJson, 'utf8');
+        if (headerBytes > X_MESSAGE_MAX_BYTES) {
+            throw new XMessageTooLargeError(headerBytes);
+        }
+        // JSON.stringify emits no literal newlines, but a stray CR/LF in a header
+        // is a request-splitting bug rather than a size error — check it explicitly.
+        if (/[\r\n]/.test(outerJson)) {
+            throw new NtfyPublishError('Plan metadata contains a line break and cannot be sent as a header', 0);
+        }
+        await this.fetchWithRetry(this.topicUrl, {
+            method: 'PUT',
+            headers: {
+                Filename: `${randomBytes(12).toString('hex')}.bin`,
+                'X-Message': outerJson,
+            },
+            body: cipher,
+        }, 'upload plan attachment');
+    }
+    /**
+     * Fetch an attachment's bytes.
+     *
+     * A 404 is its own error: ntfy expires attachments after 3 h while keeping
+     * messages for 12 h, so a replayed review routinely points at a dead URL and
+     * the caller must be able to say "expired" rather than "failed" (C-4/C-12).
+     */
+    async downloadAttachment(ref, signal) {
+        const response = await fetch(ref.url, { signal });
+        if (response.status === 404 || response.status === 410) {
+            throw new AttachmentExpiredError(ref.url);
+        }
+        if (!response.ok) {
+            throw new NtfyPublishError(`Failed to download attachment ${ref.url}: ${response.status} ${response.statusText}`, response.status);
+        }
+        return await response.text();
+    }
     /** POST a single raw body string to the ntfy topic. */
     async publishRaw(body) {
-        const response = await fetch(this.topicUrl, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body,
-        });
-        if (!response.ok) {
-            throw new Error(`Failed to publish message: ${response.status} ${response.statusText}`);
+        await this.fetchWithRetry(this.topicUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body }, 'publish message');
+    }
+    /**
+     * Send a request, retrying only the failures a delay can clear.
+     *
+     * Capped at 5 attempts and a 60 s total budget: past that the cause is
+     * structural, and spinning against a daily quota that resets at UTC midnight
+     * would block the agent for hours (C-13). `Retry-After` is honoured when
+     * present — it was absent on every probed ntfy response, so it is read
+     * opportunistically and never required.
+     */
+    async fetchWithRetry(url, init, describe) {
+        const startedAt = Date.now();
+        let delayMs = this.retry.initialDelayMs;
+        let lastMessage = '';
+        for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt++) {
+            let response;
+            try {
+                response = await fetch(url, init);
+            }
+            catch (err) {
+                // A transport-level failure (DNS, refused, reset) is worth a retry.
+                lastMessage = `${err.message}`;
+                if (attempt === this.retry.maxAttempts || Date.now() - startedAt >= this.retry.totalBudgetMs) {
+                    throw new NtfyPublishError(`Failed to ${describe}: ${lastMessage}`, 0);
+                }
+                await sleep(nextDelay(delayMs, this.retry.maxDelayMs));
+                delayMs = Math.min(delayMs * 2, this.retry.maxDelayMs);
+                continue;
+            }
+            if (response.ok)
+                return response;
+            const body = await safeText(response);
+            const verdict = classifyNtfyError(response.status, body);
+            lastMessage = verdict.message;
+            console.error(`ntfy ${describe} attempt ${attempt} failed: ${verdict.message}`);
+            if (!verdict.retryable) {
+                throw new NtfyPublishError(`Failed to ${describe}: ${verdict.message}`, response.status, verdict.code);
+            }
+            // NOT idempotent on its own. A retryable 429 is safe — ntfy rejected the
+            // message, so nothing was stored — but a 5xx is ambiguous: a proxy can
+            // return 502/504 after ntfy has already accepted and stored the message,
+            // and this then publishes it a second time. The same is true of the
+            // transport-level retry above for a reset that arrives after the request
+            // was fully sent.
+            //
+            // What makes that safe is on the client, not here: `SeenIds` in
+            // `client/src-tauri/src/ntfy.rs` de-dupes on our own `messageId` across
+            // both the cache replay and the live stream, and a retry re-sends
+            // byte-identical bytes. Remove that de-dupe and this retry starts
+            // double-delivering dialogs — there is nothing at this site that would
+            // stop it. The residual cost today is a doubled attachment upload
+            // against the daily bandwidth quota; the orphan expires in 3 h.
+            const elapsed = Date.now() - startedAt;
+            if (attempt === this.retry.maxAttempts || elapsed >= this.retry.totalBudgetMs)
+                break;
+            const retryAfterMs = parseRetryAfter(response.headers?.get?.('retry-after'));
+            const wait = Math.min(retryAfterMs ?? nextDelay(delayMs, this.retry.maxDelayMs), Math.max(0, this.retry.totalBudgetMs - elapsed));
+            await sleep(wait);
+            delayMs = Math.min(delayMs * 2, this.retry.maxDelayMs);
         }
+        throw new NtfyPublishError(`Failed to ${describe} after ${this.retry.maxAttempts} attempts: ${lastMessage}`, 429);
     }
     /** @deprecated Use publish() instead */
     async publishQuestion(msg) {
@@ -57,50 +492,255 @@ export class NtfyTransport {
         return this.publish(msg);
     }
     /**
-     * Subscribe and wait for an answer to a specific question.
-     * Opens an SSE connection and filters for answer messages matching questionId.
+     * Wait for the first message satisfying `match`.
+     *
+     * `key` identifies the waiter so overlapping calls cannot clobber one another
+     * (C-9). The cache is replayed once at registration, after the live stream is
+     * already attached, so a response published while this process was down or
+     * reconnecting still resolves the call (D-8).
      *
-     * @param questionId - The messageId of the question to wait for
-     * @param timeout - Timeout in ms (0 = no timeout)
-     * @returns The answer message
+     * `signal` releases the SSE connection and the waiter within one tick of
+     * cancellation, which is what stops a stopped tool call leaking a connection
+     * for the life of the process (D-9).
      */
-    async waitForAnswer(questionId, timeout) {
+    waitFor(key, match, signal) {
         return new Promise((resolve, reject) => {
-            this.abortController = new AbortController();
-            const { signal } = this.abortController;
-            let timer;
-            if (timeout && timeout > 0) {
-                timer = setTimeout(() => {
-                    this.abortController?.abort();
-                    reject(new Error('Dialog timeout'));
-                }, timeout);
+            if (signal?.aborted) {
+                reject(new AbortedWaitError(key, signal.reason));
+                return;
             }
-            const cleanup = () => {
-                if (timer)
-                    clearTimeout(timer);
+            const registrationId = this.nextRegistrationId++;
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                // By registration, never by key: another call may be waiting on the
+                // same key, and deleting theirs would hang them forever.
+                this.waiters.delete(registrationId);
+                signal?.removeEventListener('abort', onAbort);
+                this.releaseSubscription();
+                fn();
             };
-            // Use ntfy's JSON stream endpoint — since=<now_unix> to only get future messages
-            const sinceTs = Math.floor(Date.now() / 1000);
-            const sseUrl = `${this.topicUrl}/json?since=${sinceTs}`;
-            this.startSSEListener(sseUrl, signal, (msg) => {
-                if (msg.type === 'answer' && msg.questionId === questionId) {
-                    cleanup();
-                    resolve(msg);
-                }
-            }).catch((err) => {
-                cleanup();
-                if (!signal.aborted) {
-                    reject(err);
-                }
+            const onAbort = () => finish(() => reject(new AbortedWaitError(key, signal?.reason)));
+            signal?.addEventListener('abort', onAbort);
+            this.waiters.set(registrationId, {
+                key,
+                match,
+                resolve: (received) => finish(() => resolve(received)),
+                reject: (err) => finish(() => reject(err)),
             });
-            signal.addEventListener('abort', () => {
-                cleanup();
+            this.acquireSubscription();
+            // Replay after the stream is attached, so nothing can slip through the
+            // gap between the poll returning and the stream connecting.
+            void this.replayCache(match)
+                .then((received) => {
+                if (received)
+                    this.deliver(received);
+            })
+                .catch((err) => {
+                console.error(`Cache replay for ${key} failed: ${err}`);
             });
         });
     }
+    /**
+     * Observe matching messages without consuming them, until the returned
+     * function is called.
+     *
+     * Unlike a waiter, a watcher fires repeatedly and only sees what no waiter
+     * took — which is exactly the shape of "a second device submitted after the
+     * first one already won" (D-5). It holds the subscription open while
+     * registered.
+     */
+    watch(key, match, handle) {
+        const registrationId = this.nextRegistrationId++;
+        this.watchers.set(registrationId, { key, match, handle });
+        this.acquireSubscription();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.watchers.delete(registrationId);
+            this.releaseSubscription();
+        };
+    }
+    /**
+     * Subscribe and wait for an answer to a specific question.
+     *
+     * A thin wrapper over waitFor so the shipping AskUserQuestion path behaves
+     * exactly as before, minus the timeout (D-1).
+     */
+    async waitForAnswer(questionId, signal) {
+        const received = await this.waitFor(`answer:${questionId}`, (msg) => msg.type === 'answer' && msg.questionId === questionId, signal);
+        return received.msg;
+    }
+    /**
+     * Poll ntfy's message cache for an already-published match.
+     *
+     * `since=all` reaches back the full 12 h retention, which is the window in
+     * which a response can have been submitted while this process was gone.
+     */
+    async replayCache(match, since = 'all') {
+        const url = `${this.topicUrl}/json?poll=1&since=${since}`;
+        const response = await fetch(url, { headers: { Accept: 'application/x-ndjson' } });
+        if (!response.ok) {
+            throw new NtfyPublishError(`ntfy cache poll failed: ${response.status} ${response.statusText}`, response.status);
+        }
+        for (const line of (await response.text()).split('\n')) {
+            const received = this.parseEventLine(line);
+            if (received && match(received.msg))
+                return received;
+        }
+        return undefined;
+    }
+    /** Join the shared subscription, starting it if this is the first waiter. */
+    acquireSubscription() {
+        this.subscriptionRefs++;
+        if (this.subscriptionAbort)
+            return;
+        if (this.lastEventTs === 0)
+            this.lastEventTs = Math.floor(Date.now() / 1000);
+        const controller = new AbortController();
+        this.subscriptionAbort = controller;
+        void this.runSubscription(controller.signal);
+    }
+    /** Leave the shared subscription, closing it when the last waiter goes. */
+    releaseSubscription() {
+        this.subscriptionRefs = Math.max(0, this.subscriptionRefs - 1);
+        if (this.subscriptionRefs === 0 && this.subscriptionAbort) {
+            this.subscriptionAbort.abort();
+            this.subscriptionAbort = null;
+        }
+    }
+    /**
+     * Keep one stream attached until every waiter is gone.
+     *
+     * A clean stream end is treated exactly like an error: ntfy closes idle
+     * connections routinely, and the previous code resolved the read loop on
+     * close so the wait simply never completed (C-8).
+     */
+    async runSubscription(signal) {
+        let backoff = this.subscriptionPolicy.initialBackoffMs;
+        while (!signal.aborted) {
+            const connectedAt = Date.now();
+            try {
+                await this.startSSEListener(`${this.topicUrl}/json?since=${this.lastEventTs}`, signal, (msg, attachment) => this.deliver({ msg, attachment }));
+            }
+            catch (err) {
+                if (signal.aborted)
+                    return;
+                // A subscription ntfy will never accept is not something to retry at
+                // 30 s forever. Tell everyone waiting why, so the agent surfaces the
+                // cause instead of blocking until the host gives up (H2).
+                if (err instanceof NtfySubscribeError && !err.retryable) {
+                    console.error(`ntfy subscription rejected, giving up: ${err.message}`);
+                    this.failAllWaiters(err);
+                    return;
+                }
+                console.error(`ntfy subscription error, reconnecting: ${err.message}`);
+            }
+            if (signal.aborted)
+                return;
+            if (Date.now() - connectedAt >= this.subscriptionPolicy.healthyConnectionMs) {
+                backoff = this.subscriptionPolicy.initialBackoffMs;
+            }
+            await sleep(backoff, signal);
+            backoff = Math.min(backoff * 2, this.subscriptionPolicy.maxBackoffMs);
+        }
+    }
+    /**
+     * Hand a message to the first waiter that wants it, ignoring replays.
+     *
+     * A message is marked consumed only when a waiter actually takes it. A
+     * watcher merely observing one must not suppress the `replayCache` backstop:
+     * on the D-8 resume path the response arrives while the watcher is attached
+     * but before the waiter registers, and marking it seen there would both tell
+     * the human their submission was lost and hide it from replay, hanging the
+     * agent that was about to wait for it (H3).
+     */
+    deliver(received) {
+        const id = received.msg.messageId;
+        if (id && this.consumedIds.has(id))
+            return;
+        for (const [registrationId, waiter] of this.waiters) {
+            if (waiter.match(received.msg)) {
+                if (id)
+                    this.consumedIds.add(id);
+                this.waiters.delete(registrationId);
+                waiter.resolve(received);
+                return;
+            }
+        }
+        // Only what no waiter claimed reaches the watchers, and only once each —
+        // a reconnect replay must not publish a second "lost" acknowledgement.
+        if (id) {
+            if (this.observedIds.has(id))
+                return;
+            this.observedIds.add(id);
+        }
+        for (const watcher of [...this.watchers.values()]) {
+            if (watcher.match(received.msg))
+                watcher.handle(received);
+        }
+    }
+    /**
+     * Turn one line of ntfy's ndjson stream into a HITL message.
+     *
+     * Also advances `lastEventTs`, including for keepalives — that is what lets a
+     * reconnect resume from where the stream stopped rather than from process
+     * start.
+     */
+    parseEventLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return undefined;
+        let ntfyEvent;
+        try {
+            ntfyEvent = JSON.parse(trimmed);
+        }
+        catch {
+            return undefined; // Not valid JSON, ignore
+        }
+        if (typeof ntfyEvent.time === 'number' && ntfyEvent.time > this.lastEventTs) {
+            this.lastEventTs = ntfyEvent.time;
+        }
+        if (typeof ntfyEvent.message !== 'string')
+            return undefined;
+        try {
+            const parsed = JSON.parse(ntfyEvent.message);
+            let hitlMsg;
+            if (isEncryptedEnvelope(parsed)) {
+                if (!this.config.encryptionKey) {
+                    console.error('Received encrypted message but no encryptionKey configured — skipping');
+                    return undefined;
+                }
+                try {
+                    hitlMsg = JSON.parse(decrypt(ntfyEvent.message, this.config.encryptionKey));
+                }
+                catch (decryptErr) {
+                    console.error('Failed to decrypt message:', decryptErr);
+                    return undefined;
+                }
+            }
+            else {
+                hitlMsg = parsed;
+            }
+            if (!hitlMsg?.type)
+                return undefined;
+            return { msg: hitlMsg, attachment: parseAttachment(ntfyEvent) };
+        }
+        catch {
+            return undefined; // Not a valid HITL message, ignore
+        }
+    }
     /**
      * Open a streaming connection to ntfy and invoke the callback for each parsed HITL message.
      * Uses fetch streaming (works in Node 18+).
+     *
+     * `attachment` is the ntfy event's own attachment metadata, which only exists
+     * on the event envelope — never inside our message, since the URL is assigned
+     * by the PUT. Plan-review bodies over the inline threshold live there.
      */
     async startSSEListener(url, signal, onMessage) {
         const response = await fetch(url, {
@@ -108,7 +748,12 @@ export class NtfyTransport {
             signal,
         });
         if (!response.ok) {
-            throw new Error(`ntfy subscription failed: ${response.status} ${response.statusText}`);
+            // The same classifier the publish path uses. This is the connection the
+            // human's answer actually travels on, so throwing away a diagnosable
+            // status here is what turns a misconfiguration into a silent hang (H2).
+            const body = await response.text().catch(() => '');
+            const verdict = classifyNtfyError(response.status, body);
+            throw new NtfySubscribeError(`ntfy subscription failed: ${verdict.message}`, response.status, verdict.retryable, verdict.code);
         }
         const reader = response.body?.getReader();
         if (!reader)
@@ -124,45 +769,9 @@ export class NtfyTransport {
                 const lines = buffer.split('\n');
                 buffer = lines.pop() ?? '';
                 for (const line of lines) {
-                    const trimmed = line.trim();
-                    if (!trimmed)
-                        continue;
-                    try {
-                        const ntfyEvent = JSON.parse(trimmed);
-                        // ntfy wraps messages — the actual payload is in the 'message' field
-                        if (ntfyEvent.message) {
-                            try {
-                                const parsed = JSON.parse(ntfyEvent.message);
-                                let hitlMsg;
-                                if (isEncryptedEnvelope(parsed)) {
-                                    if (!this.config.encryptionKey) {
-                                        console.error('Received encrypted message but no encryptionKey configured — skipping');
-                                        continue;
-                                    }
-                                    try {
-                                        const decrypted = decrypt(ntfyEvent.message, this.config.encryptionKey);
-                                        hitlMsg = JSON.parse(decrypted);
-                                    }
-                                    catch (decryptErr) {
-                                        console.error('Failed to decrypt message:', decryptErr);
-                                        continue;
-                                    }
-                                }
-                                else {
-                                    hitlMsg = parsed;
-                                }
-                                if (hitlMsg.type) {
-                                    onMessage(hitlMsg);
-                                }
-                            }
-                            catch {
-                                // Not a valid HITL message, ignore
-                            }
-                        }
-                    }
-                    catch {
-                        // Not valid JSON, ignore
-                    }
+                    const received = this.parseEventLine(line);
+                    if (received)
+                        onMessage(received.msg, received.attachment);
                 }
             }
         }
@@ -173,11 +782,79 @@ export class NtfyTransport {
         }
     }
     /**
-     * Close any active subscriptions.
+     * Close any active subscriptions and fail every outstanding wait.
      */
     close() {
-        this.abortController?.abort();
-        this.abortController = null;
+        this.subscriptionAbort?.abort();
+        this.subscriptionAbort = null;
+        this.subscriptionRefs = 0;
+        this.watchers.clear();
+        this.failAllWaiters(new Error('Transport closed'));
+    }
+    /**
+     * Settle every outstanding wait with the same failure.
+     *
+     * Each waiter's own `finish` removes it from the registry, so the snapshot is
+     * taken first — rejecting while iterating would mutate the map underneath.
+     */
+    failAllWaiters(err) {
+        const waiters = [...this.waiters.values()];
+        this.waiters.clear();
+        for (const waiter of waiters) {
+            waiter.reject(err);
+        }
+    }
+}
+/**
+ * Raised when a wait is cancelled by its caller's AbortSignal.
+ *
+ * `reason` carries the external signal's own `AbortSignal.reason` (also set as
+ * the standard `Error.cause`) so a caller further up — an MCP tool handler
+ * deciding what to tell the agent — can distinguish a host-issued Stop from a
+ * host-side timeout instead of seeing only "it was cancelled".
+ */
+export class AbortedWaitError extends Error {
+    key;
+    reason;
+    constructor(key, reason) {
+        super(`Wait for ${key} was cancelled`, reason !== undefined ? { cause: reason } : undefined);
+        this.key = key;
+        this.name = 'AbortedWaitError';
+        this.reason = reason;
+    }
+}
+/** Full jitter, so concurrent servers behind one NAT do not retry in lockstep. */
+function nextDelay(baseMs, maxMs) {
+    return Math.floor(Math.random() * Math.min(baseMs, maxMs));
+}
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        }
+        signal?.addEventListener('abort', done);
+    });
+}
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
     }
 }
 //# sourceMappingURL=ntfy-transport.js.map