total-recall-brain 3.44.0 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "meta-harness",
-  "name": "Meta Harness",
-  "version": "0.3.9",
+  "name": "Metaharness",
+  "version": "0.3.13",
   "description": "Discover, configure, document, track, and run coding agent harnesses through Total Recall across mesh nodes.",
   "gate": {
     "tasks": ["Run work in another agent harness", "Choose which harness takes a task", "Check harness versions, sign-in and quota", "Read a harness's official documentation"],
@@ -124,9 +124,119 @@
         "description": "Run a task from stdin after automatic Total Recall bootstrap",
         "effect": "write",
         "output": "json",
-        "args": [],
+        "args": [
+          { "name": "background", "flag": "--background", "type": "boolean", "label": "Return the job ID and log" },
+          { "name": "goal", "flag": "--goal", "type": "string", "label": "Goal checked at completion" },
+          { "name": "maxTurns", "flag": "--max-turns", "type": "number", "label": "Job turn limit" },
+          { "name": "maxBudgetUsd", "flag": "--max-budget-usd", "type": "number", "label": "Job cost limit in USD" },
+          { "name": "maxTokens", "flag": "--max-tokens", "type": "number", "label": "Job token limit" },
+          { "name": "resultSchema", "flag": "--result-schema", "type": "string", "label": "JSON Schema file" },
+          { "name": "approvals", "flag": "--approvals", "type": "string", "label": "auto, operator, or rules" },
+          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" }
+        ],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "fork",
+        "description": "Start a new job from a saved session and branch",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "positional": true, "required": true, "label": "Job ID prefix" },
+          { "name": "at", "flag": "--at", "type": "string", "label": "Last turn to copy when supported" },
+          { "name": "background", "flag": "--background", "type": "boolean", "label": "Return the job ID and log" }
+        ],
         "timeout_ms": 600000
       },
