@achieveai/hitl-mcp-server 2.9.1 → 2.11.0

package/dist/mcp-server.d.ts

@@ -1,3 +1,56 @@
 #!/usr/bin/env node
-export {};
+import type { HitlConfig } from './types.js';
+export declare class HumanInTheLoopServer {
+    private server;
+    private transport;
+    private config;
+    /** reviewIds still waiting on a human, so a graceful exit can release them (D-3). */
+    private outstandingReviews;
+    /** `config` is injectable so a test can construct a server without a real ~/.hitl. */
+    constructor(config?: HitlConfig);
+    private setupHandlers;
+    /**
+     * ReviewPlan: snapshot a markdown plan, publish it for line-anchored review,
+     * and block until a human submits a verdict.
+     */
+    private handleReviewPlan;
+    /**
+     * Drop a subscription hold after the late-response window.
+     *
+     * The timer is unref'd so it can never be the reason the process stays alive.
+     */
+    private releaseLater;
+    /**
+     * Download, decode and validate a submitted review, then acknowledge it.
+     *
+     * The ack is what lets the client distinguish "the server read this" from "I
+     * clicked submit": the response attachment expires after 3 h while the
+     * message itself survives 12 h, so a submit can be accepted at click time and
+     * still never arrive (C-12).
+     */
+    private consumeReviewResponse;
+    private downloadResponseBody;
+    /** Tell the client whether its submission actually landed. */
+    private publishAck;
+    /**
+     * Fail before publishing when no client can be found or launched.
+     *
+     * Without a timeout to bound it, publishing to a topic nobody is subscribed
+     * to is a permanent silent hang — the agent blocks and the human never sees a
+     * window to explain why (A-10).
+     */
+    private requireClient;
+    /**
+     * Start emitting progress notifications, returning the stop function.
+     *
+     * Whether these actually keep the call alive is the calling host's decision:
+     * the MCP SDK's DEFAULT_REQUEST_TIMEOUT_MSEC is 60 s and
+     * `resetTimeoutOnProgress` defaults to false, so a host that does not opt in
+     * will time the call out regardless of what we send (D-2).
+     */
+    private startHeartbeat;
+    run(): Promise<void>;
+    /** Publish cancel_review for every review still waiting on a human. */
+    private cancelOutstandingReviews;
+}
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":""}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AAcA,OAAO,KAAK,EAaV,UAAU,EAEX,MAAM,YAAY,CAAC;AAsDpB,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,MAAM,CAAa;IAC3B,qFAAqF;IACrF,OAAO,CAAC,kBAAkB,CAAqB;IAE/C,sFAAsF;gBAC1E,MAAM,GAAE,UAAyB;IAY7C,OAAO,CAAC,aAAa;IA4brB;;;OAGG;YACW,gBAAgB;IA0J9B;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;;;OAOG;YACW,qBAAqB;YAiErB,oBAAoB;IAUlC,8DAA8D;YAChD,UAAU;IAuBxB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAUrB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAyBhB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B1B,uEAAuE;YACzD,wBAAwB;CAkBvC"}

package/dist/mcp-server.js

@@ -4,25 +4,60 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { v4 as uuidv4 } from 'uuid';
 import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
 import path from 'path';
-import { NtfyTransport } from './ntfy-transport.js';
+import { PROTOCOL_VERSION } from './types.js';
+import { NtfyTransport, AttachmentExpiredError, AbortedWaitError } from './ntfy-transport.js';
 import { loadConfig } from './config.js';
 import { detectRepoContext } from './git-context.js';
 import { performSetup, ensureClientRunning } from './setup.js';
+import { SERVER_VERSION } from './version.js';
+import { readPlanFile, PlanFileError } from './plan-file.js';
+import { resolvePlanIdentity, prepareRevision } from './snapshot-store.js';
+import { resolveBaseline, buildPlanDiff } from './plan-diff.js';
+import { encodePayload, decodePayload, PayloadDecodeError } from './payload.js';
+import { parseVerdict, normalizeResponseBody, ReviewResponseError } from './plan-review.js';
 const TOOL_NAME = 'AskUserQuestion';
 const NOTIFY_TOOL_NAME = 'Notify';
 const SETUP_TOOL_NAME = 'setup';
