@venturewild/workspace 0.6.16 → 0.6.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturewild/workspace",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "description": "Claude Code Web — Replit/Lovable-style chat-first browser UI that wraps the AI agent already installed on your machine.",
   "license": "MIT",
   "bin": {

package/server/src/background-tasks.mjs

@@ -0,0 +1,366 @@
+// Background-task registry — the "what's running in the background" surface.
+//
+// WHY this exists: the agent can launch a long job with the Bash tool's
+// `run_in_background:true` (e.g. "run the scored-verdict audit in the background").
+// We verified empirically how `claude` behaves here:
+//   - The launch tool_result is text: `Command running in background with ID:
+//     <shellId>. Output is being written to: <file>. You will be notified…`.
+//   - The task OUTLIVES the `claude -p` turn that spawned it (it's detached) — the
+//     output file keeps growing on disk after the process exits.
+//   - BUT in our one-process-per-turn model there is NO completion event delivered
+//     back into the stream, and a resumed session can't re-poll the old shell. So
+//     "I'll be notified when it finishes" never actually fires for the user.
+//   - Completion IS visible IF the agent polls in the same turn: the poll tool
+//     (newer `TaskOutput` w/ `task_id`, older `BashOutput` w/ `bash_id`) returns
+//     `<status>completed</status>` + `<exit_code>N</exit_code>`.
+//
+// So this registry fuses two signals, both of which the server already sees or can
+// reach: (1) the agent's tool-use/tool-result chunk stream (launch + any polls) and
+// (2) the on-disk output file's size/mtime (process-independent liveness). It is the
+// single source of truth behind the chat's background-task card, the topbar activity
+// tray, and the canvas Tasks block.
+//
+// HONESTY (CLAUDE.md: never fake): we only assert `completed`/`failed` from an
+// authoritative poll result or an exit-code we actually observed. Without that, a
+// task is `running`, optionally flagged `quiet` when the output file has been
+// silent past a threshold — surfaced as "no output for Xm", never a false "done".
+
+import fs from 'node:fs';
+import { resolveHolders as defaultResolveHolders, killTree as defaultKillTree } from './process-holders.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const DEFAULT_POLL_MS = 3000; // how often we stat each live task's output file
+const DEFAULT_QUIET_MS = 90_000; // silence past this → flag `quiet` (maybe stuck / maybe just slow)
+const DEFAULT_MAX_PER_WS = 40; // retained tasks per workspace (terminal ones pruned oldest-first)
+const TAIL_BYTES = 16 * 1024; // how much of the output file the tail endpoint returns
+
+const TERMINAL = new Set(['completed', 'failed', 'killed']);
+
+/** Parse a background-launch tool_result into { shellId, outputFile }. */
+export function parseLaunchResult(text) {
+  if (typeof text !== 'string') return null;
+  const idM = text.match(/background with ID:\s*([A-Za-z0-9_-]+)/i);
+  if (!idM) return null;
+  const fileM = text.match(/written to:\s*(\S+)/i);
+  let outputFile = fileM ? fileM[1] : null;
+  // The path is a contiguous no-space token; the sentence's trailing punctuation
+  // ("…/x.output. You will be notified") clings to it — strip it (output files end
+  // in letters, so this never eats a real filename char).
+  if (outputFile) outputFile = outputFile.replace(/[.,;:]+$/, '');
+  return { shellId: idM[1], outputFile: outputFile || null };
+}
+
+/** Parse a poll tool_result (`TaskOutput`/`BashOutput`) into { status, exitCode }. */
+export function parsePollResult(text) {
+  if (typeof text !== 'string') return null;
+  const sM = text.match(/<status>\s*([a-z_]+)\s*<\/status>/i);
+  if (!sM) return null;
+  const raw = sM[1].toLowerCase();
+  const eM = text.match(/<exit_code>\s*(-?\d+)\s*<\/exit_code>/i);
+  const exitCode = eM ? Number(eM[1]) : null;
+  let status = 'running';
+  if (raw === 'completed' || raw === 'done' || raw === 'finished') {
+    status = exitCode !== null && exitCode !== 0 ? 'failed' : 'completed';
+  } else if (raw === 'killed' || raw === 'stopped') {
+    status = 'killed';
+  } else if (raw === 'failed' || raw === 'error') {
+    status = 'failed';
+  }
+  return { status, exitCode };
+}
+
+// The shell id a poll/kill tool call targets, across the new + old vocabularies.
+function targetShellId(input) {
+  if (!input || typeof input !== 'object') return null;
+  return input.task_id || input.bash_id || input.shell_id || null;
+}
+
+const POLL_TOOLS = new Set(['TaskOutput', 'BashOutput']);
+const KILL_TOOLS = new Set(['TaskStop', 'KillShell', 'KillBash']);
+
+/**
+ * @param {object} opts
+ * @param {(task:object)=>void} [opts.broadcast]  called with the public task view on every change
+ * @param {()=>number}          [opts.now]
+ * @param {number}              [opts.pollMs]
+ * @param {number}              [opts.quietMs]
+ * @param {number}              [opts.maxPerWorkspace]
+ * @param {object}              [opts.fsImpl]      injectable fs (tests)
+ */
+export function createBackgroundTasks(opts = {}) {
+  const broadcast = typeof opts.broadcast === 'function' ? opts.broadcast : () => {};
+  const now = opts.now || Date.now;
+  const pollMs = opts.pollMs || DEFAULT_POLL_MS;
+  const quietMs = opts.quietMs || DEFAULT_QUIET_MS;
+  const maxPerWs = opts.maxPerWorkspace || DEFAULT_MAX_PER_WS;
+  const fsi = opts.fsImpl || fs;
+  // The OS holder/kill engine (Restart Manager on Windows, lsof on Unix). Injectable
+  // so tests never spawn PowerShell or kill a real process.
+  const holders = opts.holders || { resolveHolders: defaultResolveHolders, killTree: defaultKillTree };
+
+  // taskId (= the LAUNCH tool_use id) → task. Keying by the launch id (not the
+  // shellId) means the chat card, which is created at launch time and only knows the
+  // tool_use id, can correlate to live updates without a round-trip.
+  const tasks = new Map();
+  const byShell = new Map(); //  shellId → taskId  (for poll/kill correlation)
+  const pollTargets = new Map(); //  poll tool_use id → shellId  (result arrives later, idless)
+
+  let timer = null;
+
+  function publicView(t) {
+    return {
+      id: t.id,
+      shellId: t.shellId,
+      command: t.command,
+      description: t.description,
+      status: t.status,
+      exitCode: t.exitCode,
+      quiet: t.quiet,
+      startedAt: t.startedAt,
+      endedAt: t.endedAt,
+      lastOutputAt: t.lastOutputAt,
+      hasOutput: t.everExisted,
+      workspaceId: t.workspaceId,
+      threadId: t.threadId,
+      // NB: the absolute outputFile path is deliberately NOT exposed (it leaks the
+      // home dir — same rule the Logs route follows). Tail it via the by-id endpoint.
+    };
+  }
+
+  function emit(t) {
+    broadcast(publicView(t));
+  }
+
+  function prune(workspaceId) {
+    const ours = [...tasks.values()].filter((t) => t.workspaceId === workspaceId);
+    if (ours.length <= maxPerWs) return;
+    // Drop oldest TERMINAL tasks first; never evict something still running.
+    const terminal = ours.filter((t) => TERMINAL.has(t.status)).sort((a, b) => a.startedAt - b.startedAt);
+    let over = ours.length - maxPerWs;
+    for (const t of terminal) {
+      if (over <= 0) break;
+      tasks.delete(t.id);
+      if (t.shellId) byShell.delete(t.shellId);
+      over -= 1;
+    }
+  }
+
+  function startLaunch(workspaceId, threadId, chunk) {
+    const id = chunk.id;
+    if (!id || tasks.has(id)) return;
+    const input = chunk.input || {};
+    const t = {
+      id,
+      shellId: null,
+      outputFile: null,
+      command: String(input.command || '').slice(0, 2000),
+      description: String(input.description || '').slice(0, 300),
+      status: 'running',
+      exitCode: null,
+      quiet: false,
+      startedAt: now(),
+      endedAt: null,
+      lastOutputAt: null,
+      lastSize: 0,
+      everExisted: false,
+      workspaceId,
+      threadId: threadId || null,
+    };
+    tasks.set(id, t);
+    prune(workspaceId);
+    emit(t);
+    ensureTimer();
+  }
+
+  function fillLaunchResult(id, content) {
+    const t = tasks.get(id);
+    if (!t || t.shellId) return; // not a launch, or already resolved
+    const parsed = parseLaunchResult(content);
+    if (!parsed) return;
+    t.shellId = parsed.shellId;
+    t.outputFile = parsed.outputFile;
+    byShell.set(parsed.shellId, id);
+    emit(t);
+  }
+
+  function applyPoll(shellId, parsed) {
+    const id = byShell.get(shellId);
+    if (!id) return;
+    const t = tasks.get(id);
+    if (!t || TERMINAL.has(t.status)) return;
+    if (parsed.status === 'running') {
+      // A live poll proves it's alive right now — clears any `quiet` flag.
+      t.lastOutputAt = now();
+      if (t.quiet) { t.quiet = false; emit(t); }
+      return;
+    }
+    t.status = parsed.status;
+    t.exitCode = parsed.exitCode;
+    t.endedAt = now();
+    t.quiet = false;
+    emit(t);
+  }
+
+  function applyKill(shellId) {
+    const id = byShell.get(shellId);
+    if (!id) return;
+    const t = tasks.get(id);
+    if (!t || TERMINAL.has(t.status)) return;
+    t.status = 'killed';
+    t.endedAt = now();
+    t.quiet = false;
+    emit(t);
+  }
+
+  /**
+   * Fold one normalized chunk (from session.on('chunk')) into the registry. Only
+   * tool-use/tool-result chunks matter; everything else is ignored cheaply.
+   */
+  function observe(workspaceId, threadId, chunk) {
+    if (!chunk || !workspaceId) return;
+    if (chunk.type === 'tool-use') {
+      const name = chunk.name;
+      const input = chunk.input || {};
+      if (name === 'Bash' && input.run_in_background === true) {
+        startLaunch(workspaceId, threadId, chunk);
+      } else if (POLL_TOOLS.has(name)) {
+        const sid = targetShellId(input);
+        if (sid && chunk.id) pollTargets.set(chunk.id, sid);
+      } else if (KILL_TOOLS.has(name)) {
+        const sid = targetShellId(input);
+        if (sid) applyKill(sid);
+      }
+      return;
+    }
+    if (chunk.type === 'tool-result') {
+      const id = chunk.id;
+      if (!id) return;
+      if (tasks.has(id)) {
+        // The launching Bash's own result — carries the shell id + output path.
+        fillLaunchResult(id, chunk.content);
+      } else if (pollTargets.has(id)) {
+        const sid = pollTargets.get(id);
+        pollTargets.delete(id);
+        const parsed = parsePollResult(chunk.content);
+        if (parsed) applyPoll(sid, parsed);
+      }
+    }
+  }
+
+  // --- file-watcher: process-independent liveness for the gap between launch and
+  // the agent's next poll (which, in the per-turn model, may never come). -------
+  function tick() {
+    const t = now();
+    let anyLive = false;
+    for (const task of tasks.values()) {
+      if (TERMINAL.has(task.status)) continue;
+      anyLive = true;
+      if (!task.outputFile) continue;
+      let size = null;
+      try {
+        size = fsi.statSync(task.outputFile).size;
+      } catch {
+        size = null; // not created yet, or cleaned up after finishing
+      }
+      if (size !== null) {
+        if (!task.everExisted) task.everExisted = true;
+        if (size > task.lastSize) {
+          task.lastSize = size;
+          task.lastOutputAt = t;
+          if (task.quiet) { task.quiet = false; emit(task); }
+          continue;
+        }
+      }
+      // No new bytes this tick. Flag (or clear) the `quiet` hint honestly.
+      const idle = t - (task.lastOutputAt || task.startedAt);
+      const quiet = idle >= quietMs;
+      if (quiet !== task.quiet) { task.quiet = quiet; emit(task); }
+    }
+    if (!anyLive) stopTimer(); // nothing live → stop polling; observe() restarts it
+  }
+
+  function ensureTimer() {
+    if (timer) return;
+    timer = setInterval(tick, pollMs);
+    if (typeof timer.unref === 'function') timer.unref(); // never hold the process open
+  }
+  function stopTimer() {
+    if (timer) { clearInterval(timer); timer = null; }
+  }
+
+  return {
+    observe,
+    /** All tasks for a workspace, newest first. */
+    list(workspaceId) {
+      return [...tasks.values()]
+        .filter((t) => t.workspaceId === workspaceId)
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .map(publicView);
+    },
+    /**
+     * Stop a running task: find who holds its output file open (Restart Manager /
+     * lsof) and kill that tree. No PID was captured at launch — the output-file path
+     * we already track IS the handle. Returns {ok, status, ...}.
+     *
+     * `excludePids` MUST include any live claude pids; this method always also
+     * excludes our own pid. That guard is load-bearing: RM/lsof report READERS too,
+     * and the server tails this very file — without it we could kill ourselves.
+     */
+    async stop(workspaceId, taskId, { excludePids = [], retries = 4, retryDelayMs = 400 } = {}) {
+      const t = tasks.get(taskId);
+      if (!t || t.workspaceId !== workspaceId) return { ok: false, error: 'not-found' };
+      if (TERMINAL.has(t.status)) return { ok: true, status: t.status, alreadyTerminal: true };
+      if (!t.outputFile) return { ok: false, error: 'no-output-file' };
+      const exclude = new Set([process.pid, ...excludePids].map(Number).filter(Boolean));
+      // Retry: a single RM/lsof shot occasionally misses a live task (measured ~10%).
+      // Three clean misses on a live task is ~0.1%; a genuine empty means it finished.
+      let pids = [];
+      for (let attempt = 0; attempt <= retries; attempt++) {
+        const found = await holders.resolveHolders(t.outputFile);
+        pids = (found || []).filter((p) => !exclude.has(Number(p)));
+        if (pids.length) break;
+        if (attempt < retries) await sleep(retryDelayMs);
+      }
+      if (!pids.length) {
+        // Nobody holds it after retries → the process already exited. It finished; we
+        // did NOT stop it — say so honestly (never claim a kill we didn't make).
+        if (!TERMINAL.has(t.status)) { t.status = 'completed'; t.endedAt = now(); t.quiet = false; emit(t); }
+        return { ok: true, status: 'completed', note: 'already-finished' };
+      }
+      const killed = await holders.killTree(pids);
+      t.status = 'killed';
+      t.endedAt = now();
+      t.exitCode = null;
+      t.quiet = false;
+      emit(t);
+      return { ok: true, status: 'killed', pids, killed };
+    },
+    /** Tail the output file for one task (best-effort; null if unavailable). */
+    tail(workspaceId, taskId, bytes = TAIL_BYTES) {
+      const t = tasks.get(taskId);
+      if (!t || t.workspaceId !== workspaceId || !t.outputFile) return null;
+      try {
+        const stat = fsi.statSync(t.outputFile);
+        const start = Math.max(0, stat.size - bytes);
+        const fd = fsi.openSync(t.outputFile, 'r');
+        try {
+          const len = stat.size - start;
+          const buf = Buffer.alloc(len);
+          fsi.readSync(fd, buf, 0, len, start);
+          return buf.toString('utf8');
+        } finally {
+          fsi.closeSync(fd);
+        }
+      } catch {
+        return null;
+      }
+    },
+    /** Test/diagnostic: the internal task (incl. outputFile). */
+    _get(taskId) {
+      return tasks.get(taskId) || null;
+    },
+    _tick: tick,
+    dispose: stopTimer,
+  };
+}

package/server/src/index.mjs

@@ -84,6 +84,7 @@ import { loadAccount } from './account.mjs';
 import { getOperatorToken } from './operator.mjs';
 import { runDoctor } from './doctor.mjs';
 import { appendLine, tailFile, logFile, listLogs, TAILABLE, globalDir } from './logpaths.mjs';
+import { createBackgroundTasks } from './background-tasks.mjs';
 import { SessionReporter } from './session-reporter.mjs';
 import { TranscriptRecorder } from './transcript.mjs';
 import { loadObservabilityConsent, setObservabilityConsent } from './observability.mjs';
@@ -578,6 +579,23 @@ export async function createServer(overrides = {}) {
     }
   }
 
