total-recall-brain 3.44.0 → 3.46.0

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/skills/meta-harness/SKILL.md

@@ -4,7 +4,7 @@ description: Discover, route, coordinate, review and run coding agent harnesses
 repo_scoped: false
 ---
 
-# Meta Harness
+# Metaharness
 
 Coordinates coding agent harnesses across mesh nodes. `cli-agents` is an alias of `meta-harness`. Run `total-recall meta-harness --help` for flags.
 
@@ -12,7 +12,7 @@ Coordinates coding agent harnesses across mesh nodes. `cli-agents` is an alias o
 1. **Believe the status words.** `ready` was proved by a login probe. `unverified` has no probe, so only a completed run proves it. `needs_auth`, `blocked` and `exhausted` cannot take work; the reason is in `quotaNote` and in `excluded`.
 2. **No figure without a source.** `benchmarks` shows only fetched figures with their source and time. A dash means nobody measured it. Adapter quality and cost scores are configured priors, not measurements.
 3. **Writing happens on a branch.** `route --execute`, `coordinate --execute` and race work in their own worktree on a `meta-harness/...` branch. Nothing merges into your branch; review the branch and merge it yourself.
-4. **Long runs go to the background.** The host stops plugin commands after 10 minutes, so add `--background` to any multi-stage `--execute`. It prints a log path that receives the final JSON, and a pipeline also records a thread. Stopping a run stops its agents and removes its worktrees, unfinished branches and open thread. A remote job (`--node` with an absolute `--cwd`) has a one-hour budget; `--timeout-ms` changes it.
+4. **Long runs go to the background.** The host stops plugin commands after 10 minutes, so add `--background` to any multi-stage `--execute`. Dispatch also accepts `--background`. The command prints a job ID and log path. The first log line and `jobs/<id>.pid` record its PID. Use `cancel <job>` to stop it. SIGTERM and SIGINT stop its agents and prevent further attempts. Changed work stays on its branch as a WIP commit; the result reports that branch. Worktrees are removed and progress becomes `cancelled`. The PID file is removed when the job ends. A pipeline also closes its thread. A remote job (`--node` with an absolute `--cwd`) has a one-hour budget; `--timeout-ms` changes it.
 5. **Cost.** dsh, hermes and other metered harnesses bill per token, and `route` warns when it picks one. `--jev` also makes a metered call.
 
 ## Commands
@@ -24,9 +24,23 @@ Coordinates coding agent harnesses across mesh nodes. `cli-agents` is an alias o
 - `decompose "<task>"`: the stages and which ready harness takes each.
 - `review [<git-range>] [--staged] [--author <id>] [--reviewer <id>] [--thread <id>]`: review by another model family. `NO_DIFF` means there was nothing to review.
 - `dispatch --stdin` with JSON `{agent, cwd, prompt, permissions, node, allowUnknownAuth}`: one bootstrapped run with a receipt.
-- `threads list|show|create|close|delete`, `learn [--emit]`, `alerts check|test [--dry-run]`, `adapter list|add|remove`.
+- `cancel <job>`: stop a running local job by ID prefix or log path. Wait up to 60 seconds for its cancelled result. Finished and unknown jobs return an error. Use `watch <job>` to read progress.
+- `reply <job> "<text>"`: steer the running turn or answer its oldest question. `approve <job> <request> allow|deny` answers an approval. Native requests and MCP requests use the same approval policy.
+- `interrupt <job>`: stop the current turn and keep its session for `resume`. `goal <job> "<text>"` replaces the running job's goal.
+- `fork <job> [--at <turn>] [--background]`: start a new job from the session history on a new branch. Selected turns require native support. `resume <job> "<text>" [--background]` continues a finished session on its saved branch. Both commands keep the parent's history.
+- `route`, `coordinate` and `dispatch` accept `--goal`, `--max-turns`, `--max-budget-usd`, `--max-tokens`, `--result-schema <file>`, `--approvals auto|operator|rules` and `--question-timeout-ms`. Dispatch accepts the same fields in camelCase in its stdin JSON (`approvalPolicy` selects approvals). The default goal is the task. Completion requires a separate goal check with concrete evidence. File changes alone do not prove completion. A limit fails the job without escalation. Structured results get one correction turn if validation fails.
+- `mcp [--approvals auto|operator|rules] [--question-timeout-ms <ms>]`: serve the job's `ask` and `approve` tools over stdio. Metaharness configures this server for Claude and Codex. `watch <job>` includes capabilities, usage, plans, diffs, hooks, model reroutes and waiting requests.
+- A routed change gets a review from another model family after its gate and before its push. A blocking finding or an unreadable review stops the push. The job result contains the review.
+- A token or USD cap requires measured usage. A harness that cannot report the required usage fails with `failureKind: limit`. A zero USD cap starts no agent turn. Goal checks and JSON corrections count toward job limits. JSON Schema assertions outside the portable validator's supported set fail validation.
+- `threads list|show|create|close|delete`, `learn`, `alerts check|test [--dry-run]`, `adapter list|add|remove`.
+- `reviews`: read the durable review ledger, including selected diff, commit, reviewer, verdict and disposition. Thread deletion does not remove reviews.
+- `threads cleanup-fixtures [--dry-run]`: one-time cleanup of exact test fixture titles. The atomic SSSS record lists removed and retained IDs. Real end-to-end job threads stay in place.
 - `adoption [--node <id> | --all]`: inspect native gate activity and real managed run receipts separately from installation and login.
 - `docs-status`, `docs-refresh`, `docs-search --query <q>`, `docs-read`, `maintenance`, `setup`, `runtime <agent> <maintenance-command>`. Use dispatch for agent tasks and the service owner for gateway changes.
 
