total-recall-brain 3.44.0 → 3.46.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,84 @@
+/** Local job identity and cancellation. A terminal log result is the completion record. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDir } from './paths.mjs';
+import { createProgress } from './worker.mjs';
+
+const jobsDir = () => path.join(configDir(), 'jobs');
+export const newJobId = () => `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+
+export function startJob(operation, { id = newJobId() } = {}) {
+  if (!/^[a-z0-9-]+$/.test(id)) throw new Error('Invalid job ID.');
+  const directory = jobsDir();
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const log = path.join(directory, `${id}.log`);
+  const pidFile = path.join(directory, `${id}.pid`);
+  const record = { job: id, pid: process.pid, operation, startedAt: new Date().toISOString() };
+  fs.appendFileSync(log, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  fs.writeFileSync(pidFile, `${process.pid}\n`, { mode: 0o600, flag: 'wx' });
+  const progress = createProgress({ file: path.join(directory, `${id}.events.jsonl`), harness: operation });
+  return { ...record, log, finish(result) {
+    progress.close(result);
+    fs.appendFileSync(log, `${JSON.stringify(result)}\n`, { mode: 0o600 });
+    fs.rmSync(pidFile, { force: true });
+  } };
+}
+
+function readJob(log) {
+  const lines = fs.readFileSync(log, 'utf8').trim().split('\n');
+  let record;
+  try { record = JSON.parse(lines[0]); } catch { /* old log without PID */ }
+  let result = null;
+  for (const line of lines.slice(1).reverse()) {
+    try {
+      const value = JSON.parse(line);
+      if (typeof value.ok === 'boolean') { result = value; break; }
+    } catch { /* progress text */ }
+  }
+  return { record, result };
+}
+
+export function resolveJob(target) {
+  if (!target) throw new Error('cancel requires a job ID or log path.');
+  const directory = jobsDir();
+  const prefix = path.basename(target).replace(/\.(?:log|pid|events\.jsonl|status\.json)$/, '');
+  const files = fs.existsSync(directory) ? fs.readdirSync(directory) : [];
+  let names = files.filter(name => name.endsWith('.log') && name.startsWith(prefix));
+  if (!names.length) {
+    // An attempt ID from watch resolves to its owning job, never directly to a PID.
+    const events = files.filter(name => name.endsWith('.events.jsonl') && name.startsWith(prefix))
+      .sort((a, b) => fs.statSync(path.join(directory, b)).mtimeMs - fs.statSync(path.join(directory, a)).mtimeMs);
+    let pid;
+    try { pid = JSON.parse(fs.readFileSync(path.join(directory, events[0].replace('.events.jsonl', '.status.json')), 'utf8')).pid; } catch { /* no matching status */ }
+    if (pid) names = files.filter(name => name.endsWith('.log') && readJob(path.join(directory, name)).record?.pid === pid);
+  }
+  const exact = names.find(name => name === `${prefix}.log`);
+  if (!names.length) throw new Error(`No job log matches ${target}.`);
+  if (!exact && names.length > 1) throw new Error(`More than one job matches ${target}. Use a longer job ID.`);
+  const log = path.join(directory, exact || names[0]);
+  return { id: path.basename(log, '.log'), log, ...readJob(log) };
+}
+
+export async function cancelJob(target, { timeoutMs = 60_000, pollMs = 100 } = {}) {
+  const job = resolveJob(target);
+  if (job.result) throw new Error(`Job ${job.id} has finished${job.result.cancelled ? ' (cancelled)' : ''}.`);
+  const pidFile = path.join(jobsDir(), `${job.id}.pid`);
+  let pid;
+  try { pid = Number(fs.readFileSync(pidFile, 'utf8').trim()); } catch { /* stale or old job */ }
+  if (!Number.isSafeInteger(pid) || pid <= 1 || job.record?.pid !== pid || job.record?.job !== job.id) {
+    throw new Error(`Job ${job.id} has no active PID record.`);
+  }
+  try { process.kill(pid, 'SIGTERM'); }
+  catch (error) { throw new Error(`Cannot cancel job ${job.id}: ${error.code === 'ESRCH' ? 'the process has stopped' : error.message}.`); }
+  const deadline = Date.now() + Math.min(timeoutMs, 60_000);
+  do {
+    const { result } = readJob(job.log);
+    if (result) {
+      if (!result.cancelled) throw new Error(`Job ${job.id} finished before it could be cancelled.`);
+      return { ...result, job: job.id, log: job.log };
+    }
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+  } while (Date.now() < deadline);
+  throw new Error(`Job ${job.id} did not report cancellation within ${Math.min(timeoutMs, 60_000) / 1000} seconds. Log: ${job.log}`);
+}

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

