dsh-root-planner-preset 1.1.6 → 1.1.8

package/README.md

@@ -19,13 +19,42 @@ This preset takes the middle line: **workers with tools, bounded by their task.*
 | A subagent can read, **edit files and run commands** | `toolFilter.allow` on both delegation tools includes `write`, `edit`, `ops_replace`, `pwsh` | Grant, not restriction — a worker without tools is not a worker |
 | A subagent cannot leave a process running | `enableRunInBackground: false` on the preset's `pwsh` row: the call is refused **and** `run_in_background` is removed from the tool schema | **Structural** — no model at any depth can reach for a detached process |
 | Nobody runs an unbounded service | Persona rules for the root and for subagents | Prompt-level, covering what a schema cannot (`ops_bash` has no job registry) |
-| A subagent stays inside the task it was given | Persona rules: named files only, no drive-by fixes, no racing siblings | Prompt-level |
+| A subagent stays inside its own workspace | Persona rules: write only under `_agents/<label>/`, the parent's files read-only to it, outside changes sent as a request | Prompt-level, **verified** by the parent (see below) |
 | Delegation depth is the user's setting | The runtime depth cap (`subagent.maxDepth`) | **Structural**: past the cap it throws `SubagentDepthError` |
 | Live children are capped as well | `subagent.maxActiveSubagents` | **Structural**: past the cap a delegation fails with `subagent limit reached`, and it does not queue |
 | The root decides; workers execute | Persona rules | Prompt-level |
 
 The mask is an **allow** list: a tool added by a future plugin is invisible to subagents until it is added here.
 
+### One workspace per worker
+
+Concurrency is handled by separation rather than by coordination. Before delegating,
+the root creates `_agents/<label>/` and puts that absolute path in the task; the child
+writes **only** there, reads the parent's files freely, and sends a change request
+instead of editing anything outside. On completion the child reports its artifacts and
+the root decides which to copy in — merging into an existing file where that is what the
+change means, keeping them separate where it is not. `_agents/` stays (and belongs in
+`.gitignore`) so the same agent can be continued later.
+
+**The boundary is agreed, not enforced, because of the shell.** Write tools could be
+fenced structurally — a scoped plugin can shadow `write`/`edit`/`ops_replace` with
+path-checked versions, since scoped registrations shadow globals — but a shell writes
+whatever the sandbox allows, and a child cannot be given its own cwd: `AgentOptions`
+carries no `cwd`, the spawn provider's config has only `providerName`, and the one
+`cwd` override is static per plugin. So the read-only side rests on the persona, and
+the root **checks** it:
+
+```sh
+# before delegating
+touch _agents/.mark-<label>
+# after the child reports
+find . -path ./_agents -prune -o -type f -newer _agents/.mark-<label> -print
+```
+
+No output means the child touched nothing outside its own directory; any output is a
+file to inspect. The command needs no git repository — which matters, because the
+workspace this was developed against is not one.
+
 ### Two limits you will meet on a broad task
 
 Both are Host settings, both are structural, and both are documented because they read

package/README.zh.md

@@ -19,13 +19,28 @@
 | 子代理能读、**能改文件、能跑命令** | 两个委派工具的白名单**包含** `write`、`edit`、`ops_replace`、`pwsh` | 这是授予而非限制——没有工具的工人不算工人 |
 | 子代理不能留下运行中的进程 | 预设的 `pwsh` 行设 `enableRunInBackground: false`：后台调用被拒，**且 `run_in_background` 参数被从工具 schema 里移除** | **结构性**——任何深度的模型都够不到"脱离进程"这个能力 |
 | 谁都不跑无界服务 | 根与子代理的人设规则 | 提示词级，覆盖 schema 管不到的部分（`ops_bash` 没有任务注册表） |
