@epoch-agent/plugin-terminal 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,25 +1,37 @@
 // src/index.ts
-import { isAbsolute, resolve } from "path";
-import {
-  checkDangerousCommand,
-  isInWorkspace,
-  sandboxModeForLevel
-} from "@epoch-agent/infra";
-
+import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+import { checkDangerousCommand as checkDangerousCommand2, isInWorkspace as isInWorkspace2 } from "@epoch-agent/infra";
 // src/background.ts
 import {
   artifactsDir,
+  clearAllJobs,
+  getJob,
+  jobDetail,
   killTrackedProcess,
-  openArtifact,
+  listJobs,
+  processTableFor,
+  readJob,
+  registerJob,
+  rekeyJobs,
   shellSpawnArgs,
-  startLongLivedProcess
+  stopJob,
+  waitJob
 } from "@epoch-agent/infra";
-
 // src/sandbox.ts
 import {
   classifyFailure,
-  confine
+  confine,
+  sandboxModeForLevel
 } from "@epoch-agent/infra";
+function sandboxPolicyFor(ctx, workspaceRoot) {
+  return {
+    mode: sandboxModeForLevel(ctx.permissionLevel),
+    workspaceRoot,
+    ...ctx.extraRoots ? { extraRoots: ctx.extraRoots } : {},
+    allowNetwork: true,
+    enabled: ctx.sandboxTerminal !== false
+  };
+}
 function unconfined(skipped) {
   return { mode: null, backend: "none", enforcement: null, skipped, failure: null };
 }
@@ -64,203 +76,232 @@ function confineShell(sh, policy, cwd) {
     })
   };
 }
-
 // src/background.ts
 var MAX_TASKS = 8;
 var MAX_TASK_OUTPUT = 256 * 1024;
 var MAX_OUTPUT_CHUNK = 8 * 1024;
