@livx.cc/agentx 0.99.46 → 0.99.48

package/dist/tools.shell.js

@@ -533,8 +533,331 @@ async function findSandboxWrapper(platform = process.platform) {
   return null;
 }
 
+// src/tools.jobs.ts
+var log5 = forComponent("jobs");
+var JobRegistryOptions = class {
+  /** Tail buffer cap per job (chars). */
+  maxBuffer = 256 * 1024;
+  /** Idle window per kind: no output/progress/CPU for this long ⇒ stuck. Kinds without an activity channel
+   *  (host, native) are absent on purpose — silence is all they can ever show, so it proves nothing; their
+   *  bound is the hard cap. Explicit `background:true` shell jobs opt out per job (a quiet server is healthy). */
+  idleMs = { shell: 10 * 6e4, mcp: 10 * 6e4 };
+  /** Absolute ceiling per kind (0/absent = none). */
+  hardCapMs = { mcp: 30 * 6e4 };
+  /** Soft foreground timeout per kind: past it the caller stops waiting and gets a job id instead. */
+  foregroundMs = { mcp: 3e4 };
+  /** How often the reaper runs while reapable jobs exist. */
+  sweepMs = 15e3;
+  /** Grace between the kill signal and a forced kill (producers that escalate read this). */
+  killGraceMs = 5e3;
+  /** Finished jobs kept for inspection; older finished ones are pruned (every delegated tool call is a job). */
+  keepFinished = 200;
+  /** Clock (injectable for tests). Late-bound so a patched Date.now is honoured. */
+  now = () => Date.now();
+  /** Terminal-state notification for jobs with `notify` (the Agent wires this to `inject`). */
+  onExit;
+};
+var secs = (ms) => `${Math.round(ms / 1e3)}s`;
+var JobRegistry = class {
+  options;
+  jobs = /* @__PURE__ */ new Map();
+  seq = 0;
+  timer;
+  constructor(options) {
+    this.options = { ...new JobRegistryOptions(), ...options };
+  }
+  /** Register externally-driven work (a process, a request, a native tool) and get a handle to feed it. */
+  track(opts = {}) {
+    const o = this.options;
+    const kind = opts.kind ?? "task";
+    const now = o.now();
+    let settle;
+    const done = new Promise((r) => {
+      settle = r;
+    });
+    const job = {
+      id: `job-${++this.seq}`,
+      kind,
+      label: opts.label ?? "",
+      status: "running",
+      startedAt: now,
+      lastActivityAt: now,
+      bytes: 0,
+      holds: !!opts.holds,
+      buf: "",
+      dropped: 0,
+      idleMs: opts.idleMs ?? o.idleMs[kind] ?? 0,
+      hardCapMs: opts.hardCapMs ?? o.hardCapMs[kind] ?? 0,
+      drain: !!opts.drain,
+      notify: !!opts.notify,
+      idleAfterActivity: !!opts.idleAfterActivity,
+      active: false,
+      cpuTime: opts.cpuTime,
+      onKill: opts.onKill,
+      onExit: opts.onExit,
+      done,
+      settle
+    };
+    this.jobs.set(job.id, job);
+    if (opts.seed) this.append(job, opts.seed);
+    this.arm();
+    return {
+      id: job.id,
+      chunk: (s) => {
+        if (s) {
+          this.append(job, s);
+          job.lastActivityAt = o.now();
+          job.active = true;
+        }
+      },
+      touch: () => {
+        job.lastActivityAt = o.now();
+        job.active = true;
+      },
+      finish: (status, result, reason) => this.end(job, status, result, reason),
+      detach: () => {
+        job.holds = false;
+        job.notify = true;
+        job.drain = true;
+      },
+      get status() {
+        return job.status;
+      }
+    };
+  }
+  /** Start `fn` in the background and return a job id immediately (sandbox/subagent semantics: drained at turn end). */
+  start(fn, opts = {}) {
+    return this.run(fn, { drain: true, ...opts }).handle.id;
+  }
+  /**
+   * Run `fn` in the FOREGROUND with a soft timeout: resolves `{done:true,value}` if it settles in time, else
+   * `{done:false,id}` — the work keeps going as a detached job whose completion is reported via `onExit`.
+   * A rejection before the timeout is rethrown (the caller's normal error path). `softTimeoutMs` ≤ 0 waits forever.
+   */
+  async runForeground(fn, opts = {}) {
+    const { handle, promise } = this.run(fn, opts);
+    const soft = opts.softTimeoutMs ?? this.options.foregroundMs[opts.kind ?? "task"] ?? 0;
+    let t;
+    const late = soft > 0 ? new Promise((r) => {
+      t = setTimeout(() => r("late"), soft);
+    }) : new Promise(() => {
+    });
+    try {
+      const r = await Promise.race([promise.then((v) => ({ v }), (e) => ({ e })), late]);
+      if (r !== "late" && handle.status !== "running") this.jobs.delete(handle.id);
+      if (r === "late") {
+        if (handle.status === "running") {
+          handle.detach();
+          return { done: false, id: handle.id };
+        }
+        const settled = await promise.then((v) => ({ v }), (e) => ({ e }));
+        if ("e" in settled) throw settled.e;
+        return { done: true, value: settled.v };
+      }
+      if ("e" in r) throw r.e;
+      return { done: true, value: r.v };
+    } finally {
+      if (t) clearTimeout(t);
+    }
+  }
+  run(fn, opts) {
+    const ctl = new AbortController();
+    const handle = this.track({ ...opts, onKill: (reason) => {
+      ctl.abort(Object.assign(new Error(reason), { name: "AbortError", code: "job_killed" }));
+      opts.onKill?.(reason);
+    } });
+    let promise;
+    try {
+      promise = fn({ signal: ctl.signal, onChunk: handle.chunk, touch: handle.touch });
+    } catch (e) {
+      promise = Promise.reject(e);
+    }
+    promise.then(
+      (res) => {
+        if (handle.status === "running" && typeof res === "string" && res) handle.chunk(res);
+        handle.finish("done", res);
+      },
+      (e) => {
+        if (handle.status === "running") handle.chunk(`
+[error] ${e?.message ?? e}`);
+        handle.finish("error", void 0, e?.message ?? String(e));
+      }
+    );
+    return { handle, promise };
+  }
+  append(job, s) {
+    job.buf += s;
+    const over = job.buf.length - this.options.maxBuffer;
+    if (over > 0) {
+      job.buf = job.buf.slice(over);
+      job.dropped += over;
+    }
+    job.bytes = job.buf.length;
+  }
+  end(job, status, result, reason) {
+    if (job.status !== "running") return;
+    job.status = status;
+    job.endedAt = this.options.now();
+    job.result = result;
+    if (reason && status !== "done") job.reason = reason;
+    job.holds = false;
+    job.settle();
+    this.prune();
+    const onExit = job.onExit ?? this.options.onExit;
+    if (job.notify && onExit) {
+      try {
+        onExit({ id: job.id, kind: job.kind, label: job.label, status, reason: job.reason, tail: job.buf.slice(-4e3), result });
+      } catch (e) {
+        log5.warn(`job onExit handler threw for ${job.id}: ${e}`);
+      }
+    }
+  }
+  prune() {
+    const finished = [...this.jobs.values()].filter((j) => j.status !== "running");
+    for (const j of finished.slice(0, Math.max(0, finished.length - this.options.keepFinished))) this.jobs.delete(j.id);
+  }
+  /** Current tail output (null = no such job). */
+  output(id) {
+    return this.jobs.get(id)?.buf ?? null;
+  }
+  /** Incremental read: output from absolute char `offset` (clamped to what the ring still holds). */
+  read(id, offset = 0) {
+    const j = this.jobs.get(id);
+    if (!j) return null;
+    const start = Math.max(0, offset - j.dropped);
+    return { text: j.buf.slice(start), next: j.dropped + j.buf.length, truncated: offset < j.dropped };
+  }
+  get(id) {
+    const j = this.jobs.get(id);
+    return j ? this.info(j) : null;
+  }
+  status(id) {
+    const j = this.jobs.get(id);
+    return j ? { status: j.status, bytes: j.bytes, ...j.reason ? { reason: j.reason } : {} } : null;
+  }
+  list() {
+    return [...this.jobs.values()].map((j) => this.info(j));
+  }
+  info(j) {
+    const { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes, holds, result } = j;
+    return { id, kind, label, status, startedAt, lastActivityAt, endedAt, reason, bytes, holds, result };
+  }
+  /** Wait (bounded) for a job to settle. Resolves the job's info either way; null for an unknown id. */
+  async wait(id, timeoutMs) {
+    const j = this.jobs.get(id);
+    if (!j) return null;
+    let t;
+    await Promise.race([j.done, new Promise((r) => {
+      t = setTimeout(r, Math.max(0, timeoutMs));
+    })]);
+    if (t) clearTimeout(t);
+    return this.info(j);
+  }
+  /** Stop a job: runs its `onKill` (abort/SIGTERM) and marks it killed with `reason`. */
+  kill(id, reason = "killed by request") {
+    const j = this.jobs.get(id);
+    if (!j) return false;
+    if (j.status === "running") {
+      this.end(j, "killed", void 0, reason);
+      try {
+        j.onKill?.(reason);
+      } catch (e) {
+        log5.warn(`onKill for ${id} threw: ${e}`);
+      }
+    }
+    return true;
+  }
+  /** Kill every running job — or, with `onlyDrainable`, only turn-scoped ones (sandbox/sub-agent/handed-off MCP),
+   *  leaving jobs meant to outlive a run (a background dev server) alone. */
+  killAll(reason = "run ended", onlyDrainable = false) {
+    for (const j of this.jobs.values()) if (!onlyDrainable || j.drain) this.kill(j.id, reason);
+  }
+  /** Jobs something is synchronously waiting on (see `JobTrackOptions.holds`) that are still running. */
+  holding() {
+    return [...this.jobs.values()].filter((j) => j.status === "running" && j.holds).map((j) => this.info(j));
+  }
+  /** Await every drainable running job (turn end). Returns the ids that were still running when drain began. */
+  async drain(signal) {
+    const pending = [...this.jobs.values()].filter((j) => j.status === "running" && j.drain);
+    const all = Promise.all(pending.map((j) => j.done));
+    await (signal ? Promise.race([all, new Promise((r) => signal.aborted ? r() : signal.addEventListener("abort", () => r(), { once: true }))]) : all);
+    return pending.map((j) => j.id);
+  }
+  /**
+   * The stuck-job decision, synchronous part: kill every running job past its hard cap, or past its idle
+   * window when it has no CPU probe to argue otherwise. Cheap — the stall watchdog calls it on every tick.
+   * Returns the killed ids. Jobs WITH a probe are left to `sweep()`.
+   */
+  reap() {
+    const now = this.options.now();
+    const killed = [];
+    for (const j of this.jobs.values()) {
+      if (j.status !== "running") continue;
+      const verdict = this.verdict(j, now);
+      if (!verdict || verdict.idle && j.cpuTime) continue;
+      this.stuck(j, verdict.reason, now);
+      killed.push(j.id);
+    }
+    return killed;
+  }
+  /** Full sweep: sample CPU probes (advancing CPU = activity), then `reap()` including probed jobs. */
+  async sweep() {
+    const now = this.options.now();
+    for (const j of [...this.jobs.values()]) {
+      if (j.status !== "running" || !j.cpuTime || !j.idleMs) continue;
+      let cpu;
+      try {
+        cpu = await j.cpuTime();
+      } catch (e) {
+        log5.debug(`cpu probe for ${j.id} failed: ${e}`);
+      }
+      if (cpu != null && j.lastCpu != null && cpu > j.lastCpu) j.lastActivityAt = this.options.now();
+      const prev = j.lastCpu;
+      if (cpu != null) j.lastCpu = cpu;
+      const verdict = this.verdict(j, now);
+      if (!verdict?.idle || j.status !== "running") continue;
+      if (cpu == null) {
+        log5.debug(`not reaping ${j.id}: ${verdict.reason} but CPU unknown`);
+        continue;
+      }
+      if (prev == null) continue;
+      this.stuck(j, `${verdict.reason}, no CPU progress (${prev}s \u2192 ${cpu}s)`, now);
+    }
+    return this.reap();
+  }
+  verdict(j, now) {
+    if (j.hardCapMs && now - j.startedAt >= j.hardCapMs) return { reason: `stuck: exceeded hard cap ${secs(j.hardCapMs)}`, idle: false };
+    if (j.idleMs && (!j.idleAfterActivity || j.active) && now - j.lastActivityAt >= j.idleMs) return { reason: `stuck: idle ${secs(now - j.lastActivityAt)}`, idle: true };
+    return null;
+  }
+  stuck(j, reason, now) {
+    log5.warn(`reaping ${j.id} (${j.kind} "${j.label}"): ${reason} \u2014 age ${secs(now - j.startedAt)}, last activity ${secs(now - j.lastActivityAt)} ago, idleMs=${j.idleMs}, hardCapMs=${j.hardCapMs}, ${j.bytes} byte(s) output`);
+    if (j.onKill) j.notify = true;
+    this.kill(j.id, reason);
+  }
+  /** Keep a reaper interval alive only while a reapable job is running (unref'd: never holds the process open). */
+  arm() {
+    if (this.timer || !this.options.sweepMs) return;
+    this.timer = setInterval(() => {
+      const live = [...this.jobs.values()].some((j) => j.status === "running" && (j.idleMs || j.hardCapMs));
+      if (!live) {
+        clearInterval(this.timer);
+        this.timer = void 0;
+        return;
+      }
+      void this.sweep().catch((e) => log5.warn(`job sweep failed: ${e}`));
+    }, this.options.sweepMs);
+    this.timer.unref?.();
+  }
+  /** Stop the reaper timer (tests / teardown). */
+  dispose() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+};
+
 // src/tools.shell.ts