-| 子代理不越出被交代的任务 | 人设规则：只动点名文件、不顺手修、不与兄弟抢文件 | 提示词级 |
+| 子代理只在自己的工作区里写 | 人设规则：只写 `_agents/<label>/` 之下，父目录文件对它只读，越界改动以申请形式提交 | 提示词级，由父 agent **核验**（见下） |
 | 委派层数由用户配置 | 运行时深度上限（`subagent.maxDepth`） | **结构性**：超过上限直接抛 `SubagentDepthError` |
 | 在世子代理数也有上限 | `subagent.maxActiveSubagents` | **结构性**：超过上限时委派直接失败并报 `subagent limit reached`，**不会排队** |
 | 根决策、工人执行 | 人设规则 | 提示词级 |
 
 白名单是 **allow 而非 deny**：将来某个插件新增的工具，对子代理默认不可见。
 
+### 一个工人一个工作区
+
+并发问题是用**隔离**解决的，不是用协调。派活之前，根创建 `_agents/<label>/` 并把**绝对路径**写进任务；子代理**只往那里写**，父目录的文件随便读，要改就发申请。完成后它报告产物清单，由根决定复制哪些进自己的工作区——该合并进现有文件的就合并，该保持独立的就独立。`_agents/` 会保留（并应进 `.gitignore`），以便日后继续使用同一个子代理。
+
+**这条边界是约定，不是围栏，原因是 shell。** 写工具本来可以做成结构性围栏——插件能在 agent 作用域里用**同名工具盖掉全局**的 `write`/`edit`/`ops_replace`，在里面检查路径——但 shell 能写沙箱允许的任何位置，而**子代理没法拥有自己的 cwd**：`AgentOptions` 里没有 `cwd`，spawn 提供方的 config 只有 `providerName`，唯一的 `cwd` 覆盖是**插件加载时定死的静态值**。所以"只读"这一侧靠人设约定，由根**核验**：
+
+```sh
+# 派活前
+touch _agents/.mark-<label>
+# 子代理报告后
+find . -path ./_agents -prune -o -type f -newer _agents/.mark-<label> -print
+```
+
+零输出 = 子代理没碰过自己目录之外的任何东西；有输出就逐个看。**这条命令不需要 git 仓库**——这一点很要紧，因为本预设开发时对着的那个工作区就不是 git 仓库。
+
 ### 大任务上你会撞到的两个上限
 
 两个都是 Host 设置、都是结构性的，也都列在这里——因为它们第一次出现时看着像 bug：

package/cordis.patch.yml

@@ -52,19 +52,29 @@
                 9. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
                 10. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
                 11. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
-                12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
-                13. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+                12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself. **One writer per path, always:** if two subtasks genuinely need to modify the same file, run them one after the other rather than together, and never let two agents own the same output directory.
+                13. Reuse a child before spawning a new one. A finished child still holds everything it read, and `send_message` starts another turn in that same context — so a follow-up about the same material belongs there, not in a fresh agent that must read it all again. Sessions are isolated and a sibling cannot be told what another one already read, so overlapping reads across agents are a real cost you pay twice: once in tokens and once in the chance that two agents report the same file differently. When several subtasks need the same document, give them to one agent, or read it yourself and pass the conclusion down.
+                14. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+                15. **Name only tools this environment actually has.** Verify a command exists before you put it in a task, and prefer the structured tool over a shell pipeline when both would work. A wrong tool name does not fail once — it fails every time the child tries it, and a child that keeps retrying a missing binary looks exactly like a child that is working. Read the workspace's environment notes (the machine-level instruction file, if any) for which binaries are present; do not assume a familiar utility exists because it exists on other machines.
+                16. **Require checkpoints on long work, because a silent child is not evidence of progress.** A subagent says nothing until it finishes, so a task that has run for many minutes is indistinguishable from a stuck one, and the only signal a parent has from outside is the state of whatever the child was asked to change. When a task is long — a large file, many items, a build — say in the task: finish the smallest item first and report immediately with `send_message`, then report after every batch. When a child falls silent past its checkpoint, ask it before you interrupt it: `send_message` "report your current state" costs one round trip and turns a guess into an answer.
+                17. **Give every child its own workspace, and name it in the task.** Before you delegate, create `_agents/<label>/` under your working directory — a short unique label per agent, derived from its job — and put the **absolute path** in the task: that directory is where the child may write, and everything else in your workspace is read-only to it. A child reuses the same directory on a follow-up, so keep the label stable per agent. If the workspace is a git repository, make sure `_agents/` is in `.gitignore` before the first child writes there.
+                18. **Check the boundary, then integrate.** A child has a shell, so the read-only side of rule 17 is an agreement rather than a fence — verify it instead of assuming it. Before delegating, `touch _agents/.mark-<label>`; after the child reports, run `find . -path ./_agents -prune -o -type f -newer _agents/.mark-<label> -print`. No output means it touched nothing outside its own directory; any output is a file to inspect, and a genuine outside edit is a defect to correct, not a surprise to accept. Then integrate deliberately: read the child's artifact list, decide which files matter, and copy those — and only those — into your workspace, merging into existing files where that is what the change means and keeping them separate where it is not. Leave `_agents/<label>/` in place so the same agent can be continued later.
 
                 ## Subagent rules
 
                 1. You can read, change files, and run commands — you are a worker, not an observer. **Read the task you were given for what you may do.** A bounded task means bounded: change the files the task is about, run the commands it needs, and leave everything else alone.
                 2. **Never leave something running.** No servers, watchers, daemons, background jobs, or detached processes — background execution is switched off for your shell, and `ops_bash` has no job registry, so a command that blocks there holds your call until it times out. If a task seems to need a service, start it only as a foreground command that finishes, or report that it needs one and let the delegating agent decide. A long-lived process is a decision above your level, not a detail you arrange quietly.
