@oldflag2333333/pi-subagent 0.1.0 → 0.1.2

package/README.md

@@ -8,7 +8,7 @@ A **profile** defines a specialist's instructions, tools, and optional skills or
 
 ## Install
 
-You need **Node.js 22.19+**, **[Pi](https://pi.dev) 1.0.4+**, and **Herdr**. To launch specialists, run Pi inside a Herdr workspace with the `herdr` command available.
+You need **Node.js 22.19+**, **[Pi](https://pi.dev) 1.2.0+**, and **Herdr**. To launch specialists, run Pi inside a Herdr workspace with the `herdr` command available.
 
 ```bash
 pi install npm:@oldflag2333333/pi-subagent
@@ -75,7 +75,7 @@ Ask the reviewer profile to review src/auth for bugs and missing tests.
 | Check progress | Ask Pi to list its Subs, or open the specialist's Herdr tab |
 | Stop its current task without closing it | Ask Pi to interrupt the Sub |
 | Finish with a specialist | Ask Pi to close the Sub, or close its Herdr tab |
-| Remove communication files left by deleted Main sessions | `/clean-sub` |
+| Remove Sub sessions and communication files left by deleted Mains | `/clean-sub` |
 
 Within the same Main session, repeated `/sub:reviewer` commands reuse that profile's open Sub. If it is busy, your next task is queued. Finishing a task does not automatically close the tab.
 
@@ -145,12 +145,20 @@ These instructions apply only to your main Pi, not to its Subs. Keep shared proj
 
 ## Clean up deleted sessions
 
-Run `/clean-sub` to immediately delete runtime communication directories whose Main ID is no longer found among saved Pi sessions. It checks the default session store and the current session directory, always preserves the current Main, and creates no index. If session files cannot be read or their headers are invalid, cleanup stops rather than treating them as deleted.
+Persistent Sub histories are grouped by their owning Main, using Pi's native `--session-dir`:
 
-Persistent Sub `.jsonl` files are **not deleted**; remove them manually through Pi's session picker. Profiles and global settings are untouched. The command does not close Herdr tabs. If you moved Main files or use other custom session directories, make them available in the scanned locations before cleaning.
+```text
+~/.pi/agent/subagent/sessions/<main-session-id>/*.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.
+
+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.
 
 ## 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.
 - **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.

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 ## 安装
 
-需要 **Node.js 22.19+**、**[Pi](https://pi.dev) 1.0.4+** 和 **Herdr**。启动助手时，Pi 必须运行在 Herdr 工作区中，并且能调用 `herdr` 命令。
+需要 **Node.js 22.19+**、**[Pi](https://pi.dev) 1.2.0+** 和 **Herdr**。启动助手时，Pi 必须运行在 Herdr 工作区中，并且能调用 `herdr` 命令。
 
 ```bash
 pi install npm:@oldflag2333333/pi-subagent
@@ -75,7 +75,7 @@ mkdir -p ~/.pi/agent/subagent/profiles/reviewer
 | 查看进度 | 让 Pi 列出子助手，或打开助手的 Herdr 标签页 |
 | 停止当前任务，但保留助手会话 | 让 Pi 中断该子助手 |
 | 结束使用 | 让 Pi 关闭子助手，或手动关闭其 Herdr 标签页 |
-| 清理已删除 Main 遗留的通信文件 | `/clean-sub` |
+| 清理已删除 Main 遗留的 Sub 会话和通信文件 | `/clean-sub` |
 
 在同一个主会话（Main）中，多次调用 `/sub:reviewer` 会复用该角色已打开的子助手（Sub）。如果它正在工作，新任务会排队。任务完成后，标签页不会自动关闭。
 
@@ -145,12 +145,20 @@ reviewer/
 
 ## 清理已删除会话的遗留文件
 
-执行 `/clean-sub`，立即删除找不到对应 Main ID 的运行时通信目录。它检查 Pi 默认会话目录和当前会话目录，始终保留当前 Main，不新增索引文件。会话文件无法读取或文件头无效时会停止清理，不会将它们当作已删除。
+持久化 Sub 使用 Pi 原生的 `--session-dir`，按所属 Main 分目录保存：
 
-持久化 Sub 的 `.jsonl` **不会自动删除**，请通过 Pi 的会话列表手动删除。角色配置和全局设置不受影响，命令也不会关闭 Herdr 标签页。如果移动过 Main 文件或使用其他自定义会话目录，请先确保这些会话位于扫描范围内，再执行清理。
+```text
+~/.pi/agent/subagent/sessions/<main-session-id>/*.jsonl
+```
+
+执行 `/clean-sub`，找不到对应 Main ID 时，立即删除它的 Sub 会话目录和运行时通信目录。命令检查 Pi 默认会话目录和当前会话目录，始终保留当前 Main，不新增索引。会话文件无法读取或文件头无效时会停止清理，不会将它们当作已删除。
+
+清理前请关闭遗留的 Sub 标签页，命令只删除文件。角色配置和全局设置不受影响；以前散落在专用目录之外的 Sub 文件仍需手动删除。如果移动过 Main 文件或使用其他自定义会话目录，请先确保这些会话位于扫描范围内，再执行清理。
 
 ## 使用须知
 
+助手间消息使用自定义收件卡片，由 Pi 原生处理启动准备，不再添加用户角色唤醒消息。详见[消息机制](docs/messaging.md)。
+
 - **子助手依赖 Herdr。** 不支持无界面后台运行；最多同时打开四个子助手，子助手不能继续委派。
 - **角色配置不是沙箱。** 子助手以你的系统用户身份运行，配置“只读角色”不等于限制文件系统权限。
 - **MCP 沿用 Pi 的常规配置。** 角色只选择非 MCP 工具，不隔离或筛选 MCP 服务。自定义的非 MCP 工具必须来自主 Pi 已加载的扩展。
@@ -169,4 +177,4 @@ npm run check
 pi -e ./src/index.ts
 ```
 
-维护者可参考[发布指南](docs/releasing.md)（英文），了解 CI 和 npm 自动发布流程。
+维护者可参考[发布指南](docs/releasing.zh-CN.md)，了解首次 npm 发布、Trusted Publisher 配置和后续自动发布流程。

package/docs/messaging.md

@@ -0,0 +1,17 @@
+# Message delivery and rendering
+
+Pi Subagent requires **Pi 1.2.0 or newer**. Main ↔ Sub messages use `pi.sendMessage()` with `deliverAs: "followUp"` and `triggerTurn: true` in both directions:
+
+- **Busy receiver:** Pi queues the custom message behind its current work.
+- **Idle receiver:** Pi prepares and starts the run, including `before_agent_start`, the tool loadout, and prompt sections. The event has `messageType: "custom"`, with the starting `message` rather than a user `prompt`.
+
+There are no synthetic user-role wake messages, version fallbacks, or patches to Pi internals. Custom messages do not pass through user-input processing or execute peer text as slash commands or templates.
+
+## Delivery guarantees
+
+- `content` carries the peer message and routing instructions; `details` carries rendering and receipt metadata and is not sent to the model.
+- Custom cards retain their title, collapsed/expanded rendering, and saved-session rendering.
+- A message file is removed only after its receipt appears in the receiving session. Existing user-message receipts remain recognized to avoid redelivery of saved messages; this is data compatibility, not support for older Pi runtimes.
+- In-flight message IDs prevent duplicate submission. Synchronous submission failures leave the file retryable. Pi owns run preparation and queueing; the plugin does not keep a separate wake reservation or retry timer.
+
+Pi 1.2.0 includes the native custom-message preparation fix in [#10739](https://github.com/earendil-works/pi/pull/10739), resolving [#5581](https://github.com/earendil-works/pi/issues/5581) and [#10267](https://github.com/earendil-works/pi/issues/10267). Real SDK regression tests require profile sections to remain present on the first idle delivery, subsequent turns, busy follow-ups, and after reload. No upstream TODO or workaround is retained.

package/docs/releasing.md

@@ -1,61 +1,72 @@
 # Releasing Pi Subagent
 
-Maintainer guide. For installation and usage, see the [README](../README.md).
+English | [简体中文](releasing.zh-CN.md)
 
-## CI and automatic npm releases
+## What CI does
 
-GitHub Actions runs type checks, tests, package metadata validation, and a packaging dry run for pull requests and pushes to `main` and `dev`, on Node.js 22.19 and 24.
+`.github/workflows/release.yml` runs on PRs and pushes to `main`/`dev`, and through **Actions → CI and Release → Run workflow**.
 
-A **version increase in `package.json` pushed to `main`** releases automatically after both check jobs pass:
+- Type checks and tests on Node **22.19.0** and **24**.
+- Package/lockfile validation and an npm packaging dry run.
+- The Node 24 job uploads a `.tgz` as `npm-package-<commit SHA>` (retained for 14 days).
+- Only a **version increase pushed to `main` in `oldflag2333333/pi-subagent`** triggers publication, after both check jobs pass. Ordinary pushes, PRs, manual CI runs, and tag pushes do not publish.
 
-1. Validate the matching version in `package-lock.json`.
-2. Reserve `v<version>` at the exact checked commit.
-3. Publish the npm tarball through OIDC trusted publishing, with provenance.
-4. Create the GitHub Release with automatically generated release notes.
+Publishing uses npm OIDC with provenance, reserves `v<version>` at the checked commit, and creates a GitHub Release. Stable versions use `latest`; prereleases use `next`.
 
-Ordinary code/dependency changes with no version increase do not publish. Neither PRs, `dev` pushes, tag pushes, nor installing the workflow alone publish a package. Stable versions use npm's `latest` tag; prereleases such as `0.2.0-rc.1` use `next` and GitHub's prerelease flag.
+## First npm release: 0.1.0
 
-### One-time npm setup
+**npm requires the package to exist before a trusted publisher can be configured.** The first publish therefore needs your npm login, not OIDC. See [npm's prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/#prerequisites).
 
-For a new package, publish the initial version once after committing and checking the source:
+The npm package is **@oldflag2333333/pi-subagent**.
 
-```bash
-npm ci
-npm run check
-npm login
-npm publish --access public --ignore-scripts
-```
+1. Enable 2FA on your npm account.
+2. Push the intended release commit to `main`. Wait for the entire **CI and Release** run to succeed.
+3. Download that run's `npm-package-<commit SHA>` artifact and extract it. Use a trusted `main` run, not a PR artifact.
+4. In the extracted directory, run:
+
+   ```bash
+   npx --yes npm@11.21.0 login --registry=https://registry.npmjs.org
+   npx --yes npm@11.21.0 publish ./oldflag2333333-pi-subagent-0.1.0.tgz --access public --ignore-scripts --registry=https://registry.npmjs.org
+   ```
+
+   Complete the browser/2FA prompts yourself. Do not send credentials or OTPs to an agent. The tarball is the exact package produced by CI; no need to repack it locally. This initial interactive publish does not have CI provenance and does not create a GitHub Release.
+
+5. Verify:
 
-This bootstrap publish creates the package so its trusted publisher can be configured. Subsequent releases use the workflow below, not local `npm publish`.
+   ```bash
+   npm view @oldflag2333333/pi-subagent version --registry=https://registry.npmjs.org
+   ```
 
-In the npm settings for **@oldflag2333333/pi-subagent**, add a **GitHub Actions Trusted Publisher**:
+## Configure automatic publishing on npm
 
-| Setting | Value |
+Open **npmjs.com → @oldflag2333333/pi-subagent → Settings → Trusted publishing → Add trusted publisher → GitHub Actions**:
+
+| Field | Value |
 | --- | --- |
 | Organization or user | `oldflag2333333` |
 | Repository | `pi-subagent` |
-| Workflow filename | `release.yml` (filename only, not a path) |
-| Environment | Leave blank; this workflow does not use a GitHub Environment |
-| Allowed actions | Allow direct `npm publish` |
+| Workflow filename | `release.yml` — filename only |
+| Environment name | Leave empty |
+| Allowed actions | Enable direct `npm publish`, not just staged publishing |
+
+No `NPM_TOKEN` or other npm secret is needed in GitHub. The workflow requests `id-token: write` and uses GitHub's built-in token for tags/releases.
 
-No `NPM_TOKEN` secret is needed. GitHub supplies its built-in `GITHUB_TOKEN` for tags/releases; only the release job has `contents: write` and `id-token: write`. Publishing runs on a GitHub-hosted runner with Node 24 and a pinned npm 11 CLI. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for package-side setup.
+A new trust configuration must complete a successful OIDC publish **within 2 days**, or it expires. Configure it when you are ready for the next version, or recreate it if it expires. After verifying OIDC publishing, npm recommends **Publishing access → Require two-factor authentication and disallow tokens**.
 
-Commit the workflow to GitHub and enable Actions before the first version bump. Keep `package.json`'s `repository.url` aligned with this repository; npm provenance and the release script verify that identity.
+Source: [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
 
-### Releasing
+## Subsequent releases
 
-On your feature/release branch:
+With a clean working tree:
 
 ```bash
-npm version minor --no-git-tag-version
-# Or: npm version patch --no-git-tag-version
+npm version patch --no-git-tag-version
+# From 0.1.0, this produces 0.1.1.
 git add package.json package-lock.json
-git commit -m "chore: release v0.2.0"
+git commit -m "chore: release v0.1.1"
+git push origin main
 ```
 
-Merge that change into `main` (or push it directly if your branch policy allows). The workflow handles the tag, npm publication, and GitHub Release; do not run `npm publish` yourself.
-
-If publishing fails, correct the external setup and **re-run the original failed workflow** on its original commit. An identical already-published artifact is not republished, so a failed GitHub Release step can be completed safely. An existing tag pointing elsewhere, an npm version with different contents, or a version that would move a dist-tag backwards causes an error instead of an overwrite. A failed npm publish may leave its reserved Git tag, but no GitHub Release is announced until publication succeeds. Publish one version at a time.
-
-GitHub Releases created by `GITHUB_TOKEN` do not trigger a second release workflow, so npm publication and Release creation deliberately run in the same job.
+Use a PR instead if required by branch policy. Once the version bump reaches `main`, CI publishes npm and creates the tag and GitHub Release automatically. Do not publish locally again or pre-create the tag.
 
+If publication fails, fix the external configuration and **re-run the original failed workflow**. An identical already-published artifact is not republished; conflicting artifacts or tags fail rather than overwrite existing releases. Never try to reuse an npm version for different contents. Publish one version at a time.

package/docs/releasing.zh-CN.md

@@ -0,0 +1,72 @@
+# Pi Subagent 发布指南
+
+[English](releasing.md) | 简体中文
+
+## CI 已配置的内容
+
+工作流位于 `.github/workflows/release.yml`：
+
+- `main`、`dev` 的推送和 PR：在 Node **22.19.0 / 24** 上执行类型检查、测试、包信息校验和打包检查。
+- Node 24 检查通过后上传 `.tgz` 安装包，名称为 `npm-package-<提交 SHA>`，保留 14 天。
+- 可以在 **Actions → CI and Release → Run workflow** 手动运行检查，不会发布。
+- 只有新仓库 `main` 上的**版本递增**才会在所有检查通过后自动发布 npm、创建版本标签和 GitHub Release。
+
+普通代码提交、PR、手动运行 CI、推送标签都不会触发发布。正式版使用 npm 的 `latest`，预发布版使用 `next`。
+
+## 首次发布 0.1.0
+
+npm 包名为 **@oldflag2333333/pi-subagent**。
+
+**npm 要求包已经存在，才能配置 Trusted Publisher。** 因此首次发布需要你登录 npm 手动完成，之后才使用 CI 自动发布。参见 [npm 官方说明](https://docs.npmjs.com/cli/v11/commands/npm-trust/#prerequisites)。
+
+1. 为 npm 账号开启双因素认证（2FA）。
+2. 将准备发布的代码推送到 `main`，等待整个 **CI and Release** 工作流通过。
+3. 下载该次运行的 `npm-package-<提交 SHA>` artifact 并解压。使用确认过的 `main` 构建，不要使用 PR 的产物。
+4. 在解压目录中执行：
+
+   ```bash
+   npx --yes npm@11.21.0 login --registry=https://registry.npmjs.org
+   npx --yes npm@11.21.0 publish ./oldflag2333333-pi-subagent-0.1.0.tgz --access public --ignore-scripts --registry=https://registry.npmjs.org
+   ```
+
+   按提示完成浏览器登录和 2FA，不要把凭据或验证码发给助手。直接发布 CI 打好的包，不用在本地重新打包。首次交互式发布不带 CI provenance，也不会自动创建 GitHub Release。
+
+5. 确认结果：
+
+   ```bash
+   npm view @oldflag2333333/pi-subagent version --registry=https://registry.npmjs.org
+   ```
+
+## npm 网站上需要配置什么
+
+进入 **@oldflag2333333/pi-subagent 包页面 → Settings → Trusted publishing → Add trusted publisher → GitHub Actions**：
+
+| 字段 | 填写内容 |
+| --- | --- |
+| Organization or user | `oldflag2333333` |
+| Repository | `pi-subagent` |
+| Workflow filename | `release.yml`，不要填完整路径 |
+| Environment name | 留空 |
+| Allowed actions | 勾选允许直接 `npm publish`，不能只有 staged publishing |
+
+**GitHub 不需要添加 `NPM_TOKEN`。** 工作流使用 OIDC 临时身份，标签和 Release 使用 GitHub 自动提供的 token。
+
+新建的信任配置需要在 **2 天内成功完成一次 OIDC 发布**，否则会过期。准备发布下一版时再配置；过期后删除并重建即可。验证自动发布成功后，建议将 **Publishing access** 设置为 **Require two-factor authentication and disallow tokens**。
+
+来源：[npm Trusted publishing 文档](https://docs.npmjs.com/trusted-publishers/)。
+
+## 后续发布
+
+在干净的工作区中执行：
+
+```bash
+npm version patch --no-git-tag-version
+# 0.1.0 → 0.1.1
+git add package.json package-lock.json
+git commit -m "chore: release v0.1.1"
+git push origin main
+```
+
+如果仓库要求 PR，就通过 PR 将版本变更合入 `main`。之后 CI 自动完成 npm 发布、标签和 GitHub Release，不需要再手动 `npm publish`，也不要提前创建标签。
+
+发布失败时，修正 npm 等外部配置后，重跑**原来失败的工作流**。相同产物不会重复发布；标签或包内容冲突会报错，不会覆盖。不要用同一个 npm 版本号发布不同内容，也不要并行发布多个版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oldflag2333333/pi-subagent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reusable specialist profiles and independent sub-agents for Pi",
   "type": "module",
   "license": "MIT",
@@ -45,15 +45,15 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": ">=1.0.4",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^1.0.4",
-    "@earendil-works/pi-ai": "^1.0.4",
-    "@earendil-works/pi-coding-agent": "^1.0.4",
-    "@earendil-works/pi-tui": "^1.0.4",
+    "@earendil-works/pi-agent-core": "^1.2.0",
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0",
     "@types/node": "^22.15.0",
     "@types/semver": "^7.8.0",
     "semver": "^7.8.5",

package/src/adapters/herdr.ts

@@ -3,6 +3,7 @@ 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> {
@@ -39,8 +40,9 @@ function subArgs(spec: SubLaunchSpec): string[] {
 		"--no-extensions",
 		"-e", spec.entryPath,
 		...(fs.existsSync(herdrIntegration) ? ["-e", herdrIntegration] : []),
-		...(spec.profile.sessionPersistence === "persistent" || spec.resumeSessionId ? [] : ["--no-session"]),
-		...(spec.resumeSessionId ? ["--session", spec.resumeSessionId] : []),
+		...(spec.profile.sessionPersistence === "persistent" || spec.resumeSessionId
+			? ["--session-dir", subSessionDir(spec.mainSessionId)] : ["--no-session"]),
+		...(spec.resumeSessionId ? ["--session", spec.resumeSessionFile ?? spec.resumeSessionId] : []),
 		spec.projectTrusted ? "--approve" : "--no-approve",
 		"--name", subSessionName(safeLabel(spec.title), spec.origin),
 		...subCapabilityArgs(spec.profile, spec.entryPath),

package/src/commands/clean-sub.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { channelPath, runtimeRoot } from "../channel.js";
+import { subSessionDir, subSessionsRoot } from "../sessions.js";
 
 function entries(directory: string): fs.Dirent[] {
 	try { return fs.readdirSync(directory, { withFileTypes: true }); }
@@ -26,11 +27,16 @@ function sessionId(file: string): string {
 	} finally { fs.closeSync(fd); }
 }
 
-export function cleanSubChannels(currentMainId: string, currentSessionDir: string): { removed: number; errors: string[] } {
-	const root = runtimeRoot();
-	const candidates = entries(root).filter((entry) => entry.isDirectory());
-	if (candidates.length === 0) return { removed: 0, errors: [] };
-	if (fs.lstatSync(root).isSymbolicLink()) throw new Error("Refusing to clean a symlinked runtime directory.");
+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]);
@@ -46,19 +52,21 @@ export function cleanSubChannels(currentMainId: string, currentSessionDir: strin
 			if (entry.name.endsWith(".jsonl")) live.add(sessionId(path.join(directory, entry.name)));
 		}
 	}
-	const liveDirectories = new Set([...live].map((id) => path.basename(path.dirname(channelPath(id, "unused")))));
 	let removed = 0;
 	const errors: string[] = [];
-	for (const entry of candidates) {
-		if (liveDirectories.has(entry.name)) continue;
-		const directory = path.join(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(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+	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)}`);
+			}
 		}
 	}
 	return { removed, errors };
@@ -66,12 +74,12 @@ export function cleanSubChannels(currentMainId: string, currentSessionDir: strin
 
 export function registerCleanSubCommand(pi: ExtensionAPI): void {
 	pi.registerCommand("clean-sub", {
-		description: "Delete runtime communication files whose Main session can no longer be found; keep persistent Sub sessions.",
+		description: "Delete managed Sub sessions and communication directories whose Main session can no longer be found.",
 		handler: async (_args, ctx) => {
 			try {
-				const result = cleanSubChannels(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
+				const result = cleanSubFiles(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
 				ctx.ui.notify([
-					`Removed ${result.removed} orphaned Main communication directories. Persistent Sub sessions were not deleted.`,
+					`Removed ${result.removed} orphaned Sub data directories (sessions and communication).`,
 					...result.errors,
 				].join("\n"), result.errors.length ? "warning" : "info");
 			} catch (error) {

package/src/inbox-state.ts

@@ -49,8 +49,8 @@ export function forgetTalk(ctx: ExtensionContext, direction: TalkDirection, runI
 /** Queue behind streaming work, but never compete with manual compaction or prompt preflight. */
 export function canUseNativeQueue(ctx: ExtensionContext): boolean {
 	const value = state(ctx);
-	// sendUserMessage awaits input/auth hooks before Pi becomes busy. Submit only
-	// one idle prompt at a time; its receipt or agent_start will wake the rest.
+	// Serialize idle submissions until Pi starts the run or records its receipt.
+	// Once active, subsequent deliveries use Pi's native follow-up queue.
 	if (ctx.isIdle()) return ![...value.pending.values()].some((pending) => pending.queued && !pending.queuedWhileBusy);
 	return value.active || ctx.signal !== undefined;
 }

package/src/index.ts

@@ -24,7 +24,7 @@ export default function piSubagent(pi: ExtensionAPI): void {
 	startupProfile.register();
 	new MainContextRuntime(pi).register();
 
-	// Preserve rendering for legacy custom messages in resumed sessions.
+	// Render live deliveries and saved custom messages with the same inbox card.
 	pi.registerMessageRenderer(MESSAGE_TYPE, (message, options, theme) => {
 		const details = message.details as { title?: string; message?: string } | undefined;
 		const title = details?.title ?? "Sub";

package/src/run-manager.ts

@@ -226,7 +226,7 @@ export class MainRunManager {
 				cwd,
 				projectTrusted,
 				...(input.origin ? { origin: input.origin } : {}),
-				...(resume ? { resumeSessionId: resume.sessionId } : {}),
+				...(resume ? { resumeSessionId: resume.sessionId, resumeSessionFile: resume.sessionFile } : {}),
 				profile: input.profile,
 				channelDir: channel.channelDir,
 				token: channel.token,

package/src/sessions.ts

@@ -1,6 +1,17 @@
 import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { RunSnapshot } from "./types.js";
 
+export function subSessionsRoot(): string {
+	return path.join(getAgentDir(), "subagent", "sessions");
+}
+
+export function subSessionDir(mainSessionId: string): string {
+	if (!mainSessionId || mainSessionId === "." || mainSessionId === "..") throw new Error("Invalid Main session ID.");
+	return path.join(subSessionsRoot(), encodeURIComponent(mainSessionId));
+}
+
 export interface ResumableSubSession {
 	sessionId: string;
 	sessionFile: string;

package/src/talk-delivery.ts

@@ -1,12 +1,12 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { MESSAGE_TYPE, removeTalk, type TalkDirection } from "./channel.js";
 import type { DelegateManifest, TalkMessage } from "./types.js";
-import { formatTalkInput, readTalkReceipt } from "./talk-message.js";
+import { readTalkReceipt } from "./talk-message.js";
 import { canUseNativeQueue, forgetTalk, markTalkQueued, rememberTalk } from "./inbox-state.js";
 
 function hasReceipt(ctx: ExtensionContext, direction: TalkDirection, runId: string, messageId: string): boolean {
 	return ctx.sessionManager.getEntries().some((entry) => {
-		// Old custom-message receipts still count after upgrading or reloading.
+		// Accept both custom receipts and user-message receipts from v0.1.0.
 		const details = entry.type === "message" ? readTalkReceipt(entry.message)
 			: entry.type === "custom_message" && entry.customType === MESSAGE_TYPE
 				? entry.details as { direction?: string; runId?: string; messageId?: string } | undefined
@@ -15,7 +15,7 @@ function hasReceipt(ctx: ExtensionContext, direction: TalkDirection, runId: stri
 	});
 }
 
-/** pi.sendUserMessage is fire-and-forget; its return is not a session receipt. */
+/** pi.sendMessage is fire-and-forget; its return is not a session receipt. */
 export function deliverTalk(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
@@ -37,11 +37,13 @@ export function deliverTalk(
 	try {
 		// Pi owns waiting behind current work, not Pi Subagent. In-flight IDs prevent
 		// repeated file notifications from submitting the same follow-up twice.
-		pi.sendUserMessage(formatTalkInput({ direction, runId: manifest.runId, messageId: message.id }, content), {
-			deliverAs: "followUp",
-			// Peer text is input, not an instruction to execute slash commands or templates.
-			expandPromptTemplates: false,
-		});
+		// Pi 1.2+ prepares idle custom-message runs and preserves their prompt sections.
+		pi.sendMessage({
+			customType: MESSAGE_TYPE,
+			content,
+			display: true,
+			details: { title: manifest.title, message: message.message, direction, runId: manifest.runId, messageId: message.id },
+		}, { deliverAs: "followUp", triggerTurn: true });
 	} catch (error) {
 		pending.queued = false;
 		throw error;

package/src/tools/sub.ts

@@ -154,7 +154,7 @@ export function registerSub(pi: ExtensionAPI): void {
 		return sections;
 	});
 
-	// Preserve rendering for legacy custom messages in resumed sessions.
+	// Render live deliveries and saved custom messages with the same inbox card.
 	pi.registerMessageRenderer(MESSAGE_TYPE, (message, options, theme) => {
 		const details = message.details as { title?: string; message?: string } | undefined;
 		const title = details?.title ?? loaded.manifest.title;

package/src/types.ts

@@ -97,6 +97,8 @@ export interface SubLaunchSpec {
 	projectTrusted: boolean;
 	origin?: "manual";
 	resumeSessionId?: string;
+	/** Recorded path also supports sessions saved before per-Main directories. */
+	resumeSessionFile?: string;
 	profile: ResolvedProfile;
 	channelDir: string;
 	token: string;