@midscene/shared 1.12.2-beta-20260828074555.0 → 1.12.2

package/dist/es/cli/interrupt.mjs

@@ -1,4 +1,31 @@
 const activeInterruptWaiters = new WeakMap();
+const noop = ()=>{};
+const sigintExitCode = 130;
+function guardTerminalCtrlC(input, onInterrupt) {
+    if (!input?.isTTY || !input.setRawMode) return noop;
+    const wasRaw = true === input.isRaw;
+    const wasFlowing = true === input.readableFlowing;
+    const onData = (chunk)=>{
+        const includesCtrlC = 'string' == typeof chunk && chunk.includes('\u0003') || chunk instanceof Uint8Array && chunk.includes(3);
+        if (includesCtrlC) onInterrupt();
+    };
+    const dispose = ()=>{
+        input.removeListener('data', onData);
+        try {
+            if (!wasFlowing) input.pause?.();
+        } finally{
+            if (!wasRaw) input.setRawMode?.(false);
+        }
+    };
+    input.setRawMode(true);
+    try {
+        input.on('data', onData);
+    } catch (error) {
+        dispose();
+        throw error;
+    }
+    return dispose;
+}
 function registerCliInterruptWaiter(source) {
     const key = source;
     activeInterruptWaiters.set(key, (activeInterruptWaiters.get(key) ?? 0) + 1);
@@ -14,28 +41,76 @@ function registerCliInterruptWaiter(source) {
 function hasActiveCliInterruptWaiter(source = process) {
     return (activeInterruptWaiters.get(source) ?? 0) > 0;
 }
-function waitForCliInterrupt(watchdogMs, source = process) {
+function createCliInterruptWaiter(watchdogMs, options = {}) {
+    const source = options.source ?? process;
+    const input = options.input ?? (source === process ? process.stdin : void 0);
+    const forceExit = options.forceExit ?? (source === process ? (exitCode)=>{
+        process.exit(exitCode);
+    } : void 0);
     const unregisterWaiter = registerCliInterruptWaiter(source);
-    return new Promise((resolve, reject)=>{
-        let timer;
-        let finished = false;
-        const finish = (reason)=>{
-            if (finished) return;
-            finished = true;
-            source.removeListener('SIGINT', onSigint);
-            if (timer) clearTimeout(timer);
-            unregisterWaiter();
-            resolve(reason);
-        };
-        const onSigint = ()=>finish('sigint');
+    let timer;
+    let finished = false;
+    let disposed = false;
+    let disposeInput = noop;
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((resolve, reject)=>{
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    const finish = (reason)=>{
+        if (finished) return;
+        finished = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = void 0;
+        }
+        resolveResult(reason);
+    };
+    const onSigint = ()=>finish('sigint');
+    const onSigterm = ()=>finish('sigterm');
+    const onSighup = ()=>finish('sighup');
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        source.removeListener('SIGINT', onSigint);
+        source.removeListener('SIGTERM', onSigterm);
+        source.removeListener('SIGHUP', onSighup);
         try {
-            source.once('SIGINT', onSigint);
-        } catch (error) {
+            disposeInput();
+        } finally{
+            if (timer) {
+                clearTimeout(timer);
+                timer = void 0;
+            }
             unregisterWaiter();
-            reject(error);
-            return;
         }
+    }
+    const onTerminalCtrlC = ()=>{
+        if (!finished) return void finish('sigint');
+        dispose();
+        forceExit?.(sigintExitCode);
+    };
+    try {
+        source.on('SIGINT', onSigint);
+        source.on('SIGTERM', onSigterm);
+        source.on('SIGHUP', onSighup);
+        disposeInput = guardTerminalCtrlC(input, onTerminalCtrlC);
         if (watchdogMs > 0) timer = setTimeout(()=>finish('watchdog'), watchdogMs);
+    } catch (error) {
+        dispose();
+        rejectResult(error);
+    }
+    return {
+        result,
+        dispose
+    };
+}
+function waitForCliInterrupt(watchdogMs, source = process, input = source === process ? process.stdin : void 0) {
+    const waiter = createCliInterruptWaiter(watchdogMs, {
+        source,
+        input
     });
+    return waiter.result.finally(waiter.dispose);
 }
-export { hasActiveCliInterruptWaiter, waitForCliInterrupt };
+export { createCliInterruptWaiter, hasActiveCliInterruptWaiter, waitForCliInterrupt };

package/dist/es/cli/record-command.mjs

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { getErrorMessage } from "../agent-tools/error-formatter.mjs";
 import { resolveObservationArtifactAdapter } from "../agent-tools/observation-artifact.mjs";
 import { writeUIObservationRecord } from "../agent-tools/observation-record.mjs";
-import { waitForCliInterrupt } from "./interrupt.mjs";
+import { createCliInterruptWaiter } from "./interrupt.mjs";
 import { attachCliVerboseDumpListener, emitCliVerboseEvent } from "./verbose.mjs";
 const recordCliMetadata = {
     positionals: [
@@ -55,7 +55,7 @@ function createErrorResult(message) {
 function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata) {
     return {
         name: 'record',
-        description: 'Record the page/screen in the foreground until Ctrl+C, then save the ordered frame window for a later assert command.',
+        description: 'Record the page/screen in the foreground until Ctrl+C or a termination signal, then save the ordered frame window for a later assert command.',
         schema: {
             action: z.literal('start').describe('Start a foreground recording. Press Ctrl+C to finish.'),
             output: z.string().optional().describe('Path for the JSON observation manifest. Frames are stored in an adjacent <name>.frames directory. Defaults to a generated path under midscene_run/output.'),
@@ -80,6 +80,7 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                     toolName: 'record'
                 });
                 let observer;
+                let interruptWaiter;
                 try {
                     const watchdogMs = args.watchdogMs ?? 300000;
                     observer = await agent.startObserving({
@@ -87,12 +88,13 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                         maxFrames: args.maxFrames,
                         watchdogMs
                     });
+                    interruptWaiter = createCliInterruptWaiter(watchdogMs);
                     emitCliVerboseEvent({
                         event: 'recording_ready',
                         tool: 'record',
                         watchdogMs
                     });
-                    const stopReason = await waitForCliInterrupt(watchdogMs);
+                    const stopReason = await interruptWaiter.result;
                     emitCliVerboseEvent({
                         event: 'recording_stopping',
                         tool: 'record',
@@ -110,8 +112,12 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                         ]
                     };
                 } finally{
-                    await observer?.dispose?.();
-                    unsubscribeVerbose();
+                    try {
+                        await observer?.dispose?.();
+                    } finally{
+                        interruptWaiter?.dispose();
+                        unsubscribeVerbose();
+                    }
                 }
             } catch (error) {
                 const errorMessage = getErrorMessage(error);

package/dist/es/cli/verbose.mjs

@@ -305,7 +305,9 @@ function renderCliVerboseEventText(event, context) {
         case 'recording_ready':
             return '[Midscene] Recording. Press Ctrl+C to stop and save.';
         case 'recording_stopping':
-            return 'watchdog' === event.reason ? '[Midscene] Recording watchdog reached; finalizing and saving.' : '[Midscene] Ctrl+C received; finalizing and saving.';
+            if ('watchdog' === event.reason) return '[Midscene] Recording watchdog reached; finalizing and saving.';
+            if ('sigterm' === event.reason) return '[Midscene] SIGTERM received; finalizing and saving.';
+            return 'sighup' === event.reason ? '[Midscene] SIGHUP received; finalizing and saving.' : '[Midscene] Ctrl+C received; finalizing and saving. Press Ctrl+C again to force exit.';
         case 'dump_update':
             {
                 if (isActVerboseEvent(command, tool)) return;

package/dist/es/env/parse-model-config.mjs

@@ -5,7 +5,7 @@ import { assert } from "../utils.mjs";
 import { maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.2-beta-20260828074555.0";
+const getCurrentVersion = ()=>"1.12.2";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,

package/dist/lib/cli/interrupt.js

@@ -24,10 +24,38 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    createCliInterruptWaiter: ()=>createCliInterruptWaiter,
     hasActiveCliInterruptWaiter: ()=>hasActiveCliInterruptWaiter,
     waitForCliInterrupt: ()=>waitForCliInterrupt
 });
 const activeInterruptWaiters = new WeakMap();
+const noop = ()=>{};
+const sigintExitCode = 130;
+function guardTerminalCtrlC(input, onInterrupt) {
+    if (!input?.isTTY || !input.setRawMode) return noop;
+    const wasRaw = true === input.isRaw;
+    const wasFlowing = true === input.readableFlowing;
+    const onData = (chunk)=>{
+        const includesCtrlC = 'string' == typeof chunk && chunk.includes('\u0003') || chunk instanceof Uint8Array && chunk.includes(3);
+        if (includesCtrlC) onInterrupt();
+    };
+    const dispose = ()=>{
+        input.removeListener('data', onData);
+        try {
+            if (!wasFlowing) input.pause?.();
+        } finally{
+            if (!wasRaw) input.setRawMode?.(false);
+        }
+    };
+    input.setRawMode(true);
+    try {
+        input.on('data', onData);
+    } catch (error) {
+        dispose();
+        throw error;
+    }
+    return dispose;
+}
 function registerCliInterruptWaiter(source) {
     const key = source;
     activeInterruptWaiters.set(key, (activeInterruptWaiters.get(key) ?? 0) + 1);
@@ -43,33 +71,83 @@ function registerCliInterruptWaiter(source) {
 function hasActiveCliInterruptWaiter(source = process) {
     return (activeInterruptWaiters.get(source) ?? 0) > 0;
 }
-function waitForCliInterrupt(watchdogMs, source = process) {
+function createCliInterruptWaiter(watchdogMs, options = {}) {
+    const source = options.source ?? process;
+    const input = options.input ?? (source === process ? process.stdin : void 0);
+    const forceExit = options.forceExit ?? (source === process ? (exitCode)=>{
+        process.exit(exitCode);
+    } : void 0);
     const unregisterWaiter = registerCliInterruptWaiter(source);
-    return new Promise((resolve, reject)=>{
-        let timer;
-        let finished = false;
-        const finish = (reason)=>{
-            if (finished) return;
-            finished = true;
-            source.removeListener('SIGINT', onSigint);
-            if (timer) clearTimeout(timer);
-            unregisterWaiter();
-            resolve(reason);
-        };
-        const onSigint = ()=>finish('sigint');
+    let timer;
+    let finished = false;
+    let disposed = false;
+    let disposeInput = noop;
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((resolve, reject)=>{
+        resolveResult = resolve;
+        rejectResult = reject;
+    });
+    const finish = (reason)=>{
+        if (finished) return;
+        finished = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = void 0;
+        }
+        resolveResult(reason);
+    };
+    const onSigint = ()=>finish('sigint');
+    const onSigterm = ()=>finish('sigterm');
+    const onSighup = ()=>finish('sighup');
+    function dispose() {
+        if (disposed) return;
+        disposed = true;
+        source.removeListener('SIGINT', onSigint);
+        source.removeListener('SIGTERM', onSigterm);
+        source.removeListener('SIGHUP', onSighup);
         try {
-            source.once('SIGINT', onSigint);
-        } catch (error) {
+            disposeInput();
+        } finally{
+            if (timer) {
+                clearTimeout(timer);
+                timer = void 0;
+            }
             unregisterWaiter();
-            reject(error);
-            return;
         }
+    }
+    const onTerminalCtrlC = ()=>{
+        if (!finished) return void finish('sigint');
+        dispose();
+        forceExit?.(sigintExitCode);
+    };
+    try {
+        source.on('SIGINT', onSigint);
+        source.on('SIGTERM', onSigterm);
+        source.on('SIGHUP', onSighup);
+        disposeInput = guardTerminalCtrlC(input, onTerminalCtrlC);
         if (watchdogMs > 0) timer = setTimeout(()=>finish('watchdog'), watchdogMs);
+    } catch (error) {
+        dispose();
+        rejectResult(error);
+    }
+    return {
+        result,
+        dispose
+    };
+}
+function waitForCliInterrupt(watchdogMs, source = process, input = source === process ? process.stdin : void 0) {
+    const waiter = createCliInterruptWaiter(watchdogMs, {
+        source,
+        input
     });
+    return waiter.result.finally(waiter.dispose);
 }
+exports.createCliInterruptWaiter = __webpack_exports__.createCliInterruptWaiter;
 exports.hasActiveCliInterruptWaiter = __webpack_exports__.hasActiveCliInterruptWaiter;
 exports.waitForCliInterrupt = __webpack_exports__.waitForCliInterrupt;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createCliInterruptWaiter",
     "hasActiveCliInterruptWaiter",
     "waitForCliInterrupt"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/lib/cli/record-command.js

@@ -83,7 +83,7 @@ function createErrorResult(message) {
 function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata) {
     return {
         name: 'record',
-        description: 'Record the page/screen in the foreground until Ctrl+C, then save the ordered frame window for a later assert command.',
+        description: 'Record the page/screen in the foreground until Ctrl+C or a termination signal, then save the ordered frame window for a later assert command.',
         schema: {
             action: external_zod_namespaceObject.z.literal('start').describe('Start a foreground recording. Press Ctrl+C to finish.'),
             output: external_zod_namespaceObject.z.string().optional().describe('Path for the JSON observation manifest. Frames are stored in an adjacent <name>.frames directory. Defaults to a generated path under midscene_run/output.'),
@@ -108,6 +108,7 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                     toolName: 'record'
                 });
                 let observer;
+                let interruptWaiter;
                 try {
                     const watchdogMs = args.watchdogMs ?? 300000;
                     observer = await agent.startObserving({
@@ -115,12 +116,13 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                         maxFrames: args.maxFrames,
                         watchdogMs
                     });
+                    interruptWaiter = (0, external_interrupt_js_namespaceObject.createCliInterruptWaiter)(watchdogMs);
                     (0, external_verbose_js_namespaceObject.emitCliVerboseEvent)({
                         event: 'recording_ready',
                         tool: 'record',
                         watchdogMs
                     });
-                    const stopReason = await (0, external_interrupt_js_namespaceObject.waitForCliInterrupt)(watchdogMs);
+                    const stopReason = await interruptWaiter.result;
                     (0, external_verbose_js_namespaceObject.emitCliVerboseEvent)({
                         event: 'recording_stopping',
                         tool: 'record',
@@ -138,8 +140,12 @@ function createRecordCliCommand(getAgent, initArgSchema = {}, initArgCliMetadata
                         ]
                     };
                 } finally{
-                    await observer?.dispose?.();
-                    unsubscribeVerbose();
+                    try {
+                        await observer?.dispose?.();
+                    } finally{
+                        interruptWaiter?.dispose();
+                        unsubscribeVerbose();
+                    }
                 }
             } catch (error) {
                 const errorMessage = (0, error_formatter_js_namespaceObject.getErrorMessage)(error);

package/dist/lib/cli/verbose.js

@@ -342,7 +342,9 @@ function renderCliVerboseEventText(event, context) {
         case 'recording_ready':
             return '[Midscene] Recording. Press Ctrl+C to stop and save.';
         case 'recording_stopping':
-            return 'watchdog' === event.reason ? '[Midscene] Recording watchdog reached; finalizing and saving.' : '[Midscene] Ctrl+C received; finalizing and saving.';
+            if ('watchdog' === event.reason) return '[Midscene] Recording watchdog reached; finalizing and saving.';
+            if ('sigterm' === event.reason) return '[Midscene] SIGTERM received; finalizing and saving.';
+            return 'sighup' === event.reason ? '[Midscene] SIGHUP received; finalizing and saving.' : '[Midscene] Ctrl+C received; finalizing and saving. Press Ctrl+C again to force exit.';
         case 'dump_update':
             {
                 if (isActVerboseEvent(command, tool)) return;

package/dist/lib/env/parse-model-config.js

@@ -37,7 +37,7 @@ const external_utils_js_namespaceObject = require("../utils.js");
 const external_helper_js_namespaceObject = require("./helper.js");
 const external_init_debug_js_namespaceObject = require("./init-debug.js");
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.2-beta-20260828074555.0";
+const getCurrentVersion = ()=>"1.12.2";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: external_constants_js_namespaceObject.INSIGHT_MODEL_CONFIG_KEYS,

package/dist/types/cli/interrupt.d.ts

@@ -1,13 +1,49 @@
-export type CliInterruptReason = 'sigint' | 'watchdog';
+export type CliInterruptReason = 'sigint' | 'sigterm' | 'sighup' | 'watchdog';
+type CliInterruptSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
 export interface CliInterruptSource {
-    once(event: 'SIGINT', listener: () => void): unknown;
-    removeListener(event: 'SIGINT', listener: () => void): unknown;
+    on(event: CliInterruptSignal, listener: () => void): unknown;
+    removeListener(event: CliInterruptSignal, listener: () => void): unknown;
+}
+export interface CliInterruptInputSource {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    readonly readableFlowing?: boolean | null;
+    on(event: 'data', listener: (chunk: unknown) => void): unknown;
+    removeListener(event: 'data', listener: (chunk: unknown) => void): unknown;
+    setRawMode?(enabled: boolean): unknown;
+    pause?(): unknown;
+}
+export interface CliInterruptWaiter {
+    /** Resolves on the first stop signal or watchdog timeout. */
+    readonly result: Promise<CliInterruptReason>;
+    /** Release signal handlers after asynchronous finalization has completed. */
+    dispose(): void;
+}
+export interface CliInterruptWaiterOptions {
+    source?: CliInterruptSource;
+    input?: CliInterruptInputSource;
+    /** Called after restoring the terminal when Ctrl+C is pressed again. */
+    forceExit?: (exitCode: number) => void;
 }
 /** Whether a foreground CLI command is currently waiting for this source. */
 export declare function hasActiveCliInterruptWaiter(source?: CliInterruptSource): boolean;
 /**
- * Wait until the foreground CLI receives Ctrl+C. A positive watchdog keeps a
- * forgotten recording from running forever and uses the same graceful save
- * path as an explicit interrupt.
+ * Keep graceful-stop handlers installed until the caller has finished saving.
+ *
+ * Package runners such as pnpm can deliver SIGINT to the foreground child,
+ * immediately follow it with SIGTERM, then cause SIGHUP when the runner exits
+ * and its pseudo-terminal closes. Resolving on the first signal is not enough:
+ * removing any handler at that point lets a subsequent signal kill the child
+ * during asynchronous artifact finalization.
+ *
+ * On a TTY, Ctrl+C is captured as raw input so the package runner itself stays
+ * alive until the child has saved and restored the terminal. Signal handlers
+ * remain as the graceful-stop path for externally delivered termination.
+ */
+export declare function createCliInterruptWaiter(watchdogMs: number, options?: CliInterruptWaiterOptions): CliInterruptWaiter;
+/**
+ * Wait for one stop request and release the handlers immediately afterwards.
+ * Long-running finalizers should use {@link createCliInterruptWaiter} instead.
  */
-export declare function waitForCliInterrupt(watchdogMs: number, source?: CliInterruptSource): Promise<CliInterruptReason>;
+export declare function waitForCliInterrupt(watchdogMs: number, source?: CliInterruptSource, input?: CliInterruptInputSource | undefined): Promise<CliInterruptReason>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.12.2-beta-20260828074555.0",
+  "version": "1.12.2",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/interrupt.ts

@@ -1,11 +1,72 @@
-export type CliInterruptReason = 'sigint' | 'watchdog';
+export type CliInterruptReason = 'sigint' | 'sigterm' | 'sighup' | 'watchdog';
+
+type CliInterruptSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
 
 export interface CliInterruptSource {
-  once(event: 'SIGINT', listener: () => void): unknown;
-  removeListener(event: 'SIGINT', listener: () => void): unknown;
+  on(event: CliInterruptSignal, listener: () => void): unknown;
+  removeListener(event: CliInterruptSignal, listener: () => void): unknown;
+}
+
+export interface CliInterruptInputSource {
+  readonly isTTY?: boolean;
+  readonly isRaw?: boolean;
+  readonly readableFlowing?: boolean | null;
+  on(event: 'data', listener: (chunk: unknown) => void): unknown;
+  removeListener(event: 'data', listener: (chunk: unknown) => void): unknown;
+  setRawMode?(enabled: boolean): unknown;
+  pause?(): unknown;
+}
+
+export interface CliInterruptWaiter {
+  /** Resolves on the first stop signal or watchdog timeout. */
+  readonly result: Promise<CliInterruptReason>;
+  /** Release signal handlers after asynchronous finalization has completed. */
+  dispose(): void;
+}
+
+export interface CliInterruptWaiterOptions {
+  source?: CliInterruptSource;
+  input?: CliInterruptInputSource;
+  /** Called after restoring the terminal when Ctrl+C is pressed again. */
+  forceExit?: (exitCode: number) => void;
 }
 
 const activeInterruptWaiters = new WeakMap<object, number>();
+const noop = () => {};
+const sigintExitCode = 130;
+
+function guardTerminalCtrlC(
+  input: CliInterruptInputSource | undefined,
+  onInterrupt: () => void,
+): () => void {
+  if (!input?.isTTY || !input.setRawMode) return noop;
+
+  const wasRaw = input.isRaw === true;
+  const wasFlowing = input.readableFlowing === true;
+  const onData = (chunk: unknown) => {
+    const includesCtrlC =
+      (typeof chunk === 'string' && chunk.includes('\u0003')) ||
+      (chunk instanceof Uint8Array && chunk.includes(3));
+    if (includesCtrlC) onInterrupt();
+  };
+  const dispose = () => {
+    input.removeListener('data', onData);
+    try {
+      if (!wasFlowing) input.pause?.();
+    } finally {
+      if (!wasRaw) input.setRawMode?.(false);
+    }
+  };
+
+  input.setRawMode(true);
+  try {
+    input.on('data', onData);
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+  return dispose;
+}
 
 function registerCliInterruptWaiter(source: CliInterruptSource): () => void {
   const key = source as object;
@@ -33,39 +94,114 @@ export function hasActiveCliInterruptWaiter(
 }
 
 /**
- * Wait until the foreground CLI receives Ctrl+C. A positive watchdog keeps a
- * forgotten recording from running forever and uses the same graceful save
- * path as an explicit interrupt.
+ * Keep graceful-stop handlers installed until the caller has finished saving.
+ *
+ * Package runners such as pnpm can deliver SIGINT to the foreground child,
+ * immediately follow it with SIGTERM, then cause SIGHUP when the runner exits
+ * and its pseudo-terminal closes. Resolving on the first signal is not enough:
+ * removing any handler at that point lets a subsequent signal kill the child
+ * during asynchronous artifact finalization.
+ *
+ * On a TTY, Ctrl+C is captured as raw input so the package runner itself stays
+ * alive until the child has saved and restored the terminal. Signal handlers
+ * remain as the graceful-stop path for externally delivered termination.
  */
-export function waitForCliInterrupt(
+export function createCliInterruptWaiter(
   watchdogMs: number,
-  source: CliInterruptSource = process,
-): Promise<CliInterruptReason> {
+  options: CliInterruptWaiterOptions = {},
+): CliInterruptWaiter {
+  const source = options.source ?? process;
+  const input =
+    options.input ?? (source === process ? process.stdin : undefined);
+  const forceExit =
+    options.forceExit ??
+    (source === process
+      ? (exitCode: number) => {
+          process.exit(exitCode);
+        }
+      : undefined);
   const unregisterWaiter = registerCliInterruptWaiter(source);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let finished = false;
+  let disposed = false;
+  let disposeInput = noop;
+  let resolveResult!: (reason: CliInterruptReason) => void;
+  let rejectResult!: (error: unknown) => void;
 
-  return new Promise((resolve, reject) => {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let finished = false;
+  const result = new Promise<CliInterruptReason>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
 
-    const finish = (reason: CliInterruptReason) => {
-      if (finished) return;
-      finished = true;
-      source.removeListener('SIGINT', onSigint);
-      if (timer) clearTimeout(timer);
-      unregisterWaiter();
-      resolve(reason);
-    };
-    const onSigint = () => finish('sigint');
+  const finish = (reason: CliInterruptReason) => {
+    if (finished) return;
+    finished = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    resolveResult(reason);
+  };
+  const onSigint = () => finish('sigint');
+  const onSigterm = () => finish('sigterm');
+  const onSighup = () => finish('sighup');
 
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    source.removeListener('SIGINT', onSigint);
+    source.removeListener('SIGTERM', onSigterm);
+    source.removeListener('SIGHUP', onSighup);
     try {
-      source.once('SIGINT', onSigint);
-    } catch (error) {
+      disposeInput();
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
       unregisterWaiter();
-      reject(error);
+    }
+  }
+
+  const onTerminalCtrlC = () => {
+    if (!finished) {
+      finish('sigint');
       return;
     }
+
+    // The first Ctrl+C protects asynchronous artifact finalization. A second
+    // explicit Ctrl+C is the user's escape hatch if device or file I/O hangs.
+    dispose();
+    forceExit?.(sigintExitCode);
+  };
+
+  try {
+    source.on('SIGINT', onSigint);
+    source.on('SIGTERM', onSigterm);
+    source.on('SIGHUP', onSighup);
+    disposeInput = guardTerminalCtrlC(input, onTerminalCtrlC);
     if (watchdogMs > 0) {
       timer = setTimeout(() => finish('watchdog'), watchdogMs);
     }
-  });
+  } catch (error) {
+    dispose();
+    rejectResult(error);
+  }
+
+  return { result, dispose };
+}
+
+/**
+ * Wait for one stop request and release the handlers immediately afterwards.
+ * Long-running finalizers should use {@link createCliInterruptWaiter} instead.
+ */
+export function waitForCliInterrupt(
+  watchdogMs: number,
+  source: CliInterruptSource = process,
+  input: CliInterruptInputSource | undefined = source === process
+    ? process.stdin
+    : undefined,
+): Promise<CliInterruptReason> {
+  const waiter = createCliInterruptWaiter(watchdogMs, { source, input });
+  return waiter.result.finally(waiter.dispose);
 }

package/src/cli/record-command.ts

@@ -9,7 +9,7 @@ import type {
   ToolResult,
   ToolSchema,
 } from '../agent-tools/types';
-import { waitForCliInterrupt } from './interrupt';
+import { type CliInterruptWaiter, createCliInterruptWaiter } from './interrupt';
 import { attachCliVerboseDumpListener, emitCliVerboseEvent } from './verbose';
 
 const recordCliMetadata: ToolCliMetadata = {
@@ -62,7 +62,7 @@ export function createRecordCliCommand(
   return {
     name: 'record',
     description:
-      'Record the page/screen in the foreground until Ctrl+C, then save the ordered frame window for a later assert command.',
+      'Record the page/screen in the foreground until Ctrl+C or a termination signal, then save the ordered frame window for a later assert command.',
     schema: {
       action: z
         .literal('start')
@@ -125,6 +125,7 @@ export function createRecordCliCommand(
         let observer:
           | Awaited<ReturnType<NonNullable<BaseAgent['startObserving']>>>
           | undefined;
+        let interruptWaiter: CliInterruptWaiter | undefined;
         try {
           const watchdogMs = (args.watchdogMs as number | undefined) ?? 300_000;
           observer = await agent.startObserving({
@@ -132,12 +133,13 @@ export function createRecordCliCommand(
             maxFrames: args.maxFrames as number | undefined,
             watchdogMs,
           });
+          interruptWaiter = createCliInterruptWaiter(watchdogMs);
           emitCliVerboseEvent({
             event: 'recording_ready',
             tool: 'record',
             watchdogMs,
           });
-          const stopReason = await waitForCliInterrupt(watchdogMs);
+          const stopReason = await interruptWaiter.result;
           emitCliVerboseEvent({
             event: 'recording_stopping',
             tool: 'record',
@@ -158,8 +160,12 @@ export function createRecordCliCommand(
             ],
           };
         } finally {
-          await observer?.dispose?.();
-          unsubscribeVerbose();
+          try {
+            await observer?.dispose?.();
+          } finally {
+            interruptWaiter?.dispose();
+            unsubscribeVerbose();
+          }
         }
       } catch (error: unknown) {
         const errorMessage = getErrorMessage(error);

package/src/cli/verbose.ts

@@ -587,9 +587,15 @@ function renderCliVerboseEventText(
     case 'recording_ready':
       return '[Midscene] Recording. Press Ctrl+C to stop and save.';
     case 'recording_stopping':
-      return event.reason === 'watchdog'
-        ? '[Midscene] Recording watchdog reached; finalizing and saving.'
-        : '[Midscene] Ctrl+C received; finalizing and saving.';
+      if (event.reason === 'watchdog') {
+        return '[Midscene] Recording watchdog reached; finalizing and saving.';
+      }
+      if (event.reason === 'sigterm') {
+        return '[Midscene] SIGTERM received; finalizing and saving.';
+      }
+      return event.reason === 'sighup'
+        ? '[Midscene] SIGHUP received; finalizing and saving.'
+        : '[Midscene] Ctrl+C received; finalizing and saving. Press Ctrl+C again to force exit.';
     case 'dump_update': {
       if (isActVerboseEvent(command, tool)) {
         return undefined;