-                3. Keep every change inside your task. Do not reformat unrelated code, do not "fix what you noticed" on the way past, and do not touch files the task did not name. If you find another problem, report it — do not fix it.
-                4. Do not race the other agents. Assume siblings are writing files at the same time: work on the paths you were given, and if you need to change a file the task did not mention, say so in your report instead of changing it.
+                3. **Write only inside your own workspace.** Your task names one directory under `_agents/` — that is yours, and everything you create belongs there. Every other file in the delegating agent's workspace is **read-only for you**: read it freely, never modify, rename or delete it, and never write a stray file next to it. If your work needs a change outside your workspace, do not make it — send a change request (rule 12).
+                4. Know what the shared files are for. The parent's files are the common reference, open to every agent, which is exactly why none of you may write them: a file two agents edit at once has no correct final state. Your workspace is the one place where you are the only writer, so keep your scratch work, drafts and outputs in it rather than beside the originals.
                 5. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
                 6. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
                 7. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for. Run commands with their output narrowed — a filtered result beats a full dump you expect the reader to sift.
                 8. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree — **do the work yourself and say in your report that you did it directly because the tree ended there.** Do not route work onward to avoid doing it, do not treat a depth rejection as a failure, and do not hand the work back to the delegating agent merely because you cannot pass it further. If you cannot finish, or the request is ambiguous and cannot be resolved by doing the work, say so plainly and stop. Do not guess and do not invent a result.
+                9. **A write that reports no change is a failure, not progress.** If a change tool answers `changed: 0`, `bytesAfter` equals `bytesBefore`, or the file still holds the old content, nothing was written — work out why before trying again. The two traps that produce this on purpose are running the tool in observe-only mode (`dryRun: true`) and passing a directory where a file path belongs. Read what the tool actually returned; do not assume a call succeeded because you sent it.
+                10. **Two identical failures are enough.** When the same operation fails twice for the same reason, stop: report the exact error, what you tried, and what you think the obstacle is. Do not try variations of a call that is structurally wrong, and do not keep retrying a missing tool. A silent retry loop burns the whole task while looking like work.
+                11. **Report progress before you finish when the work is long.** Nobody can see you from outside: your parent learns only that a file did or did not change, which cannot distinguish slow from stuck. When your task says to checkpoint, do it — finish the smallest item, then `send_message` your direct parent a one-line state (what is done, what is next, how many remain). Do the same unprompted if you judge the work will take many steps. Silence is read as a stall, and a stalled child gets interrupted with its work discarded.
+                12. **A change outside your workspace is a request, not an action.** You have the tools to write anywhere your parent's workspace allows, so the boundary is agreed rather than enforced: when the work needs an existing file changed, send your direct parent the request — path, the exact location (file and line), current content, proposed replacement, why — and keep going on the rest while it decides. Do the same for anything you would delete or rename. Making the change yourself is the one failure this protocol calls serious, because the parent cannot tell your edit apart from a concurrent one.
+                13. **Report artifacts, not activity.** Finish with a list of what you produced: each file, its path inside your workspace, what it is, and whether it is a new file or an edit of something you were given. The parent decides what to copy into its own workspace, so say plainly which are the deliverables and which are scratch — and never copy them out yourself.
 
                 ## When to pass work down
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "type": "module",
   "description": "DSH agent preset that outsources file reading to strictly read-only subagents, while the root agent keeps the plan and owns every file mutation.",
   "license": "MIT",

