@wolido/async-subagent-isolation 1.6.2 → 1.7.0

package/README.en.md

@@ -241,13 +241,13 @@ User runs /subagent-result <taskId> to read the full output
 
 ## Example agents
 
-The GitHub repo ships three ready-to-reference agents in [`examples/pi/agent/agents/`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/agents):
+The GitHub repo ships three ready-to-reference agents in [`examples/pi/agent/agents/`](https://github.com/Wolido/async-subagent-isolation/tree/main/examples/pi/agent/agents):
 
 | Agent | Purpose | Tools | Skill |
 |-------|---------|-------|-------|
-| [`coder`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/coder.md) | Write, modify, and validate code | `read, write, edit, bash, grep, find, ls` | `systematic-debugging` |
-| [`reviewer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/reviewer.md) | Read-only review with actionable feedback | `read, grep, find, ls` | _(none)_ |
-| [`writer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/writer.md) | Write docs, READMEs, commit messages | `read, write, edit, grep, find, ls` | `writing-clearly-and-concisely` |
+| [`coder`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/coder.md) | Write, modify, and validate code | `read, write, edit, bash, grep, find, ls` | `systematic-debugging` |
+| [`reviewer`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/reviewer.md) | Read-only review with actionable feedback | `read, grep, find, ls` | _(none)_ |
+| [`writer`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/writer.md) | Write docs, READMEs, commit messages | `read, write, edit, grep, find, ls` | `writing-clearly-and-concisely` |
 
 Copy the ones you need into `~/.pi/agent/agents/` (user-scoped) or `.pi/agents/` (project-scoped; project overrides user on name collisions). Feel free to modify them or create your own. After modifying or adding agent files, run `/reload` to refresh the subagent roster injected into the main agent's prompt (see "Configuration management").
 

package/README.md

@@ -241,13 +241,13 @@ Dispatched coder. taskId: 01912345-6789-7abc-8def-0123456789ab
 
 ## 示例 agents
 
-仓库 [`examples/pi/agent/agents/`](https://github.com/Wolido/subagent-isolation/tree/main/examples/pi/agent/agents) 提供三个可直接参考的 agent：
+仓库 [`examples/pi/agent/agents/`](https://github.com/Wolido/async-subagent-isolation/tree/main/examples/pi/agent/agents) 提供三个可直接参考的 agent：
 
 | Agent | 作用 | 可用工具 | 加载的 skill |
 |-------|------|----------|-------------|
-| [`coder`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/coder.md) | 写代码、改代码、跑验证 | `read, write, edit, bash, grep, find, ls` | `systematic-debugging` |
-| [`reviewer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/reviewer.md) | 只读评审，输出可操作的反馈 | `read, grep, find, ls` | _(无)_ |
-| [`writer`](https://github.com/Wolido/subagent-isolation/blob/main/examples/pi/agent/agents/writer.md) | 写文档、改 README、生成 commit message | `read, write, edit, grep, find, ls` | `writing-clearly-and-concisely` |
+| [`coder`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/coder.md) | 写代码、改代码、跑验证 | `read, write, edit, bash, grep, find, ls` | `systematic-debugging` |
+| [`reviewer`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/reviewer.md) | 只读评审，输出可操作的反馈 | `read, grep, find, ls` | _(无)_ |
+| [`writer`](https://github.com/Wolido/async-subagent-isolation/blob/main/examples/pi/agent/agents/writer.md) | 写文档、改 README、生成 commit message | `read, write, edit, grep, find, ls` | `writing-clearly-and-concisely` |
 
 复制到 `~/.pi/agent/agents/`（用户级）或 `.pi/agents/`（项目级，同名时 project 覆盖 user）即可使用，可按需修改或新建。修改或新建 agent 文件后运行 `/reload`，刷新注入主 agent 提示词的子 agent 清单（见“配置管理”一节）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolido/async-subagent-isolation",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Fix context rot and context pollution in long AI agent sessions. Subagents run in isolated processes; the main agent stays read-only and context stays clean.",
   "license": "MIT",
   "author": "Wolido",

package/src/index.ts

@@ -161,6 +161,213 @@ function isDirectory(p: string): boolean {
 	}
 }
 
+// ===== Subagent spawn preflight (cwd / command validation) =====
+
+export type PreflightCode = "CWD_MISSING" | "CWD_NOT_DIR" | "EXEC_MISSING" | "CWD_INACCESSIBLE";
+
+export interface PreflightResult {
+	ok: boolean;
+	code?: PreflightCode | null;
+	message?: string;
+	fields?: {
+		command?: string;
+		cwd?: string;
+		cwdExists?: boolean;
+		source?: "param" | "session";
+	};
+}
+
+/**
+ * Normalize the requested subagent cwd. Lenient on spelling, strict on
+ * existence (existence is checked separately by preflightSpawn):
+ * - "~/x" -> homedir/x, "~" -> homedir (injected for testability)
+ * - relative -> resolved against sessionCwd (the session cwd, NOT process.cwd())
+ * - absolute -> path.normalize
+ * - no paramCwd (or empty / whitespace-only) -> sessionCwd verbatim (byte-identical to legacy behavior)
+ */
+export function resolveAgentCwd(opts: {
+	paramCwd?: string;
+	sessionCwd: string;
+	homedir: string;
+}): { cwd: string; source: "param" | "session" } {
+	const { paramCwd, sessionCwd, homedir } = opts;
+	// 空串与纯空白一律视同"未传参数"：不谎报 source=param，也不把空白拼成真实目录名。
+	if (paramCwd === undefined || paramCwd.trim() === "") return { cwd: sessionCwd, source: "session" };
+	let cwd: string;
+	if (paramCwd === "~") cwd = homedir;
+	else if (paramCwd.startsWith("~/")) cwd = path.join(homedir, paramCwd.slice(2));
+	else if (path.isAbsolute(paramCwd)) cwd = path.normalize(paramCwd);
+	else cwd = path.resolve(sessionCwd, paramCwd);
+	return { cwd, source: "param" };
+}
+
+/** Facts gathered by (a)sync fs probes; decision itself is pure. */
+interface PreflightFacts {
+	command: string;
+	cwd: string;
+	source?: "param" | "session";
+	/** true = 任一 cwd 探针（checkExists/isDir）抛错。"探测失败"与"探测为否"
+	 *  是两种不同事实，必须独立记录——压成同一个（cwdErrno=undefined）正是
+	 *  ENOENT-vs-EACCES 误判与 fail-open 的根因。 */
+	cwdProbeFailed?: boolean;
+	/** errno of a failed cwd probe, recorded verbatim (e.g. "ENOENT", "EACCES");
+	 *  "EUNKNOWN" when the throw carried no `.code` — 可辨识占位值，不冒充任何
+	 *  真实 errno。 */
+	cwdErrno?: string;
+	cwdExists: boolean;
+	/** undefined when the isDir probe was not reached or itself threw
+	 *  （未探测/探测失败 ≠ 探针确定为 false）。 */
+	cwdIsDir?: boolean;
+	/** undefined when the exec check does not apply (non-absolute command). */
+	executable?: boolean;
+	/** errno of the failed exec probe, surfaced verbatim in the EXEC_MISSING message. */
+	execErrno?: string;
+}
+
+function decidePreflight(f: PreflightFacts): PreflightResult {
+	// 判定优先级是刻意的：cwd 先判、command 后判——两者同时异常时只报 cwd。
+	const fields = { command: f.command, cwd: f.cwd, source: f.source };
+	if (f.cwdProbeFailed === true) {
+		// 探针抛错 = "我无法判定"，绝不能读作"探针确定为否"。errno 分类（全局
+		// 仅此一处）：ENOENT/ENOTDIR 带原生语义（路径上无此物 / 父级分量是文件）
+		// ——checkExists 先 true、随后 isDir 抛 ENOENT 属两次探测之间目录被删
+		// （TOCTOU），此时"不存在"才是诚实且可行动的答案；其余 errno
+		// （EACCES/ELOOP/ENAMETOOLONG/…）与"无 errno 的抛错"（记作 EUNKNOWN）=
+		// 无法判定存在性，绝不谎称"不存在"。
+		if (f.cwdErrno === "ENOENT" || f.cwdErrno === "ENOTDIR") {
+			return {
+				ok: false,
+				code: "CWD_MISSING",
+				message: `[CWD_MISSING] 子代理工作目录不存在: ${f.cwd}（来源: ${f.source === "session" ? "session cwd" : "agent cwd 参数"}）。不会自动创建该目录；如确需使用，请先创建该目录后重试。`,
+				fields: { ...fields, cwdExists: false },
+			};
+		}
+		// CWD_INACCESSIBLE 语义 = "目录存在但无法访问"，故 fields.cwdExists 恒为 true。
+		return {
+			ok: false,
+			code: "CWD_INACCESSIBLE",
+			message: `[CWD_INACCESSIBLE] 子代理工作目录存在但无法访问: ${f.cwd}（errno=${f.cwdErrno ?? "EUNKNOWN"}）。请检查目录权限/链接环路后重试。`,
+			fields: { ...fields, cwdExists: true },
+		};
+	}
+	if (!f.cwdExists) {
+		// checkExists 未抛错且返回 false = 探针确定"不存在"（非探测失败）。
+		return {
+			ok: false,
+			code: "CWD_MISSING",
+			message: `[CWD_MISSING] 子代理工作目录不存在: ${f.cwd}（来源: ${f.source === "session" ? "session cwd" : "agent cwd 参数"}）。不会自动创建该目录；如确需使用，请先创建该目录后重试。`,
+			fields: { ...fields, cwdExists: false },
+		};
+	}
+	if (f.cwdIsDir === false) {
+		return {
+			ok: false,
+			code: "CWD_NOT_DIR",
+			message: `[CWD_NOT_DIR] 子代理工作目录已存在但不是目录: ${f.cwd}。请改为传入一个目录路径。`,
+			fields: { ...fields, cwdExists: true },
+		};
+	}
+	if (f.executable === false) {
+		return {
+			ok: false,
+			code: "EXEC_MISSING",
+			message: `[EXEC_MISSING] 子代理启动命令不可执行: ${f.command}（errno=${f.execErrno ?? "EUNKNOWN"}）。长生命周期 pi 进程持有的 node 路径可能已因 Homebrew 升级被删除，请重启 pi 后重试。`,
+			fields: { ...fields, cwdExists: true },
+		};
+	}
+	// 正向判定：ok:true 只在 cwdIsDir === true（探针确定"是目录"）时成立。
+	// `!== false` 是 bug——探针抛错留下的 undefined 不是"是"。
+	if (f.cwdIsDir === true) {
+		return { ok: true };
+	}
+	// 兜底（按采集逻辑不可达：cwdExists 为 true 且探针未抛错时 isDir 必写下
+	// boolean）。存在仅为保证任何事实组合都 fail-closed，绝不静默放行。
+	return {
+		ok: false,
+		code: "CWD_INACCESSIBLE",
+		message: `[CWD_INACCESSIBLE] 子代理工作目录存在但无法访问: ${f.cwd}（errno=${f.cwdErrno ?? "EUNKNOWN"}）。请检查目录权限/链接环路后重试。`,
+		fields: { ...fields, cwdExists: true },
+	};
+}
+
+/**
+ * Pre-spawn validation (async contract form). Returns a structured result
+ * instead of throwing so callers can propagate code/fields through the
+ * normal result channel. fs checks are injected for testability.
+ *
+ * 公共 API：注入式事实采集的官方接缝，供需要自定义探针的调用方（含测
+ * 试）使用。纯适配器：只负责"await 注入的探针采集事实、如实记录 errno 与
+ * 探测失败 → 交给 decidePreflight → 返回"，内部无任何独立判定分支（判定逻
+ * 辑全局仅 decidePreflight 一处）。生产路径走同步入口 preflightSpawnSync
+ * 以保证 spawn 时序（异步入口曾因引入 microtask 导致 107 个既有用例失败）。
+ * The executable check applies only to absolute command paths — bare names
+ * like "pi" resolve via PATH at spawn time and must not be access()-checked.
+ */
+export async function preflightSpawn(opts: {
+	command: string;
+	cwd: string;
+	source?: "param" | "session";
+	checkExists: (p: string) => Promise<boolean>;
+	isDir: (p: string) => Promise<boolean>;
+	hasExec: (p: string) => Promise<boolean>;
+}): Promise<PreflightResult> {
+	const facts: PreflightFacts = { command: opts.command, cwd: opts.cwd, source: opts.source, cwdExists: false };
+	try {
+		facts.cwdExists = await opts.checkExists(opts.cwd);
+	} catch (err) {
+		// 探针抛错 = 探测失败（独立事实），无 .code 时记可辨识占位值 EUNKNOWN。
+		facts.cwdProbeFailed = true;
+		facts.cwdErrno = (err as NodeJS.ErrnoException).code ?? "EUNKNOWN";
+	}
+	if (facts.cwdExists) {
+		try {
+			facts.cwdIsDir = await opts.isDir(opts.cwd);
+		} catch (err) {
+			facts.cwdProbeFailed = true;
+			facts.cwdErrno = (err as NodeJS.ErrnoException).code ?? "EUNKNOWN";
+		}
+	}
+	if (facts.cwdExists && facts.cwdIsDir === true && path.isAbsolute(opts.command)) {
+		try {
+			facts.executable = await opts.hasExec(opts.command);
+		} catch (err) {
+			facts.executable = false;
+			facts.execErrno = (err as NodeJS.ErrnoException).code;
+		}
+	}
+	return decidePreflight(facts);
+}
+
+/**
+ * Synchronous preflight for runSingleAgent: spawn must stay reachable
+ * within the same synchronous segment as before the preflight existed
+ * (async fs probes would delay spawn past callers that assert immediately).
+ * 纯适配器：statSync/accessSync 采集事实（如实记录 errno）→ decidePreflight
+ * 统一判定，内部无独立判定分支。
+ */
+function preflightSpawnSync(input: { command: string; cwd: string; source?: "param" | "session" }): PreflightResult {
+	const facts: PreflightFacts = { command: input.command, cwd: input.cwd, source: input.source, cwdExists: false };
+	try {
+		const stat = fs.statSync(input.cwd);
+		facts.cwdExists = true;
+		facts.cwdIsDir = stat.isDirectory();
+	} catch (err) {
+		// 与异步入口同一纪律：抛错 = 探测失败，无 .code 时记 EUNKNOWN。
+		facts.cwdProbeFailed = true;
+		facts.cwdErrno = (err as NodeJS.ErrnoException).code ?? "EUNKNOWN";
+	}
+	if (facts.cwdExists && facts.cwdIsDir === true && path.isAbsolute(input.command)) {
+		try {
+			fs.accessSync(input.command, fs.constants.X_OK);
+			facts.executable = true;
+		} catch (err) {
+			facts.executable = false;
+			facts.execErrno = (err as NodeJS.ErrnoException).code;
+		}
+	}
+	return decidePreflight(facts);
+}
+
 function findNearestProjectAgentsDir(cwd: string): string | null {
 	let currentDir = cwd;
 	while (true) {
@@ -1706,6 +1913,10 @@ interface SingleResult {
 	startedAt: number;
 	/** Wall-clock finish, set when the run resolves; absent while running. */
 	finishedAt?: number;
+	/** Preflight failure code, set when the run was rejected before spawn. */
+	preflightCode?: PreflightCode;
+	/** Structured preflight failure context (command/cwd/cwdExists/source). */
+	preflightFields?: PreflightResult["fields"];
 }
 
 interface SubagentDetails {
@@ -1727,6 +1938,24 @@ function getFinalOutput(messages: Message[]): string {
 	return "";
 }
 
+/**
+ * N2(c): the result answer is the LAST assistant message's non-empty text —
+ * never an earlier turn's. When the final assistant turn errored or produced
+ * only thinking/tool calls, earlier text is stale and must not masquerade as
+ * the answer. Returns "" when the run ended without final text.
+ */
+function getLastAssistantText(messages: Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "assistant") continue;
+		for (const part of msg.content) {
+			if (part.type === "text" && part.text.trim()) return part.text;
+		}
+		return "";
+	}
+	return "";
+}
+
 type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, any> };
 
 function getDisplayItems(messages: Message[]): DisplayItem[] {
@@ -2308,9 +2537,11 @@ async function runSingleAgent(
 	if (effectiveThinking) args.push("--thinking", effectiveThinking);
 	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
 
-	// Effective working directory: agent-specific cwd > session default.
-	// Used both for resolving relative skill paths and as the spawned process cwd.
-	const effectiveCwd = cwd ?? defaultCwd;
+	// Effective working directory: agent-specific cwd (normalized) > session
+	// default. Used both for resolving relative skill paths and as the spawned
+	// process cwd. When no cwd param is given this is defaultCwd verbatim.
+	const cwdResolution = resolveAgentCwd({ paramCwd: cwd, sessionCwd: defaultCwd, homedir: os.homedir() });
+	const effectiveCwd = cwdResolution.cwd;
 
 	// MODIFIED: inject per-agent skill isolation
 	const skillWarnings: string[] = [];
@@ -2398,6 +2629,28 @@ async function runSingleAgent(
 		}
 
 		args.push(`Task: ${task}`);
+
+		// Preflight: validate the normalized cwd and the executable BEFORE
+		// spawning, so a missing cwd surfaces as a structured CWD_MISSING error
+		// instead of the misleading raw `spawn <execPath> ENOENT`.
+		const invocation = getPiInvocation(args);
+		// Synchronous on purpose: keeps spawn reachable within the same
+		// synchronous segment as before this preflight existed.
+		const preflight = preflightSpawnSync({
+			command: invocation.command,
+			cwd: effectiveCwd,
+			source: cwdResolution.source,
+		});
+		if (!preflight.ok) {
+			currentResult.exitCode = 1;
+			currentResult.errorMessage = preflight.message;
+			currentResult.stderr += `${preflight.message}\n`;
+			currentResult.preflightCode = preflight.code ?? undefined;
+			currentResult.preflightFields = preflight.fields;
+			currentResult.finishedAt = Date.now();
+			return currentResult;
+		}
+
 		let wasAborted = false;
 
 		const POST_EXIT_GRACE_MS = 500;
@@ -2406,7 +2659,6 @@ async function runSingleAgent(
 		const DEFAULT_HARD_TIMEOUT_MS = 0;
 
 		const exitCode = await new Promise<number>((resolve) => {
-			const invocation = getPiInvocation(args);
 			const currentDepth = parseEnvInt(process.env.PI_SUBAGENT_DEPTH, 0);
 			const proc = spawn(invocation.command, invocation.args, {
 				cwd: effectiveCwd,
@@ -2582,8 +2834,41 @@ async function runSingleAgent(
 						) {
 							currentResult.stopReason = msg.stopReason;
 						}
-						if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
 						if (msg.stopReason === "error" || msg.errorMessage) {
+							// N3: a failed turn is not terminal. pi may auto-retry inside
+							// this same process (agent_end{willRetry:true} ->
+							// auto_retry_start -> ...), so only record the cause and keep
+							// waiting — no kill, no finalize. The activity timer stays
+							// armed (resetActivityTimer above + the stdout data handler),
+							// so a process that goes silent after the error still ends as
+							// activity_timeout, never as a permanent "running".
+							if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
+						} else {
+							// A healthy assistant turn after a recovered retry clears the
+							// recorded error, so a retried run can still finalize as
+							// success (finalize maps a lingering errorMessage to exit 1).
+							currentResult.errorMessage = undefined;
+						}
+					}
+					emitProgress();
+				}
+
+				if (event.type === "agent_end") {
+					if (event.willRetry) {
+						// willRetry === true: pi is about to auto-retry inside this
+						// same process — nothing is final yet. The retry's own delay
+						// may exceed the activity window, so the inactivity net is
+						// suspended (not re-armed) until genuine stdout/stderr
+						// activity resumes; a provisional activity_timeout recorded
+						// while the failed turn awaited this decision is revoked.
+						suspendActivityTimerForRetry();
+					} else {
+						resetActivityTimer();
+						// willRetry === false is NOT a failure signal by itself (it
+						// also fires on normal success), so only an already-recorded
+						// error state finalizes as failure here; a clean agent_end is
+						// left for the natural process exit.
+						if (currentResult.stopReason === "error" || currentResult.errorMessage) {
 							try {
 								proc.kill("SIGKILL");
 							} catch {
@@ -2594,7 +2879,36 @@ async function runSingleAgent(
 							return;
 						}
 					}
-					emitProgress();
+				}
+
+				if (event.type === "auto_retry_start") {
+					// Retry cycle starting; the process stays alive — wait for the
+					// retried turn. The retry delay (delayMs) can exceed the
+					// activity window, so the inactivity net is suspended (not
+					// re-armed); genuine activity re-arms it via the stdout/stderr
+					// data handlers.
+					suspendActivityTimerForRetry();
+				}
+
+				if (event.type === "auto_retry_end") {
+					if (event.success === false) {
+						resetActivityTimer();
+						// Retries exhausted: finalError is the authoritative cause.
+						if (event.finalError) currentResult.errorMessage = String(event.finalError);
+						try {
+							proc.kill("SIGKILL");
+						} catch {
+							/* ignore ESRCH */
+						}
+						emitProgress();
+						finalize(1);
+						return;
+					}
+					// success === true: the run continues; the recovered turn's
+					// message_end clears the recorded error. Suspend the inactivity
+					// net until that activity arrives (same reasoning as
+					// auto_retry_start).
+					suspendActivityTimerForRetry();
 				}
 			};
 			const processLine = (line: string) => {
@@ -2614,6 +2928,18 @@ async function runSingleAgent(
 				);
 				if (activityMs > 0) {
 					activityTimer = setTimeout(() => {
+						// A failed turn still awaiting pi's retry decision
+						// (stopReason === "error" / errorMessage recorded, no
+						// agent_end or auto_retry_end yet) makes the timeout
+						// PROVISIONAL: SIGKILL still reclaims a genuinely hung
+						// process (and the exit it guarantees finalizes the task as
+						// timed out), but finalization is deferred to that exit so
+						// a retry-lifecycle event observed before it can revoke the
+						// provisional stopReason (see suspendActivityTimerForRetry).
+						// Any other silence finalizes immediately — the process is
+						// hung mid-work and must never run forever.
+						const awaitingRetryDecision =
+							currentResult.stopReason === "error" || !!currentResult.errorMessage;
 						currentResult.stopReason = "activity_timeout";
 						const elapsed = Date.now() - lastActivityAt;
 						const phase = currentResult.phase;
@@ -2624,11 +2950,33 @@ async function runSingleAgent(
 						} catch {
 							/* ignore ESRCH */
 						}
-						finalize(1);
+						if (!awaitingRetryDecision) finalize(1);
 					}, activityMs);
 				}
 			};
 
+			/**
+			 * Retry-lifecycle events (agent_end{willRetry:true},
+			 * auto_retry_start, auto_retry_end{success:true}) prove the process
+			 * is alive but are followed by pi's own retry delay, which may exceed
+			 * the activity window. Suspend the inactivity net until genuine
+			 * stdout/stderr activity re-arms it (the data handlers call
+			 * resetActivityTimer), and revoke a provisional activity_timeout
+			 * stopReason recorded while the failed turn awaited pi's retry
+			 * decision.
+			 */
+			const suspendActivityTimerForRetry = () => {
+				// Same guard as resetActivityTimer: after resolution, once abort
+				// started teardown, or after the process exited, touching the
+				// timer/stopReason is meaningless (abort 后不得再动计时器).
+				if (resolved || wasAborted || exitCodeValue !== null) return;
+				if (activityTimer) {
+					clearTimeout(activityTimer);
+					activityTimer = undefined;
+				}
+				if (currentResult.stopReason === "activity_timeout") currentResult.stopReason = undefined;
+			};
+
 			const setupHardTimer = () => {
 				// Don't arm after resolution, once abort started teardown, or after
 				// the process exited (same guard as resetActivityTimer): a hard
@@ -2695,7 +3043,11 @@ async function runSingleAgent(
 			});
 
 			proc.on("error", (err) => {
-				currentResult.stderr += `[async-subagent-isolation] process error: ${err?.message ?? String(err)}\n`;
+				// A raw spawn ENOENT blames the executable path even when the real
+				// cause is a missing cwd — attach the structured context so the
+				// message can no longer be misread as "node is broken".
+				const cwdExists = isDirectory(effectiveCwd);
+				currentResult.stderr += `[async-subagent-isolation] process error: ${err?.message ?? String(err)} (command: ${invocation.command}, cwd: ${effectiveCwd}, cwdExists: ${cwdExists})\n`;
 				finalize(1);
 			});
 
@@ -2992,8 +3344,34 @@ function getTaskStatus(result: SingleResult): SubagentTaskStatus {
 	const stopReason = result.stopReason;
 	if (stopReason === "aborted" || stopReason === "killed_on_shutdown") return "cancelled";
 	if (stopReason === "activity_timeout" || stopReason === "hard_timeout") return "timeout";
-	if (result.exitCode !== 0 || stopReason === "error") return "failure";
-	return "success";
+	return isTaskFailure(result) ? "failure" : "success";
+}
+
+/**
+ * The single "did this run fail" predicate (N2 three-layer success criteria,
+ * inverted): (a) a clean exit with no recorded error, (b) a normal terminal
+ * stopReason ("error"/abort/timeout are terminal failures; "length"/"deferred"
+ * mean the answer was cut off or postponed), (c) non-empty text on the LAST
+ * assistant message. Exit 0 alone never proves success.
+ *
+ * Shared by all three success/failure call sites — the async terminal status
+ * (getTaskStatus), the sync execute() isError flag and the renderResult icon —
+ * so they can never drift into disagreeing about the same run.
+ */
+function isTaskFailure(result: SingleResult): boolean {
+	const stopReason = result.stopReason;
+	if (result.exitCode !== 0) return true;
+	if (
+		stopReason === "error" ||
+		stopReason === "aborted" ||
+		stopReason === "killed_on_shutdown" ||
+		stopReason === "activity_timeout" ||
+		stopReason === "hard_timeout"
+	)
+		return true;
+	if (result.errorMessage) return true;
+	if (stopReason === "length" || stopReason === "deferred") return true;
+	return !getLastAssistantText(result.messages);
 }
 
 /** Structured payload carried by the subagent-result message's details field. */
@@ -3015,6 +3393,13 @@ export interface SubagentResultDetails {
 	usage: UsageStats;
 	sessionId: string;
 	output: string;
+	/**
+	 * Truncated failure cause (ERROR_MESSAGE_MAX_CHARS), present only on failed
+	 * tasks whose run recorded an errorMessage (message_end(error) or
+	 * auto_retry_end{finalError}). Also inlined as the envelope's `- Error:`
+	 * meta line.
+	 */
+	errorMessage?: string;
 }
 
 /**
@@ -3024,6 +3409,38 @@ export interface SubagentResultDetails {
  */
 const DETAILS_OUTPUT_MAX_CHARS = 16 * 1024;
 
+/**
+ * Cap for the failure cause surfaced through the result envelope (meta `- Error:`
+ * line and details.errorMessage). Long provider payloads are truncated with a
+ * visible marker; the prefix is preserved so the error stays identifiable.
+ */
+export const ERROR_MESSAGE_MAX_CHARS = 2000;
+
+/** Truncate an over-long error message, keeping the identifying prefix. */
+function truncateErrorMessage(message: string): string {
+	if (message.length <= ERROR_MESSAGE_MAX_CHARS) return message;
+	return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}\n... (truncated)`;
+}
+
+/**
+ * Cap for the stderr tail surfaced through the envelope's `- Stderr:` meta
+ * line on otherwise clueless failures (no errorMessage, no output).
+ */
+const STDERR_TAIL_MAX_CHARS = 1000;
+
+/**
+ * Compact stderr tail for the envelope's `- Stderr:` meta line: trimmed and
+ * capped to the last STDERR_TAIL_MAX_CHARS. The stderr text is presented
+ * verbatim — no content rewriting of any kind (no prefix stripping, no
+ * log-level normalization), so the main agent sees exactly what the
+ * subprocess wrote.
+ */
+function summarizeStderrTail(stderr: string): string {
+	const trimmed = stderr.trim();
+	if (!trimmed) return "";
+	return trimmed.length > STDERR_TAIL_MAX_CHARS ? trimmed.slice(-STDERR_TAIL_MAX_CHARS) : trimmed;
+}
+
 /**
  * Fixed trigger line inserted into every [subagent-result] envelope right
  * after the title line (before the in-flight block). Steer delivery injects
@@ -3068,7 +3485,10 @@ export function buildResultEnvelope(
 	errorMessage?: string,
 ): { content: string; details: SubagentResultDetails } {
 	const statusWord = STATUS_WORDS[status];
-	const output = result ? getFinalOutput(result.messages) : "";
+	// details.output / body carry only the real final-turn assistant text
+	// (N2/N4): never an earlier turn's stale text, never the errorMessage,
+	// never raw stderr — those must not masquerade as the answer.
+	const output = result ? getLastAssistantText(result.messages) : "";
 	const usage: UsageStats =
 		result?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 	const sessionId = result?.sessionId ?? task.taskId;
@@ -3078,8 +3498,23 @@ export function buildResultEnvelope(
 	const durationMs = result
 		? Math.max(0, (result.finishedAt ?? Date.now()) - result.startedAt)
 		: Math.max(0, Date.now() - task.startedAt);
+	// N1: surface the recorded failure cause (message_end errorMessage or
+	// auto_retry_end finalError, both stored on result.errorMessage) in the
+	// meta-info area and in details.errorMessage, truncated with a marker.
+	const exposedError =
+		status === "failure" && result?.errorMessage ? truncateErrorMessage(result.errorMessage) : undefined;
+	// N4 follow-up: a failure with neither a recorded cause nor final text
+	// would otherwise end in a bare "(no output)" with zero clues (e.g. a
+	// subprocess that wrote a fatal error to stderr and died without any
+	// message_end). Surface the stderr TAIL as a labelled `- Stderr:` meta
+	// line — never as the body, never in details.output (stderr must not
+	// masquerade as the answer, N4), and never next to a `- Error:` line (a
+	// recorded errorMessage takes precedence, N1).
+	const stderrTail =
+		status === "failure" && !exposedError && !output && result?.stderr
+			? summarizeStderrTail(result.stderr)
+			: "";
 	let body = output;
-	if (!body && result) body = result.errorMessage || result.stderr.trim();
 	// Only genuine failures are labelled "Internal error"; a user cancel or
 	// session shutdown rejection is an expected abort, so it gets a note
 	// carrying the abort's origin (user cancel vs session shutdown).
@@ -3092,6 +3527,10 @@ export function buildResultEnvelope(
 		`- Status: ${statusWord}`,
 		`- Task: ${truncateTaskDescription(task.task)}`,
 		`- Duration: ${formatDuration(durationMs)} · Usage: ${formatUsageStats(usage, result?.model) || "-"}`,
+		// The `- Error:` line sits inside the meta-info area, after Status and
+		// before the `- Session:` anchor the in-flight block extraction relies on.
+		...(exposedError ? [`- Error: ${exposedError}`] : []),
+		...(stderrTail ? [`- Stderr: ${stderrTail}`] : []),
 		`- Session: ${sessionId}`,
 		"",
 		// 在途 block: completeAsyncTask deletes this task from the registry
@@ -3117,6 +3556,7 @@ export function buildResultEnvelope(
 				output.length > DETAILS_OUTPUT_MAX_CHARS
 					? `${output.slice(0, DETAILS_OUTPUT_MAX_CHARS)}\n... (truncated; full output in content)`
 					: output,
+			errorMessage: exposedError,
 		},
 	};
 }
@@ -3264,7 +3704,12 @@ const SubagentParams = Type.Object({
 	confirmProjectAgents: Type.Optional(
 		Type.Boolean({ description: "Prompt before running project-local agents. Default: false.", default: false }),
 	),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	cwd: Type.Optional(
+		Type.String({
+			description:
+				'Working directory for the agent process. Must be an existing directory: a nonexistent path is a hard error (reported as [CWD_MISSING]) and is never auto-created — create it first if needed. Only "~/…" and bare "~" are expanded to the home directory; "~user/…" is not supported and errors as CWD_MISSING. Relative paths resolve against the session cwd.',
+		}),
+	),
 });
 
 export default function (pi: ExtensionAPI) {
@@ -3592,7 +4037,13 @@ export default function (pi: ExtensionAPI) {
 					ctx.model,
 					modelOverrides,
 				);
-				const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+				// N2 on the sync path too: exit 0 without non-empty text on the LAST
+				// assistant message is a fake success (silent no-answer run, errored
+				// final turn, truncated/deferred answer, …) — report failure with the
+				// full diagnostics instead. The predicate is shared with the async
+				// terminal status (getTaskStatus) and the renderer (renderResult), so
+				// sync and async can never disagree about the same run.
+				const isError = isTaskFailure(result);
 				if (isError) {
 					const diagnostics = formatSubagentDiagnostics(result) + `\n\n[subagent session: ${result.sessionId}]`;
 					return {
@@ -3601,7 +4052,7 @@ export default function (pi: ExtensionAPI) {
 						isError: true,
 					};
 				}
-				const rawOutput = getFinalOutput(result.messages);
+				const rawOutput = getLastAssistantText(result.messages);
 				const outputText = rawOutput
 					? `${rawOutput}\n\n[subagent session: ${result.sessionId}]`
 					: `[subagent session: ${result.sessionId}]`;
@@ -3658,7 +4109,10 @@ export default function (pi: ExtensionAPI) {
 
 			if (details.mode === "single" && details.results.length === 1) {
 				const r = details.results[0];
-				const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+				// Shared failure predicate (isTaskFailure): the icon must match the
+				// status the async envelope / sync isError would report for the same
+				// run — e.g. exit 0 + stopReason "length" renders ✗, not ✓.
+				const isError = isTaskFailure(r);
 				const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
 				const displayItems = getDisplayItems(r.messages);
 				const finalOutput = getFinalOutput(r.messages);