@piagent/platform 1.45.0 → 1.46.1

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

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

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

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

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

@@ -0,0 +1,187 @@
+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
+// 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
+// items and decisions are one session entry when the run ends.
+export const LEDGER_ENTRY = 'agent-watch-objections';
+// A brief objection that blocks file changes until it is resolved: the brief
+// rests on a premise the code contradicts, or on a reading the member's words
+// contradict, and the helper pointed at a place that exists.
+const PREMISE = new Set(['wrong_premise', 'conflicts_with_request']);
+const DECISIONS = ['accepted', 'rejected'];
+// After this many refused answers a model that cannot resolve an item goes on;
+// the run reports the item as left without a decision.
+export const LEDGER_REFUSALS = 3;
+const MAX_ITEMS = 60, READ_LIMIT = 5 * 1024 * 1024;
+
+// "file:line" in a piece of evidence; null when it names none.
+export function evidenceRef(text) {
+  const m = String(text ?? '').match(/(?:^|[\s(`'"])((?:[\w@.-]+\/)*[\w@.-]*[\w-]\.[A-Za-z0-9]+):(\d+)\b/);
+  return m ? { file: m[1], line: Number(m[2]) } : null;
+}
+// Whether the place exists in the project: 'ok', 'missing' (no such file, or
+// the file is shorter), or null when there is nothing to check or the file is
+// outside the project or too large to read.
+export function checkRef(cwd, ref) {
+  if (!cwd || !ref?.file || path.isAbsolute(ref.file) || ref.file.split(/[\\/]/).includes('..')) return null;
+  let real;
+  try { real = fs.realpathSync(path.join(cwd, ref.file)); } catch { return 'missing'; }
+  const root = fs.realpathSync(cwd);
+  if (real !== root && !real.startsWith(root + path.sep)) return null;
+  try {
+    const stat = fs.statSync(real);
+    if (!stat.isFile()) return 'missing';
+    if (!ref.line) return 'ok';
+    if (stat.size > READ_LIMIT) return null;
+    return fs.readFileSync(real, 'utf8').split('\n').length >= ref.line ? 'ok' : 'missing';
+  } catch { return null; }
+}
+
+const clip = (value, n) => typeof value === 'string' ? value.trim().slice(0, n) : '';
+export const ledgerOf = run => run?.ledger ?? [];
+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).
+export function addItems(managed, source, role, list, { required } = {}) {
+  const run = managed.run;
+  if (!run || !list?.length) return [];
+  const added = [];
+  for (const raw of list) {
+    if (run.ledger.length >= MAX_ITEMS) break;
+    const evidence = clip(raw.evidence, 500), ref = raw.file ? { file: raw.file, line: raw.line ?? null } : evidenceRef(evidence), place = checkRef(managed.cwd, ref);
+    const must = source === 'brief' ? PREMISE.has(raw.kind) && !!evidence && place !== 'missing' : source === 'review' ? raw.kind === 'blocking' : !!required;
+    const item = { id: `o${run.ledger.length + 1}`, source, role, kind: raw.kind, detail: clip(raw.detail, 500), evidence, ...(ref ? { ref } : {}), ...(place ? { place } : {}), required: must, status: 'open' };
+    run.ledger.push(item); added.push(item);
+  }
+  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 setStatus = (item, status, extra = {}) => Object.assign(item, { status, ...extra });
+export function saveLedger(managed) {
+  const items = ledgerOf(managed.run);
+  if (items.length) try { managed.session.sessionManager.appendCustomEntry(LEDGER_ENTRY, { items, at: new Date().toISOString() }); } catch { /* the report still counts them */ }
+}
+
+// resolve_objection: the main agent's decision on one item, kept with what it
+// 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.',
+    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) => {
+      const item = ledgerOf(owner.run).find(i => i.id === args?.id);
+      if (!item) throw Error(`managed-objection-unknown: no objection ${String(args?.id).slice(0, 10)} in this message; the open ones are ${open(owner.run).map(i => i.id).join(', ') || 'none'}.`);
+      if (!['open', 'noted'].includes(item.status)) throw Error(`managed-objection-settled: ${item.id} is already ${item.status}.`);
+      if (!DECISIONS.includes(args.decision) || !clip(args.checked, 300)) throw Error('managed-objection-invalid: send decision accepted or rejected, and what you checked.');
+      if (args.decision === 'accepted' && !clip(args.change, 300)) throw Error('managed-objection-invalid: an accepted objection names what you changed (the brief, the plan or the code).');
+      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.` : '';
+      return { content: [{ type: 'text', text: `Recorded: ${item.id} ${args.decision}.${back}` }], details: { id: item.id, decision: args.decision } };
+    } };
+}
+
+// Before an edit or a command that may change files: an open premise
+// objection is resolved first. `answer` names the model answer the call came
+// from, so calls sent together count once.
+export function ledgerGuard(run, answer) {
+  const items = blockingItems(run);
+  if (!items.length) return;
+  run.ledgerRefusals ??= new Set();
+  if (!run.ledgerRefusals.has(answer) && run.ledgerRefusals.size >= LEDGER_REFUSALS) { run.ledgerSkipped = true; return; }
+  run.ledgerRefusals.add(answer);
+  throw Error(`managed-objection-open: resolve ${items.map(i => i.id).join(', ')} with resolve_objection before changing files.\n${items.map(itemText).join('\n')}`);
+}
+
+// The receipt's counts (report version 3): objections to briefs, those the
+// main agent decided, the disagreements handed to the member.
+export function briefCounts(run) {
+  const briefs = ledgerOf(run).filter(i => i.source === 'brief');
+  return { objections: briefs.length, answered: briefs.filter(i => ['accepted', 'rejected', 'withdrawn'].includes(i.status)).length };
+}
+
+// A required rejection the helper has not judged yet; the harness asks it.
+export const toRejudge = run => ledgerOf(run).filter(i => i.source === 'brief' && i.required && i.status === 'rejected' && !i.rejudged);
+export function rejudgeBrief(item) {
+  return `You objected to the brief the main agent gave you:\n[${item.kind}] ${item.detail}${item.evidence ? `\nYour evidence: ${item.evidence}` : ''}\n\nThe main agent rejected the objection.\nWhat it checked: ${item.resolution.checked}\nIts reason: ${item.resolution.reason}\n\nJudge its reason against the code and the member's words. When the reason holds, end with an empty brief_issues list. When your objection still holds, repeat it in brief_issues with evidence; the member then decides.`;
+}
+
+// One step of the completion gate (true: the gate goes round again). A
+// rejected premise objection goes back to its helper, which withdraws it or
+// keeps it for the member; then the items the main agent never decided are
+// put to it once, with no new review.
+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'); }
+    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 });
+    return true;
+  }
+  const pending = undecided(run);
+  if (!pending.length || run.decideAsked) return false;
+  run.decideAsked = true;
+  await send(decideText(pending), { phase: 'answer', ids: pending.map(i => i.id), issues: pending.slice(0, 10).map(i => ({ kind: i.kind, detail: i.detail })) });
+  return true;
+}
+
+// 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 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.`;
+}
+// The final status line's words about the ledger.
+export function ledgerWords(run) {
+  const items = ledgerOf(run), count = s => items.filter(i => i.status === s).length, words = [];
+  if (!items.length && !run.minorFindings) return null;
+  for (const [status, label] of [['accepted', 'accepted'], ['rejected', 'rejected'], ['withdrawn', 'withdrawn by the helper'], ['cleared', 'cleared by a later check'], ['disputed', 'for the member'], ['open', 'left without a decision'], ['noted', 'noted']])
+    if (count(status)) words.push(`${count(status)} ${label}`);
+  if (run.minorFindings) words.push(`${run.minorFindings} minor finding(s) listed`);
+  return `objections: ${words.join(', ')}`;
+}
+
+// A review of this turn's patch replaces the findings of the one before it:
+// its blocking and major findings are the items, its minor ones only counted.
+// A finding it repeats keeps its item (and the main agent's decision); one it
+// no longer reports is cleared, or withdrawn when the agent had rejected it.
+const sameFinding = (item, f) => (item.ref?.file ?? null) === (f.file || null) && (item.ref?.line === f.line || item.detail === clip(f.issue, 500));
+export function recordFindings(managed, findings) {
+  const run = managed.run;
+  if (!run || !findings) return;
+  // A re-review after a fix read only the files changed since: an item about another file stands.
+  const focus = managed.reviewFocus?.files ? new Set(managed.reviewFocus.files) : null;
+  const kept = findings.filter(f => f.severity !== 'minor'), live = ledgerOf(run).filter(i => i.source === 'review' && ['open', 'rejected'].includes(i.status)
+    && (!focus || i.kind === 'blocking' || !i.ref?.file || focus.has(i.ref.file)));
+  for (const item of live) if (!kept.some(f => f.severity === item.kind && sameFinding(item, f))) setStatus(item, item.status === 'open' ? 'cleared' : 'withdrawn');
+  addItems(managed, 'review', 'review', kept.filter(f => !live.some(i => i.kind === f.severity && sameFinding(i, f))).map(f => ({ kind: f.severity, detail: f.issue, evidence: f.evidence, file: f.file || null, line: f.line })));
+  run.minorFindings = findings.length - kept.length;
+}
+// The files changed since the last review of this turn's patch, for a
+// re-review after a fix; null when that cannot be told.
+export async function reviewFocus(managed) {
+  const before = managed.reviewFiles, now = before ? await managed.changedFiles?.() : null;
+  if (!before || !now) return null;
+  const files = [...new Set([...before.keys(), ...now.keys()])].filter(name => before.get(name) !== now.get(name)).sort();
+  return files.length ? { files: files.slice(0, 200) } : null;
+}
+// The main agent's decisions on items of one source, for the helper that judges them again.
+export function decisionsText(run, source) {
+  const decided = ledgerOf(run).filter(i => i.source === source && i.resolution);
+  return decided.length ? `\n\nThe main agent's recorded decisions:\n${decided.map(i => `- ${i.detail}: ${i.resolution.decision}; checked: ${i.resolution.checked}${i.resolution.reason ? `; reason: ${i.resolution.reason}` : ''}${i.resolution.change ? `; changed: ${i.resolution.change}` : ''}`).join('\n')}` : '';
+}

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