-var bySession = /* @__PURE__ */ new Map();
-var counter = 0;
-function nextId() {
-  counter += 1;
-  return `t${counter}`;
-}
-function bucketOf(sessionId) {
-  const existing = bySession.get(sessionId);
-  if (existing) return existing;
-  const fresh = /* @__PURE__ */ new Map();
-  bySession.set(sessionId, fresh);
-  return fresh;
-}
-function taskIn(sessionId, id) {
-  return bySession.get(sessionId)?.get(id);
-}
 function startTask(sessionId, command, cwd, homeDir, sandbox) {
-  const bucket = bucketOf(sessionId);
-  const running = [...bucket.values()].filter((t) => t.status === "running");
+  const running = listJobs(sessionId, "command").filter((j) => j.status === "running");
   if (running.length >= MAX_TASKS) {
-    const list = running.map((t) => `${t.id} (${t.command})`).join("\u3001");
+    const list = running.map((j) => `${j.id} (${j.label})`).join("\u3001");
     return {
       error: `\u540E\u53F0\u4EFB\u52A1\u5DF2\u8FBE\u4E0A\u9650 ${MAX_TASKS} \u4E2A\uFF0C\u5148\u7528 task_stop \u505C\u6389\u4E00\u4E2A\u3002\u5728\u8DD1\u7684\uFF1A${list}`
     };
   }
-  const id = nextId();
-  let finish;
-  const done2 = new Promise((resolve2) => {
-    finish = resolve2;
-  });
   const raw = shellSpawnArgs(command);
   const sh = confineShell({ file: raw.file, args: raw.args }, sandbox, cwd);
-  const task = {
-    id,
-    command,
+  let pid = 0;
+  const job = registerJob({
+    sessionId,
+    kind: "command",
+    label: command,
     ...cwd ? { cwd } : {},
-    pid: 0,
-    status: "running",
-    startedAt: Date.now(),
-    buffer: "",
-    totalBytes: 0,
-    droppedBytes: 0,
+    maxOutput: MAX_TASK_OUTPUT,
     artifactsDir: artifactsDir(sessionId, homeDir),
-    sandbox: sh.outcome,
-    done: done2,
-    finish
-  };
-  bucket.set(id, task);
-  const started = startLongLivedProcess({
+    artifactLabel: "task",
+    stop: () => killTrackedProcess(pid),
+    terminates: true,
+    detail: { sandbox: sh.outcome }
+  });
+  const started = processTableFor(sessionId).start({
     file: sh.file,
     args: sh.args,
     ...cwd ? { cwd } : {},
     ...raw.options ? { spawnOptions: raw.options } : {},
-    onOutput: (chunk) => append(task, chunk),
+    onOutput: (chunk) => job.append(chunk),
     onExit: (code) => {
-      if (task.status === "running") {
-        task.status = code === null ? "failed" : "exited";
-        if (code !== null) task.exitCode = code;
-      }
-      task.endedAt = Date.now();
-      if (task.status === "exited" && code !== null && code !== 0) {
-        task.sandbox = sh.classify(code, task.buffer);
+      const status = code === null ? "failed" : "exited";
+      if (job.status() === "running" && status === "exited" && code !== null && code !== 0) {
+        job.detail.sandbox = sh.classify(code, bufferOf(sessionId, job.id));
       }
-      task.spill?.close();
-      task.finish();
+      job.finish(status, code ?? void 0);
     }
   });
-  task.pid = started.pid;
-  return { task: toInfo(task), sandbox: sh.outcome };
+  pid = started.pid;
+  job.setPid(pid);
+  return { task: toInfo(job.info()), sandbox: sh.outcome };
+}
+function bufferOf(sessionId, id) {
+  return readJob(sessionId, id, 0, MAX_TASK_OUTPUT)?.output ?? "";
 }
 function taskSandbox(sessionId, id) {
-  return taskIn(sessionId, id)?.sandbox;
-}
-function append(task, chunk) {
-  task.totalBytes += chunk.length;
-  task.buffer += chunk;
-  if (task.buffer.length <= MAX_TASK_OUTPUT) return;
-  if (task.spill === void 0) {
-    task.spill = openArtifact(task.artifactsDir, `task-${task.id}`, ".txt") ?? null;
-    task.spill?.append(task.buffer);
-  } else {
-    task.spill?.append(chunk);
-  }
-  const drop = task.buffer.length - MAX_TASK_OUTPUT;
-  task.buffer = task.buffer.slice(drop);
-  task.droppedBytes += drop;
+  return jobDetail(sessionId, id)?.sandbox;
 }
 function listTasks(sessionId) {
-  const bucket = bySession.get(sessionId);
-  return bucket ? [...bucket.values()].map(toInfo) : [];
+  return listJobs(sessionId).map(toInfo);
+}
+function commandJob(sessionId, id) {
+  const info = getJob(sessionId, id);
+  return info?.kind === "command" ? info : void 0;
 }
 function taskOutput(sessionId, id, since = 0) {
-  const task = taskIn(sessionId, id);
-  if (!task) return void 0;
-  const from = Math.max(since, task.droppedBytes);
-  const missed = Math.max(0, task.droppedBytes - since);
-  const slice = task.buffer.slice(from - task.droppedBytes);
-  const output = slice.slice(0, MAX_OUTPUT_CHUNK);
-  return {
-    info: toInfo(task),
-    output,
-    nextCursor: from + output.length,
-    missed,
-    hasMore: output.length < slice.length
-  };
+  if (!getJob(sessionId, id)) return void 0;
+  const read = readJob(sessionId, id, since, MAX_OUTPUT_CHUNK);
+  if (!read) return void 0;
+  return { ...read, info: toInfo(read.info) };
 }
-async function stopTask(sessionId, id) {
-  const task = taskIn(sessionId, id);
-  if (!task || task.status !== "running") return false;
-  task.status = "killed";
-  task.endedAt = Date.now();
-  await killTrackedProcess(task.pid);
-  task.spill?.close();
-  task.finish();
-  return true;
+function stopTask(sessionId, id) {
+  if (!commandJob(sessionId, id)) return Promise.resolve(false);
+  return stopJob(sessionId, id);
 }
 async function waitTask(sessionId, id, timeoutMs) {
-  const task = taskIn(sessionId, id);
-  if (!task) return void 0;
-  if (task.status !== "running") return { info: toInfo(task), timedOut: false };
-  let timer;
-  const timeout = new Promise((resolve2) => {
-    timer = setTimeout(() => resolve2("timeout"), timeoutMs);
-    timer.unref?.();
-  });
-  try {
-    const winner = await Promise.race([task.done.then(() => "done"), timeout]);
-    return { info: toInfo(task), timedOut: winner === "timeout" };
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
+  if (!commandJob(sessionId, id)) return void 0;
+  const result = await waitJob(sessionId, id, timeoutMs);
+  if (!result) return void 0;
+  return { info: toInfo(result.info), timedOut: result.timedOut };
 }
 function rekeyTasks(from, to) {
-  if (from === to) return;
-  const moving = bySession.get(from);
-  if (!moving) return;
-  bySession.delete(from);
-  const target = bySession.get(to);
-  if (!target) {
-    bySession.set(to, moving);
-    return;
-  }
-  for (const [id, task] of moving) target.set(id, task);
+  rekeyJobs(from, to, ["command"]);
 }
 function clearAllTasks() {
-  for (const bucket of bySession.values()) {
-    for (const task of bucket.values()) task.spill?.close();
-  }
-  bySession.clear();
-  counter = 0;
+  clearAllJobs(["command"]);
 }
-function toInfo(task) {
+function toInfo(info) {
   return {
-    id: task.id,
-    command: task.command,
-    ...task.cwd ? { cwd: task.cwd } : {},
-    pid: task.pid,
-    status: task.status,
-    ...task.exitCode === void 0 ? {} : { exitCode: task.exitCode },
-    startedAt: task.startedAt,
-    ...task.endedAt === void 0 ? {} : { endedAt: task.endedAt },
-    outputBytes: task.totalBytes,
-    truncated: task.droppedBytes > 0,
-    ...task.spill ? { artifact: task.spill.path } : {}
+    id: info.id,
+    kind: info.kind,
+    label: info.label,
+    ...info.kind === "command" ? { command: info.label } : {},
+    ...info.cwd ? { cwd: info.cwd } : {},
+    pid: info.pid,
+    status: taskStatus(info),
+    ...info.exitCode === void 0 ? {} : { exitCode: info.exitCode },
+    startedAt: info.startedAt,
+    ...info.endedAt === void 0 ? {} : { endedAt: info.endedAt },
+    outputBytes: info.outputBytes,
+    truncated: info.truncated,
+    ...info.artifact ? { artifact: info.artifact } : {}
   };
 }
+function taskStatus(info) {
+  return info.status;
+}
 function describeTask(info) {
   const dur = Math.round(((info.endedAt ?? Date.now()) - info.startedAt) / 1e3);
   const state = info.status === "running" ? `\u8FD0\u884C\u4E2D ${dur}s` : info.status === "exited" ? `\u5DF2\u7ED3\u675F\uFF0C\u9000\u51FA\u7801 ${info.exitCode}` : info.status === "killed" ? "\u5DF2\u505C\u6B62" : "\u542F\u52A8\u5931\u8D25";
   const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
   return `${info.id}  ${state}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09  ${info.command}`;
 }
-
 // src/exec.ts
 import { spawn } from "child_process";
 import {
   createStreamDecoder,
-  killAllTrackedProcesses,
-  killProcessTree as killProcessTree2,
+  killProcessTree,
+  processFallbackTable,
   shellSpawnArgs as shellSpawnArgs2
 } from "@epoch-agent/infra";
-
 // src/limits.ts
 var MAX_CAPTURE_BYTES = 10 * 1024 * 1024;
 var OVER_CAPTURE_NOTICE = `
 [\u8F93\u51FA\u8D85\u8FC7 ${MAX_CAPTURE_BYTES / 1024 / 1024} MB\uFF0C\u5DF2\u622A\u65AD\u5E76\u7EC8\u6B62\u8FDB\u7A0B\uFF1A\u8FD9\u4E0D\u662F\u4E00\u6B21\u6B63\u5E38\u7684\u547D\u4EE4\u8F93\u51FA\uFF08\u591A\u534A\u662F cat \u4E86\u4E8C\u8FDB\u5236\u6587\u4EF6\u6216\u8FDB\u4E86\u6B7B\u5FAA\u73AF\uFF09\u3002\u8BF7\u7F29\u5C0F\u8F93\u51FA\u8303\u56F4\u91CD\u8BD5\uFF0C\u6BD4\u5982\u52A0 head / tail / grep\u3002]`;
 var NO_OUTPUT = "(\u65E0\u8F93\u51FA)";
-
+// src/exec.ts
+var FORCE_SETTLE_MS = 3e3;
+function killChildTree(child) {
+  void killProcessTree({
+    pid: child.pid ?? 0,
+    detached: false,
+    escalate: true,
+    isExited: () => child.exitCode !== null || child.signalCode !== null
+  });
+}
+function collectStreams(child, onOverflow, onOutput) {
+  let stdout = "";
+  let stderr = "";
+  let truncated = false;
+  const outDecoder = createStreamDecoder();
+  const errDecoder = createStreamDecoder();
+  child.stdout?.on("data", (chunk) => {
+    if (truncated) return;
+    const piece = outDecoder.write(chunk);
+    if (piece) {
+      stdout += piece;
+      onOutput?.(piece);
+    }
+    if (stdout.length > MAX_CAPTURE_BYTES) {
+      truncated = true;
+      stdout = stdout.slice(0, MAX_CAPTURE_BYTES);
+      onOverflow();
+    }
+  });
+  child.stderr?.on("data", (chunk) => {
+    if (stderr.length >= MAX_CAPTURE_BYTES) return;
+    const piece = errDecoder.write(chunk);
+    if (!piece) return;
+    stderr += piece;
+    onOutput?.(piece);
+  });
+  return () => {
+    if (!truncated) stdout += outDecoder.end();
+    if (stderr.length < MAX_CAPTURE_BYTES) stderr += errDecoder.end();
+    const tail = truncated ? OVER_CAPTURE_NOTICE : "";
+    return { stdout: (stdout + tail).trimEnd(), stderr: stderr.trimEnd() };
+  };
+}
+function runCommand(command, options) {
+  return new Promise((resolve3, reject) => {
+    const raw = shellSpawnArgs2(command);
+    const sh = confineShell({ file: raw.file, args: raw.args }, options.sandbox, options.cwd);
+    const child = spawn(sh.file, sh.args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      cwd: options.cwd,
+      ...raw.options
+    });
+    let killedBy = null;
+    let settled = false;
+    let forceTimer;
+    const drain = collectStreams(child, () => kill("overflow"), options.onOutput);
+    const timer = setTimeout(() => kill("timeout"), options.timeout);
+    const abortCheck = setInterval(() => {
+      if (options.signal?.aborted) kill("abort");
+    }, 100);
+    function clearTimers() {
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      clearInterval(abortCheck);
+    }
+    function finish() {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      const { stdout, stderr } = drain();
+      const exitCode = child.exitCode ?? -1;
+      resolve3({
+        stdout,
+        stderr,
+        exitCode,
+        ...killedBy === "timeout" ? { timedOut: true } : {},
+        ...killedBy === "abort" ? { aborted: true } : {},
+        sandbox: killedBy ? sh.outcome : sh.classify(exitCode, stderr)
+      });
+    }
+    function kill(why) {
+      if (killedBy) return;
+      killedBy = why;
+      killChildTree(child);
+      forceTimer = setTimeout(finish, FORCE_SETTLE_MS);
+    }
+    if (options.signal?.aborted) kill("abort");
+    child.on("close", finish);
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      reject(err);
+    });
+  });
+}
+async function cleanupBackgroundProcesses(table) {
+  await (table ?? processFallbackTable()).killAll();
+}
 // src/pty.ts
 import { spawn as spawnPty } from "node-pty";
-import { IS_WINDOWS, killProcessTree, shellPtyArgs } from "@epoch-agent/infra";
-
+import {
+  IS_WINDOWS,
+  killProcessTree as killProcessTree2,
+  processTableFor as processTableFor2,
+  shellPtyArgs
+} from "@epoch-agent/infra";
 // src/pty-helper.ts
 import { accessSync, chmodSync, constants, existsSync } from "fs";
 import { createRequire } from "module";
@@ -302,12 +343,24 @@ function ptyHelperHint() {
 node-pty \u7684 spawn-helper \u6CA1\u6709\u6267\u884C\u6743\u9650\uFF0C\u4E14\u81EA\u52A8\u4FEE\u590D\u5931\u8D25\uFF08${failure}\uFF09\u3002
 \u624B\u52A8\u4FEE\uFF1Achmod +x <\u4E0A\u9762\u8FD9\u4E2A\u8DEF\u5F84>`;
 }
-
 // src/pty.ts
 var PTY_IS_GROUP_LEADER = !IS_WINDOWS;
+function asKeystrokes(input) {
+  return IS_WINDOWS ? input.replaceAll(/\r?\n/g, "\r") : input;
+}
 var ptySessions = /* @__PURE__ */ new Map();
+var killing = /* @__PURE__ */ new WeakMap();
 function killPtyTree(pty) {
-  void killProcessTree({ pid: pty.pid, detached: PTY_IS_GROUP_LEADER, escalate: true, pty });
+  const started = killing.get(pty);
+  if (started) return started;
+  const running = killProcessTree2({
+    pid: pty.pid,
+    detached: PTY_IS_GROUP_LEADER,
+    escalate: true,
+    pty
+  });
+  killing.set(pty, running);
+  return running;
 }
 function confinePty(raw, policy, cwd) {
   if (!Array.isArray(raw.args)) {
@@ -318,10 +371,10 @@ function confinePty(raw, policy, cwd) {
   return { file: sh.file, args: sh.args, outcome: sh.outcome, classify: sh.classify };
 }
 function runCommandPty(command, options) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const previous = ptySessions.get(options.tag);
     if (previous) {
-      killPtyTree(previous);
+      void killPtyTree(previous);
       ptySessions.delete(options.tag);
     }
     const raw = shellPtyArgs(command);
@@ -337,7 +390,7 @@ function runCommandPty(command, options) {
         rows: 40
       });
     } catch (err) {
-      resolve2({
+      resolve3({
         stdout: `PTY \u542F\u52A8\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}${ptyHelperHint()}`,
         exitCode: 1,
         sandbox: sh.outcome
@@ -345,6 +398,10 @@ function runCommandPty(command, options) {
       return;
     }
     ptySessions.set(options.tag, pty);
+    const untrack = processTableFor2(options.sessionId).trackForeign(
+      pty.pid,
+      () => killPtyTree(pty)
+    );
     let output = "";
     let truncated = false;
     let settled = false;
@@ -357,21 +414,21 @@ function runCommandPty(command, options) {
       clearTimeout(timer);
       clearInterval(abortCheck);
       releaseSlot();
-      resolve2(result);
+      resolve3(result);
     };
     const timer = setTimeout(() => {
-      killPtyTree(pty);
+      void killPtyTree(pty);
       finish({ stdout: output.trimEnd() || "(\u8D85\u65F6\uFF0C\u65E0\u8F93\u51FA)", exitCode: -1, sandbox: sh.outcome });
     }, options.timeout);
     const abortCheck = setInterval(() => {
       if (!options.signal?.aborted) return;
-      killPtyTree(pty);
+      void killPtyTree(pty);
       finish({ stdout: output.trimEnd(), exitCode: -1, aborted: true, sandbox: sh.outcome });
     }, 100);
     if (options.stdin) {
       setTimeout(() => {
         try {
-          pty.write((options.stdin ?? "") + "\n");
+          pty.write(asKeystrokes((options.stdin ?? "") + "\n"));
         } catch {
         }
       }, 200);
@@ -383,136 +440,19 @@ function runCommandPty(command, options) {
       if (output.length > MAX_CAPTURE_BYTES) {
         truncated = true;
         output = output.slice(0, MAX_CAPTURE_BYTES) + OVER_CAPTURE_NOTICE;
-        killPtyTree(pty);
+        void killPtyTree(pty);
       }
     });
     pty.onExit(({ exitCode }) => {
+      untrack();
       finish({
         stdout: output.trimEnd() || NO_OUTPUT,
         exitCode,
-        // PTY 只有一股流，**没有独立的 stderr** —— 而拒绝方言和 runner
-        // 致命行都是 runner 往 stderr 打的。这里把整股流当 stderr 喂进去是
-        // 对的：那两组正则都锚在行首的后端自称上（`sandbox-exec:`），
-        // 混进来的 stdout 不会把它们撞出假阳性
         sandbox: sh.classify(exitCode, output)
       });
     });
   });
 }
-function killAllPtySessions() {
-  const pending = [];
-  for (const [tag, pty] of ptySessions) {
-    pending.push(
-      killProcessTree({ pid: pty.pid, detached: PTY_IS_GROUP_LEADER, escalate: true, pty })
-    );
-    ptySessions.delete(tag);
-  }
-  return pending;
-}
-
-// src/exec.ts
-var FORCE_SETTLE_MS = 3e3;
-function killChildTree(child) {
-  void killProcessTree2({
-    pid: child.pid ?? 0,
-    detached: false,
-    escalate: true,
-    isExited: () => child.exitCode !== null || child.signalCode !== null
-  });
-}
-function collectStreams(child, onOverflow, onOutput) {
-  let stdout = "";
-  let stderr = "";
-  let truncated = false;
-  const outDecoder = createStreamDecoder();
-  const errDecoder = createStreamDecoder();
-  child.stdout?.on("data", (chunk) => {
-    if (truncated) return;
-    const piece = outDecoder.write(chunk);
-    if (piece) {
-      stdout += piece;
-      onOutput?.(piece);
-    }
-    if (stdout.length > MAX_CAPTURE_BYTES) {
-      truncated = true;
-      stdout = stdout.slice(0, MAX_CAPTURE_BYTES);
-      onOverflow();
-    }
-  });
-  child.stderr?.on("data", (chunk) => {
-    if (stderr.length >= MAX_CAPTURE_BYTES) return;
-    const piece = errDecoder.write(chunk);
-    if (!piece) return;
-    stderr += piece;
-    onOutput?.(piece);
-  });
-  return () => {
-    if (!truncated) stdout += outDecoder.end();
-    if (stderr.length < MAX_CAPTURE_BYTES) stderr += errDecoder.end();
-    const tail = truncated ? OVER_CAPTURE_NOTICE : "";
-    return { stdout: (stdout + tail).trimEnd(), stderr: stderr.trimEnd() };
-  };
-}
-function runCommand(command, options) {
-  return new Promise((resolve2, reject) => {
-    const raw = shellSpawnArgs2(command);
-    const sh = confineShell({ file: raw.file, args: raw.args }, options.sandbox, options.cwd);
-    const child = spawn(sh.file, sh.args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      cwd: options.cwd,
-      ...raw.options
-    });
-    let killedBy = null;
-    let settled = false;
-    let forceTimer;
-    const drain = collectStreams(child, () => kill("overflow"), options.onOutput);
-    const timer = setTimeout(() => kill("timeout"), options.timeout);
-    const abortCheck = setInterval(() => {
-      if (options.signal?.aborted) kill("abort");
-    }, 100);
-    function clearTimers() {
-      clearTimeout(timer);
-      clearTimeout(forceTimer);
-      clearInterval(abortCheck);
-    }
-    function finish() {
-      if (settled) return;
-      settled = true;
-      clearTimers();
-      const { stdout, stderr } = drain();
-      const exitCode = child.exitCode ?? -1;
-      resolve2({
-        stdout,
-        stderr,
-        exitCode,
-        ...killedBy === "timeout" ? { timedOut: true } : {},
-        ...killedBy === "abort" ? { aborted: true } : {},
-        // 分类只在**我们没有主动杀它**的时候做：超时 / 中断的非零退出是我们
-        // 自己造成的，往分类器里送只会得到一句「命令自己失败了」的废话，
-        // 而调用方那边已经有 `timedOut` / `aborted` 两个更准确的字段
-        sandbox: killedBy ? sh.outcome : sh.classify(exitCode, stderr)
-      });
-    }
-    function kill(why) {
-      if (killedBy) return;
-      killedBy = why;
-      killChildTree(child);
-      forceTimer = setTimeout(finish, FORCE_SETTLE_MS);
-    }
-    if (options.signal?.aborted) kill("abort");
-    child.on("close", finish);
-    child.on("error", (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimers();
-      reject(err);
-    });
-  });
-}
-async function cleanupBackgroundProcesses() {
-  await Promise.all([killAllTrackedProcesses(), ...killAllPtySessions()]);
-}
-
 // src/sandbox-notice.ts
 var MODE_BOUNDARY = {
   "read-only": "\u53EA\u8BFB\uFF1A\u5199\u4EFB\u4F55\u6587\u4EF6\u90FD\u4F1A\u88AB OS \u6321\u4E0B",
@@ -521,6 +461,9 @@ var MODE_BOUNDARY = {
 };
 function sandboxNotice(sb) {
   if (sb.skipped === "not-requested") return "";
+  if (sb.skipped === "config-disabled") {
+    return "[\u6C99\u7BB1: \u5173] \u914D\u7F6E\u91CC sandbox.terminal \u662F false\uFF0C\u672C\u6B21\u6CA1\u6709 OS \u7EA7\u9694\u79BB\uFF0C\u547D\u4EE4\u80FD\u8BFB\u5199\u6574\u4E2A\u6587\u4EF6\u7CFB\u7EDF\u3002\u8FD9\u4E00\u6863\u548C\u6743\u9650\u6863\u4F4D\u65E0\u5173\uFF08\u5BA1\u6279\u7167\u65E7\uFF09\uFF0C\u5371\u9669\u547D\u4EE4\u8868\u4ECD\u7136\u5728\u5C97\u3002";
+  }
   if (sb.skipped === "mode-disabled") {
     return "[\u6C99\u7BB1: \u5173] \u5F53\u524D\u6743\u9650\u6863\u4F4D\u662F\u300C\u5141\u8BB8\u4E00\u5207\u300D\uFF0C\u672C\u6B21\u6CA1\u6709 OS \u7EA7\u9694\u79BB\u3002\u5371\u9669\u547D\u4EE4\u8868\u4ECD\u7136\u5728\u5C97\u3002";
   }
@@ -539,18 +482,26 @@ function sandboxError(sb) {
   if (failure2.kind === "runner-failed") {
     return {
       message: `\u6C99\u7BB1\u542F\u52A8\u5931\u8D25\uFF0C\u547D\u4EE4\u6CA1\u6709\u6267\u884C\uFF1A${failure2.evidence ?? "(\u6C99\u7BB1\u672A\u7ED9\u51FA\u539F\u56E0)"}`,
-      suggestion: "\u8FD9\u4E0D\u662F\u547D\u4EE4\u672C\u8EAB\u7684\u95EE\u9898\uFF0C\u522B\u6539\u547D\u4EE4\u3002\u628A\u8FD9\u6761\u539F\u6587\u62A5\u7ED9\u7528\u6237\uFF0C\u6216\u6362\u5230\u300C\u5141\u8BB8\u4E00\u5207\u300D\u6863\u4F4D\u7ED5\u5F00\u6C99\u7BB1\u3002"
+      suggestion: "\u8FD9\u4E0D\u662F\u547D\u4EE4\u672C\u8EAB\u7684\u95EE\u9898\uFF0C\u522B\u6539\u547D\u4EE4\u3002\u628A\u8FD9\u6761\u539F\u6587\u62A5\u7ED9\u7528\u6237 \u2014\u2014 \u8981\u7ED5\u5F00\u7684\u8BDD\uFF0C\u8BA9\u4ED6\u5728 config.yaml \u91CC\u5199 sandbox.terminal: false\uFF08\u53EA\u5173\u6C99\u7BB1\uFF0C\u5BA1\u6279\u4E0D\u52A8\uFF09\uFF0C\u522B\u529D\u4ED6\u5207\u300C\u5141\u8BB8\u4E00\u5207\u300D\u6863\u4F4D\u3002"
     };
   }
   if (failure2.kind === "sandbox-denied") {
     return {
       message: `\u547D\u4EE4\u88AB\u6C99\u7BB1\u6321\u4E0B\uFF1A${failure2.evidence ?? "(\u6C99\u7BB1\u672A\u7ED9\u51FA\u539F\u56E0)"}`,
-      suggestion: sb.mode === "read-only" ? "\u5F53\u524D\u662F\u53EA\u8BFB\u6863\u4F4D\uFF0C\u4EFB\u4F55\u5199\u5165\u90FD\u4F1A\u88AB\u6321\u3002\u8981\u771F\u7684\u6539\u4E1C\u897F\uFF0C\u5148\u8BF7\u7528\u6237\u5207\u6362\u6743\u9650\u6863\u4F4D\u3002" : "\u6C99\u7BB1\u53EA\u653E\u5F00\u5DE5\u4F5C\u533A\u3001\u4E34\u65F6\u76EE\u5F55\u548C\u5DE5\u5177\u94FE\u7F13\u5B58\u3002\u8981\u5199\u5230\u522B\u5904\uFF0C\u5148\u8BF7\u7528\u6237\u786E\u8BA4\u3002"
+      suggestion: sb.mode === "read-only" ? "\u5F53\u524D\u662F\u53EA\u8BFB\u6863\u4F4D\uFF0C\u4EFB\u4F55\u5199\u5165\u90FD\u4F1A\u88AB\u6321\u3002\u8981\u771F\u7684\u6539\u4E1C\u897F\uFF0C\u5148\u8BF7\u7528\u6237\u5207\u6362\u6743\u9650\u6863\u4F4D\u3002" : "\u6C99\u7BB1\u53EA\u653E\u5F00\u5DE5\u4F5C\u533A\u3001\u4E34\u65F6\u76EE\u5F55\u548C\u5DE5\u5177\u94FE\u7F13\u5B58\u3002\u8981\u5199\u5230\u522B\u5904\uFF0C\u5148\u8BF7\u7528\u6237\u786E\u8BA4\uFF1B\u5982\u679C\u88AB\u6321\u7684\u662F\u4E00\u6761\u672C\u6765\u8BE5\u80FD\u8DD1\u7684\u547D\u4EE4\uFF08\u6BD4\u5982\u67D0\u4E2A\u6CA1\u767B\u8BB0\u7684\u5DE5\u5177\u94FE\u7F13\u5B58\u76EE\u5F55\uFF09\uFF0C\u4ED6\u53EF\u4EE5\u5728 config.yaml \u91CC\u5199 sandbox.terminal: false \u6574\u4E2A\u5173\u6389\u3002"
     };
   }
   return null;
 }
-
+// src/shell/tools.ts
+import { isAbsolute, resolve } from "path";
+import { checkDangerousCommand, isInWorkspace, t } from "@epoch-agent/infra";
+// src/shell/limits.ts
+var MAX_SHELLS = 4;
+var MAX_SHELL_OUTPUT = 256 * 1024;
+var MAX_SHELL_CHUNK = 8 * 1024;
+var SHELL_IDLE_MS = 10 * 60 * 1e3;
+var SHELL_SWEEP_MS = 60 * 1e3;
 // src/spill.ts
 import { artifactsDir as artifactsDir2, headCodePoints, tailCodePoints, writeArtifact } from "@epoch-agent/infra";
 var PREVIEW_HEAD = 2e3;
@@ -587,48 +538,567 @@ function describeMissed(missed, locator) {
   const where = locator ? retrievalHint(locator) : NOT_STORED;
   return `\uFF08\u5F00\u5934 ${missed} \u5B57\u8282\u5DF2\u7ECF\u6EDA\u51FA\u73AF\u5F62\u7F13\u51B2\uFF09${where}`;
 }
-
-// src/tasks.ts
-var DEFAULT_WAIT_MS = 3e4;
-var MAX_WAIT_MS = 3e5;
+function describeMore(nextCursor) {
+  return `\uFF08\u8FD8\u6709\u66F4\u591A\uFF0C\u7528 since: ${nextCursor} \u7EE7\u7EED\u53D6\uFF09`;
+}
+// src/shell/notice.ts
+function stateOf(info) {
+  const alive = Math.round((Date.now() - info.startedAt) / 1e3);
+  switch (info.status) {
+    case "running": {
+      const idle = Math.round((Date.now() - info.lastActivity) / 1e3);
+      return `\u6D3B\u7740 ${alive}s\uFF08\u7A7A\u95F2 ${idle}s\uFF09`;
+    }
+    case "exited":
+      return `shell \u81EA\u5DF1\u9000\u4E86\uFF0C\u9000\u51FA\u7801 ${info.exitCode}`;
+    case "closed":
+      return "\u5DF2\u5173\u95ED";
+    case "reaped":
+      return `\u7A7A\u95F2\u8D85\u8FC7 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\uFF0C\u5DF2\u56DE\u6536`;
+  }
+}
+function describeShell(info) {
+  const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
+  return `${info.id}  ${stateOf(info)}  cwd=${info.cwd}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09`;
+}
+function openedNotice(info) {
+  return [
+    `\u6301\u4E45 shell \u4F1A\u8BDD ${info.id} \u5DF2\u5F00\uFF1A${info.shell}\uFF0C\u5DE5\u4F5C\u76EE\u5F55 ${info.cwd}`,
+    "shell_send \u53D1\u8F93\u5165\uFF08\u8BB0\u5F97\u81EA\u5DF1\u5E26 \\n\uFF09\xB7 shell_read \u589E\u91CF\u8BFB \xB7 shell_close \u5173\u6389 \xB7 shell_list \u770B\u5168\u90E8\u3002",
+    `\u6CE8\u610F\uFF1A\u4F1A\u8BDD\u6D3B\u4E0D\u8FC7 epoch \u8FDB\u7A0B\uFF0C\u9000\u51FA\u65F6\u4F1A\u88AB\u4E00\u8D77\u6536\u6389\uFF1B\u7A7A\u95F2 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\u4E5F\u4F1A\u88AB\u56DE\u6536\u3002`
+  ].join("\n");
+}
+function closedNotice(id) {
+  return `${id} \u5DF2\u5173\u95ED\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002`;
+}
+function alreadyGoneNotice(id) {
+  return `${id} \u5DF2\u7ECF\u4E0D\u5728\u8FD0\u884C\u4E2D\u4E86\u3002`;
+}
+var NO_SHELLS = "\u6CA1\u6709\u6301\u4E45 shell \u4F1A\u8BDD\u3002\u7528 shell_open \u5F00\u4E00\u4E2A\u3002";
+function listHead(count) {
+  return `${count} \u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\uFF08\u540C\u65F6\u6700\u591A ${MAX_SHELLS} \u4E2A\uFF09`;
+}
+var NO_NEW_OUTPUT = "\uFF08\u8FD9\u4E00\u6BB5\u6CA1\u6709\u65B0\u8F93\u51FA\u3002\u547D\u4EE4\u53EF\u80FD\u8FD8\u5728\u8DD1\uFF0C\u7B49\u4E00\u4F1A\u513F\u518D shell_read\uFF09";
+function writeFailedNotice(message) {
+  return `
+[\u5199\u5165\u5931\u8D25\uFF1A${message}]
+`;
+}
+function readNotice(result) {
+  const notes = [];
+  if (result.missed > 0) notes.push(describeMissed(result.missed, result.info.artifact));
+  if (result.hasMore) notes.push(describeMore(result.nextCursor));
+  return [
+    describeShell(result.info),
+    ...notes,
+    "",
+    result.output || NO_NEW_OUTPUT,
+    "",
+    `nextCursor: ${result.nextCursor}`
+  ].join("\n");
+}
+// src/shell/sessions.ts
+import { spawn as spawnPty2 } from "node-pty";
+import {
+  allJobs,
+  appendJob,
+  artifactsDir as artifactsDir3,
+  clearAllJobs as clearAllJobs2,
+  getDefaultShell,
+  getJob as getJob2,
+  IS_WINDOWS as IS_WINDOWS2,
+  jobDetail as jobDetail2,
+  listJobs as listJobs2,
+  processTableFor as processTableFor3,
+  readJob as readJob2,
+  registerJob as registerJob2,
+  stopJob as stopJob2,
+  touchJob
+} from "@epoch-agent/infra";
+var CSI_PREAMBLE = /^(?:\x1b\[[0-9;?]*[ -/]*[@-~])+/;
+var CONPTY_SIGNATURE = "\x1B[?9001h";
+function dropConPtyPreamble(chunk) {
+  if (!IS_WINDOWS2 || !chunk.startsWith(CONPTY_SIGNATURE)) return chunk;
+  return chunk.slice(chunk.match(CSI_PREAMBLE)?.[0].length ?? 0);
+}
+function toShellInfo(info, detail) {
+  return {
+    id: info.id,
+    pid: info.pid,
+    cwd: info.cwd ?? info.label,
+    shell: detail?.shell ?? "",
+    status: shellStatus(info.status),
+    ...info.exitCode === void 0 ? {} : { exitCode: info.exitCode },
+    startedAt: info.startedAt,
+    lastActivity: info.lastActivity,
+    outputBytes: info.outputBytes,
+    truncated: info.truncated,
+    ...info.artifact ? { artifact: info.artifact } : {}
+  };
+}
+function shellStatus(status) {
+  switch (status) {
+    case "running":
+    case "exited":
+    case "reaped":
+      return status;
+    default:
+      return "closed";
+  }
+}
+function shellIn(sessionId, id) {
+  const info = getJob2(sessionId, id);
+  if (!info || info.kind !== "shell") return void 0;
+  const detail = jobDetail2(sessionId, id);
+  return detail ? { info, detail } : void 0;
+}
+function toShellRead(read, detail) {
+  return { ...read, info: toShellInfo(read.info, detail) };
+}
+function openShell(sessionId, cwd, homeDir, sandbox) {
+  const running = listJobs2(sessionId, "shell").filter((s) => s.status === "running");
+  if (running.length >= MAX_SHELLS) {
+    return {
+      error: "limit",
+      limit: MAX_SHELLS,
+      running: running.map((info) => toShellInfo(info, jobDetail2(sessionId, info.id)))
+    };
+  }
+  const file = getDefaultShell();
+  const sh = confineShell({ file, args: [] }, sandbox, cwd);
+  let pty;
+  try {
+    ensurePtyHelperExecutable();
+    pty = spawnPty2(sh.file, sh.args, {
+      name: "xterm-256color",
+      cwd,
+      env: { ...process.env, TERM: "xterm-256color", FORCE_COLOR: "1" },
+      cols: 120,
+      rows: 40
+    });
+  } catch (err) {
+    return {
+      error: "spawn-failed",
+      message: err instanceof Error ? err.message : String(err),
+      hint: ptyHelperHint()
+    };
+  }
+  const detail = {
+    pty,
+    shell: file,
+    sandbox: sh.outcome,
+    fresh: true,
+    untrack: () => {
+    }
+  };
+  const job = registerJob2({
+    sessionId,
+    kind: "shell",
+    label: cwd,
+    cwd,
+    maxOutput: MAX_SHELL_OUTPUT,
+    artifactsDir: artifactsDir3(sessionId, homeDir),
+    artifactLabel: "shell",
+    stop: () => killPtyTree(pty),
+    stoppedStatus: "closed",
+    terminates: false,
+    detail
+  });
+  job.setPid(pty.pid);
+  detail.untrack = processTableFor3(sessionId).trackForeign(pty.pid, () => killPtyTree(pty));
+  armSweep();
+  pty.onData((chunk) => {
+    if (detail.fresh) {
+      detail.fresh = false;
+      job.append(dropConPtyPreamble(chunk));
+      return;
+    }
+    job.append(chunk);
+  });
+  pty.onExit(({ exitCode }) => {
+    job.finish("exited", exitCode);
+    afterEnd(detail);
+  });
+  return { shell: toShellInfo(job.info(), detail), sandbox: sh.outcome };
+}
+function afterEnd(detail) {
+  detail.untrack();
+  disarmSweepIfIdle();
+}
+async function sendToShell(sessionId, id, input, waitMs) {
+  sweepIdleShells();
+  const found = shellIn(sessionId, id);
+  if (!found) return {};
+  if (found.info.status !== "running") return { info: toShellInfo(found.info, found.detail) };
+  const cursor = found.info.outputBytes;
+  touchJob(sessionId, id);
+  try {
+    found.detail.pty.write(asKeystrokes(input));
+  } catch (err) {
+    appendJob(sessionId, id, writeFailedNotice(err instanceof Error ? err.message : String(err)));
+  }
+  await sleep(waitMs);
+  touchJob(sessionId, id);
+  const read = readJob2(sessionId, id, cursor, MAX_SHELL_CHUNK);
+  return read ? toShellRead(read, found.detail) : {};
+}
+function readShell(sessionId, id, since = 0) {
+  sweepIdleShells();
+  const found = shellIn(sessionId, id);
+  if (!found) return {};
+  touchJob(sessionId, id);
+  const read = readJob2(sessionId, id, since, MAX_SHELL_CHUNK);
+  return read ? toShellRead(read, found.detail) : {};
+}
+async function closeShell(sessionId, id) {
+  const found = shellIn(sessionId, id);
+  if (!found || found.info.status !== "running") return false;
+  const closed = await stopJob2(sessionId, id);
+  if (closed) afterEnd(found.detail);
+  return closed;
+}
+function listShells(sessionId) {
+  sweepIdleShells();
+  return listJobs2(sessionId, "shell").map(
+    (info) => toShellInfo(info, jobDetail2(sessionId, info.id))
+  );
+}
+function clearAllShells() {
+  for (const { sessionId, info } of allJobs("shell")) {
+    jobDetail2(sessionId, info.id)?.untrack();
+  }
+  clearAllJobs2(["shell"]);
+  clearInterval(sweepTimer);
+  sweepTimer = void 0;
+}
+var sweepTimer;
+function sweepIdleShells(now = Date.now()) {
+  const reaped = [];
+  for (const { sessionId, info } of allJobs("shell")) {
+    if (info.status !== "running") continue;
+    if (now - info.lastActivity < SHELL_IDLE_MS) continue;
+    const detail = jobDetail2(sessionId, info.id);
+    if (!detail) continue;
+    void stopJob2(sessionId, info.id, "reaped").then(() => afterEnd(detail));
+    reaped.push(toShellInfo({ ...info, status: "reaped" }, detail));
+  }
+  return reaped;
+}
+function armSweep() {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => void sweepIdleShells(), SHELL_SWEEP_MS);
+  sweepTimer.unref?.();
+}
+function disarmSweepIfIdle() {
+  if (allJobs("shell").some((j) => j.info.status === "running")) return;
+  clearInterval(sweepTimer);
+  sweepTimer = void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve3) => {
+    const timer = setTimeout(resolve3, ms);
+    timer.unref?.();
+  });
+}
+function shellSandbox(sessionId, id) {
+  return shellIn(sessionId, id)?.detail.sandbox;
+}
+// src/shell/tools.ts
+var DEFAULT_WAIT_MS = 2e3;
+var MAX_WAIT_MS = 3e4;
 function ok(output) {
   return { success: true, output, duration: 0 };
 }
-function notFound(id) {
+function fail(code, message, suggestion) {
   return {
     success: false,
     output: "",
-    error: {
-      code: 2101,
-      message: `\u6CA1\u6709\u7F16\u53F7\u4E3A ${id} \u7684\u540E\u53F0\u4EFB\u52A1`,
-      suggestion: "\u7528 task_list \u770B\u5F53\u524D\u6709\u54EA\u4E9B"
+    error: { code, message, ...suggestion ? { suggestion } : {} },
+    duration: 0
+  };
+}
+function notFound(id) {
+  return fail(2101, t("shell.not_found", { id }), t("shell.not_found_suggestion"));
+}
+function notRunning(info) {
+  if (info.status === "reaped") {
+    return fail(
+      2102,
+      t("shell.reaped", { id: info.id, minutes: SHELL_IDLE_MS / 6e4 }),
+      t("shell.reaped_suggestion")
+    );
+  }
+  return fail(2102, t("shell.not_running", { id: info.id }), t("shell.not_running_suggestion"));
+}
+function toolResultFor(id, result, ctx) {
+  if (!("output" in result)) {
+    return result.info ? notRunning(result.info) : notFound(id);
+  }
+  const sb = shellSandbox(ctx.sessionId, id);
+  const sbErr = sb ? sandboxError(sb) : null;
+  const body = readNotice(result);
+  return ok(sbErr ? `${body}
+${sbErr.message}
+${sbErr.suggestion}` : body);
+}
+var shellOpen = {
+  name: "shell_open",
+  description: `\u5F00\u4E00\u4E2A**\u6301\u4E45** shell \u4F1A\u8BDD\uFF08PTY\uFF09\uFF0C\u8FD4\u56DE\u4F1A\u8BDD id\u3002\u548C terminal \u7684\u533A\u522B\u662F\u5B83\u8DE8\u591A\u6B21\u5DE5\u5177\u8C03\u7528\u6D3B\u7740\uFF1Acd / export / source venv/bin/activate \u90FD\u4F1A\u7559\u5B58\uFF0CREPL \u8FDB\u53BB\u4E86\u8FD8\u80FD\u51FA\u6765\u3002\u9002\u5408\u300C\u5148\u6FC0\u6D3B\u73AF\u5883\u518D\u8DD1\u51E0\u6761\u547D\u4EE4\u300D\u300C\u591A\u8F6E\u4EA4\u4E92\u7684 npm init\u300D\u300CNode / Python REPL\u300D\u3002\u540C\u65F6\u6700\u591A ${MAX_SHELLS} \u4E2A\uFF1B\u7A7A\u95F2 ${SHELL_IDLE_MS / 6e4} \u5206\u949F\u4F1A\u88AB\u56DE\u6536\uFF1B**\u4F1A\u8BDD\u6D3B\u4E0D\u8FC7 epoch \u8FDB\u7A0B**\uFF08\u9000\u51FA\u65F6\u4E00\u8D77\u6536\u6389\uFF0C\u522B\u6307\u671B\u4E0B\u6B21\u8FD0\u884C\u8FD8\u5728\uFF09\u3002\u4E00\u6B21\u6027\u547D\u4EE4\u4ECD\u7136\u7528 terminal \u2014\u2014 \u90A3\u6761\u4E0D\u5FC5\u5F00\u4F1A\u8BDD\u3002`,
+  parameters: {
+    type: "object",
+    properties: {
+      workdir: {
+        type: "string",
+        description: "\u4F1A\u8BDD\u7684\u521D\u59CB\u5DE5\u4F5C\u76EE\u5F55\uFF08\u5FC5\u987B\u5728\u5DE5\u4F5C\u533A\u5185\uFF0C\u76F8\u5BF9\u8DEF\u5F84\u6309\u5DE5\u4F5C\u533A\u6839\u89E3\u6790\uFF09"
+      }
+    },
+    required: []
+  },
+  supportsParallel: false,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  operation: "command",
+  describeTarget: (args) => String(args["workdir"] ?? ""),
+  execute: (args, ctx) => {
+    const workdir = args["workdir"] ? String(args["workdir"]) : void 0;
+    const baseDir = ctx.workDir || process.cwd();
+    if (workdir && !isInWorkspace(workdir, baseDir, ctx.extraRoots)) {
+      return Promise.resolve(
+        fail(
+          2006,
+          t("shell.workdir_out_of_bounds", { workdir, root: baseDir }),
+          t("shell.workdir_suggestion")
+        )
+      );
+    }
+    const cwd = workdir ? resolveWorkdir(workdir, baseDir) : baseDir;
+    const opened = openShell(ctx.sessionId, cwd, ctx.homeDir, sandboxPolicyFor(ctx, baseDir));
+    if ("error" in opened) {
+      if (opened.error === "limit") {
+        const list = opened.running.map(describeShell).join("\n");
+        return Promise.resolve(
+          fail(
+            2006,
+            t("shell.limit_reached", { limit: opened.limit, list }),
+            t("shell.limit_suggestion")
+          )
+        );
+      }
+      return Promise.resolve(
+        fail(
+          2005,
+          t("shell.spawn_failed", { message: opened.message + opened.hint }),
+          t("shell.spawn_failed_suggestion")
+        )
+      );
+    }
+    const notice = sandboxNotice(opened.sandbox);
+    return Promise.resolve(
+      ok([...notice ? [notice] : [], openedNotice(opened.shell)].join("\n"))
+    );
+  }
+};
+function resolveWorkdir(workdir, baseDir) {
+  return isAbsolute(workdir) ? resolve(workdir) : resolve(baseDir, workdir);
+}
+var shellSend = {
+  name: "shell_send",
+  description: '\u5F80\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u91CC\u53D1\u8F93\u5165\uFF0C\u7B49 wait \u6BEB\u79D2\u4E4B\u540E\u628A\u8FD9\u6BB5\u65F6\u95F4\u7684\u8F93\u51FA\u4EA4\u56DE\u6765\u3002**\u6362\u884C\u8981\u81EA\u5DF1\u5E26**\uFF1Ainput \u662F\u9010\u5B57\u5199\u8FDB\u53BB\u7684\uFF0C"pwd" \u53EA\u662F\u628A\u4E09\u4E2A\u5B57\u7B26\u6253\u4E0A\u53BB\uFF0C"pwd\\n" \u624D\u4F1A\u6267\u884C\u3002Ctrl+C \u5C31\u662F\u53D1 "\\x03"\uFF08\u8FD9\u6BD4\u7ED9\u8FDB\u7A0B\u53D1\u4FE1\u53F7\u66F4\u51C6\uFF0C\u7528\u6237\u5728\u771F\u7EC8\u7AEF\u91CC\u6309\u7684\u6B63\u662F\u8FD9\u6761\u8DEF\uFF09\u3002\u8F93\u51FA\u6CA1\u7B49\u591F\u5C31\u518D\u7528 shell_read \u63A5\u7740\u53D6\uFF08\u6E38\u6807\u63A5\u4E0A\u6B21\u7684 nextCursor\uFF09\u3002\u53D1\u8FDB\u53BB\u7684\u5185\u5BB9**\u548C terminal \u8D70\u540C\u4E00\u6761\u5371\u9669\u547D\u4EE4\u8868\u548C\u6743\u9650\u5224\u5B9A** \u2014\u2014 \u6301\u4E45\u4F1A\u8BDD\u4E0D\u662F\u65C1\u8DEF\u3002',
+  parameters: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "\u4F1A\u8BDD id\uFF0C\u4F8B\u5982 s1" },
+      input: { type: "string", description: "\u9010\u5B57\u5199\u8FDB\u4F1A\u8BDD\u7684\u8F93\u5165\uFF0C\u901A\u5E38\u8981\u4EE5 \\n \u7ED3\u5C3E" },
+      wait: {
+        type: "number",
+        description: `\u7B49\u591A\u4E45\u518D\u8FD4\u56DE\u8F93\u51FA\uFF08\u6BEB\u79D2\uFF0C\u9ED8\u8BA4 ${DEFAULT_WAIT_MS}\uFF0C\u6700\u5927 ${MAX_WAIT_MS}\uFF09`
+      }
+    },
+    required: ["id", "input"]
+  },
+  supportsParallel: false,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  },
+  operation: "command",
+  describeTarget: (args) => String(args["input"] ?? ""),
+  execute: async (args, ctx) => {
+    const id = String(args["id"] ?? "");
+    const input = String(args["input"] ?? "");
+    if (!input) return fail(2004, t("shell.empty_input"), t("shell.empty_input_suggestion"));
+    const danger = checkDangerousCommand(input);
+    if (danger.dangerous) {
+      return fail(
+        2003,
+        t("shell.dangerous", { desc: danger.desc ?? "" }),
+        t("shell.dangerous_suggestion", { input: input.trim() })
+      );
+    }
+    const requested = Number(args["wait"]);
+    const wait = Math.min(
+      Number.isFinite(requested) && requested >= 0 ? requested : DEFAULT_WAIT_MS,
+      MAX_WAIT_MS
+    );
+    return toolResultFor(id, await sendToShell(ctx.sessionId, id, input, wait), ctx);
+  }
+};
+var shellRead = {
+  name: "shell_read",
+  description: `\u589E\u91CF\u8BFB\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u7684\u8F93\u51FA\u3002\u53C2\u6570: id(\u5FC5\u586B), since(\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF0C\u53EA\u53D6\u65B0\u589E\u90E8\u5206)\u3002\u5355\u6B21\u6700\u591A ${MAX_SHELL_CHUNK} \u5B57\u8282\uFF0C\u8F93\u51FA\u5F88\u957F\u65F6\u5206\u6B21\u53D6\uFF1B\u4F1A\u8BDD\u4E0D\u5728\u8DD1\u4E86\u4E5F\u8BFB\u5F97\u5230\uFF08\u7F13\u51B2\u91CC\u90A3\u6BB5\u8F93\u51FA\u8FD8\u5728\uFF09\uFF0C\u6D3B\u4E0D\u6D3B\u7740\u770B\u56DE\u6267\u7B2C\u4E00\u884C\u3002`,
+  parameters: {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "\u4F1A\u8BDD id\uFF0C\u4F8B\u5982 s1" },
+      since: { type: "number", description: "\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF1B\u4E0D\u7ED9\u5C31\u4ECE\u5934\u53D6" }
     },
+    required: ["id"]
+  },
+  annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+  operation: "file_read",
+  describeTarget: (args) => String(args["id"] ?? ""),
+  execute: (args, ctx) => {
+    const id = String(args["id"] ?? "");
+    const since = Number(args["since"]);
+    const result = readShell(ctx.sessionId, id, Number.isFinite(since) && since > 0 ? since : 0);
+    return Promise.resolve(toolResultFor(id, result, ctx));
+  }
+};
+var shellClose = {
+  name: "shell_close",
+  description: "\u5173\u6389\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\uFF08\u6740\u6574\u68F5\u8FDB\u7A0B\u6811\uFF0C\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B)\u3002\u540D\u989D\u6EE1\u4E86\u3001\u6216\u8005\u8FD9\u4E2A\u73AF\u5883\u4E0D\u518D\u9700\u8981\u4E86\u5C31\u5173\u6389 \u2014\u2014 \u4F1A\u8BDD\u6D3B\u7740\u5C31\u4E00\u76F4\u5360\u4E00\u4E2A\u540D\u989D\u3002",
+  parameters: {
+    type: "object",
+    properties: { id: { type: "string", description: "\u4F1A\u8BDD id" } },
+    required: ["id"]
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  operation: "file_read",
+  describeTarget: (args) => String(args["id"] ?? ""),
+  execute: async (args, ctx) => {
+    const id = String(args["id"] ?? "");
+    if (await closeShell(ctx.sessionId, id)) return ok(closedNotice(id));
+    const exists = listShells(ctx.sessionId).some((s) => s.id === id);
+    return exists ? ok(alreadyGoneNotice(id)) : notFound(id);
+  }
+};
+var shellList = {
+  name: "shell_list",
+  description: "\u5217\u51FA\u672C\u6B21\u4F1A\u8BDD\u5F00\u8FC7\u7684\u6301\u4E45 shell \u4F1A\u8BDD\uFF1Aid\u3001\u5DE5\u4F5C\u76EE\u5F55\u3001\u6D3B\u4E86\u591A\u4E45\u3001\u7A7A\u95F2\u591A\u4E45\u3001\u8F93\u51FA\u5B57\u8282\u6570\u3002\u4E0D\u786E\u5B9A\u624B\u91CC\u6709\u54EA\u4E9B\u4F1A\u8BDD\u3001\u6216\u8005\u649E\u4E0A\u540D\u989D\u4E0A\u9650\u65F6\u5148\u770B\u8FD9\u4E2A\u3002",
+  parameters: { type: "object", properties: {}, required: [] },
+  annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
+  operation: "file_read",
+  execute: (_args, ctx) => {
+    const shells = listShells(ctx.sessionId);
+    if (shells.length === 0) return Promise.resolve(ok(NO_SHELLS));
+    return Promise.resolve(ok([listHead(shells.length), ...shells.map(describeShell)].join("\n")));
+  }
+};
+var SHELL_TOOLS = [
+  shellOpen,
+  shellSend,
+  shellRead,
+  shellClose,
+  shellList
+];
+// src/tasks.ts
+import { getJob as getJob3, listJobs as listJobs3, readJob as readJob3, stopJob as stopJob3, waitJob as waitJob2 } from "@epoch-agent/infra";
+// src/job-notice.ts
+var KIND_MARK = {
+  command: "\u547D\u4EE4",
+  shell: "\u4F1A\u8BDD",
+  agent: "\u5B50 agent"
+};
+function stateOf2(status, exitCode, seconds) {
+  switch (status) {
+    case "running":
+      return `\u8FD0\u884C\u4E2D ${seconds}s`;
+    case "exited":
+      return `\u5DF2\u7ED3\u675F\uFF0C\u9000\u51FA\u7801 ${exitCode}`;
+    case "killed":
+      return "\u5DF2\u505C\u6B62";
+    case "closed":
+      return "\u5DF2\u5173\u95ED";
+    case "reaped":
+      return "\u7A7A\u95F2\u5DF2\u88AB\u56DE\u6536";
+    case "failed":
+      return "\u542F\u52A8\u5931\u8D25";
+  }
+}
+function describeJob(info) {
+  const dur = Math.round(((info.endedAt ?? Date.now()) - info.startedAt) / 1e3);
+  const trunc = info.truncated ? "\uFF0C\u5F00\u5934\u5DF2\u6EDA\u51FA\u7F13\u51B2" : "";
+  return `${info.id}  [${KIND_MARK[info.kind]}] ${stateOf2(info.status, info.exitCode, dur)}\uFF08${info.outputBytes} \u5B57\u8282\u8F93\u51FA${trunc}\uFF09  ${info.label}`;
+}
+var NO_JOBS = "\u6CA1\u6709\u540E\u53F0\u4F5C\u4E1A\u3002\u7528 terminal \u7684 background: true \u8D77\u4E00\u6761\u540E\u53F0\u547D\u4EE4\uFF0C\u6216\u8005 shell_open \u5F00\u4E00\u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\u3002";
+function listHead2(count) {
+  return `${count} \u4E2A\u540E\u53F0\u4F5C\u4E1A\uFF08\u540E\u53F0\u547D\u4EE4 + \u6301\u4E45 shell \u4F1A\u8BDD\uFF0C\u4E00\u8D77\u5217\uFF09`;
+}
+function notFoundNotice(id) {
+  return `\u6CA1\u6709\u7F16\u53F7\u4E3A ${id} \u7684\u540E\u53F0\u4F5C\u4E1A`;
+}
+var NOT_FOUND_SUGGESTION = "\u7528 task_list \u770B\u5F53\u524D\u6709\u54EA\u4E9B\uFF08\u540E\u53F0\u547D\u4EE4\u548C\u6301\u4E45\u4F1A\u8BDD\u90FD\u5728\u91CC\u9762\uFF09";
+var NO_NEW_OUTPUT2 = "\uFF08\u8FD9\u4E00\u6BB5\u6CA1\u6709\u65B0\u8F93\u51FA\uFF09";
+function waitTimedOutNotice(seconds) {
+  return `
+\u7B49\u4E86 ${seconds}s \u8FD8\u6CA1\u7ED3\u675F\uFF0C**\u6CA1\u6709\u505C\u5B83**\u3002\u53EF\u4EE5\u63A5\u7740\u5E72\u522B\u7684\uFF0C\u6216\u518D\u7B49\u4E00\u6B21\u3002`;
+}
+var WAIT_DONE = "\n\u7528 task_output \u53D6\u8F93\u51FA\u3002";
+function neverEndsNotice(id) {
+  return `
+${id} \u662F\u4E00\u4E2A\u6301\u4E45 shell \u4F1A\u8BDD\uFF0C\u5B83\u6CA1\u6709\u300C\u7ED3\u675F\u300D\u8FD9\u4E2A\u72B6\u6001 \u2014\u2014 \u4E00\u76F4\u7B49\u4E0B\u53BB\u4E5F\u4E0D\u4F1A\u6709\u7ED3\u679C\u3002
+\u8981\u770B\u5B83\u73B0\u5728\u7684\u8F93\u51FA\u7528 shell_read({ id: '${id}' })\uFF0C\u8981\u53D1\u4E0B\u4E00\u53E5\u7528 shell_send\uFF0C\u8981\u6536\u6389\u5B83\u7528 shell_close \u6216 task_stop\u3002`;
+}
+function stoppedNotice(id, kind) {
+  return kind === "shell" ? `${id} \u5DF2\u5173\u95ED\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u90A3\u4E2A\u4F1A\u8BDD\u91CC\u7684\u73AF\u5883\uFF08cd / venv / REPL\uFF09\u6CA1\u4E86\uFF0C\u8981\u7528\u5F97\u91CD\u5F00\u4E00\u4E2A\u3002` : `${id} \u5DF2\u505C\u6B62\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002`;
+}
+function alreadyStoppedNotice(id) {
+  return `${id} \u5DF2\u7ECF\u4E0D\u5728\u8FD0\u884C\u4E2D\u4E86\u3002`;
+}
+// src/jobs.ts
+import { jobDetail as jobDetail3 } from "@epoch-agent/infra";
+function jobSandbox(sessionId, id) {
+  return jobDetail3(sessionId, id)?.sandbox;
+}
+// src/tasks.ts
+var DEFAULT_WAIT_MS2 = 3e4;
+var MAX_WAIT_MS2 = 3e5;
+function ok2(output) {
+  return { success: true, output, duration: 0 };
+}
+function notFound2(id) {
+  return {
+    success: false,
+    output: "",
+    error: { code: 2101, message: notFoundNotice(id), suggestion: NOT_FOUND_SUGGESTION },
     duration: 0
   };
 }
 var taskList = {
   name: "task_list",
-  description: "\u5217\u51FA\u672C\u6B21\u4F1A\u8BDD\u8D77\u8FC7\u7684\u540E\u53F0\u4EFB\u52A1\uFF08terminal \u7684 background: true \u8D77\u7684\uFF09\uFF0C\u542B\u72B6\u6001\u3001\u9000\u51FA\u7801\u3001\u8F93\u51FA\u5B57\u8282\u6570\u3002",
+  description: "\u5217\u51FA\u672C\u6B21\u4F1A\u8BDD\u8D77\u8FC7\u7684**\u540E\u53F0\u4F5C\u4E1A** \u2014\u2014 terminal \u7684 background: true \u8D77\u7684\u540E\u53F0\u547D\u4EE4\uFF0C\u548C shell_open \u5F00\u7684\u6301\u4E45 shell \u4F1A\u8BDD\uFF0C\u4E24\u79CD\u4E00\u8D77\u5217\uFF0C\u6BCF\u884C\u6807\u51FA\u662F\u54EA\u4E00\u79CD\uFF08[\u547D\u4EE4] / [\u4F1A\u8BDD]\uFF09\u3002\u542B\u72B6\u6001\u3001\u9000\u51FA\u7801\u3001\u8F93\u51FA\u5B57\u8282\u6570\u3002\u4E0D\u786E\u5B9A\u624B\u91CC\u6709\u4EC0\u4E48\u5728\u8DD1\u5C31\u5148\u770B\u8FD9\u4E2A\u3002",
   parameters: { type: "object", properties: {}, required: [] },
   annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
   operation: "file_read",
   execute: (_args, ctx) => {
-    const tasks = listTasks(ctx.sessionId);
-    if (tasks.length === 0) {
-      return Promise.resolve(ok("\u6CA1\u6709\u540E\u53F0\u4EFB\u52A1\u3002\u7528 terminal \u7684 background: true \u8D77\u4E00\u4E2A\u3002"));
-    }
-    return Promise.resolve(
-      ok([`${tasks.length} \u4E2A\u540E\u53F0\u4EFB\u52A1`, ...tasks.map(describeTask)].join("\n"))
-    );
+    const jobs = listJobs3(ctx.sessionId);
+    if (jobs.length === 0) return Promise.resolve(ok2(NO_JOBS));
+    return Promise.resolve(ok2([listHead2(jobs.length), ...jobs.map(describeJob)].join("\n")));
   }
 };
 var taskOutputTool = {
   name: "task_output",
-  description: `\u53D6\u4E00\u4E2A\u540E\u53F0\u4EFB\u52A1\u7684\u8F93\u51FA\u3002\u53C2\u6570: id(\u5FC5\u586B), since(\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF0C\u7528\u6765\u53EA\u53D6\u65B0\u589E\u90E8\u5206)\u3002\u5355\u6B21\u6700\u591A ${MAX_OUTPUT_CHUNK} \u5B57\u8282\uFF1B\u8F93\u51FA\u5F88\u957F\u65F6\u4F1A\u5206\u6B21\u53D6\uFF0C\u8FD4\u56DE\u91CC\u4F1A\u8BF4\u660E\u8FD8\u6709\u6CA1\u6709\u66F4\u591A\u3002`,
+  description: `\u53D6\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\u7684\u8F93\u51FA\uFF08\u540E\u53F0\u547D\u4EE4 t1 \u548C\u6301\u4E45\u4F1A\u8BDD s1 \u90FD\u884C\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B), since(\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF0C\u7528\u6765\u53EA\u53D6\u65B0\u589E\u90E8\u5206)\u3002\u5355\u6B21\u6700\u591A ${MAX_OUTPUT_CHUNK} \u5B57\u8282\uFF1B\u8F93\u51FA\u5F88\u957F\u65F6\u4F1A\u5206\u6B21\u53D6\uFF0C\u8FD4\u56DE\u91CC\u4F1A\u8BF4\u660E\u8FD8\u6709\u6CA1\u6709\u66F4\u591A\u3002`,
   parameters: {
     type: "object",
     properties: {
-      id: { type: "string", description: "\u4EFB\u52A1 id\uFF0C\u4F8B\u5982 t1" },
+      id: { type: "string", description: "\u4F5C\u4E1A id\uFF0C\u4F8B\u5982 t1\uFF08\u540E\u53F0\u547D\u4EE4\uFF09\u6216 s1\uFF08\u6301\u4E45\u4F1A\u8BDD\uFF09" },
       since: { type: "number", description: "\u4E0A\u6B21\u8FD4\u56DE\u7684 nextCursor\uFF1B\u4E0D\u7ED9\u5C31\u4ECE\u5934\u53D6" }
     },
     required: ["id"]
@@ -639,29 +1109,42 @@ var taskOutputTool = {
   execute: (args, ctx) => {
     const id = String(args["id"] ?? "");
     const since = Number(args["since"]);
-    const result = taskOutput(ctx.sessionId, id, Number.isFinite(since) && since > 0 ? since : 0);
-    if (!result) return Promise.resolve(notFound(id));
-    const head = describeTask(result.info);
+    const result = readJob3(
+      ctx.sessionId,
+      id,
+      Number.isFinite(since) && since > 0 ? since : 0,
+      MAX_OUTPUT_CHUNK
+    );
+    if (!result) return Promise.resolve(notFound2(id));
+    const head = describeJob(result.info);
     const notes = [];
     if (result.missed > 0) notes.push(describeMissed(result.missed, result.info.artifact));
-    if (result.hasMore) notes.push(`\uFF08\u8FD8\u6709\u66F4\u591A\uFF0C\u7528 since: ${result.nextCursor} \u7EE7\u7EED\u53D6\uFF09`);
-    const sb = taskSandbox(ctx.sessionId, id);
+    if (result.hasMore) notes.push(describeMore(result.nextCursor));
+    const sb = jobSandbox(ctx.sessionId, id);
     const sbErr = sb ? sandboxError(sb) : null;
     if (sbErr) notes.push(`${sbErr.message}
 ${sbErr.suggestion}`);
-    const body = result.output || "\uFF08\u8FD9\u4E00\u6BB5\u6CA1\u6709\u65B0\u8F93\u51FA\uFF09";
     return Promise.resolve(
-      ok([head, ...notes, "", body, "", `nextCursor: ${result.nextCursor}`].join("\n"))
+      ok2(
+        [
+          head,
+          ...notes,
+          "",
+          result.output || NO_NEW_OUTPUT2,
+          "",
+          `nextCursor: ${result.nextCursor}`
+        ].join("\n")
+      )
     );
   }
 };
 var taskWait = {
   name: "task_wait",
-  description: "\u963B\u585E\u7B49\u4E00\u4E2A\u540E\u53F0\u4EFB\u52A1\u7ED3\u675F\u3002\u53C2\u6570: id(\u5FC5\u586B), timeoutMs(\u9ED8\u8BA4 30000\uFF0C\u6700\u5927 300000)\u3002**\u8D85\u65F6\u4E0D\u4F1A\u6740\u5B83** \u2014\u2014 \u53EA\u662F\u544A\u8BC9\u4F60\u8FD8\u5728\u8DD1\uFF0C\u8981\u505C\u7528 task_stop\u3002",
+  description: "\u963B\u585E\u7B49\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\u7ED3\u675F\u3002\u53C2\u6570: id(\u5FC5\u586B), timeoutMs(\u9ED8\u8BA4 30000\uFF0C\u6700\u5927 300000)\u3002**\u8D85\u65F6\u4E0D\u4F1A\u6740\u5B83** \u2014\u2014 \u53EA\u662F\u544A\u8BC9\u4F60\u8FD8\u5728\u8DD1\uFF0C\u8981\u505C\u7528 task_stop\u3002\u6301\u4E45 shell \u4F1A\u8BDD\uFF08s1\uFF09\u538B\u6839\u6CA1\u6709\u300C\u7ED3\u675F\u300D\u8FD9\u4E2A\u72B6\u6001\uFF0C\u7B49\u5B83\u4F1A**\u7ACB\u523B**\u8FD4\u56DE\u4E00\u53E5\u8BF4\u660E\u800C\u4E0D\u662F\u5E72\u7B49\u3002",
   parameters: {
     type: "object",
     properties: {
-      id: { type: "string", description: "\u4EFB\u52A1 id" },
+      id: { type: "string", description: "\u4F5C\u4E1A id" },
       timeoutMs: { type: "number", description: "\u6700\u591A\u7B49\u591A\u4E45\uFF08\u6BEB\u79D2\uFF09" }
     },
     required: ["id"]
@@ -673,41 +1156,37 @@ var taskWait = {
     const id = String(args["id"] ?? "");
     const requested = Number(args["timeoutMs"]);
     const timeout = Math.min(
-      Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_WAIT_MS,
-      MAX_WAIT_MS
+      Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_WAIT_MS2,
+      MAX_WAIT_MS2
     );
-    const result = await waitTask(ctx.sessionId, id, timeout);
-    if (!result) return notFound(id);
-    const tail = result.timedOut ? `
-\u7B49\u4E86 ${Math.round(timeout / 1e3)}s \u8FD8\u6CA1\u7ED3\u675F\uFF0C**\u6CA1\u6709\u505C\u5B83**\u3002\u53EF\u4EE5\u63A5\u7740\u5E72\u522B\u7684\uFF0C\u6216\u518D\u7B49\u4E00\u6B21\u3002` : "\n\u7528 task_output \u53D6\u8F93\u51FA\u3002";
-    return ok(describeTask(result.info) + tail);
+    const result = await waitJob2(ctx.sessionId, id, timeout);
+    if (!result) return notFound2(id);
+    const tail = result.neverEnds ? neverEndsNotice(id) : result.timedOut ? waitTimedOutNotice(Math.round(timeout / 1e3)) : WAIT_DONE;
+    return ok2(describeJob(result.info) + tail);
   }
 };
 var taskStop = {
   name: "task_stop",
-  description: "\u505C\u6389\u4E00\u4E2A\u540E\u53F0\u4EFB\u52A1\uFF08\u6740\u6574\u68F5\u8FDB\u7A0B\u6811\uFF0C\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B)\u3002",
+  description: "\u505C\u6389\u4E00\u4E2A\u540E\u53F0\u4F5C\u4E1A\uFF08\u6740\u6574\u68F5\u8FDB\u7A0B\u6811\uFF0C\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002\u53C2\u6570: id(\u5FC5\u586B)\u3002\u540E\u53F0\u547D\u4EE4\uFF08t1\uFF09\u548C\u6301\u4E45\u4F1A\u8BDD\uFF08s1\uFF09\u90FD\u80FD\u505C \u2014\u2014 \u505C\u4E00\u4E2A\u6301\u4E45\u4F1A\u8BDD\u7B49\u4EF7\u4E8E shell_close\uFF0C\u90A3\u4E2A\u4F1A\u8BDD\u91CC\u7684\u73AF\u5883\uFF08cd / venv / REPL\uFF09\u4F1A\u4E00\u8D77\u6CA1\u3002",
   parameters: {
     type: "object",
-    properties: { id: { type: "string", description: "\u4EFB\u52A1 id" } },
+    properties: { id: { type: "string", description: "\u4F5C\u4E1A id" } },
     required: ["id"]
   },
-  // 它真的会杀进程，所以**不是** readOnly
   annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
   operation: "file_read",
   describeTarget: (args) => String(args["id"] ?? ""),
   execute: async (args, ctx) => {
     const id = String(args["id"] ?? "");
-    const stopped = await stopTask(ctx.sessionId, id);
-    if (!stopped) {
-      const tasks = listTasks(ctx.sessionId);
-      const exists = tasks.some((t) => t.id === id);
-      return exists ? ok(`${id} \u5DF2\u7ECF\u4E0D\u5728\u8FD0\u884C\u4E2D\u4E86\u3002`) : notFound(id);
+    const before = getJob3(ctx.sessionId, id);
+    if (!before) return notFound2(id);
+    if (!await stopJob3(ctx.sessionId, id)) {
+      return ok2(alreadyStoppedNotice(id));
     }
-    return ok(`${id} \u5DF2\u505C\u6B62\uFF08\u542B\u5B83\u8D77\u7684\u5B50\u8FDB\u7A0B\uFF09\u3002`);
+    return ok2(stoppedNotice(id, before.kind));
   }
 };
 var TASK_TOOLS = [taskList, taskOutputTool, taskWait, taskStop];
-
 // src/index.ts
 var DEFAULT_TIMEOUT = 6e4;
 var PTY_TIMEOUT = 3e4;
@@ -720,14 +1199,6 @@ function detectCd(command) {
   if (!rawTarget) return null;
   return rawTarget.trim().replace(/^["']|["']$/g, "");
 }
-function sandboxPolicyFor(ctx, workspaceRoot) {
-  return {
-    mode: sandboxModeForLevel(ctx.permissionLevel),
-    workspaceRoot,
-    ...ctx.extraRoots ? { extraRoots: ctx.extraRoots } : {},
-    allowNetwork: true
-  };
-}
 function toSandboxFailure(sb, output, duration) {
   const err = sandboxError(sb);
   if (!err) return null;
@@ -735,8 +1206,6 @@ function toSandboxFailure(sb, output, duration) {
     success: false,
     output,
     error: {
-      // 2008 = 被沙箱挡下（命令跑了，动作被拒）
-      // 2009 = 沙箱自己没起来（命令**没有**跑）
       code: sb.failure?.kind === "runner-failed" ? 2009 : 2008,
       message: err.message,
       suggestion: err.suggestion
@@ -775,9 +1244,6 @@ var terminalTool = {
     required: ["command"]
   },
   supportsParallel: false,
-  // 任意 shell 命令：能删数据、能联网，两个方向都到顶。
-  // `openWorldHint: true` 同时让 core 把输出包进 `<tool_output untrusted="true">`
-  // —— `curl` 抓回来的东西和 web_fetch 抓的没有区别。
   annotations: {
     readOnlyHint: false,
     destructiveHint: true,
@@ -785,7 +1251,6 @@ var terminalTool = {
     openWorldHint: true
   },
   operation: "command",
-  // 审批目标就是完整命令串（五候选里的 command 也能猜到，这里写明确的）
   describeTarget: (args) => String(args["command"] ?? ""),
   async execute(args, ctx) {
     const command = String(args["command"] ?? "");
@@ -801,7 +1266,7 @@ var terminalTool = {
         duration: 0
       };
     }
-    const danger = checkDangerousCommand(command);
+    const danger = checkDangerousCommand2(command);
     if (danger.dangerous) {
       return {
         success: false,
@@ -817,7 +1282,7 @@ var terminalTool = {
     const baseDir = ctx.workDir || process.cwd();
     let cwd = baseDir;
     if (workdir) {
-      if (!isInWorkspace(workdir, baseDir, ctx.extraRoots)) {
+      if (!isInWorkspace2(workdir, baseDir, ctx.extraRoots)) {
         return {
           success: false,
           output: "",
@@ -829,7 +1294,7 @@ var terminalTool = {
           duration: 0
         };
       }
-      cwd = isAbsolute(workdir) ? resolve(workdir) : resolve(baseDir, workdir);
+      cwd = isAbsolute2(workdir) ? resolve2(workdir) : resolve2(baseDir, workdir);
     }
     if (isBackground) {
       const started = startTask(
@@ -867,12 +1332,10 @@ var terminalTool = {
           timeout: PTY_TIMEOUT,
           cwd,
           tag: ctx.sessionId + "::pty",
+          sessionId: ctx.sessionId,
           ...stdin ? { stdin } : {},
           ...ctx.signal ? { signal: ctx.signal } : {},
           ...ctx.onOutput ? { onOutput: ctx.onOutput } : {},
-          // 方案 46 PR-5：PTY 这条路 2026-08-17 起也有 OS 强制的写入边界。
-          // tty 分配 / 窗口尺寸 / 信号转发三样在真 Seatbelt 上逐条验过照旧，
-          // 实测表在 pty.ts 的文件头 —— 那三样正是方案 §三 点名要单独验的
           sandbox: sandboxPolicyFor(ctx, baseDir)
         });
         const duration = Date.now() - startTime;
@@ -920,10 +1383,6 @@ ${CD_NOTICE(cdTarget)}`;
         signal: ctx.signal,
         cwd,
         ...ctx.onOutput ? { onOutput: ctx.onOutput } : {},
-        // 方案 46 PR-1：`terminal` 的默认路径从这里起有 OS 强制的写入边界。
-        // **边界按工作区主根算，不按 `cwd` 算** —— `cwd` 可能是工作区的子目录
-        // （模型传了 workdir），按它算的话「写工作区里另一个目录」会被挡，
-        // 而那是一次完全正常的操作
         sandbox: sandboxPolicyFor(ctx, baseDir)
       });
       const duration = Date.now() - startTime;