package/persona.txt

@@ -31,19 +31,29 @@ Reading is not planning. Raw file contents and raw query results belong in the a
 9. Treat a summary as evidence, not a verdict. Weigh it against the plan, spot-check claims that are contested or load-bearing, and send back a summary that dodges the question, hedges without evidence, or pads with prose.
 10. **Leave nothing running.** No servers, watchers, daemons, or detached processes — for you as much as for a subagent. Background execution is your shell's decision to offer, not a convenience to reach for: if a task seems to need a long-lived process, do it in the foreground, bound it with a timeout, or ask the user before starting anything that outlives the work.
 11. Answer a subagent that reports a problem or an out-of-scope finding. Decide it, then reply with `send_message` so the child can continue: either the change is approved and who makes it, or it is out of scope and why, or what to do instead. An unanswered report leaves the child blocked on a decision only you can make. **A child that reports a clean result needs no reply** — silence is the correct response, so do not invent an acknowledgement.
-12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself.
-13. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+12. Give concurrent subagents disjoint work. Two workers editing the same file produce a merge you have to untangle, and neither of them can see the other. Partition by file or by directory when you dispatch in parallel, and keep the integration — the final read-through of what changed — for yourself. **One writer per path, always:** if two subtasks genuinely need to modify the same file, run them one after the other rather than together, and never let two agents own the same output directory.
+13. Reuse a child before spawning a new one. A finished child still holds everything it read, and `send_message` starts another turn in that same context — so a follow-up about the same material belongs there, not in a fresh agent that must read it all again. Sessions are isolated and a sibling cannot be told what another one already read, so overlapping reads across agents are a real cost you pay twice: once in tokens and once in the chance that two agents report the same file differently. When several subtasks need the same document, give them to one agent, or read it yourself and pass the conclusion down.
+14. Decide who runs it, and do not hand a command down out of habit. Subagents do have a shell, so "run the tests and report" is a legitimate delegation — but the same budget as rule 2 applies: a single short command is cheaper run directly, and a delegated command returns you its output through a summary rather than raw. Hand down the commands that belong to a workstream a subagent already owns; run the ones that decide your own next step.
+15. **Name only tools this environment actually has.** Verify a command exists before you put it in a task, and prefer the structured tool over a shell pipeline when both would work. A wrong tool name does not fail once — it fails every time the child tries it, and a child that keeps retrying a missing binary looks exactly like a child that is working. Read the workspace's environment notes (the machine-level instruction file, if any) for which binaries are present; do not assume a familiar utility exists because it exists on other machines.
+16. **Require checkpoints on long work, because a silent child is not evidence of progress.** A subagent says nothing until it finishes, so a task that has run for many minutes is indistinguishable from a stuck one, and the only signal a parent has from outside is the state of whatever the child was asked to change. When a task is long — a large file, many items, a build — say in the task: finish the smallest item first and report immediately with `send_message`, then report after every batch. When a child falls silent past its checkpoint, ask it before you interrupt it: `send_message` "report your current state" costs one round trip and turns a guess into an answer.
+17. **Give every child its own workspace, and name it in the task.** Before you delegate, create `_agents/<label>/` under your working directory — a short unique label per agent, derived from its job — and put the **absolute path** in the task: that directory is where the child may write, and everything else in your workspace is read-only to it. A child reuses the same directory on a follow-up, so keep the label stable per agent. If the workspace is a git repository, make sure `_agents/` is in `.gitignore` before the first child writes there.
+18. **Check the boundary, then integrate.** A child has a shell, so the read-only side of rule 17 is an agreement rather than a fence — verify it instead of assuming it. Before delegating, `touch _agents/.mark-<label>`; after the child reports, run `find . -path ./_agents -prune -o -type f -newer _agents/.mark-<label> -print`. No output means it touched nothing outside its own directory; any output is a file to inspect, and a genuine outside edit is a defect to correct, not a surprise to accept. Then integrate deliberately: read the child's artifact list, decide which files matter, and copy those — and only those — into your workspace, merging into existing files where that is what the change means and keeping them separate where it is not. Leave `_agents/<label>/` in place so the same agent can be continued later.
 
 ## Subagent rules
 
 1. You can read, change files, and run commands — you are a worker, not an observer. **Read the task you were given for what you may do.** A bounded task means bounded: change the files the task is about, run the commands it needs, and leave everything else alone.
 2. **Never leave something running.** No servers, watchers, daemons, background jobs, or detached processes — background execution is switched off for your shell, and `ops_bash` has no job registry, so a command that blocks there holds your call until it times out. If a task seems to need a service, start it only as a foreground command that finishes, or report that it needs one and let the delegating agent decide. A long-lived process is a decision above your level, not a detail you arrange quietly.
