total-recall-brain 3.44.0 → 3.45.0

package/scaffold/.agent/skills/total-recall/plugins/openwiki/cli.mjs

@@ -16,6 +16,7 @@ import { getTokenStatus, setTokenValue } from './src/token.mjs';
 import { lintWikiHubs } from './src/lint.mjs';
 import { generateWiki } from './src/generate.mjs';
 import { retrieveContext } from './src/context-provider.mjs';
+import { refreshDiagnostics } from './src/refresh-diagnostics.mjs';
 
 /**
  * Regenerate the generated pages of every registered project that carries them.
@@ -25,7 +26,14 @@ import { retrieveContext } from './src/context-provider.mjs';
  * Defaults to a report; --apply performs the refreshes, because regenerating a
  * repository's documentation is a write to that repository.
  */
-async function refreshCommand(args) {
+export async function refreshCommand(args, {
+  read = readProjects, dueFor = isDue, refresh = refreshProjectAsync,
+  getKey = resolveKey, configFor = loadOpenWikiConfig,
+} = {}) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: total-recall openwiki refresh [--repo <name>] [--apply] [--force] [--diagnostics [--slot <local-minute>]] [--json]');
+    return;
+  }
   const json = args.includes('--json');
   const apply = args.includes('--apply');
   const force = args.includes('--force');
