dual-brain 0.1.0

package/src/health.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * health.mjs — Reactive provider health tracking for the Dual-Brain Orchestrator.
+ *
+ * Replaces budget-pressure estimation with real cooldown state persisted to
+ * .dualbrain/health.json.  No external dependencies.
+ *
+ * Exports: getHealth, markHot, markDegraded, markHealthy, checkCooldown,
+ *          getProviderScore, recordDispatch, getSessionStats, resetHealth
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HEALTH_FILE = '.dualbrain/health.json';
+
+// Cooldown ladder in minutes: index = attempts - 1, capped at last entry
+const COOLDOWN_LADDER = [5, 15, 45];
+// Window in which repeated hot marks escalate the ladder (ms)
+const ESCALATION_WINDOW_MS = 2 * 60 * 60 * 1000;
+
+// ─── File I/O ────────────────────────────────────────────────────────────────
+
+function healthPath(cwd) {
+  return join(cwd ?? process.cwd(), HEALTH_FILE);
+}
+
+function loadRaw(cwd) {
+  const p = healthPath(cwd);
+  if (!existsSync(p)) return { states: {}, session: null };
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return { states: {}, session: null }; }
+}
+
+function saveRaw(data, cwd) {
+  const p = healthPath(cwd);
+  mkdirSync(join(cwd ?? process.cwd(), '.dualbrain'), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function key(provider, modelClass) {
+  return `${provider}:${modelClass}`;
+}
+
+// ─── Session helpers ──────────────────────────────────────────────────────────
+
+function ensureSession(data) {
+  if (!data.session || typeof data.session !== 'object') {
+    data.session = { startedAt: new Date().toISOString(), dispatches: [] };
+  }
+  if (!Array.isArray(data.session.dispatches)) data.session.dispatches = [];
+  return data;
+}
+
+// ─── Exported: getHealth ─────────────────────────────────────────────────────
+
+/**
+ * Return the raw health data (states + session).
+ * @param {string} [cwd]
+ * @returns {{ states: object, session: object }}
+ */
+export function getHealth(cwd) {
+  return loadRaw(cwd);
+}
+
+// ─── Exported: markHot ───────────────────────────────────────────────────────
+
+/**
+ * Mark a provider+model as hot (rate-limited).  Escalates cooldown on repeat.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ */
+export function markHot(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  const existing = data.states[k] ?? {};
+  const now = Date.now();
+
+  // Count how many times this was already marked hot within the escalation window
+  let attempts = (existing.attempts ?? 0);
+  const sinceMs = existing.since ? now - Date.parse(existing.since) : Infinity;
+  if (sinceMs < ESCALATION_WINDOW_MS && existing.status === 'hot') {
+    attempts += 1;
+  } else if (existing.status !== 'hot') {
+    // First time hot (or was healthy/probing before): reset counter to 1
+    attempts = 1;
+  }
+  // Clamp to ladder length
+  const ladderIdx = Math.min(attempts - 1, COOLDOWN_LADDER.length - 1);
+  const cooldownMinutes = COOLDOWN_LADDER[ladderIdx];
+
+  data.states[k] = {
+    status: 'hot',
+    since: new Date().toISOString(),
+    cooldownMinutes,
+    attempts,
+  };
+  saveRaw(data, cwd);
+}
+
+// ─── Exported: markDegraded ──────────────────────────────────────────────────
+
+/**
+ * Signal soft degradation (slow responses, elevated errors) without full cooldown.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ */
+export function markDegraded(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  // Only downgrade if currently healthy or probing — never upgrade from hot
+  if (!data.states[k] || ['healthy', 'probing'].includes(data.states[k].status)) {
+    data.states[k] = { status: 'degraded', since: new Date().toISOString() };
+    saveRaw(data, cwd);
+  }
+}
+
+// ─── Exported: markHealthy ───────────────────────────────────────────────────
+
+/**
+ * Clear hot/degraded state and reset attempt counter.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ */
+export function markHealthy(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  data.states[k] = { status: 'healthy', since: new Date().toISOString() };
+  saveRaw(data, cwd);
+}
+
+// ─── Exported: checkCooldown ─────────────────────────────────────────────────
+
+/**
+ * Returns true if the cooldown for a hot provider+model has expired.
+ * Side-effect: transitions status from 'hot' to 'probing' when expired.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ * @returns {boolean} true = cooldown expired, ready to probe
+ */
+export function checkCooldown(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  const state = data.states[k];
+  if (!state || state.status !== 'hot') return true; // not hot → no cooldown
+
+  const sinceMs = Date.parse(state.since);
+  const cooldownMs = (state.cooldownMinutes ?? 5) * 60 * 1000;
+  const expired = Date.now() - sinceMs >= cooldownMs;
+
+  if (expired) {
+    // Transition to probing
+    data.states[k] = { ...state, status: 'probing', probingAt: new Date().toISOString() };
+    saveRaw(data, cwd);
+    return true;
+  }
+  return false;
+}
+
+// ─── Exported: getProviderScore ──────────────────────────────────────────────
+
+/**
+ * Returns a 0-100 routing preference score for a provider+model.
+ * healthy=100, degraded=50, probing=25, hot=0
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ * @returns {number}
+ */
+export function getProviderScore(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  const state = data.states[k];
+  if (!state) return 100;
+  switch (state.status) {
+    case 'healthy':  return 100;
+    case 'degraded': return 50;
+    case 'probing':  return 25;
+    case 'hot':      return 0;
+    default:         return 100;
+  }
+}
+
+// ─── Exported: recordDispatch ────────────────────────────────────────────────
+
+/**
+ * Log a successful dispatch for session tracking.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {number} tokens
+ * @param {string} [cwd]
+ */
+export function recordDispatch(provider, modelClass, tokens, cwd) {
+  const data = ensureSession(loadRaw(cwd));
+  data.session.dispatches.push({
+    provider,
+    model: modelClass,
+    tokens: tokens ?? 0,
+    at: new Date().toISOString(),
+  });
+  saveRaw(data, cwd);
+}
+
+// ─── Exported: getSessionStats ───────────────────────────────────────────────
+
+/**
+ * Return per-provider aggregated call + token counts for the current session.
+ * @param {string} [cwd]
+ * @returns {{ [provider: string]: { calls: number, tokens: number } }}
+ */
+export function getSessionStats(cwd) {
+  const { session } = loadRaw(cwd);
+  const stats = {};
+  for (const d of (session?.dispatches ?? [])) {
+    if (!stats[d.provider]) stats[d.provider] = { calls: 0, tokens: 0 };
+    stats[d.provider].calls  += 1;
+    stats[d.provider].tokens += (d.tokens ?? 0);
+  }
+  return stats;
+}
+
+// ─── Exported: resetHealth ───────────────────────────────────────────────────
+
+/**
+ * Wipe all health state (states + session).
+ * @param {string} [cwd]
+ */
+export function resetHealth(cwd) {
+  saveRaw({ states: {}, session: null }, cwd);
+}
+
+// ─── Remaining cooldown helper (used by status display) ──────────────────────
+
+/**
+ * Returns remaining cooldown in minutes for a hot provider+model, or 0.
+ * @param {string} provider
+ * @param {string} modelClass
+ * @param {string} [cwd]
+ * @returns {number}
+ */
+export function remainingCooldownMinutes(provider, modelClass, cwd) {
+  const data = loadRaw(cwd);
+  const k = key(provider, modelClass);
+  const state = data.states[k];
+  if (!state || state.status !== 'hot') return 0;
+  const elapsedMs = Date.now() - Date.parse(state.since);
+  const cooldownMs = (state.cooldownMinutes ?? 5) * 60 * 1000;
+  const remaining = cooldownMs - elapsedMs;
+  return remaining > 0 ? Math.ceil(remaining / 60_000) : 0;
+}

package/src/index.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * index.mjs — Main entry point for the dual-brain package.
+ *
+ * Re-exports all public APIs from the four core modules, plus a top-level
+ * orchestrate() convenience function for programmatic use.
+ */
+
+export { loadProfile, saveProfile, ensureProfile, runOnboarding, rememberPreference, forgetPreference, getActivePreferences, getAvailableProviders, isSoloBrain, getHeadModel, detectAuth, detectEnvironment, saveSubscription, listSubscriptions, autoRefreshToken } from './profile.mjs';
+export { detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths } from './detect.mjs';
+export { decideRoute, getModelCapabilities, getAvailableModels, shouldDualBrain, explainDecision } from './decide.mjs';
+export { dispatch, buildCommand, detectRuntime, compressResult, dispatchDualBrain } from './dispatch.mjs';
+export { loadPlaybook, listPlaybooks, executePlaybook, createRunArtifact } from './playbook.mjs';
+export { getHealth, markHot, markDegraded, markHealthy, checkCooldown, getProviderScore, recordDispatch, getSessionStats, resetHealth, remainingCooldownMinutes } from './health.mjs';
+export { detectRepo, loadRepoCache, getTestCommand, getLintCommand } from './repo.mjs';
+export { loadSession, saveSession, updateSession, clearSession, formatSessionCard, importReplitSessions, renameSession, pinSession, unpinSession, categorizeSession, getSessionMeta, autoLabel, enrichSessions, ensurePersistence, syncSessionMirror, buildSessionIndex, searchSessions, getSessionContext } from './session.mjs';
+export { decompose, isSimpleTask, taskGraphToWaves } from './decompose.mjs';
+export { generateBrief, compressPriorResults, listRoles } from './brief.mjs';
+export { redact, redactFiles, isSecretFile } from './redact.mjs';
+export { isInsideClaude, buildNativeDispatch, normalizeResult } from './dispatch.mjs';
+export { box, bar, badge, menu, separator } from './tui.mjs';
+
+// Top-level convenience function
+export async function orchestrate({ prompt, files, cwd, dryRun }) {
+  // Import dynamically to avoid circular issues
+  const { ensureProfile } = await import('./profile.mjs');
+  const { detectTask } = await import('./detect.mjs');
+  const { decideRoute } = await import('./decide.mjs');
+  const { dispatch: run, dispatchDualBrain } = await import('./dispatch.mjs');
+
+  const profile = await ensureProfile(cwd || process.cwd(), { interactive: false });
+  const detection = detectTask({ prompt, files });
+  const decision = decideRoute({ profile, detection, cwd: cwd || process.cwd() });
+
+  if (dryRun) {
+    return { profile, detection, decision, result: null };
+  }
+
+  const result = decision.dualBrain
+    ? await dispatchDualBrain({ decision, prompt, files, cwd: cwd || process.cwd() })
+    : await run({ decision, prompt, files, cwd: cwd || process.cwd() });
+
+  return { profile, detection, decision, result };
+}

package/src/install-hooks.mjs

@@ -0,0 +1,100 @@
+/**
+ * install-hooks.mjs — Merge dual-brain PreToolUse hooks into .claude/settings.json.
+ *
+ * Exported function: installHooks(cwd)
+ * Returns: { installed: string[], skipped: string[] }
+ */
+
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+const PKG_ROOT   = join(__dirname, '..');
+
+// The hook commands we want present in .claude/settings.json PreToolUse
+const HEAD_GUARD_CMD   = 'node .claude/hooks/head-guard.mjs';
+const ENFORCE_TIER_CMD = 'node .claude/hooks/enforce-tier.mjs';
+
+const DESIRED_HOOKS = [
+  { matcher: 'Edit',         command: HEAD_GUARD_CMD },
+  { matcher: 'Write',        command: HEAD_GUARD_CMD },
+  { matcher: 'NotebookEdit', command: HEAD_GUARD_CMD },
+  { matcher: 'Bash',         command: HEAD_GUARD_CMD },
+  { matcher: 'Agent',        command: ENFORCE_TIER_CMD },
+];
+
+/**
+ * Install dual-brain enforcement hooks into a project's .claude/settings.json.
+ *
+ * @param {string} cwd - Project root directory (where .claude/ should live)
+ * @returns {{ installed: string[], skipped: string[] }}
+ */
+export function installHooks(cwd) {
+  const claudeDir    = join(cwd, '.claude');
+  const hooksDir     = join(claudeDir, 'hooks');
+  const settingsPath = join(claudeDir, 'settings.json');
+
+  const installed = [];
+  const skipped   = [];
+
+  // Ensure directories exist
+  mkdirSync(hooksDir, { recursive: true });
+
+  // Copy hook files from package into project's .claude/hooks/
+  const filesToCopy = [
+    { name: 'head-guard.mjs',   exec: true },
+    { name: 'enforce-tier.mjs', exec: false },
+  ];
+
+  for (const { name, exec } of filesToCopy) {
+    const src = join(PKG_ROOT, 'hooks', name);
+    const dst = join(hooksDir, name);
+    if (existsSync(src)) {
+      cpSync(src, dst);
+      if (exec) {
+        try { chmodSync(dst, 0o755); } catch {}
+      }
+      installed.push(`hooks/${name}`);
+    }
+  }
+
+  // Read existing settings (or start fresh)
+  let settings = {};
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  } catch {
+    // File doesn't exist or is malformed — start empty
+  }
+
+  // Ensure hooks.PreToolUse array exists
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+  const preToolUse = settings.hooks.PreToolUse;
+
+  // Merge: for each desired hook, add only if command is not already registered for that matcher
+  for (const { matcher, command } of DESIRED_HOOKS) {
+    const alreadyPresent = preToolUse.some(entry =>
+      entry.matcher === matcher &&
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some(h => h.command === command)
+    );
+
+    if (alreadyPresent) {
+      skipped.push(`PreToolUse[${matcher}]`);
+    } else {
+      preToolUse.push({
+        matcher,
+        hooks: [{ type: 'command', command }],
+      });
+      installed.push(`PreToolUse[${matcher}]`);
+    }
+  }
+
+  // Write back merged settings
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  return { installed, skipped };
+}

package/src/playbook.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * playbook.mjs — Playbook loader and executor for the Dual-Brain Orchestrator.
+ *
+ * Exports:
+ *   loadPlaybook(intent, cwd)           → playbook object | null
+ *   listPlaybooks(cwd)                  → [{ name, source, stepCount }]
+ *   executePlaybook(playbook, context)  → { steps, summary, runId }
+ *   createRunArtifact(runId, results, cwd) → artifact path
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+import { loadProfile } from './profile.mjs';
+import { decideRoute, shouldDualBrain } from './decide.mjs';
+import { dispatch, dispatchDualBrain } from './dispatch.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUILTIN_DIR = join(__dirname, '..', 'playbooks');
+const GLOBAL_DIR  = join(homedir(), '.config', 'dual-brain', 'playbooks');
+
+// ─── Playbook resolution helpers ─────────────────────────────────────────────
+
+function projectDir(cwd) {
+  return join(cwd || process.cwd(), '.dualbrain', 'playbooks');
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+function playbookPath(dir, intent) {
+  return join(dir, `${intent}.json`);
+}
+
+// ─── Exported: loadPlaybook ───────────────────────────────────────────────────
+
+/**
+ * Find and return a playbook matching the given intent.
+ * Search order: project-local → global user → built-in.
+ * Returns null if no match found.
+ * @param {string} intent
+ * @param {string} [cwd]
+ * @returns {object|null}
+ */
+export function loadPlaybook(intent, cwd) {
+  if (!intent) return null;
+
+  const candidates = [
+    { dir: projectDir(cwd), source: 'project' },
+    { dir: GLOBAL_DIR,      source: 'global'  },
+    { dir: BUILTIN_DIR,     source: 'builtin' },
+  ];
+
+  for (const { dir, source } of candidates) {
+    const path = playbookPath(dir, intent);
+    if (existsSync(path)) {
+      const pb = readJson(path);
+      if (pb) return { ...pb, _source: source, _path: path };
+    }
+  }
+
+  return null;
+}
+
+// ─── Exported: listPlaybooks ──────────────────────────────────────────────────
+
+/**
+ * Return all available playbooks across all sources, deduped (project wins).
+ * @param {string} [cwd]
+ * @returns {{ name: string, source: string, stepCount: number }[]}
+ */
+export function listPlaybooks(cwd) {
+  const seen = new Map(); // name → entry (first write wins: project > global > builtin)
+
+  const sources = [
+    { dir: projectDir(cwd), source: 'project' },
+    { dir: GLOBAL_DIR,      source: 'global'  },
+    { dir: BUILTIN_DIR,     source: 'builtin' },
+  ];
+
+  for (const { dir, source } of sources) {
+    if (!existsSync(dir)) continue;
+    let files;
+    try { files = readdirSync(dir); } catch { continue; }
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      const name = basename(file, '.json');
+      if (seen.has(name)) continue; // project-local already registered
+      const pb = readJson(join(dir, file));
+      if (!pb) continue;
+      seen.set(name, {
+        name: pb.name ?? name,
+        source,
+        stepCount: Array.isArray(pb.steps) ? pb.steps.length : 0,
+      });
+    }
+  }
+
+  return [...seen.values()];
+}
+
+// ─── Exported: createRunArtifact ─────────────────────────────────────────────
+
+/**
+ * Persist a run manifest under .dualbrain/runs/<runId>/manifest.json.
+ * @param {string} runId
+ * @param {object[]} results  — step result objects
+ * @param {string} [cwd]
+ * @returns {string} path to the manifest file
+ */
+export function createRunArtifact(runId, results, cwd) {
+  const dir = join(cwd || process.cwd(), '.dualbrain', 'runs', runId);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'manifest.json');
+  const manifest = {
+    runId,
+    createdAt: new Date().toISOString(),
+    stepCount: results.length,
+    steps: results,
+  };
+  writeFileSync(path, JSON.stringify(manifest, null, 2));
+  return path;
+}
+
+// ─── Step prompt builder ──────────────────────────────────────────────────────
+
+function buildStepPrompt(step, priorOutputs, basePrompt) {
+  const parts = [];
+
+  if (basePrompt) parts.push(`Context: ${basePrompt}`);
+
+  if (priorOutputs.length > 0) {
+    parts.push('Prior step results:');
+    for (const prior of priorOutputs) {
+      parts.push(`  [${prior.stepId}] ${prior.summary ?? '(no output)'}`);
+    }
+  }
+
+  parts.push(`\nCurrent task — ${step.title}: ${step.goal}`);
+
+  if (step.output?.kind) {
+    parts.push(`Expected output format: ${step.output.kind}`);
+  }
+
+  return parts.join('\n');
+}
+
+// ─── Exported: executePlaybook ────────────────────────────────────────────────
+
+/**
+ * Execute all steps in a playbook sequentially, feeding prior outputs forward.
+ * @param {object} playbook
+ * @param {{ profile?: object, prompt?: string, files?: string[], cwd?: string, dryRun?: boolean, verbose?: boolean }} context
+ * @returns {Promise<{ steps: object[], summary: string, runId: string }>}
+ */
+export async function executePlaybook(playbook, context = {}) {
+  const {
+    prompt = '',
+    files  = [],
+    cwd    = process.cwd(),
+    dryRun = false,
+    verbose = false,
+  } = context;
+
+  let { profile } = context;
+  if (!profile) {
+    try { profile = await loadProfile(cwd); } catch { profile = {}; }
+  }
+
+  const runId      = randomUUID();
+  const steps      = playbook.steps ?? [];
+  const results    = [];
+  const priorOuts  = [];
+
+  if (verbose) {
+    console.log(`[playbook] Starting "${playbook.name}" — ${steps.length} steps (runId: ${runId})`);
+  }
+
+  for (const step of steps) {
+    const stepPrompt = buildStepPrompt(step, priorOuts, prompt);
+
+    // Build synthetic detection that respects the step's declared tier
+    const detection = {
+      intent:     step.tier === 'think'  ? 'architecture'
+                : step.tier === 'search' ? 'search'
+                : 'edit',
+      tier:       step.tier ?? 'execute',
+      risk:       'medium',
+      complexity: 'moderate',
+      effort:     'medium',
+    };
+
+    // Force dual-brain if step declares consensus:true OR risk warrants it
+    const forceDual = step.consensus === true || shouldDualBrain(detection, profile);
+    const decision  = decideRoute({ profile, detection, cwd });
+    if (forceDual) decision.dualBrain = true;
+
+    if (verbose) {
+      const mode = forceDual ? 'dual-brain' : `${decision.provider}/${decision.model}`;
+      console.log(`[playbook] Step "${step.id}" → ${mode} (${decision.tier})`);
+    }
+
+    // Gate: log and continue (blocking gates are a future concern)
+    if (step.gate) {
+      console.log(`[playbook] Gate "${step.gate}" — checking (non-blocking in this version)`);
+    }
+
+    let result;
+    try {
+      if (forceDual) {
+        result = await dispatchDualBrain({ decision, prompt: stepPrompt, files, cwd, dryRun });
+        result = {
+          status:   result.consensus === 'both-failed' ? 'failed' : 'completed',
+          summary:  result.claude?.summary ?? result.openai?.summary ?? '(dual-brain)',
+          dualBrain: result,
+        };
+      } else {
+        result = await dispatch({ decision, prompt: stepPrompt, files, cwd, dryRun });
+      }
+    } catch (err) {
+      result = { status: 'error', summary: err.message, error: err.message };
+    }
+
+    const stepResult = {
+      stepId:   step.id,
+      title:    step.title,
+      tier:     step.tier ?? 'execute',
+      dualBrain: forceDual,
+      status:   result.status,
+      summary:  result.summary ?? null,
+      error:    result.error ?? null,
+    };
+
+    results.push(stepResult);
+    priorOuts.push({ stepId: step.id, summary: result.summary });
+
+    if (verbose) {
+      console.log(`[playbook]   → ${stepResult.status}: ${stepResult.summary ?? stepResult.error}`);
+    }
+  }
+
+  const passed  = results.filter(r => r.status === 'completed' || r.status === 'dry-run').length;
+  const failed  = results.filter(r => r.status === 'failed' || r.status === 'error').length;
+  const summary = `Playbook "${playbook.name}" finished: ${passed}/${steps.length} steps passed${failed ? `, ${failed} failed` : ''}.`;
+
+  if (!dryRun) {
+    try { createRunArtifact(runId, results, cwd); } catch {}
+  }
+
+  return { steps: results, summary, runId };
+}