+const REVIEW_TOOL_NAME = 'ReviewPlan';
 const SERVER_NAME = 'hitl-mcp-server';
-const SERVER_VERSION = '2.9.1';
+/** Interval between progress notifications that keep a blocked MCP call alive. */
+const HEARTBEAT_INTERVAL_MS = 15_000;
+/**
+ * How long to keep listening for a second device's submission after a review
+ * has already been answered, so the loser is told rather than left hanging.
+ */
+const LATE_RESPONSE_WINDOW_MS = 45_000;
 /** Directory where the compiled server JS lives (used for relative binary paths). */
 const SERVER_DIR = path.dirname(fileURLToPath(import.meta.url));
-class HumanInTheLoopServer {
+/** Best-effort message for an unknown thrown value, for ack reasons and logs. */
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The honest message for a genuine abort of `waitFor`/`waitForAnswer`: a real,
+ * recoverable event, not the same thing as ntfy being unreachable.
+ *
+ * A Stop and a host-side timeout are the two things that actually cancel the
+ * wait — this says so instead of leaving the agent staring at "was cancelled".
+ * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0` is offered as something to try, not
+ * as a stated cause: auto-background only ever detaches an already-running
+ * call from the foreground, it does not itself abort the request.
+ */
+const ABORT_REMEDIATION_MESSAGE = 'Wait cancelled before response; may be Stop or host timeout; ' +
+    'set CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 in global settings and restart.';
+export class HumanInTheLoopServer {
     server;
     transport;
-    constructor() {
-        const config = loadConfig();
+    config;
+    /** reviewIds still waiting on a human, so a graceful exit can release them (D-3). */
+    outstandingReviews = new Set();
+    /** `config` is injectable so a test can construct a server without a real ~/.hitl. */
+    constructor(config = loadConfig()) {
+        this.config = config;
         this.server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
-        this.transport = new NtfyTransport(config);
+        this.transport = new NtfyTransport(this.config);
         this.setupHandlers();
     }
     setupHandlers() {
@@ -127,7 +162,7 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                                     properties: {
                                         question: {
                                             type: 'string',
-                                            description: 'The sub-question text (supports markdown)',
+                                            description: 'The sub-question text (supports markdown). If omitted, falls back to the header text.',
                                         },
                                         header: {
                                             type: 'string',
@@ -154,7 +189,7 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                                         allowMultiple: { type: 'boolean', default: false },
                                         allowOther: { type: 'boolean', default: true },
                                     },
-                                    required: ['question', 'options'],
+                                    required: ['options'],
                                 },
                                 minItems: 1,
                                 maxItems: 4,
@@ -169,12 +204,6 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                                 description: 'Whether to show an "Additional Context" text field for supplementary information',
                                 default: true,
                             },
-                            timeout: {
-                                type: 'number',
-                                description: 'Timeout in milliseconds (default: 3600000 = 1 hour)',
-                                minimum: 1000,
-                                maximum: 86400000,
-                            },
                         },
                         required: ['context'],
                     },
@@ -216,6 +245,43 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                         required: ['title', 'body'],
                     },
                 },
+                {
+                    name: REVIEW_TOOL_NAME,
+                    description: `Get line-anchored human review of an implementation plan you have written to a markdown file.
+
+The plan opens as a two-pane review window on every device the user has subscribed — phone, laptop, desktop — so they can review it wherever they are. They select line ranges, attach comments to them, and return a verdict. This call blocks until they submit.
+
+Use this instead of pasting a plan into AskUserQuestion whenever you want feedback on specific lines rather than a yes/no. Typical moments: after drafting an implementation plan, a migration sequence, an architecture proposal, or a refactor outline.
+
+IMPORTANT — do not modify the file while this call is blocked. The returned snapshotHash identifies the exact content the human reviewed; if you rewrite the file mid-review, their approval applies to text that no longer exists.
+
+Revisions: call it again with the same file after making the requested changes. The user sees a diff against what they reviewed last time rather than the whole plan again, and the revision number increments.
+
+Returns JSON: { success, timestamp, respondedFrom, verdict, overallFeedback, inlineComments[], revision, isNewPlan, snapshotHash }.
+- verdict is one of: approved | changes_requested | rejected | skipped | cancelled
+- inlineComments are { path, startLine, endLine, side, comment }, stably sorted, with line numbers in the source-line space of the file you passed
+- changes_requested and rejected always carry either overallFeedback or at least one inline comment
+
+Blocking past 60 seconds requires the calling MCP host to opt into resetTimeoutOnProgress; this server emits progress heartbeats but cannot enforce the host's timeout.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            filePath: {
+                                type: 'string',
+                                description: 'Absolute or cwd-relative path to the markdown plan file (.md or .markdown, up to 1 MB).',
+                            },
+                            context: {
+                                type: 'string',
+                                description: 'Brief description of what project and work you are doing. This helps the human understand the situation across devices.',
+                            },
+                            summary: {
+                                type: 'string',
+                                description: 'Optional short prose framing shown above the document — what changed since last time, or what you most want feedback on.',
+                            },
+                        },
+                        required: ['filePath', 'context'],
+                    },
+                },
             ],
         }));
         this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
