@piagent/platform 1.46.0 → 1.46.1

package/docs-site/whats-new.html

@@ -37,7 +37,7 @@
         <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" width="28" height="28" /></span>
         <span class="brand-name"><b>Piagent</b> <span>Platform</span></span>
       </a>
-      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.0" title="v1.46.0 docs · VI"><span class="dot"></span>v1.46.0</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.1" title="v1.46.1 docs · VI"><span class="dot"></span>v1.46.1</a>
       <nav class="top-nav" aria-label="Tài liệu">
         <a href="/quickstart">Tài liệu</a>
         <a href="/whats-new" aria-current="page">Changelog</a>
@@ -108,7 +108,22 @@
 <div class="release-filter" role="toolbar" aria-label="Lọc theo loại thay đổi"><button type="button" data-filter-kind="all" aria-pressed="true">Tất cả</button><button type="button" data-filter-kind="new" aria-pressed="false">Mới</button><button type="button" data-filter-kind="improved" aria-pressed="false">Cải thiện</button><button type="button" data-filter-kind="fixed" aria-pressed="false">Sửa lỗi</button><button type="button" data-filter-kind="security" aria-pressed="false">Bảo mật</button></div>
 <section class="section releases" data-releases>
 <h2 id="latest" class="sr-only">Mới nhất</h2>
-<article class="release latest" id="v1-46-0" data-release>
+<article class="release latest" id="v1-46-1" data-release>
+  <div class="release-meta"><a class="release-version" href="#v1-46-1">v1.46.1</a><time class="release-date" datetime="2026-10-28">28/10/2026</time></div>
+  <div class="release-body">
+    <h3 data-toc-skip id="v1-46-1-title">Phản biện có sổ ghi, review một nhịp, subagent song song khi được yêu cầu</h3>
+    <p>Harness công ty ghi một sổ phản biện cùng quyết định của main, review một nhịp mỗi lượt, và chỉ chạy 2–3 helper cùng role song song khi member yêu cầu.</p>
+    <ul class="release-items">
+      <li data-kind="new"><span class="kind kind-new">Mới</span><span>Phản biện brief, finding review và claim fail chung một sổ; main ghi quyết định bằng resolve_objection, phản biện sai tiền đề chặn sửa file đến khi được quyết.</span></li>
+      <li data-kind="new"><span class="kind kind-new">Mới</span><span>Mặc định mỗi role một helper; khi member yêu cầu 2–3 helper cùng role, chúng chạy song song, mỗi helper một grant với Agent Studio 0.50.0 và Agent Watch 0.15.17.</span></li>
+      <li data-kind="improved"><span class="kind kind-improved">Cải thiện</span><span>Review một nhịp mỗi lượt: review bắt buộc do harness làm, review lại sau khi sửa chỉ đọc file đã đổi, finding minor chỉ liệt kê.</span></li>
+      <li data-kind="improved"><span class="kind kind-improved">Cải thiện</span><span>Terminal công ty hiện checklist và việc từng subagent đang làm ngay trên ô nhập.</span></li>
+      <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>piagent studio cài fd ở lần mở đầu tiên nên gợi ý @ hiện file và thư mục; trước đây fd không bao giờ được tải, kể cả khi đã có ở /opt/homebrew/bin.</span></li>
+    </ul>
+    <p class="release-requires"><strong>Cần:</strong> Agent Studio 0.50.0 và Agent Watch 0.15.17 (Windows 0.1.18) để subagent chạy song song</p>
+  </div>
+</article>
+<article class="release" id="v1-46-0" data-release>
   <div class="release-meta"><a class="release-version" href="#v1-46-0">v1.46.0</a><time class="release-date" datetime="2026-10-28">28/10/2026</time></div>
   <div class="release-body">
     <h3 data-toc-skip id="v1-46-0-title">Piagent chạy trong Pi home riêng, pi của bạn giữ nguyên bản gốc</h3>
@@ -411,22 +426,21 @@
     </ul>
   </div>
 </article>
-<article class="release" id="v1-38-1" data-release>
-  <div class="release-meta"><a class="release-version" href="#v1-38-1">v1.38.1</a><time class="release-date" datetime="2026-10-23">23/10/2026</time></div>
-  <div class="release-body">
-    <h3 data-toc-skip id="v1-38-1-title">Bản phát hành chính thức của v1.38.0</h3>
-    <p>v1.38.0 không qua release check vì hai test nên chưa từng được phát hành; v1.38.1 là cùng bản đó với hai test đã được sửa.</p>
-    <ul class="release-items">
-      <li data-kind="improved"><span class="kind kind-improved">Cải thiện</span><span>Hai test phát hành nay pass trên Linux và máy chạy chậm, nên editor, terminal, review, checkpoint và Bypass của v1.38.0 có trong bản này.</span></li>
-    </ul>
-  </div>
-</article>
 </section>
 <section class="section archive">
   <h2 id="archive">Các bản trước</h2>
   <p class="section-lead">Bản cũ hơn, gom theo tháng. Mở một tháng để xem từng thay đổi.</p>
   <details class="release-archive">