@@ -2,7 +2,6 @@
  * Execution receipts and the learning loop.
  * Receipts are an append-only SSSS ledger. Scorecards, quota walls and proposals fold from it.
  */
-import { spawnSync } from 'node:child_process';
 import { computeEmpiricalScorecard } from '../capability/index.mjs';
 import { receiptsFile } from './paths.mjs';
 import { classifyFailure } from './worker.mjs';
@@ -105,18 +104,10 @@ export function activeCredentialBlocks(entries = [], now = Date.now(), holdMs =
   return blocks;
 }
 
-/** With `emit`, proposals are written through the memory owner. A failed write is reported, never hidden. */
-export async function learnFromHistory({ emit = false, runner = spawnSync } = {}) {
+/** Read the same receipts the router uses. Proposals stay in this report. */
+export async function learnFromHistory() {
   const entries = await readReceipts();
   const scorecard = computeEmpiricalScorecard(entries);
   const proposals = proposalsFrom(scorecard, entries);
-  const emitted = [];
-  if (emit) for (const proposal of proposals) {
-    const result = runner(process.env.TOTAL_RECALL_BIN || 'total-recall', ['remember', 'fact', `${proposal.reason} ${proposal.recommendation}`, '--project', '--slug', proposal.id, '--tags', `meta-harness,${proposal.id}`], { encoding: 'utf8', timeout: 30000 });
-    const output = `${result.stdout || ''}\n${result.stderr || ''}`;
-    // The slug is the proposal's identity, so an open proposal is reported once, however often learn runs.
-    const existing = result.status !== 0 && /already exists/i.test(output);
-    emitted.push({ id: proposal.id, ok: result.status === 0 || existing, ...(existing ? { existing: true } : {}), error: result.status === 0 || existing ? undefined : String(result.stderr || result.error || 'remember failed').slice(0, 300) });
-  }
-  return { ok: emitted.every(row => row.ok), totalHistoryRuns: entries.length, scorecard, walls: activeQuotaWalls(entries), credentialBlocks: activeCredentialBlocks(entries), proposals, ...(emit ? { emitted } : {}) };
+  return { ok: true, totalHistoryRuns: entries.length, scorecard, walls: activeQuotaWalls(entries), credentialBlocks: activeCredentialBlocks(entries), proposals };
 }

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

@@ -0,0 +1,17 @@
+/** Run each maintenance owner even when another owner fails. The daemon records the result. */
+import { setupIntegrations } from './setup.mjs';
+import { maintainDocumentation } from './documentation.mjs';
+
+export async function maintainIntegrations(options = {}, owners = {}) {
+  const steps = {
+    setup: owners.setup || (() => setupIntegrations()),
+    gates: owners.gates || (async () => (await import('./gate-adapters/index.mjs')).installAll()),
+    docs: owners.docs || (() => maintainDocumentation(options)),
+  };
+  const result = {};
+  for (const [name, execute] of Object.entries(steps)) {
+    try { result[name] = await execute(); }
+    catch (error) { result[name] = { ok: false, error: error.message }; }
+  }
+  return { ...result, ok: Object.values(result).every(step => step?.ok === true) };
+}