@oldflag2333333/pi-subagent 0.1.3 → 0.1.5

package/README.md

@@ -164,26 +164,35 @@ These instructions apply only to your main Pi, not to its Subs. Keep shared proj
 
 ## Clean up deleted sessions
 
-Persistent Sub histories are grouped by their owning Main, using Pi's native `--session-dir`:
+Persistent Subs use Pi's native session store alongside ordinary sessions, with IDs of the form `sub-<UUID>`:
 
 ```text
-~/.pi/agent/subagent/sessions/<main-session-id>/*.jsonl
+~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_sub-<UUID>.jsonl
 ```
 
-Run `/clean-sub` to immediately delete both the Sub session directory and runtime communication directory for any Main ID no longer found among saved Pi sessions. It checks Pi's default session store and the current session directory, always preserves the current Main, and creates no index. Unreadable session files or invalid headers stop cleanup instead of being treated as deleted.
+Same-cwd Subs inherit Main's session directory (including `--session-dir` overrides); Subs launched in another cwd use Pi's normal storage for that cwd. Ephemeral Subs still use `--no-session`. Native `/resume` can discover saved Subs; `--continue` may therefore select a Sub if it is the most recent session.
 
-Close any orphaned Sub tabs before cleaning; the command only deletes files. Profiles and global settings are untouched. Older Sub files outside the managed directory still need manual deletion. If you moved Main files or use other custom session directories, make them available in the scanned locations before cleaning.
+Ownership is stored in both directions: Main's `subagent-run` custom entries record Sub IDs and paths, and each Sub's `subagent-owner` custom entry records its own ID and Main's ID and file path. These entries do not enter model context. Reloading or resuming does not duplicate unchanged ownership metadata.
+
+- `/clean-sub` permanently deletes orphaned Sub JSONL files across Pi's native session store and the current custom session directory, plus orphaned runtime communication directories. A Sub is orphaned when its recorded Main ID cannot be found. Recorded Main file paths also protect owners stored outside native discovery.
+- On Pi exit (`session_shutdown` with reason `quit`), the same cleanup runs automatically, limited to Subs whose session-header cwd matches the current cwd. Switching sessions, forking, and reloading do not trigger cleanup. Main existence is still checked across projects to protect cross-cwd Subs.
+- The current session/owning Main is always preserved, including unsaved sessions. Missing ownership metadata is preserved with a warning; unreadable files, invalid headers, or conflicting ownership abort cleanup before deletion. Shared session directories, ordinary sessions, profiles, and settings are never deleted. No separate index or legacy-storage migration is used.
+
+Close orphaned Sub tabs before cleaning; cleanup deletes files, not running agents. Custom stores other than the current session directory are not scanned for Sub files; run `/clean-sub` from those stores when needed.
 
 ## Things to know
 
 Messages use custom inbox cards and Pi’s native run preparation, without extra user-role wake messages. See [messaging behavior](docs/messaging.md).
 
 - **Herdr is required for Subs.** There is no headless fallback. Up to four Subs can be open at once, and Subs cannot delegate further.
+- **Subs cannot fork or clone.** `/fork` and `/clone` are cancelled in Sub tabs; Main sessions are unaffected.
 - **Profiles are not a sandbox.** Subs run as your OS user. A read-only role is not a filesystem permission boundary.
 - **MCP follows Pi's normal configuration.** Profiles select non-MCP tools; they do not isolate or filter MCP servers. Custom non-MCP tools must come from extensions already loaded in Main.
 - **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).
+
 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.
 
 To hide or show Pi Subagent Subs in Herdr's Agents panel, see the optional [Herdr companion plugin](herdr-plugin/README.md).

package/README.zh-CN.md

@@ -164,26 +164,35 @@ reviewer/
 
 ## 清理已删除会话的遗留文件
 
-持久化 Sub 使用 Pi 原生的 `--session-dir`，按所属 Main 分目录保存：
+持久化 Sub 与普通会话一起使用 Pi 原生会话目录，ID 格式为 `sub-<UUID>`：
 
 ```text
-~/.pi/agent/subagent/sessions/<main-session-id>/*.jsonl
+~/.pi/agent/sessions/<工作目录编码>/<timestamp>_sub-<UUID>.jsonl
 ```
 