@@ -979,22 +1438,33 @@ ${CD_NOTICE(cdTarget)}`;
 var terminalPlugin = {
   name: "@epoch-agent/plugin-terminal",
   version: "0.0.0",
-  description: "\u7EC8\u7AEF\u547D\u4EE4\u6267\u884C + PTY \u4EA4\u4E92 + \u540E\u53F0\u4EFB\u52A1 [Hermes/Codex]",
-  // 四个后台任务工具**无条件注册**：它们只读任务表，没有任务时 task_list
-  // 就说一句「没有」。按「有没有任务」动态注册的话，模型第一次起后台任务之后
-  // 工具表会变，而它这一轮看到的还是旧的
-  tools: [terminalTool, ...TASK_TOOLS]
+  description: "\u7EC8\u7AEF\u547D\u4EE4\u6267\u884C + PTY \u4EA4\u4E92 + \u540E\u53F0\u4EFB\u52A1 + \u6301\u4E45 shell \u4F1A\u8BDD [Hermes/Codex]",
+  tools: [terminalTool, ...TASK_TOOLS, ...SHELL_TOOLS]
 };
 export {
+  MAX_SHELLS,
+  MAX_SHELL_CHUNK,
+  MAX_SHELL_OUTPUT,
   MAX_TASKS,
+  SHELL_IDLE_MS,
+  SHELL_SWEEP_MS,
+  SHELL_TOOLS,
   TASK_TOOLS,
   cleanupBackgroundProcesses,
+  clearAllShells,
   clearAllTasks,
+  closeShell,
+  describeShell,
   describeTask,
+  listShells,
   listTasks,
+  openShell,
+  readShell,
   rekeyTasks,
+  sendToShell,
   startTask,
   stopTask,
+  sweepIdleShells,
   taskOutput,
   taskSandbox,
   terminalPlugin,