+      {
+        "name": "resume",
+        "description": "Continue a finished job session on its saved branch",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "positional": true, "required": true, "label": "Job ID prefix" },
+          { "name": "text", "type": "string", "positional": true, "required": true, "label": "Continuation message" },
+          { "name": "background", "flag": "--background", "type": "boolean", "label": "Return the job ID and log" }
+        ],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "cancel",
+        "description": "Stop a running job and wait up to 60 seconds for its cancelled result",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job ID prefix or log path", "positional": true, "required": true }
+        ],
+        "timeout_ms": 65000
+      },
+      {
+        "name": "reply",
+        "description": "Send a reply to a running job or answer its oldest waiting question",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job ID prefix or log path", "positional": true, "required": true },
+          { "name": "text", "type": "string", "label": "Reply text", "positional": true, "required": true },
+          { "name": "localDelivery", "flag": "--local-delivery", "type": "boolean", "label": "Deliver on this node" }
+        ],
+        "timeout_ms": 65000
+      },
+      {
+        "name": "approve",
+        "description": "Allow or deny a waiting job approval",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job ID prefix or log path", "positional": true, "required": true },
+          { "name": "requestId", "type": "string", "label": "Approval request ID", "positional": true, "required": true },
+          { "name": "value", "type": "string", "label": "allow or deny", "positional": true, "required": true },
+          { "name": "localDelivery", "flag": "--local-delivery", "type": "boolean", "label": "Deliver on this node" }
+        ],
+        "timeout_ms": 65000
+      },
+      {
+        "name": "interrupt",
+        "description": "Stop the current job turn and keep its session resumable",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job ID prefix or log path", "positional": true, "required": true },
+          { "name": "localDelivery", "flag": "--local-delivery", "type": "boolean", "label": "Deliver on this node" }
+        ],
+        "timeout_ms": 65000
+      },
+      {
+        "name": "goal",
+        "description": "Set the goal of a running job",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job ID prefix or log path", "positional": true, "required": true },
+          { "name": "text", "type": "string", "label": "Goal text", "positional": true, "required": true },
+          { "name": "localDelivery", "flag": "--local-delivery", "type": "boolean", "label": "Deliver on this node" }
+        ],
+        "timeout_ms": 65000
+      },
+      {
+        "name": "mcp",
+        "description": "Serve the Metaharness ask and approve tools over MCP stdio",
+        "effect": "write",
+        "args": [
+          { "name": "approvals", "flag": "--approvals", "type": "string", "label": "Approval policy: auto, operator, or rules" },
+          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" }
+        ]
+      },
+      {
+        "name": "watch",
+        "description": "Show job status, recent events, waiting questions and approvals",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          { "name": "job", "type": "string", "label": "Job id prefix or event log path", "positional": true },
+          { "name": "tail", "flag": "--tail", "type": "string", "label": "Events to show" }
+        ]
+      },
       {
         "name": "included-status",
         "description": "Read included usage policy and optionally check Codex allowance without a turn",
@@ -383,6 +493,13 @@
         "output": "json",
         "timeout_ms": 600000,
         "args": [
+          { "name": "goal", "flag": "--goal", "type": "string", "label": "Goal checked at completion" },
+          { "name": "maxTurns", "flag": "--max-turns", "type": "number", "label": "Job turn limit" },
+          { "name": "maxBudgetUsd", "flag": "--max-budget-usd", "type": "number", "label": "Job cost limit in USD" },
+          { "name": "maxTokens", "flag": "--max-tokens", "type": "number", "label": "Job token limit" },
+          { "name": "resultSchema", "flag": "--result-schema", "type": "string", "label": "JSON Schema file" },
+          { "name": "approvals", "flag": "--approvals", "type": "string", "label": "auto, operator, or rules" },
+          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" },
           {
             "name": "task",
             "type": "string",
@@ -427,6 +544,13 @@
         "effect": "write",
         "output": "json",
         "args": [
+          { "name": "goal", "flag": "--goal", "type": "string", "label": "Goal checked at completion" },
+          { "name": "maxTurns", "flag": "--max-turns", "type": "number", "label": "Job turn limit" },
+          { "name": "maxBudgetUsd", "flag": "--max-budget-usd", "type": "number", "label": "Job cost limit in USD" },
+          { "name": "maxTokens", "flag": "--max-tokens", "type": "number", "label": "Job token limit" },
+          { "name": "resultSchema", "flag": "--result-schema", "type": "string", "label": "JSON Schema file" },
+          { "name": "approvals", "flag": "--approvals", "type": "string", "label": "auto, operator, or rules" },
+          { "name": "questionTimeoutMs", "flag": "--question-timeout-ms", "type": "number", "label": "Question timeout in milliseconds" },
           {
             "name": "task",
             "type": "string",
@@ -474,16 +598,10 @@
       },
       {
         "name": "learn",
-        "description": "Summarize run receipts into scorecards and quota walls; --emit writes proposals to memory",
+        "description": "Summarize run receipts into scorecards, quota walls and proposals",
         "effect": "write",
         "output": "json",
         "args": [
-          {
-            "name": "emit",
-            "flag": "--emit",
-            "type": "boolean",
-            "label": "Write proposals through the memory owner"
-          },
           { "name": "void", "flag": "--void", "type": "string", "label": "Comma-separated receipt ids to void" },
           { "name": "reason", "flag": "--reason", "type": "string", "label": "Why the receipts are void" }
         ]
@@ -584,7 +702,7 @@
           {
             "name": "action",
             "type": "string",
-            "label": "list | show | create | update | close | delete",
+            "label": "list | show | create | update | close | delete | cleanup-fixtures",
             "required": true,
             "positional": true
           },
@@ -598,7 +716,8 @@
           { "name": "summary", "flag": "--summary", "type": "string", "label": "Thread summary" },
           { "name": "status", "flag": "--status", "type": "string", "label": "Lifecycle status or list filter" },
           { "name": "platform", "flag": "--platform", "type": "string", "label": "Harness platform or list filter" },
-          { "name": "branch", "flag": "--branch", "type": "string", "label": "Deliverable branch" }
+          { "name": "branch", "flag": "--branch", "type": "string", "label": "Deliverable branch" },
+          { "name": "dryRun", "flag": "--dry-run", "type": "boolean", "label": "Preview fixture cleanup" }
         ]
       },
       {
@@ -623,6 +742,13 @@
           { "name": "allowUnknownAuth", "type": "boolean", "flag": "--allow-unknown-auth", "label": "Explicitly allow an unknown login state" }
         ]
       },
+      {
+        "name": "reviews",
+        "description": "Read durable review results, including disposition and selected diff",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
       {
         "name": "review",
         "description": "Execute automated adversarial cross-model code review on Git diffs, PR branches, or staged changes",
@@ -682,7 +808,7 @@
     "setup_command": "setup"
   },
   "branding": {
-    "name": "Meta Harness",
+    "name": "Metaharness",
     "color": "#3b82f6",
     "accent": "#38bdf8",
     "background": "#0c1427",
@@ -695,7 +821,7 @@
         "kind": "card",
         "tag": "meta-harness-card",
         "module": "ui/card.js",
-        "description": "Meta Harness multi-agent coordination matrix"
+        "description": "Metaharness multi-agent coordination matrix"
       }
     ]
   },
@@ -741,6 +867,13 @@
       "command": "maintenance --models",
       "placement": "selected-node",
       "timeout_ms": 300000
+    },
+    {
+      "intent": "Report quota walls and measured usage to the operator",
+      "schedule": "*/15 * * * *",
+      "command": "alerts check",
+      "placement": "selected-node",
+      "timeout_ms": 60000
     }
   ]
 }

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.' };
 }