@piagent/platform 1.51.1 → 1.52.0

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 } : {}) };

package/packages/piagent-core/managed/language-environment.mjs

@@ -121,10 +121,14 @@ function linkGradleDistributions(source, target) {
   }
 }
 
+// The per-project package cache a sandboxed command may write.
+export function cacheDirectory(userHome, repositoryTop) {
+  const root = process.platform === 'linux' ? path.join(process.env.XDG_CACHE_HOME || path.join(userHome, '.cache'), 'piagent/sandbox') : path.join(userHome, 'Library/Caches/Piagent/sandbox');
+  return path.join(root, createHash('sha256').update(repositoryTop).digest('hex').slice(0, 24));
+}
 export function languageEnvironment({ userHome, repositoryTop, home }) {
   const linux = process.platform === 'linux';
-  const root = linux ? path.join(process.env.XDG_CACHE_HOME || path.join(userHome, '.cache'), 'piagent/sandbox') : path.join(userHome, 'Library/Caches/Piagent/sandbox');
-  const cache = path.join(root, createHash('sha256').update(repositoryTop).digest('hex').slice(0, 24));
+  const cache = cacheDirectory(userHome, repositoryTop), root = path.dirname(cache);
   fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
   fs.chmodSync(cache, 0o700);
   const now = new Date(); try { fs.utimesSync(cache, now, now); } catch { /* best effort */ }

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

@@ -1,11 +1,12 @@
+import { callName } from './role-names.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { briefIssues } from './workflow.mjs';
 
 // The objection ledger: what a helper holds against the main agent's work in
 // one run (one member message), and what the main agent decided about it.
-// A helper's objection to its brief, a review finding and a failed verify
-// claim are one kind of item: open until the main agent resolves it with
+// A helper's objection to its brief and a review finding are one kind
+// of item: open until the main agent resolves it with
 // resolve_objection (accepted with what it changed, or rejected with what it
 // checked and why), and a rejection of a required item goes back to the
 // helper once; a disagreement that remains goes to the member. The run's
@@ -50,7 +51,7 @@ const open = run => ledgerOf(run).filter(i => i.status === 'open');
 export const blockingItems = run => open(run).filter(i => i.required && i.source === 'brief');
 
 // Adds items from one helper answer. `source`: brief (an objection to the
-// brief), review (blocking and major findings) or verify (failed claims).
+// brief), review (blocking and major findings) 
 export function addItems(managed, source, role, list, { required } = {}) {
   const run = managed.run;
   if (!run || !list?.length) return [];
@@ -64,7 +65,7 @@ export function addItems(managed, source, role, list, { required } = {}) {
   }
   return added;
 }
-export const itemText = i => `${i.id} [${i.source === 'brief' ? i.kind : i.source === 'review' ? i.kind : 'failed claim'}] ${i.role}: ${i.detail}${i.evidence ? ` (evidence: ${i.evidence}${i.place === 'missing' ? '; the harness found no such place' : ''})` : ''}`;
+export const itemText = i => `${i.id} [${i.source === 'brief' ? i.kind : i.source === 'review' ? i.kind : 'failed claim'}] ${callName(i.role)}: ${i.detail}${i.evidence ? ` (evidence: ${i.evidence}${i.place === 'missing' ? '; the harness found no such place' : ''})` : ''}`;
 export const setStatus = (item, status, extra = {}) => Object.assign(item, { status, ...extra });
 export function saveLedger(managed) {
   const items = ledgerOf(managed.run);
@@ -75,7 +76,7 @@ export function saveLedger(managed) {
 // checked. An accepted item names what changed; a rejected one says why.
 export function resolveTool(owner) {
   return { name: 'resolve_objection', label: 'Objection',
-    description: 'Record your decision on an objection a helper raised (its id, such as o1): a brief objection, a review finding or a failed verify claim. Check it first at the place its evidence names. accepted: you agree; say what you changed (a corrected brief, the plan, the code). rejected: say what you checked (file:line, a command and its result) and why the objection does not hold; a rejected required objection goes back to the helper, and a disagreement that remains goes to the member.',
+    description: 'Record your decision on an objection a helper raised (its id, such as o1): a brief objection or a review finding. Check it first at the place its evidence names. accepted: you agree; say what you changed (a corrected brief, the plan, the code). rejected: say what you checked (file:line, a command and its result) and why the objection does not hold; a rejected required objection goes back to the helper, and a disagreement that remains goes to the member.',
     parameters: { type: 'object', properties: { id: { type: 'string', maxLength: 10 }, decision: { type: 'string', enum: DECISIONS }, checked: { type: 'string', minLength: 1, maxLength: 300 },
       change: { type: 'string', maxLength: 300 }, reason: { type: 'string', maxLength: 500 } }, required: ['id', 'decision', 'checked'], additionalProperties: false },
     execute: async (_id, args) => {
@@ -87,7 +88,7 @@ export function resolveTool(owner) {
       if (args.decision === 'rejected' && !clip(args.reason, 500)) throw Error('managed-objection-invalid: a rejected objection says why it does not hold.');
       const resolution = { decision: args.decision, checked: clip(args.checked, 300), ...(args.change ? { change: clip(args.change, 300) } : {}), ...(args.reason ? { reason: clip(args.reason, 500) } : {}) };
       setStatus(item, args.decision, { resolution });
-      const back = args.decision === 'rejected' && item.required ? ` The ${item.role} subagent judges your reason before the turn ends.` : '';
+      const back = args.decision === 'rejected' && item.required ? ` The ${callName(item.role)} subagent judges your reason before the turn ends.` : '';
       return { content: [{ type: 'text', text: `Recorded: ${item.id} ${args.decision}.${back}` }], details: { id: item.id, decision: args.decision } };
     } };
 }
@@ -125,12 +126,12 @@ export async function settleLedger(managed, run, { note, send, signal }) {
   const rejected = toRejudge(run)[0];
   if (rejected) {
     rejected.rejudged = true; let reply;
-    await note(`Harness: the ${rejected.role} subagent judges the main agent's reason for rejecting ${rejected.id}.`, { phase: 'rejudge', role: rejected.role, id: rejected.id });
-    try { reply = (await managed.delegate({ role: rejected.role, task: rejudgeBrief(rejected) }, signal, { harness: true })).content.map(p => p.text).join('\n'); }
+    await note(`Harness: the ${callName(rejected.role)} subagent judges the main agent's reason for rejecting ${rejected.id}.`, { phase: 'rejudge', role: rejected.role, id: rejected.id });
+    try { reply = (await managed.delegate({ role: callName(rejected.role), task: rejudgeBrief(rejected) }, signal, { harness: true })).content.map(p => p.text).join('\n'); }
     catch { return true; }
     if (!briefIssues(reply)?.length) { setStatus(rejected, 'withdrawn'); return true; }
     setStatus(rejected, 'disputed'); run.disputes.push({ source: rejected.role, brief: true });
-    await note(`Harness: the ${rejected.role} subagent keeps its objection; the member decides.\n${itemText(rejected)}`, { phase: 'dispute', role: rejected.role, id: rejected.id });
+    await note(`Harness: the ${callName(rejected.role)} subagent keeps its objection; the member decides.\n${itemText(rejected)}`, { phase: 'dispute', role: rejected.role, id: rejected.id });
     return true;
   }
   const asked = run.decidedAsked ??= new Set(), pending = undecided(run).filter(item => !asked.has(item.id));
@@ -142,7 +143,7 @@ export async function settleLedger(managed, run, { note, send, signal }) {
 
 // What the main agent still has to decide before the turn ends: required
 // items, review findings above minor, brief objections it never answered.
-export const undecided = run => open(run).filter(i => i.required || i.source !== 'verify');
+export const undecided = run => open(run);
 export function decideText(items) {
   return `Harness: ${items.length} objection(s) have no decision yet:\n${items.map(i => '- ' + itemText(i)).join('\n')}\nCheck each at the place its evidence names, then record your decision with resolve_objection: accepted with what you changed, or rejected with what you checked and why. Minor review findings need nothing; no new review follows.`;
 }

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

@@ -1,4 +1,5 @@
-import { briefIssues, currentPlan, planText, verifyVerdicts } from './workflow.mjs';
+import { callName } from './helper-roles.mjs';
+import { briefIssues, currentPlan, planText } from './workflow.mjs';
 import { addItems, itemText, ledgerOf, setStatus } from './ledger.mjs';
 export { resolveTool } from './ledger.mjs';
 
@@ -42,10 +43,10 @@ export function anchorText(manager, harness) {
 // reviews the final patch), else once, and again only after blocking findings.
 export function beforeDelegate(run, role, harness, { since = null, review = null, changed = false, asked = false } = {}) {
   if (!run || harness) return;
-  if (run.disputes.some(d => d.source === role && d.brief)) throw Error(`managed-helper-disputed: the ${role} subagent objected to your briefs twice for this message, so the member decides. Tell them what it objects to and what you decided; do not delegate to it again before their next message.`);
+  if (run.disputes.some(d => d.source === role && d.brief)) throw Error(`managed-helper-disputed: the ${callName(role)} subagent objected to your briefs twice for this message, so the member decides. Tell them what it objects to and what you decided; do not delegate to it again before their next message.`);
   const mine = ledgerOf(run).filter(i => i.source === 'brief' && i.role === role && i.status === 'open');
   const blocked = mine.filter(i => i.required);
-  if (blocked.length) throw Error(`managed-objection-open: the ${role} subagent objected to your brief; record your decision with resolve_objection before you brief it again.\n${blocked.map(itemText).join('\n')}`);
+  if (blocked.length) throw Error(`managed-objection-open: the ${callName(role)} subagent objected to your brief; record your decision with resolve_objection before you brief it again.\n${blocked.map(itemText).join('\n')}`);
   // Reviewers the member asked for (copies.mjs) run at their word.
   if (role === 'review' && !since && changed && !asked) {
     if (run.policy.review === 'require') throw Error('managed-review-by-harness: the harness reviews the final patch when you finish; do not ask for a review yourself. Finish the change and its checks.');
@@ -67,29 +68,11 @@ export async function relayObjection(managed, role, reply, harness) {
   const second = ledgerOf(run).some(i => i.source === 'brief' && i.role === role), items = addItems(managed, 'brief', role, issues), list = items.map(itemText).join('\n');
   if (second) { run.disputes.push({ source: role, brief: true }); for (const item of items) setStatus(item, 'disputed'); }
   await managed.session.sendCustomMessage({ customType: 'agent-watch-process', display: true,
-    content: second ? `Harness: the ${role} subagent objected to a brief a second time for this message; the exchange stops and the member decides.\n${list}`
-      : `Harness: the ${role} subagent objected to the brief the main agent gave it:\n${list}`,
+    content: second ? `Harness: the ${callName(role)} subagent objected to a brief a second time for this message; the exchange stops and the member decides.\n${list}`
+      : `Harness: the ${callName(role)} subagent objected to the brief the main agent gave it:\n${list}`,
     details: { phase: second ? 'dispute' : 'objection', role, by: 'main', issues: issues.map(({ kind, detail }) => ({ kind, detail })), ids: items.map(i => i.id) } }, { triggerTurn: false });
-  if (second) return `\n\n[Harness] The ${role} subagent objected to your brief again. This is its second objection for this message, so the harness ends the exchange: do not delegate to it again before the member's next message. Tell the member plainly what it objects to and what you decided, and let them decide.`;
+  if (second) return `\n\n[Harness] The ${callName(role)} subagent objected to your brief again. This is its second objection for this message, so the harness ends the exchange: do not delegate to it again before the member's next message. Tell the member plainly what it objects to and what you decided, and let them decide.`;
   const blocking = items.filter(i => i.required);
-  return `\n\n[Harness] The ${role} subagent objected to your brief:\n${list}\nCheck each at the place its evidence names, then record your decision with resolve_objection (accepted with what you changed, or rejected with what you checked and why).${blocking.length ? ` Until you do, file changes are refused: ${blocking.map(i => i.id).join(', ')} say${blocking.length === 1 ? 's' : ''} the brief rests on a wrong premise or conflicts with the request.` : ''} A rejected objection goes back to the helper; a second objection from it for this message goes to the member.`;
+  return `\n\n[Harness] The ${callName(role)} subagent objected to your brief:\n${list}\nCheck each at the place its evidence names, then record your decision with resolve_objection (accepted with what you changed, or rejected with what you checked and why).${blocking.length ? ` Until you do, file changes are refused: ${blocking.map(i => i.id).join(', ')} say${blocking.length === 1 ? 's' : ''} the brief rests on a wrong premise or conflicts with the request.` : ''} A rejected objection goes back to the helper; a second objection from it for this message goes to the member.`;
 }
 
-// Verify's verdicts, counted for the receipt; its failed claims go into the
-// ledger (required under a required verify, noted otherwise). Under a
-// required verify the failed claims are the run's to settle; once the agent
-// has been sent back with them, only the harness's own re-check replaces
-// them, and a claim it no longer fails is cleared.
-export function recordVerdicts(managed, reply, harness, details) {
-  const run = managed.run, found = verifyVerdicts(reply);
-  details.verdicts = found ? Object.fromEntries(['pass', 'fail', 'unverifiable'].map(s => [s, found.filter(v => v.status === s).length])) : null;
-  if (run && found && (harness || !run.claimsAsked)) {
-    run.verifyFails = found.filter(v => v.status === 'fail');
-    const failed = new Set(run.verifyFails.map(v => v.claim)), required = run.policy.verify === 'require';
-    for (const item of ledgerOf(run)) if (item.source === 'verify' && ['open', 'rejected', 'noted'].includes(item.status) && !failed.has(item.detail)) setStatus(item, 'cleared');
-    const known = new Set(ledgerOf(run).filter(i => i.source === 'verify' && i.status !== 'cleared').map(i => i.detail));
-    const added = addItems(managed, 'verify', 'verify', run.verifyFails.filter(v => !known.has(v.claim)).map(v => ({ kind: 'fail', detail: v.claim, evidence: v.evidence })), { required });
-    if (!required) for (const item of added) setStatus(item, 'noted');
-  }
-  return found ? ' · ' + Object.entries(details.verdicts).filter(([, n]) => n).map(([s, n]) => `${n} ${s}`).join(', ') : '';
-}

package/packages/piagent-core/managed/role-names.mjs

@@ -0,0 +1,6 @@
+// A helper's working name (what the main agent calls it) and its Harness role
+// (Studio's grant). No imports: ledger.mjs and copies.mjs need these names
+// without loading helper-roles.mjs, which imports workflow.mjs (a cycle).
+export const ROLE_NAMES = Object.freeze({ explore: 'scout', scout: 'research', advisor: 'advisor', general: 'general', review: 'review' });
+export const HELPER_ROLES = Object.freeze(Object.values(ROLE_NAMES));
+export const callName = role => Object.keys(ROLE_NAMES).find(name => ROLE_NAMES[name] === role) ?? role;

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

@@ -14,18 +14,15 @@ import { nativeManagedModel, isVendor, piProvider, studioAPI, studioPath } from
 import { fetchOriginTool } from './repository-operation.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
 import { enableCompanyTurnRetry, wrapRoleStreams, conversationSession } from './request-stream.mjs'; import { StudioLink, closeRun } from './studio-link.mjs';
-import { trackToolFailures } from './tool-failures.mjs';
-import { fastServed, fastSetter, fastState, recordFast, restoreFast } from './fast-mode.mjs';
-import { runHelper } from './helper-run.mjs';
-import { askTool } from './member-questions.mjs';
-import { setTimeout as sleep } from 'node:timers/promises';
+import { trackToolFailures } from './tool-failures.mjs'; import { fastServed, fastSetter, fastState, recordFast, restoreFast } from './fast-mode.mjs';
+import { runHelper } from './helper-run.mjs'; import { sweepGeneral } from './general-clone.mjs'; import { askTool } from './member-questions.mjs';
 import { stageCompaction, compactEarly, backOffFailedCompaction, trackCompaction, boundRequestImages } from './compaction.mjs';
 import { readPatchDigest, readPatchSnapshot, readChangedFiles, readHead, readRepositoryHeads } from './patch-snapshot.mjs';
-import { memberTurn } from './continuation.mjs';
+import { memberTurn } from './continuation.mjs'; import { setTimeout as sleep } from 'node:timers/promises';
 import { workflowPolicy, repositoryChecks, sessionPlanTool, currentPlan, workflowPrompt, RunProcess, completionGate, pendingBaseline, pendingPaths, pendingHead, processEditTools } from './workflow.mjs';
 import { workflowContextTool, workflowContextExtension } from './workflow-context.mjs';
 import { beforeDelegate, resolveTool } from './objections.mjs'; import { fanOut, withDroppedNote } from './copies.mjs'; import { withMemberMcp } from './member-mcp.mjs';
-import { HELPER_CALLS, HELPER_ROLES, helperRoles, helperPrompt, webPrompt, delegateDescription, mainWebLookups, limitedWebTools } from './helper-roles.mjs'; import { delegateParameters, delegateArgs, SPEC_PROMPT } from './helper-settlement.mjs';
+import { HELPER_CALLS, HELPER_ROLES, ROLE_NAMES, callName, helperRoles, helperPrompt, webPrompt, delegateDescription, mainWebLookups, limitedWebTools } from './helper-roles.mjs'; import { delegateParameters, delegateArgs, SPEC_PROMPT } from './helper-settlement.mjs';
 import { loadAgentResources } from './agent-skills.mjs';
 import { loadPiagentThemes } from '../runtime/terminal/terminal-style.mjs';
 import { alwaysBypass, restorePermission, recordBypass, permissionSetter } from './permission.mjs';
@@ -463,19 +460,21 @@ export class ManagedSession {
       content: 'Review is stale: code changed after review. Ask for another review only after fixing blocking findings; under a required review the harness reviews the final patch.', details: this.review }, { triggerTurn: false });
   }
   // `harness`: the completion gate asks, not the main agent (its brief, its turn).
-  async delegate({ role, task, title, since, ...more }, signal, { harness = false } = {}) {
+  async delegate({ role: name, task, title, since, ...more }, signal, { harness = false } = {}) {
+    const role = ROLE_NAMES[name]; // the helper's working name -> its Harness role
     if (!this.grant || !HELPER_ROLES.includes(role) || typeof task !== 'string' || !task.trim() || task.length > 12000 || this.helpers.has(role)) throw Error('managed-helper-unavailable');
     const enabled = helperRoles(this.manifest);
-    if (!enabled.includes(role)) throw Error(`managed-helper-not-configured: the company Harness has no ${role} subagent${enabled.length ? `; use ${enabled.join(', ')}` : ''}.`);
+    if (!enabled.includes(role)) throw Error(`managed-helper-not-configured: the company Harness has no ${name} subagent${enabled.length ? `; use ${enabled.map(callName).join(', ')}` : ''}.`);
+    if (role === 'general' && (more.copies || more.split)) throw Error('managed-general-single: the general helper runs one at a time, each in its own clone; call it again for the next piece of work after merging the first.');
+    if (role === 'general') this.orphans = sweepGeneral(this);
     // Studio lets each helper role run HELPER_CALLS times per run (one user
     // message), each helper the member asked for counted (copies.mjs). Say so at once.
     const asked = fanOut(this.session?.sessionManager, role, more, harness), fan = asked?.dropped ? null : asked;
-    if ((this.helperCalls.get(role) ?? 0) + (fan?.n ?? 1) > HELPER_CALLS) throw Error(`managed-helper-limit: the ${role} subagent already ran ${HELPER_CALLS} times for this user message. Go on with what it returned, or use it again after the next user message.`);
+    if ((this.helperCalls.get(role) ?? 0) + (fan?.n ?? 1) > HELPER_CALLS) throw Error(`managed-helper-limit: the ${name} subagent already ran ${HELPER_CALLS} times for this user message. Go on with what it returned, or use it again after the next user message.`);
     beforeDelegate(this.run, role, harness, { since, review: this.review, changed: (this.ownPaths?.size ?? 0) > 0, asked: !!fan });
     const job = this.runHelper(role, task, signal, harness, title, role === 'review' && typeof since === 'string' && since.trim() ? since.trim() : null, fan); this.helpers.set(role, job); this.publishHelpers();
-    // While a helper works (a verify running a long suite) the main agent is
-    // quiet: a beat each minute tells the dashboard's watchdog, which stops a
-    // turn after 15 minutes without an event, that the turn is working.
+    // While a helper works (a general helper running a long suite) the main agent is quiet: a beat each
+    // minute tells the dashboard's watchdog (it stops a turn after 15 silent minutes) that the turn is working.
     const beat = setInterval(() => this.notify({ type: 'managed_helper_progress', role }), this.helperBeatMs ?? HELPER_BEAT_MS); beat.unref?.();
     try { return withDroppedNote(await job, role, asked); } finally { clearInterval(beat); this.helpers.delete(role); this.publishHelpers(); }
   }
@@ -495,6 +494,7 @@ export class ManagedSession {
     if (this.disposed) return;
     this.disposed = true;
     await this.session?.abort(); await Promise.allSettled([...this.helpers.values()]);
+    for (const root of this.liveClones ?? []) fs.rmSync(root, { recursive: true, force: true });
     this.session?.dispose(); await this.boundary?.dispose(); await this.broker.dispose();
   }
 }