@@ -1,10 +1,12 @@
 import { briefIssues, currentPlan, planText, verifyVerdicts } from './workflow.mjs';
+import { addItems, itemText, ledgerOf, setStatus } from './ledger.mjs';
+export { resolveTool } from './ledger.mjs';
 
 // A helper may object to the brief it was given, with evidence. It never
-// decides and never does other work instead: the main agent decides and has
-// to answer the objection (a corrected brief, another approach, or why the
-// objection does not hold). The same helper objecting a second time in a run
-// stops the exchange, and the member decides.
+// decides and never does other work instead: the main agent decides and
+// records its decision in the ledger (ledger.mjs): accepted with what it
+// changed, or rejected with what it checked and why. The same helper
+// objecting a second time in a run stops the exchange, and the member decides.
 
 // The member's own words for a helper: the current message and, while a
 // message only continues earlier work ("tiếp tục", a short follow-up), the
@@ -33,41 +35,61 @@ export function anchorText(manager, harness) {
 }
 
 // Before a helper starts: once a helper objected twice in a run the member
-// decides, so the main agent cannot send it another brief before then. A
-// new brief to a helper that objected answers that objection.
-export function beforeDelegate(run, role, harness) {
+// decides, so the main agent cannot send it another brief before then. An
+// open premise objection of the role is resolved with resolve_objection
+// first; a new brief answers any other objection of the role. A review the
+// main agent asks for itself: none under a required review (the 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.`);
-  for (const objection of run.objections) if (objection.role === role) objection.answered = true;
+  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')}`);
+  // 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.');
+    if (run.mainReviews > 0 && !(review?.stale && review.blocking > 0)) throw Error('managed-review-once: this change was reviewed already. Fix its blocking findings and ask again only then; fix major findings or reject them with resolve_objection; minor findings need nothing.');
+  }
+  if (role === 'review' && !since) run.mainReviews = (run.mainReviews ?? 0) + 1;
+  for (const item of mine) setStatus(item, 'accepted', { resolution: { decision: 'accepted', checked: 'sent the role a new brief', change: 'a new brief' } });
 }
 