-    <summary><span>Tháng 10/2026</span><span class="archive-count">57</span></summary>
+    <summary><span>Tháng 10/2026</span><span class="archive-count">58</span></summary>
+    <div class="archive-row" id="v1-38-1">
+      <div class="archive-head"><a class="release-version" href="#v1-38-1">v1.38.1</a> <span class="release-date">23/10/2026</span></div>
+      <div class="archive-body">
+        <p><strong>Bản phát hành chính thức của v1.38.0</strong> — v1.38.0 không qua release check vì hai test nên chưa từng được phát hành; v1.38.1 là cùng bản đó với hai test đã được sửa.</p>
+        <ul class="release-items">
+        <li data-kind="improved"><span class="kind kind-improved">Cải thiện</span><span>Hai test phát hành nay pass trên Linux và máy chạy chậm, nên editor, terminal, review, checkpoint và Bypass của v1.38.0 có trong bản này.</span></li>
+        </ul>
+      </div>
+    </div>
     <div class="archive-row" id="v1-38-0">
       <div class="archive-head"><a class="release-version" href="#v1-38-0">v1.38.0</a> <span class="release-date">23/10/2026</span></div>
       <div class="archive-body">

package/docs-site/windows.html

@@ -37,7 +37,7 @@
         <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" width="28" height="28" /></span>
         <span class="brand-name"><b>Piagent</b> <span>Platform</span></span>
       </a>
-      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.0" title="v1.46.0 docs · VI"><span class="dot"></span>v1.46.0</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.1" title="v1.46.1 docs · VI"><span class="dot"></span>v1.46.1</a>
       <nav class="top-nav" aria-label="Tài liệu">
         <a href="/quickstart">Tài liệu</a>
         <a href="/whats-new">Changelog</a>

package/docs-site/workflows.html

@@ -37,7 +37,7 @@
         <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" width="28" height="28" /></span>
         <span class="brand-name"><b>Piagent</b> <span>Platform</span></span>
       </a>
-      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.0" title="v1.46.0 docs · VI"><span class="dot"></span>v1.46.0</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.46.1" title="v1.46.1 docs · VI"><span class="dot"></span>v1.46.1</a>
       <nav class="top-nav" aria-label="Tài liệu">
         <a href="/quickstart">Tài liệu</a>
         <a href="/whats-new">Changelog</a>

package/evals/private-holdout-v1/public-exposure.v2.json

@@ -256,8 +256,8 @@
     },
     {
       "path": "tests",
-      "fileCount": 635,
-      "sha256": "e192ed7528a5d5a992cd33c3837ee6f779b404e45cedc06f79978e2bfa9272eb"
+      "fileCount": 636,
+      "sha256": "143847ccd4abfed97f9fc6bc5f7e5d654eb1cf83507ed473f5d2344327b14d8e"
     }
   ],
   "custodianComparisonRules": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.46.0",
+  "version": "1.46.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/managed/copies.mjs

