@oldflag2333333/pi-subagent 0.1.6 → 0.1.7

package/README.md

@@ -191,7 +191,9 @@ Messages use custom inbox cards and Pi’s native run preparation, without extra
 - **Subs have separate conversations.** They receive their task, profile, and normal project context—not Main's chat history. Include the details they need in the task.
 - **Reloading Main does not close Subs.** Close tabs you no longer need. Hard crashes may require manual cleanup.
 
-Before a fresh or resumed Sub launch, the plugin submits a short shell probe and waits up to 60 seconds for it to execute before submitting the full Pi command. This avoids macOS truncating long commands (especially resume paths) and dropping Enter while the shell is still initializing. The wait is cancellable; launch failure attempts to close the new tab rather than sending Enter to a partial command. See [Herdr issue #4950](https://github.com/herdrdev/herdr/issues/4950).
+Fresh and resumed Subs start from a private `0600` POSIX shell script in their existing runtime communication directory. The terminal receives only the fixed short command `sh "$PI_SUBAGENT_LAUNCH"`; the script path travels through the tab environment, and Pi's full arguments are read from the file. No shell probe or long terminal input is needed, avoiding the macOS canonical line-input limit even while the shell initializes. The plugin waits up to 60 seconds for the expected Pi in the same pane and terminal to become idle before naming it and submitting the task. Startup remains cancellable, and failures attempt to close the new tab. See [Herdr issue #4950](https://github.com/herdrdev/herdr/issues/4950).
+
+The script unlinks itself after the shell opens it; Main also removes it once Pi is ready or a launch fails, times out, or is cancelled—even if tab rollback fails. Each new launch reclaims leftover launch scripts at least five minutes old only when their creator process is confirmed gone. Live processes, uncertain liveness, symlinks, unrelated files, and communication directories are preserved. Failures to inspect or remove abandoned scripts are warned about and skipped without blocking new launches or the rest of the sweep. Normal channel cleanup is unchanged; script cleanup does not depend on the operating system purging temporary files.
 
 If a profile is missing or fails to start, run `/profiles` first. Check its directory/name match, project trust, and any referenced tools, skills, or extensions. If Herdr is unavailable, confirm Pi is running inside a Herdr workspace.
 

package/README.zh-CN.md

@@ -191,7 +191,9 @@ reviewer/
 - **子助手拥有独立对话。** 它会收到任务、角色配置和常规项目上下文，但不会收到主对话的聊天记录。请在任务中提供必要信息。
 - **重载主 Pi 不会关闭子助手。** 不再需要时请关闭标签页；异常崩溃后可能需要手动清理。
 
-新建或恢复子助手时，插件先发送一条短 shell 探针，并等待最多 60 秒确认它已执行，再提交完整 Pi 命令。这样可避免 macOS 上 shell 仍在初始化时，长命令（尤其是包含会话路径的 resume）被截断、末尾 Enter 丢失的问题。探针等待支持取消；启动失败会尝试关闭新建的标签页，不会向半截命令补发 Enter。参见 [Herdr 已知问题 #4950](https://github.com/herdrdev/herdr/issues/4950)。
+新建或恢复子助手时，插件会在已有的运行通信目录中创建权限为 `0600` 的私有 POSIX shell 启动脚本。终端只接收固定短命令 `sh "$PI_SUBAGENT_LAUNCH"`，脚本路径通过标签页环境变量传入，完整 Pi 参数从文件读取。不再使用 shell 探针，也不再向终端输入长行，因此即使 shell 仍在初始化，也不会触发 macOS 的 canonical 行输入长度限制。插件等待最多 60 秒，确认同一 pane 和 terminal 中检测到的 Pi 已进入空闲状态，再命名并提交任务。等待支持取消，启动失败会尝试关闭新建标签页。参见 [Herdr 已知问题 #4950](https://github.com/herdrdev/herdr/issues/4950)。
+
+脚本在被 shell 打开后自行删除；Main 也会在 Pi 就绪或启动失败、超时、取消时兜底删除，即使标签页关闭失败也会尝试回收。每次新启动还会回收已超过 5 分钟、且创建进程确认不存在的残留启动脚本；仍存活的进程、存活状态不明的进程、符号链接、其他文件和通信目录不会被扫描清理逻辑删除。检查或删除遗留脚本失败时会输出警告并跳过，不会阻塞新启动或其他条目的回收。原有通信目录的生命周期保持不变，脚本回收不依赖操作系统定期清空临时目录。
 
 如果找不到角色或启动失败，先运行 `/profiles`，检查目录名与 `name` 是否一致、项目是否受信任，以及引用的工具、技能和扩展是否可用。如果提示 Herdr 不可用，请确认 Pi 正在 Herdr 工作区内运行。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oldflag2333333/pi-subagent",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Reusable specialist profiles and independent sub-agents for Pi",
   "type": "module",
   "license": "MIT",

package/src/adapters/herdr.ts

@@ -1,9 +1,10 @@
-import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { subSessionName } from "../manual-context.js";
 import { subCapabilityArgs } from "../profiles/launch-args.js";
+import { LAUNCH_COMMAND, launchScriptContent, launchScriptPath, reapAbandonedLaunchScripts } from "./launch-script.js";
 import type { SubAgentStatus, SubLaunchSpec, SubSurfaceAdapter, SurfaceHandle } from "../types.js";
 
 function parseEnvelope(stdout: string): Record<string, unknown> {
@@ -70,6 +71,8 @@ export class HerdrTabAdapter implements SubSurfaceAdapter {
 		const workspaceId = process.env.HERDR_WORKSPACE_ID;
 		if (!workspaceId) throw new Error("HERDR_WORKSPACE_ID is unavailable; Pi is not running in a Herdr workspace.");
 		signal?.throwIfAborted();
+		reapAbandonedLaunchScripts();
+		const launcher = launchScriptPath(spec.channelDir);
 		const label = `↳ pi · ${safeLabel(spec.title)}`;
 		const created = await this.pi.exec("herdr", [
 			"tab", "create",
@@ -79,6 +82,7 @@ export class HerdrTabAdapter implements SubSurfaceAdapter {
 			"--env", "PI_SUBAGENT_ROLE=sub",
 			"--env", `PI_SUBAGENT_CHANNEL=${spec.channelDir}`,
 			"--env", `PI_SUBAGENT_TOKEN=${spec.token}`,
+			"--env", `PI_SUBAGENT_LAUNCH=${launcher}`,
 			"--no-focus",
 		], { timeout: 15_000, signal });
 		let payload: Record<string, unknown>;
@@ -90,29 +94,34 @@ export class HerdrTabAdapter implements SubSurfaceAdapter {
 		const paneId = nestedString(payload, "root_pane", "pane_id") ?? nestedString(payload, "pane", "pane_id");
 		if (!tabId) throw new Error("Herdr tab creation response did not contain a tab ID; automatic cleanup is unavailable.");
 		const handle: SurfaceHandle = { adapter: "herdr", tabId, ...(paneId ? { paneId } : {}) };
+		const terminalId = nestedString(payload, "root_pane", "terminal_id") ?? nestedString(payload, "pane", "terminal_id");
+		let launcherOwned = false;
+		const removeLauncher = () => {
+			if (!launcherOwned) return;
+			fs.rmSync(launcher, { force: true });
+			launcherOwned = false;
+		};
 		const step = async (args: string[], timeout: number, failure: string) => {
 			signal?.throwIfAborted();
 			const result = await this.pi.exec("herdr", args, { timeout, signal });
-			if (result.code !== 0 || result.killed) throw new Error(result.stderr || failure);
 			signal?.throwIfAborted();
+			if (result.code !== 0 || result.killed) throw new Error(result.stderr || failure);
 		};
 		try {
 			if (created.code !== 0 || created.killed) throw new Error(created.stderr || "Failed to create Herdr tab.");
 			if (!paneId) throw new Error("Herdr tab creation response did not contain a root pane ID.");
-			// A new pane's shell can still be initializing in canonical mode.
-			// On macOS a long launch line can lose its tail (including Enter).
-			// Execute a short probe first; match only its output, never the echoed
-			// command. Unwrapped rows keep a wrapped command from matching early.
-			const readyMarker = `pi-subagent-shell-ready-${randomUUID()}`;
-			await step(["pane", "run", paneId, `echo ${readyMarker}`], 10_000, "Failed to probe the Sub shell.");
-			await step([
-				"pane", "wait-output", paneId, "--regex", `^${readyMarker}$`,
-				"--source", "recent-unwrapped", "--timeout", "60000",
-			], 65_000, "The Sub shell did not become ready.");
+			// The file is private and exclusive; even a partial write is owned and
+			// cleaned up on failure. Its path travels via tab env, not PTY input.
+			const fd = fs.openSync(launcher, "wx", 0o600);
+			launcherOwned = true;
+			try { fs.writeFileSync(fd, launchScriptContent(subArgs(spec)), "utf8"); }
+			finally { fs.closeSync(fd); }
+			await step(["pane", "run", paneId, LAUNCH_COMMAND], 10_000, "Failed to launch Sub Pi in Herdr tab.");
+			await this.waitForPi(handle, terminalId, signal);
+			// pane run only acknowledges admission; never unlink on that alone.
+			removeLauncher();
 			const name = agentName(spec.runId);
-			await step([
-				"agent", "start", name, "--kind", "pi", "--pane", paneId, "--timeout", "60000", "--", ...subArgs(spec),
-			], 70_000, "Failed to start Sub Pi in Herdr tab.");
+			await step(["agent", "rename", paneId, name], 10_000, "Failed to name the Sub Pi agent.");
 			await step([
 				"pane", "report-metadata", paneId, "--source", "subagent",
 				"--token", "subagent_role=sub", "--token", `subagent_main_session=${spec.mainSessionId}`,
@@ -121,16 +130,53 @@ export class HerdrTabAdapter implements SubSurfaceAdapter {
 			await step(["agent", "prompt", name, spec.task], 20_000, "Failed to submit the delegated task to the Herdr agent.");
 			return handle;
 		} catch (error) {
+			let rollback: unknown;
 			try {
 				// Rollback must not inherit the cancellation that caused the failure.
 				await this.close(handle);
-			} catch (cleanup) {
-				throw new HerdrLaunchCleanupError(handle, error, cleanup);
+			} catch (cleanup) { rollback = cleanup; }
+			try { removeLauncher(); }
+			catch (cleanup) {
+				error = new AggregateError([error, cleanup], `Sub launch failed: ${error instanceof Error ? error.message : String(error)}. Launch script cleanup also failed (${launcher}): ${cleanup instanceof Error ? cleanup.message : String(cleanup)}.`, { cause: error });
 			}
+			if (rollback) throw new HerdrLaunchCleanupError(handle, error, rollback);
 			throw error;
 		}
 	}
 
+	private async waitForPi(handle: SurfaceHandle, terminalId: string | undefined, signal?: AbortSignal): Promise<void> {
+		const deadline = Date.now() + 60_000;
+		while (true) {
+			signal?.throwIfAborted();
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) throw new Error("Sub Pi did not become ready within 60 seconds.");
+			const response = await this.pi.exec("herdr", ["agent", "get", handle.paneId!], { timeout: Math.min(3000, remaining), signal });
+			signal?.throwIfAborted();
+			if (Date.now() >= deadline) throw new Error("Sub Pi did not become ready within 60 seconds.");
+			if (response.killed) throw new Error(response.stderr || "Herdr agent readiness check was interrupted.");
+			let payload: Record<string, unknown>;
+			try { payload = parseEnvelope(`${response.stdout}\n${response.stderr}`); }
+			catch (error) { throw new Error(response.stderr || "Invalid Herdr agent readiness response.", { cause: error }); }
+			if (response.code !== 0) {
+				if (nestedString(payload, "error", "code") !== "agent_not_found") {
+					throw new Error(response.stderr || "Failed to inspect the starting Sub Pi agent.");
+				}
+			} else {
+				const agent = payload.agent as Record<string, unknown> | undefined;
+				if (!agent || typeof agent !== "object") throw new Error("Herdr readiness response did not contain an agent.");
+				if (agent.pane_id !== handle.paneId || agent.tab_id !== handle.tabId
+					|| (terminalId && agent.terminal_id !== terminalId)) throw new Error("The Sub Pi terminal changed during startup.");
+				if (agent.agent && agent.agent !== "pi") throw new Error(`Expected Sub Pi, but Herdr detected ${agent.agent}.`);
+				if (agent.agent_status === "blocked") throw new Error("Sub Pi is blocked during startup and is not ready for prompts.");
+				// interactive_ready is a managed-agent-start-only field in Herdr.
+				// Unmanaged Pi readiness comes from its lifecycle hook or UI detector.
+				if (agent.agent === "pi" && !agent.launch_pending && (agent.agent_status === "idle" || agent.agent_status === "done")) return;
+			}
+			try { await delay(Math.max(0, Math.min(100, deadline - Date.now())), undefined, { signal }); }
+			catch (error) { signal?.throwIfAborted(); throw error; }
+		}
+	}
+
 	async status(handle: SurfaceHandle | undefined): Promise<SubAgentStatus> {
 		if (!handle?.paneId) return "unknown";
 		try {

package/src/adapters/launch-script.ts

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { runtimeRoot } from "../channel.js";
+
+// Only this fixed-size command crosses the PTY, never the path or Pi arguments.
+export const LAUNCH_COMMAND = 'sh "$PI_SUBAGENT_LAUNCH"';
+export const ABANDONED_LAUNCH_AGE_MS = 5 * 60_000;
+const LAUNCH_FILE = /^launch-([1-9]\d*)-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\.sh$/;
+
+export function launchScriptPath(channelDir: string): string {
+	return path.join(channelDir, `launch-${process.pid}-${randomUUID()}.sh`);
+}
+
+export function launchScriptContent(args: readonly string[]): string {
+	const quoted = args.map((arg) => `'${arg.replaceAll("'", "'\\''")}'`);
+	// The shell has opened the file by this point and can keep reading its FD
+	// after unlinking it. Self-removal also works if Main has already crashed.
+	return `#!/bin/sh\nrm -f -- "$0"\nunset PI_SUBAGENT_LAUNCH\nexec pi ${quoted.join(" ")}\n`;
+}
+
+function warnReapError(target: string, error: unknown): void {
+	if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+	console.warn(`Pi Subagent: abandoned launch script cleanup skipped (${target}): ${error instanceof Error ? error.message : String(error)}`);
+}
+
+function entries(directory: string): fs.Dirent[] {
+	try { return fs.readdirSync(directory, { withFileTypes: true }); }
+	catch (error) {
+		warnReapError(directory, error);
+		return [];
+	}
+}
+
+/** Best-effort sweep of expired launch files belonging to dead processes, never channels. */
+export function reapAbandonedLaunchScripts(root = runtimeRoot(), now = Date.now()): void {
+	// Directory entries, rather than stat-followed paths, keep symlinked trees
+	// out of the sweep. Each run's normal channel cleanup remains independent.
+	try { if (!fs.lstatSync(root).isDirectory()) return; }
+	catch (error) {
+		warnReapError(root, error);
+		return;
+	}
+	for (const owner of entries(root)) {
+		if (!owner.isDirectory()) continue;
+		const ownerDir = path.join(root, owner.name);
+		for (const run of entries(ownerDir)) {
+			if (!run.isDirectory()) continue;
+			const directory = path.join(ownerDir, run.name);
+			for (const entry of entries(directory)) {
+				const match = LAUNCH_FILE.exec(entry.name);
+				if (!entry.isFile() || !match) continue;
+				const file = path.join(directory, entry.name);
+				try {
+					const stat = fs.lstatSync(file);
+					if (!stat.isFile() || now - stat.mtimeMs < ABANDONED_LAUNCH_AGE_MS
+						|| (typeof process.getuid === "function" && stat.uid !== process.getuid())) continue;
+					const pid = Number(match[1]);
+					if (!Number.isSafeInteger(pid) || pid > 0x7fffffff) continue;
+					try { process.kill(pid, 0); }
+					catch (error) {
+						// EPERM and other ambiguous liveness failures must preserve it.
+						if ((error as NodeJS.ErrnoException).code === "ESRCH") fs.unlinkSync(file);
+					}
+				} catch (error) {
+					warnReapError(file, error);
+				}
+			}
+		}
+	}
+}