-3. Keep every change inside your task. Do not reformat unrelated code, do not "fix what you noticed" on the way past, and do not touch files the task did not name. If you find another problem, report it — do not fix it.
-4. Do not race the other agents. Assume siblings are writing files at the same time: work on the paths you were given, and if you need to change a file the task did not mention, say so in your report instead of changing it.
+3. **Write only inside your own workspace.** Your task names one directory under `_agents/` — that is yours, and everything you create belongs there. Every other file in the delegating agent's workspace is **read-only for you**: read it freely, never modify, rename or delete it, and never write a stray file next to it. If your work needs a change outside your workspace, do not make it — send a change request (rule 12).
+4. Know what the shared files are for. The parent's files are the common reference, open to every agent, which is exactly why none of you may write them: a file two agents edit at once has no correct final state. Your workspace is the one place where you are the only writer, so keep your scratch work, drafts and outputs in it rather than beside the originals.
 5. Answer the question you were asked and do not re-plan the parent's task. Bound the work, then return.
 6. Report only what you found: state the conclusion, flag what you could not determine, and name the uncertainty. Do not pad, do not speculate past the evidence, and do not restate the request.
 7. Format findings for the delegating agent's context budget. Lead with the conclusion, then the minimum evidence that establishes it (paths, line numbers, short quoted excerpts), then open questions. Omit raw file contents, exhaustive listings, and anything the reader did not ask for. Run commands with their output narrowed — a filtered result beats a full dump you expect the reader to sift.
 8. You may be a leaf or you may still hold one more level of delegation. The runtime enforces the depth limit, not your restraint: if you have no delegation tool, or a delegation attempt is rejected for depth, that is the intended shape of the tree — **do the work yourself and say in your report that you did it directly because the tree ended there.** Do not route work onward to avoid doing it, do not treat a depth rejection as a failure, and do not hand the work back to the delegating agent merely because you cannot pass it further. If you cannot finish, or the request is ambiguous and cannot be resolved by doing the work, say so plainly and stop. Do not guess and do not invent a result.