@@ -37,7 +45,7 @@ async function refreshCommand(args) {
 
   let projects;
   try {
-    projects = readProjects();
+    projects = read();
   } catch (err) {
     if (json) console.log(JSON.stringify({ ok: false, error: err.message }));
     else console.error(`OpenWiki refresh: ${err.message}`);
@@ -52,20 +60,28 @@ async function refreshCommand(args) {
     return;
   }
 
+  if (args.includes('--diagnostics')) {
+    const slotIndex = args.indexOf('--slot');
+    const result = await refreshDiagnostics({ projects, slot: slotIndex >= 0 ? args[slotIndex + 1] : null });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
   const reports = [];
   for (const project of projects) {
     let state;
     try {
-      state = force ? { due: true, ...staleness(project.root) } : isDue(project);
+      state = dueFor(project, { force });
     } catch (err) {
-      reports.push({ ...project, action: 'skipped', reason: err.message });
+      reports.push({ ...project, action: 'failed', reason: err.message });
       continue;
     }
     if (!state.due) {
       if (state.skipped) {
         reports.push({ ...project, action: 'skipped', reason: state.reason });
       } else {
-        reports.push({ ...project, action: 'current', generatedAt: state.generatedAt, commitsSince: state.commitsSince });
+        reports.push({ ...project, action: 'current', reason: state.reason, generationCommit: state.generationCommit, generationTime: state.generationTime, generatedAt: state.generatedAt, commitsSince: state.commitsSince });
       }
       continue;
     }
@@ -73,7 +89,10 @@ async function refreshCommand(args) {
       ...project,
       action: 'due',
       uninitialized: Boolean(state.uninitialized),
+      mode: state.mode,
       generatedAt: state.generatedAt,
+      generationCommit: state.generationCommit,
+      generationTime: state.generationTime,
       commitsSince: state.commitsSince,
       reason: state.reason
     });
@@ -82,8 +101,8 @@ async function refreshCommand(args) {
   const due = reports.filter((r) => r.action === 'due');
   let payloadBudgetNote = null;
   if (apply && due.length) {
-    const config = loadOpenWikiConfig();
-    const { key, from } = resolveKey({ provider: config.provider });
+    const config = configFor();
+    const { key, from } = getKey({ provider: config.provider });
     if (!key) {
       const keyName = config.provider === 'google' ? 'GOOGLE_API_KEY' : 'OPENROUTER_API_KEY';
       const error = `No model credential for provider '${config.provider}'. Save via: total-recall auth secret set ${keyName} --stdin`;
@@ -109,20 +128,25 @@ async function refreshCommand(args) {
       while (queueIndex < due.length) {
         const itemIndex = queueIndex++;
         const entry = due[itemIndex];
-        const mode = entry.uninitialized ? 'init' : 'update';
+        const mode = entry.mode || (entry.uninitialized ? 'init' : 'update');
         if (!json) {
           console.log(`[${itemIndex + 1}/${due.length}] ▶ ${entry.name.padEnd(28)} starting ${mode}...`);
         }
-        const result = await refreshProjectAsync(
-          { name: entry.name, root: entry.root },
-          { key, model: config.model, provider: config.provider, timeoutMs: config.timeout_ms }
-        );
+        let result;
+        try {
+          result = await refresh(
+            { name: entry.name, root: entry.root },
+            { key, model: config.model, provider: config.provider, timeoutMs: config.timeout_ms }
+          );
+        } catch (error) {
+          result = { action: 'failed', reason: error.message.split(key).join('[REDACTED]') };
+        }
         completedCount++;
         const index = reports.findIndex((r) => r.root === entry.root);
         reports[index] = { ...reports[index], ...result, credential: from };
         if (!json) {
-          const duration = Math.round((Date.now() - (result.startedAt || Date.now())) / 1000);
-          const icon = result.action === 'failed' ? '✖' : '✔';
+          const duration = Math.round((result.durationMs || 0) / 1000);
+          const icon = ['failed', 'partial'].includes(result.action) ? '✖' : '✔';
           console.log(`[${completedCount}/${due.length}] ${icon} ${entry.name.padEnd(28)} ${result.action} (${duration}s)${result.reason ? ` — ${result.reason}` : ''}`);
         }
       }
@@ -133,8 +157,9 @@ async function refreshCommand(args) {
   }
 
   const failed = reports.filter((r) => r.action === 'failed');
+  const partial = reports.filter((r) => r.action === 'partial');
   const payload = {
-    ok: failed.length === 0,
+    ok: failed.length === 0 && partial.length === 0,
     applied: apply,
     retention: describeRetention(),
     note: payloadBudgetNote,
@@ -145,6 +170,8 @@ async function refreshCommand(args) {
       uninitialized: reports.filter((r) => r.uninitialized).length,
       refreshed: reports.filter((r) => r.action === 'refreshed' || r.action === 'initialized').length,
       failed: failed.length,
+      partial: partial.length,
+      skipped: reports.filter((r) => r.action === 'skipped').length,
       current: reports.filter((r) => r.action === 'current').length,
     },
     reports,
@@ -152,15 +179,17 @@ async function refreshCommand(args) {
   if (json) console.log(JSON.stringify(payload, null, 2));
   else {
     console.log(`OpenWiki refresh (${apply ? 'apply' : 'report'}): ${payload.counts.registered} registered, ${payload.counts.due} due (${payload.counts.uninitialized} uninitialized)`);
-    for (const r of reports) {
+    // Put failures last so bounded scheduler tails retain their causes.
+    for (const r of [...reports].sort((a, b) => Number(['failed', 'partial'].includes(a.action)) - Number(['failed', 'partial'].includes(b.action)))) {
       if (r.action === 'current') continue;
-      const age = r.uninitialized ? 'uninitialized' : (r.generatedAt ? `generated ${r.generatedAt.slice(0, 10)}` : 'never generated');
+      const age = r.action === 'skipped' ? 'outside repository generation' : r.generationTime ? `generated ${r.generationTime} at ${r.generationCommit}` : r.uninitialized ? 'uninitialized' : (r.generatedAt ? `last attempt ${r.generatedAt}; generation commit unknown` : 'never generated');
       console.log(`  ${r.action.padEnd(9)} ${r.name.padEnd(28)} ${age}${Number.isFinite(r.commitsSince) && r.commitsSince !== Infinity ? `, ${r.commitsSince} commits since` : ''}${r.reason ? ` — ${r.reason}` : ''}`);
     }
     if (payloadBudgetNote) console.log(payloadBudgetNote);
     if (!apply && due.length) console.log('Re-run with --apply to regenerate. Pages are a projection; vault content is never touched.');
   }
-  if (failed.length) process.exitCode = 1;
+  if (!payload.ok) process.exitCode = 1;
+  return payload;
 }
 
 async function probeCommand(args) {

package/scaffold/.agent/skills/total-recall/plugins/openwiki/package-lock.json

@@ -1,18 +1,18 @@
 {
   "name": "tr-plugin-openwiki",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-openwiki",
-      "version": "0.1.10",
+      "version": "0.1.11",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.43.3"
+        "total-recall-brain": "3.44.0"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5529,9 +5529,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.43.3",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.43.3.tgz",
-      "integrity": "sha512-yjfPN/BQxEEa+iodyFXQov/6fRt1pZg/7RcmgsbpALwBt6Ki3JJjT3tzArBC7NxHQmXgGYyKnCYId6xe/W2rPg==",
+      "version": "3.44.0",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.44.0.tgz",
+      "integrity": "sha512-VNPaIO9zsSwoxAsJ5ByIQBP9zPpLq4RiQO7Vrex4rBOHFQJT50P7utcZiLMSZTyZJU4C/m5uB8qTCSBMp6+l6Q==",
       "dev": true,
       "license": "MIT",
       "workspaces": [
@@ -5539,7 +5539,7 @@
       ],
       "dependencies": {
         "@simplewebauthn/server": "^13.3.2",
-        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.4",
+        "@ssss/cli": "npm:@gregiteen/ssss-cli@0.14.5",
         "bcrypt": "^6.0.0",
         "better-sqlite3": "^12.11.1",
         "cookie-parser": "^1.4.7",

package/scaffold/.agent/skills/total-recall/plugins/openwiki/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-openwiki",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "type": "module",
   "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall",
   "scripts": {

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

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "openwiki",
   "name": "OpenWiki",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Multi-repo knowledge graph and documentation wiki engine for Total Recall.",
   "license": "MIT",
   "runtime": {

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/refresh-diagnostics.mjs

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readProjects } from './refresh.mjs';
+
+/** Read through Total Recall's event service. Never open vault files here. */
+async function readTaskEvents(options) {
+  const service = process.env.TR_PACKAGE_ROOT
+    ? pathToFileURL(path.join(process.env.TR_PACKAGE_ROOT, 'src', 'core', 'ssss-operation-service.mjs')).href
+    : 'total-recall-brain/src/core/ssss-operation-service.mjs';
+  const { listVfsEvents } = await import(service);
+  return listVfsEvents(options);
+}
+
+export async function refreshDiagnostics({
+  projects = readProjects(),
+  vaultRoot = path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'memory-vault'),
+  listEvents = readTaskEvents,
+  slot = null,
+} = {}) {
+  let taskEvents = [], eventError = null;
+  try {
+    taskEvents = (await listEvents({ vaultRoot })).flatMap(event => {
+      let payload = event.payload || event.content;
+      if (typeof payload === 'string') {
+        try { payload = JSON.parse(payload); } catch { return []; }
+      }
+      return payload?.kind === 'plugin.task_run' && payload.plugin_id === 'openwiki' && payload.command === 'auto-refresh'
+        ? [{ at: event.timestamp || event.created_at || null, ...payload }] : [];
+    });
+  } catch (error) { eventError = error.message; }
+  taskEvents.sort((a, b) => String(a.at).localeCompare(String(b.at)));
+  taskEvents = slot ? taskEvents.filter(event => event.slot === slot) : taskEvents.slice(-1);
+  const reports = projects.map(project => {
+    const logPath = path.join(project.root, 'openwiki', '.refresh-attempt.json');
+    try { return { ...project, logPath, attempt: JSON.parse(fs.readFileSync(logPath, 'utf8')) }; }
+    catch (error) { return { ...project, logPath, attempt: null, logError: error.code === 'ENOENT' ? 'No retained generator output' : error.message }; }
+  });
+  return {
+    ok: !eventError, eventError, taskEvents, reports,
+    note: 'Task events retain only an output tail. Full legacy generator output was not saved; it cannot be reconstructed from that tail.',
+  };
+}

package/scaffold/.agent/skills/total-recall/plugins/openwiki/src/refresh.mjs

@@ -30,6 +30,19 @@ const PLUGIN_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const RETENTION_NOTE = 'pages are a projection, not canonical memory';
 const DEFAULT_LOCK_MS = 6 * 60 * 60 * 1000;
 
+const gitRun = (_command, args, options) => spawnSync('total-recall', ['git', ...args], options);
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+/** An unfinished init must resume as init, even after it has written pages. */
+export function generationMode(root) {
+  const state = readJson(path.join(root, 'openwiki', '.run.json'));
+  if (state?.mode === 'init' && state.phase && !['complete', 'idle'].includes(state.phase)) return 'init';
+  return hasWiki(root) ? 'update' : 'init';
+}
+
 export function registryPath(home = os.homedir()) {
   return path.join(home, '.agent', 'skills', 'total-recall', 'config', 'project-registry.json');
 }
@@ -69,7 +82,7 @@ export function readProjects({ registry = registryPath() } = {}) {
   });
 }
 
-/** Does this project carry generated pages at all? A repo with no openwiki/ is skipped, never created. */
+/** Does this project carry generated Markdown pages? */
 export function hasWiki(root) {
   const dir = path.join(root, 'openwiki');
   const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
@@ -82,15 +95,18 @@ export function hasWiki(root) {
  * since the recorded generation, which is the same measure the per-repo driver
  * used. Uncommitted work is not counted, so an open edit does not read as drift.
  */
-export function isGitRepo(root, { git = spawnSync } = {}) {
+export function isGitRepo(root, { git = gitRun } = {}) {
   if (fs.existsSync(path.join(root, '.git'))) return true;
   const res = git('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
-  return !res.error && res.status === 0;
+  if (res.error || res.status !== 0 || String(res.stdout).trim() !== 'true') return false;
+  const top = git('git', ['-C', root, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (top.error || top.status !== 0) return false;
+  return fs.realpathSync(root) === fs.realpathSync(String(top.stdout).trim());
 }
 
-export function staleness(root, { git = spawnSync } = {}) {
+export function staleness(root, { git = gitRun } = {}) {
   if (!isGitRepo(root, { git })) {
-    return { root, head: '', generatedAt: null, generatedStatus: null, files: null, lastCodeChange: null, commitsSince: 0, stale: false };
+    return { root, head: '', generationCommit: null, generationTime: null, generatedAt: null, generatedStatus: null, files: null, lastCodeChange: null, commitsSince: 0, stale: false };
   }
   const marker = path.join(root, 'openwiki', '.last-update.json');
   let head = '';
@@ -104,6 +120,11 @@ export function staleness(root, { git = spawnSync } = {}) {
     generatedAt = typeof parsed.updatedAt === 'string' ? parsed.updatedAt : null;
     generatedStatus = typeof parsed.status === 'string' ? parsed.status : null;
   } catch { /* no marker: never generated, or unreadable */ }
+  const receipt = readJson(path.join(root, 'openwiki', '.generation.json'));
+  const validReceipt = typeof receipt?.commit === 'string' && /^[a-f0-9]{7,64}$/i.test(receipt.commit)
+    && typeof receipt.completedAt === 'string' && Number.isFinite(Date.parse(receipt.completedAt));
+  const generationCommit = validReceipt ? receipt.commit : null;
+  const generationTime = validReceipt ? receipt.completedAt : null;
 
   // The page contents, so a refresh can be judged on what it actually rewrote.
   // openwiki writes its marker when generation begins, so the marker alone
@@ -122,12 +143,15 @@ export function staleness(root, { git = spawnSync } = {}) {
   const lastCodeChange = !log.error && log.status === 0 ? String(log.stdout || '').trim() || null : null;
 
   let commitsSince = null;
-  if (generatedAt) {
-    const count = git('git', ['-C', root, 'rev-list', '--count', `--since=${generatedAt}`, 'HEAD', '--', '.', ':!openwiki'], { encoding: 'utf8' });
-    if (!count.error && count.status === 0) commitsSince = Number(String(count.stdout || '').trim());
-  }
-  const stale = generatedAt === null || (Number.isFinite(commitsSince) && commitsSince > 0);
-  return { root, head, generatedAt, generatedStatus, files, lastCodeChange, commitsSince, stale };
+  if (generationCommit || generatedAt) {
+    const range = generationCommit ? [`${generationCommit}..HEAD`] : [`--since=${generatedAt}`, 'HEAD'];
+    const count = git('git', ['-C', root, 'rev-list', '--count', ...range, '--', '.', ':!openwiki'], { encoding: 'utf8' });
+    const value = String(count.stdout || '').trim();
+    if (!count.error && count.status === 0 && /^\d+$/.test(value)) commitsSince = Number(value);
+  }
+  const incomplete = generatedStatus === 'interrupted' || stillGenerating(root);
+  const stale = incomplete || generatedAt === null || commitsSince === null || commitsSince > 0;
+  return { root, head, generationCommit, generationTime, generatedAt, generatedStatus, files, lastCodeChange, commitsSince, stale, mode: generationMode(root) };
 }
 
 /**
@@ -250,14 +274,81 @@ export function stillGenerating(root) {
   }
 }
 
+function writeReceipt(root, name, value) {
+  const dir = path.join(root, 'openwiki');
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, name);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(tmp, target);
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+function redact(value, key) {
+  let text = String(value || '');
+  if (key) text = text.split(key).join('[REDACTED]');
+  return text.replace(/\bBearer\s+\S+/gi, 'Bearer [REDACTED]').replace(/\bsk-[\w-]+/g, '[REDACTED]');
+}
+
+function finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock }) {
+  const after = staleness(project.root, { git });
+  const exitCode = result.error ? (result.error.code || 1) : result.signal ? 1 : result.status;
+  const completedAt = new Date(clock()).toISOString();
+  const stdout = redact(result.stdout, key), stderr = redact(result.stderr, key);
+  const error = redact(result.error?.message, key);
+  const lines = `${stderr}\n${stdout}`.replace(/\x1b\[[0-9;]*m/g, '').split('\n').map(line => line.trim()).filter(Boolean);
+  const diagnostic = lines.find(line => /context_length_exceeded|Provider returned error|exited without|Could not restore|interrupted OpenWiki|fetch failed/.test(line));
+  const reason = error || (result.signal ? `terminated by ${result.signal}` : diagnostic || lines.filter(line => !/^(\[ERR\]\s*)?Error Diagnostics$/.test(line)).at(-1) || `exit ${exitCode}`);
+  const wrote = pagesWritten(before, after) || (!before.files && hasWiki(project.root) ? 1 : 0);
+  const advanced = after.generatedAt !== before.generatedAt;
+  let action, failureReason;
+  if (after.generatedStatus === 'interrupted' || stillGenerating(project.root)) {
+    action = 'partial';
+    failureReason = `${wrote} page(s) rewritten, but the run did not finish; it resumes on the next refresh (${reason})`;
+  } else if (exitCode !== 0) {
+    action = 'failed'; failureReason = reason;
+  } else if (!advanced && !wrote) {
+    action = 'failed'; failureReason = 'command exited 0 and no page changed';
+  } else if (!before.head) {
+    action = 'failed'; failureReason = 'Cannot record generation without a source commit';
+  } else {
+    action = mode === 'init' ? 'initialized' : 'refreshed';
+  }
+  const logPath = path.join(project.root, 'openwiki', '.refresh-attempt.json');
+  const report = { ...project, ...after, action, reason: failureReason, exitCode, signal: result.signal || null, from: before.generatedAt, to: after.generatedAt, durationMs: clock() - startedAt, via, mode, logPath };
+  try {
+    writeReceipt(project.root, '.refresh-attempt.json', { startedAt: new Date(startedAt).toISOString(), completedAt, sourceCommit: before.head || null, action, mode, exitCode, signal: result.signal || null, error, stdout, stderr });
+    if (action === 'initialized' || action === 'refreshed') {
+      writeReceipt(project.root, '.generation.json', { commit: before.head, completedAt });
+      report.generationCommit = before.head;
+      report.generationTime = completedAt;
+      report.commitsSince = after.head === before.head ? 0 : null;
+      report.stale = after.head !== before.head;
+    } else if (before.generationCommit && before.generationTime) {
+      // Init can replace openwiki/ before it fails. Retain the last success.
+      writeReceipt(project.root, '.generation.json', { commit: before.generationCommit, completedAt: before.generationTime });
+      report.generationCommit = before.generationCommit;
+      report.generationTime = before.generationTime;
+    }
+  } catch (error) {
+    report.action = 'failed'; report.reason = `Could not save refresh receipt: ${error.message}`;
+  }
+  return report;
+}
+
 export function refreshProject(project, {
-  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, run = spawnSync, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
+  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, run = spawnSync, now = Date.now(), clock = Date.now, targetVersion = null, pluginRoot = PLUGIN_ROOT,
 } = {}) {
-  if (!isGitRepo(project.root, { git: run })) {
+  const git = run === spawnSync ? gitRun : run;
+  if (!isGitRepo(project.root, { git })) {
     return { ...project, action: 'skipped', reason: 'not a git repository' };
   }
-  const before = staleness(project.root, { git: run });
+  const before = staleness(project.root, { git });
   const uninitialized = !hasWiki(project.root);
+  const mode = generationMode(project.root);
 
   let command = binary, args = binaryArgs, via = binary ? 'explicit' : null;
   if (!command) {
@@ -273,19 +364,12 @@ export function refreshProject(project, {
   const selectedModel = model || config.model;
   const selectedProvider = provider || config.provider;
 
-  const modeFlag = uninitialized ? '--init' : '--update';
+  const modeFlag = `--${mode}`;
   const cmdArgs = [...args, modeFlag, '-p'];
   if (selectedModel) {
     cmdArgs.push('--modelId', selectedModel);
   }
 
-  if (uninitialized) {
-    const runFile = path.join(project.root, 'openwiki', '.run.json');
-    if (fs.existsSync(runFile)) {
-      try { fs.unlinkSync(runFile); } catch {}
-    }
-  }
-
   const childEnv = { ...process.env };
   if (selectedProvider === 'google') {
     childEnv.GOOGLE_API_KEY = key;
@@ -312,47 +396,18 @@ export function refreshProject(project, {
     timeout: timeoutMs,
   });
 
-  const after = staleness(project.root, { git: run });
-  const exitCode = result.error ? (result.error.code || 1) : result.status;
-  const advanced = after.generatedAt !== before.generatedAt || (uninitialized && hasWiki(project.root));
-  const wrote = pagesWritten(before, after) || (uninitialized && hasWiki(project.root) ? 1 : 0);
-
-  const outcome = after.generatedStatus === 'interrupted' || stillGenerating(project.root)
-    ? 'partial'
-    : (advanced ? (uninitialized ? 'initialized' : 'refreshed') : 'unchanged');
-
-  if (exitCode !== 0 && !wrote) {
-    return { ...project, action: 'failed', reason: result.error?.message || `exit ${exitCode}`, exitCode, ...after };
-  }
-  if (!advanced && !wrote) {
-    return { ...project, action: 'failed', reason: `command exited ${exitCode} and no page changed`, exitCode, ...after };
-  }
-  if (outcome === 'partial') {
-    return {
-      ...project,
-      action: 'partial',
-      reason: `${wrote} page(s) rewritten, but the run did not finish (the generator was cut off); it resumes on the next refresh`,
-      exitCode,
-      from: before.generatedAt,
-      to: after.generatedAt,
-      via,
-      ...after,
-    };
-  }
-  if (exitCode !== 0) {
-    return { ...project, action: 'failed', reason: result.error?.message || `exit ${exitCode}`, exitCode, ...after };
-  }
-  return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
+  return finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock });
 }
 
 export async function refreshProjectAsync(project, {
-  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, now = Date.now(), targetVersion = null, pluginRoot = PLUGIN_ROOT,
+  key, model = null, provider = null, binary = null, binaryArgs = [], timeoutMs = 30 * 60 * 1000, now = Date.now(), clock = Date.now, targetVersion = null, pluginRoot = PLUGIN_ROOT, git = gitRun, spawnProcess = spawn,
 } = {}) {
-  if (!isGitRepo(project.root, { git: spawnSync })) {
+  if (!isGitRepo(project.root, { git })) {
     return { ...project, action: 'skipped', reason: 'not a git repository' };
   }
-  const before = staleness(project.root, { git: spawnSync });
+  const before = staleness(project.root, { git });
   const uninitialized = !hasWiki(project.root);
+  const mode = generationMode(project.root);
   let command = binary, args = binaryArgs, via = binary ? 'explicit' : null;
   if (!command) {
     const resolved = resolveGenerator({ run: spawnSync, targetVersion, pluginRoot, requireBundled: uninitialized });
@@ -367,19 +422,12 @@ export async function refreshProjectAsync(project, {
   const selectedModel = model || config.model;
   const selectedProvider = provider || config.provider;
 
-  const modeFlag = uninitialized ? '--init' : '--update';
+  const modeFlag = `--${mode}`;
   const cmdArgs = [...args, modeFlag, '-p'];
   if (selectedModel) {
     cmdArgs.push('--modelId', selectedModel);
   }
 
-  if (uninitialized) {
-    const runFile = path.join(project.root, 'openwiki', '.run.json');
-    if (fs.existsSync(runFile)) {
-      try { fs.unlinkSync(runFile); } catch {}
-    }
-  }
-
   const childEnv = { ...process.env };
   if (selectedProvider === 'google') {
     childEnv.GOOGLE_API_KEY = key;
@@ -399,74 +447,33 @@ export async function refreshProjectAsync(project, {
 
   const startedAt = now;
   const result = await new Promise((resolve) => {
-    const proc = spawn(command, cmdArgs, {
+    const proc = spawnProcess(command, cmdArgs, {
       cwd: project.root,
       env: childEnv,
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: timeoutMs,
     });
-    let stdout = '', stderr = '';
+    let stdout = '', stderr = '', error = null;
     proc.stdout?.on('data', (d) => { stdout += d; });
     proc.stderr?.on('data', (d) => { stderr += d; });
-    proc.on('error', (err) => resolve({ error: err, status: 1, stdout, stderr }));
-    proc.on('close', (status) => resolve({ status: status ?? 0, stdout, stderr }));
+    proc.on('error', (err) => { error = err; });
+    proc.on('close', (status, signal) => resolve({ error, status, signal, stdout, stderr }));
   });
-
-  const after = staleness(project.root, { git: spawnSync });
-  const exitCode = result.error ? (result.error.code || 1) : result.status;
-  const advanced = after.generatedAt !== before.generatedAt || (uninitialized && hasWiki(project.root));
-  const wrote = pagesWritten(before, after) || (uninitialized && hasWiki(project.root) ? 1 : 0);
-
-  const outcome = after.generatedStatus === 'interrupted' || stillGenerating(project.root)
-    ? 'partial'
-    : (advanced ? (uninitialized ? 'initialized' : 'refreshed') : 'unchanged');
-
-  const extractReason = (rawErr, rawOut) => {
-    if (result.error?.message) return result.error.message;
-    const combined = `${rawErr || ''}\n${rawOut || ''}`.trim();
-    if (!combined) return `exit ${exitCode}`;
-    const lines = combined.split('\n').map((l) => l.trim()).filter(Boolean);
-    const diag = lines.find((l) => l.includes('Error Diagnostics') || l.includes('exited without') || l.includes('Could not restore') || l.includes('Provider returned error') || l.includes('fetch failed'));
-    if (diag) return diag.replace(/^\[ERR\]\s*/, '');
-    const last = lines[lines.length - 1];
-    return last ? last.replace(/^\[ERR\]\s*/, '') : `exit ${exitCode}`;
-  };
-  const failReason = extractReason(result.stderr, result.stdout);
-
-  if (exitCode !== 0 && !wrote) {
-    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
-  }
-  if (!advanced && !wrote) {
-    return { ...project, action: 'failed', reason: failReason || `command exited ${exitCode} and no page changed`, exitCode, ...after };
-  }
-  if (outcome === 'partial') {
-    return {
-      ...project,
-      action: 'partial',
-      reason: `${wrote} page(s) rewritten, but the run did not finish (the generator was cut off); it resumes on the next refresh`,
-      exitCode,
-      from: before.generatedAt,
-      to: after.generatedAt,
-      via,
-      ...after,
-    };
-  }
-  if (exitCode !== 0) {
-    return { ...project, action: 'failed', reason: failReason, exitCode, ...after };
-  }
-  return { ...project, action: uninitialized ? 'initialized' : 'refreshed', from: before.generatedAt, to: after.generatedAt, durationMs: Date.now() - startedAt, via, ...after };
+  return finishRefresh(project, { before, result, git, key, mode, startedAt, via, clock });
 }
 
 /** Is a refresh due for this project under the configured interval? */
-export function isDue(project, { lockMs = DEFAULT_LOCK_MS, now = Date.now(), git = spawnSync } = {}) {
+export function isDue(project, { lockMs = DEFAULT_LOCK_MS, now = Date.now(), git = gitRun, force = false } = {}) {
   if (!isGitRepo(project.root, { git })) {
     return { due: false, skipped: true, reason: 'not a git repository' };
   }
   const state = staleness(project.root, { git });
+  if (force) return { due: true, uninitialized: !hasWiki(project.root), ...state };
   if (!hasWiki(project.root)) {
     return { due: true, uninitialized: true, reason: 'uninitialized (missing openwiki/ pages)', ...state };
   }
   if (!state.stale) return { due: false, ...state };
+  if (state.generatedStatus === 'interrupted' || stillGenerating(project.root)) return { due: true, reason: 'resume incomplete generation', ...state };
   if (state.generatedAt) {
     const at = Date.parse(state.generatedAt);
     if (Number.isFinite(at) && now - at < lockMs) return { due: false, reason: 'refreshed recently', ...state };