@thispointon/kondi-chat 0.1.2

package/src/engine/permissions.ts

@@ -0,0 +1,293 @@
+/**
+ * Permission System — safety gate in front of every tool execution.
+ *
+ * Tiers:
+ *   - auto-approve   : execute immediately
+ *   - confirm        : ask the user once; may be escalated to session-approve
+ *   - always-confirm : ask every time, cannot be auto-approved from config
+ *
+ * The backend calls `check()` to classify, then `requestPermission()` to
+ * emit a `permission_request` to the TUI and await a response. Responses
+ * come back through `handleResponse()` from the TUI's `permission_response`.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+export type PermissionTier = 'auto-approve' | 'confirm' | 'always-confirm';
+export type PermissionDecision = 'approved' | 'denied' | 'approved-session' | 'approved-turn';
+
+export interface PermissionConfig {
+  defaultTier: PermissionTier;
+  tools: Record<string, PermissionTier>;
+  alwaysConfirmPatterns: string[];
+  sessionOverrides?: Record<string, PermissionTier>;
+}
+
+const DEFAULT_TOOL_TIERS: Record<string, PermissionTier> = {
+  read_file: 'auto-approve',
+  list_files: 'auto-approve',
+  search_code: 'auto-approve',
+  update_plan: 'auto-approve',
+  write_file: 'confirm',
+  edit_file: 'confirm',
+  run_command: 'confirm',
+  create_task: 'confirm',
+  update_memory: 'confirm',
+  git_status: 'auto-approve',
+  git_diff: 'auto-approve',
+  git_log: 'auto-approve',
+  git_commit: 'confirm',
+  git_branch: 'confirm',
+  git_create_pr: 'confirm',
+  spawn_agent: 'confirm',
+  web_search: 'auto-approve',
+  web_fetch: 'confirm',
+};
+
+const DEFAULT_ALWAYS_CONFIRM_PATTERNS: string[] = [
+  'rm\\s+(-[rfR]+\\s+|--recursive)',
+  'git\\s+push\\s+(-f|--force|--force-with-lease)',
+  'git\\s+push\\s+.*\\b(main|master)\\b',
+  'git\\s+reset\\s+--hard',
+  'chmod\\s+(777|000)',
+  'sudo(\\s|$)',
+  'curl.*\\|\\s*(sh|bash)',
+  'wget.*\\|\\s*(sh|bash)',
+  'dd\\s+',
+  '>\\s*/dev/',
+  // Write/redirect to system dirs
+  '>\\s*(/etc|/usr|/bin|/sbin|/boot|/root|~)',
+  // Crypto/secret exfil vectors
+  '(ssh-keygen|openssl)\\s+.*\\bprivate\\b',
+];
+
+/**
+ * Shell compound/chaining operators that let a caller append arbitrary
+ * follow-up commands. When `run_command` is classified as `auto-approve`
+ * and the command string contains any of these, we force an upgrade to
+ * `confirm` so a human sees the chain before it runs. This closes the
+ * "auto-approve `npm test` then `&& rm -rf ~`" gap.
+ *
+ * Detection is textual on purpose — anything short of a full shell AST
+ * parse has edge cases (e.g. `echo "a && b"` contains `&&` inside a
+ * quoted string). We accept the false-positive rate here: at worst the
+ * user sees a confirm dialog for a command that was actually safe, and
+ * can approve it. The alternative — shipping a production shell parser —
+ * is a much bigger maintenance surface.
+ */
+const SHELL_CHAIN_OPERATORS: RegExp = /(&&|\|\||;|\||`|\$\(|>>|\bxargs\b|\beval\b)/;
+
+/**
+ * Public predicate so wrappers that *force* a result to `auto-approve`
+ * (e.g. the `--auto-approve run_command` CLI flag) can re-apply the
+ * chain-operator gate themselves. Without this, a CLI allow-list would
+ * silently bypass `check()`'s upgrade to `confirm` because the wrapper
+ * overrides the resolved tier after `check()` returns.
+ */
+export function hasShellChainOperator(command: string): boolean {
+  return SHELL_CHAIN_OPERATORS.test(normalizeCommand(command));
+}
+
+const DEFAULT_CONFIG: PermissionConfig = {
+  defaultTier: 'confirm',
+  tools: { ...DEFAULT_TOOL_TIERS },
+  alwaysConfirmPatterns: DEFAULT_ALWAYS_CONFIRM_PATTERNS,
+};
+
+// Permission dialogs wait indefinitely — the user responds when ready.
+// No auto-deny timeout; the TUI keeps the dialog visible until dismissed.
+const REQUEST_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24h (effectively forever)
+
+interface Pending {
+  resolve: (d: PermissionDecision) => void;
+  timeout: NodeJS.Timeout;
+}
+
+function fingerprint(tool: string, args: Record<string, unknown>): string {
+  // Stable JSON by sorted keys
+  const keys = Object.keys(args).sort();
+  const normalized: Record<string, unknown> = {};
+  for (const k of keys) normalized[k] = args[k];
+  const s = tool + '::' + JSON.stringify(normalized);
+  return createHash('sha1').update(s).digest('hex').slice(0, 16);
+}
+
+export class PermissionManager {
+  private config: PermissionConfig;
+  private skip: boolean;
+  private patterns: RegExp[];
+  private pending = new Map<string, Pending>();
+  /** Session approvals: fingerprint -> approved */
+  private sessionApprovals = new Set<string>();
+  /** Auto-generated sequential id */
+  private nextId = 0;
+  /**
+   * Yolo-for-this-turn: approve every confirm-tier tool call until the
+   * backend declares the turn over via endTurn(). always-confirm tools
+   * (rm -rf, sudo, force-push to main, …) are NEVER bypassed.
+   */
+  private turnApproveAll = false;
+
+  constructor(configPath: string, skipPermissions = false, userConfigPath?: string) {
+    this.skip = skipPermissions;
+    // Load user-level permissions as the base, then merge any explicit
+    // project-level overrides on top. Projects that don't have a
+    // permissions.json get the user-level settings (auto-approve etc.)
+    // without any hardcoded defaults overriding them. `userConfigPath` is
+    // an injection point used by tests to keep the developer's actual
+    // ~/.kondi-chat/permissions.json from leaking into the test config.
+    const resolvedUserPath = userConfigPath ?? join(homedir(), '.kondi-chat', 'permissions.json');
+    const userConfig = loadConfig(resolvedUserPath);
+    const projectConfig = loadConfig(configPath);
+    // Use DEFAULT_CONFIG as the ultimate fallback if neither user nor project has settings.
+    this.config = {
+      defaultTier: projectConfig.defaultTier || userConfig.defaultTier || DEFAULT_CONFIG.defaultTier,
+      tools: { ...DEFAULT_TOOL_TIERS, ...userConfig.tools, ...projectConfig.tools },
+      alwaysConfirmPatterns: projectConfig.alwaysConfirmPatterns.length > 0
+        ? projectConfig.alwaysConfirmPatterns
+        : userConfig.alwaysConfirmPatterns.length > 0
+          ? userConfig.alwaysConfirmPatterns
+          : DEFAULT_ALWAYS_CONFIRM_PATTERNS,
+      sessionOverrides: projectConfig.sessionOverrides,
+    };
+    this.patterns = this.config.alwaysConfirmPatterns.map(p => {
+      try { return new RegExp(p); } catch { return null; }
+    }).filter((r): r is RegExp => r !== null);
+    if (skipPermissions) {
+      process.stderr.write('[permissions] --dangerously-skip-permissions active; all tools auto-approved\n');
+    }
+  }
+
+  /** Classify a tool call without prompting. */
+  check(tool: string, args: Record<string, unknown>): PermissionTier {
+    if (this.skip) return 'auto-approve';
+
+    // Start from session override → tool default → config default.
+    const sessionTier = this.config.sessionOverrides?.[tool];
+    let tier: PermissionTier = sessionTier
+      || this.config.tools[tool]
+      || this.config.defaultTier;
+
+    // run_command-specific safety rails:
+    //   1. always-confirm patterns (rm -rf, sudo, curl|sh, …) are bypass-
+    //      proof — they always escalate to the strictest tier regardless
+    //      of what the config or session override says.
+    //   2. shell compound/chain operators (&&, ||, ;, |, $(), backtick,
+    //      xargs, eval) force-upgrade `auto-approve` → `confirm`. A human
+    //      sees every chained command before it runs, but yolo-for-turn
+    //      can still batch-approve them — they're "risky" not "forbidden".
+    if (tool === 'run_command') {
+      const cmd = normalizeCommand(String(args.command ?? ''));
+      for (const re of this.patterns) {
+        if (re.test(cmd)) return 'always-confirm';
+      }
+      if (tier === 'auto-approve' && SHELL_CHAIN_OPERATORS.test(cmd)) {
+        return 'confirm';
+      }
+    }
+
+    return tier;
+  }
+
+  /**
+   * Request permission: if tier is auto-approve or session-approved, resolve
+   * immediately; otherwise emit a permission_request and await a response.
+   */
+  async requestPermission(
+    tool: string,
+    args: Record<string, unknown>,
+    emit: (event: any) => void,
+  ): Promise<PermissionDecision> {
+    if (this.skip) return 'approved';
+    const tier = this.check(tool, args);
+    if (tier === 'auto-approve') return 'approved';
+
+    // Yolo-for-this-turn: user pressed 4, they mean approve EVERYTHING
+    // for the rest of this turn — including always-confirm tier. The flag
+    // resets automatically at endTurn().
+    if (this.turnApproveAll) return 'approved';
+
+    const fp = fingerprint(tool, args);
+    if (tier !== 'always-confirm' && this.sessionApprovals.has(fp)) return 'approved';
+
+    const id = `perm-${Date.now()}-${this.nextId++}`;
+    emit({
+      type: 'permission_request',
+      id,
+      tool,
+      args: JSON.stringify(args).slice(0, 2000),
+      summary: summarize(tool, args),
+      tier,
+    });
+
+    return new Promise<PermissionDecision>((resolve) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        emit({ type: 'permission_timeout', id, tool });
+        resolve('denied');
+      }, REQUEST_TIMEOUT_MS);
+      this.pending.set(id, { resolve, timeout });
+    }).then(decision => {
+      if (decision === 'approved-session' && tier !== 'always-confirm') {
+        this.sessionApprovals.add(fp);
+      }
+      if (decision === 'approved-turn') {
+        this.turnApproveAll = true;
+      }
+      return decision;
+    });
+  }
+
+  /** Handle a response from the TUI. Duplicate/unknown ids are ignored. */
+  handleResponse(id: string, decision: PermissionDecision): void {
+    const p = this.pending.get(id);
+    if (!p) return;
+    clearTimeout(p.timeout);
+    this.pending.delete(id);
+    p.resolve(decision);
+  }
+
+  /** Backend calls this when the assistant turn completes — clears yolo. */
+  endTurn(): void {
+    this.turnApproveAll = false;
+  }
+}
+
+function normalizeCommand(cmd: string): string {
+  return cmd.trim().replace(/\s+/g, ' ');
+}
+
+function summarize(tool: string, args: Record<string, unknown>): string {
+  switch (tool) {
+    case 'run_command': return `Run shell command: ${String(args.command || '').slice(0, 200)}`;
+    case 'write_file': return `Write file: ${String(args.path || '')}`;
+    case 'edit_file': return `Edit file: ${String(args.path || '')}`;
+    case 'create_task': return `Dispatch task: ${String(args.description || '').slice(0, 160)}`;
+    case 'update_memory': return `Update ${String(args.scope || '')} memory (${String(args.operation || '')})`;
+    default: return `${tool}(${JSON.stringify(args).slice(0, 160)})`;
+  }
+}
+
+function loadConfig(configPath: string): PermissionConfig {
+  if (!existsSync(configPath)) {
+    // Don't write defaults to project level — let user-level handle it.
+    // Only return an empty config so the merge in the constructor picks
+    // up user-level settings without project-level overriding them.
+    return { defaultTier: '' as PermissionTier, tools: {}, alwaysConfirmPatterns: [], sessionOverrides: undefined };
+  }
+  try {
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return {
+      defaultTier: raw.defaultTier || DEFAULT_CONFIG.defaultTier,
+      tools: { ...DEFAULT_TOOL_TIERS, ...(raw.tools || {}) },
+      alwaysConfirmPatterns: raw.alwaysConfirmPatterns || DEFAULT_ALWAYS_CONFIRM_PATTERNS,
+      sessionOverrides: raw.sessionOverrides,
+    };
+  } catch (e) {
+    process.stderr.write(`[permissions] Failed to parse ${configPath}: ${(e as Error).message}; using defaults\n`);
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/engine/pipeline.ts

@@ -0,0 +1,376 @@
+/**
+ * Pipeline — the Discuss → Commit → Dispatch → Execute → Verify → Reflect loop.
+ *
+ * Orchestrates the flow between conversation model, worker model,
+ * and local verification tools. All calls are recorded in the audit ledger.
+ */
+
+import { join } from 'node:path';
+import type {
+  Session, SessionState, TaskCard, RepoMap,
+  LLMResponse, VerificationResult, ProviderId,
+} from '../types.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import { createTaskCard, executeTaskCard, readRelevantFiles } from './task-card.ts';
+import { parseFileReplacements, applyChanges, formatApplyResult, type ApplyResult } from './apply.ts';
+import { verify } from './verify.ts';
+import { Ledger } from '../audit/ledger.ts';
+import type { Router as UnifiedRouter } from '../router/index.ts';
+import type { RoutingCollector } from '../router/collector.ts';
+import { PipelineError } from './errors.ts';
+import { TaskStore } from './task-store.ts';
+
+// ---------------------------------------------------------------------------
+// Pipeline configuration
+// ---------------------------------------------------------------------------
+
+export interface PipelineConfig {
+  /** Fallback provider (used when no router is available) */
+  provider: ProviderId;
+  model?: string;
+  /** Unified router for model selection */
+  router?: UnifiedRouter;
+  /** Training data collector */
+  collector?: RoutingCollector;
+  /** Max failures before retrying with enhanced prompt */
+  promotionThreshold: number;
+  /** Working directory */
+  workingDir: string;
+  /** Run verification after execution? */
+  autoVerify: boolean;
+  /** Task store for persisting task cards across sessions. */
+  taskStore?: TaskStore;
+  /**
+   * Optional event sink — if provided, the pipeline streams an
+   * `activity` event per phase as it runs. Threaded in from
+   * `ToolContext.emit` by `toolCreateTask` so the TUI can show
+   * "pipeline: dispatch → claude-sonnet …" / "pipeline: execute → gemini
+   * …" / "pipeline: verify → PASSED" in real time instead of blocking
+   * on a single opaque `create_task` tool call. Leaving this undefined
+   * preserves the silent behavior for any caller that wants it.
+   */
+  emit?: (event: Record<string, unknown>) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline result
+// ---------------------------------------------------------------------------
+
+export interface PipelineResult {
+  /** The task card that was created and executed */
+  task: TaskCard;
+  /** Worker model output */
+  executionOutput: string;
+  /** Files written to disk */
+  applied?: ApplyResult;
+  /** Verification results (if autoVerify) */
+  verification?: VerificationResult;
+  /** Frontier model reflection on results */
+  reflection: string;
+  /** Was the task promoted to frontier after cheap failures? */
+  promoted: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full pipeline for a user request that requires code execution.
+ *
+ * 1. Dispatch — create task card from user intent + session state
+ * 2. Execute — send task card to worker model
+ * 3. Verify — run local tests/lint/typecheck
+ * 4. Reflect — frontier summarizes what happened
+ *
+ * Returns the result for display in the conversation.
+ */
+export async function runPipeline(
+  userIntent: string,
+  session: Session,
+  ledger: Ledger,
+  config: PipelineConfig,
+): Promise<PipelineResult> {
+
+  /** Track what happened in each pipeline phase so the router's intent
+   *  classifier can make informed per-step decisions. */
+  const priorPhases: Array<{ phase: string; model: string; summary?: string; succeeded?: boolean }> = [];
+
+  /** Resolve provider/model from router or fallback, passing accumulated
+   *  phase context so the intent classifier sees the full picture. */
+  const route = async (
+    phase: import('../types.ts').LedgerPhase,
+    promptText: string,
+    taskKind?: string,
+    failures = 0,
+  ) => {
+    if (config.router) {
+      const decision = await config.router.select(
+        phase,
+        promptText,
+        taskKind,
+        failures,
+        config.promotionThreshold,
+        { priorPhases: [...priorPhases], currentGoal: userIntent },
+      );
+      return { provider: decision.model.provider, model: decision.model.id, decision };
+    }
+    return { provider: config.provider, model: config.model, decision: undefined as any };
+  };
+
+  const emit = config.emit;
+  emit?.({ type: 'activity', text: `pipeline: starting — "${userIntent.slice(0, 80)}"`, activity_type: 'step' });
+
+  // -----------------------------------------------------------------------
+  // Step 1: Dispatch — create task card
+  // -----------------------------------------------------------------------
+  const dispatchRoute = await route('dispatch', userIntent);
+  emit?.({
+    type: 'activity',
+    text: `pipeline: dispatch → ${dispatchRoute.model || '(fallback)'} (${dispatchRoute.decision?.reason || 'fallback'})`,
+    activity_type: 'step',
+  });
+  let card, dispatchResponse;
+  try {
+    ({ card, response: dispatchResponse } = await createTaskCard(
+      userIntent,
+      session.state,
+      session.repoMap,
+      dispatchRoute.provider,
+      dispatchRoute.model,
+      ledger,
+    ));
+  } catch (e) {
+    throw new PipelineError(
+      `dispatch failed: ${e instanceof Error ? e.message : String(e)}`,
+      { severity: 'fatal', stage: 'dispatch', cause: e },
+    );
+  }
+  // process.stderr.write(`  │  │  model: ${dispatchResponse.model}  ${dispatchResponse.inputTokens}in/${dispatchResponse.outputTokens}out\n`);
+  // process.stderr.write(`  │  ╰─ task ${card.id} (${card.kind}): ${card.goal.slice(0, 60)}\n`);
+
+  // Record routing outcome
+  config.collector?.record({
+    timestamp: new Date().toISOString(),
+    phase: 'dispatch', taskKind: card.kind, promptLength: userIntent.length,
+    contextTokens: dispatchResponse.inputTokens, failures: 0, promoted: false,
+    modelId: dispatchResponse.model, provider: dispatchRoute.provider,
+    succeeded: true, inputTokens: dispatchResponse.inputTokens,
+    outputTokens: dispatchResponse.outputTokens,
+    costUsd: 0, latencyMs: dispatchResponse.latencyMs,
+    routeReason: dispatchRoute.decision?.reason || 'fallback',
+    routingTier: dispatchRoute.decision?.tier,
+  });
+
+  priorPhases.push({
+    phase: 'dispatch',
+    model: dispatchResponse.model,
+    summary: `task ${card.id} (${card.kind}): ${card.goal.slice(0, 80)}`,
+    succeeded: true,
+  });
+
+  card.status = 'executing';
+  session.tasks.push(card);
+  session.state.activeTaskId = card.id;
+  config.taskStore?.setCurrent(card);
+
+  // -----------------------------------------------------------------------
+  // Step 2: Execute — router picks the worker model
+  // -----------------------------------------------------------------------
+  const fileContents = config.workingDir
+    ? readRelevantFiles(config.workingDir, card.relevantFiles)
+    : '';
+
+  const execRoute = await route('execute', card.goal, card.kind, card.failures);
+  emit?.({
+    type: 'activity',
+    text: `pipeline: execute → ${execRoute.model || '(fallback)'} (${execRoute.decision?.reason || 'fallback'})`,
+    activity_type: 'step',
+  });
+  let executionResponse;
+  try {
+    executionResponse = await executeTaskCard(
+      card,
+      session.repoMap,
+      fileContents,
+      execRoute.provider,
+      execRoute.model,
+      ledger,
+    );
+  } catch (e) {
+    throw new PipelineError(
+      `execute failed: ${e instanceof Error ? e.message : String(e)}`,
+      { severity: 'recoverable', stage: 'execute', cause: e },
+    );
+  }
+  // process.stderr.write(`  │  │  model: ${executionResponse.model}  ${executionResponse.inputTokens}in/${executionResponse.outputTokens}out\n`);
+  // process.stderr.write(`  │  ╰─ done\n`);
+
+  // -----------------------------------------------------------------------
+  // Step 2.5: Apply — write model output to disk
+  // -----------------------------------------------------------------------
+  priorPhases.push({
+    phase: 'execute',
+    model: executionResponse.model,
+    summary: `wrote ${executionResponse.outputTokens} output tokens`,
+    succeeded: true,
+  });
+
+  let applyResult: ApplyResult | undefined;
+  if (config.workingDir && card.outputMode !== 'text') {
+    const changes = parseFileReplacements(executionResponse.content);
+    if (changes.length > 0) {
+      const backupDir = join(config.workingDir, '.kondi-chat', 'backups', card.id);
+      applyResult = applyChanges(config.workingDir, changes, backupDir);
+      emit?.({
+        type: 'activity',
+        text: `pipeline: apply → ${applyResult.applied.length} file(s) written${applyResult.skipped.length > 0 ? `, ${applyResult.skipped.length} skipped` : ''}`,
+        activity_type: 'step',
+      });
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Step 3: Verify — run local tools
+  // -----------------------------------------------------------------------
+  let verification: VerificationResult | undefined;
+
+  if (config.autoVerify && config.workingDir) {
+    card.status = 'verifying';
+    emit?.({ type: 'activity', text: 'pipeline: verify → running tests/typecheck/lint', activity_type: 'step' });
+    verification = verify(config.workingDir, session.repoMap);
+    emit?.({
+      type: 'activity',
+      text: `pipeline: verify → ${verification.passed ? 'PASSED' : 'FAILED'}`,
+      activity_type: 'step',
+    });
+    priorPhases.push({
+      phase: 'verify',
+      model: 'local',
+      summary: verification.passed ? 'tests passed' : 'tests FAILED',
+      succeeded: verification.passed,
+    });
+
+    const verifyOutput = [
+      verification.testOutput ? `Tests: ${verification.passed ? 'PASS' : 'FAIL'}\n${verification.testOutput}` : '',
+      verification.typecheckOutput ? `Typecheck: ${verification.typecheckOutput}` : '',
+      verification.lintOutput ? `Lint: ${verification.lintOutput}` : '',
+    ].filter(Boolean).join('\n\n');
+
+    // process.stderr.write(`  │  ╰─ ${verification.passed ? 'PASSED' : 'FAILED'}\n`);
+    ledger.recordVerification(card.id, verification.passed, verifyOutput);
+
+    // Retry on failure — enrich prompt with error context so router can escalate
+    if (!verification.passed && card.failures < config.promotionThreshold) {
+      card.failures++;
+      session.state.recentFailures.push(
+        `Task ${card.id} failed (attempt ${card.failures}): ${verifyOutput.slice(0, 200)}`
+      );
+
+      // pipeline: retry (attempt N/M) — suppressed for TUI
+
+      // Retry — router may promote to a better model based on failure count
+      const retryRoute = await route('execute', card.goal, card.kind, card.failures);
+      const retryCard = { ...card, constraints: [...card.constraints, `Previous attempt failed with: ${verifyOutput.slice(0, 500)}`] };
+      // process.stderr.write(`  │  │  ${retryRoute.decision?.promoted ? 'PROMOTED' : 'retrying'}${retryRoute.decision ? ` [${retryRoute.decision.reason}]` : ''}\n`);
+      executionResponse = await executeTaskCard(
+        retryCard,
+        session.repoMap,
+        fileContents,
+        retryRoute.provider,
+        retryRoute.model,
+        ledger,
+      );
+      // process.stderr.write(`  │  │  model: ${executionResponse.model}  ${executionResponse.inputTokens}in/${executionResponse.outputTokens}out\n`);
+      // process.stderr.write(`  │  ╰─ retry done\n`);
+
+      // Re-verify
+      // process.stderr.write(`  │  ╭─ verify (local)\n`);
+      verification = verify(config.workingDir, session.repoMap);
+      const retryVerifyOutput = [
+        verification.testOutput ? `Tests: ${verification.passed ? 'PASS' : 'FAIL'}\n${verification.testOutput}` : '',
+        verification.typecheckOutput ? `Typecheck: ${verification.typecheckOutput}` : '',
+      ].filter(Boolean).join('\n\n');
+      // process.stderr.write(`  │  ╰─ ${verification.passed ? 'PASSED' : 'FAILED'}\n`);
+      ledger.recordVerification(card.id, verification.passed, retryVerifyOutput);
+    }
+  }
+
+  const promoted = card.failures >= config.promotionThreshold;
+  card.status = verification?.passed ? 'passed' : (promoted ? 'promoted' : 'failed');
+  card.completedAt = new Date().toISOString();
+
+  // Record execution outcome for router training
+  config.collector?.record({
+    timestamp: new Date().toISOString(),
+    phase: 'execute', taskKind: card.kind, promptLength: card.goal.length,
+    contextTokens: executionResponse.inputTokens, failures: card.failures, promoted,
+    modelId: executionResponse.model, provider: executionResponse.provider,
+    succeeded: verification?.passed ?? true,
+    verificationPassed: verification?.passed,
+    inputTokens: executionResponse.inputTokens,
+    outputTokens: executionResponse.outputTokens,
+    costUsd: 0, latencyMs: executionResponse.latencyMs,
+    routeReason: execRoute.decision?.reason || 'fallback',
+    routingTier: execRoute.decision?.tier,
+  });
+
+  // -----------------------------------------------------------------------
+  // Step 4: Reflect — frontier summarizes what happened
+  // -----------------------------------------------------------------------
+  const reflectRoute = await route('reflect', card.goal);
+  emit?.({
+    type: 'activity',
+    text: `pipeline: reflect → ${reflectRoute.model || '(fallback)'} (${reflectRoute.decision?.reason || 'fallback'})`,
+    activity_type: 'step',
+  });
+  let reflectionResponse: LLMResponse;
+  try {
+    reflectionResponse = await callLLM({
+    provider: reflectRoute.provider,
+    model: reflectRoute.model,
+    systemPrompt: 'You are summarizing the results of a coding task for the user. Be concise. Report what was done, whether it passed verification, and what to do next.',
+    userMessage: `Task: ${card.goal}
+Kind: ${card.kind}
+Status: ${card.status}
+
+Worker output (summary):
+${executionResponse.content.slice(0, 3000)}
+
+${verification ? `Verification: ${verification.passed ? 'PASSED' : 'FAILED'}
+${verification.testOutput ? `Test output: ${verification.testOutput.slice(0, 500)}` : ''}
+${verification.typecheckOutput ? `Typecheck: ${verification.typecheckOutput.slice(0, 500)}` : ''}` : 'Verification: skipped'}
+
+Summarize the results for the user. If failed, suggest what to try next.`,
+    maxOutputTokens: 1500,
+  });
+  } catch (e) {
+    // Reflection is non-essential — we already executed and verified. If
+    // the reflection call fails, degrade gracefully with a synthetic
+    // summary instead of nuking the whole pipeline result.
+    reflectionResponse = {
+      content: `(reflection failed: ${e instanceof Error ? e.message : String(e)})`,
+      model: reflectRoute.model || 'unknown',
+      provider: reflectRoute.provider,
+      inputTokens: 0, outputTokens: 0, latencyMs: 0,
+    };
+  }
+
+  ledger.record('reflect', reflectionResponse, `Reflect on task ${card.id}`, { taskId: card.id });
+
+  // Clean up state + persist completed task to history
+  session.state.activeTaskId = undefined;
+  if (card.status === 'passed') {
+    session.state.recentFailures = session.state.recentFailures.filter(f => !f.includes(card.id));
+  }
+  config.taskStore?.complete();
+
+  return {
+    task: card,
+    executionOutput: executionResponse.content,
+    applied: applyResult,
+    verification,
+    reflection: reflectionResponse.content,
+    promoted,
+  };
+}