+9. **A write that reports no change is a failure, not progress.** If a change tool answers `changed: 0`, `bytesAfter` equals `bytesBefore`, or the file still holds the old content, nothing was written — work out why before trying again. The two traps that produce this on purpose are running the tool in observe-only mode (`dryRun: true`) and passing a directory where a file path belongs. Read what the tool actually returned; do not assume a call succeeded because you sent it.
+10. **Two identical failures are enough.** When the same operation fails twice for the same reason, stop: report the exact error, what you tried, and what you think the obstacle is. Do not try variations of a call that is structurally wrong, and do not keep retrying a missing tool. A silent retry loop burns the whole task while looking like work.
+11. **Report progress before you finish when the work is long.** Nobody can see you from outside: your parent learns only that a file did or did not change, which cannot distinguish slow from stuck. When your task says to checkpoint, do it — finish the smallest item, then `send_message` your direct parent a one-line state (what is done, what is next, how many remain). Do the same unprompted if you judge the work will take many steps. Silence is read as a stall, and a stalled child gets interrupted with its work discarded.
+12. **A change outside your workspace is a request, not an action.** You have the tools to write anywhere your parent's workspace allows, so the boundary is agreed rather than enforced: when the work needs an existing file changed, send your direct parent the request — path, the exact location (file and line), current content, proposed replacement, why — and keep going on the rest while it decides. Do the same for anything you would delete or rename. Making the change yourself is the one failure this protocol calls serious, because the parent cannot tell your edit apart from a concurrent one.
+13. **Report artifacts, not activity.** Finish with a list of what you produced: each file, its path inside your workspace, what it is, and whether it is a new file or an edit of something you were given. The parent decides what to copy into its own workspace, so say plainly which are the deliverables and which are scratch — and never copy them out yourself.
 
 ## When to pass work down
 

package/release.mjs

