total-recall-brain 3.43.3 → 3.45.0

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

@@ -9,16 +9,52 @@ import { recordRunReceipt } from './learner.mjs';
 import { resolvePool, localExecutionNode } from './pool.mjs';
 import { routeTask } from './router.mjs';
 import { runQualityGate } from './gate.mjs';
-import { isGitRepo, createWorktree, removeWorktree, commitAll, linkDependencies, deleteBranch } from './worktree.mjs';
+import { isGitRepo, isDirty, pushBranch, createWorktree, removeWorktree, commitAll, linkDependencies, deleteBranch, provideDependencies } from './worktree.mjs';
 import { forwardRemoteOperation } from './remote-operation.mjs';
+import { queueIncludedJob } from './usage-queue.mjs';
+import { configDir } from './paths.mjs';
+import path from 'node:path';
+import { cancellationResult } from './worker.mjs';
+import { executeCodeReview, reviewBlocksPush } from './review.mjs';
+import { sessionOptions } from './session/run.mjs';
+import fs from 'node:fs';
+import { jobPaths } from './control.mjs';
+
+// A routed attempt gets time in proportion to the work the route measured (A-101); --timeout-ms overrides.
+export const ROUTED_TIMEOUT_MS = { local: 15 * 60_000, budget: 30 * 60_000, frontier: 90 * 60_000 };
+
+/**
+ * What Metaharness itself recorded about this job, for the reviewer (A-122): questions the agent
+ * asked, the operator's replies, the goal check and the gate. The reviewer sees only the diff
+ * otherwise and cannot verify claims about how the job ran.
+ */
+export function reviewEvidence(jobId, attempt = {}) {
+  const evidence = { goalCheck: attempt.goalCheck ?? null, gate: attempt.gate ? { status: attempt.gate.status, passed: attempt.gate.passed } : null, questions: [], replies: [] };
+  if (!jobId) return evidence;
+  let paths;
+  try { paths = jobPaths(jobId); } catch { return evidence; }
+  const lines = file => { try { return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch { return []; } };
+  for (const e of lines(paths.events)) if (e.kind === 'question') evidence.questions.push({ requestId: e.requestId, questions: e.questions || e.text, source: e.source, t: e.t });
+  for (const c of lines(paths.inbox)) if (c.type === 'reply' || c.command === 'reply') evidence.replies.push({ requestId: c.requestId || null, text: c.text, t: c.t });
+  return evidence;
+}
 
 export async function executeRoutedTask(task, options = {}) {
+  if (cancellationResult()) return cancellationResult();
   const remote = await forwardRemoteOperation('route', task, { ...options, execute: true });
   if (remote) return remote;
   if (options.node) localExecutionNode(options);
   const cwd = options.cwd || process.cwd();
+  const controls = sessionOptions({ ...options, cwd });
   if (!isGitRepo(cwd)) throw new Error('Routed execution writes on its own branch, so it must run inside a git repository');
   const route = options.route || await routeTask(task, options);
+  const replay = { kind: 'route', gate: options.gate === true, gateOptions: options.gateOptions, controls };
+  if (!route.selected && route.deferred) {
+    const blocked = { ok: false, failureKind: 'quota', error: 'The included usage allowance is exhausted.', resetsAt: route.deferred.resetsAt };
+    const job = await queueIncludedJob({ agent: route.deferred.harness, cwd, prompt: task }, blocked,
+      { role: 'Routed', replay, launchPrevented: true });
+    return { ...blocked, route, attempts: [], queued: true, queueId: job.id };
+  }
   if (!route.selected) return { ok: false, route, attempts: [], error: 'No harness can take this task right now.' };
   const node = localExecutionNode(options, route.placement);
   const pool = options.pool || (await resolvePool(options)).ready.map(h => h.id);
@@ -27,32 +63,50 @@ export async function executeRoutedTask(task, options = {}) {
   const attempts = [];
   const alerts = [];
   const tried = new Set();
-  let harness = route.selected, diagnostic = null, previous = null;
+  let harness = route.selected, diagnostic = null, previous = null, carried = null;
+  const timeoutMs = options.timeoutMs || ROUTED_TIMEOUT_MS[route.tier] || ROUTED_TIMEOUT_MS.budget;
 
   for (let index = 1; index <= maxAttempts && harness; index += 1) {
+    if (cancellationResult()) return { route, attempts, alerts, ...cancellationResult() };
     tried.add(harness);
     const branch = `meta-harness/${id}-${index}-${harness}`;
-    const directory = createWorktree(cwd, { branch });
-    const attempt = { harness, branch: null, commit: null, gate: null, escalatedFrom: previous };
+    // An escalation continues from the previous attempt's unfinished work instead of starting over (A-102).
+    const directory = createWorktree(cwd, { branch, ...(carried ? { ref: carried } : {}) });
+    // A-107: each attempt streams its agent's events here live; the path is announced first.
+    const progressFile = options.progressDir === false ? undefined
+      : path.join(options.progressDir || path.join(configDir(), 'jobs'), `${id}-${index}-${harness}.events.jsonl`);
+    const attempt = { harness, branch: null, commit: null, gate: null, escalatedFrom: previous, ...(progressFile ? { progressFile } : {}) };
     attempts.push(attempt);
+    if (progressFile) console.error(JSON.stringify({ progress: progressFile, attempt: index, harness }));
+    // A-109: the agent gets the repository's dependencies in its own checkout, so its tests run.
+    let stopped;
     try {
+      attempt.dependencies = (options.provideDependencies || provideDependencies)(cwd, directory);
       const prompt = `Work only in this checkout. Do not commit; the harness commits your changes.\nTask:\n${task}${diagnostic ? `\n\nA previous attempt by ${previous} failed. Diagnostic:\n${diagnostic}` : ''}`;
-      const result = await dispatchWithReceipt({ agent: harness, node, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous });
+      const result = await dispatchWithReceipt({ agent: harness, node, branch, cwd: directory, contextCwd: cwd, contextTask: task, prompt, permissions: { read: true, write: true }, timeoutMs,
+        ...controls, goal: controls.goal || task,
+        ...(progressFile ? { progressFile } : {}), allowUnknownAuth: options.allowUnknownAuth === true }, { dispatchFn: options.dispatchFn, role: 'Routed', complexityScore: route.complexity?.score, escalatedFrom: previous, replay, retryId: options.retryId });
       attempt.ok = result.ok === true;
+      if (result.cancelled) stopped = result;
       attempt.durationMs = result.durationMs;
-      attempt.output = result.response || null;
+      attempt.timeoutMs = timeoutMs;
+      attempt.output = result.response || result.partialOutput || null;
+      if (result.sessionId) { attempt.sessionId = result.sessionId; attempt.branch = branch; }
+      attempt.goalCheck = result.goalCheck;
+      attempt.structured = result.structured;
+      attempt.usage = result.usage;
+      if (!attempt.ok && result.stderr) attempt.stderr = result.stderr;
       if (result.ok) {
         attempt.commit = commitAll(directory, `meta-harness: ${task.slice(0, 60)}\n\nAgent: ${harness}`);
         if (attempt.commit) attempt.branch = branch;
-        else {
-          attempt.ok = false; attempt.error = 'The agent reported success but changed no files.';
-          await recordRunReceipt({ harness, role: 'Implementer', task, success: false, failureKind: 'no-change', error: attempt.error });
-        }
+        // Keep the session branch even when the goal required no repository edit.
+        else if (result.sessionId) attempt.branch = branch;
       } else {
         attempt.error = result.error;
         attempt.failureKind = result.failureKind;
+        if (result.queued || result.queueError || (result.failureKind === 'quota' && options.retryId) || ['billing-policy', 'limit', 'interrupted'].includes(result.failureKind)) stopped = result;
       }
-      if (attempt.ok && options.gate) {
+      if (attempt.ok && options.gate && !cancellationResult()) {
         linkDependencies(cwd, directory);
         attempt.gate = await (options.gateFn || runQualityGate)(directory, options.gateOptions);
         // A gate that could not run says nothing about this agent's work, so it does not escalate.
@@ -64,23 +118,54 @@ export async function executeRoutedTask(task, options = {}) {
         await recordRunReceipt({ harness, role: 'Gate', task, success: attempt.gate.passed, failureKind: attempt.gate.passed ? null : 'gate', error: attempt.gate.passed ? null : attempt.gate.summary, gate: attempt.gate.status });
         attempt.ok = attempt.gate.passed;
       }
+      if (attempt.ok && attempt.commit && !cancellationResult()) {
+        attempt.review = await (options.reviewFn || executeCodeReview)({ cwd, author: harness, task,
+          evidence: reviewEvidence(options.jobId || process.env.TR_METAHARNESS_JOB, attempt),
+          target: `HEAD...${attempt.commit}`, dispatchFn: options.dispatchFn, reviewer: options.reviewer,
+          allowUnknownAuth: options.allowUnknownAuth === true, availableHarnesses: options.availableHarnesses });
+        if (reviewBlocksPush(attempt.review)) {
+          attempt.ok = false; attempt.failureKind = 'review';
+          attempt.error = attempt.review.error || JSON.stringify(attempt.review.review?.findings || []) || 'Review blocked the push.';
+        }
+      }
     } catch (error) {
       attempt.ok = false;
       attempt.error = String(error.message);
     } finally {
-      removeWorktree(cwd, directory);
-      // Only the branch this run hands back survives; the attempt record keeps what happened.
-      if (!attempt.ok) { deleteBranch(cwd, branch); attempt.branch = null; }
+      if (cancellationResult()) {
+        Object.assign(attempt, cancellationResult());
+        stopped = cancellationResult();
+      }
+      // A failed attempt's edits are kept as an unfinished commit on its branch for review and for the
+      // next attempt to continue from; only an attempt that changed nothing loses its branch (A-102).
+      if (!attempt.ok && !attempt.commit) {
+        let wip = null;
+        try { wip = commitAll(directory, `meta-harness: unfinished attempt by ${harness}\n\n${String(attempt.error || '').slice(0, 300)}`); }
+        catch (error) { attempt.wipError = String(error.message); }
+        if (wip) { attempt.wip = wip; attempt.branch = branch; carried = wip; }
+      } else if (!attempt.ok && attempt.commit) carried = attempt.commit;
+      // Edits that could not be committed are never deleted (A-114): the checkout and branch stay for recovery.
+      if (attempt.wipError && isDirty(directory)) { attempt.keptWorktree = directory; attempt.branch = branch; }
+      else {
+        removeWorktree(cwd, directory);
+        if (!attempt.ok && !attempt.wip && !attempt.commit && !attempt.sessionId) { deleteBranch(cwd, branch); attempt.branch = null; }
+      }
     }
 
-    if (attempt.ok) return { ok: true, route, gateApplied: Boolean(options.gate), branch: attempt.branch, commit: attempt.commit, harness, attempts, alerts };
+    if (stopped?.cancelled) return { ...stopped, route, attempts, alerts, branch: attempt.branch, commit: attempt.commit, wip: attempt.wip, harness };
+    if (attempt.ok) {
+      const push = options.push === false ? { pushed: false, reason: 'push disabled for this run' } : pushBranch(cwd, attempt.branch);
+      return { ok: true, route, goalCheck: attempt.goalCheck, structured: attempt.structured, review: attempt.review,
+        gateApplied: Boolean(options.gate), branch: attempt.branch, commit: attempt.commit, push, harness, attempts, alerts };
+    }
+    if (stopped) return { ...stopped, route, attempts, alerts };
 
     const remaining = pool.filter(item => !tried.has(item));
     const next = remaining.length ? evaluateGateCascade(harness, { testsPassed: false }, remaining) : null;
     diagnostic = attempt.gate?.summary || attempt.error || 'The previous attempt failed.';
     previous = harness;
     harness = next?.recommendedHarness && !tried.has(next.recommendedHarness) ? next.recommendedHarness : null;
-    if (harness) alerts.push(await notifyAlert({ title: 'Meta Harness: escalating', message: `${previous} failed on "${task.slice(0, 60)}"; escalating to ${harness}.`, severity: 'warning' }));
+    if (harness) alerts.push(await notifyAlert({ title: 'Metaharness: escalating', message: `${previous} failed on "${task.slice(0, 60)}"; escalating to ${harness}.`, severity: 'warning' }));
   }
   return { ok: false, route, gateApplied: Boolean(options.gate), attempts, alerts, error: 'No attempt passed.' };
 }

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

@@ -8,6 +8,7 @@ import { recordRunReceipt } from './learner.mjs';
 import { classifyTaskComplexity, synthesizeOneWayValve } from '../capability/index.mjs';
 import { notifyAlert } from './alerts.mjs';
 import { dispatchWithReceipt } from './dispatch.mjs';
+import { queueIncludedJob } from './usage-queue.mjs';
 import { resolvePool, localExecutionNode } from './pool.mjs';
 import { createThread, appendThreadTurn, updateThread } from './threads.mjs';
 import { executeCodeReview } from './review.mjs';
@@ -15,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;
@@ -100,10 +103,14 @@ 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' : '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 || '' });
     return result;
   };
@@ -126,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(); }
     }
 
