@piagent/platform 1.51.2 → 1.52.0

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.51.2" title="v1.51.2 docs · VI"><span class="dot"></span>v1.51.2</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.52.0" title="v1.52.0 docs · VI"><span class="dot"></span>v1.52.0</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,21 @@
 <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-51-2" data-release>
+<article class="release latest" id="v1-52-0" data-release>
+  <div class="release-meta"><a class="release-version" href="#v1-52-0">v1.52.0</a><time class="release-date" datetime="2026-11-08">08/11/2026</time></div>
+  <div class="release-body">
+    <h3 data-toc-skip id="v1-52-0-title">Helper công ty có thêm advisor và general làm việc trong bản clone riêng</h3>
+    <p>Harness công ty khai báo mọi helper, và agent chính gọi chúng bằng tên công việc: explore, scout, advisor, general và review. General chỉ sửa code trong bản clone riêng và trả về một git ref để merge.</p>
+    <ul class="release-items">
+      <li data-kind="breaking"><span class="kind kind-breaking">Thay đổi lớn</span><span>Helper được gọi là explore, scout, advisor, general và review; tên cũ research và verify không còn, helper verify bị bỏ.</span></li>
+      <li data-kind="new"><span class="kind kind-new">Mới</span><span>advisor cho ý kiến thứ hai trước quyết định khó: khuyến nghị, các phương án đã loại và rủi ro.</span></li>
+      <li data-kind="new"><span class="kind kind-new">Mới</span><span>general nhận việc lớn trên macOS: sửa, chạy check và commit trong clone riêng, không đụng file của bạn, rồi trả về refs/general/&lt;id&gt;.</span></li>
+      <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>WebUI ghi đúng lỗi của advisor hay general thay vì gọi là lỗi của review.</span></li>
+    </ul>
+    <p class="release-requires"><strong>Cần:</strong> Agent Studio 0.51.0 và Agent Watch 0.15.20 (Windows 0.1.19) để dùng helper advisor và general</p>
+  </div>
+</article>
+<article class="release" id="v1-51-2" data-release>
   <div class="release-meta"><a class="release-version" href="#v1-51-2">v1.51.2</a><time class="release-date" datetime="2026-11-03">03/11/2026</time></div>
   <div class="release-body">
     <h3 data-toc-skip id="v1-51-2-title">Chạy riêng phần test liên quan dùng được với mọi công cụ test</h3>
@@ -408,25 +422,24 @@
     </ul>
   </div>
 </article>
-<article class="release" id="v1-44-0" data-release>
-  <div class="release-meta"><a class="release-version" href="#v1-44-0">v1.44.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-44-0-title">Giữ Pi của bạn, chọn giao diện Terminal, thêm repo skill <span class="tag">không phát hành</span></h3>
-    <p>Đã tag nhưng chưa publish: advisory undici mới trong Pi host làm kiểm tra runtime fail. Thay bằng 1.44.1.</p>
-    <ul class="release-items">
-      <li data-kind="new"><span class="kind kind-new">Mới</span><span>/style chọn giao diện Terminal: system, dark, light của Pi hoặc ocean, paper, contrast, focus của Piagent. Terminal công ty nhớ lựa chọn.</span></li>
-      <li data-kind="new"><span class="kind kind-new">Mới</span><span>piagent skills add mattpocock/skills thêm repo skill GitHub ghim một commit; skill dùng được dạng /skill:tên trong Pi, Terminal công ty và dashboard.</span></li>
-      <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>Setup, install, update không còn hạ pi mới hơn của dev (vd 1.4.0) về bản pin 1.3.0: Piagent giữ bản riêng trong ~/.piagent/pi-host cho phiên công ty, dashboard và lệnh piagent pi.</span></li>
-      <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>piagent-uninstall --with-host gỡ bản Pi riêng của Piagent và giữ nguyên pi mới hơn của dev.</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">74</span></summary>
+    <summary><span>Tháng 10/2026</span><span class="archive-count">75</span></summary>
+    <div class="archive-row" id="v1-44-0">
+      <div class="archive-head"><a class="release-version" href="#v1-44-0">v1.44.0</a> <span class="release-date">28/10/2026</span></div>
+      <div class="archive-body">
+        <p><strong>Giữ Pi của bạn, chọn giao diện Terminal, thêm repo skill</strong> <span class="tag">không phát hành</span> — Đã tag nhưng chưa publish: advisory undici mới trong Pi host làm kiểm tra runtime fail. Thay bằng 1.44.1.</p>
+        <ul class="release-items">
+        <li data-kind="new"><span class="kind kind-new">Mới</span><span>/style chọn giao diện Terminal: system, dark, light của Pi hoặc ocean, paper, contrast, focus của Piagent. Terminal công ty nhớ lựa chọn.</span></li>
+        <li data-kind="new"><span class="kind kind-new">Mới</span><span>piagent skills add mattpocock/skills thêm repo skill GitHub ghim một commit; skill dùng được dạng /skill:tên trong Pi, Terminal công ty và dashboard.</span></li>
+        <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>Setup, install, update không còn hạ pi mới hơn của dev (vd 1.4.0) về bản pin 1.3.0: Piagent giữ bản riêng trong ~/.piagent/pi-host cho phiên công ty, dashboard và lệnh piagent pi.</span></li>
+        <li data-kind="fixed"><span class="kind kind-fixed">Sửa lỗi</span><span>piagent-uninstall --with-host gỡ bản Pi riêng của Piagent và giữ nguyên pi mới hơn của dev.</span></li>
+        </ul>
+      </div>
+    </div>
     <div class="archive-row" id="v1-43-9">
       <div class="archive-head"><a class="release-version" href="#v1-43-9">v1.43.9</a> <span class="release-date">27/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.51.2" title="v1.51.2 docs · VI"><span class="dot"></span>v1.51.2</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.52.0" title="v1.52.0 docs · VI"><span class="dot"></span>v1.52.0</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.51.2" title="v1.51.2 docs · VI"><span class="dot"></span>v1.51.2</a>