+  // Background-task frames are WORKSPACE-scoped but THREAD-agnostic: a job the agent
+  // launched in chat A is still "running in this workspace", so the topbar tray and
+  // the canvas Tasks block (which span threads) must see it. Sent to every socket on
+  // the workspace, regardless of which chat thread it's bound to.
+  function broadcastTask(task) {
+    if (!task || !task.workspaceId) return;
+    const data = JSON.stringify({ type: 'task', task });
+    for (const ws of chatClients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      if (ws._wsWorkspaceId !== task.workspaceId) continue;
+      ws.send(data);
+    }
+  }
+  // The registry persists ACROSS turns (a background job outlives the `claude -p`
+  // process that spawned it), so it lives here in server scope — never per-session.
+  const bgTasks = createBackgroundTasks({ broadcast: broadcastTask });
+
   /**
    * Run one chat turn: spawn the agent, stream every chunk to every chat
    * client, and persist the resulting session id so the next turn resumes it.
@@ -644,6 +662,10 @@ export async function createServer(overrides = {}) {
           return;
         }
         if (chunk.type === 'error') sawError = true;
+        // Track background jobs (Bash run_in_background:true + any TaskOutput/BashOutput
+        // polls) so the chat card, topbar tray, and Tasks block can show live status.
+        // Cheap no-op for every other chunk type.
+        bgTasks.observe(workspace.id, threadId, chunk);
         broadcastChat({ type: 'chunk', messageId: id, chunk }, workspace.id, threadId);
         activityBus.publish({ type: 'chat-stream', messageId: id, chunk });
         // Surface the turn's token/cost totals so the activity bar can show
@@ -2554,6 +2576,45 @@ export async function createServer(overrides = {}) {
     return c.json({ name, lines, body: tailFile(logFile(name), lines) });
   });
 
+  // Background tasks (the agent's run_in_background jobs) — what's running, finished,
+  // or gone quiet. Owner-only (fileTree): these expose the commands the agent ran on
+  // the host, which a share-link viewer must not see (same posture as Logs). The
+  // absolute output-file path is never returned (it would leak the home dir); tail it
+  // by id instead.
+  app.get('/api/workspace/tasks', (c) => {
+    const forbidden = require(c, 'fileTree');
+    if (forbidden) return forbidden;
+    return c.json({ tasks: bgTasks.list(workspaceFor(c).id) });
+  });
+
+  app.get('/api/workspace/tasks/:id/output', (c) => {
+    const forbidden = require(c, 'fileTree');
+    if (forbidden) return forbidden;
+    const id = c.req.param('id');
+    const bytes = Math.min(Number(c.req.query('bytes')) || 16384, 200_000);
+    const output = bgTasks.tail(workspaceFor(c).id, id, bytes);
+    if (output === null) return c.json({ error: 'no-output', id }, 404);
+    return c.json({ id, output });
+  });
+
+  // Stop a running background task — resolve who holds its output file open and kill
+  // that tree (Restart Manager on Windows, lsof on Unix). Owner-only. We pass every
+  // LIVE claude pid to exclude so a Stop during an in-flight turn can't kill the
+  // active agent (and `stop` always also excludes our own server pid — the guard that
+  // matters, since RM/lsof report the file's readers too).
+  app.post('/api/workspace/tasks/:id/stop', async (c) => {
+    const forbidden = require(c, 'fileTree');
+    if (forbidden) return forbidden;
+    const id = c.req.param('id');
+    const claudePids = [...currentTurns.values()]
+      .map((t) => t?.session?.proc?.pid)
+      .filter((p) => Number.isInteger(p));
+    auditAction(c, 'task-stop', `id=${id}`);
+    const res = await bgTasks.stop(workspaceFor(c).id, id, { excludePids: claudePids });
+    if (!res.ok) return c.json(res, res.error === 'not-found' ? 404 : 400);
+    return c.json(res);
+  });
+
   // --- component inbox ---
   app.get('/api/inbox', async (c) => {
     // Enforce the `inbox` capability (partner-only). It existed in the matrix

package/server/src/process-holders.mjs

@@ -0,0 +1,122 @@
+// Cross-platform "who is running this background task, and stop it" — without ever
+// capturing a PID at launch (which fighting claude's opaque background mechanism
+// proved unreliable). Instead we use the one thing we already know: the task's
+// OUTPUT FILE path. The running process holds that file open, so:
+//
+//   resolveHolders(file) -> the PIDs holding it open
+//   killTree(pids)       -> stop them (whole tree)
+//
+//   Windows: Restart Manager (rstrtmgr.dll) — the API installers use to find which
+//            process locks a file — driven by a tiny embedded PowerShell helper.
+//   macOS/Linux: `lsof -t` (terse, PIDs only).
+//
+// SAFETY (proven necessary in the spike): RM/lsof also report READERS — our own
+// server tails the file, so a naive kill could `taskkill` the wild-workspace server
+// itself. Callers MUST pass the pids to exclude (our pid + any live claude pids);
+// this module never kills blindly.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const execFileP = promisify(execFile);
+
+// PowerShell Restart Manager locker-finder. Embedded (not a shipped .ps1) so it
+// works regardless of how the package is published; written to a temp file on first
+// use and invoked with -File. Prints the holding PIDs, one per line.
+const RM_PS = [
+  'param([string]$Path)',
+  "$ErrorActionPreference='SilentlyContinue'",
+  "$sig = @'",
+  'using System; using System.Runtime.InteropServices; using System.Collections.Generic;',
+  'public static class RmFile {',
+  ' [StructLayout(LayoutKind.Sequential)] struct RM_UNIQUE_PROCESS { public int dwProcessId; public System.Runtime.InteropServices.ComTypes.FILETIME ProcessStartTime; }',
+  ' [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)] struct RM_PROCESS_INFO {',
+  '  public RM_UNIQUE_PROCESS Process;',
+  '  [MarshalAs(UnmanagedType.ByValTStr, SizeConst=256)] public string strAppName;',
+  '  [MarshalAs(UnmanagedType.ByValTStr, SizeConst=64)] public string strServiceShortName;',
+  '  public int ApplicationType; public uint AppStatus; public uint TSSessionId; [MarshalAs(UnmanagedType.Bool)] public bool bRestartable; }',
+  ' [DllImport("rstrtmgr.dll", CharSet=CharSet.Unicode)] static extern int RmStartSession(out uint h, int flags, string key);',
+  ' [DllImport("rstrtmgr.dll")] static extern int RmEndSession(uint h);',
+  ' [DllImport("rstrtmgr.dll", CharSet=CharSet.Unicode)] static extern int RmRegisterResources(uint h, uint nf, string[] files, uint na, RM_UNIQUE_PROCESS[] apps, uint ns, string[] svc);',
+  ' [DllImport("rstrtmgr.dll")] static extern int RmGetList(uint h, out uint need, ref uint count, [In,Out] RM_PROCESS_INFO[] info, ref uint reasons);',
+  ' public static List<int> Lockers(string p){ var r=new List<int>(); uint h; if(RmStartSession(out h,0,Guid.NewGuid().ToString())!=0)return r;',
+  '  try{ if(RmRegisterResources(h,1,new[]{p},0,null,0,null)!=0)return r; uint need=0,count=0,reasons=0; int res=RmGetList(h,out need,ref count,null,ref reasons);',
+  '   if(res==234){ var info=new RM_PROCESS_INFO[need]; count=need; if(RmGetList(h,out need,ref count,info,ref reasons)==0){ for(int i=0;i<count;i++) r.Add(info[i].Process.dwProcessId);} } }',
+  '  finally{ RmEndSession(h); } return r; } }',
+  "'@",
+  'Add-Type -TypeDefinition $sig',
+  '[RmFile]::Lockers($Path) | ForEach-Object { $_ }',
+].join('\r\n');
+
+let _rmScriptPath = null;
+function ensureRmScript() {
+  if (_rmScriptPath && fs.existsSync(_rmScriptPath)) return _rmScriptPath;
+  const p = path.join(os.tmpdir(), 'wild-workspace-rm-holders.ps1');
+  try { fs.writeFileSync(p, RM_PS, 'utf8'); _rmScriptPath = p; } catch { _rmScriptPath = null; }
+  return _rmScriptPath;
+}
+
+function parsePids(stdout) {
+  return String(stdout || '')
+    .split(/\r?\n/)
+    .map((l) => parseInt(l.trim(), 10))
+    .filter((n) => Number.isInteger(n) && n > 0);
+}
+
+/**
+ * PIDs currently holding `filePath` open (the running task's process tree + any
+ * readers). Returns [] on any failure or when nothing holds it (task finished).
+ */
+export async function resolveHolders(filePath, { exec = execFileP, platform = process.platform } = {}) {
+  if (!filePath) return [];
+  try {
+    if (platform === 'win32') {
+      const script = ensureRmScript();
+      if (!script) return [];
+      const { stdout } = await exec(
+        'powershell',
+        ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Path', filePath],
+        { timeout: 9000, windowsHide: true },
+      );
+      return uniq(parsePids(stdout));
+    }
+    const { stdout } = await exec('lsof', ['-t', '--', filePath], { timeout: 9000 });
+    return uniq(parsePids(stdout));
+  } catch (e) {
+    // lsof exits 1 with no output when nothing holds the file — that's "empty", not
+    // an error. Salvage any stdout the failed call captured, else treat as empty.
+    if (e && e.stdout) return uniq(parsePids(e.stdout));
+    return [];
+  }
+}
+
+/** Force-kill each pid AND its child tree. Returns per-pid {pid, ok}. */
+export async function killTree(pids, { exec = execFileP, platform = process.platform, kill = (p, s) => process.kill(p, s) } = {}) {
+  const out = [];
+  for (const pid of uniq(pids)) {
+    try {
+      if (platform === 'win32') {
+        await exec('taskkill', ['/PID', String(pid), '/T', '/F'], { timeout: 9000, windowsHide: true });
+      } else {
+        // SIGKILL the holder; lsof returned the whole fd-sharing chain, so killing
+        // each holder takes down the tree. A transient child (e.g. `sleep`) exits on
+        // its own once its parent is gone.
+        try { kill(pid, 'SIGKILL'); } catch { /* already gone */ }
+      }
+      out.push({ pid, ok: true });
+    } catch (e) {
+      // taskkill exits non-zero with "process not found" when /T already reaped it as
+      // part of an earlier pid's tree — that's success, not failure.
+      const msg = String((e && (e.stderr || e.message)) || '');
+      out.push({ pid, ok: /not found|not be terminated/i.test(msg) });
+    }
+  }
+  return out;
+}
+
+function uniq(arr) {
+  return [...new Set(arr)];
+}