@oldflag2333333/pi-subagent 0.1.0 → 0.1.1

package/README.md

@@ -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. An idle receiver also gets a short user-role wake prompt to preserve its profile instructions. See [messaging behavior and the Pi wake workaround](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

@@ -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,28 @@
+# Message delivery and rendering
+
+Main ↔ Sub messages remain custom inbox cards. Delivery uses the same `parentWake` wrapper in both directions:
+
+- **Busy receiver:** `pi.sendMessage()` with `deliverAs: "followUp"` and `triggerTurn: true`, using Pi's native queue.
+- **Idle receiver:** append the card with `pi.sendMessage(..., { triggerTurn: false })`, then start the run with a short, fixed `pi.sendUserMessage(..., { deliverAs: "steer" })` prompt. This goes through normal input preparation and `before_agent_start`.
+
+The wake is a real, visible user-role message added by the extension, not a duplicate of the peer's message. It only asks the receiving agent to process its inbox within its existing task and authority. Peer text stays in the custom card and is never submitted as executable slash-command input.
+
+## 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. Legacy user-message receipts remain recognized.
+- An idle burst shares one wake while that wake is starting. Reservations survive `/reload`, are scoped to the receiving session, and clear on `agent_start` or non-reload shutdown.
+- If a wake never starts, a later idle delivery can request another wake after ten seconds. The deadline does not create a timer or promise autonomous retry after an input hook handles the wake.
+- A synchronous wake failure keeps the message file retryable; retrying does not append the custom card again. Pi's fire-and-forget extension API does not expose asynchronous prompt failures as delivery receipts.
+
+## Why the workaround exists
+
+Pi 1.0.4 and 1.1.0 have an idle custom-message wake path that bypasses `before_agent_start` and can drop profile prompt sections:
+
+- [#5581: custom-message starts bypass run preparation](https://github.com/earendil-works/pi/issues/5581)
+- [#10267: contributed prompt sections are dropped](https://github.com/earendil-works/pi/issues/10267)
+
+The implementation adapts [nicobailon/pi-subagents' parentWake](https://github.com/nicobailon/pi-subagents/blob/0c33ec7cb26ed1db270d72e746c3c975be880aeb/src/shared/parent-wake.ts), with retries for synchronous wake failures. Attribution and the MIT license are in [third-party notices](third-party-notices.md).
+
+Real Pi SDK tests cover the first idle wake, subsequent turns, busy follow-ups, and reload. The previous upstream TODO is now a required passing regression test. This workaround does not patch Pi internals or claim to fix unrelated retry/resume paths in Pi itself.

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/docs/third-party-notices.md

@@ -0,0 +1,25 @@
+# Third-party notices
+
+`src/parent-wake.ts` adapts the parent wake workaround from [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents/blob/0c33ec7cb26ed1db270d72e746c3c975be880aeb/src/shared/parent-wake.ts).
+
+## pi-subagents — MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

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

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

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { MESSAGE_TYPE, type TalkDirection } from "./channel.js";
 import type { DelegateManifest, TalkMessage } from "./types.js";
 import { readTalkReceipt } from "./talk-message.js";
+import { parentWakeFor } from "./parent-wake.js";
 
 type ReadonlySessionManager = ExtensionContext["sessionManager"];
 interface PendingTalk {
@@ -49,8 +50,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;
 }
@@ -68,6 +69,7 @@ export function bindInboxEvents(pi: ExtensionAPI, getContext: () => ExtensionCon
 	pi.on("agent_start", () => {
 		const ctx = getContext();
 		if (!ctx) return;
+		parentWakeFor(pi, ctx).agentStarted();
 		const value = state(ctx);
 		value.runSerial++;
 		value.aborted = ctx.signal?.aborted === true;
@@ -76,6 +78,10 @@ export function bindInboxEvents(pi: ExtensionAPI, getContext: () => ExtensionCon
 		ctx.signal?.addEventListener("abort", () => { if (value.runSerial === runSerial) value.aborted = true; }, { once: true });
 		wakePending();
 	});
+	pi.on("session_shutdown", (event, ctx) => {
+		// Use the event context: manager shutdown may already have cleared its active context.
+		parentWakeFor(pi, ctx).sessionShutdown(event.reason);
+	});
 	pi.on("agent_end", (event) => {
 		const ctx = getContext();
 		if (!ctx) return;

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/parent-wake.ts

@@ -0,0 +1,86 @@
+// Adapted from nicobailon/pi-subagents (MIT), src/shared/parent-wake.ts.
+// Copyright (c) 2026 Nico Bailon. See docs/third-party-notices.md.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// Shared by Main and Sub. Peer content stays in the custom message, never in this prompt.
+export const PARENT_WAKE_TEXT = "Process the new Pi Subagent inbox messages above and continue the task already authorized for this session. Follow your profile and communication protocol. Do not infer new user authorization.";
+export const WAKE_PENDING_MS = 10_000;
+
+type WakeContext = Pick<ExtensionContext, "isIdle" | "sessionManager">;
+type WakeReservation = { sessionId: string; sentAt?: number; failed?: boolean };
+const reservationsSymbol = Symbol.for("pi-subagent.parent-wake-reservations.v1");
+const wakeGlobal = globalThis as typeof globalThis & { [reservationsSymbol]?: WeakMap<object, WakeReservation> };
+const reservations = wakeGlobal[reservationsSymbol] ?? (wakeGlobal[reservationsSymbol] = new WeakMap<object, WakeReservation>());
+
+export interface ParentWake {
+	sendMessage(...args: Parameters<ExtensionAPI["sendMessage"]>): void;
+	/** A custom receipt alone must not acknowledge a synchronously failed wake. */
+	retryFailedWake(): boolean;
+	bindSession(ctx: WakeContext): void;
+	agentStarted(): void;
+	sessionShutdown(reason: string | undefined): void;
+}
+
+export function createParentWake(pi: Pick<ExtensionAPI, "sendMessage" | "sendUserMessage">, now: () => number = Date.now): ParentWake {
+	let ctx: WakeContext;
+	let reservation: WakeReservation = { sessionId: "" };
+	const wake = () => {
+		if (reservation.sentAt !== undefined && now() - reservation.sentAt < WAKE_PENDING_MS) return;
+		reservation.sentAt = now();
+		try {
+			// Steer safely queues the wake if another prompt starts a run first.
+			pi.sendUserMessage(PARENT_WAKE_TEXT, { deliverAs: "steer" });
+			reservation.failed = false;
+		} catch (error) {
+			reservation.sentAt = undefined;
+			reservation.failed = true;
+			throw error;
+		}
+	};
+	return {
+		sendMessage(message, options) {
+			if (options?.triggerTurn !== true || !ctx.isIdle()) {
+				pi.sendMessage(message, options);
+				return;
+			}
+			// Pi's idle custom-message wake bypasses before_agent_start (#5581/#10267).
+			// Retain custom rendering but use native user-input preparation to start the run.
+			pi.sendMessage(message, { triggerTurn: false });
+			wake();
+		},
+		retryFailedWake() {
+			if (!reservation.failed) return true;
+			if (!ctx.isIdle()) return false;
+			wake();
+			return true;
+		},
+		bindSession(context) {
+			ctx = context;
+			const sessionId = context.sessionManager.getSessionId();
+			const retained = reservations.get(context.sessionManager);
+			reservation = retained?.sessionId === sessionId ? retained : { sessionId };
+			reservations.set(context.sessionManager, reservation);
+		},
+		agentStarted() {
+			reservation.sentAt = undefined;
+			reservation.failed = false;
+		},
+		sessionShutdown(reason) {
+			if (reason !== "reload") {
+				reservation.sentAt = undefined;
+				reservation.failed = false;
+			}
+		},
+	};
+}
+
+const runtimes = new WeakMap<ExtensionAPI, ParentWake>();
+export function parentWakeFor(pi: ExtensionAPI, ctx: WakeContext): ParentWake {
+	let wake = runtimes.get(pi);
+	if (!wake) {
+		wake = createParentWake(pi);
+		runtimes.set(pi, wake);
+	}
+	wake.bindSession(ctx);
+	return wake;
+}

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,13 @@
 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 { parentWakeFor } from "./parent-wake.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 +16,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,
@@ -26,6 +27,7 @@ export function deliverTalk(
 	content: string,
 ): "acknowledged" | "waiting" | "sent" {
 	if (hasReceipt(ctx, direction, manifest.runId, message.id)) {
+		if (!parentWakeFor(pi, ctx).retryFailedWake()) return "waiting";
 		forgetTalk(ctx, direction, manifest.runId, message.id);
 		removeTalk(channelDir, direction, message.id);
 		return "acknowledged";
@@ -37,11 +39,14 @@ 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,
-		});
+		// Keep peer content in the custom inbox card. Idle runs use a separate,
+		// fixed user wake so Pi assembles the profile sections through its input pipeline.
+		parentWakeFor(pi, ctx).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;