+      <a class="version-badge" href="/whats-new" data-docs-version="v1.52.0" title="v1.52.0 docs · VI"><span class="dot"></span>v1.52.0</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": 651,
-      "sha256": "87bed56a6089ee73778f5f9ae3beeb95b1fc5b807f0a124ea5d52126968e29f3"
+      "fileCount": 653,
+      "sha256": "577758e269e6cb8d79d32cec4c354be0ea343404c897c24280dc50f86002ea21"
     }
   ],
   "custodianComparisonRules": {

package/package.json

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

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

@@ -1,3 +1,4 @@
+import { callName } from './role-names.mjs';
 import { memberMessages, memberRequest } from './objections.mjs';
 
 // Several helpers of one role, at the member's request only ("use 3
@@ -30,7 +31,7 @@ export function fanOut(manager, role, args, harness) {
   if (harness) throw Error('managed-copies-invalid: the harness runs one helper per call.');
   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)) return { dropped: n };
-  if (n > MAX_COPIES) throw Error(`managed-copies-invalid: ask for 2 to ${MAX_COPIES} ${role} helpers (copies, or one split line per helper).`);
+  if (n > MAX_COPIES) throw Error(`managed-copies-invalid: ask for 2 to ${MAX_COPIES} ${callName(role)} helpers (copies, or one split line per helper).`);
   return { n, split: split.length ? split : null };
 }
 // The helper's answer, with what the main agent reads above it when it asked