@@ -238,7 +304,7 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                     throw new McpError(ErrorCode.InvalidParams, 'Missing required parameters: title and body');
                 }
                 try {
-                    ensureClientRunning(SERVER_DIR);
+                    this.requireClient();
                     const notification = {
                         type: 'notification',
                         messageId: uuidv4(),
@@ -256,6 +322,9 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                     throw new McpError(ErrorCode.InternalError, `Failed to send notification: ${error instanceof Error ? error.message : 'Unknown error'}`);
                 }
             }
+            if (request.params.name === REVIEW_TOOL_NAME) {
+                return await this.handleReviewPlan(request.params.arguments, extra);
+            }
             if (request.params.name !== TOOL_NAME) {
                 throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${request.params.name}`);
             }
@@ -269,18 +338,25 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                 throw new McpError(ErrorCode.InvalidParams, 'Provide either question+options for a single question, or a questions array for batch mode');
             }
             try {
-                // Auto-launch client if not running
-                ensureClientRunning(SERVER_DIR);
+                // Auto-launch client if not running. Must precede publish: with no
+                // timeout, publishing to a topic nobody reads blocks forever (A-10).
+                this.requireClient();
                 const repo = detectRepoContext();
                 const mapOption = (opt) => ({
-                    label: opt.label || opt.value,
-                    value: opt.value,
+                    label: opt.label || opt.value || '',
+                    // Backfill value from label when the LLM omits it (agents habitually
+                    // call this tool like the built-in AskUserQuestion, which has no
+                    // `value` field). Symmetric with the label fallback above. Without
+                    // this, JSON.stringify drops the undefined `value` key and older
+                    // clients fail to deserialize the whole message, silently dropping
+                    // the popup.
+                    value: opt.value ?? opt.label ?? '',
                     description: opt.description,
                     preview: opt.preview,
                 });
                 const batchQuestions = hasBatchQuestions
                     ? args.questions.map((sq) => ({
-                        question: sq.question,
+                        question: sq.question || sq.header || 'Please choose an option:',
                         header: sq.header,
                         options: sq.options.map(mapOption),
                         allowMultiple: sq.allowMultiple ?? false,
@@ -300,44 +376,27 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
                         : args.options.map(mapOption),
                     allowMultiple: hasBatchQuestions ? false : args.allowMultiple !== false,
                     allowOther: hasBatchQuestions ? true : args.allowOther !== false,
-                    timeout: args.timeout || 3600000,
                     questions: batchQuestions,
                 };
                 console.error(`Publishing question ${questionMsg.messageId} to ntfy...`);
                 await this.transport.publish(questionMsg);
                 console.error('Question published. Waiting for answer...');
-                // Send periodic progress notifications to prevent MCP client timeout.
-                // Each progress notification resets the client's countdown timer.
-                const HEARTBEAT_INTERVAL_MS = 15_000;
-                const progressToken = extra?._meta?.progressToken;
-                let heartbeatTimer;
-                let progressCount = 0;
-                if (progressToken !== undefined) {
-                    heartbeatTimer = setInterval(async () => {
-                        progressCount++;
-                        try {
-                            await extra.sendNotification({
-                                method: 'notifications/progress',
-                                params: {
-                                    progressToken,
-                                    progress: progressCount,
-                                    total: 0,
-                                    message: 'Waiting for human response...',
-                                },
-                            });
-                        }
-                        catch {
-                            // Client may have disconnected; ignore
-                        }
-                    }, HEARTBEAT_INTERVAL_MS);
-                }
+                this.transport.pending.record({
+                    kind: 'question',
+                    id: questionMsg.messageId,
+                    createdAt: Date.now(),
+                });
                 let answer;
+                const stopHeartbeat = this.startHeartbeat(extra);
                 try {
-                    answer = await this.transport.waitForAnswer(questionMsg.messageId, questionMsg.timeout);
+                    answer = await this.transport.waitForAnswer(questionMsg.messageId, extra?.signal);
                 }
                 finally {
-                    if (heartbeatTimer)
-                        clearInterval(heartbeatTimer);
+                    // One finally for both: a host cancellation must release the SSE
+                    // connection and the timer together, or every stop/retry cycle leaks
+                    // one of each for the life of the process (D-9).
+                    stopHeartbeat();
+                    this.transport.pending.clear(questionMsg.messageId);
                 }
                 console.error(`Answer received from ${answer.respondedFrom}`);
                 // Strip (RECOMMENDED) markers from values
@@ -394,40 +453,332 @@ IMPORTANT: When in doubt, ASK. Getting human input ensures accuracy and saves ti
             }
             catch (error) {
                 console.error('Dialog error:', error);
-                if (error instanceof Error && error.message === 'Dialog timeout') {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: JSON.stringify({
-                                    success: false,
-                                    error: 'timeout',
-                                    message: 'The user did not respond within the timeout period',
-                                }, null, 2),
-                            },
-                        ],
-                    };
+                if (error instanceof AbortedWaitError) {
+                    throw new McpError(ErrorCode.InternalError, ABORT_REMEDIATION_MESSAGE);
                 }
                 throw new McpError(ErrorCode.InternalError, `Failed to get human response: ${error instanceof Error ? error.message : 'Unknown error'}`);
             }
         });
     }
+    /**
+     * ReviewPlan: snapshot a markdown plan, publish it for line-anchored review,
+     * and block until a human submits a verdict.
+     */
+    async handleReviewPlan(args, extra) {
+        if (typeof args?.filePath !== 'string' || args.filePath.trim() === '') {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: filePath');
+        }
+        if (typeof args?.context !== 'string' || args.context.trim() === '') {
+            throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: context');
+        }
+        // Validate and read before anything else: a rejected path must never reach
+        // the snapshot store, ntfy, or the human's screen.
+        let plan;
+        try {
+            plan = readPlanFile(args.filePath);
+        }
+        catch (err) {
+            if (err instanceof PlanFileError) {
+                throw new McpError(ErrorCode.InvalidParams, err.message);
+            }
+            throw err;
+        }
+        this.requireClient();
+        const identity = resolvePlanIdentity(plan.resolvedPath);
+        let recorded;
+        try {
+            recorded = prepareRevision(identity, plan.content);
+        }
+        catch (err) {
+            // The store retries what is transient; anything reaching here is a real
+            // filesystem problem, and a raw EPERM stack is not something an agent
+            // can act on.
+            throw new McpError(ErrorCode.InternalError, `Could not record a snapshot of ${identity.displayPath}: ${describeError(err)}. ` +
+                `The plan review needs to write under ${path.dirname(identity.dir)}.`);
+        }
+        const snapshotHash = `sha256:${recorded.digest}`;
+        const diff = buildPlanDiff(identity.displayPath, plan.content, resolveBaseline(identity, recorded));
+        // Reuse the reviewId of an identical review this or a previous process was
+        // still waiting on. A window may still be open for it on the human's
+        // device, and its response then resolves this call instead of asking
+        // again (D-8).
+        const resumable = this.transport.pending.findResumableReview(identity.planId, snapshotHash);
+        const reviewId = resumable?.id ?? uuidv4();
+        const body = { content: plan.content, diff };
+        const encoded = encodePayload(body, this.config.encryptionKey);
+        const reviewMsg = {
+            type: 'plan_review',
+            messageId: reviewId,
+            timestamp: Date.now(),
+            protocolVersion: PROTOCOL_VERSION,
+            repo: detectRepoContext(path.dirname(plan.resolvedPath)),
+            context: args.context,
+            summary: typeof args.summary === 'string' ? args.summary : '',
+            displayPath: identity.displayPath,
+            planId: identity.planId,
+            revision: recorded.revision,
+            isNewPlan: recorded.isNewPlan,
+            snapshotHash,
+            body: encoded.ref,
+        };
+        this.transport.pending.record({
+            kind: 'plan_review',
+            id: reviewId,
+            planId: identity.planId,
+            snapshotHash,
+            createdAt: Date.now(),
+        });
+        this.outstandingReviews.add(reviewId);
+        console.error(`Publishing plan_review ${reviewId} (revision ${recorded.revision}, ` +
+            `${encoded.ref.kind} payload, ${encoded.ref.contentLength} bytes) to ntfy...`);
+        const stopHeartbeat = this.startHeartbeat(extra);
+        // Watch for a second device submitting after the first one already won.
+        // Registered before the wait so there is no window in which a late
+        // response goes unnoticed; `watch` only sees what no waiter consumed, so
+        // the winning response never reaches it (D-5).
+        const stopWatchingLateResponses = this.transport.watch(`late_response:${reviewId}`, (msg) => msg.type === 'plan_review_response' && msg.reviewId === reviewId, (received) => {
+            const late = received.msg;
+            console.error(`Review ${reviewId} already resolved; telling ${late.respondedFrom} it was lost.`);
+            void this.publishAck(reviewId, late.messageId, 'lost', 'This review had already been submitted from another device.');
+        });
+        try {
+            await this.transport.publishPlan(reviewMsg, encoded.ref.kind === 'attachment' ? encoded.cipher : undefined);
+            // The revision is out the door, so it may now become the baseline the
+            // next review diffs against (M6). A failure here only leaves the next
+            // diff rebased on the older revision — worth saying out loud, not worth
+            // abandoning a review the human is already looking at.
+            try {
+                recorded.commit();
+            }
+            catch (err) {
+                console.error(`Published review ${reviewId} but could not update the snapshot pointer for ` +
+                    `${identity.displayPath}: ${describeError(err)}. The next review will diff against ` +
+                    `revision ${recorded.previous?.revision ?? 0}.`);
+            }
+            const { msg: response, attachment } = await this.transport.waitFor(`plan_review_response:${reviewId}`, (msg) => msg.type === 'plan_review_response' && msg.reviewId === reviewId, extra?.signal);
+            const result = await this.consumeReviewResponse(reviewMsg, response, attachment);
+            // Stay attached briefly so a submit that lost the race still gets told,
+            // rather than the losing client sitting on a 30 s ack timeout.
+            this.releaseLater(stopWatchingLateResponses);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            stopWatchingLateResponses();
+            if (error instanceof McpError)
+                throw error;
+            console.error('ReviewPlan error:', error);
+            if (error instanceof AbortedWaitError) {
+                throw new McpError(ErrorCode.InternalError, ABORT_REMEDIATION_MESSAGE);
+            }
+            throw new McpError(ErrorCode.InternalError, `Failed to get plan review: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+        finally {
+            // Same finally for the timer and the wait registration: a host
+            // cancellation must release both, not leak one per stop/retry cycle (D-9).
+            stopHeartbeat();
+            this.outstandingReviews.delete(reviewId);
+            this.transport.pending.clear(reviewId);
+        }
+    }
+    /**
+     * Drop a subscription hold after the late-response window.
+     *
+     * The timer is unref'd so it can never be the reason the process stays alive.
+     */
+    releaseLater(release) {
+        setTimeout(release, LATE_RESPONSE_WINDOW_MS).unref?.();
+    }
+    /**
+     * Download, decode and validate a submitted review, then acknowledge it.
+     *
+     * The ack is what lets the client distinguish "the server read this" from "I
+     * clicked submit": the response attachment expires after 3 h while the
+     * message itself survives 12 h, so a submit can be accepted at click time and
+     * still never arrive (C-12).
+     */
+    async consumeReviewResponse(reviewMsg, response, attachment) {
+        let verdict;
+        let body;
+        try {
+            // Inside the try so a client that sends nonsense is acknowledged as
+            // lost rather than leaving the human's window claiming success.
+            verdict = parseVerdict(response.verdict);
+            // The human must have reviewed the content we published. A mismatch is a
+            // stale window or a broken client, and accepting it would approve this
+            // revision on the strength of a review of a different one (A-8/M5).
+            if (response.snapshotHash && response.snapshotHash !== reviewMsg.snapshotHash) {
+                throw new ReviewResponseError(`Response is for snapshot ${response.snapshotHash}, but this review published ` +
+                    `${reviewMsg.snapshotHash}.`);
+            }
+            const cipher = response.body?.kind === 'attachment'
+                ? await this.downloadResponseBody(attachment)
+                : response.body?.data ?? '';
+            const decoded = decodePayload(cipher, this.config.encryptionKey, response.body?.contentHash ?? '');
+            body = normalizeResponseBody(verdict, decoded, reviewMsg.displayPath);
+        }
+        catch (err) {
+            await this.publishAck(reviewMsg.messageId, response.messageId, 'lost', describeError(err));
+            if (err instanceof AttachmentExpiredError) {
+                throw new McpError(ErrorCode.InternalError, `The review was submitted but its payload had already expired on ntfy (attachments live 3 h). ` +
+                    `Ask for the review again.`);
+            }
+            if (err instanceof PayloadDecodeError || err instanceof ReviewResponseError) {
+                throw new McpError(ErrorCode.InternalError, `Unusable review response: ${err.message}`);
+            }
+            throw err;
+        }
+        await this.publishAck(reviewMsg.messageId, response.messageId, 'received');
+        return {
+            success: true,
+            timestamp: response.timestamp,
+            respondedFrom: response.respondedFrom,
+            verdict,
+            overallFeedback: body.overallFeedback,
+            inlineComments: body.inlineComments,
+            revision: reviewMsg.revision,
+            isNewPlan: reviewMsg.isNewPlan,
+            // Checked against what we published above, so this is the content the
+            // human actually reviewed rather than whatever the client claimed (A-8).
+            snapshotHash: reviewMsg.snapshotHash,
+        };
+    }
+    async downloadResponseBody(attachment) {
+        if (!attachment) {
+            throw new McpError(ErrorCode.InternalError, 'Review response claims an attachment payload but the message carried no attachment URL.');
+        }
+        return await this.transport.downloadAttachment(attachment);
+    }
+    /** Tell the client whether its submission actually landed. */
+    async publishAck(reviewId, responseId, status, reason) {
+        const ack = {
+            type: 'plan_review_ack',
+            messageId: uuidv4(),
+            timestamp: Date.now(),
+            protocolVersion: PROTOCOL_VERSION,
+            reviewId,
+            responseId,
+            status,
+            reason,
+        };
+        try {
+            await this.transport.publishPlan(ack);
+        }
+        catch (err) {
+            console.error(`Could not acknowledge review ${reviewId}: ${err}`);
+        }
+    }
+    /**
+     * Fail before publishing when no client can be found or launched.
+     *
+     * Without a timeout to bound it, publishing to a topic nobody is subscribed
+     * to is a permanent silent hang — the agent blocks and the human never sees a
+     * window to explain why (A-10).
+     */
+    requireClient() {
+        const result = ensureClientRunning(SERVER_DIR);
+        if (!result.ok) {
+            throw new McpError(ErrorCode.InternalError, `No HITL client available, so nobody would see this. ${result.reason ?? ''}`.trim());
+        }
+    }
+    /**
+     * Start emitting progress notifications, returning the stop function.
+     *
+     * Whether these actually keep the call alive is the calling host's decision:
+     * the MCP SDK's DEFAULT_REQUEST_TIMEOUT_MSEC is 60 s and
+     * `resetTimeoutOnProgress` defaults to false, so a host that does not opt in
+     * will time the call out regardless of what we send (D-2).
+     */
+    startHeartbeat(extra) {
+        const progressToken = extra?._meta?.progressToken;
+        if (progressToken === undefined)
+            return () => { };
+        let progressCount = 0;
+        const timer = setInterval(async () => {
+            progressCount++;
+            try {
+                await extra.sendNotification({
+                    method: 'notifications/progress',
+                    params: {
+                        progressToken,
+                        progress: progressCount,
+                        total: 0,
+                        message: 'Waiting for human response...',
+                    },
+                });
+            }
+            catch {
+                // Client may have disconnected; ignore
+            }
+        }, HEARTBEAT_INTERVAL_MS);
+        return () => clearInterval(timer);
+    }
     async run() {
         const stdioTransport = new StdioServerTransport();
         await this.server.connect(stdioTransport);
         console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio (ntfy-backed)`);
-        const shutdown = () => {
+        let shuttingDown = false;
+        const shutdown = async () => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
             console.error('Shutting down...');
+            // Tell open review windows their agent is gone before dropping the
+            // connection, so they show "agent exited" and keep the typed comments
+            // rather than waiting on a process that no longer exists (D-3).
+            // A hard kill (SIGKILL/OOM) cannot be caught here by design.
+            await this.cancelOutstandingReviews('agent_exited');
             this.transport.close();
             process.exit(0);
         };
-        process.on('SIGINT', shutdown);
-        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', () => void shutdown());
+        process.on('SIGTERM', () => void shutdown());
     }
+    /** Publish cancel_review for every review still waiting on a human. */
+    async cancelOutstandingReviews(reason) {
+        for (const reviewId of this.outstandingReviews) {
+            const cancel = {
+                type: 'cancel_review',
+                messageId: uuidv4(),
+                timestamp: Date.now(),
+                protocolVersion: PROTOCOL_VERSION,
+                reviewId,
+                reason,
+            };
+            try {
+                await this.transport.publishPlan(cancel);
+            }
+            catch (err) {
+                console.error(`Could not cancel review ${reviewId}: ${err}`);
+            }
+        }
+        this.outstandingReviews.clear();
+    }
+}
+/**
+ * True when this file is what node was asked to run, rather than something
+ * another module imported.
+ *
+ * Compared through realpath because npm installs the `bin` entry as a symlink:
+ * `process.argv[1]` is then the link in `node_modules/.bin`, not this file. If
+ * the comparison cannot be made at all we boot — failing to start a server
+ * someone asked for is far worse than starting one nobody wanted.
+ */
+function isDirectlyExecuted() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return true;
+    }
+}
+if (isDirectlyExecuted()) {
+    const server = new HumanInTheLoopServer();
+    server.run().catch((error) => {
+        console.error('Server error:', error);
+        process.exit(1);
+    });
 }
-const server = new HumanInTheLoopServer();
-server.run().catch((error) => {
-    console.error('Server error:', error);
-    process.exit(1);
-});
 //# sourceMappingURL=mcp-server.js.map