-执行 `/clean-sub`，找不到对应 Main ID 时，立即删除它的 Sub 会话目录和运行时通信目录。命令检查 Pi 默认会话目录和当前会话目录，始终保留当前 Main，不新增索引。会话文件无法读取或文件头无效时会停止清理，不会将它们当作已删除。
+相同工作目录的 Sub 沿用 Main 的会话目录（包括 `--session-dir` 自定义目录）；指定其他工作目录时使用该目录对应的 Pi 常规存储。临时 Sub 仍使用 `--no-session`。原生 `/resume` 可以发现持久化 Sub；因此 `--continue` 也可能选中最近活动的 Sub。
 
-清理前请关闭遗留的 Sub 标签页，命令只删除文件。角色配置和全局设置不受影响；以前散落在专用目录之外的 Sub 文件仍需手动删除。如果移动过 Main 文件或使用其他自定义会话目录，请先确保这些会话位于扫描范围内，再执行清理。
+归属信息双向保存在 JSONL 中：Main 的 `subagent-run` 自定义条目记录 Sub ID 和文件路径；Sub 的 `subagent-owner` 自定义条目记录自身 ID、Main ID 和 Main 文件路径。这些条目不进入模型上下文，重载或恢复时不会重复写入未变化的归属信息。
+
+- `/clean-sub` 扫描 Pi 全局原生会话库及当前自定义会话目录，永久删除找不到所属 Main ID 的孤儿 Sub JSONL 文件，同时清理孤儿运行时通信目录。也会检查记录的 Main 文件路径，保护保存在扫描范围之外的 Main。
+- 退出 Pi 时（`session_shutdown` 的 `reason` 为 `quit`）自动执行清理，但只清理会话头中工作目录与当前目录相同的 Sub。切换会话、fork 和重载不触发清理；判断 Main 是否存在仍跨项目检查，避免误删跨目录委派的 Sub。
+- 始终保护当前会话或所属 Main，包括尚未保存的会话。缺失归属元数据的 Sub 会保留并警告；无法读取文件、会话头无效或归属冲突时，在删除前中止清理。不删除共享会话目录、普通会话、角色配置或设置。不新增独立索引，也不迁移旧存储。
+
+清理前请关闭孤儿 Sub 标签页；清理只删除文件，不关闭运行中的助手。当前会话目录之外的其他自定义存储不会被扫描 Sub 文件，需要从相应存储运行 `/clean-sub`。
 
 ## 使用须知
 
 助手间消息使用自定义收件卡片，由 Pi 原生处理启动准备，不再添加用户角色唤醒消息。详见[消息机制](docs/messaging.md)。
 
 - **子助手依赖 Herdr。** 不支持无界面后台运行；最多同时打开四个子助手，子助手不能继续委派。
+- **子助手不支持 fork 或 clone。** Sub 标签页中的 `/fork` 和 `/clone` 会被取消，不影响 Main 会话。
 - **角色配置不是沙箱。** 子助手以你的系统用户身份运行，配置“只读角色”不等于限制文件系统权限。
 - **MCP 沿用 Pi 的常规配置。** 角色只选择非 MCP 工具，不隔离或筛选 MCP 服务。自定义的非 MCP 工具必须来自主 Pi 已加载的扩展。
 - **子助手拥有独立对话。** 它会收到任务、角色配置和常规项目上下文，但不会收到主对话的聊天记录。请在任务中提供必要信息。
 - **重载主 Pi 不会关闭子助手。** 不再需要时请关闭标签页；异常崩溃后可能需要手动清理。
 
