pi-herdr-subagents-lite 0.3.0 → 0.5.0

package/README.md

@@ -4,19 +4,19 @@ English | [简体中文](README.zh-CN.md)
 
 A pi extension that runs subagents as separate pi processes in herdr panes. One tool, two actions: `run` starts a subagent, `send` continues it, results come back asynchronously.
 
-Experimental; compatibility across versions is not promised. Exact behavior lives in the [v1 contract](docs/specs/0001-v1-contract.md). Project docs are in Chinese.
+Behavior is defined by the [v1 contract](docs/specs/0001-v1-contract.md). Project docs are in Chinese.
 
 ## Features
 
 - **Separate process, human takeover**: each subagent is its own pi process in a herdr pane. Same cwd as the parent opens a tab in the same workspace, otherwise a new workspace. Switch into the pane and take over at any time.
-- **Profile layers**: Markdown + frontmatter under `<agent-dir>/pi-herdr-subagents-lite/profiles/`, plus a project layer under `.pi/pi-herdr-subagents-lite/profiles/` that wins on the same `name`.
-- **Async, merged results**: `run` returns at once. Each finished child reports one `subagent_result` message; results inside `aggregateWindowMs` merge into one. Oversize results go to an artifact file.
+- **Profile layers**: Markdown + frontmatter profiles, global and per project.
+- **Async, merged results**: `run` returns at once. Each finished turn reports one `subagent_result` message; results inside `aggregateWindowMs` merge into one. Oversize results go to an artifact file.
 - **Questions stay with the human**: a child prompt marks its pane `herdr:blocked` and nothing goes to the parent. The human answers in the child pane; no model relays the answer.
 - **No nesting by default, no sandbox**: child tool sets drop this tool unless the profile names it. The profile picks tools; the extension does not restrict writes.
 
 ## Requirements
 
-herdr `0.9.5`, pi `1.4.0`, Node `>= 22.19`. The parent must run inside a herdr pane, otherwise calls fail with `not_in_herdr`.
+Tested with herdr `0.9.5` and pi `1.4.0`. Node `>= 22.19`. The parent must run inside a herdr pane, otherwise calls fail with `not_in_herdr`.
 
 ## Install
 
@@ -36,7 +36,7 @@ Upgrade with `pi update --extensions`, remove with `pi remove <source>`. After a
 ## Quick start
 
 1. Start `pi` in a herdr pane.