-var log5 = forComponent("shell");
+var log6 = forComponent("shell");
 var clean = (s) => truncateOutput(redactSecrets(s.replace(/\n+$/, "")));
 var DETACHED = { stdio: ["ignore", "pipe", "pipe"], detached: true };
 function killGroup(proc, signal) {
@@ -567,62 +890,122 @@ async function nodeSpawn() {
   return _spawn;
 }
 function formatJobExit(n) {
-  return `[background job ${n.id} ${n.status}${n.exitCode != null ? ` exit ${n.exitCode}` : ""}] \`${n.command}\`
+  return `[background job ${n.id} ${n.status}${n.exitCode != null ? ` exit ${n.exitCode}` : ""}${n.reason ? `: ${n.reason}` : ""}] \`${n.command}\`
 ` + (n.tail ? `${n.tail}
 ` : "(no output)\n") + `Read the full output with ShellOutput({id:"${n.id}"}).`;
 }
+function parsePsTime(t) {
+  const m = t.trim().match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+(?:\.\d+)?)$/);
+  if (!m) return void 0;
+  return Number(m[1] ?? 0) * 86400 + Number(m[2] ?? 0) * 3600 + Number(m[3]) * 60 + Number(m[4]);
+}
+async function psGroupCpuSeconds(pgid) {
+  try {
+    const { execFile } = await import("child_process");
+    const out = await new Promise((res, rej) => execFile("ps", ["-A", "-o", "pid=,ppid=,pgid=,time="], { timeout: 5e3, env: { ...process.env, LC_ALL: "C" } }, (e, so) => e ? rej(e) : res(String(so))));
+    return sumTreeCpu(out, pgid);
+  } catch (e) {
+    log6.debug(`ps cpu probe failed for group ${pgid}: ${e}`);
+    return void 0;
+  }
+}
+function sumTreeCpu(psOut, root) {
+  const rows = psOut.split("\n").map((l) => l.trim().split(/\s+/)).filter((r) => r.length >= 4).map(([pid, ppid, pgid, time]) => ({ pid: Number(pid), ppid: Number(ppid), pgid: Number(pgid), sec: parsePsTime(time) }));
+  const inJob = new Set(rows.filter((r) => r.pgid === root || r.pid === root).map((r) => r.pid));
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const r of rows) if (!inJob.has(r.pid) && inJob.has(r.ppid)) {
+      inJob.add(r.pid);
+      grew = true;
+    }
+  }
+  let total;
+  for (const r of rows) if (inJob.has(r.pid) && r.sec != null) total = (total ?? 0) + r.sec;
+  return total;
+}
 var ShellJobRegistry = class {
   constructor(cfg) {
     this.cfg = cfg;
+    this.jobs = cfg.jobs ?? new JobRegistry(cfg.maxBuffer ? { maxBuffer: cfg.maxBuffer } : {});
     if (cfg.killOnExit && typeof process !== "undefined") process.once("exit", () => this.killAll());
   }
   cfg;
-  jobs = /* @__PURE__ */ new Map();
-  seq = 0;
+  jobs;
+  meta = /* @__PURE__ */ new Map();
   async start(command) {
-    const id = `job-${++this.seq}`;
-    const max = this.cfg.maxBuffer ?? 256 * 1024;
-    const job = { command, buf: "", status: "running" };
-    const append = (chunk) => {
-      const s = typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "";
-      job.buf = (job.buf + s).slice(-max);
-    };
+    const h = this.track(command, { idleMs: 0 });
     try {
       const spawn = this.cfg.spawn ?? await nodeSpawn();
       const argv = this.cfg.osSandbox ? await spawnArgvFor(command, this.cfg.cwd, this.cfg.osSandbox) : { bin: "/bin/sh", args: ["-c", command] };
-      const proc = spawn(argv.bin, argv.args, { cwd: this.cfg.cwd, env: childEnv(this.cfg), ...DETACHED });
-      job.proc = proc;
-      proc.stdout?.on("data", append);
-      proc.stderr?.on("data", append);
-      proc.on("error", (err) => {
-        if (job.status === "running") {
-          job.status = "error";
-          append(`
-[error] ${err?.message ?? err}`);
-          this.notifyExit(id, job);
-        }
-      });
-      proc.on("close", (code) => {
-        if (job.status === "running") {
-          job.status = "exited";
-          job.exitCode = code ?? void 0;
-          this.notifyExit(id, job);
-        }
-      });
+      this.attach(h, spawn(argv.bin, argv.args, { cwd: this.cfg.cwd, env: childEnv(this.cfg), ...DETACHED }));
     } catch (e) {
-      job.status = "error";
-      job.buf = `failed to spawn: ${e?.message ?? e}`;
+      h.chunk(`failed to spawn: ${e?.message ?? e}`);
+      h.finish("error", void 0, e?.message ?? String(e));
+    }
+    return h.id;
+  }
+  track(command, extra) {
+    const meta = { command };
+    let id = "";
+    const h = this.jobs.track({
+      kind: "shell",
+      label: command,
+      seed: extra.seed,
+      idleMs: extra.idleMs,
+      cpuTime: extra.cpu ? async () => meta.proc?.pid ? (this.cfg.cpuTime ?? psGroupCpuSeconds)(meta.proc.pid) : void 0 : void 0,
+      onKill: () => this.signal(meta),
+      onExit: (n) => this.notifyExit(id, meta, n.status, n.reason),
+      notify: true
+    });
+    id = h.id;
+    this.meta.set(id, meta);
+    return h;
+  }
+  attach(h, proc) {
+    const meta = this.meta.get(h.id);
+    meta.proc = proc;
+    const append = (chunk) => h.chunk(typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "");
+    proc.stdout?.on("data", append);
+    proc.stderr?.on("data", append);
+    proc.on("error", (err) => {
+      if (h.status === "running") {
+        append(`
+[error] ${err?.message ?? err}`);
+        h.finish("error", void 0, err?.message ?? String(err));
+      }
+    });
+    proc.on("close", (code) => {
+      if (h.status === "running") {
+        meta.exitCode = code ?? void 0;
+        h.finish("done");
+      }
+    });
+  }
+  /** SIGTERM the whole group (bg children are detached group leaders — /bin/sh alone would orphan a forked
+   *  server), then SIGKILL after the grace period if it is still there. Falls back to the pid for fakes. */
+  signal(meta) {
+    const proc = meta.proc;
+    if (!killGroup(proc, "SIGTERM")) {
+      try {
+        proc?.kill("SIGTERM");
+      } catch {
+      }
     }
-    this.jobs.set(id, job);
-    return id;
-  }
-  /** Fire `onExit` at most once per job, with the tail so the model can act without a second round-trip. */
-  notified = /* @__PURE__ */ new Set();
-  notifyExit(id, job) {
-    if (this.notified.has(id) || !this.cfg.onExit) return;
-    this.notified.add(id);
+    if (!proc?.pid) return;
+    let closed = false;
+    proc.on("close", () => {
+      closed = true;
+    });
+    const t = setTimeout(() => {
+      if (!closed) killGroup(proc, "SIGKILL");
+    }, this.jobs.options.killGraceMs);
+    t.unref?.();
+  }
+  /** Fire `onExit` at most once per job (the registry guarantees one terminal state), with the tail so the model can act without a second round-trip. */
+  notifyExit(id, meta, status, reason) {
+    if (!this.cfg.onExit || status === "killed" && !reason?.startsWith("stuck")) return;
     try {
-      this.cfg.onExit({ id, command: job.command, status: job.status, exitCode: job.exitCode, tail: clean(job.buf).slice(-4e3) });
+      this.cfg.onExit({ id, command: meta.command, status: shellStatus(status), exitCode: meta.exitCode, tail: clean(this.jobs.output(id) ?? "").slice(-4e3), ...reason && status !== "done" ? { reason } : {} });
     } catch {
     }
   }
@@ -641,14 +1024,20 @@ var ShellJobRegistry = class {
   }
   /** Current tail output for a job (null = no such job). */
   output(id) {
-    return this.jobs.get(id)?.buf ?? (this.jobs.has(id) ? "" : null);
+    return this.meta.has(id) ? this.jobs.output(id) : null;
   }
+  // null too once the shared registry pruned it
   status(id) {
-    const j = this.jobs.get(id);
-    return j ? { status: j.status, exitCode: j.exitCode, bytes: j.buf.length } : null;
+    const m = this.meta.get(id);
+    const j = m && this.jobs.get(id);
+    if (!m || !j) {
+      this.meta.delete(id);
+      return null;
+    }
+    return { status: shellStatus(j.status), exitCode: m.exitCode, bytes: j.bytes, ...j.reason ? { reason: j.reason } : {} };
   }
   list() {
-    return [...this.jobs].map(([id, j]) => ({ id, command: j.command, status: j.status }));
+    return [...this.meta].filter(([id]) => this.jobs.get(id)).map(([id, m]) => ({ id, command: m.command, status: shellStatus(this.jobs.get(id).status) }));
   }
   /**
    * Take over an ALREADY-RUNNING child as a background job. A foreground command that outruns its
@@ -656,53 +1045,22 @@ var ShellJobRegistry = class {
    * worse, a launcher that spawned its own detached worker leaves that worker running with nothing
    * tracking it. Adopting hands the model a handle instead: the command keeps going, its completion
    * is reported like any other job, and `seed` carries the output produced before the handoff.
+   * Unlike an explicit background job it IS liveness-checked (idle window + CPU probe): nobody asked for
+   * a long-lived process here, so one that goes silent and CPU-idle is stuck, not serving.
    */
   adopt(command, proc, seed = "") {
-    const id = `job-${++this.seq}`;
-    const max = this.cfg.maxBuffer ?? 256 * 1024;
-    const job = { command, buf: seed.slice(-max), status: "running", proc };
-    const append = (chunk) => {
-      const s = typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "";
-      job.buf = (job.buf + s).slice(-max);
-    };
-    proc.stdout?.on("data", append);
-    proc.stderr?.on("data", append);
-    proc.on("error", (err) => {
-      if (job.status === "running") {
-        job.status = "error";
-        append(`
-[error] ${err?.message ?? err}`);
-        this.notifyExit(id, job);
-      }
-    });
-    proc.on("close", (code) => {
-      if (job.status === "running") {
-        job.status = "exited";
-        job.exitCode = code ?? void 0;
-        this.notifyExit(id, job);
-      }
-    });
-    this.jobs.set(id, job);
-    return id;
+    const h = this.track(command, { seed, cpu: true });
+    this.attach(h, proc);
+    return h.id;
   }
-  kill(id) {
-    const j = this.jobs.get(id);
-    if (!j) return false;
-    if (j.status === "running") {
-      if (!killGroup(j.proc, "SIGTERM")) {
-        try {
-          j.proc?.kill("SIGTERM");
-        } catch {
-        }
-      }
-      j.status = "killed";
-    }
-    return true;
+  kill(id, reason = "killed by ShellKill") {
+    return this.meta.has(id) && this.jobs.kill(id, reason);
   }
   killAll() {
-    for (const id of this.jobs.keys()) this.kill(id);
+    for (const id of this.meta.keys()) this.jobs.kill(id, "agent exiting");
   }
 };
+var shellStatus = (s) => s === "done" ? "exited" : s === "running" ? "running" : s === "killed" ? "killed" : "error";
 function makeRealShellTool(options) {
   const defaultTimeoutMs = options.timeoutMs ?? 12e4;
   const maxTimeoutMs = Math.max(options.maxTimeoutMs ?? 6e5, defaultTimeoutMs);
@@ -833,7 +1191,7 @@ function makeRealShellTool(options) {
           proc.stderr?.on("data", collect);
           proc.on("error", (err) => {
             if (err?.name === "AbortError" || ctl.signal.aborted) return finish(reasonFor(timedOut, timeoutMs, clean(out)));
-            log5.debug("shell spawn error", err);
+            log6.debug("shell spawn error", err);
             finish(`[exit 1] ${err?.message ?? err}${out ? "\n" + clean(out) : ""}`);
           });
           proc.on("close", (code) => {
@@ -853,7 +1211,7 @@ function makeRealShellTool(options) {
   };
 }
 function handoffFor(timeoutMs, id, body, notifies) {
-  const head = `[still running] exceeded ${timeoutMs}ms, so it was handed to background job ${id} \u2014 NOT killed, it is still going. Check on it with ShellOutput({id:"${id}"}) / ShellStatus({id:"${id}"}), stop it with ShellKill({id:"${id}"}). ` + (notifies ? "Its completion will be reported to you, so you may continue with other work meanwhile." : "Nothing will tell you when it finishes \u2014 poll it yourself before you rely on its result.");
+  const head = `[still running] exceeded ${timeoutMs}ms, so it was handed to background job ${id} \u2014 NOT killed, it is still going (it is only stopped if it goes silent with no CPU activity for a long time, and then you are told why). Check on it with ShellOutput({id:"${id}"}) / ShellStatus({id:"${id}"}), stop it with ShellKill({id:"${id}"}). ` + (notifies ? "Its completion will be reported to you, so you may continue with other work meanwhile." : "Nothing will tell you when it finishes \u2014 poll it yourself before you rely on its result.");
   return body ? `${head}
 Output so far:
 ${body}` : head;
@@ -878,7 +1236,7 @@ function makeShellJobTools(registry) {
         const out = registry.output(String(id));
         if (out == null) return NO_JOB(String(id));
         const st = registry.status(String(id));
-        return `[${st.status}${st.exitCode != null ? ` exit ${st.exitCode}` : ""}]
+        return `[${st.status}${st.exitCode != null ? ` exit ${st.exitCode}` : ""}${st.reason ? `: ${st.reason}` : ""}]
 ${clean(out) || "(no output yet)"}`;
       }
     },
@@ -893,13 +1251,13 @@ ${clean(out) || "(no output yet)"}`;
           return jobs.length ? jobs.map((j) => `${j.id}  ${j.status}  ${j.command}`).join("\n") : "(no background jobs)";
         }
         const st = registry.status(String(id));
-        return st ? `${st.status}${st.exitCode != null ? ` (exit ${st.exitCode})` : ""} \xB7 ${st.bytes} byte(s) buffered` : NO_JOB(String(id));
+        return st ? `${st.status}${st.exitCode != null ? ` (exit ${st.exitCode})` : ""}${st.reason ? ` \u2014 ${st.reason}` : ""} \xB7 ${st.bytes} byte(s) buffered` : NO_JOB(String(id));
       }
     },
     {
       ...dropOnRebind,
       name: "ShellKill",
-      description: "Stop a running background Shell job by id (SIGTERM).",
+      description: "Stop a running background Shell job by id (SIGTERM to its process group, SIGKILL if it ignores that).",
       parameters: { type: "object", required: ["id"], properties: { id: { type: "string" } } },
       async run({ id }) {
         return registry.kill(String(id)) ? `Killed job ${id}.` : NO_JOB(String(id));
@@ -911,6 +1269,9 @@ export {
   ShellJobRegistry,
   formatJobExit,
   makeRealShellTool,
-  makeShellJobTools
+  makeShellJobTools,
+  parsePsTime,
+  psGroupCpuSeconds,
+  sumTreeCpu
 };
 //# sourceMappingURL=tools.shell.js.map