+`setup --node <recorded-node>` places documentation maintenance, model maintenance
+and quota alerts through the existing daemon. Maintenance attempts all stale
+documentation sources and reports setup, gate and documentation failures separately.
+
 ## When something fails
 Read `failureKind` on the result. `quota` carries `resetsAt`, and routing avoids that harness until then. `auth` and `not-ready` mean the operator must sign in or install something. These do not count against a harness's pass rate; `agent` and `gate` failures do.

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

@@ -90,9 +90,9 @@ export async function inspectFleetAdoption({ node, inventory = listTargets, read
           argv: ['total-recall', 'meta-harness', 'adoption', '--json'],
         });
         try { report = JSON.parse(result.output); } catch { /* The installed CLI did not supply an adoption report. */ }
-        if (report?.error === 'Unknown operation: adoption') return { ...row, status: 'update-required', error: 'The installed Meta Harness does not support adoption reports.' };
+        if (report?.error === 'Unknown operation: adoption') return { ...row, status: 'update-required', error: 'The installed Metaharness does not support adoption reports.' };
         if (!report || !Array.isArray(report.agents) || typeof report.pluginVersion !== 'string' || typeof report.ok !== 'boolean' || (report.ok && !result.ok)) {
-          return { ...row, status: 'adoption-unavailable', error: 'The installed Meta Harness did not return an adoption report. Verify its version and CLI availability.' };
+          return { ...row, status: 'adoption-unavailable', error: 'The installed Metaharness did not return an adoption report. Verify its version and CLI availability.' };
         }
       }
       return { ...row, status: report.ok ? 'inspected' : 'partial', report };

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

@@ -4,7 +4,7 @@ import { readReceipts, activeQuotaWalls } from './learner.mjs';
 
 const SEVERITY = { info: 'info', warning: 'high', high: 'high', critical: 'critical' };
 
