total-recall-brain 3.44.0 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/control.mjs

@@ -0,0 +1,145 @@
+/** Job commands and events. The inbox is append-only; ack events are its cursor. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { configDir } from './paths.mjs';
+import { resolveJob } from './jobs.mjs';
+
+const execute = promisify(execFile);
+export function jobPaths(job) {
+  const id = typeof job === 'string' ? job : job?.id || job?.job;
+  if (typeof id !== 'string' || !/^[a-z0-9-]+$/.test(id)) throw new Error('Invalid job ID.');
+  const base = path.join(configDir(), 'jobs', id);
+  return { id, inbox: `${base}.inbox.jsonl`, events: `${base}.events.jsonl` };
+}
+
+function readLines(file) {
+  let data;
+  try { data = fs.readFileSync(file, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  // An append from another process can still be incomplete.
+  return data.split('\n').slice(0, -1).filter(Boolean).map(line => JSON.parse(line));
+}
+
+export function appendEvent(job, event) {
+  const { events } = jobPaths(job);
+  fs.mkdirSync(path.dirname(events), { recursive: true, mode: 0o700 });
+  const entry = { ...event, t: new Date().toISOString() };
+  fs.appendFileSync(events, JSON.stringify(entry) + '\n', { mode: 0o600 });
+  return entry;
+}
+
+/** Read all requests, including requests older than watch's --tail. */
+export function waitingRequests(job) {
+  const file = typeof job === 'string' && job.endsWith('.events.jsonl') ? job : jobPaths(job).events;
+  const waiting = new Map();
+  for (const event of readLines(file)) {
+    if (['question', 'approval'].includes(event.kind) && event.requestId) waiting.set(event.requestId, event);
+    if (event.kind === 'ack' && event.requestId && event.ok !== false) waiting.delete(event.requestId);
+  }
+  return [...waiting.values()];
+}
+
+function normalizeCommand(command) {
+  if (!command || typeof command !== 'object' || Array.isArray(command)) throw new Error('A job command is required.');
+  const type = command.type || command.command || command.kind;
+  if (!['reply', 'approve', 'interrupt', 'goal', 'fork'].includes(type)) throw new Error('Unsupported job command.');
+  if (['reply', 'goal'].includes(type) && (typeof command.text !== 'string' || !command.text.trim())) throw new Error(`${type} requires text.`);
+  if (type === 'approve' && (typeof command.requestId !== 'string' || !command.requestId || !['allow', 'deny'].includes(command.value))) {
+    throw new Error('approve requires a request ID and allow or deny.');
+  }
+  if (command.requestId !== undefined && (typeof command.requestId !== 'string' || !command.requestId)) throw new Error('Invalid request ID.');
+  return { ...command, type, command: type, id: command.id || randomUUID(), t: new Date().toISOString() };
+}
+
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+/** Resolve prefixes through the same owner as cancel. Remote delivery never writes a local inbox. */
+export async function appendCommand(target, command, { local = false, execFileFn = execute } = {}) {
+  const job = resolveJob(typeof target === 'string' ? target : target?.id || target?.job);
+  if (job.result) throw new Error(`Job ${job.id} has finished.`);
+  const entry = normalizeCommand(command);
+  const node = job.record?.node;
+  if (!local && node && node !== 'local') {
+    if (typeof node !== 'string' || node.startsWith('-') || /[\0\r\n]/.test(node)) throw new Error('Invalid job node.');
+    const args = [entry.type, job.record.remoteJob || job.id];
+    if (entry.type === 'approve') args.push(entry.requestId, entry.value);
+    else if (!['interrupt', 'fork'].includes(entry.type)) args.push(entry.text);
+    if (entry.type === 'fork' && entry.atTurn) args.push('--at', entry.atTurn);
+    args.push('--local-delivery', '--json');
+    const remote = `total-recall meta-harness ${args.map(quote).join(' ')}`;
+    const result = await execFileFn(process.env.TOTAL_RECALL_BIN || 'total-recall', ['mesh', 'exec', node, remote],
+      { encoding: 'utf8', timeout: 60_000, maxBuffer: 1024 * 1024 });
+    if (result.exitCode && result.exitCode !== 0) throw new Error(result.stderr || 'Remote command failed.');
+    // mesh exec may wrap the remote result. Transport failures must not look like delivery.
+    let report;
+    try { report = JSON.parse(result.stdout); } catch { /* mesh can return plain command output */ }
+    if (report?.ok === false) throw new Error(report.error || 'Remote command failed.');
+    return { ok: true, job: job.id, node, remote: true, command: entry, ...(report ? { delivery: report } : {}) };
+  }
+  const waiting = waitingRequests(job.id);
+  const reserved = new Set(readLines(jobPaths(job.id).inbox).map(row => row.requestId).filter(Boolean));
+  const request = entry.requestId ? waiting.find(row => row.requestId === entry.requestId)
+    : entry.type === 'reply' ? waiting.find(row => row.kind === 'question' && !reserved.has(row.requestId)) : null;
+  if (entry.requestId && !request) throw new Error(`No waiting request matches ${entry.requestId}.`);
+  if (request && entry.type === 'approve' && request.kind !== 'approval') throw new Error('The request is not an approval.');
+  if (request && entry.type === 'reply' && request.kind !== 'question') throw new Error('The request is not a question.');
+  if (request) {
+    if (reserved.has(request.requestId)) throw new Error('The request already has an answer in the inbox.');
+    entry.requestId = request.requestId;
+    if (request.source === 'mcp') entry.recipient = 'mcp';
+    // A deferred question is answered by the session runner, which starts the next turn with it.
+    else if (request.source === 'deferred') entry.recipient = 'deferred';
+  }
+  const { inbox } = jobPaths(job.id);
+  fs.mkdirSync(path.dirname(inbox), { recursive: true, mode: 0o700 });
+  fs.appendFileSync(inbox, JSON.stringify(entry) + '\n', { mode: 0o600 });
+  return { ok: true, job: job.id, command: entry };
+}
+
+/**
+ * One consumer handles commands in file order. A false return leaves a command for
+ * another consumer. MCP answers have their own recipient so a worker cannot also
+ * send them to the driver. Await close() before releasing the driver.
+ */
+export function tailInbox(job, onCommand, { pollMs = 50, recipient = 'driver', onError = () => {} } = {}) {
+  const { inbox, events } = jobPaths(job);
+  fs.mkdirSync(path.dirname(inbox), { recursive: true, mode: 0o700 });
+  fs.closeSync(fs.openSync(inbox, 'a', 0o600));
+  let closed = false, running = null;
+  const seen = new Set();
+  const poll = () => {
+    if (closed || running) return running;
+    running = (async () => {
+      const acknowledged = new Set(readLines(events).filter(row => row.kind === 'ack' && row.commandId).map(row => row.commandId));
+      for (const command of readLines(inbox)) {
+        if (closed) break;
+        if (!command.id || seen.has(command.id) || acknowledged.has(command.id) || (command.recipient || 'driver') !== recipient) continue;
+        let result;
+        try { result = await onCommand(command); }
+        catch (error) {
+          // A failed command is reported once; do not repeat an agent side effect.
+          seen.add(command.id);
+          appendEvent(job, { kind: 'ack', command: command.type || command.command, commandId: command.id,
+            requestId: command.requestId, ok: false, text: error.message });
+          onError(error);
+          continue;
+        }
+        if (result === false || result?.handled === false) continue;
+        seen.add(command.id);
+        appendEvent(job, { kind: 'ack', command: command.type || command.command, commandId: command.id,
+          requestId: command.requestId, ok: true, text: `Handled ${command.type || command.command}`, ...(result?.via ? { via: result.via } : {}) });
+      }
+    })().catch(onError).finally(() => { running = null; });
+    return running;
+  };
+  const timer = setInterval(poll, pollMs);
+  poll();
+  const close = async () => { closed = true; clearInterval(timer); await running; };
+  // A function is convenient for existing watcher callers; properties support explicit lifecycle use.
+  close.close = close;
+  close.poll = poll;
+  return close;
+}

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/coordinator.mjs