-const issueText = (issue, i) => `${i + 1}. [${issue.kind}] ${issue.detail}${issue.evidence ? ` (evidence: ${issue.evidence})` : ''}`;
-// After a helper answered: an objection to the main agent's brief is
-// recorded, shown to the member and handed to the main agent with the answer.
-// Returns the note the main agent reads under the helper's answer ('' when
-// there is none). The harness's own briefs (its review, its re-check) are
-// fixed text: an objection to one only restates the member's request, so
-// it is not relayed.
+// After a helper answered: an objection to the main agent's brief goes into
+// the ledger, is shown to the member and handed to the main agent with the
+// answer. Returns the note the main agent reads under the helper's answer
+// ('' when there is none). The harness's own briefs (its review, its
+// re-check) are fixed text: an objection to one only restates the member's
+// request, so it is not relayed.
 export async function relayObjection(managed, role, reply, harness) {
   const run = managed.run, issues = harness ? null : briefIssues(reply);
   if (!run || !issues?.length) return '';
-  const second = run.objections.some(o => o.role === role), list = issues.map(issueText).join('\n');
-  run.objections.push({ role, issues, answered: false, disputed: second });
-  if (second) run.disputes.push({ source: role, brief: true });
+  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}`,
-    details: { phase: second ? 'dispute' : 'objection', role, by: 'main', issues: issues.map(({ kind, detail }) => ({ kind, detail })) } }, { triggerTurn: false });
-  return second ? `\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.`
-    : `\n\n[Harness] The ${role} subagent objected to your brief (see brief_issues above). You decide, but answer the objection before you act on this answer: send it a corrected brief, change your approach, or tell the member why the objection does not hold. A second objection from it for this message goes to the member.`;
+    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.`;
+  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.`;
 }
 
-// Verify's verdicts, counted for the receipt. 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.
-export function recordVerdicts(run, reply, harness, details) {
-  const found = verifyVerdicts(reply);
+// 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');
+  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/patch-snapshot.mjs

@@ -176,6 +176,15 @@ export function reviewParts(snapshot, size = REVIEW_PART_BYTES) {
   return { parts: parts.length ? parts : [{ files: [], text: `Patch snapshot ${snapshot.digest}: every changed file is too large to review.${skipped}` }], omitted };
 }
 
+// A re-review after a fix (focus: the files changed since the last review)
+// reads only the parts that hold one of them: the other parts were reviewed
+// and have not changed. Without such a part, or in one part, all of it.
+export function focusParts(review, focus) {
+  if (!focus?.files?.length || review.parts.length < 2) return review;
+  const files = new Set(focus.files), kept = review.parts.filter(part => part.files?.some(file => files.has(file)));
+  return kept.length ? { ...review, parts: kept } : review;
+}
+
 // One answer from the review of every part: each part's summary, then the
 // findings of all parts (most severe first) and their objections to the brief
 // in one JSON block. `parsed`: every part gave its JSON.