dsh-root-planner-preset 1.1.6 → 1.1.7

package/cordis.patch.yml

@@ -52,8 +52,9 @@
                 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.
 
                 ## Subagent rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-root-planner-preset",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "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,8 +31,9 @@ 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.
 
 ## Subagent rules
 

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

@@ -62,6 +62,30 @@ check(
   'persona forbids long-running processes for subagents',
 );
 
+/**
+ * Rule count, 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 this number in the same commit as the rule it counts, so the release is the
+ * act that carries it.
+ */
+const ROOT_RULE_COUNT = 14;
+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 delegation = plugins.find((row) => row.id === 'delegation');
 check(delegation?.group === true, 'delegation is a group row');
 const delegationRows = delegation?.config ?? [];