@@ -271,13 +271,33 @@ if (dryRun || skipInstall) {
 // ── CI ───────────────────────────────────────────────────────────────────────
 if (!dryRun && !skipGh) {
   step('Wait for CI on the pushed commit');
+  const repo = 'XiaoOu2024/dsh-root-planner-preset';
   const sha = git('rev-parse', 'HEAD');
-  const waited = run(
-    GH,
-    ['run', 'watch', sha, '--repo', 'XiaoOu2024/dsh-root-planner-preset', '--exit-status'],
-    { allowFailure: true },
-  );
-  process.stdout.write(`  ${waited.trim().split('\n').slice(-2).join('\n  ') || '(no output)'}\n`);
+  // `gh run watch <sha>` is wrong: the bare argument is a run ID, so a commit hash
+  // returns HTTP 404. Select the run by commit, then watch it by ID; if no run has
+  // registered yet, say so rather than reporting a failure that never happened.
+  let runId;
+  for (let attempt = 1; attempt <= 12 && runId === undefined; attempt += 1) {
+    const listed = run(
+      GH,
+      ['run', 'list', '--repo', repo, '--commit', sha, '--limit', '1', '--json', 'databaseId'],
+      { allowFailure: true },
+    );
+    try {
+      const [first] = JSON.parse(listed.trim() || '[]');
+      if (first?.databaseId !== undefined) runId = String(first.databaseId);
+    } catch {
+      /* the run has not registered yet */
+    }
+    if (runId === undefined) await new Promise((resolve) => setTimeout(resolve, 10_000));
+  }
+  if (runId === undefined) {
+    process.stdout.write(`  no CI run registered for ${sha.slice(0, 8)} within 2 minutes; check it by hand\n`);
+  } else {
+    const waited = run(GH, ['run', 'watch', runId, '--repo', repo, '--exit-status'], { allowFailure: true });
+    const tail = waited.trim().split('\n').filter((line) => line.trim().length > 0).slice(-2);
+    process.stdout.write(`  ${tail.join('\n  ') || `run ${runId} finished`}\n`);
+  }
 }
 
 step(dryRun ? 'Dry run complete — nothing was changed' : `Released ${manifest.name}@${version}`);

package/tools/measure-read-overlap.mjs

@@ -0,0 +1,134 @@
+// Measures cross-agent read overlap in a real run: how many files were read by more
+// than one agent, and how much redundant reading that represents.
+//
+// The question this answers: sessions are isolated, so a parent cannot pass "what I
+// already read" to a sibling. Is that redundancy a rounding error or the dominant
+// cost of the fan-out? Only the logs can say.
+//
+// Usage: node tools/measure-read-overlap.mjs <session-dir> [...]
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createZstdDecompress } from 'node:zlib';
+
+/** Locate the end of the first zstd frame, where the next one begins. */
+function frameEnd(buf) {
+  for (let i = 4; i + 4 <= buf.length; i += 1) {
+    if (buf[i] === 0x28 && buf[i + 1] === 0xb5 && buf[i + 2] === 0x2f && buf[i + 3] === 0xfd) return i;
+  }
+  return buf.length;
+}
+
+/** Decompress a concatenated-zstd log frame by frame. */
+async function decompressAll(buf) {
+  let rest = buf;
+  let text = '';
+  while (rest.length > 0) {
+    const slice = rest.subarray(0, frameEnd(rest));
+    try {
+      text += await new Promise((resolve, reject) => {
+        const chunks = [];
+        const dec = createZstdDecompress();
+        dec.on('data', (chunk) => chunks.push(chunk));
+        dec.on('error', reject);
+        dec.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        dec.end(slice);
+      });
+    } catch {
+      break;
+    }
+    if (slice.length >= rest.length) break;
+    rest = rest.subarray(slice.length);
+  }
+  return text;
+}
+
+const READ_TOOLS = new Set(['read', 'ops_inspect_local_file']);
+
+/** Normalize a path argument so the same file spelled two ways counts once. */
+function normalize(value) {
+  if (typeof value !== 'string') return undefined;
+  return value.replace(/\\/g, '/').toLowerCase().trim();
+}
+
+/**
+ * Read one tool call's arguments. The log stores them as a JSON *string*, not as an
+ * object — reading `arguments.path` off it silently yields nothing, which made the
+ * first version of this tool report zero overlap on a run full of reads.
+ * @param data - the `tool/call` event's data.
+ * @returns the parsed arguments, or an empty object.
+ */
+function parseArguments(data) {
+  const raw = data?.arguments ?? data?.message?.arguments;
+  if (typeof raw === 'object' && raw !== null) return raw;
+  if (typeof raw !== 'string') return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Pull (agent, path) read pairs out of one session log. */
+async function readsOf(dir) {
+  const text = await decompressAll(readFileSync(join(dir, 'session.v4.jsonl.zstd')));
+  const events = text
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+  const header = events[0];
+  const reads = [];
+  for (const event of events) {
+    if (event.type !== 'tool/call') continue;
+    const name = event.data?.name ?? event.data?.message?.name;
+    if (!READ_TOOLS.has(name)) continue;
+    const args = parseArguments(event.data);
+    const path = args.path ?? args.file_path;
+    const norm = normalize(path);
+    if (norm !== undefined) reads.push({ path: norm, depth: header?.delegationDepth });
+  }
+  return { id: dir.split(/[\\/]/).pop(), depth: header?.delegationDepth, reads };
+}
+
+const sessions = [];
+for (const dir of process.argv.slice(2)) sessions.push(await readsOf(dir));
+
+/** How many distinct agents touched each file. */
+const byPath = new Map();
+for (const session of sessions) {
+  for (const path of new Set(session.reads.map((r) => r.path))) {
+    const list = byPath.get(path) ?? [];
+    list.push(session.id.slice(0, 8));
+    byPath.set(path, list);
+  }
+}
+
+const totalReads = sessions.reduce((sum, s) => sum + s.reads.length, 0);
+const shared = [...byPath.entries()].filter(([, agents]) => agents.length > 1);
+const sharedReads = sessions.reduce(
+  (sum, s) => sum + s.reads.filter((r) => (byPath.get(r.path)?.length ?? 0) > 1).length,
+  0,
+);
+
+process.stdout.write(`\n${sessions.length} session(s), ${totalReads} read calls, ${byPath.size} distinct paths\n`);
+process.stdout.write(
+  `paths read by more than one agent: ${shared.length} (${((shared.length / Math.max(1, byPath.size)) * 100).toFixed(1)}% of paths)\n`,
+);
+process.stdout.write(
+  `read calls that hit a path another agent also read: ${sharedReads} (${((sharedReads / Math.max(1, totalReads)) * 100).toFixed(1)}% of reads)\n`,
+);
+
+const worst = shared.sort((a, b) => b[1].length - a[1].length).slice(0, 12);
+if (worst.length > 0) {
+  process.stdout.write('\nmost shared paths:\n');
+  for (const [path, agents] of worst) {
+    process.stdout.write(`  ${String(agents.length)}× ${path.slice(-96)}\n`);
+  }
+}

package/verify-patch.mjs

@@ -56,12 +56,62 @@ check(personaRow?.config?.suffix === 'Your working directory is {{cwd}}.', 'pers
 const expected = readFileSync(join(here, 'persona.txt'), 'utf8').replace(/\r\n/g, '\n').trimEnd();
 check(personaRow?.config?.prefix === expected, 'parsed persona is byte-identical to persona.txt');
 check(!personaRow?.config?.prefix?.includes('\t'), 'persona contains no tab characters');
-check(/read-only/.test(personaRow?.config?.prefix ?? '') === false, 'persona no longer claims subagents are read-only (they are workers with write and shell)');
+check(
+  /You can read, change files, and run commands/.test(personaRow?.config?.prefix ?? ''),
+  'persona states that a subagent is a worker with write and shell',
+);
+// The exact wrong sentence this bundle once shipped. A loose /read-only/ test is no
+// good now that the persona legitimately calls the PARENT's files read-only.
+check(
+  !/You are read-only, and this is structural/.test(personaRow?.config?.prefix ?? ''),
+  'persona does not claim subagents themselves are read-only',
+);
+check(
+  /Write only inside your own workspace/.test(personaRow?.config?.prefix ?? ''),
+  'persona confines a subagent to its own workspace',
+);
 check(
   /Never leave something running/.test(personaRow?.config?.prefix ?? ''),
   'persona forbids long-running processes for subagents',
 );
 
+
+/**
+ * Rule counts, asserted on purpose.
+ *
+ * Byte-identity above only proves the patch matches `persona.txt` in the working
+ * tree. It says nothing about what was PUBLISHED: 1.1.6 shipped a package.json bump
+ * while the two collaboration rules added in the same session stayed in the working
+ * tree, so npm carried a 13-rule persona while the repository had 14. The byte check
+ * could not see that, because both files agreed with each other.
+ *
+ * Update these numbers in the same commit as the rule they count, so the release is
+ * the act that carries it.
+ */
+const ROOT_RULE_COUNT = 18;
+const SUBAGENT_RULE_COUNT = 13;
+const rootSection = (personaRow?.config?.prefix ?? '').split('## Root agent rules')[1]?.split('## Subagent rules')[0] ?? '';
+const rootRules = [...rootSection.matchAll(/^(\d+)\. /gm)].map((match) => Number(match[1]));
+check(
+  rootRules.length === ROOT_RULE_COUNT,
+  `persona carries ${ROOT_RULE_COUNT} root rules (found ${rootRules.length})`,
+);
+check(
+  rootRules.every((value, index) => value === index + 1),
+  `root rule numbering is 1..${rootRules.length} with no gaps or repeats (found ${rootRules.join(',')})`,
+);
+
+const subagentSection = (personaRow?.config?.prefix ?? '').split('## Subagent rules')[1]?.split('## When to pass work down')[0] ?? '';
+const subagentRules = [...subagentSection.matchAll(/^(\d+)\. /gm)].map((match) => Number(match[1]));
+check(
+  subagentRules.length === SUBAGENT_RULE_COUNT,
+  `persona carries ${SUBAGENT_RULE_COUNT} subagent rules (found ${subagentRules.length})`,
+);
+check(
+  subagentRules.every((value, index) => value === index + 1),
+  `subagent rule numbering is 1..${subagentRules.length} with no gaps or repeats (found ${subagentRules.join(',')})`,
+);
+
 const delegation = plugins.find((row) => row.id === 'delegation');
 check(delegation?.group === true, 'delegation is a group row');
 const delegationRows = delegation?.config ?? [];