@tonyclaw/agent-inspector 3.0.44 → 3.0.46

package/src/proxy/logIndex.ts

@@ -1,15 +1,18 @@
-import { readFile, writeFile, stat, readdir } from "node:fs/promises";
-import { createReadStream, existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { writeFile, readdir, rename, unlink, open } from "node:fs/promises";
+import { constants, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { createInterface } from "node:readline";
 import { Buffer } from "node:buffer";
 import { resolveLogDir, logger } from "./logger";
-import type { ApiFormat, CapturedLog } from "./schemas";
+import {
+  CapturedLogSchema,
+  type ApiFormat,
+  type CaptureIncompleteReason,
+  type CapturedLog,
+} from "./schemas";
 import { textByteLength } from "../lib/unknown";
 import {
-  findSqliteLogIndexEntry,
   getSqliteLogIndexMaxId,
-  listSqliteLogIndexEntries,
   replaceSqliteLogIndexEntries,
   syncSqliteLogIndexEntries,
   upsertSqliteLogIndexEntry,
@@ -19,6 +22,8 @@ import {
   PRIVATE_FILE_MODE,
   securePrivateFileSync,
 } from "./privateDataPath";
+import { recoverCapturedLogStorage } from "./jsonlRecovery";
+import { getSessionArchiveMaxLogId } from "./sessionArchive";
 
 export type LogIndexSummary = {
   id: number;
@@ -50,6 +55,10 @@ export type LogIndexSummary = {
   streamingChunksPath: string | null;
   rawRequestBodyBytes: number | null;
   responseTextBytes: number | null;
+  captureIncomplete: boolean;
+  droppedChunks: number;
+  droppedBytes: number;
+  captureIncompleteReason: CaptureIncompleteReason | null;
   warnings?: string[];
   error: string | null;
 };
@@ -78,6 +87,7 @@ type LogIndex = {
 
 const INDEX_VERSION = 1;
 const INDEX_FILE = "logs.idx";
+const INDEX_READ_CHUNK_BYTES = 64 * 1024;
 
 export { resolveLogDir as getLogDir };
 
@@ -86,6 +96,7 @@ function getIndexPath(): string {
 }
 
 let cachedIndex: LogIndex | null = null;
+let allocatedMaxId = 0;
 let sqliteBackfillScheduledMaxId = 0;
 
 export function createLogIndexEntryMetadata(log: CapturedLog): LogIndexEntryMetadata {
@@ -122,6 +133,10 @@ export function createLogIndexEntryMetadata(log: CapturedLog): LogIndexEntryMeta
       streamingChunksPath: log.streamingChunksPath ?? null,
       rawRequestBodyBytes: log.rawRequestBodyBytes ?? textByteLength(log.rawRequestBody),
       responseTextBytes: log.responseTextBytes ?? textByteLength(log.responseText),
+      captureIncomplete: log.captureIncomplete ?? false,
+      droppedChunks: log.droppedChunks ?? 0,
+      droppedBytes: log.droppedBytes ?? 0,
+      captureIncompleteReason: log.captureIncompleteReason ?? null,
       warnings: log.warnings,
       error: log.error ?? null,
     },
@@ -136,45 +151,11 @@ function createEmptyIndex(): LogIndex {
   };
 }
 
-function isLogIndex(obj: unknown): obj is LogIndex {
-  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return false;
-  const versionDesc = Object.getOwnPropertyDescriptor(obj, "version");
-  const entriesDesc = Object.getOwnPropertyDescriptor(obj, "entries");
-  const maxIdDesc = Object.getOwnPropertyDescriptor(obj, "maxId");
-  return (
-    versionDesc !== undefined &&
-    typeof versionDesc.value === "number" &&
-    entriesDesc !== undefined &&
-    typeof entriesDesc.value === "object" &&
-    entriesDesc.value !== null &&
-    maxIdDesc !== undefined &&
-    typeof maxIdDesc.value === "number"
-  );
-}
-
 export async function loadIndex(): Promise<LogIndex> {
   if (cachedIndex !== null) return cachedIndex;
-
-  const indexPath = getIndexPath();
-  if (!existsSync(indexPath)) {
-    cachedIndex = createEmptyIndex();
-    return cachedIndex;
-  }
-
-  try {
-    const content = await readFile(indexPath, "utf-8");
-    const parsed: unknown = JSON.parse(content);
-    if (isLogIndex(parsed)) {
-      cachedIndex = parsed;
-    } else {
-      cachedIndex = createEmptyIndex();
-    }
-    return cachedIndex;
-  } catch (err) {
-    logger.error("[logIndex] Failed to load index:", String(err));
-    cachedIndex = createEmptyIndex();
-    return cachedIndex;
-  }
+  // logs.idx and inspector.sqlite are projections only. A cold process always rebuilds from
+  // authoritative JSONL rather than allowing a stale, conflicting, or higher derived row to win.
+  return await rebuildIndex();
 }
 
 export async function saveIndex(index: LogIndex): Promise<void> {
@@ -186,15 +167,23 @@ export async function saveIndex(index: LogIndex): Promise<void> {
     return;
   }
 
+  const temporaryPath = `${indexPath}.${String(process.pid)}.${randomUUID()}.tmp`;
   try {
-    await writeFile(indexPath, JSON.stringify(index), {
+    await writeFile(temporaryPath, JSON.stringify(index), {
       encoding: "utf-8",
       mode: PRIVATE_FILE_MODE,
     });
+    if (!securePrivateFileSync(temporaryPath)) {
+      await unlink(temporaryPath).catch(() => undefined);
+      logger.error("[logIndex] Failed to secure temporary index file:", temporaryPath);
+      return;
+    }
+    await rename(temporaryPath, indexPath);
     if (!securePrivateFileSync(indexPath)) {
       logger.error("[logIndex] Failed to secure index file:", indexPath);
     }
   } catch (err) {
+    await unlink(temporaryPath).catch(() => undefined);
     logger.error("[logIndex] Failed to save index:", String(err));
   }
 }
@@ -220,6 +209,25 @@ export async function addToIndex(
   scheduleIndexFlush();
 }
 
+/**
+ * Refresh the searchable summary after a request reaches its terminal state. The initial index
+ * entry is created before the upstream call starts, so leaving it untouched would make compact
+ * reads (and the SQLite sidecar) report the pre-request placeholder after finalization.
+ */
+export async function updateLogIndexEntryMetadata(log: CapturedLog): Promise<void> {
+  const index = await loadIndex();
+  const existing = index.entries[log.id];
+  if (existing === undefined) return;
+
+  const updated: LogIndexEntry = {
+    ...existing,
+    ...createLogIndexEntryMetadata(log),
+  };
+  index.entries[log.id] = updated;
+  await upsertSqliteLogIndexEntry(updated);
+  scheduleIndexFlush();
+}
+
 // Batch writes: collect pending flushes and write once
 let indexFlushScheduled = false;
 let indexFlushTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -250,9 +258,6 @@ export async function flushIndex(): Promise<void> {
 }
 
 export async function findInIndex(id: number): Promise<LogIndexEntry | null> {
-  const sqliteEntry = await findSqliteLogIndexEntry(id);
-  if (sqliteEntry !== null) return sqliteEntry;
-
   const index = await loadIndex();
   return index.entries[id] ?? null;
 }
@@ -260,10 +265,6 @@ export async function findInIndex(id: number): Promise<LogIndexEntry | null> {
 export async function listIndexEntries(): Promise<LogIndexEntry[]> {
   const index = await loadIndex();
   const sqliteMaxId = await getSqliteLogIndexMaxId();
-  if (sqliteMaxId !== null && sqliteMaxId >= index.maxId) {
-    const sqliteEntries = await listSqliteLogIndexEntries();
-    if (sqliteEntries !== null) return sqliteEntries;
-  }
   maybeBackfillSqliteIndex(index, sqliteMaxId);
   return Object.values(index.entries).sort((left, right) => left.id - right.id);
 }
@@ -277,12 +278,7 @@ export async function listFilteredIndexEntries({
 }): Promise<LogIndexEntry[]> {
   const index = await loadIndex();
   const sqliteMaxId = await getSqliteLogIndexMaxId();
-  if (sqliteMaxId !== null && sqliteMaxId >= index.maxId) {
-    const sqliteEntries = await listSqliteLogIndexEntries({ sessionId, model });
-    if (sqliteEntries !== null) return sqliteEntries;
-  }
   maybeBackfillSqliteIndex(index, sqliteMaxId);
-
   return Object.values(index.entries)
     .sort((left, right) => left.id - right.id)
     .filter((entry) => {
@@ -311,6 +307,11 @@ type FileIndexResult = {
   maxId: number;
 };
 
+type ParsedIndexRecord =
+  | { status: "blank" }
+  | { status: "log"; log: CapturedLog }
+  | { status: "invalid"; message: string };
+
 function readStringOrNullField(entry: object, field: string): string | null {
   const desc = Object.getOwnPropertyDescriptor(entry, field);
   if (desc === undefined) return null;
@@ -349,6 +350,22 @@ function readApiFormatField(entry: object): ApiFormat {
   }
 }
 
+function readCaptureIncompleteReasonField(entry: object): CaptureIncompleteReason | null {
+  const value = readStringOrNullField(entry, "captureIncompleteReason");
+  switch (value) {
+    case "capacity-exceeded":
+    case "pipeline-closed":
+    case "write-failed":
+    case "finalize-failed":
+    case "upstream-stream-error":
+    case "shutdown":
+      return value;
+    case null:
+    default:
+      return null;
+  }
+}
+
 function readStringArrayField(entry: object, field: string): string[] | undefined {
   const desc = Object.getOwnPropertyDescriptor(entry, field);
   if (desc === undefined || !Array.isArray(desc.value)) return undefined;
@@ -398,58 +415,138 @@ function readLogIndexSummary(entry: object, id: number): LogIndexSummary {
     streamingChunksPath: readStringOrNullField(entry, "streamingChunksPath"),
     rawRequestBodyBytes: readTextByteLength(entry, "rawRequestBodyBytes", "rawRequestBody"),
     responseTextBytes: readTextByteLength(entry, "responseTextBytes", "responseText"),
+    captureIncomplete: readBooleanField(entry, "captureIncomplete"),
+    droppedChunks: readNumberOrNullField(entry, "droppedChunks") ?? 0,
+    droppedBytes: readNumberOrNullField(entry, "droppedBytes") ?? 0,
+    captureIncompleteReason: readCaptureIncompleteReasonField(entry),
     warnings: readStringArrayField(entry, "warnings"),
     error: readStringOrNullField(entry, "error"),
   };
 }
 
-async function indexFile(filePath: string, file: string): Promise<FileIndexResult> {
-  const entries: Record<number, LogIndexEntry> = {};
-  let maxId = 0;
-  let byteOffset = 0;
+function parseIndexRecord(record: Buffer, file: string, byteOffset: number): ParsedIndexRecord {
+  const content =
+    record.length > 0 && record[record.length - 1] === 0x0d ? record.subarray(0, -1) : record;
+  const line = content.toString("utf-8");
+  if (line.trim() === "") return { status: "blank" };
 
-  const fileStream = createInterface({
-    input: createReadStream(filePath),
-    crlfDelay: Infinity,
-  });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch (error) {
+    return {
+      status: "invalid",
+      message: `Malformed JSONL record in ${file} at byte ${String(byteOffset)}: ${String(error)}`,
+    };
+  }
+  const validated = CapturedLogSchema.safeParse(parsed);
+  return validated.success
+    ? { status: "log", log: validated.data }
+    : {
+        status: "invalid",
+        message: `Invalid captured-log record in ${file} at byte ${String(byteOffset)}`,
+      };
+}
 
-  for await (const line of fileStream) {
-    const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
-    if (line.trim() !== "") {
-      try {
-        const entry: unknown = JSON.parse(line);
-        if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
-          const idDesc = Object.getOwnPropertyDescriptor(entry, "id");
-          if (idDesc !== undefined && typeof idDesc.value === "number") {
-            const entryId = idDesc.value;
-            maxId = Math.max(maxId, entryId);
-            entries[entryId] = {
-              id: entryId,
-              file,
-              byteOffset,
-              byteLength: lineBytes,
-              sessionId: readStringOrNullField(entry, "sessionId"),
-              model: readStringOrNullField(entry, "model"),
-              summary: readLogIndexSummary(entry, entryId),
-            };
-          }
-        }
-      } catch {
-        // Skip malformed lines
-      }
+function addIndexedRecord(
+  result: FileIndexResult,
+  parsed: ParsedIndexRecord,
+  file: string,
+  byteOffset: number,
+  byteLength: number,
+): Error | null {
+  switch (parsed.status) {
+    case "blank":
+      return null;
+    case "invalid":
+      return new Error(parsed.message);
+    case "log": {
+      const entry = parsed.log;
+      result.maxId = Math.max(result.maxId, entry.id);
+      result.entries[entry.id] = {
+        id: entry.id,
+        file,
+        byteOffset,
+        byteLength,
+        sessionId: entry.sessionId,
+        model: entry.model,
+        summary: readLogIndexSummary(entry, entry.id),
+      };
+      return null;
     }
-    byteOffset += lineBytes;
   }
+}
+
+async function indexFile(filePath: string, file: string): Promise<FileIndexResult> {
+  const result: FileIndexResult = { entries: {}, maxId: 0 };
+  let handle: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const fileStats = await handle.stat();
+    if (!fileStats.isFile()) {
+      return await Promise.reject(new Error(`Captured-log ledger is not a regular file: ${file}`));
+    }
+
+    const readBuffer = Buffer.alloc(INDEX_READ_CHUNK_BYTES);
+    let position = 0;
+    let pending = Buffer.alloc(0);
+    let pendingOffset = 0;
+    while (position < fileStats.size) {
+      const length = Math.min(INDEX_READ_CHUNK_BYTES, fileStats.size - position);
+      const read = await handle.read(readBuffer, 0, length, position);
+      if (read.bytesRead === 0) {
+        return await Promise.reject(
+          new Error(`Captured-log ledger changed while rebuilding index: ${file}`),
+        );
+      }
+      const chunk = readBuffer.subarray(0, read.bytesRead);
+      const combined = pending.length === 0 ? Buffer.from(chunk) : Buffer.concat([pending, chunk]);
+      let consumed = 0;
+      let newline = combined.indexOf(0x0a, consumed);
+      while (newline !== -1) {
+        const record = combined.subarray(consumed, newline);
+        const byteOffset = pendingOffset + consumed;
+        const byteLength = record.length + 1;
+        const error = addIndexedRecord(
+          result,
+          parseIndexRecord(record, file, byteOffset),
+          file,
+          byteOffset,
+          byteLength,
+        );
+        if (error !== null) return await Promise.reject(error);
+        consumed = newline + 1;
+        newline = combined.indexOf(0x0a, consumed);
+      }
+      pending = Buffer.from(combined.subarray(consumed));
+      pendingOffset += consumed;
+      position += read.bytesRead;
+    }
 
-  return { entries, maxId };
+    if (pending.length > 0) {
+      return await Promise.reject(
+        new Error(`Captured-log ledger ended without recovery delimiter: ${file}`),
+      );
+    }
+    return result;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
 }
 
 export async function rebuildIndex(): Promise<LogIndex> {
   const logDir = resolveLogDir();
   const newIndex = createEmptyIndex();
+  const recovery = await recoverCapturedLogStorage(logDir);
+  if (recovery.level === "unavailable") {
+    return await Promise.reject(
+      new Error(recovery.diagnostic ?? "Captured-log recovery blocked index rebuild"),
+    );
+  }
 
   if (!existsSync(logDir)) {
     cachedIndex = newIndex;
+    allocatedMaxId = 0;
     await saveIndex(newIndex);
     await replaceSqliteLogIndexEntries([]);
     return newIndex;
@@ -470,6 +567,7 @@ export async function rebuildIndex(): Promise<LogIndex> {
   }
 
   cachedIndex = newIndex;
+  allocatedMaxId = Math.max(allocatedMaxId, newIndex.maxId);
   await saveIndex(newIndex);
   await replaceSqliteLogIndexEntries(Object.values(newIndex.entries));
   return newIndex;
@@ -494,11 +592,9 @@ async function withIdLock<T>(fn: () => Promise<T>): Promise<T> {
 export async function getNextLogId(): Promise<number> {
   return withIdLock(async () => {
     const index = await loadIndex();
-    const sqliteMaxId = await getSqliteLogIndexMaxId();
-    const nextId = Math.max(index.maxId, sqliteMaxId ?? 0) + 1;
-    index.maxId = nextId;
-    // Synchronously update the index in memory (disk write is deferred via batching)
-    cachedIndex = index;
+    const archiveMaxId = await getSessionArchiveMaxLogId();
+    const nextId = Math.max(index.maxId, archiveMaxId, allocatedMaxId) + 1;
+    allocatedMaxId = nextId;
     return nextId;
   });
 }

package/src/proxy/logger.ts

@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer";
-import { appendFileSync } from "node:fs";
+import { closeSync, constants, fsyncSync, openSync, writeSync } from "node:fs";
 import { appendFile, readdir, rename, stat, unlink } from "node:fs/promises";
 import path from "node:path";
 import { getDataDir } from "./dataDir";
@@ -9,6 +9,12 @@ import {
   securePrivateFileSync,
   securePrivateTreeSync,
 } from "./privateDataPath";
+import {
+  canAppendCapturedLogFileOnExit,
+  markCapturedLogFileAppended,
+  recoverCapturedLogFileBeforeAppend,
+  recoverCapturedLogStorage,
+} from "./jsonlRecovery";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_RETENTION_DAYS = 7;
@@ -236,17 +242,25 @@ export async function initLogger(): Promise<void> {
     } else if (!securePrivateTreeSync(dir)) {
       writeStderrFallback("[logger] Failed to secure existing log files:", dir);
     } else {
-      const entries = await readdir(dir);
-      for (const entry of entries) {
-        if (!entry.endsWith(".jsonl")) continue;
-        const fullPath = path.join(dir, entry);
-        try {
-          const s = await stat(fullPath);
-          if (s.mtimeMs < cutoff) {
-            await unlink(fullPath);
+      const recovery = await recoverCapturedLogStorage(dir);
+      if (recovery.level === "unavailable") {
+        writeStderrFallback(
+          "[logger] Captured-log recovery blocked readiness:",
+          recovery.diagnostic ?? "unknown recovery failure",
+        );
+      } else {
+        const entries = await readdir(dir);
+        for (const entry of entries) {
+          if (!entry.endsWith(".jsonl")) continue;
+          const fullPath = path.join(dir, entry);
+          try {
+            const s = await stat(fullPath);
+            if (s.mtimeMs < cutoff) {
+              await unlink(fullPath);
+            }
+          } catch {
+            // Skip files that can't be stat - not critical
           }
-        } catch {
-          // Skip files that can't be stat - not critical
         }
       }
     }
@@ -354,9 +368,29 @@ export const logger = {
 
 // Write buffer for batching async writes
 const MAX_BUFFER_SIZE = 1000;
+const BUFFER_FLUSH_DELAY_MS = 10;
 let writeBuffer: string[] = [];
 let writeQueue: Promise<void> = Promise.resolve();
 let logWriteLock: Promise<void> = Promise.resolve();
+let scheduledBufferFlush: ReturnType<typeof setTimeout> | null = null;
+
+function queueBufferedFlush(): void {
+  writeQueue = writeQueue.then(() => runWithLogWriteLock(flushWriteBufferUnlocked));
+}
+
+function cancelScheduledBufferFlush(): void {
+  if (scheduledBufferFlush === null) return;
+  clearTimeout(scheduledBufferFlush);
+  scheduledBufferFlush = null;
+}
+
+function scheduleBufferedFlush(): void {
+  if (scheduledBufferFlush !== null) return;
+  scheduledBufferFlush = setTimeout(() => {
+    scheduledBufferFlush = null;
+    queueBufferedFlush();
+  }, BUFFER_FLUSH_DELAY_MS);
+}
 
 export async function runWithLogWriteLock<T>(fn: () => Promise<T>): Promise<T> {
   const previousLock = logWriteLock;
@@ -393,10 +427,20 @@ async function flushWriteBufferUnlocked(): Promise<void> {
       writeStderrFallback("[logger] Failed to secure captured-log directory:", filePath);
       return;
     }
+    const recovery = await recoverCapturedLogFileBeforeAppend(resolveLogDir(), filePath);
+    if (recovery.level === "unavailable") {
+      writeBuffer.unshift(toWrite);
+      writeStderrFallback(
+        "[logger] Refused captured-log append until recovery succeeds:",
+        recovery.diagnostic ?? "unknown recovery failure",
+      );
+      return;
+    }
     await appendFile(filePath, toWrite, { encoding: "utf-8", mode: PRIVATE_FILE_MODE });
     if (!securePrivateFileSync(filePath)) {
       writeStderrFallback("[logger] Failed to secure captured-log file:", filePath);
     }
+    await markCapturedLogFileAppended(resolveLogDir(), filePath);
   } catch (err) {
     // On failure, re-queue the data so it is not lost
     writeBuffer.unshift(toWrite);
@@ -408,9 +452,10 @@ export function appendLogEntry(entry: Record<string, unknown>): void {
   const line = JSON.stringify(entry) + "\n";
   writeBuffer.push(line);
   if (writeBuffer.length >= MAX_BUFFER_SIZE) {
-    writeQueue = writeQueue.then(() => runWithLogWriteLock(flushWriteBufferUnlocked));
+    cancelScheduledBufferFlush();
+    queueBufferedFlush();
   } else if (writeBuffer.length === 1) {
-    writeQueue = writeQueue.then(() => runWithLogWriteLock(flushWriteBufferUnlocked));
+    scheduleBufferedFlush();
   }
 }
 
@@ -419,6 +464,7 @@ export function appendLogEntry(entry: Record<string, unknown>): void {
  * to avoid losing unflushed data.
  */
 export async function flushLogBuffer(): Promise<void> {
+  cancelScheduledBufferFlush();
   await writeQueue;
   if (writeBuffer.length > 0) {
     await runWithLogWriteLock(flushWriteBufferUnlocked);
@@ -441,7 +487,24 @@ process.on("exit", () => {
       // Synchronous write required in 'exit' handler (async I/O not allowed)
       const filePath = getLogFilePath();
       if (!ensurePrivateDirectorySync(path.dirname(filePath))) return;
-      appendFileSync(filePath, toWrite, { encoding: "utf-8", mode: PRIVATE_FILE_MODE });
+      if (!canAppendCapturedLogFileOnExit(resolveLogDir(), filePath)) return;
+      const descriptor = openSync(
+        filePath,
+        constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW,
+        PRIVATE_FILE_MODE,
+      );
+      try {
+        const payload = Buffer.from(toWrite, "utf-8");
+        let written = 0;
+        while (written < payload.length) {
+          const writeCount = writeSync(descriptor, payload, written, payload.length - written);
+          if (writeCount === 0) return;
+          written += writeCount;
+        }
+        fsyncSync(descriptor);
+      } finally {
+        closeSync(descriptor);
+      }
       void securePrivateFileSync(filePath);
     } catch {
       // Best-effort: nothing we can do in an exit handler

package/src/proxy/platformCommands.ts

@@ -205,6 +205,47 @@ export function killPid(pid: number, platform: PlatformName = process.platform):
   }
 }
 
+export type ProcessTreeSignal = "SIGTERM" | "SIGKILL";
+
+/**
+ * Signal a child process and every descendant created in its process tree.
+ *
+ * Unix callers must spawn the root with `detached: true`, which makes its PID the process-group
+ * ID. Windows has no equivalent portable Node signal, so taskkill owns descendant traversal.
+ */
+export function signalProcessTree(
+  pid: number,
+  signal: ProcessTreeSignal,
+  platform: PlatformName = process.platform,
+): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    if (platform === "win32") {
+      const args = ["/PID", String(pid), "/T"];
+      if (signal === "SIGKILL") args.push("/F");
+      execFileSync("taskkill.exe", args, {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      return true;
+    }
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    // Killing only the Windows root would orphan descendants and could make the runtime report a
+    // false clean shutdown. Let the caller retry taskkill with /F instead.
+    if (platform === "win32") return false;
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
 export const platformCommandParsersForTests = {
   parseUnixLsofPids,
   parseUnixSsPids,