@@ -38,12 +39,12 @@ export function fanOut(manager, role, args, harness) {
 export function withDroppedNote(result, role, asked) {
   const n = asked?.dropped, first = result?.content?.[0];
   if (!n || first?.type !== 'text') return result;
-  const note = `One ${role} helper ran, not ${n}: the member's own words did not ask for ${n} ${role} helpers. Go on with this answer; run several only when the member asks for that many.\n\n`;
+  const note = `One ${callName(role)} helper ran, not ${n}: the member's own words did not ask for ${n} ${callName(role)} helpers. Go on with this answer; run several only when the member asks for that many.\n\n`;
   return { ...result, content: [{ ...first, text: note + first.text }, ...result.content.slice(1)] };
 }
 // 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.'}`;
+  return `\n\nThe member asked for ${fan.n} ${callName(role)} helpers; you are ${callName(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 => {
@@ -53,18 +54,17 @@ const jsonOf = reply => {
 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 }) {
+// one JSON block joining their findings and objections, so the
+// review and objection readers see every copy. `parsed`: every copy
+// gave its JSON. A finding any copy reports stands.
+export function mergeCopies(role, label, answers, { findingsOf, issuesOf }) {
   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 json = { ...(findings ? { findings: findings.slice(0, 40) } : {}), brief_issues: issues,
+    summary: `${n} ${callName(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/general-clone.mjs

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { cacheDirectory } from './language-environment.mjs';
+
+// The general helper changes files, so it never works in the member's
+// project. It works in its own clone: a separate repository with its own
+// .git (refs, config, hooks), no remote, and no writable path to the project
+// or its refs. A linked worktree would share the project's .git, and the
+// sandbox opens a shared git directory for writing. The clone is `--shared`: it
+// borrows the project's object files (read-only inside the sandbox, by the
+// boundary's readRoots) instead of copying them, so it costs about what a
+// worktree costs. The only crossing is takeBack below, run by this runtime,
+// not by the helper: it copies the clone's commits into the project as one
+// private ref, refs/general/<id>, and touches nothing else. The main agent
+// merges that ref itself.
+export const GENERAL_ENTRY = 'agent-watch-general';
+const OWNER = '.piagent-owner';
+const run = promisify(execFile);
+// The clone's own configuration is the helper's to write. The runtime
+// therefore reads it only through git commands that cannot start a program
+// the clone names: these override what a clone's config could set.
+const SAFE = ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', '-c', 'core.alternateRefsCommand=', '-c', 'protocol.file.allow=always'];
+const gitEnv = () => ({ PATH: '/usr/bin:/bin', HOME: os.tmpdir(), GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', LANG: 'en_US.UTF-8' });
+const git = (exe, cwd, args) => run(exe, [...SAFE, ...args], { cwd, env: gitEnv(), maxBuffer: 4 << 20, timeout: 120_000 }).then(r => r.stdout.trim());
+
+// A clone of the project's HEAD. Work not yet committed in the project is not
+// in it: `dirty` lists those paths so the main agent can be told.
+export async function cloneProject(managed) {
+  // The clone's isolation is proven under the macOS sandbox only; the Linux (bubblewrap) path is not, so it stays closed.
+  if (process.platform !== 'darwin') throw Error('managed-general-unavailable: the general helper is not verified on this platform yet; do the work yourself.');
+  const exe = managed.boundary.git, project = managed.cwd;
+  let top, base, dirty, objects;
+  try {
+    top = fs.realpathSync(await git(exe, project, ['rev-parse', '--show-toplevel']));
+    base = await git(exe, project, ['rev-parse', '--verify', 'HEAD']);
+    objects = fs.realpathSync(path.resolve(project, await git(exe, project, ['rev-parse', '--git-path', 'objects'])));
+    dirty = (await git(exe, project, ['status', '--porcelain', '-uall'])).split('\n').filter(Boolean).map(l => l.replace(/^\S{1,2}\s+/, '')).slice(0, 50);
+  } catch { throw Error('managed-general-needs-git: the general helper needs the project to be a git repository with a commit; commit first or do the work yourself.'); }
+  if (top !== project) throw Error('managed-general-needs-git: the general helper needs the project folder to be the repository root.');
+  const id = randomUUID().slice(0, 8), dir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'piagent-general-'));
+  try {
+    await git(exe, dir, ['clone', '-q', '--shared', '--no-tags', '--template=', '--', project, path.join(dir, 'work')]);
+    await git(exe, path.join(dir, 'work'), ['remote', 'remove', 'origin']);
+  } catch (error) { fs.rmSync(dir, { recursive: true, force: true }); throw Error(`managed-general-clone-failed: ${String(error?.message).slice(0, 200)}`); }
+  const token = randomUUID(); // the proof, in the folder and in the session's record, that this runtime made it
+  fs.writeFileSync(path.join(dir, OWNER), token, { mode: 0o600 });
+  const real = fs.realpathSync(path.join(dir, 'work'));
+  return { id, base, dirty, token, objects, cache: cacheDirectory(managed.boundary.userHome, real), root: dir, dir: real };
+}
+
+// The clone's folder, and the package cache the sandbox keyed to it (no later run shares it).
+export function discardClone(clone) { fs.rmSync(clone.root, { recursive: true, force: true }); fs.rmSync(clone.cache, { recursive: true, force: true }); }
+
+// Bring the clone's commits into the project as refs/general/<id> and
+// discard the clone. Returns what the main agent needs to merge them.
+export async function takeBack(managed, clone) {
+  const exe = managed.boundary.git, project = managed.cwd;
+  try {
+    // The helper writes the clone's .git: a gitfile or alternates would point
+    // the fetch at a path outside it.
+    const dotgit = path.join(clone.dir, '.git');
+    const alternates = path.join(dotgit, 'objects/info/alternates');
+    if (!fs.lstatSync(dotgit).isDirectory() || fs.readFileSync(alternates, 'utf8').trim() !== clone.objects) throw Error('the clone was changed to point outside itself');
+    const ref = `refs/general/${clone.id}`;
+    await git(exe, project, ['fetch', '-q', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', clone.dir, `+HEAD:${ref}`]);
+    const head = await git(exe, project, ['rev-parse', '--verify', ref]);
+    if (head === clone.base) { await git(exe, project, ['update-ref', '-d', ref]); return { ref: null, head, base: clone.base, files: [], note: 'The general helper made no commit, so nothing came back. Only committed work is returned.' }; }
+    if (!(await git(exe, project, ['merge-base', '--is-ancestor', clone.base, head]).then(() => true, () => false))) { await git(exe, project, ['update-ref', '-d', ref]); throw Error('the clone no longer descends from the commit it started from'); }
+    const files = (await git(exe, project, ['diff', '--numstat', `${clone.base}..${head}`])).split('\n').filter(Boolean).map(l => { const [added, deleted, ...name] = l.split('\t'); return `+${added} -${deleted} ${name.join('\t')}`; }).slice(0, 80);
+    return { ref, head, base: clone.base, files, note: null };
+  } finally { discardClone(clone); }
+}
+
+// What the main agent reads with the helper's answer.
+export function takeBackText(clone, back) {
+  const dirty = clone.dirty.length ? ` The helper did not see ${clone.dirty.length} uncommitted path(s) in the project (${clone.dirty.slice(0, 8).join(', ')}${clone.dirty.length > 8 ? ', …' : ''}).` : '';
+  if (!back.ref) return `\n\n${back.note}${dirty}`;
+  return `\n\nThe general helper's commits are in ${back.ref} (${back.base.slice(0, 9)}..${back.head.slice(0, 9)}); your files are unchanged. Merge or cherry-pick that ref yourself, run the checks on the result, then ask for review; delete the ref afterwards (git update-ref -d ${back.ref}). Changed:\n${back.files.join('\n')}${dirty}`;
+}
+
+// One entry per general run, so a later turn knows what ran and what came back;
+// "running" with the folder and its token is also the record of what to recover.
+export function recordGeneral(managed, clone, status, back = null) {
+  managed.session.sessionManager.appendCustomEntry(GENERAL_ENTRY, { id: clone.id, base: clone.base, status, root: clone.root, token: clone.token, ...(back?.ref ? { ref: back.ref, head: back.head } : {}), at: new Date().toISOString() });
+}
+// A crash or a kill skips the cleanup above. When the conversation next runs a
+// general helper, a run its record still calls "running" (and this process
+// is not running) has its clone removed only if the folder is provably the one
+// this runtime made: a real folder, ours, directly in the temporary folder,
+// holding the token the record names. Anything else is only reported.
+export function sweepGeneral(managed) {
+  const last = new Map(), tmp = fs.realpathSync(os.tmpdir()), removed = [], unproven = [];
+  for (const e of managed.session.sessionManager.getEntries?.() ?? []) if (e.type === 'custom' && e.customType === GENERAL_ENTRY) last.set(e.data.id, e.data);
+  for (const d of last.values()) {
+    if (d.status !== 'running' || typeof d.root !== 'string' || managed.liveClones?.has(d.root)) continue;
+    let st; try { st = fs.lstatSync(d.root); } catch { continue; } // already gone
+    let owned = false;
+    try {
+      owned = st.isDirectory() && !st.isSymbolicLink() && st.uid === process.getuid() && path.dirname(d.root) === tmp && path.basename(d.root).startsWith('piagent-general-')
+        && fs.readFileSync(path.join(d.root, OWNER), 'utf8') === d.token;
+    } catch { /* no marker: not proven */ }
+    if (owned) { fs.rmSync(d.root, { recursive: true, force: true }); removed.push(d.id); } else unproven.push(d.root);
+  }
+  return { removed, unproven };
+}
+export const sweepText = ({ removed, unproven }) => (removed.length ? `\n\nAn earlier general run (${removed.join(', ')}) was interrupted; its clone folder was removed and any work in it was not returned.` : '')
+  + (unproven.length ? `\n\nA folder an earlier general run recorded could not be proven to be the one it made, so it was left in place: ${unproven.join(', ')}.` : '');

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

@@ -1,14 +1,18 @@
-import { REVIEW_PROMPT, VERIFY_PROMPT, BRIEF_CHECK, BRIEF_ISSUES_JSON, isCheckCommand } from './workflow.mjs';
+import { REVIEW_PROMPT, BRIEF_CHECK, BRIEF_ISSUES_JSON } from './workflow.mjs';
 
 // Each helper role runs at most this often per user message (Studio's MaxHelperCalls).
 export const HELPER_CALLS = 8;
 
 // The helpers a main agent may delegate to, in the Harness's order. Each is
 // optional: only those the company Harness enables (and Agent Watch passes
-// on) are offered. Scout reads the code, research also reads the web, verify
-// re-checks a result with the repository's checks and primary sources,
-// review judges the patch. None of them changes files.
-export const HELPER_ROLES = Object.freeze(['scout', 'research', 'verify', 'review']);
+// on) are offered. The main agent names a helper by its working name; Studio
+// knows the same helper by its Harness role (its grant). explore reads the
+// code, scout reads the web (and the code), advisor gives a second opinion,
+// review judges the patch. general is the only one that changes files, and
+// only in its own clone of the project (general-clone.mjs). Main does small
+// changes, integration and the repository checks itself.
+import { ROLE_NAMES, HELPER_ROLES, callName } from './role-names.mjs';
+export { ROLE_NAMES, HELPER_ROLES, callName };
 export const helperRoles = manifest => HELPER_ROLES.filter(role => manifest?.harness?.configuration?.[role]);
 const WIDE_READING = 'when understanding the task needs more reading than a few batches of files, such as a flow across many modules of an unfamiliar codebase';
 const NETWORK_COMMANDS = 'run_with_network only when a command itself needs the internet or starts a local server or browser, such as end-to-end tests (the user approves each one)';
@@ -24,7 +28,7 @@ export function mainWebLookups(manifest) {
 export function limitedWebTools(tools, currentRun, limit) {
   return tools.map(tool => ({ ...tool, execute: async (...args) => {
     const run = currentRun();
-    if (run && ++run.webLookups > limit) throw Error(`managed-web-lookups-spent: you used your ${limit} quick web lookup(s) for this message. Hand the rest of the web work to the research helper (delegate role "research").`);
+    if (run && ++run.webLookups > limit) throw Error(`managed-web-lookups-spent: you used your ${limit} quick web lookup(s) for this message. Hand the rest of the web work to the scout helper (delegate role "scout").`);
     return tool.execute(...args);
   } }));
 }
@@ -34,15 +38,16 @@ export function webPrompt(roles, lookups = 0) {
   if (!roles.includes('research'))
     return ` Shell commands run without network: use web_search for current information or documentation, web_fetch to read a public https page, and ${NETWORK_COMMANDS}.`;
   return lookups > 0
-    ? ` Shell commands run without network. For one quick fact (a version, a flag, one documentation page) use web_search or web_fetch yourself, at most ${lookups} call(s) per member message; hand anything wider on the web (several sources, comparisons, news, research) to the research helper, and use ${NETWORK_COMMANDS}.`
-    : ` Shell commands run without network and you have no web tools: hand anything on the web (current information, news, documentation, releases, error messages) to the research helper, and use ${NETWORK_COMMANDS}.`;
+    ? ` Shell commands run without network. For one quick fact (a version, a flag, one documentation page) use web_search or web_fetch yourself, at most ${lookups} call(s) per member message; hand anything wider on the web (several sources, comparisons, news, research) to the scout helper, and use ${NETWORK_COMMANDS}.`
+    : ` Shell commands run without network and you have no web tools: hand anything on the web (current information, news, documentation, releases, error messages) to the scout helper, and use ${NETWORK_COMMANDS}.`;
 }
 export function helperPrompt(roles) {
   const lines = [];
-  if (roles.includes('scout')) lines.push(`Use the scout helper (delegate role "scout") ${WIDE_READING}, and work from its file:line findings; do small lookups yourself.`);
-  if (roles.includes('research')) lines.push(roles.includes('scout') ? 'Use the research helper (delegate role "research") for anything on the web (current information, news, library and API docs, releases, error messages), together with the code when needed; give it the question and the answer you need, and work from its summary.'
-    : `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.');
+  if (roles.includes('scout')) lines.push(`Use the explore helper (delegate role "explore") ${WIDE_READING}, and work from its file:line findings; do small lookups yourself.`);
+  if (roles.includes('research')) lines.push(roles.includes('scout') ? 'Use the scout helper (delegate role "scout") for anything on the web (current information, news, library and API docs, releases, error messages), together with the code when needed; give it the question and the answer you need, and work from its summary.'
+    : `Use the scout helper (delegate role "scout") 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('advisor')) lines.push('Use the advisor helper (delegate role "advisor") for a second opinion before a hard or hard-to-reverse decision (a design, a plan, a suspected root cause): give it the question, your options and what you know; it answers with a recommendation and the risks.');
+  if (roles.includes('general')) lines.push('Make small changes yourself. Use the general helper (delegate role "general") for large work, or work that can proceed apart from you: it works in its own clone of the repository, one general helper at a time, and cannot touch your files. It sees only committed work (commit first if it needs your changes); its commits come back as a git ref that you merge or cherry-pick yourself. You then run the repository checks and, for a non-trivial change, ask the review helper.');
   // 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); 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).
@@ -50,44 +55,30 @@ export function helperPrompt(roles) {
   return lines.length ? ' ' + lines.join(' ') : '';
 }
 const HELPER_USES = {
-  scout: () => 'scout: 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). It reads only the project, no web, and answers with file:line facts; your own context stays free for the change.',
-  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.',
+  scout: () => 'explore: 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). It reads only the project, no web, and answers with file:line facts; your own context stays free for the change.',
+  research: roles => roles.includes('scout') ? 'scout: 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.'
+    : 'scout: 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.',
+  advisor: () => 'advisor: a second opinion on a hard or hard-to-reverse decision. It reads the project, has no web, and answers with a recommendation, the options it rejected and the risks.',
+  general: () => 'general: large work, or work that can proceed apart from you. It edits and runs checks in its own clone of the repository (never your files), commits there, and its commits come back as the git ref it names, which you merge or cherry-pick yourself. It sees only committed work. One at a time.',
   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 scout question on what the first answer opened.`;
+  return `Hand work to a helper with its own context. Helpers read the project and cannot call helpers; only general changes files, in its own clone. ${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.
+// Explore, scout and advisor 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.`;
 const RESEARCH_PROMPT = `Research the assigned question. Read only the needed source; use web_search or web_fetch for external documentation. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and what you checked and found nothing in. ${OBJECTIONS}`;
 const SCOUT_PROMPT = `Scout the codebase for the assigned question. Search first (grep, find), then read only the parts that matter. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and where you looked and found nothing. You have no web access: when the answer needs external documentation, say so. ${OBJECTIONS}`;
+const ADVISOR_PROMPT = `Advise on the assigned decision. Read the project as needed. Give a recommendation, the options you rejected and why, and the risks, as points the main agent can act on (file:line where one rests on code). Say what you could not check. You have no web access. ${OBJECTIONS}`;
+const GENERAL_PROMPT = `You are the general helper: you do the assigned work in your own clone of the repository, which is your working folder. Nothing you do there reaches the main agent's files. Make the change, run the checks that cover it, and COMMIT your finished work (git add -A, git commit): only committed work is returned. Do not rewrite or delete history before the starting commit. Answer with what you changed (file:line), the checks you ran and their result, and what you left undone. ${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 delegate.`;
 export const READ_TOOLS = ['read', 'grep', 'find', 'ls'];
-// What each helper may use. Every helper's project is read-only; verify also
-// runs commands there (offline, writes only to its temporary directory).
+export const WRITE_TOOLS = [...READ_TOOLS, 'bash', 'edit', 'write'];
+// What each helper may use. The project is read-only to every helper except
+// general, which writes only its own clone (`writes`).
 export const HELPER_SETUP = {
-  scout: { web: false, commands: false, prompt: SCOUT_PROMPT, label: 'Scout' },
-  research: { web: true, commands: false, prompt: RESEARCH_PROMPT, label: 'Research' },
-  verify: { web: true, commands: true, prompt: VERIFY_PROMPT, label: 'Verify' },
+  scout: { web: false, commands: false, prompt: SCOUT_PROMPT, label: 'Explore' },
+  research: { web: true, commands: false, prompt: RESEARCH_PROMPT, label: 'Scout' },
+  advisor: { web: false, commands: false, prompt: ADVISOR_PROMPT, label: 'Advisor' },
+  general: { web: false, commands: true, writes: true, prompt: GENERAL_PROMPT, label: 'General' },
   review: { web: false, commands: false, prompt: REVIEW_PROMPT, label: 'Review' },
 };
-// A repository check a helper ran counts for the run like one the main
-// agent ran, when the code was the same before and after it: the helper
-// cannot write, but the main agent may edit beside it in the same answer.
-export function countedCheck(managed, tool) {
-  if (tool.name !== 'bash') return tool;
-  return { ...tool, execute: async (...args) => {
-    // Whether anything in the folder moved during the check (another
-    // conversation's edit too: the suite ran on the whole folder); the check
-    // then counts for this conversation's own code.
-    const folder = async () => { try { return await (managed.folderDigest ?? managed.digest).call(managed); } catch { return null; } };
-    const counted = managed.run && isCheckCommand(args[1]?.command, managed.checks.commands), before = counted ? await folder() : null;
-    let ok = false;
-    try { const result = await tool.execute(...args); ok = !result?.isError; return result; }
-    finally {
-      const after = counted && before !== null ? await folder() : null;
-      if (after !== null && after === before) await managed.run.afterTool('bash', args[1], ok, () => managed.digest(), managed);
-    }
-  } };
-}

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

@@ -4,19 +4,19 @@
 // refusal, starts once more: Studio then gives the new helper the next model
 // of its role that serves (an auto role's list).
 import { fenced, HELPER_UNTRUSTED_RULE } from './untrusted.mjs';
-import { relevantChecks } from './check-evidence.mjs';
 import { jobTitle } from './call-purpose.mjs';
 import { ManagedToolBoundary } from './tool-boundary.mjs';
 import { managedResourceLoader } from './resource-loader.mjs';
 import { shareGrant, releaseGrant, slotArgs, baseRole } from './grant-share.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
 import { reviewParts, focusParts, mergeReviews, REVIEW_PARALLEL, emptySnapshot, readBranchBase, readPatchDigest, readPatchSnapshot, resolveReviewBase } from './patch-snapshot.mjs';
-import { reviewFindings, briefIssues, verifyVerdicts } from './workflow.mjs';
+import { reviewFindings, briefIssues } from './workflow.mjs';
 import { currentWorkflow, helperWorkflowPrompt } from './workflow-context.mjs';
-import { anchorText, relayObjection, recordVerdicts } from './objections.mjs';
+import { anchorText, relayObjection } 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 { HELPER_CALLS, HELPER_SETUP, READ_TOOLS, WRITE_TOOLS } from './helper-roles.mjs';
+import { cloneProject, discardClone, takeBack, takeBackText, sweepText, recordGeneral } from './general-clone.mjs';
 import { trackToolFailures } from './tool-failures.mjs';
 import { helperMemoryTools, renewer } from './memory.mjs';
 import { answeredSettlement, failedSettlement, settleHelper, OUTCOME_WORDS } from './helper-settlement.mjs';
@@ -88,7 +88,7 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
     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 });
+    const merged = mergeCopies(role, setup.label, results, { findingsOf: reviewFindings, issuesOf: briefIssues });
     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;
@@ -104,10 +104,9 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
     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 });
+    content: `${setup.label}: ${usage.toLocaleString('en-US')} tokens${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`;
@@ -137,7 +136,7 @@ async function answerUnder(managed, key, task, signal, harness, snapshot, parts,
     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;
+  let boundary, report = null, clone = null, liveRoot = null;
   const sessions = new Set(), watched = new Set(), spec = managed.helperSpecs?.get(role) ?? {};
   const renew = renewer(managed, key, g => verifyGrant(g, managed.manifest, key));
   try {
@@ -146,20 +145,24 @@ async function answerUnder(managed, key, task, signal, harness, snapshot, parts,
     // 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);
-    boundary = new ManagedToolBoundary({ cwd: managed.cwd, sdkRoot: managed.sdk, protectedRoots: managed.protectedRoots, readOnly: true, commands: setup.commands }); boundary.unsandboxed = () => alwaysBypass(managed);
-    const checks = role === 'verify' ? `\n\nRepository checks: ${managed.checks.commands.length ? relevantChecks(managed, managed.checks.commands).map(c => '`' + c + '`').join(', ') : 'none declared or detected; choose the tests, type check or build that cover the claims'}.${managed.run?.fullAsked || managed.run?.scopeChoice === 'full' ? '' : ' Run only the tests that cover the claims: the member decides about a whole-suite run.'}` : '';
+    // General writes, but only in its own clone of the project (general-clone.mjs); the others read the project.
+    if (setup.writes) { clone = await cloneProject(managed); (managed.liveClones ??= new Set()).add(liveRoot = clone.root); recordGeneral(managed, clone, 'running'); }
+    const cwd = clone?.dir ?? managed.cwd;
+    boundary = new ManagedToolBoundary({ cwd, sdkRoot: managed.sdk, protectedRoots: managed.protectedRoots, readOnly: !setup.writes, commands: setup.commands, ...(clone ? { identity: managed.boundary.setup.identity, readRoots: [clone.objects] } : {}) });
+    // Always bypass would run a command on the host, outside the clone.
+    if (!setup.writes) boundary.unsandboxed = () => alwaysBypass(managed);
     // 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, note = '', who = key) => {
-      const { session } = await managed.api.createAgentSession({ cwd: managed.cwd, model, modelRuntime: runtime, thinkingLevel: grant.effort || 'off',
+      const { session } = await managed.api.createAgentSession({ 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: [...unsandboxedBash(managed, boundary.tools(managed.api)).filter(tool => READ_TOOLS.includes(tool.name) || setup.commands && tool.name === 'bash').map(tool => countedCheck(managed, tool)),
+        sessionManager: managed.api.SessionManager.inMemory(cwd), noTools: 'builtin', tools: [...(setup.writes ? WRITE_TOOLS : READ_TOOLS), ...(setup.web ? ['web_search', 'web_fetch'] : []), ...memory.map(tool => tool.name)],
+        customTools: [...(setup.writes ? boundary.tools(managed.api).filter(tool => WRITE_TOOLS.includes(tool.name)) : unsandboxedBash(managed, boundary.tools(managed.api)).filter(tool => READ_TOOLS.includes(tool.name))),
           ...(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 + note + 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)) + 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.
@@ -191,9 +194,10 @@ async function answerUnder(managed, key, task, signal, harness, snapshot, parts,
       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 });
+      const merged = mergeCopies(role, setup.label, answers, { findingsOf: reviewFindings, issuesOf: briefIssues });
       ({ reply, usage } = merged); review = merged.findings ? merged : null;
     }
+    if (clone) { const back = await takeBack(managed, clone); recordGeneral(managed, clone, 'returned', back); reply += takeBackText(clone, back) + sweepText(managed.orphans ?? { removed: [], unproven: [] }); managed.orphans = null; clone = null; }
     const from = snapshot?.from ?? null;
     const stale = snapshot ? (await (from ? readPatchDigest(managed.boundary, null, from.base) : managed.patchDigest())) !== snapshot.digest : false;
     const findings = snapshot ? (review ? review.findings : reviewFindings(reply)) : null;
@@ -201,6 +205,8 @@ async function answerUnder(managed, key, task, signal, harness, snapshot, parts,
     return { reply, usage, review, stale, from, grant, report };
   } catch (error) { report = failedSettlement(role, error, signal, spec); throw error; }
   finally {
+    if (clone) { discardClone(clone); recordGeneral(managed, clone, 'discarded'); }
+    managed.liveClones?.delete(liveRoot);
     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, key);

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

@@ -1,14 +1,14 @@
 // How a helper's attempt ended (Agent Studio 0.34+, POST /v1/managed/settle):
 // one report per attempt, sent with the helper's own run token before its
 // role closes. succeeded: the helper did its job and answered in the form its
-// role needs (verify's verdicts, review's findings); failed: it could not
+// role needs (review's findings); failed: it could not
 // (an error); cancelled: the member or the main agent stopped it;
 // unverifiable: it answered without what its role needs, or its review went
 // stale. Studio reads a helper role that closed without a report as
 // unverifiable: absence is never success or failure.
 import { CLIENT_AGENT } from './client-agent.mjs';
 import { hasCapability } from './studio-capabilities.mjs';
-import { HELPER_ROLES } from './helper-roles.mjs';
+import { ROLE_NAMES } from './helper-roles.mjs';
 
 // The task as the main agent gives it: five optional fields beside the brief.
 export const SPEC_FIELDS = Object.freeze({
@@ -20,7 +20,7 @@ export const SPEC_FIELDS = Object.freeze({
 });
 const field = description => ({ type: 'string', maxLength: 1000, description });
 export function delegateParameters() {
-  return { type: 'object', properties: { role: { type: 'string', enum: HELPER_ROLES },
+  return { type: 'object', properties: { role: { type: 'string', enum: Object.keys(ROLE_NAMES) },
     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)])),
@@ -37,7 +37,7 @@ export const SPEC_PROMPT = ' Give a helper target and acceptance at least (also
 // brief; the main agent's task follows. The spec is kept for the settlement.
 export function delegateArgs(self, args) {
   const spec = Object.fromEntries(Object.keys(SPEC_FIELDS).map(k => [k, typeof args?.[k] === 'string' ? args[k].trim().slice(0, 1000) : '']).filter(([, v]) => v));
-  (self.helperSpecs ??= new Map()).set(args?.role, spec);
+  (self.helperSpecs ??= new Map()).set(ROLE_NAMES[args?.role], spec);
   if (!Object.keys(spec).length) return args;
   const head = Object.entries(spec).map(([k, v]) => `${k[0].toUpperCase()}${k.slice(1)}: ${v}`).join('\n');
   return { ...args, task: `${head}\n\n${args.task}`.slice(0, 12000) };
@@ -58,18 +58,14 @@ export function answeredSettlement(role, reply, details = {}, spec = {}) {
   const summary = clip(typeof parsed?.summary === 'string' && parsed.summary.trim() ? parsed.summary : prose || `${role} answered.`, 600);
   const evidence = [], files = new Set();
   let outcome = 'succeeded';
-  if (role === 'verify') {
-    const verdicts = Array.isArray(parsed?.verdicts) ? parsed.verdicts : null;
-    if (!verdicts) outcome = 'unverifiable';
-    for (const v of verdicts ?? []) evidence.push(clip(`${v?.status ?? '?'}: ${v?.claim ?? ''} — ${v?.evidence ?? ''}`, 300));
-  } else if (role === 'review') {
+  if (role === 'review') {
     if (details.stale) outcome = 'unverifiable';
     else if (details.parsed === false) outcome = 'unverifiable';
     for (const f of details.findings ?? []) { evidence.push(clip(`${f.severity} ${f.file ?? ''}:${f.line ?? ''} ${f.issue ?? ''}`, 300)); if (f.file) files.add(String(f.file)); }
   }
   for (const m of String(reply).matchAll(FILE_LINE)) {
     files.add(m[1].replace(/^\.\//, ''));
-    if (role !== 'verify' && role !== 'review' && evidence.length < 8) evidence.push(clip(`${m[1]}:${m[2]}`, 300));
+    if (role !== 'review' && evidence.length < 8) evidence.push(clip(`${m[1]}:${m[2]}`, 300));
   }
   return { outcome, summary: details.stale ? 'The patch changed during review; this review is stale.' : summary,
     evidence: [...new Set(evidence.filter(Boolean))].slice(0, 8), files: [...files].filter(f => f.length <= 300).slice(0, 50), ...(Object.keys(spec ?? {}).length ? { spec } : {}) };