-2. Write a profile (next section); its frontmatter `name` is the key `run` takes. The file name is not used for lookup.
+2. Write a profile (next section); `run` takes its frontmatter `name`.
 3. Ask the model to call the tool:
 
 ```json
@@ -55,7 +55,7 @@ Global profiles live in `<agent-dir>/pi-herdr-subagents-lite/profiles/*.md`, pro
 
 ```markdown
 ---
-# Key run takes; keep it equal to the file name
+# Key run takes; the file name is not used
 name: explore
 description: "Read-only research: read code, answer questions, change nothing"
 
@@ -70,7 +70,7 @@ tools: read, bash
 # Omitted = pi discovery; "" = no skills; a list = only those
 skills: ""
 
-# append (default) / replace: body is appended to or replaces the system prompt
+# append / replace: body is appended to or replaces the system prompt
 # task: body is the task text, no identity file
 system-prompt: append
 
@@ -84,18 +84,20 @@ disable-model-invocation: false
 You are a read-only explorer. Answer with file paths and line numbers.
 ```
 
-Defaults and error codes: [contract section 2](docs/specs/0001-v1-contract.md#2-profile). A file without `name`, or with an invalid field, stays out of the list; duplicate names in one layer are all rejected. `run` returns `profile_invalid` with the file, field and reason.
+Error codes: [contract section 2](docs/specs/0001-v1-contract.md#2-profile). Defaults: `src/profile/frontmatter.ts` and `test/profile/`. A file without `name`, or with an invalid field, stays out of the list; duplicate names in one layer are all rejected. `run` returns `profile_invalid` with the file, field and reason.
 
 A bundled example ships with the extension; its file name and `name` are both `domain`. Loading reads `profiles/*.md` only and the example is written only when missing, so copy it one level up:
 
 ```bash
-cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
+cd <agent-dir>/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
 ```
 
 ## Configuration
 
 One global file: `<agent-dir>/pi-herdr-subagents-lite/config.json`. `<agent-dir>` defaults to `~/.pi/agent` and follows `PI_CODING_AGENT_DIR`. Project config is not read.
 
+Defaults and clamp boundaries: `src/config/index.ts`, `test/config/config.test.ts`. Key meaning: [contract §1](docs/specs/0001-v1-contract.md#1-配置).
+
 ### Minimal config
 
 A missing file means all defaults. To change one value, write only that value:
@@ -106,57 +108,24 @@ A missing file means all defaults. To change one value, write only that value:
 }
 ```
 
-### Full config
-
-Every key with its default. Strict JSON: an unknown key, a wrong type or a bad enum makes the extension fail to load and pi exits naming the field. The `//` lines are comments; delete them before use.
-
-```jsonc
-{
-  // Gates tool registration only; the bridge has its own switch
-  "enabled": true,
-
-  // Name the model sees; ^[a-z][a-z0-9_]{0,31}$
-  "toolName": "subagent",
-
-  // Resolved from PATH; set an absolute path to pin a version
-  "herdrBin": "herdr",
-
-  // Live children per parent session; auto-exit false keeps its slot after settling
-  "maxConcurrent": 16,
-
-  // Per result (1024-1048576); beyond it the full text goes to an artifact and the message keeps a truncated head plus the path
-  "maxResultChars": 16384,
-
-  // Ms (0-10000); results inside the window merge into one message, 0 = deliver each immediately
-  "aggregateWindowMs": 500,
+### Keys
 
-  // Parent shutdown reasons that close its child tabs: new / resume / fork / quit / reload; empty = never
-  "closeChildrenOn": [],
-
-  // Child inbox polling interval in ms (50-5000)
-  "inboxPollMs": 250,
-
-  // Parent agent list polling in ms (100-60000); larger saves processes, smaller spots finished children sooner
-  "pollIntervalMs": 1000,
-
-  // Override tool text. Omitted keys keep the built-in text; the values are placeholders, drop the whole block if unused
-  "prompts": {
-    "description": "One line about what this tool does",
-    "snippet": "One line shown in Available tools",
-    // Keep a line containing {{profiles}} to keep the profile list
-    "guidelines": ["Do not wait for a result in this turn.", "Available profiles:\n{{profiles}}"]
-  },
-
-  // Turns pi prompt events into herdr:blocked, for native notifications
-  "bridge": {
-    "enabled": true,
-    // Which prompt kinds count as blocked
-    "blockedOn": ["custom", "select", "confirm", "input", "editor"]
-  }
-}
-```
-
-Out-of-range numbers are clamped to the boundary, not rejected. The config is read once, so restart pi after editing.
+| Key | Meaning |
+|---|---|
+| `enabled` | Gates tool registration only; the bridge has its own switch |
+| `toolName` | Name the model sees; `^[a-z][a-z0-9_]{0,31}$` |
+| `herdrBin` | herdr executable; a plain name resolves from PATH, an absolute path pins a version |
+| `maxConcurrent` | Live children per parent session; an `auto-exit: false` child keeps its slot after settling |
+| `maxResultChars` | Per-result character limit; beyond it the full text goes to an artifact and the message keeps a truncated head plus the path |
+| `aggregateWindowMs` | Merge window in milliseconds; 0 = deliver each result at once |
+| `closeChildrenOn` | Parent shutdown reasons that close its child tabs: `new` / `resume` / `fork` / `quit` / `reload`; empty = never |
+| `inboxPollMs` | Child inbox polling interval |
+| `pollIntervalMs` | Parent `agent list` interval while a child is working or blocked, or within 30 s of `run` / `send` |
+| `idlePollIntervalMs` | Parent interval when every live child only waits for `send`; it bounds how late a vanished pane is noticed (a killed child whose pane lives is fixed at 10 s) |
+| `prompts` | Tool text overrides: `description`, `snippet`, `guidelines`; omitted keys keep the built-in text; `snippet: ""` hides the tool from Available tools; keep `{{profiles}}` to list profiles |
+| `bridge` | `enabled` turns pi prompt events into `herdr:blocked`; `blockedOn` lists the prompt kinds that count as blocked |
+
+Strict JSON: an unknown key, a wrong type or a bad enum makes the extension fail to load, and pi exits naming the field. Out-of-range numbers clamp to the boundary. The config is read once, so restart pi after editing.
 
 ## Reference projects
 
@@ -171,18 +140,15 @@ The design is based on these projects. Thank you.
 
 ## Docs
 
-All docs are in Chinese.
-
 - [ARCHITECTURE](docs/ARCHITECTURE.md): module boundaries, dependency direction, test seams
 - [GLOSSARY](docs/GLOSSARY.md): the only source for terms
 - [Modules](docs/modules/): usage and trade-offs per module
-- [ADR](docs/decisions/): decisions and rejected proposals, with reasons
 
 ## Development
 
 ```bash
 pnpm install        # dependencies
-pnpm check          # lint + import boundaries + types + unit tests
+pnpm check          # the four checks below
 pnpm test           # unit tests (vitest)
 pnpm lint           # biome
 pnpm typecheck      # tsc --noEmit

package/README.zh-CN.md

@@ -4,19 +4,19 @@
 
 pi 扩展：让子代理作为独立 pi 进程跑在 herdr pane 里。一个工具，两个 action：`run` 起子代理，`send` 续聊，结果异步回投。
 
-实验阶段，不保证跨版本兼容。行为以 [v1 契约](docs/specs/0001-v1-contract.md) 为准。
+行为以 [v1 契约](docs/specs/0001-v1-contract.md) 为准。
 
 ## 功能
 
 - **独立进程，可人工接管**：每个子代理是 herdr pane 里独立的 pi 进程。cwd 与父相同则同 workspace 新开 tab，否则新建 workspace。随时切进去接管。
-- **两层 profile**：Markdown + frontmatter，全局 `<agent-dir>/pi-herdr-subagents-lite/profiles/`，项目层 `.pi/pi-herdr-subagents-lite/profiles/`，`name` 相同时项目层覆盖。
-- **异步、可合并的结果**：`run` 立即返回。每个子代理收工时投一条 `subagent_result`；落在 `aggregateWindowMs` 内的结果合并成一条。超长结果落 artifact 文件。
+- **两层 profile**：Markdown + frontmatter，全局一层、项目一层。
+- **异步、可合并的结果**：`run` 立即返回。每次收工投一条 `subagent_result`；落在 `aggregateWindowMs` 内的结果合并成一条。超长结果落 artifact 文件。
 - **反问留在人这边**：子代理弹出对话框时只发出 `herdr:blocked` 事件，父侧什么也收不到。人在子 pane 里回答，不经模型转达。
 - **默认不嵌套，也不是沙箱**：子代理的工具集默认去掉本工具，profile 里点名才授予。工具由 profile 决定，扩展不限制写操作。
 
 ## 要求
 
-herdr `0.9.5`、pi `1.4.0`、Node `>= 22.19`。父会话必须在 herdr pane 里，否则调用返回 `not_in_herdr`。
+在 herdr `0.9.5` 与 pi `1.4.0` 上测过。Node `>= 22.19`。父会话必须在 herdr pane 里，否则调用返回 `not_in_herdr`。
 
 ## 安装
 
@@ -36,7 +36,7 @@ pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # 只对当前进程
 ## 快速开始
 
 1. 在 herdr pane 里启动 `pi`。
-2. 写一个 profile（下一节）；frontmatter `name` 就是 `run` 的寻址名，文件名不参与查找。
+2. 写一个 profile（下一节）；frontmatter `name` 就是 `run` 的寻址名。
 3. 让模型调用工具：
 
 ```json
@@ -55,7 +55,7 @@ pi -e /path/to/pi-herdr-subagents-lite/src/index.ts        # 只对当前进程
 
 ```markdown
 ---
-# run 的寻址名；建议与文件名保持一致
+# run 的寻址名；文件名不参与查找
 name: explore
 description: 只读调研：读代码、回答问题，不改动任何文件
 
@@ -70,32 +70,34 @@ tools: read, bash
 # 省略 = 由 pi 发现；"" = 不加载；列表 = 只加载列出的
 skills: ""
 
-# append（默认）/ replace：正文追加到或替换系统提示
+# append / replace：正文追加到或替换系统提示
 # task：正文就是任务文本，不写身份文件
 system-prompt: append
 
 # 收工后自行退出并关掉 tab；有打开的对话框或 inbox 待投递时会等
 auto-exit: true
 
-# true = 从工具说明里隐藏；显式 run 仍然可用
+# true = 不出现在 guidelines 的 profile 列表里；显式 run 仍然可用
 disable-model-invocation: false
 ---
 
 你是一名只读探索者，回答时给出文件路径与行号。
 ```
 
-字段默认值与错误码见 [契约 §2](docs/specs/0001-v1-contract.md#2-profile)。没写 `name`、字段非法或同层同名的文件都不进列表；对它 `run` 返回 `profile_invalid`，带文件、字段与原因。
+错误码见 [契约 §2](docs/specs/0001-v1-contract.md#2-profile)；默认值见 `src/profile/frontmatter.ts` 与 `test/profile/`。没写 `name`、字段非法或同层同名的文件都不进列表；对它 `run` 返回 `profile_invalid`，带文件、字段与原因。
 
 扩展自带一个示例 profile，文件名和 `name` 都是 `domain`。加载只读 `profiles/*.md`，示例也只在缺失时写入，所以复制一层上去即可：
 
 ```bash
-cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
+cd <agent-dir>/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.md
 ```
 
 ## 配置
 
 只有一个全局文件：`<agent-dir>/pi-herdr-subagents-lite/config.json`。`<agent-dir>` 默认 `~/.pi/agent`，跟随 `PI_CODING_AGENT_DIR`。项目级配置不读。
 
+默认值与 clamp 边界：`src/config/index.ts`、`test/config/config.test.ts`。键与语义：[契约 §1](docs/specs/0001-v1-contract.md#1-配置)。
+
 ### 最小配置
 
 文件不存在就全用默认值。只改一项，就只写这一项：
@@ -106,57 +108,24 @@ cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.
 }
 ```
 
-### 完整配置
-
-逐项列出，值是默认值。必须是严格 JSON：未知键、类型不对、枚举非法都会让扩展加载失败，pi 报出字段名退出。`//` 行是注释，用之前删掉。
-
-```jsonc
-{
-  // 只管工具注册；bridge 有自己的开关
-  "enabled": true,
-
-  // 模型看到的工具名；^[a-z][a-z0-9_]{0,31}$
-  "toolName": "subagent",
-
-  // 从 PATH 解析；写绝对路径可锁定版本
-  "herdrBin": "herdr",
-
-  // 每个父会话并存的子代理数；auto-exit 为 false 的子代理收工后仍占槽
-  "maxConcurrent": 16,
-
-  // 单条结果上限（1024-1048576）；超了全文落 artifact，消息里留截断的头和路径
-  "maxResultChars": 16384,
-
-  // 合并窗口，毫秒（0-10000）；窗口内的结果并成一条，0 = 逐条立即投递
-  "aggregateWindowMs": 500,
+### 键
 
-  // 父会话以这些原因退出时关掉子 tab：new / resume / fork / quit / reload；空 = 从不关
-  "closeChildrenOn": [],
-
-  // 子侧 inbox 轮询间隔，毫秒（50-5000）
-  "inboxPollMs": 250,
-
-  // 父侧 agent list 轮询间隔，毫秒（100-60000）；调大省进程，调小更早发现收工
-  "pollIntervalMs": 1000,
-
-  // 覆盖工具文案。省略的键用内置文案；下面的值是占位符，不用就整段删掉
-  "prompts": {
-    "description": "一句话说明这个工具做什么",
-    "snippet": "Available tools 里的一句话",
-    // 保留含 {{profiles}} 的行才会保留 profile 列表
-    "guidelines": ["不要在本轮等待结果。", "可用 profile：\n{{profiles}}"]
-  },
-
-  // 把 pi 的对话框事件转成 herdr:blocked，供原生通知使用
-  "bridge": {
-    "enabled": true,
-    // 哪些对话框算 blocked
-    "blockedOn": ["custom", "select", "confirm", "input", "editor"]
-  }
-}
-```
-
-超范围的数字会被夹到边界，不报错。配置只读一次，改完重启 pi。
+| 键 | 含义 |
+|---|---|
+| `enabled` | 只管工具注册；bridge 有自己的开关 |
+| `toolName` | 模型看到的工具名；`^[a-z][a-z0-9_]{0,31}$` |
+| `herdrBin` | herdr 可执行文件；裸名从 PATH 解析，绝对路径锁定版本 |
+| `maxConcurrent` | 每个父会话并存的子代理数；`auto-exit: false` 的子代理收工后仍占槽 |
+| `maxResultChars` | 单条结果字符上限；超了全文落 artifact，消息里留截断的头和路径 |
+| `aggregateWindowMs` | 合并窗口，毫秒；0 = 逐条立即投递 |
+| `closeChildrenOn` | 父会话以这些原因退出时关掉子 tab：`new` / `resume` / `fork` / `quit` / `reload`；空 = 从不关 |
+| `inboxPollMs` | 子侧 inbox 轮询间隔 |
+| `pollIntervalMs` | 父侧 `agent list` 间隔；有子代理在 working 或 blocked，或刚 `run` / `send` 的 30 秒内用 |
+| `idlePollIntervalMs` | 所有 live 子代理都只是在等 `send` 时的间隔；它决定 pane 消失最晚多久被发现（pane 还在、进程被杀的那类固定 10 秒） |
+| `prompts` | 覆盖工具文案：`description`、`snippet`、`guidelines`；省略的键用内置文案；`snippet: ""` 让工具从 Available tools 消失；保留 `{{profiles}}` 才会列出 profile |
+| `bridge` | `enabled` 把 pi 对话框事件转成 `herdr:blocked`；`blockedOn` 列出算 blocked 的对话框类型 |
+
+必须是严格 JSON：未知键、类型不对、枚举非法都会让扩展加载失败，pi 报出字段名退出。超范围的数字会被夹到边界，不报错。配置只读一次，改完重启 pi。
 
 ## 参考项目
 
@@ -171,16 +140,15 @@ cd ~/.pi/agent/pi-herdr-subagents-lite/profiles && cp examples/domain.md domain.
 
 ## 文档
 
-- [ARCHITECTURE](docs/ARCHITECTURE.md) — 模块边界与 seam，改结构前看
-- [GLOSSARY](docs/GLOSSARY.md) — 术语唯一来源，命名前看
-- [模块](docs/modules/) — 各模块的用法与取舍
-- [ADR](docs/decisions/) — 已决选型与理由，改设计前扫一遍
+- [ARCHITECTURE](docs/ARCHITECTURE.md)：模块边界、依赖方向、测试 seam
+- [GLOSSARY](docs/GLOSSARY.md)：术语唯一来源
+- [模块](docs/modules/)：各模块的用法与取舍
 
 ## 开发
 
 ```bash
 pnpm install        # 装依赖
-pnpm check          # lint + 导入边界 + 类型 + 单测
+pnpm check          # 下面四项
 pnpm test           # 单测（vitest）
 pnpm lint           # biome
 pnpm typecheck      # tsc --noEmit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-subagents-lite",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Run pi subagents in herdr panes.",
   "type": "module",
   "license": "MIT",

package/src/config/index.ts

@@ -41,6 +41,7 @@ export interface Config {
   closeChildrenOn: ShutdownReason[];
   inboxPollMs: number;
   pollIntervalMs: number;
+  idlePollIntervalMs: number;
   prompts: PromptOverrides;
   bridge: { enabled: boolean; blockedOn: BlockedKind[] };
 }
@@ -77,6 +78,7 @@ function parse(raw: Raw, file: string): Config {
     closeChildrenOn: enumList(top, "closeChildrenOn", SHUTDOWN_REASONS, []),
     inboxPollMs: integer(top, "inboxPollMs", 250, 50, 5000),
     pollIntervalMs: integer(top, "pollIntervalMs", 1000, 100, 60000),
+    idlePollIntervalMs: integer(top, "idlePollIntervalMs", 8000, 100, 60000),
     prompts: promptOverrides(top),
     bridge: {
       enabled: boolean(bridge, "enabled", true),

package/src/config/schema.ts

@@ -8,6 +8,7 @@ export const CONFIG_KEYS = [
   "closeChildrenOn",
   "inboxPollMs",
   "pollIntervalMs",
+  "idlePollIntervalMs",
   "prompts",
   "bridge",
 ];

package/src/error/index.ts

@@ -0,0 +1,3 @@
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/extension/index.ts

@@ -1,6 +1,7 @@
 import type { SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import { createBridge } from "../bridge/index.ts";
 import type { BlockedKind, Config } from "../config/index.ts";
+import { errorText } from "../error/index.ts";
 import type { HerdrHost } from "../herdr/index.ts";
 import { drain, hasInbox, pumpInbox } from "../inbox/index.ts";
 import type { ProfileCatalog, ProfileSources } from "../profile/index.ts";
@@ -30,10 +31,6 @@ export interface SessionContext {
 
 export type { SubagentTool };
 
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 type SessionStartHandler = (event: SessionStartEvent, ctx: SessionContext) => void;
 type SettledHandler = (event: { type: "agent_settled" }, ctx: SessionContext) => void;
 type PromptHandler = (event: { kind: BlockedKind; title?: string }) => void;
@@ -100,7 +97,7 @@ export function createExtension(deps: ExtensionDeps): (pi: ExtensionRegistrar) =
           }
           stopInbox();
           const detail = errorText(error);
-          ctx.ui.notify(`inbox: stopped after ${INBOX_FAILURE_LIMIT} delivery failures: ${detail}`, "error");
+          ctx.ui.notify(`subagent messages stopped after ${INBOX_FAILURE_LIMIT} delivery failures: ${detail}`, "error");
         },
       });
     };
@@ -112,12 +109,14 @@ export function createExtension(deps: ExtensionDeps): (pi: ExtensionRegistrar) =
         readLastAssistant: deps.readLastAssistant,
         readExitReceipt: deps.readExitReceipt,
         loadProfiles: () => deps.loadProfiles(sources),
+        trusted: sources.trusted,
         maxConcurrent: config.maxConcurrent,
         maxResultChars: config.maxResultChars,
         aggregateWindowMs: config.aggregateWindowMs,
         pollIntervalMs: config.pollIntervalMs,
+        idlePollIntervalMs: config.idlePollIntervalMs,
         toolName: config.toolName,
-        onDeliveryError: (error) => ctx.ui.notify(`delivery failed: ${errorText(error)}`, "error"),
+        onDeliveryError: (error) => ctx.ui.notify(`subagent result not delivered: ${errorText(error)}`, "error"),
       });
       service.onResult((results) => sendResults(pi, results));
     };

package/src/extension/shutdown.ts

@@ -27,10 +27,10 @@ export function watchShutdown(pi: ExtensionRegistrar, deps: ShutdownDeps): void
     if (closing && deps.config.closeChildrenOn.includes(event.reason)) {
       const { kept, failed } = await closing.closeChildren();
       for (const name of kept) {
-        ctx.ui.notify(`child "${name}" kept: its tab was not a single pane`, "warning");
+        ctx.ui.notify(`child "${name}" kept running: its tab has more than one pane`, "warning");
       }
       for (const failure of failed) {
-        ctx.ui.notify(`child "${failure.name}" close failed: ${failure.reason}`, "error");
+        ctx.ui.notify(`could not close child "${failure.name}": ${failure.reason}`, "error");
       }
     } else {
       closing?.shutdown();

package/src/herdr/agent.ts

@@ -10,6 +10,7 @@ export interface AgentSnapshot {
 export interface AgentEntry extends AgentSnapshot {
   name: string | null;
   paneId: string;
+  sessionFile: string | null;
 }
 
 export interface StartAgentInput {
@@ -17,20 +18,18 @@ export interface StartAgentInput {
   paneId: string;
   sessionFile: string;
   agentArgs: string[];
-  briefFile: string;
 }
 
-export type ResumeAgentInput = Omit<StartAgentInput, "briefFile">;
-
 interface AgentInfo {
   agent_status: AgentStatus;
   completion_seq?: number | null;
   state_change_seq?: number;
   name?: string | null;
   pane_id: string;
+  agent_session?: { kind?: string; value?: string } | null;
 }
 
-function agentStartCommand(input: ResumeAgentInput): string[] {
+function agentStartCommand(input: StartAgentInput): string[] {
   return [
     "agent",
     "start",
@@ -48,14 +47,14 @@ function agentStartCommand(input: ResumeAgentInput): string[] {
   ];
 }
 
+function sessionPath(agent: AgentInfo): string | null {
+  const session = agent.agent_session;
+  return session?.kind === "path" && typeof session.value === "string" ? session.value : null;
+}
+
 export function createAgentCommands(exec: ExecHerdr) {
   return {
-    async startAgent({ name, briefFile, ...input }: StartAgentInput) {
-      await exec(agentStartCommand({ name, ...input }));
-      await exec(["agent", "prompt", name, `@${briefFile}`]);
-    },
-
-    async resumeAgent(input: ResumeAgentInput) {
+    async startAgent(input: StartAgentInput) {
       await exec(agentStartCommand(input));
     },
 
@@ -64,6 +63,7 @@ export function createAgentCommands(exec: ExecHerdr) {
       return result.agents.map((agent) => ({
         name: agent.name ?? null,
         paneId: agent.pane_id,
+        sessionFile: sessionPath(agent),
         status: agent.agent_status,
         completionSeq: agent.completion_seq ?? agent.state_change_seq ?? 0,
       }));

package/src/herdr/index.ts

@@ -1,4 +1,4 @@
-import type { AgentEntry, AgentSnapshot, ResumeAgentInput, StartAgentInput } from "./agent.ts";
+import type { AgentEntry, AgentSnapshot, StartAgentInput } from "./agent.ts";
 import { createAgentCommands } from "./agent.ts";
 import { createHerdrExec, HerdrHostError } from "./cli.ts";
 import type {
@@ -21,13 +21,12 @@ export interface HerdrHost {
   renameTab(input: RenameTabInput): Promise<void>;
   renamePane(input: RenamePaneInput): Promise<void>;
   startAgent(input: StartAgentInput): Promise<void>;
-  resumeAgent(input: ResumeAgentInput): Promise<void>;
   hasPane(paneId: string): Promise<boolean>;
   listAgents(): Promise<AgentEntry[]>;
   closeTabIfOnlyPane(input: CloseTabInput): Promise<CloseTabResult>;
 }
 
-export type { AgentEntry, AgentSnapshot, CloseTabResult, ResumeAgentInput, StartAgentInput };
+export type { AgentEntry, AgentSnapshot, CloseTabResult, StartAgentInput };
 
 export function createHerdrHost(bin: string): HerdrHost {
   const { execJson } = createHerdrExec(bin);

package/src/herdr/pane.ts

@@ -9,15 +9,15 @@ export interface CreateTabInput {
   cwd: string;
   label: string;
   env: Record<string, string>;
-  workspaceId?: string;
 }
 
 export interface CreateWorkspaceInput {
   cwd: string;
   label: string;
+  env: Record<string, string>;
 }
 
-export interface CreatedWorkspace {
+export interface CreatedWorkspace extends CreatedTab {
   workspaceId: string;
 }
 
@@ -59,20 +59,25 @@ interface PaneInfo {
 
 export function createPaneCommands(exec: ExecHerdr) {
   return {
-    async createWorkspace({ cwd, label }: CreateWorkspaceInput): Promise<CreatedWorkspace> {
-      const result = await exec<{ workspace: WorkspaceInfo }>([
+    async createWorkspace({ cwd, label, env }: CreateWorkspaceInput): Promise<CreatedWorkspace> {
+      const result = await exec<{ workspace: WorkspaceInfo; tab: TabInfo; root_pane: PaneInfo }>([
         "workspace",
         "create",
         "--cwd",
         cwd,
         "--label",
         label,
+        ...envArgs(env),
         "--no-focus",
       ]);
-      return { workspaceId: result.workspace.workspace_id };
+      return {
+        workspaceId: result.workspace.workspace_id,
+        tabId: result.tab.tab_id,
+        paneId: result.root_pane.pane_id,
+      };
     },
 
-    async createTab({ cwd, label, env, workspaceId }: CreateTabInput): Promise<CreatedTab> {
+    async createTab({ cwd, label, env }: CreateTabInput): Promise<CreatedTab> {
       const result = await exec<{ tab: TabInfo; root_pane: PaneInfo }>([
         "tab",
         "create",
@@ -81,7 +86,6 @@ export function createPaneCommands(exec: ExecHerdr) {
         "--label",
         label,
         ...envArgs(env),
-        ...(workspaceId === undefined ? [] : ["--workspace", workspaceId]),
         "--no-focus",
       ]);
       return { tabId: result.tab.tab_id, paneId: result.root_pane.pane_id };

package/src/inbox/index.ts

@@ -3,7 +3,6 @@ import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, wri
 import { join } from "node:path";
 
 const MESSAGE_SUFFIX = ".md";
-const DELIVERED_DIR = ".delivered";
 
 function inboxDir(sessionFile: string): string {
   return `${sessionFile}.inbox`;
@@ -56,18 +55,12 @@ export function enqueue(sessionFile: string, text: string): void {
 
 export function drain(sessionFile: string, deliver: (text: string) => void): number {
   const dir = inboxDir(sessionFile);
-  const names = pendingNames(dir);
-  if (names.length === 0) {
-    return 0;
-  }
-
-  const deliveredDir = join(dir, DELIVERED_DIR);
-  mkdirSync(deliveredDir, { recursive: true });
   let delivered = 0;
-  for (const name of names) {
-    const text = readFileSync(join(dir, name), "utf8");
+  for (const name of pendingNames(dir)) {
+    const path = join(dir, name);
+    const text = readFileSync(path, "utf8");
     deliver(text);
-    renameSync(join(dir, name), join(deliveredDir, name));
+    rmSync(path, { force: true });
     delivered += 1;
   }
   return delivered;

package/src/profile/examples.ts

@@ -1,20 +1,21 @@
 export const EXAMPLE_PROFILE_FILE = "domain.md";
 
 export const EXAMPLE_PROFILE = `---
-# Copy this file to profiles/domain.md to use it. \`name\` is what \`run\` takes.
+# Copy this file to profiles/domain.md to use it.
 name: domain
-description: Take one domain of work into a fresh context. Invoke by name.
-
-# User-invoked: hidden from the tool guidelines, so only an explicit run uses it.
-disable-model-invocation: true
-
-# Close the tab once the work is done; set false to keep it for follow-ups.
-auto-exit: true
+description: Use when the task covers another domain.
+# model: provider/model
+# thinking: low
+tools: -subagent
+skills: []
+system-prompt: append
+auto-exit: false
+disable-model-invocation: false
 ---
-You work on one domain per task.
+Work on one domain per task.
 
-- The task names your domain. Stay inside it and do not touch files of other domains.
-- Read the code you need yourself; do not ask the parent for context you can read.
-- Report results, not exploration: what changed, what is left, what blocks you.
-- Need a decision only the user can make? Stop and report it.
+- Change only files in that domain.
+- Read the code yourself. Do not ask the parent for context.
+- Report what changed, what is left, and what blocks you.
+- Stop if only the user can decide. Report the question.
 `;