@@ -0,0 +1,61 @@
+import { memberMessages, memberRequest } from './objections.mjs';
+
+// Several helpers of one role, at the member's request only ("use 3
+// reviewers", "cho 3 scout"): one delegate call runs 2 to MAX_COPIES helper
+// sessions of the role side by side, each with its own context, and their
+// answers merge into one. The main agent never adds helpers on its own, and
+// the harness never does: the call quotes the member's words that ask for
+// them, and those words must be the member's own and name the number. The
+// copies share the role's grant, so Studio counts the role once while each
+// copy counts against the role's calls for the message.
+export const MAX_COPIES = 3;
+const COUNTS = { two: 2, three: 3, hai: 2, ba: 3 };
+// Words that say the number is of helpers, not of files or steps.
+const HELPER_WORDS = /agent|helper|review|scout|research|verif|nghiên cứu|kiểm|xác minh|trinh sát/;
+const normal = text => String(text ?? '').toLowerCase().normalize('NFC').replace(/\s+/g, ' ').trim();
+// The largest helper count the words name (a digit, or two/three in English or Vietnamese).
+export function namedCount(words) {
+  const found = [...normal(words).matchAll(/(?<![\p{L}\d])(\d+|two|three|hai|ba)(?![\p{L}\d])/gu)].map(m => COUNTS[m[1]] ?? Number(m[1]));
+  return found.length ? Math.max(...found) : 0;
+}
+// The copies a delegate call asks for, checked against the member's words;
+// null for a plain call. `split`: one line per copy naming its share of the work.
+export function fanOut(manager, role, args, harness) {
+  const split = Array.isArray(args?.split) ? args.split.map(s => typeof s === 'string' ? s.trim().slice(0, 500) : '').filter(Boolean) : [];
+  const n = split.length || (Number.isInteger(args?.copies) ? args.copies : 1);
+  if (n <= 1 && !args?.member_words) return null;
+  if (harness) throw Error('managed-copies-invalid: the harness runs one helper per call.');
+  if (n < 2 || n > MAX_COPIES) throw Error(`managed-copies-invalid: ask for 2 to ${MAX_COPIES} ${role} helpers (copies, or one split line per helper).`);
+  const words = normal(args?.member_words);
+  if (words.length < 3 || !memberRequest(memberMessages(manager)).some(text => normal(text).includes(words)) || namedCount(words) < n || !HELPER_WORDS.test(words))
+    throw Error(`managed-copies-not-asked: more than one ${role} helper runs only when the member asks for it. Quote in member_words the member's own words that ask for ${n} (verbatim, with the number); otherwise use one helper.`);
+  return { n, split: split.length ? split : null };
+}
+// What one copy reads under its brief.
+export function copyNote(role, i, fan) {
+  return `\n\nThe member asked for ${fan.n} ${role} helpers; you are ${role} helper ${i + 1} of ${fan.n}. ${fan.split ? `Your share of the work: ${fan.split[i]}. The others cover the rest.` : 'The others have the same brief: answer on your own judgement.'}`;
+}
+
+const jsonOf = reply => {
+  for (const raw of [...String(reply).matchAll(/```json\s*([\s\S]*?)```/g)].map(m => m[1]).reverse()) { try { const v = JSON.parse(raw); if (v && typeof v === 'object') return v; } catch { /* next */ } }
+  return null;
+};
+const unique = (list, key) => { const seen = new Set(); return list.filter(x => { const k = key(x); if (seen.has(k)) return false; seen.add(k); return true; }); };
+const SEVERITY = { blocking: 0, major: 1, minor: 2 };
+// One answer from the copies: each helper's prose (its JSON left out), then
+// one JSON block joining their findings, verdicts and objections, so the
+// review, verify and objection readers see every copy. `parsed`: every copy
+// gave its JSON. A finding or a failed claim any copy reports stands.
+export function mergeCopies(role, label, answers, { findingsOf, issuesOf, verdictsOf }) {
+  const n = answers.length, room = Math.floor(12000 / n);
+  const findings = role === 'review' ? unique(answers.flatMap(a => findingsOf(a.reply) ?? []), f => `${f.severity}|${f.file}|${f.line}|${f.issue}`).sort((a, b) => SEVERITY[a.severity] - SEVERITY[b.severity]) : null;
+  const verdicts = role === 'verify' ? unique(answers.flatMap(a => verdictsOf(a.reply) ?? []), v => `${v.status}|${v.claim}`) : null;
+  const issues = unique(answers.flatMap(a => issuesOf(a.reply) ?? []), i => `${i.kind}|${i.detail}`).slice(0, 5);
+  const parsed = answers.every(a => jsonOf(a.reply));
+  const summaries = answers.map(a => jsonOf(a.reply)?.summary).filter(s => typeof s === 'string').map(s => s.slice(0, 200));
+  const json = { ...(findings ? { findings: findings.slice(0, 40) } : {}), ...(verdicts ? { verdicts: verdicts.slice(0, 40) } : {}), brief_issues: issues,
+    summary: `${n} ${role} helpers${summaries.length ? ': ' + summaries.join(' | ') : ''}`.slice(0, 900) };
+  const body = answers.map((a, i) => `### ${label} helper ${i + 1} of ${n}\n${String(a.reply).replace(/```json\s*[\s\S]*?```/g, '').trim().slice(0, room)}`).join('\n\n');
+  return { reply: `${body}\n\n\`\`\`json\n${JSON.stringify(json)}\n\`\`\``, usage: answers.reduce((total, a) => total + a.usage, 0),
+    ...(findings ? { findings, parsed, blocking: findings.filter(f => f.severity === 'blocking').length } : {}) };
+}

package/packages/piagent-core/managed/grant-share.mjs