-export async function notifyAlert({ title = 'Meta Harness', message = '', severity = 'info', eventId, dryRun = false } = {}) {
+export async function notifyAlert({ title = 'Metaharness', message = '', severity = 'info', eventId, dryRun = false } = {}) {
   const args = ['alerts', 'send', '--title', title, '--message', message, '--severity', SEVERITY[severity] || 'info', '--source', 'meta-harness'];
   if (eventId) args.push('--event-id', eventId);
   if (dryRun) args.push('--dry-run');
@@ -20,13 +20,13 @@ export async function notifyAlert({ title = 'Meta Harness', message = '', severi
 export async function checkAlerts({ quotas = {}, threshold = 85, dryRun = false } = {}) {
   const walls = activeQuotaWalls(await readReceipts());
   const candidates = Object.entries(walls).map(([harness, wall]) => ({
-    title: `Meta Harness: ${harness} is out of quota`,
+    title: `Metaharness: ${harness} is out of quota`,
     message: `${wall.message || 'Quota wall observed.'} Routing avoids ${harness} until ${wall.until}.`,
     severity: 'warning', eventId: `meta-harness-wall-${harness}-${wall.until}`,
   }));
   for (const [id, quota] of Object.entries(quotas)) {
     if (typeof quota?.usagePercent === 'number' && quota.usagePercent > threshold && quota.billingModel !== 'local') candidates.push({
-      title: `Meta Harness: ${id} is at ${quota.usagePercent}%`, message: `Measured usage on ${id} is above ${threshold}%.`,
+      title: `Metaharness: ${id} is at ${quota.usagePercent}%`, message: `Measured usage on ${id} is above ${threshold}%.`,
       severity: 'warning', eventId: `meta-harness-usage-${id}-${new Date().toISOString().slice(0, 10)}`,
     });
   }

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

@@ -9,18 +9,46 @@ 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 };
+  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,
@@ -35,34 +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, replay, retryId: options.retryId });
+      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) || result.failureKind === 'billing-policy') stopped = result;
+        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.
@@ -74,16 +118,46 @@ 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));
@@ -91,7 +165,7 @@ export async function executeRoutedTask(task, options = {}) {
     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/chat.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { configDir } from './paths.mjs';
+import { PluginStateStore } from './ssss-store.mjs';
+import { getActiveAdapters } from './worker.mjs';
+
+const CODEX_DRAFT = 'codex://threads/new';
+const MAX_SELECTION_BYTES = 16_384;
+const MAX_DRAFT_LINK_LENGTH = 8_192;
+const UNSAFE_TEXT = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+const BRAIN_ID = /^(?:global|project:[^,]+|tenant:[a-zA-Z0-9._-]+)$/u;
+const ADAPTER_ID = /^[a-z][a-z0-9-]{0,63}$/;
+
+// Chat preferences follow the dashboard's brain. The auth store override is
+// exclusively for credentials and may point outside an isolated dashboard.
+const chatStore = () => new PluginStateStore(
+  path.join(configDir({ ...process.env, TR_SECRETS_BRAIN: undefined }), 'chat-default.json'),
+  'meta-harness',
+);
+const displayAdapter = ({ id, name }) => ({ id, name });
+
+function brainContext(selection) {
+  if (typeof selection !== 'string' || Buffer.byteLength(selection) > MAX_SELECTION_BYTES || UNSAFE_TEXT.test(selection)) {
+    throw new Error('Chat requires a bounded comma-separated list of brain IDs');
+  }
+  const ids = [...new Set(selection.split(',').map(id => id.trim()))];
+  if (ids.some(id => !BRAIN_ID.test(id))) throw new Error('Chat brain IDs must use global, project:<name>, or tenant:<name>');
+  return `Use this Total Recall brain selection for Chat: ${JSON.stringify(ids)}. Resolve the selected IDs through Total Recall before retrieving or writing memory.`;
+}
+
+function launchUrl(adapterId, value) {
+  if (value === undefined) return undefined;
+  const message = 'Use an HTTPS launch URL without credentials, a query or a fragment, or a Codex Chat link for Codex';
+  if (typeof value !== 'string' || value.length > 2048 || UNSAFE_TEXT.test(value) || /\s|\\/u.test(value)) {
+    throw new Error(message);
+  }
+  if (adapterId === 'codex' && /^codex:\/\/threads\/[a-zA-Z0-9_-]{1,128}$/.test(value)) return value;
+  if (!value.startsWith('https://') || /[?#]/.test(value)) throw new Error(message);
+  const url = URL.parse(value);
+  if (!url?.hostname || url.username || url.password) throw new Error(message);
+  return url.href;
+}
+
+function resolveTarget(settings, adapters, context) {
+  const choices = adapters.map(displayAdapter);
+  if (!settings) return { ok: true, configured: false, choices, context };
+  const adapter = adapters.find(({ id }) => id === settings.adapterId);
+  if (!adapter) {
+    return {
+      ok: true, configured: false, choices, context,
+      warning: 'The saved Chat harness is unavailable. Choose a new default.',
+    };
+  }
+
+  const target = launchUrl(adapter.id, settings.url) ?? (adapter.id === 'codex' ? CODEX_DRAFT : undefined);
+  let href = target;
+  if (target === CODEX_DRAFT) {
+    const draft = `${target}?prompt=${encodeURIComponent(context)}`;
+    if (draft.length <= MAX_DRAFT_LINK_LENGTH) href = draft;
+  }
+  return { ok: true, configured: true, choices, context, harness: displayAdapter(adapter), ...(href ? { href } : {}) };
+}
+
+/** Return a draft target. The caller decides when to open it and the operator submits in the harness. */
+export function chatTarget(brains = 'global') {
+  const context = brainContext(brains);
+  const settings = chatStore().read(null);
+  if (settings !== null && (!settings || typeof settings.adapterId !== 'string' || !ADAPTER_ID.test(settings.adapterId))) {
+    throw new Error('The saved Chat default is invalid');
+  }
+  return resolveTarget(settings, getActiveAdapters(), context);
+}
+
+/** Only the adapter and optional launch URL are persistent. */
+export function setChatDefault(adapterId, url) {
+  const adapters = getActiveAdapters();
+  if (!adapters.some(({ id }) => id === adapterId)) throw new Error('Choose a registered Metaharness adapter for Chat');
+  const settings = { adapterId, url: launchUrl(adapterId, url) };
+  chatStore().write(settings);
+  return resolveTarget(settings, adapters, brainContext('global'));
+}

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);