@@ -16,6 +16,8 @@ import { isGitRepo, isDirty, headCommit, createWorktree, removeWorktree, commitA
 import { lastJsonWith } from './json-reply.mjs';
 import { runQualityGate } from './gate.mjs';
 import { forwardRemoteOperation } from './remote-operation.mjs';
+import { cancellationResult } from './worker.mjs';
+import { sessionOptions } from './session/run.mjs';
 
 const OPEN_THREADS = new Set();
 const MAX_BLUEPRINT = 20000;
@@ -101,9 +103,12 @@ async function runPipeline(task, poolInfo, options) {
   const branch = options.branch || `meta-harness/${thread.id}`;
   const run = async (stage, harness, prompt, { workdir = cwd, permissions, role = stage.role } = {}) => {
     stage.status = 'running';
-    const result = await dispatchWithReceipt({ agent: harness.id, node: 'local', cwd: workdir, contextCwd: cwd, contextTask: task, prompt, permissions: permissions || stage.permissions, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
-    stage.status = result.ok ? 'completed' : result.queued ? 'queued' : 'failed';
+    const result = await dispatchWithReceipt({ agent: harness.id, node: 'local', cwd: workdir, contextCwd: cwd, contextTask: task, prompt,
+      ...sessionOptions({ ...options, cwd }), goal: stage.role === 'Implementer' ? options.goal || task : prompt.slice(0, 4000),
+      permissions: permissions || stage.permissions, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role, complexityScore: complexity.score });
+    stage.status = result.cancelled ? 'cancelled' : result.ok ? 'completed' : result.queued ? 'queued' : 'failed';
     stage.output = result.response || result.error || null;
+    for (const key of ['goalCheck', 'structured', 'sessionId', 'progressFile', 'usage']) if (result[key] !== undefined) stage[key] = result[key];
     stage.failureKind = result.ok ? undefined : result.failureKind;
     if (result.queueId) stage.queueId = result.queueId;
     appendThreadTurn(thread.id, { role: role.toLowerCase(), agent: harness.id, content: stage.output || '' });
@@ -128,17 +133,14 @@ async function runPipeline(task, poolInfo, options) {
     const implementer = await run(stage('Implementer'), roles.implementer, `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit; the harness commits your changes.\nTask:\n${task}\n\nBlueprint:\n${blueprint}`, { workdir: implementerDir });
     if (!implementer.ok) { ok = false; return finish(); }
     commit = commitAll(implementerDir, `meta-harness: ${task.slice(0, 60)}\n\nImplementer: ${roles.implementer.id}`);
-    if (!commit) {
-      Object.assign(stage('Implementer'), { status: 'failed', failureKind: 'agent', output: 'The Implementer reported success but changed no files.' });
-      await recordRunReceipt({ harness: roles.implementer.id, role: 'Implementer', task, success: false, failureKind: 'no-change', error: 'The Implementer reported success but changed no files.' });
-      ok = false; return finish();
-    }
+    if (!commit) commit = baseCommit;
     stage('Implementer').commit = commit;
     updateThread(thread.id, { branch, worktreePath: null });
 
     if (options.gate) {
       linkDependencies(cwd, implementerDir);
       gate = await (options.gateFn || runQualityGate)(implementerDir, options.gateOptions);
+      if (cancellationResult()) { ok = false; return finish(); }
       if (!gate.passed) { ok = false; stage('Verifier').status = 'skipped'; stage('Verifier').output = `Quality gate did not pass: ${gate.summary}`; return finish(); }
     }
 
@@ -165,16 +167,24 @@ async function runPipeline(task, poolInfo, options) {
     return finish();
   } finally {
     removeWorktree(cwd, implementerDir);
-    if (implementerDir && (!commit || !ok)) deleteBranch(cwd, branch);
+    if (implementerDir && (!commit || (!ok && !cancellationResult()))) deleteBranch(cwd, branch);
   }
 
   function finish() {
+    const cancelled = cancellationResult();
+    if (cancelled) {
+      ok = false;
+      if (implementerDir) commit = commitAll(implementerDir, 'meta-harness: unfinished pipeline from a cancelled job') || commit;
+    }
     return (async () => {
       for (const item of stages) if (item.status === 'planned') item.status = 'skipped';
       OPEN_THREADS.delete(thread.id);
-      updateThread(thread.id, { status: ok ? 'completed' : 'failed', branch: ok && commit ? branch : null, commit, baseCommit });
-      const alert = await notifyAlert({ title: ok ? 'Meta Harness: pipeline passed' : 'Meta Harness: pipeline failed', message: `${task.slice(0, 80)}${commit ? ` (branch ${branch})` : ''}`, severity: ok ? 'info' : 'warning' });
-      return { ...base, ok, threadId: thread.id, branch: ok && commit ? branch : null, commit, baseCommit, gate, warnings, durationMs: Date.now() - started, alert };
+      updateThread(thread.id, { status: ok ? 'completed' : 'failed', branch: (ok || cancelled) && commit ? branch : null, commit, baseCommit });
+      const alert = cancelled ? null : await notifyAlert({ title: ok ? 'Metaharness: pipeline passed' : 'Metaharness: pipeline failed', message: `${task.slice(0, 80)}${commit ? ` (branch ${branch})` : ''}`, severity: ok ? 'info' : 'warning' });
+      const limited = stages.find(item => item.failureKind === 'limit');
+      return { ...base, ok, ...cancelled, ...(limited ? { failureKind: 'limit', error: limited.output } : {}), goalCheck: stage('Implementer')?.goalCheck, structured: stage('Implementer')?.structured,
+        sessionId: stage('Implementer')?.sessionId, progressFile: stage('Implementer')?.progressFile,
+        threadId: thread.id, branch: (ok || cancelled) && commit ? branch : null, commit, baseCommit, gate, warnings, durationMs: Date.now() - started, alert };
     })();
   }
 }
@@ -187,14 +197,15 @@ async function runCouncil(task, poolInfo, options) {
   if (!seats.length) throw new Error('No harness can take work right now');
   const cwd = options.cwd || process.cwd();
   const votes = await Promise.all(seats.map(async harness => {
-    const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd, contextTask: task, prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Council' });
-    return { harness, ok: result.ok === true, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }),
+    const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), prompt: `[ROLE: COUNCIL MEMBER]\nDo not change any file. Assess this proposal, with its trade-offs and risks:\n${task}\n\nEnd your reply with exactly one JSON object: {"vote":"APPROVE"|"REJECT","reason":"..."}`, permissions: READ, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Council' });
+    return { harness, ok: result.ok === true, failureKind: result.failureKind, ...(result.ok ? parseVote(result.response) : { vote: 'ABSTAIN', reason: null, error: result.error }),
       ...(result.queueId ? { queueId: result.queueId } : {}), feedback: result.response || null };
   }));
   const count = vote => votes.filter(item => item.vote === vote).length;
   const majority = votes.length / 2;
   const consensus = count('APPROVE') > majority ? 'approved' : count('REJECT') > majority ? 'rejected' : 'no-consensus';
-  return { ok: votes.some(item => item.ok), mode: 'council', task, executedLive: true, consensus, excluded: poolInfo.excluded, votes };
+  const limited = votes.some(item => item.failureKind === 'limit');
+  return { ok: !limited && votes.some(item => item.ok), ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'council', task, executedLive: true, consensus, excluded: poolInfo.excluded, votes };
 }
 
 async function runRace(task, poolInfo, options) {
@@ -212,12 +223,20 @@ async function runRace(task, poolInfo, options) {
     try {
       const started = Date.now();
       directory = createWorktree(cwd, { branch });
-      const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd: directory, contextCwd: cwd, contextTask: task, prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Race' });
-      const commit = result.ok ? commitAll(directory, `meta-harness race: ${task.slice(0, 60)}\n\nAgent: ${harness}`) : null;
-      if (commit && options.gate) linkDependencies(cwd, directory);
-      const gate = commit ? await (options.gateFn || runQualityGate)(directory, options.gateOptions) : null;
-      keep = Boolean(commit) && gate?.passed === true;
-      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, completedAt: Date.now(), durationMs: Date.now() - started, error: result.ok ? (commit ? (keep ? undefined : 'The quality gate failed') : 'No files changed') : result.error,
+      const result = await dispatchWithReceipt({ agent: harness, node: 'local', cwd: directory, contextCwd: cwd, contextTask: task, ...sessionOptions({ ...options, cwd }), goal: options.goal || task, prompt: `[ROLE: IMPLEMENTER]\nWork only in this checkout. Implement the task and its tests. Do not commit.\nTask:\n${task}`, permissions: WRITE, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Race' });
+      const commit = result.ok || result.cancelled ? commitAll(directory, `meta-harness race: ${task.slice(0, 60)}\n\nAgent: ${harness}`) : null;
+      if (result.cancelled) {
+        keep = Boolean(commit);
+        return { ...result, harness, branch: keep ? branch : null, wip: commit };
+      }
+      if (result.ok && options.gate) linkDependencies(cwd, directory);
+      const gate = result.ok ? await (options.gateFn || runQualityGate)(directory, options.gateOptions) : null;
+      if (cancellationResult()) {
+        keep = Boolean(commit);
+        return { ...cancellationResult(), harness, branch: keep ? branch : null, commit };
+      }
+      keep = result.ok === true && gate?.passed === true;
+      return { harness, branch: keep ? branch : null, commit: keep ? commit : null, ok: keep, gate, goalCheck: result.goalCheck, structured: result.structured, failureKind: result.failureKind, completedAt: Date.now(), durationMs: Date.now() - started, error: result.ok ? keep ? undefined : 'The quality gate failed' : result.error,
         ...(result.queueId ? { queueId: result.queueId } : {}) };
     } catch (error) {
       return { harness, branch: null, commit: null, ok: false, gate: null, durationMs: null, error: String(error.message) };
@@ -227,10 +246,12 @@ async function runRace(task, poolInfo, options) {
     }
   }));
   const finishers = entries.filter(entry => entry.ok).sort((a, b) => a.completedAt - b.completedAt);
-  return { ok: finishers.length > 0, mode: 'race', task, executedLive: true, gateApplied: true, verification: finishers.length ? 'passed' : 'failed', winner: finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
+  const limited = entries.some(item => item.failureKind === 'limit');
+  return { ok: !limited && finishers.length > 0, ...(limited ? { failureKind: 'limit' } : {}), ...cancellationResult(), mode: 'race', task, executedLive: true, gateApplied: true, verification: !limited && finishers.length ? 'passed' : 'failed', winner: limited ? null : finishers[0]?.harness || null, excluded: poolInfo.excluded, candidates: entries };
 }
 
 export async function coordinateTask(taskDescription, options = {}) {
+  if (cancellationResult()) return cancellationResult();
   const task = String(taskDescription || '').trim();
   if (!task) throw new Error('Task description is required for coordination');
   const remote = await forwardRemoteOperation('coordinate', task, options);

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/dispatch-request.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { sessionOptions } from './session/run.mjs';
 
 const DEFAULT_PERMISSIONS = Object.freeze({ read: true, write: false, send: false, destructive: false });
 export { DEFAULT_PERMISSIONS };
@@ -14,11 +15,12 @@ export function commandPermissions(value = DEFAULT_PERMISSIONS) {
 const PUBLIC_FIELDS = [
   'agent', 'cwd', 'prompt', 'permissions', 'node', 'allowUnknownAuth', 'timeoutMs',
   'model', 'tools', 'settingSources', 'allowedTools',
+  'goal', 'maxTurns', 'maxTokens', 'maxBudgetUsd', 'resultSchema', 'approvalPolicy', 'questionTimeoutMs', 'effort', 'fallbackModel', 'name',
 ];
 
 export function validateDispatchRequest(request) {
   if (!request || typeof request !== 'object' || Array.isArray(request)) throw new Error('Dispatch requires a JSON object');
-  if (Object.keys(request).some(key => !PUBLIC_FIELDS.includes(key))) throw new Error('Unsupported dispatch field; workspace context and containment are managed by Meta Harness');
+  if (Object.keys(request).some(key => !PUBLIC_FIELDS.includes(key))) throw new Error('Unsupported dispatch field; workspace context and containment are managed by Metaharness');
   if (typeof request.agent !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(request.agent) ||
       typeof request.cwd !== 'string' || !path.isAbsolute(request.cwd) || request.cwd.includes('\0') ||
       typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 65536) {
@@ -28,7 +30,7 @@ export function validateDispatchRequest(request) {
   if (request.allowUnknownAuth !== undefined && typeof request.allowUnknownAuth !== 'boolean') throw new Error('allowUnknownAuth must be a boolean');
   const timeoutMs = request.timeoutMs === undefined ? 300000 : request.timeoutMs;
   if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 540000) throw new Error('Foreground dispatch timeout must be 1..540000 ms');
-  return { ...request, permissions: commandPermissions(request.permissions), timeoutMs };
+  return { ...request, ...sessionOptions(request), permissions: commandPermissions(request.permissions), timeoutMs };
 }
 
 /** The installed destination starts from its own project context and decides containment itself. */

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/dispatch.mjs

@@ -1,17 +1,20 @@
 /** One path for every agent run: contain it if needed, dispatch it, classify the outcome, write its receipt. */
 import { executeOnNode } from './executor.mjs';
-import { classifyFailure, INCLUDED_BILLING, READ_ONLY_ADAPTERS } from './worker.mjs';
+import { classifyFailure, INCLUDED_BILLING, READ_ONLY_ADAPTERS, cancellationResult } from './worker.mjs';
 import { recordRunReceipt } from './learner.mjs';
-import { isGitRepo, createWorktree, removeWorktree } from './worktree.mjs';
+import { isGitRepo, createWorktree, removeWorktree, commitAll, deleteBranch } from './worktree.mjs';
+import { randomUUID } from 'node:crypto';
 import { includedAdmission, openRouterAdmission, readIncludedPolicy } from './included-usage.mjs';
 import { queueIncludedJob } from './usage-queue.mjs';
 
 export async function dispatchWithReceipt(request, { dispatchFn, node = request.node || 'local', role, complexityScore, escalatedFrom,
-  record = recordRunReceipt, replay, retryId, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
+  record = recordRunReceipt, replay, retryId, manageWrites = false, usagePolicy = readIncludedPolicy, admit = includedAdmission, admitOpenRouter = openRouterAdmission } = {}) {
   const started = Date.now();
+  if (cancellationResult()) return cancellationResult();
   // A harness that cannot be told not to write does read-only work in a checkout that is thrown away.
   const contain = node === 'local' && request.permissions?.write !== true && !READ_ONLY_ADAPTERS.includes(request.agent) && request.isolated !== true && isGitRepo(request.cwd);
-  let scratch = null, result, billingMode = null, launchPrevented = false;
+  const ownWrites = manageWrites && node === 'local' && request.permissions?.write === true && isGitRepo(request.cwd);
+  let scratch = null, branch = null, result, billingMode = null, launchPrevented = false;
   try {
     let effective = request;
     const policy = await usagePolicy();
@@ -24,19 +27,32 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
         launchPrevented = true;
       } else effective = { ...request, [INCLUDED_BILLING]: { key: admission.key, claudePlan: admission.claudePlan, openRouter: admission.openRouter } };
     }
+    result = cancellationResult() || result;
     if (!result) {
-      if (contain) {
-        scratch = createWorktree(request.cwd, { prefix: 'meta-harness-readonly-' });
-        effective = { ...effective, cwd: scratch, contextCwd: request.contextCwd || request.cwd, isolated: true };
+      if (contain || ownWrites) {
+        branch = ownWrites ? `meta-harness/dispatch-${randomUUID()}` : null;
+        scratch = createWorktree(request.cwd, { ...(branch ? { branch } : {}), prefix: ownWrites ? 'meta-harness-dispatch-' : 'meta-harness-readonly-' });
+        effective = { ...effective, ...(branch ? { branch } : {}), cwd: scratch, contextCwd: request.contextCwd || request.cwd, isolated: true };
       }
       result = dispatchFn ? await dispatchFn(effective) : await executeOnNode(node, { ...effective, operation: 'dispatch' });
+      if (cancellationResult()) result = { ...result, ...cancellationResult() };
       if (contain) result = { ...result, readOnly: 'disposable-checkout' };
     }
   } catch (error) {
     const message = String(error?.message || error);
     result = { ok: false, error: message, agent: request.agent, ...(error?.code === 'NOT_READY' ? { failureKind: 'not-ready' } : classifyFailure(message)) };
   } finally {
-    if (scratch) removeWorktree(request.cwd, scratch);
+    if (scratch) {
+      try {
+        if (branch) {
+          const commit = commitAll(scratch, result?.cancelled ? 'meta-harness: unfinished cancelled dispatch' : 'meta-harness: dispatch changes');
+          if (commit) result = { ...result, branch, ...(result?.ok ? { commit } : { wip: commit }) };
+          else if (result?.sessionId) result = { ...result, branch };
+          else deleteBranch(request.cwd, branch);
+        }
+      } finally { removeWorktree(request.cwd, scratch); }
+      if (branch && !result?.branch) deleteBranch(request.cwd, branch);
+    }
   }
   const durationMs = Date.now() - started;
   if (result.execution?.receiptOwner === 'destination' && result.receiptId) return { ...result, durationMs };
@@ -52,7 +68,15 @@ export async function dispatchWithReceipt(request, { dispatchFn, node = request.
       }
     }
   }
-  if (launchPrevented) return { ...result, launchPrevented, durationMs };
+  if (launchPrevented) {
+    // A launch refused for quota is a quota wall too (A-124): record it, so routing sees the harness as
+    // exhausted until its reset and picks another included harness instead of choosing it again.
+    if (result.failureKind === 'quota') {
+      try { await record({ harness: request.agent, role, task: String(request.contextTask || request.prompt || '').slice(0, 200), success: false,
+        failureKind: 'quota', error: result.error, resetsAt: result.resetsAt || null }); } catch { /* bookkeeping must not hide the refusal */ }
+    }
+    return { ...result, launchPrevented, durationMs };
+  }
   // A finished run keeps its result: the worktree and any cost are real even when bookkeeping fails.
   let receipt, receiptError;
   try {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/documentation.mjs

@@ -3,7 +3,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
-import { loadCustomAdapters } from './worker.mjs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { agentEnvironment, loadCustomAdapters } from './worker.mjs';
+
+const exec = promisify(execFile);
 
 export const DOC_SOURCES = [
   { id: 'claude', index: 'https://code.claude.com/docs/llms.txt', prefix: 'https://code.claude.com/docs/', catalog:true },
@@ -69,7 +73,7 @@ async function download(url, fetchImpl, declaredOrigin) {
   if (declaredOrigin) allowed.add(declaredOrigin);
   for(let redirects=0;redirects<5;redirects++) {
     if(target.protocol!=='https:' || target.username || target.password || !allowed.has(target.hostname)) throw new Error(`Unapproved official documentation origin: ${target.hostname}`);
-    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-Meta-Harness-Docs','Accept':'*/*'}});
+    const response=await fetchImpl(target,{redirect:'manual',signal:AbortSignal.timeout(20000),headers:{'User-Agent':'Total-Recall-Metaharness-Docs','Accept':'*/*'}});
     if(response.status>=300 && response.status<400){target=new URL(response.headers.get('location'),target);continue;}
     // Some entries advertise Markdown exports which no longer exist while the
     // same official HTML document remains available. Fetch that representation.
@@ -91,7 +95,27 @@ function links(text,base,prefix) {
   return [...new Set(values.map(value=>{try{const url=new URL(value);url.hash='';url.search='';url.pathname=url.pathname.replace(/\/{2,}/g,'/').replace(/\/$/,'') || '/';return url.href;}catch{return '';}}))]
     .filter(url=>url.startsWith(prefix) && !/%3[CE]|[<>"'`\s]/i.test(url) && !/\.(png|jpg|jpeg|svg|gif|css|js|woff2?|ico|pdf|json|ya?ml|xml|zip|gz|tgz|lock)$/i.test(url));
 }
-export async function refreshDocumentation({ directory = documentationDirectory(), agent, fetchImpl = fetch, now = () => new Date(), maxPages = 1500 } = {}) {
+async function gitDocumentationPaths(source) {
+  const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'meta-harness-doc-tree-'));
+  const options = {
+    cwd: checkout, timeout: 30000, maxBuffer: 4 * 1024 * 1024,
+    env: { ...agentEnvironment(), GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: os.devNull },
+  };
+  try {
+    await exec('git', ['-c', 'http.followRedirects=false', 'clone', '--quiet', '--filter=blob:none',
+      '--depth=1', '--single-branch', '--branch', source.branch, '--no-checkout',
+      '--', `https://github.com/${source.repo}.git`, checkout], options);
+    const { stdout } = await exec('git', ['ls-tree', '-r', '-z', 'HEAD', '--', ...source.directories], options);
+    return stdout.split('\0').flatMap(entry => {
+      const match = /^100(?:644|755) blob [a-f0-9]+\t([\s\S]+)$/.exec(entry);
+      return match ? [match[1]] : [];
+    });
+  } catch {
+    throw new Error(`Could not read the official documentation tree through Git for ${source.repo}`);
+  } finally { fs.rmSync(checkout, { recursive: true, force: true }); }
+}
+
+export async function refreshDocumentation({ directory = documentationDirectory(), agent, fetchImpl = fetch, now = () => new Date(), maxPages = 1500, readGitPaths = gitDocumentationPaths } = {}) {
   const sources=sourcesFor(agent);
   if(!sources.length)throw new Error('Unknown documentation adapter');
   const reports=[];
@@ -99,11 +123,27 @@ export async function refreshDocumentation({ directory = documentationDirectory(
     const previous=metadata(directory,source.id), pages=[], queue=[source.index], seen=new Set(), queued=new Set(queue), errors=[], discovered=new Set(), skipped=[];
     // `found` marks a link taken from HTML navigation. The vendor's catalog, the index and the repository tree are authoritative; a link found by scraping is not.
     const enqueue=(url,found=false)=>{if(!queued.has(url)){queued.add(url);queue.push(url);if(found)discovered.add(url);}};
+    let treeSource;
     try {
       if(source.repo) {
-        const tree=JSON.parse(await download(`https://api.github.com/repos/${source.repo}/git/trees/${source.branch}?recursive=1`,fetchImpl));
-        if(tree.truncated)throw new Error('Official repository documentation tree is truncated');
-        for(const entry of tree.tree || [])if(entry.type==='blob' && /\.(md|mdx)$/i.test(entry.path) && source.directories.some(dir=>entry.path.startsWith(dir)))enqueue(`https://raw.githubusercontent.com/${source.repo}/${source.branch}/${entry.path}`);
+        let paths;
+        try {
+          const tree = JSON.parse(await download(`https://api.github.com/repos/${source.repo}/git/trees/${source.branch}?recursive=1`, fetchImpl));
+          if (tree.truncated) throw new Error('Official repository documentation tree is truncated');
+          if (!Array.isArray(tree.tree)) throw new Error('Invalid official repository documentation tree');
+          paths = tree.tree.filter(entry => entry.type === 'blob').map(entry => entry.path);
+          treeSource = 'github-rest';
+        } catch (error) {
+          if (!/^Documentation HTTP (403|429):|^Official repository documentation tree is truncated$/.test(error.message)) throw error;
+          paths = await readGitPaths(source);
+          treeSource = 'github-git';
+        }
+        for (const file of paths) {
+          if (!/\.(md|mdx)$/i.test(file) || !source.directories.some(dir => file.startsWith(dir))) continue;
+          const encoded = file.split('/').map(encodeURIComponent).join('/');
+          enqueue(`https://raw.githubusercontent.com/${source.repo}/${source.branch}/${encoded}`);
+        }
+        if (queue.length === 1) throw new Error('Official repository documentation tree contains no additional pages');
       }
       // Bounded batches; follow the official index/navigation to cover agent features.
       while(queue.length) {
@@ -138,7 +178,7 @@ export async function refreshDocumentation({ directory = documentationDirectory(
         reports.push({id:source.id,ok:false,error,pages:preserved.pages?.length || 0,downloadedPages:pages.length,failedCount:errors.length,failures:errors,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});continue;
       }
       atomic(path.join(directory,source.id,'index.json'),JSON.stringify({id:source.id,complete:true,checkedAt,lastAttempt:checkedAt,pages,...(skipped.length?{skipped}:{})},null,2));
-      reports.push({id:source.id,ok:true,pages:pages.length,...(skipped.length?{skippedCount:skipped.length,skipped}:{})});
+      reports.push({id:source.id,ok:true,pages:pages.length,...(treeSource?{treeSource}:{}),...(skipped.length?{skippedCount:skipped.length,skipped}:{})});
     } catch(error) {
       atomic(path.join(directory,source.id,'index.json'),JSON.stringify({...previous,id:source.id,lastAttempt:now().toISOString(),error:error.message},null,2));
       reports.push({id:source.id,ok:false,error:error.message,pages:previous?.pages?.length || 0});
@@ -156,11 +196,15 @@ export async function ensureDocumentation(options={}) {
 
 export async function maintainDocumentation(options={}) {
   const status=documentationStatus(options);
-  const next=status.agents.filter(row=>!row.fresh).sort((a,b)=>String(a.lastAttempt || '').localeCompare(String(b.lastAttempt || '')))[0];
-  if(!next)return {...status,scope:'all-agent-documentation-current'};
-  const refreshed=await refreshDocumentation({...options,agent:next.id});
+  const pending=status.agents.filter(row=>!row.fresh).sort((a,b)=>String(a.lastAttempt || '').localeCompare(String(b.lastAttempt || '')));
+  const reports=[];
+  // Missing documentation for one harness must not prevent attempts for the others.
+  for(const row of pending) {
+    try { reports.push(...(await refreshDocumentation({...options,agent:row.id})).agents); }
+    catch(error) { reports.push({id:row.id,ok:false,error:error.message}); }
+  }
   const current=documentationStatus(options);
-  return {...refreshed,scope:'one-stale-agent-refreshed',coverage_complete:current.ok,pending:current.agents.filter(row=>!row.fresh).map(row=>row.id)};
+  return {...current,ok:current.ok && reports.every(row=>row.ok),scope:'all-agent-documentation',refresh:reports,coverage_complete:current.ok,pending:current.agents.filter(row=>!row.fresh).map(row=>row.id)};
 }
 
 export function readDocumentation({agent,url,directory=documentationDirectory()}) {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/executor.mjs

@@ -34,15 +34,35 @@ export async function listTargets() {
 }
 
 export function workerProgram(request) {
-  const source = fs.readFileSync(new URL('./worker.mjs', import.meta.url), 'utf8');
-  return source + '\nrunWorker(' + JSON.stringify(request) + ').then(result=>console.log(JSON.stringify(result))).catch(error=>{console.error(String(error?.message||"Selected agent worker failed"));process.exitCode=1;});\n';
+  // Materialize a portable module graph. The stdin launcher imports only Node
+  // built-ins. Relative imports resolve inside this owned bundle on the node.
+  const names = ['worker.mjs', 'control.mjs', 'jobs.mjs', 'paths.mjs', 'mcp-server.mjs',
+    ...fs.readdirSync(new URL('./session/', import.meta.url)).filter(name => name.endsWith('.mjs')).map(name => `session/${name}`)];
+  const files = Object.fromEntries(names.map(name => [name, fs.readFileSync(new URL(name, import.meta.url), 'utf8')]));
+  return `import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'metaharness-worker-'));
+try {
+  for (const [name, source] of Object.entries(${JSON.stringify(files)})) {
+    const file = path.join(directory, name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, source, { mode: 0o600 });
+  }
+  const { runWorker } = await import(pathToFileURL(path.join(directory, 'worker.mjs')).href);
+  console.log(JSON.stringify(await runWorker(${JSON.stringify(request)})));
+} catch (error) { console.error(String(error?.message || 'Selected agent worker failed')); process.exitCode = 1; }
+finally { fs.rmSync(directory, { recursive: true, force: true }); }
+`;
+
 }
 
 function destinationDispatchResult(result, node, request) {
   let payload;
   try { payload = JSON.parse(result.output); } catch { /* No structured result from the installed owner. */ }
   if (!payload || typeof payload.ok !== 'boolean' || (payload.ok && !result.ok)) {
-    throw notReady(`Installed Meta Harness on ${node} returned no valid dispatch outcome (exit ${result.exitCode ?? 'unknown'})`);
+    throw notReady(`Installed Metaharness on ${node} returned no valid dispatch outcome (exit ${result.exitCode ?? 'unknown'})`);
   }
   return { ...payload, execution: { node, workspace: request.cwd, remote: true,
     ...(typeof payload.receiptId === 'string' ? { receiptOwner: 'destination' } : {}) } };
@@ -60,7 +80,9 @@ export async function executeOnNode(node, request, { worker = runWorker, process
   if (dispatch) {
     const input = JSON.stringify(destinationDispatchRequest(request));
     if (Buffer.byteLength(input) > 65536) throw new Error('Remote dispatch request is too large');
-    transport = { operation: 'direct', cwd: request.cwd, argv: ['total-recall', 'meta-harness', 'dispatch', '--stdin', '--json'], input, timeoutMs: 600000 };
+    // The transport outlives the attempt it carries by a minute, so the destination reports its own timeout (A-101).
+    transport = { operation: 'direct', cwd: request.cwd, argv: ['total-recall', 'meta-harness', 'dispatch', '--stdin', '--json'], input,
+      timeoutMs: Number.isInteger(request.timeoutMs) && request.timeoutMs > 0 ? request.timeoutMs + 60_000 : 600000 };
   }
   const managed = dispatch || (transport.argv?.[1] === 'meta-harness' &&
     ['route', 'coordinate', 'review', 'process', 'run-command', 'usage-retry'].includes(transport.argv[2]));

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/hermes.mjs

@@ -27,6 +27,32 @@ function withGate(text) {
   return `${text.replace(/\n*$/, text ? '\n' : '')}\nhooks:\n  pre_tool_call:\n${entry}`;
 }
 
+/**
+ * Remove every hook list item whose command runs the gate. Other tools rewrite config.yaml (the
+ * lesson hooks re-serialize it), so the item is found by indentation, not by its exact text: the
+ * item runs from its `- ` line to the next line indented no deeper than that dash.
+ */
+export function withoutGate(text) {
+  if (!text.includes(GATE)) return text;
+  const exact = text.replace(ENTRY_LINES, '');
+  if (!exact.includes(GATE)) return exact;
+  let lines = text.split('\n');
+  const indent = (line) => line.match(/^ */)[0].length;
+  for (let guard = 0; guard < 50; guard++) {
+    const hit = lines.findIndex((line) => line.includes(GATE));
+    if (hit < 0) break;
+    let start = hit;
+    while (start >= 0 && !/^ *- /.test(lines[start])) start--;
+    if (start < 0 || indent(lines[start]) > indent(lines[hit])) break;
+    const dash = indent(lines[start]);
+    let end = start + 1;
+    while (end < lines.length && (lines[end].trim() === '' || indent(lines[end]) > dash)) end++;
+    while (end > start + 1 && lines[end - 1].trim() === '') end--;
+    lines = [...lines.slice(0, start), ...lines.slice(end)];
+  }
+  return lines.join('\n');
+}
+
 export const hermesAdapter = {
   id: 'hermes',
   level: 'enforced',
@@ -118,7 +144,9 @@ export const hermesAdapter = {
     const present = text.includes(GATE);
     if (remove || off) {
       if (present) {
-        if (!dryRun) fs.writeFileSync(configPath, text.replace(ENTRY_LINES, ''));
+        const next = withoutGate(text);
+        if (next.includes(GATE)) throw new Error(`could not remove the gate from ${configPath}; remove the pre_tool_call entry that runs "${GATE}" by hand`);
+        if (!dryRun) fs.writeFileSync(configPath, next);
         removed.push('managed pre_tool_call gate');
       }
       return { settings: configPath, added, removed };

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/gate-adapters/index.mjs

@@ -1,5 +1,5 @@
 /**
- * Gate Adapters registry for Meta Harness (tr-plugin-cli-agents).
+ * Gate Adapters registry for Metaharness (tr-plugin-cli-agents).
  * Provides harness-specific parsing, emission, installation and verification.
  */
 import { claudeAdapter } from './claude.mjs';

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/included-usage.mjs

@@ -195,7 +195,7 @@ export function queryCodexAccount(cwd, { env = process.env, timeoutMs = 10000 }
         child.kill('SIGTERM');
       }
     });
-    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'meta_harness', title: 'Meta Harness', version: '1' } } });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'meta_harness', title: 'Metaharness', version: '1' } } });
   });
 }