@@ -7,7 +7,7 @@ export function shareGrant(owner, role) {
   owner.sharedGrants ??= new Map();
   const shared = owner.sharedGrants.get(role);
   if (shared && Date.now() - shared.at < 60_000) { shared.users++; return shared; }
-  const entry = { at: Date.now(), users: 1, grant: owner.broker.request('renew', { role }) };
+  const entry = { at: Date.now(), users: 1, grant: owner.broker.request('renew', slotArgs(role)) };
   entry.grant.catch(() => { if (owner.sharedGrants.get(role) === entry) owner.sharedGrants.delete(role); });
   owner.sharedGrants.set(role, entry);
   return entry;
@@ -16,3 +16,11 @@ export function shareGrant(owner, role) {
 export function releaseGrant(owner, role, entry) {
   if (--entry.users <= 0 && owner.sharedGrants?.get(role) === entry) owner.sharedGrants.delete(role);
 }
+
+// A helper the member asked for beside another of its role holds a grant of
+// its own: its key is role#slot (slot 2 or 3), the broker's {role, slot}.
+export const baseRole = key => String(key).split('#')[0];
+export function slotArgs(key) {
+  const [role, slot] = String(key).split('#');
+  return slot ? { role, slot: Number(slot) } : { role };
+}

package/packages/piagent-core/managed/helper-roles.mjs

@@ -44,7 +44,9 @@ export function helperPrompt(roles) {
     : `Use the research helper (delegate role "research") for anything on the web (current information, news, documentation) and ${WIDE_READING}; work from its findings and do small code lookups yourself.`);
   if (roles.includes('verify')) lines.push('Before you report a non-trivial result as done, you may have the verify helper (delegate role "verify") confirm it independently: it runs the repository checks on the current code and checks claims against the code and primary sources, answering pass, fail or unverifiable with evidence.');
   // Helpers read the member's request beside the brief and may object to it.
-  if (lines.length) lines.push('A helper sees the member\'s request next to your brief and may object to the brief with evidence (brief_issues). You decide, but answer every objection: send a corrected brief, change your approach, or tell the member why it does not hold. A helper that objects twice for one message goes to the member.');
+  if (lines.length) lines.push('A helper sees the member\'s request next to your brief and may object to the brief with evidence (brief_issues); each objection gets an id. You decide, but check each one at the place its evidence names and record your decision with resolve_objection: accepted with what you changed (a corrected brief, the plan, the code), or rejected with what you checked and why. An objection that the brief rests on a wrong premise or conflicts with the request refuses file changes until you decide it; a rejected one goes back to the helper, and a disagreement that remains goes to the member, as does a second objection from the same helper for one message.');
+  // More than one helper of a role, only at the member's word (copies.mjs).
+  if (lines.length) lines.push('One helper per role works on a brief. Only when the member asks for several of one role ("use 3 subagents", "dùng 2 helper"), run up to 3 in one delegate call: copies for independent answers on the same brief, or split for shares of the work, with member_words quoting the member\'s request. Never add helpers on your own.');
   return lines.length ? ' ' + lines.join(' ') : '';
 }
 const HELPER_USES = {
@@ -52,10 +54,10 @@ const HELPER_USES = {
   research: roles => roles.includes('scout') ? 'research: anything on the web (current information, news, library or API documentation, releases, error messages), with the code when needed. It searches and reads the pages; you get its summary with sources.'
     : 'research: anything on the web (current information, news, documentation; it searches and reads the pages, you get its summary with sources), and before changing an area you do not know that spans more files than you can read in a few batches (where something is computed and every caller, how a flow crosses modules); your own context stays free for the change.',
   verify: () => 'verify: an independent check of a result: it runs the repository checks on the current code (offline, and the project is read-only for its commands) and confirms claims, yours or a helper\'s, against the code and primary sources. It answers pass, fail or unverifiable per claim, with evidence.',
-  review: () => 'review: an independent review of the current patch (this turn\'s changes, commits made in the turn included). To review work committed in earlier turns, pass since: the commit, branch or HEAD~N it started from; when this turn changed nothing, it reviews the branch\'s commits since it left the default branch.',
+  review: () => 'review: an independent review of the current patch (this turn\'s changes, commits made in the turn included). To review work committed in earlier turns, pass since: the commit, branch or HEAD~N it started from; when this turn changed nothing, it reviews the branch\'s commits since it left the default branch. Ask once, when your change is finished, and again only after fixing blocking findings; under a required review the harness reviews the final patch and refuses your own call.',
 };
 export function delegateDescription(roles) {
-  return `Hand work to a helper with its own context. Helpers read the project but cannot change files or call helpers. ${roles.map(role => HELPER_USES[role](roles)).join(' ')} A lookup that one grep or read answers stays with you. Write the task as a brief the helper can act on alone: the goal, what to find or check, where to start and what you already know or ruled out, and the answer you need (file:line facts). One call per helper runs at a time; each can be called again, up to ${HELPER_CALLS} times per user message, for example a second review after fixing what the first one found.`;
+  return `Hand work to a helper with its own context. Helpers read the project but cannot change files or call helpers. ${roles.map(role => HELPER_USES[role](roles)).join(' ')} A lookup that one grep or read answers stays with you. Write the task as a brief the helper can act on alone: the goal, what to find or check, where to start and what you already know or ruled out, and the answer you need (file:line facts). One call per helper runs at a time; each can be called again, up to ${HELPER_CALLS} times per user message, for example a second scout question on what the first answer opened.`;
 }
 // Scout and research end with their objections to the brief, if any.
 const OBJECTIONS = `${BRIEF_CHECK} End your answer with one JSON object in a \`\`\`json block: {${BRIEF_ISSUES_JSON}}, with an empty list when the brief is sound. You cannot change files or delegate.`;

package/packages/piagent-core/managed/helper-run.mjs

@@ -7,12 +7,14 @@ import { fenced, HELPER_UNTRUSTED_RULE } from './untrusted.mjs';
 import { jobTitle } from './call-purpose.mjs';
 import { ManagedToolBoundary } from './tool-boundary.mjs';
 import { managedResourceLoader } from './resource-loader.mjs';
-import { shareGrant, releaseGrant } from './grant-share.mjs';
+import { shareGrant, releaseGrant, slotArgs, baseRole } from './grant-share.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
-import { reviewParts, mergeReviews, REVIEW_PARALLEL, emptySnapshot, readBranchBase, readPatchDigest, readPatchSnapshot, resolveReviewBase } from './patch-snapshot.mjs';
-import { reviewFindings, briefIssues } from './workflow.mjs';
+import { reviewParts, focusParts, mergeReviews, REVIEW_PARALLEL, emptySnapshot, readBranchBase, readPatchDigest, readPatchSnapshot, resolveReviewBase } from './patch-snapshot.mjs';
+import { reviewFindings, briefIssues, verifyVerdicts } from './workflow.mjs';
 import { currentWorkflow, helperWorkflowPrompt } from './workflow-context.mjs';
 import { anchorText, relayObjection, recordVerdicts } from './objections.mjs';
+import { recordFindings } from './ledger.mjs';
+import { copyNote, mergeCopies } from './copies.mjs';
 import { HELPER_CALLS, HELPER_SETUP, READ_TOOLS, countedCheck } from './helper-roles.mjs';
 import { trackToolFailures } from './tool-failures.mjs';
 import { helperMemoryTools, renewer } from './memory.mjs';
@@ -43,14 +45,16 @@ async function reviewSnapshot(managed, harness, since) {
   return branch ? Object.assign(await readPatchSnapshot(managed.boundary, null, branch.base), { from: { kind: 'branch', ref: branch.ref, base: branch.base } }) : snapshot;
 }
 
-export async function runHelper(managed, role, task, signal, harness, { verifyGrant, patiently, title, since }) {
-  const snapshot = role === 'review' ? await reviewSnapshot(managed, harness, since) : null, parts = snapshot ? reviewParts(snapshot) : null;
+export async function runHelper(managed, role, task, signal, harness, { verifyGrant, patiently, title, since, fan = null }) {
+  const snapshot = role === 'review' ? await reviewSnapshot(managed, harness, since) : null;
+  // The harness's re-review after a fix reads only the parts holding a file changed since (reviewFocus).
+  const parts = snapshot ? focusParts(reviewParts(snapshot), harness && !since ? managed.reviewFocus : null) : null;
   // A helper whose company model account is out of usage, or resting after
   // a refusal, starts once more: Studio then gives the new helper the next
   // model of its role that serves (an auto role's list). Helpers read and
   // run checks only, so starting over repeats no change.
   for (let attempt = 1; ; attempt += 1) {
-    try { return await helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title }); }
+    try { return await helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title, fan }); }
     catch (error) {
       if (attempt >= HELPER_ATTEMPTS || signal?.aborted || !HELPER_SWITCH.has(failureCode(error?.message)) || (managed.helperCalls.get(role) ?? 0) >= HELPER_CALLS) throw error;
     }
@@ -59,13 +63,62 @@ export async function runHelper(managed, role, task, signal, harness, { verifyGr
 // A helper's role closes through the same wait as the run's close: a passing
 // failure of Agent Watch's way to Studio is asked again. A close that still
 // fails leaves the helper's answer standing: the role closes with the run,
-// and the next helper of the role closes it first.
-export async function closeRole(managed, role) {
-  try { await viaLink(managed.studioLink, () => managed.broker.request('close', { role })); managed.unclosed?.delete(role); }
-  catch { (managed.unclosed ??= new Set()).add(role); }
+// and the next helper of the role closes it first. `key`: the role, or
+// role#slot for a helper the member asked for beside it (grant-share.mjs).
+export async function closeRole(managed, key) {
+  try { await viaLink(managed.studioLink, () => managed.broker.request('close', slotArgs(key))); managed.unclosed?.delete(key); }
+  catch { (managed.unclosed ??= new Set()).add(key); }
 }
-async function helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title }) {
-  if (managed.unclosed?.has(role)) await closeRole(managed, role);
+// Helpers the member asked for run on grants of their own (slots) when
+// Studio and Agent Watch hold several of a role at once; otherwise side by
+// side on the role's one grant, where Studio takes their requests in turn.
+const slotsReady = managed => (managed.manifest?.broker_features ?? []).includes('helper-slots');
+
+async function helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title, fan }) {
+  const setup = HELPER_SETUP[role], opts = { verifyGrant, patiently, title };
+  let result;
+  if (!fan) result = await answerUnder(managed, role, task, signal, harness, snapshot, parts, opts, ['']);
+  else if (!slotsReady(managed)) result = await answerUnder(managed, role, task, signal, harness, snapshot, parts, opts, Array.from({ length: fan.n }, (_, i) => copyNote(role, i, fan)));
+  else {
+    // One grant per helper, all at once; the first that fails stops the others.
+    const stop = new AbortController(), both = AbortSignal.any([stop.signal, ...(signal ? [signal] : [])]);
+    let results;
+    try { results = await Promise.all(Array.from({ length: fan.n }, (_, i) => answerUnder(managed, i ? `${role}#${i + 1}` : role, task, both, harness, snapshot, parts, opts, [copyNote(role, i, fan)]).catch(error => { stop.abort(); throw error; }))); }
+    catch (error) { throw signal?.aborted ? Error('managed-helper-cancelled') : error; }
+    const merged = mergeCopies(role, setup.label, results, { findingsOf: reviewFindings, issuesOf: briefIssues, verdictsOf: verifyVerdicts });
+    result = { ...results[0], reply: merged.reply, usage: merged.usage, review: merged.findings ? merged : null, stale: results.some(r => r.stale), report: null };
+  }
+  const { reply, usage, review, stale, from, grant } = result;
+  const details = { role, runID: grant.run_id, tokens: usage, patchDigest: snapshot?.digest, stale, ...(fan ? { helpers: fan.n, ...(slotsReady(managed) ? { slots: true } : {}) } : {}), ...(from ? { since: { kind: from.kind, ref: from.ref, base: from.base } } : {}) };
+  if (snapshot) {
+    // Severity-graded findings decide whether the harness sends the agent back.
+    const findings = review ? review.findings : reviewFindings(reply);
+    Object.assign(details, { parsed: review ? review.parsed : !!findings, findings: (findings ?? []).slice(0, 40), blocking: findings?.filter(f => f.severity === 'blocking').length ?? 0 });
+    if (review) Object.assign(details, { parts: parts.parts.length, unread: parts.omitted.map(o => o.path).slice(0, 50) });
+    if (managed.run) { managed.run.reviews += 1; managed.run.blocking += details.blocking; }
+    // A review of earlier commits is not the review of this turn's change;
+    // what each file held then tells a later re-review what changed since.
+    if (!from) { managed.review = details; if (!stale) { recordFindings(managed, findings); managed.reviewFiles = await managed.changedFiles?.(); } }
+    managed.session.sessionManager.appendCustomEntry('agent-watch-review', details);
+  }
+  const verdicts = role === 'verify' ? recordVerdicts(managed, reply, harness, details) : '';
+  const report = result.report ?? answeredSettlement(role, reply, details, managed.helperSpecs?.get(role) ?? {}); details.outcome = report.outcome;
+  await managed.session.sendCustomMessage({ customType: 'agent-watch-helper-receipt', display: true,
+    content: `${setup.label}: ${usage.toLocaleString('en-US')} tokens${verdicts}${fan ? ` · ${fan.n} helpers` : review ? ` · ${parts.parts.length} parts` : ''}${snapshot ? (stale ? ' · review is stale' : ' · patch ' + snapshot.digest.slice(0, 12)) : ''} · ${OUTCOME_WORDS[report.outcome]}.`, details }, { triggerTurn: false });
+  // An objection to the brief comes with the answer; a stale review has none to act on.
+  const objection = stale ? '' : await relayObjection(managed, role, reply, harness);
+  const ending = `Outcome: ${report.outcome}${report.outcome === 'unverifiable' ? ` (${report.summary})` : ''}.\n\n`;
+  // The helper read untrusted content: its answer is data for the main agent.
+  return { content: [{ type: 'text', text: ending + (stale ? 'Review is stale: the patch changed during review. Ask for another review only after fixing blocking findings; under a required review the harness reviews the final patch.' : fenced(`${setup.label} helper's answer`, reply) + objection) }], details };
+}
+
+// One grant of the role (`key`: the role, or role#slot) and the helper
+// sessions that answer under it, one per note (a copy's place among the
+// helpers the member asked for). Its settlement goes to Studio and the grant
+// closes before the answer is used.
+async function answerUnder(managed, key, task, signal, harness, snapshot, parts, { verifyGrant, patiently, title }, notes) {
+  const role = baseRole(key);
+  if (managed.unclosed?.has(key)) await closeRole(managed, key);
   // A long local tool step may outlive the main lease. Refresh authority
   // before asking for a child; the broker serializes concurrent renewals,
   // and main's own searches running beside it share managed renew.
@@ -75,18 +128,18 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
     try {
       const parent = await share.grant;
       verifyGrant(parent, managed.manifest, 'main'); managed.grant = parent;
-      grant = await patiently(() => managed.broker.request('child', { role }), 2);
+      grant = await patiently(() => managed.broker.request('child', slotArgs(key)), 2);
     } finally { releaseGrant(managed, 'main', share); }
-    managed.helperCalls.set(role, (managed.helperCalls.get(role) ?? 0) + 1);
-    try { verifyGrant(grant, managed.manifest, role); }
-    catch (error) { try { await managed.broker.request('close', { role }); } catch { /* closes with the run */ } throw error; }
+    managed.helperCalls.set(role, (managed.helperCalls.get(role) ?? 0) + notes.length); // each helper the member asked for counts
+    try { verifyGrant(grant, managed.manifest, key); }
+    catch (error) { try { await managed.broker.request('close', slotArgs(key)); } catch { /* closes with the run */ } throw error; }
   } catch (error) { throw Error(`managed-helper-failed: ${describeFailure(role, failureText(error))}`); }
   let boundary, report = null;
-  const sessions = new Set(), spec = managed.helperSpecs?.get(role) ?? {};
-  const renew = renewer(managed, role, g => verifyGrant(g, managed.manifest, role));
+  const sessions = new Set(), watched = new Set(), spec = managed.helperSpecs?.get(role) ?? {};
+  const renew = renewer(managed, key, g => verifyGrant(g, managed.manifest, key));
   try {
     const runtime = await managed.api.ModelRuntime.create({ credentials: new managed.ai.InMemoryCredentialStore(), modelsPath: null, refreshOnCreate: false, allowModelNetwork: false });
-    const model = managed.installModel(runtime, grant); managed.wrapStreams(runtime, role);
+    const model = managed.installModel(runtime, grant); managed.wrapStreams(runtime, key);
     // Studio's logs name the job by its title (the brief's first line without one).
     (managed.jobTitles ??= new WeakMap()).set(runtime, jobTitle(task, title));
     const setup = HELPER_SETUP[role], memory = helperMemoryTools(managed, () => grant, renew);
@@ -95,15 +148,15 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
     // One helper session answers the brief (with one part of the patch for a
     // review in parts); its reply and tokens. A helper runs at its role's
     // level from Studio (fixed by the Harness, or its main agent's).
-    const ask = async extra => {
+    const ask = async (extra, note = '', who = key) => {
       const { session } = await managed.api.createAgentSession({ cwd: managed.cwd, model, modelRuntime: runtime, thinkingLevel: grant.effort || 'off',
         settingsManager: managed.api.SettingsManager.inMemory({ retry: { enabled: false, provider: { maxRetries: 0 } }, cacheWarming: 'off' }),
         sessionManager: managed.api.SessionManager.inMemory(managed.cwd), noTools: 'builtin', tools: [...READ_TOOLS, ...(setup.commands ? ['bash'] : []), ...(setup.web ? ['web_search', 'web_fetch'] : []), ...memory.map(tool => tool.name)],
         customTools: [...boundary.tools(managed.api).filter(tool => READ_TOOLS.includes(tool.name) || setup.commands && tool.name === 'bash').map(tool => countedCheck(managed, tool)),
-          ...(setup.web ? managed.webTools(runtime, role) : []), ...memory], resourceLoader: managedResourceLoader(managed.api, { systemPrompt: setup.prompt + HELPER_UNTRUSTED_RULE }) });
-      sessions.add(session); trackToolFailures(managed, session, role);
+          ...(setup.web ? managed.webTools(runtime, key) : []), ...memory], resourceLoader: managedResourceLoader(managed.api, { systemPrompt: setup.prompt + HELPER_UNTRUSTED_RULE }) });
+      sessions.add(session); trackToolFailures(managed, session, role); watched.add(who); watchHelper(managed, who, session, task, title);
       const abort = () => void session.abort(); signal?.addEventListener('abort', abort, { once: true });
-      try { if (signal?.aborted) throw Error('managed-helper-cancelled'); await session.prompt(anchorText(managed.session.sessionManager, harness) + task + helperWorkflowPrompt(currentWorkflow(managed.session.sessionManager)) + checks + extra, { expandPromptTemplates: false }); }
+      try { if (signal?.aborted) throw Error('managed-helper-cancelled'); await session.prompt(anchorText(managed.session.sessionManager, harness) + task + note + helperWorkflowPrompt(currentWorkflow(managed.session.sessionManager)) + checks + extra, { expandPromptTemplates: false }); }
       finally { signal?.removeEventListener('abort', abort); }
       const messages = session.messages.filter(m => m.role === 'assistant');
       // The main agent (and the member) learn why a helper failed, not just that it did.
@@ -112,50 +165,65 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
       if (!messages.length || messages.at(-1).stopReason === 'aborted') throw Error(signal?.aborted ? 'managed-helper-cancelled' : 'managed-helper-failed');
       return { reply: messages.map(textContent).join('\n'), usage: messages.reduce((n, m) => n + (m.usage?.totalTokens ?? 0), 0) };
     };