+新建或恢复子助手时，插件先发送一条短 shell 探针，并等待最多 60 秒确认它已执行，再提交完整 Pi 命令。这样可避免 macOS 上 shell 仍在初始化时，长命令（尤其是包含会话路径的 resume）被截断、末尾 Enter 丢失的问题。探针等待支持取消；启动失败会尝试关闭新建的标签页，不会向半截命令补发 Enter。参见 [Herdr 已知问题 #4950](https://github.com/herdrdev/herdr/issues/4950)。
+
 如果找不到角色或启动失败，先运行 `/profiles`，检查目录名与 `name` 是否一致、项目是否受信任，以及引用的工具、技能和扩展是否可用。如果提示 Herdr 不可用，请确认 Pi 正在 Herdr 工作区内运行。
 
 如需在 Herdr 的 Agents 面板中隐藏或显示 Pi Subagent 子助手，可安装可选的 [Herdr 配套插件](herdr-plugin/README.md)（英文说明）。

package/package.json

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

package/src/adapters/herdr.ts

@@ -1,9 +1,9 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { subSessionName } from "../manual-context.js";
 import { subCapabilityArgs } from "../profiles/launch-args.js";
-import { subSessionDir } from "../sessions.js";
 import type { SubAgentStatus, SubLaunchSpec, SubSurfaceAdapter, SurfaceHandle } from "../types.js";
 
 function parseEnvelope(stdout: string): Record<string, unknown> {
@@ -40,9 +40,9 @@ function subArgs(spec: SubLaunchSpec): string[] {
 		"--no-extensions",
 		"-e", spec.entryPath,
 		...(fs.existsSync(herdrIntegration) ? ["-e", herdrIntegration] : []),
-		...(spec.profile.sessionPersistence === "persistent" || spec.resumeSessionId
-			? ["--session-dir", subSessionDir(spec.mainSessionId)] : ["--no-session"]),
-		...(spec.resumeSessionId ? ["--session", spec.resumeSessionFile ?? spec.resumeSessionId] : []),
+		...(spec.profile.sessionPersistence === "persistent"
+			? (spec.sessionDir ? ["--session-dir", spec.sessionDir] : []) : ["--no-session"]),
+		...(spec.resumeSessionFile ? ["--session", spec.resumeSessionFile] : ["--session-id", spec.sessionId]),
 		spec.projectTrusted ? "--approve" : "--no-approve",
 		"--name", subSessionName(safeLabel(spec.title), spec.origin),
 		...subCapabilityArgs(spec.profile, spec.entryPath),
@@ -99,6 +99,16 @@ export class HerdrTabAdapter implements SubSurfaceAdapter {
 		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.");
 			const name = agentName(spec.runId);
 			await step([
 				"agent", "start", name, "--kind", "pi", "--pane", paneId, "--timeout", "60000", "--", ...subArgs(spec),

package/src/channel.ts

@@ -100,6 +100,7 @@ export function readManifest(channelDir: string): DelegateManifest {
 	const value = record(readJson(path.join(channelDir, "manifest.json")));
 	if (!value || value.version !== 1 || typeof value.runId !== "string" || typeof value.mainSessionId !== "string"
 		|| typeof value.title !== "string" || typeof value.task !== "string" || typeof value.cwd !== "string"
+		|| (value.mainSessionFile !== undefined && (typeof value.mainSessionFile !== "string" || !path.isAbsolute(value.mainSessionFile)))
 		|| (value.origin !== undefined && value.origin !== "manual")
 		|| !validProfile(value.profile) || typeof value.token !== "string" || typeof value.createdAt !== "number") {
 		throw new Error("Invalid Pi Subagent channel manifest.");

package/src/commands/clean-sub.ts

@@ -1,8 +1,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createInterface } from "node:readline";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { channelPath, runtimeRoot } from "../channel.js";
-import { subSessionDir, subSessionsRoot } from "../sessions.js";
+import { channelPath, readManifest, runtimeRoot } from "../channel.js";
+import { parseSubSessionOwner, SUB_OWNER_ENTRY, SUB_SESSION_ID, type SubSessionOwner } from "../sessions.js";
+
+interface SavedSession {
+	file: string;
+	id: string;
+	cwd: string;
+	owner?: SubSessionOwner;
+}
+
+interface CleanupResult {
+	removed: number;
+	removedChannels: number;
+	errors: string[];
+}
 
 function entries(directory: string): fs.Dirent[] {
 	try { return fs.readdirSync(directory, { withFileTypes: true }); }
@@ -12,74 +26,137 @@ function entries(directory: string): fs.Dirent[] {
 	}
 }
 
-/** Read only the header; never load transcripts or treat an unreadable session as deleted. */
-function sessionId(file: string): string {
-	const fd = fs.openSync(file, "r");
+function sessionDirectories(currentSessionDir: string): string[] {
+	const root = path.join(getAgentDir(), "sessions");
+	const directories = new Set([root, ...(currentSessionDir ? [path.resolve(currentSessionDir)] : [])]);
+	for (const entry of entries(root)) {
+		if (entry.isDirectory() || entry.isSymbolicLink()) directories.add(path.join(root, entry.name));
+	}
+	return [...directories];
+}
+
+/** Read headers only for Mains; stream Sub ownership without loading transcripts into memory. */
+async function inspectSession(file: string, scopeCwd?: string, headerOnly = false): Promise<SavedSession | undefined> {
+	const input = fs.createReadStream(file, { encoding: "utf8" });
+	const lines = createInterface({ input, crlfDelay: Infinity });
+	let session: SavedSession | undefined;
 	try {
-		const buffer = Buffer.alloc(64 * 1024);
-		const length = fs.readSync(fd, buffer, 0, buffer.length, 0);
-		const text = buffer.subarray(0, length).toString("utf8");
-		const header = JSON.parse(text.split("\n", 1)[0]!);
-		if (header?.type !== "session" || typeof header.id !== "string" || !header.id) throw new Error("Invalid session header");
-		return header.id;
+		for await (const line of lines) {
+			if (!session) {
+				const header = JSON.parse(line);
+				if (header?.type !== "session" || typeof header.id !== "string" || !header.id
+					|| typeof header.cwd !== "string" || !path.isAbsolute(header.cwd)) throw new Error("Invalid session header");
+				session = { file, id: header.id, cwd: header.cwd };
+				if (headerOnly || !SUB_SESSION_ID.test(session.id) || (scopeCwd && path.resolve(session.cwd) !== scopeCwd)) break;
+				continue;
+			}
+			if (!line.includes(SUB_OWNER_ENTRY)) continue;
+			const entry = JSON.parse(line);
+			if (entry?.type !== "custom" || entry.customType !== SUB_OWNER_ENTRY) continue;
+			const owner = parseSubSessionOwner(entry.data);
+			if (owner.subSessionId !== session.id || owner.mainSessionId === session.id
+				|| (owner.mainSessionFile !== undefined && !path.isAbsolute(owner.mainSessionFile))) throw new Error("Invalid Sub session ownership");
+			if (session.owner && session.owner.mainSessionId !== owner.mainSessionId) {
+				throw new Error("Conflicting Sub session owners");
+			}
+			session.owner = owner;
+		}
+		if (!session) throw new Error("Missing session header");
+		return session;
 	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
 		throw new Error(`Cannot inspect session ${file}: ${error instanceof Error ? error.message : String(error)}`);
-	} finally { fs.closeSync(fd); }
+	} finally {
+		lines.close();
+		input.destroy();
+	}
 }
 
-export function cleanSubFiles(currentMainId: string, currentSessionDir: string): { removed: number; errors: string[] } {
-	const stores = [
-		{ root: runtimeRoot(), ownerDirectory: (id: string) => path.basename(path.dirname(channelPath(id, "unused"))) },
-		{ root: subSessionsRoot(), ownerDirectory: (id: string) => path.basename(subSessionDir(id)) },
-	].map((store) => {
-		const candidates = entries(store.root).filter((entry) => entry.isDirectory());
-		if (candidates.length && fs.lstatSync(store.root).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${store.root}`);
-		return { ...store, candidates };
-	});
-	if (stores.every((store) => store.candidates.length === 0)) return { removed: 0, errors: [] };
-
-	const sessionsRoot = path.join(getAgentDir(), "sessions");
-	const directories = new Set([sessionsRoot]);
-	if (currentSessionDir) directories.add(currentSessionDir);
-	for (const entry of entries(sessionsRoot)) {
-		const file = path.join(sessionsRoot, entry.name);
-		if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(file).isDirectory())) directories.add(file);
+/** Global discovery establishes Main liveness even when only one cwd is being cleaned. */
+export async function cleanSubFiles(currentSessionId: string, currentSessionDir: string, cwd?: string): Promise<CleanupResult> {
+	const scopeCwd = cwd ? path.resolve(cwd) : undefined;
+	const live = new Set([currentSessionId]); // Includes unsaved/in-memory current sessions.
+	const sessions: SavedSession[] = [];
+	const errors: string[] = [];
+	const ownerFiles = new Map<string, string>();
+	for (const directory of sessionDirectories(currentSessionDir)) {
+		const files = entries(directory);
+		if (files.length && fs.lstatSync(directory).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${directory}`);
+		for (const entry of files) {
+			if (!entry.name.endsWith(".jsonl")) continue;
+			const file = path.join(directory, entry.name);
+			// A linked Main still establishes liveness, but links are never deletion targets.
+			const session = await inspectSession(file, scopeCwd);
+			if (!session) continue;
+			live.add(session.id);
+			if (session.owner?.mainSessionFile) ownerFiles.set(session.owner.mainSessionFile, session.owner.mainSessionId);
+			if (entry.isFile() && SUB_SESSION_ID.test(session.id) && (!scopeCwd || path.resolve(session.cwd) === scopeCwd)) {
+				if (session.owner) sessions.push(session);
+				else errors.push(`Preserved Sub without owner metadata: ${file}`);
+			}
+		}
 	}
-	const live = new Set([currentMainId]);
-	// Complete discovery before deleting anything. A read/parse error aborts cleanup.
-	for (const directory of directories) {
-		for (const entry of entries(directory)) {
-			if (entry.name.endsWith(".jsonl")) live.add(sessionId(path.join(directory, entry.name)));
+
+	const channels: Array<{ directory: string; mainSessionId: string }> = [];
+	const runtime = runtimeRoot();
+	const owners = entries(runtime);
+	if (owners.length && fs.lstatSync(runtime).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${runtime}`);
+	for (const owner of owners) {
+		if (!owner.isDirectory()) continue;
+		const ownerDir = path.join(runtime, owner.name);
+		for (const run of entries(ownerDir)) {
+			if (!run.isDirectory()) continue;
+			const directory = path.join(ownerDir, run.name);
+			const manifest = readManifest(directory);
+			if (path.resolve(channelPath(manifest.mainSessionId, manifest.runId)) !== path.resolve(directory)) throw new Error(`Invalid channel identity: ${directory}`);
+			if (scopeCwd && path.resolve(manifest.cwd) !== scopeCwd) continue;
+			if (manifest.mainSessionFile) ownerFiles.set(manifest.mainSessionFile, manifest.mainSessionId);
+			channels.push({ directory, mainSessionId: manifest.mainSessionId });
 		}
 	}
+	// Recorded paths also protect Mains using a custom store outside native discovery.
+	for (const [file, id] of ownerFiles) {
+		if (live.has(id)) continue;
+		const main = await inspectSession(file, undefined, true);
+		if (main?.id === id) live.add(id);
+	}
+
 	let removed = 0;
-	const errors: string[] = [];
-	for (const store of stores) {
-		const liveDirectories = new Set([...live].map(store.ownerDirectory));
-		for (const entry of store.candidates) {
-			if (liveDirectories.has(entry.name)) continue;
-			const directory = path.join(store.root, entry.name);
-			try {
-				// Do not follow a directory replaced with a symlink during discovery.
-				if (!fs.lstatSync(directory).isDirectory()) continue;
-				fs.rmSync(directory, { recursive: true, force: true });
-				removed++;
-			} catch (error) {
-				errors.push(`${directory}: ${error instanceof Error ? error.message : String(error)}`);
-			}
+	let removedChannels = 0;
+	// Discovery must finish successfully before any destructive operation.
+	for (const session of sessions) {
+		if (session.id === currentSessionId || live.has(session.owner!.mainSessionId)) continue;
+		try {
+			if (!fs.lstatSync(session.file).isFile()) continue;
+			fs.unlinkSync(session.file);
+			removed++;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push(`${session.file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	for (const channel of channels) {
+		if (live.has(channel.mainSessionId)) continue;
+		try {
+			if (!fs.lstatSync(channel.directory).isDirectory()) continue;
+			fs.rmSync(channel.directory, { recursive: true, force: true });
+			removedChannels++;
+			try { fs.rmdirSync(path.dirname(channel.directory)); }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOTEMPTY" && (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push(`${channel.directory}: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
-	return { removed, errors };
+	return { removed, removedChannels, errors };
 }
 
-export function registerCleanSubCommand(pi: ExtensionAPI): void {
+export function registerCleanSubCommand(pi: ExtensionAPI, owningMainId?: string): void {
 	pi.registerCommand("clean-sub", {
-		description: "Delete managed Sub sessions and communication directories whose Main session can no longer be found.",
+		description: "Delete orphaned Sub sessions across Pi's native session store and orphaned communication files.",
 		handler: async (_args, ctx) => {
 			try {
-				const result = cleanSubFiles(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
+				const result = await cleanSubFiles(owningMainId ?? ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
 				ctx.ui.notify([
-					`Removed ${result.removed} orphaned Sub data directories (sessions and communication).`,
+					`Removed ${result.removed} orphaned Sub sessions and ${result.removedChannels} communication directories.`,
 					...result.errors,
 				].join("\n"), result.errors.length ? "warning" : "info");
 			} catch (error) {
@@ -87,4 +164,13 @@ export function registerCleanSubCommand(pi: ExtensionAPI): void {
 			}
 		},
 	});
+	pi.on("session_shutdown", async (event, ctx) => {
+		if (event.reason !== "quit") return;
+		try {
+			const result = await cleanSubFiles(owningMainId ?? ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir(), ctx.cwd);
+			if (result.errors.length) ctx.ui.notify(`Sub cleanup: ${result.errors.join("\n")}`, "warning");
+		} catch (error) {
+			ctx.ui.notify(`Sub cleanup aborted: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
+	});
 }

package/src/run-manager.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { AdapterRegistry } from "./adapters/index.js";
@@ -189,11 +190,16 @@ export class MainRunManager {
 		}
 		const runId = randomUUID();
 		const mainSessionId = this.ctx.sessionManager.getSessionId();
+		const mainSessionFile = this.ctx.sessionManager.getSessionFile();
+		const subSessionId = resume?.sessionId ?? `sub-${randomUUID()}`;
 		const projectTrusted = this.ctx.isProjectTrusted();
 		const cwd = resume?.cwd ?? input.cwd;
+		const sessionDir = resume ? path.dirname(resume.sessionFile)
+			: path.resolve(cwd) === path.resolve(this.ctx.cwd) ? this.ctx.sessionManager.getSessionDir() : undefined;
 		const channel = createChannel({
 			runId,
 			mainSessionId,
+			...(mainSessionFile ? { mainSessionFile } : {}),
 			title: input.title,
 			task: input.task,
 			cwd,
@@ -212,7 +218,8 @@ export class MainRunManager {
 			channelDir: channel.channelDir,
 			createdAt: Date.now(),
 			updatedAt: Date.now(),
-			...(resume ? { subSessionId: resume.sessionId, subSessionFile: resume.sessionFile } : {}),
+			subSessionId,
+			...(resume ? { subSessionFile: resume.sessionFile } : {}),
 		};
 		try {
 			this.save(run);
@@ -226,7 +233,9 @@ export class MainRunManager {
 				cwd,
 				projectTrusted,
 				...(input.origin ? { origin: input.origin } : {}),
-				...(resume ? { resumeSessionId: resume.sessionId, resumeSessionFile: resume.sessionFile } : {}),
+				sessionId: subSessionId,
+				sessionDir,
+				...(resume ? { resumeSessionFile: resume.sessionFile } : {}),
 				profile: input.profile,
 				channelDir: channel.channelDir,
 				token: channel.token,

package/src/sessions.ts

@@ -1,15 +1,43 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { RunSnapshot } from "./types.js";
 
-export function subSessionsRoot(): string {
-	return path.join(getAgentDir(), "subagent", "sessions");
+export const SUB_OWNER_ENTRY = "subagent-owner";
+export const SUB_SESSION_ID = /^sub-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export interface SubSessionOwner {
+	version: 1;
+	subSessionId: string;
+	mainSessionId: string;
+	mainSessionFile?: string;
+}
+
+export function parseSubSessionOwner(value: unknown): SubSessionOwner {
+	const owner = value as Partial<SubSessionOwner> | undefined;
+	if (!owner || owner.version !== 1 || typeof owner.subSessionId !== "string"
+		|| typeof owner.mainSessionId !== "string" || !owner.mainSessionId
+		|| (owner.mainSessionFile !== undefined && typeof owner.mainSessionFile !== "string")) {
+		throw new Error("Invalid Sub session owner metadata.");
+	}
+	return owner as SubSessionOwner;
 }
 
-export function subSessionDir(mainSessionId: string): string {
-	if (!mainSessionId || mainSessionId === "." || mainSessionId === "..") throw new Error("Invalid Main session ID.");
-	return path.join(subSessionsRoot(), encodeURIComponent(mainSessionId));
+/** Ownership is session-wide, not branch-relative. Never silently reassign a Sub. */
+export function recordSubSessionOwner(pi: ExtensionAPI, ctx: ExtensionContext, mainSessionId: string, mainSessionFile?: string): void {
+	const subSessionId = ctx.sessionManager.getSessionId();
+	const entries = ctx.sessionManager.getEntries().filter((entry): entry is SessionEntry & { type: "custom" } =>
+		entry.type === "custom" && entry.customType === SUB_OWNER_ENTRY);
+	let previous: SubSessionOwner | undefined;
+	for (const entry of entries) {
+		const owner = parseSubSessionOwner(entry.data);
+		if (owner.subSessionId !== subSessionId || owner.mainSessionId !== mainSessionId) {
+			throw new Error("Sub session owner does not match this Main.");
+		}
+		previous = owner;
+	}
+	if (!previous || previous.mainSessionFile !== mainSessionFile) {
+		pi.appendEntry(SUB_OWNER_ENTRY, { version: 1, subSessionId, mainSessionId, ...(mainSessionFile ? { mainSessionFile } : {}) } satisfies SubSessionOwner);
+	}
 }
 
 export interface ResumableSubSession {

package/src/tools/sub.ts

@@ -21,6 +21,8 @@ import { applyProfileTools } from "../profiles/tool-selection.js";
 import { MANUAL_SUB_GUIDANCE, subSessionName } from "../manual-context.js";
 import { talkView } from "../talk-render.js";
 import { ChannelMonitor } from "../channel-monitor.js";
+import { recordSubSessionOwner } from "../sessions.js";
+import { registerCleanSubCommand } from "../commands/clean-sub.js";
 import { bindInboxEvents } from "../inbox-state.js";
 import { deliverTalk, ProtocolErrors } from "../talk-delivery.js";
 import type { ActiveTurn, DelegateManifest } from "../types.js";
@@ -61,6 +63,12 @@ export function registerSub(pi: ExtensionAPI): void {
 	);
 	bindInboxEvents(pi, () => activeContext, () => monitor.wakeAll());
 
+	// Fork/clone would copy ownership metadata into a different session.
+	pi.on("session_before_fork", (_event, ctx) => {
+		ctx.ui.notify("Sub sessions do not support /fork or /clone.", "warning");
+		return { cancel: true };
+	});
+
 	// Pi emits resource discovery after all session_start handlers, including
 	// extensions that register the profile's tools dynamically during startup.
 	pi.on("resources_discover", (_event, ctx) => {
@@ -77,6 +85,7 @@ export function registerSub(pi: ExtensionAPI): void {
 
 	pi.on("session_start", (_event, ctx) => {
 		activeContext = ctx;
+		recordSubSessionOwner(pi, ctx, loaded.manifest.mainSessionId, loaded.manifest.mainSessionFile);
 		pi.setSessionName(subSessionName(loaded.manifest.title, loaded.manifest.origin));
 		ctx.ui.setTitle(`[sub] ${loaded.manifest.title}`);
 		ctx.ui.setStatus("subagent", `sub · ${loaded.manifest.profile.name}`);
@@ -212,4 +221,6 @@ export function registerSub(pi: ExtensionAPI): void {
 			writeSubClosed(loaded.channelDir, loaded.manifest, "The Sub session was closed manually.");
 		}
 	});
+	// Run after the Sub shutdown protocol, and preserve its still-active owning Main.
+	registerCleanSubCommand(pi, loaded.manifest.mainSessionId);
 }

package/src/types.ts

@@ -4,6 +4,7 @@ export interface DelegateManifest {
 	version: 1;
 	runId: string;
 	mainSessionId: string;
+	mainSessionFile?: string;
 	title: string;
 	task: string;
 	cwd: string;
@@ -96,8 +97,9 @@ export interface SubLaunchSpec {
 	cwd: string;
 	projectTrusted: boolean;
 	origin?: "manual";
-	resumeSessionId?: string;
-	/** Recorded path also supports sessions saved before per-Main directories. */
+	sessionId: string;
+	/** Same-cwd Subs inherit Main's session directory, including custom stores. */
+	sessionDir?: string;
 	resumeSessionFile?: string;
 	profile: ResolvedProfile;
 	channelDir: string;