@@ -163,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 };
     })();
   }
 }
@@ -185,13 +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 }), feedback: result.response || null };
+    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) {
@@ -209,12 +223,21 @@ 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) };
     } finally {
@@ -223,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);
@@ -235,6 +260,14 @@ export async function coordinateTask(taskDescription, options = {}) {
   if (!['pipeline', 'orchestrate', 'council', 'race'].includes(mode)) throw new Error(`Unsupported coordination mode: ${mode}`);
   localExecutionNode(options);
   const poolInfo = await resolvePool(options);
+  const wall = poolInfo.excluded.find(item => item.failureKind === 'quota');
+  const minimum = mode === 'race' || ((mode === 'pipeline' || mode === 'orchestrate') && options.allowSameFamily !== true) ? 2 : 1;
+  if (options.execute === true && wall && poolInfo.ready.length < minimum) {
+    const blocked = { ok: false, failureKind: 'quota', error: 'Coordination is waiting for included usage.', resetsAt: wall.resetsAt };
+    const job = await queueIncludedJob({ agent: wall.harness, cwd: options.cwd || process.cwd(), prompt: task }, blocked,
+      { role: 'Coordinate', launchPrevented: true });
+    return { ...blocked, mode, executedLive: false, queued: true, queueId: job.id, needsReview: job.needsReview };
+  }
   if (mode === 'council') return runCouncil(task, poolInfo, options);
   if (mode === 'race') return runRace(task, poolInfo, options);
   return runPipeline(task, poolInfo, options);

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

@@ -0,0 +1,40 @@
+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 };
+
+export function commandPermissions(value = DEFAULT_PERMISSIONS) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Command permissions must be boolean values');
+  for (const key of Object.keys(value)) {
+    if (!Object.hasOwn(DEFAULT_PERMISSIONS, key) || typeof value[key] !== 'boolean') throw new Error(`Invalid permission ${key}`);
+  }
+  return { ...DEFAULT_PERMISSIONS, ...value };
+}
+
+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 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) {
+    throw new Error('Dispatch requires an explicit agent, absolute workspace, and bounded nonempty prompt');
+  }
+  if (request.node !== undefined && (typeof request.node !== 'string' || !request.node.trim() || /[\0\r\n]/.test(request.node))) throw new Error('Invalid dispatch node');
+  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, ...sessionOptions(request), permissions: commandPermissions(request.permissions), timeoutMs };
+}
+
+/** The installed destination starts from its own project context and decides containment itself. */
+export function destinationDispatchRequest(request) {
+  const fields = PUBLIC_FIELDS.filter(key => key !== 'node' && request[key] !== undefined);
+  return validateDispatchRequest(Object.fromEntries(fields.map(key => [key, request[key]])));
+}