-    let reply, usage, review = null;
-    if (!parts || parts.parts.length === 1) {
-      ({ reply, usage } = await ask(parts ? `\n${parts.parts[0].text}` : ''));
-      reply = reply.slice(0, 16000);
-    } else {
+    // One helper's answer: the brief (with the whole patch, or the patch in parts for a large review).
+    const once = async (note = '', who = key) => {
+      if (!parts || parts.parts.length === 1) { const answer = await ask(parts ? `\n${parts.parts[0].text}` : '', note, who); return { ...answer, reply: answer.reply.slice(0, 16000), review: null }; }
       // A large patch: one reviewer per part, REVIEW_PARALLEL at a time (Studio
       // admits one request of a role at a time); the first part that fails
       // stops the others.
       const answers = new Array(parts.parts.length);
       let next = 0;
       const reviewer = async () => {
-        while (next < parts.parts.length) { const i = next++; answers[i] = await ask(`\n${parts.parts[i].text}`); }
+        while (next < parts.parts.length) { const i = next++; answers[i] = await ask(`\n${parts.parts[i].text}`, note, who); }
       };
       try { await Promise.all(Array.from({ length: Math.min(REVIEW_PARALLEL, parts.parts.length) }, reviewer)); }
       catch (error) { next = parts.parts.length; for (const session of sessions) void session.abort(); throw error; }
-      review = mergeReviews(parts, answers, { findingsOf: reviewFindings, issuesOf: briefIssues });
-      ({ reply, usage } = review);
+      const review = mergeReviews(parts, answers, { findingsOf: reviewFindings, issuesOf: briefIssues });
+      return { reply: review.reply, usage: review.usage, review };
+    };
+    let reply, usage, review = null;
+    if (notes.length === 1) ({ reply, usage, review } = await once(notes[0]));
+    else {
+      // Helpers the member asked for on this one grant, each on its own; the first that fails stops the others.
+      let answers;
+      try { answers = await Promise.all(notes.map((note, i) => once(note, i ? `${role}#${i + 1}` : key))); }
+      catch (error) { for (const session of sessions) void session.abort(); throw error; }
+      const merged = mergeCopies(role, setup.label, answers, { findingsOf: reviewFindings, issuesOf: briefIssues, verdictsOf: verifyVerdicts });
+      ({ reply, usage } = merged); review = merged.findings ? merged : null;
     }
     const from = snapshot?.from ?? null;
     const stale = snapshot ? (await (from ? readPatchDigest(managed.boundary, null, from.base) : managed.patchDigest())) !== snapshot.digest : false;
-    const details = { role, runID: grant.run_id, tokens: usage, patchDigest: snapshot?.digest, stale, ...(from ? { since: { kind: from.kind, ref: from.ref, base: from.base } } : {}) };
-    if (snapshot) {
-      // Severity-graded findings decide whether the harness sends the agent back.
-      const findings = review ? review.findings : reviewFindings(reply);
-      Object.assign(details, { parsed: review ? review.parsed : !!findings, findings: (findings ?? []).slice(0, 40), blocking: findings?.filter(f => f.severity === 'blocking').length ?? 0 });
-      if (review) Object.assign(details, { parts: parts.parts.length, unread: parts.omitted.map(o => o.path).slice(0, 50) });
-      if (managed.run) { managed.run.reviews += 1; managed.run.blocking += details.blocking; }
-      // A review of earlier commits is not the review of this turn's change.
-      if (!from) managed.review = details;
-      managed.session.sessionManager.appendCustomEntry('agent-watch-review', details);
-    }
-    const verdicts = role === 'verify' ? recordVerdicts(managed.run, reply, harness, details) : '';
-    report = answeredSettlement(role, reply, details, spec); details.outcome = report.outcome;
-    await managed.session.sendCustomMessage({ customType: 'agent-watch-helper-receipt', display: true,
-      content: `${setup.label}: ${usage.toLocaleString('en-US')} tokens${verdicts}${review ? ` · ${parts.parts.length} parts` : ''}${snapshot ? (stale ? ' · review is stale' : ' · patch ' + snapshot.digest.slice(0, 12)) : ''} · ${OUTCOME_WORDS[report.outcome]}.`, details }, { triggerTurn: false });
-    // An objection to the brief comes with the answer; a stale review has none to act on.
-    const objection = stale ? '' : await relayObjection(managed, role, reply, harness);
-    const ending = `Outcome: ${report.outcome}${report.outcome === 'unverifiable' ? ` (${report.summary})` : ''}.\n\n`;
-    // The helper read untrusted content: its answer is data for the main agent.
-    return { content: [{ type: 'text', text: ending + (stale ? 'Review is stale: the patch changed during review. Obtain a new review for the current patch.' : fenced(`${setup.label} helper's answer`, reply) + objection) }], details };
+    const findings = snapshot ? (review ? review.findings : reviewFindings(reply)) : null;
+    report = answeredSettlement(role, reply, snapshot ? { stale, parsed: review ? review.parsed : !!findings, findings: findings ?? [] } : {}, spec);
+    return { reply, usage, review, stale, from, grant, report };
   } catch (error) { report = failedSettlement(role, error, signal, spec); throw error; }
   finally {
     for (const session of sessions) session.dispose(); await boundary?.dispose();
     await settleHelper(managed, renew.lease, report); // with the role's current token, before it closes
-    await closeRole(managed, role);
+    await closeRole(managed, key);
+    for (const who of watched) helperState(managed, who, null);
   }
 }
+
+// The helpers running now and what each is doing, told to the session's
+// listeners (the terminal's subagent panel, the WebUI) as it changes.
+export function helperState(managed, key, state) {
+  const states = managed.helperStates ??= new Map();
+  if (state) states.set(key, state); else states.delete(key);
+  managed.notify?.({ type: 'managed_helper_state', helpers: [...states].map(([k, s]) => ({ key: k, role: baseRole(k), slot: slotArgs(k).slot ?? 1, ...s })) });
+}
+// What a helper is doing, for the terminal's subagent panel: the job and its
+// latest tool step, told to listeners as it changes (company-terminal.mjs).
+function watchHelper(managed, key, session, task, title) {
+  const job = String(title || task.split('\n').find(line => line.trim()) || '').trim().slice(0, 120);
+  helperState(managed, key, { job, step: 'đọc brief' });
+  session.subscribe?.(event => {
+    if (event?.type !== 'tool_execution_start') return;
+    helperState(managed, key, { job, step: stepText(event.toolName, event.args) });
+  });
+}
+const STEP = { read: 'đọc', grep: 'tìm', find: 'tìm file', ls: 'xem thư mục', bash: 'chạy', web_search: 'tìm trên web', web_fetch: 'đọc trang', memory_search: 'tra team memory', memory_ask: 'hỏi team memory' };
+export function stepText(tool, args = {}) {
+  const what = args?.path ?? args?.pattern ?? args?.command ?? args?.query ?? args?.url ?? '';
+  return `${STEP[tool] ?? tool}${what ? ' ' + String(what).replace(/\s+/g, ' ').slice(0, 80) : ''}`;
+}

package/packages/piagent-core/managed/helper-settlement.mjs

@@ -24,7 +24,11 @@ export function delegateParameters() {
     title: { type: 'string', maxLength: 120, description: 'One line naming the job, for the company logs (for example "Find where login tokens are stored").' },
     task: { type: 'string', minLength: 1, maxLength: 12000 },
     ...Object.fromEntries(Object.entries(SPEC_FIELDS).map(([name, description]) => [name, field(description)])),
-    since: { type: 'string', maxLength: 200, description: 'Review only: the commit, branch or HEAD~N the work to review started from (work committed in earlier turns).' } },
+    since: { type: 'string', maxLength: 200, description: 'Review only: the commit, branch or HEAD~N the work to review started from (work committed in earlier turns).' },
+    // Several helpers of the role, only at the member's request (copies.mjs).
+    copies: { type: 'integer', minimum: 2, maximum: 3, description: 'Only when the member asked for several helpers of this role: how many (2 or 3) run side by side on this brief. Never on your own.' },
+    split: { type: 'array', minItems: 2, maxItems: 3, items: { type: 'string', minLength: 1, maxLength: 500 }, description: 'Instead of copies: one line per helper naming its share of the work, when the member asked for several and the work divides.' },
+    member_words: { type: 'string', maxLength: 300, description: 'With copies or split: the member\'s own words, verbatim, that ask for that many helpers.' } },
   required: ['role', 'task'], additionalProperties: false };
 }
 export const SPEC_PROMPT = ' Give a helper target and acceptance at least (also change, constraints and ownership when they matter): it answers against them, and its ending is recorded with them.';