bonecode 1.3.0 → 1.4.1

package/src/engine/session/build_mode.ts

@@ -0,0 +1,895 @@
+/**
+ * Autonomous Build Mode — small-model-friendly project orchestrator
+ *
+ * Why: small/local models (8-20B) struggle with open-ended "build me X" prompts.
+ * They produce prose, hallucinate edits, and forget what they were doing across
+ * turns. This module replaces the single-turn agent loop with a deterministic
+ * state machine that drives the model through narrow, focused stages.
+ *
+ * State flow:
+ *
+ *   ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
+ *   │ CLARIFY  │ ──▶ │   PLAN   │ ──▶ │ EXECUTE  │ ──▶ │  VERIFY  │
+ *   │ (Q&A)    │     │ (todos)  │     │ (loop)   │     │ (yes/no) │
+ *   └──────────┘     └──────────┘     └─────┬────┘     └─────┬────┘
+ *                                            │                │
+ *                                            ▼                ▼
+ *                                       ┌────────┐       ┌────────┐
+ *                                       │  DONE  │ ◀──── │ all ok │
+ *                                       └────────┘       └────────┘
+ *                                                              │
+ *                                                              │ failures
+ *                                                              ▼
+ *                                                        back to PLAN
+ *
+ * Each stage uses a tightly scoped prompt with a structured-output requirement
+ * (JSON we parse deterministically). The agent's natural "describe what I'd do"
+ * tendency is replaced by short, mechanical answers.
+ *
+ * State is persisted to the sessions table (in build_state JSON column) so
+ * the loop can resume across restarts and is visible to the user via the UI.
+ */
+
+import { generateText } from "ai";
+import { v4 as uuid } from "uuid";
+import { pool } from "../../../bone/output/session/src/db";
+import { broadcastToChannel } from "../../../bone/output/session/src/websocket";
+import { logger } from "../../../bone/output/session/src/logger";
+import { runAgentLoop } from "./prompt";
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+export type BuildStage = "clarify" | "plan" | "execute" | "verify" | "done" | "failed";
+
+export interface DesignDoc {
+  goal: string;
+  requirements: string[];
+  constraints: string[];
+  artifacts: string[]; // expected file paths
+}
+
+export interface BuildTodo {
+  id: string;
+  title: string;
+  description: string;
+  status: "pending" | "in_progress" | "completed" | "failed";
+  failure_count: number;
+  evidence?: string; // file paths or notes recorded after completion
+}
+
+export interface BuildState {
+  stage: BuildStage;
+  original_prompt: string;
+  design: DesignDoc | null;
+  todos: BuildTodo[];
+  iteration: number;
+  max_iterations: number;
+  pending_clarification?: string;
+  verification_results?: VerificationResult[];
+  error?: string;
+  /** Set after probe: whether the model can emit OpenAI-format tool calls. */
+  tool_capable?: boolean;
+}
+
+export interface VerificationResult {
+  requirement: string;
+  satisfied: boolean;
+  evidence: string;
+}
+
+export interface BuildModeInput {
+  session_id: string;
+  message_id: string;
+  prompt: string;
+  model_id: string;
+  provider_id: string;
+}
+
+// ─── Persistence ──────────────────────────────────────────────────────────────
+
+async function loadState(session_id: string): Promise<BuildState | null> {
+  try {
+    const r = await pool.query(`SELECT build_state FROM sessions WHERE id = $1`, [session_id]);
+    const raw = r.rows[0]?.build_state;
+    if (!raw) return null;
+    return typeof raw === "string" ? JSON.parse(raw) : raw;
+  } catch {
+    return null;
+  }
+}
+
+async function saveState(session_id: string, state: BuildState): Promise<void> {
+  // Try with the dedicated column first; fall back to permission_ruleset.build
+  // if the column doesn't exist yet (older schemas).
+  try {
+    await pool.query(
+      `UPDATE sessions SET build_state = $2::jsonb, updated_at = NOW() WHERE id = $1`,
+      [session_id, JSON.stringify(state)]
+    );
+  } catch {
+    try {
+      await pool.query(
+        `UPDATE sessions
+         SET permission_ruleset = jsonb_set(COALESCE(permission_ruleset, '{}'::jsonb), '{build}', $2::jsonb),
+             updated_at = NOW()
+         WHERE id = $1`,
+        [session_id, JSON.stringify(state)]
+      );
+    } catch {}
+  }
+}
+
+function emit(session_id: string, event: string, data: Record<string, unknown>) {
+  broadcastToChannel("session_events", { type: event, session_id, ...data });
+}
+
+// ─── Structured-output helpers ────────────────────────────────────────────────
+
+/**
+ * Ask the model a focused question with a JSON-only response requirement.
+ * Strips any prose/markdown around the JSON and parses it. Returns null on
+ * failure so the caller can decide whether to retry.
+ */
+async function askJson<T>(input: {
+  model_id: string;
+  provider_id: string;
+  system: string;
+  user: string;
+  schema_hint: string; // human-readable description of the expected shape
+}): Promise<T | null> {
+  const { getLanguageModel } = await import("./build_mode_helpers");
+  const model = getLanguageModel(input.provider_id, input.model_id);
+
+  const fullSystem = [
+    input.system,
+    "",
+    "OUTPUT REQUIREMENTS:",
+    `- Reply with a single JSON object only.`,
+    `- Expected shape: ${input.schema_hint}`,
+    `- Do NOT include any prose before or after the JSON.`,
+    `- Do NOT wrap in markdown code fences.`,
+    `- Do NOT explain. Output only the JSON object.`,
+  ].join("\n");
+
+  try {
+    const { text } = await generateText({
+      model,
+      system: fullSystem,
+      prompt: input.user,
+      temperature: 0.1,
+      maxTokens: 2048,
+    });
+    return parseJsonLoose<T>(text);
+  } catch (e: any) {
+    logger.error("build_mode_json_failed", { event: "askJson", metadata: { error: e.message } });
+    return null;
+  }
+}
+
+/**
+ * Parse JSON from a model response that might be wrapped in markdown fences,
+ * have extra prose around it, or contain partial output. Returns null if no
+ * recoverable JSON object is found.
+ */
+function parseJsonLoose<T>(raw: string): T | null {
+  if (!raw) return null;
+  // Strip <think>...</think> blocks (some reasoning models include them)
+  let s = raw.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+  // Strip code fences
+  s = s.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "").trim();
+  // Find first { and matching close
+  const start = s.indexOf("{");
+  if (start === -1) {
+    // Maybe an array
+    const arrStart = s.indexOf("[");
+    if (arrStart === -1) return null;
+    return tryParse<T>(extractBalanced(s, arrStart, "[", "]"));
+  }
+  return tryParse<T>(extractBalanced(s, start, "{", "}"));
+}
+
+function extractBalanced(s: string, start: number, open: string, close: string): string {
+  let depth = 0;
+  let inStr = false;
+  let escape = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i];
+    if (escape) { escape = false; continue; }
+    if (ch === "\\") { escape = true; continue; }
+    if (ch === '"') { inStr = !inStr; continue; }
+    if (inStr) continue;
+    if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) return s.slice(start, i + 1);
+    }
+  }
+  return s.slice(start); // unbalanced — return what we have
+}
+
+function tryParse<T>(s: string): T | null {
+  try { return JSON.parse(s) as T; } catch { return null; }
+}
+
+// ─── Stage 1: Clarify ─────────────────────────────────────────────────────────
+
+async function stageClarify(state: BuildState, input: BuildModeInput): Promise<BuildState> {
+  emit(input.session_id, "build.stage", { stage: "clarify" });
+
+  // Ask the model: do you have enough info? If not, what 1-3 questions?
+  const result = await askJson<{
+    sufficient: boolean;
+    questions: string[];
+    proposed_design?: DesignDoc;
+  }>({
+    model_id: input.model_id,
+    provider_id: input.provider_id,
+    system: [
+      "You are a senior engineer scoping a project.",
+      "The user has given you a prompt. Decide if you have enough to start.",
+      "If yes, propose a concrete design document.",
+      "If no, ask 1-3 specific questions.",
+      "",
+      "RULES:",
+      "- Never ask more than 3 questions in one round.",
+      "- Questions must be answerable in one sentence each.",
+      "- If the prompt is concrete enough (mentions specific tech, scope, constraints), set sufficient=true.",
+    ].join("\n"),
+    user: `User prompt:\n${input.prompt}`,
+    schema_hint: `{ "sufficient": boolean, "questions": string[], "proposed_design": { "goal": string, "requirements": string[], "constraints": string[], "artifacts": string[] } }`,
+  });
+
+  if (!result) {
+    state.error = "Could not parse model response during clarification.";
+    state.stage = "failed";
+    return state;
+  }
+
+  if (result.sufficient && result.proposed_design) {
+    state.design = result.proposed_design;
+    state.stage = "plan";
+    emit(input.session_id, "build.design", { design: result.proposed_design });
+    return state;
+  }
+
+  // Ask the user the questions
+  state.pending_clarification = result.questions.join("\n");
+  emit(input.session_id, "build.questions", { questions: result.questions });
+  return state;
+}
+
+/**
+ * Called when the user has answered the clarification questions.
+ * Combines the original prompt + answers into a finalized design.
+ */
+export async function continueAfterClarification(
+  session_id: string,
+  user_answer: string,
+  model_id: string,
+  provider_id: string
+): Promise<BuildState | null> {
+  const state = await loadState(session_id);
+  if (!state || state.stage !== "clarify") return null;
+
+  const result = await askJson<DesignDoc>({
+    model_id,
+    provider_id,
+    system: [
+      "You are scoping a project. Below is the original user prompt, the questions you asked, and the user's answers.",
+      "Produce a concrete design document.",
+      "",
+      "REQUIREMENTS list must be specific and verifiable (each item must be answerable yes/no).",
+      "ARTIFACTS list must be concrete file paths the project should produce.",
+    ].join("\n"),
+    user: [
+      `Original prompt:\n${state.original_prompt}`,
+      ``,
+      `Questions asked:\n${state.pending_clarification ?? ""}`,
+      ``,
+      `User's answers:\n${user_answer}`,
+    ].join("\n"),
+    schema_hint: `{ "goal": string, "requirements": string[], "constraints": string[], "artifacts": string[] }`,
+  });
+
+  if (!result) {
+    state.error = "Could not finalize design from clarification answers.";
+    state.stage = "failed";
+  } else {
+    state.design = result;
+    state.pending_clarification = undefined;
+    state.stage = "plan";
+    emit(session_id, "build.design", { design: result });
+  }
+
+  await saveState(session_id, state);
+  return state;
+}
+
+// ─── Stage 2: Plan ────────────────────────────────────────────────────────────
+
+async function stagePlan(state: BuildState, input: BuildModeInput): Promise<BuildState> {
+  if (!state.design) {
+    state.stage = "failed";
+    state.error = "No design to plan from.";
+    return state;
+  }
+
+  emit(input.session_id, "build.stage", { stage: "plan" });
+
+  const result = await askJson<{ todos: Array<{ title: string; description: string }> }>({
+    model_id: input.model_id,
+    provider_id: input.provider_id,
+    system: [
+      "You are turning a design document into an ordered todo list.",
+      "",
+      "RULES:",
+      "- Each todo must be a concrete, single-file action when possible.",
+      "- Use tool-friendly verbs: 'Write', 'Edit', 'Run', 'Create'.",
+      "- Order todos by dependency: schema/config first, then implementation, then tests.",
+      "- Aim for 5-15 todos. Don't split trivial work.",
+      "- Each title fits on one line, max 80 chars.",
+      "- Each description gives the file path and what to do, in 1-2 sentences.",
+    ].join("\n"),
+    user: [
+      `Design:`,
+      `Goal: ${state.design.goal}`,
+      `Requirements:\n${state.design.requirements.map((r) => `- ${r}`).join("\n")}`,
+      `Constraints:\n${state.design.constraints.map((c) => `- ${c}`).join("\n")}`,
+      `Expected artifacts:\n${state.design.artifacts.map((a) => `- ${a}`).join("\n")}`,
+    ].join("\n"),
+    schema_hint: `{ "todos": [{ "title": string, "description": string }] }`,
+  });
+
+  if (!result || !Array.isArray(result.todos) || result.todos.length === 0) {
+    state.error = "Could not produce a todo list.";
+    state.stage = "failed";
+    return state;
+  }
+
+  state.todos = result.todos.map((t) => ({
+    id: uuid(),
+    title: t.title,
+    description: t.description,
+    status: "pending",
+    failure_count: 0,
+  }));
+  state.stage = "execute";
+  emit(input.session_id, "build.plan", { todos: state.todos });
+  return state;
+}
+
+// ─── Stage 3: Execute ─────────────────────────────────────────────────────────
+
+const MAX_TODO_RETRIES = 3;
+
+async function stageExecute(state: BuildState, input: BuildModeInput): Promise<BuildState> {
+  emit(input.session_id, "build.stage", { stage: "execute" });
+
+  // Detect tool-calling capability with a probe. Small/local models often can't
+  // emit tool calls in the OpenAI format. When that's the case, switch to
+  // a content-fallback path where we ask the model for a JSON manifest of
+  // files to write and apply them ourselves via fs.
+  if (state.tool_capable === undefined) {
+    state.tool_capable = await probeToolCapability(input);
+    if (!state.tool_capable) {
+      emit(input.session_id, "session.warning", {
+        message: `Model ${input.model_id} cannot emit tool calls — using JSON-manifest fallback mode (file content provided directly by the model, applied by the orchestrator).`,
+      });
+    }
+  }
+
+  // Track consecutive tool-call failures so we can bail out fast instead
+  // of grinding through 30 iterations against a model that can't do tools.
+  let consecutiveZeroToolCallTodos = 0;
+  const ABORT_AFTER_CONSECUTIVE_ZERO = 2;
+
+  while (state.iteration < state.max_iterations) {
+    state.iteration++;
+
+    const next = state.todos.find((t) => t.status === "pending");
+    if (!next) {
+      // All todos done — move to verification
+      state.stage = "verify";
+      return state;
+    }
+
+    next.status = "in_progress";
+    emit(input.session_id, "build.todo.start", { todo: next });
+
+    let succeeded = false;
+    let toolCallsCount = 0;
+    let errorMsg = "";
+
+    if (state.tool_capable) {
+      // ── Tool-calling path ────────────────────────────────────────────────
+      const focusedPrompt = [
+        `<build-task>`,
+        `Title: ${next.title}`,
+        `Description: ${next.description}`,
+        ``,
+        `This is one task in a larger build. Complete this task NOW by calling the appropriate tools.`,
+        `Do not describe what you would do — call the tools.`,
+        `</build-task>`,
+      ].join("\n");
+
+      const taskMsgId = uuid();
+      await pool.query(
+        `INSERT INTO messages (id, session_id, role) VALUES ($1, $2, 'user')`,
+        [taskMsgId, input.session_id]
+      );
+      const taskPartId = uuid();
+      await pool.query(
+        `INSERT INTO parts (id, message_id, session_id, part_type, data, order_index) VALUES ($1, $2, $3, 'text', $4, 0)`,
+        [taskPartId, input.session_id, input.session_id, JSON.stringify({ text: focusedPrompt, synthetic: true })]
+      );
+
+      const result = await runAgentLoop({
+        session_id: input.session_id,
+        message_id: taskMsgId,
+        content: focusedPrompt,
+        model_id: input.model_id,
+        provider_id: input.provider_id,
+        agent_name: "build",
+      });
+
+      toolCallsCount = await countToolCallsSince(input.session_id, taskMsgId);
+      succeeded = result.ok && toolCallsCount > 0;
+      errorMsg = result.error || "no tool calls";
+    } else {
+      // ── JSON-manifest fallback ───────────────────────────────────────────
+      const fallback = await executeFallback(state, next, input);
+      succeeded = fallback.ok;
+      toolCallsCount = fallback.filesWritten;
+      errorMsg = fallback.error || "no files produced";
+    }
+
+    if (succeeded) {
+      next.status = "completed";
+      next.evidence = state.tool_capable
+        ? `${toolCallsCount} tool call(s) made`
+        : `${toolCallsCount} file(s) written via fallback`;
+      consecutiveZeroToolCallTodos = 0;
+      emit(input.session_id, "build.todo.done", { todo: next });
+    } else {
+      next.failure_count++;
+      if (next.failure_count >= MAX_TODO_RETRIES) {
+        next.status = "failed";
+        consecutiveZeroToolCallTodos++;
+        emit(input.session_id, "build.todo.failed", { todo: next, reason: errorMsg });
+      } else {
+        next.status = "pending";
+        emit(input.session_id, "build.todo.retry", { todo: next, attempt: next.failure_count });
+      }
+    }
+
+    await saveState(input.session_id, state);
+
+    // Early bailout — if N consecutive todos fail completely, this model can't
+    // do the job. Stop so the user can switch models instead of waiting through
+    // 30 useless iterations.
+    if (consecutiveZeroToolCallTodos >= ABORT_AFTER_CONSECUTIVE_ZERO) {
+      state.stage = "failed";
+      state.error = `Model failed ${consecutiveZeroToolCallTodos} consecutive todos with no progress. ${
+        state.tool_capable
+          ? "Try MODEL_SUPPORTS_TOOLS=false to enable JSON-manifest fallback."
+          : "The model cannot produce structured output for this task. Try a larger or more instruction-tuned model."
+      }`;
+      emit(input.session_id, "session.warning", { message: state.error });
+      return state;
+    }
+  }
+
+  // Hit max iterations — bail out
+  if (state.todos.some((t) => t.status === "pending" || t.status === "in_progress")) {
+    state.stage = "failed";
+    state.error = `Hit iteration limit (${state.max_iterations}) with todos still pending.`;
+  } else {
+    state.stage = "verify";
+  }
+  return state;
+}
+
+async function countToolCallsSince(session_id: string, since_message_id: string): Promise<number> {
+  try {
+    const r = await pool.query(
+      `SELECT COUNT(*)::int AS n FROM tool_calls
+       WHERE session_id = $1
+         AND created_at >= (SELECT created_at FROM messages WHERE id = $2)`,
+      [session_id, since_message_id]
+    );
+    return r.rows[0]?.n || 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ─── Tool-capability probe & JSON-manifest fallback ───────────────────────────
+
+/**
+ * Detect whether the model can produce a structured tool call. Honors the
+ * MODEL_SUPPORTS_TOOLS env override so users with known-good models skip the
+ * probe entirely. Otherwise, runs a tiny smoke test: ask the model to write a
+ * trivial file via the `write` tool and check whether tool_calls were recorded.
+ *
+ * Result is cached on the BuildState so we only probe once per build.
+ */
+async function probeToolCapability(input: BuildModeInput): Promise<boolean> {
+  if (process.env.MODEL_SUPPORTS_TOOLS === "true") return true;
+  if (process.env.MODEL_SUPPORTS_TOOLS === "false") return false;
+  // Heuristic: known-good model families
+  const id = input.model_id.toLowerCase();
+  if (
+    id.includes("gpt-4") ||
+    id.includes("gpt-5") ||
+    id.includes("claude") ||
+    id.includes("gemini-1.5") ||
+    id.includes("gemini-2") ||
+    id.includes("gemini-3")
+  ) {
+    return true;
+  }
+  // For everything else, probe live. Run a one-shot agent call asking for a
+  // single trivial tool invocation and see if the DB records it.
+  try {
+    const probeMsgId = uuid();
+    await pool.query(
+      `INSERT INTO messages (id, session_id, role) VALUES ($1, $2, 'user')`,
+      [probeMsgId, input.session_id]
+    );
+    const probePartId = uuid();
+    const probePrompt =
+      "PROBE: Write a single line of text 'probe' to a file at .bonecode-probe using the write tool. Do not respond with prose. Call the write tool exactly once.";
+    await pool.query(
+      `INSERT INTO parts (id, message_id, session_id, part_type, data, order_index) VALUES ($1, $2, $3, 'text', $4, 0)`,
+      [probePartId, probeMsgId, input.session_id, JSON.stringify({ text: probePrompt, synthetic: true })]
+    );
+
+    await runAgentLoop({
+      session_id: input.session_id,
+      message_id: probeMsgId,
+      content: probePrompt,
+      model_id: input.model_id,
+      provider_id: input.provider_id,
+      agent_name: "build",
+    });
+
+    const calls = await countToolCallsSince(input.session_id, probeMsgId);
+    return calls > 0;
+  } catch {
+    return false;
+  }
+}
+
+interface FallbackResult {
+  ok: boolean;
+  filesWritten: number;
+  error?: string;
+}
+
+/**
+ * JSON-manifest fallback for models that can't emit tool calls.
+ *
+ * Asks the model for a manifest:
+ *   { "files": [{ "path": "...", "content": "..." }], "commands": ["..."] }
+ *
+ * Then applies it directly via fs/exec. The model never has to format an
+ * OpenAI-style tool call — it just produces a structured JSON document, which
+ * smaller/abliterated models handle much better.
+ */
+async function executeFallback(
+  state: BuildState,
+  todo: BuildTodo,
+  input: BuildModeInput
+): Promise<FallbackResult> {
+  const fs = require("fs/promises");
+  const path = require("path");
+  const { execSync } = require("child_process");
+
+  // Resolve worktree from the session
+  const sessionRow = await pool.query(
+    `SELECT s.directory, p.worktree FROM sessions s
+     LEFT JOIN projects p ON p.id = s.project_id
+     WHERE s.id = $1`,
+    [input.session_id]
+  );
+  const worktree =
+    sessionRow.rows[0]?.directory || sessionRow.rows[0]?.worktree || process.cwd();
+
+  // Build a focused prompt with the design context so the model knows what
+  // it's contributing to.
+  const designContext = state.design
+    ? [
+        `Design goal: ${state.design.goal}`,
+        `Constraints: ${state.design.constraints.join("; ") || "(none)"}`,
+        `Expected artifacts: ${state.design.artifacts.join(", ") || "(unspecified)"}`,
+      ].join("\n")
+    : "";
+
+  const completedFiles = state.todos
+    .filter((t) => t.status === "completed" && t.evidence)
+    .map((t) => `- ${t.title}`)
+    .join("\n");
+
+  const result = await askJson<{
+    files?: Array<{ path: string; content: string }>;
+    commands?: string[];
+  }>({
+    model_id: input.model_id,
+    provider_id: input.provider_id,
+    system: [
+      "You are completing one task in a project build. Produce a JSON manifest of the files to create or update and shell commands to run for THIS task only.",
+      "",
+      "RULES:",
+      "- Output a single JSON object: { \"files\": [...], \"commands\": [...] }",
+      "- Each file must have a relative `path` and full `content`. Do not abbreviate file content.",
+      "- File paths must be relative to the project root (no leading slash, no '..').",
+      "- Commands run in the project root. Use them only for compilation, package install, or migrations.",
+      "- Do not include explanatory prose. The JSON IS the entire response.",
+    ].join("\n"),
+    user: [
+      `<design>`,
+      designContext,
+      `</design>`,
+      ``,
+      `<completed-tasks>`,
+      completedFiles || "(none yet)",
+      `</completed-tasks>`,
+      ``,
+      `<current-task>`,
+      `Title: ${todo.title}`,
+      `Description: ${todo.description}`,
+      `</current-task>`,
+    ].join("\n"),
+    schema_hint: `{ "files": [{ "path": string, "content": string }], "commands": string[] }`,
+  });
+
+  if (!result || (!Array.isArray(result.files) && !Array.isArray(result.commands))) {
+    return { ok: false, filesWritten: 0, error: "Model did not produce a valid manifest" };
+  }
+
+  let filesWritten = 0;
+  const errors: string[] = [];
+
+  // Write files
+  for (const f of result.files ?? []) {
+    if (!f || typeof f.path !== "string" || typeof f.content !== "string") continue;
+    // Sanity: no traversal, no absolute paths
+    if (f.path.includes("..") || path.isAbsolute(f.path)) {
+      errors.push(`refused unsafe path: ${f.path}`);
+      continue;
+    }
+    const target = path.resolve(worktree, f.path);
+    if (!target.startsWith(path.resolve(worktree))) {
+      errors.push(`refused path outside worktree: ${f.path}`);
+      continue;
+    }
+    try {
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, f.content, "utf-8");
+      filesWritten++;
+      // Surface a tool.completed event so the TUI shows an Edit/Write line
+      const callId = `fallback-${uuid()}`;
+      const broadcastModule = await import("../../../bone/output/session/src/websocket");
+      broadcastModule.broadcastToChannel("part_stream", {
+        type: "tool.requested",
+        session_id: input.session_id,
+        tool_call_id: callId,
+        tool_name: "write",
+        tool_input: { path: f.path, content: f.content.slice(0, 200) },
+      });
+      broadcastModule.broadcastToChannel("part_stream", {
+        type: "tool.completed",
+        session_id: input.session_id,
+        tool_call_id: callId,
+        tool_name: "write",
+        tool_input: { path: f.path },
+        duration_ms: 0,
+      });
+    } catch (e: any) {
+      errors.push(`${f.path}: ${e.message}`);
+    }
+  }
+
+  // Run commands
+  for (const cmd of result.commands ?? []) {
+    if (typeof cmd !== "string" || !cmd.trim()) continue;
+    try {
+      execSync(cmd, { cwd: worktree, stdio: "pipe", timeout: 60_000 });
+      const callId = `fallback-${uuid()}`;
+      const broadcastModule = await import("../../../bone/output/session/src/websocket");
+      broadcastModule.broadcastToChannel("part_stream", {
+        type: "tool.requested",
+        session_id: input.session_id,
+        tool_call_id: callId,
+        tool_name: "bash",
+        tool_input: { command: cmd },
+      });
+      broadcastModule.broadcastToChannel("part_stream", {
+        type: "tool.completed",
+        session_id: input.session_id,
+        tool_call_id: callId,
+        tool_name: "bash",
+        tool_input: { command: cmd },
+        duration_ms: 0,
+      });
+    } catch (e: any) {
+      errors.push(`command failed: ${cmd} → ${e.message}`);
+    }
+  }
+
+  return {
+    ok: filesWritten > 0 || (result.commands?.length ?? 0) > 0,
+    filesWritten,
+    error: errors.length ? errors.join("; ") : undefined,
+  };
+}
+
+// ─── Stage 4: Verify ──────────────────────────────────────────────────────────
+
+async function stageVerify(state: BuildState, input: BuildModeInput): Promise<BuildState> {
+  if (!state.design) {
+    state.stage = "failed";
+    state.error = "No design to verify against.";
+    return state;
+  }
+
+  emit(input.session_id, "build.stage", { stage: "verify" });
+
+  const results: VerificationResult[] = [];
+
+  for (const requirement of state.design.requirements) {
+    // Ask the model: is this requirement satisfied? Yes/no plus evidence.
+    const r = await askJson<{ satisfied: boolean; evidence: string }>({
+      model_id: input.model_id,
+      provider_id: input.provider_id,
+      system: [
+        "You are auditing whether a single requirement has been satisfied by the project so far.",
+        "",
+        "RULES:",
+        "- Answer with a yes/no verdict and one-line evidence.",
+        "- Evidence should reference concrete files or behavior.",
+        "- If you cannot tell, set satisfied=false and explain in evidence what's missing.",
+        "- Do not assume anything not visible in the project.",
+      ].join("\n"),
+      user: [
+        `Requirement: ${requirement}`,
+        ``,
+        `Original goal: ${state.design.goal}`,
+        ``,
+        `Expected artifacts:\n${state.design.artifacts.map((a) => `- ${a}`).join("\n")}`,
+        ``,
+        `Completed work:\n${state.todos
+          .filter((t) => t.status === "completed")
+          .map((t) => `- ${t.title}`)
+          .join("\n") || "(none)"}`,
+      ].join("\n"),
+      schema_hint: `{ "satisfied": boolean, "evidence": string }`,
+    });
+
+    const result: VerificationResult = r
+      ? { requirement, satisfied: r.satisfied, evidence: r.evidence }
+      : { requirement, satisfied: false, evidence: "Could not verify (no response)." };
+    results.push(result);
+    emit(input.session_id, "build.verify.item", { requirement, satisfied: result.satisfied, evidence: result.evidence });
+  }
+
+  state.verification_results = results;
+
+  const allOk = results.every((r) => r.satisfied);
+  if (allOk) {
+    state.stage = "done";
+    emit(input.session_id, "build.done", { verifications: results });
+  } else {
+    // Re-plan only the unsatisfied requirements
+    const failures = results.filter((r) => !r.satisfied);
+    if (state.iteration >= state.max_iterations) {
+      state.stage = "failed";
+      state.error = `${failures.length} requirement(s) unsatisfied after ${state.max_iterations} iterations.`;
+    } else {
+      // Generate new todos to address failures
+      const newPlan = await askJson<{ todos: Array<{ title: string; description: string }> }>({
+        model_id: input.model_id,
+        provider_id: input.provider_id,
+        system: "Some requirements are not yet satisfied. Produce a short todo list to fix them.",
+        user: [
+          `Unsatisfied requirements:`,
+          ...failures.map((f) => `- ${f.requirement} (missing: ${f.evidence})`),
+        ].join("\n"),
+        schema_hint: `{ "todos": [{ "title": string, "description": string }] }`,
+      });
+
+      if (newPlan && Array.isArray(newPlan.todos) && newPlan.todos.length > 0) {
+        for (const t of newPlan.todos) {
+          state.todos.push({
+            id: uuid(),
+            title: t.title,
+            description: t.description,
+            status: "pending",
+            failure_count: 0,
+          });
+        }
+        state.stage = "execute";
+        emit(input.session_id, "build.replan", { added: newPlan.todos.length });
+      } else {
+        state.stage = "failed";
+        state.error = `Cannot generate fix-up tasks for ${failures.length} unsatisfied requirement(s).`;
+      }
+    }
+  }
+  return state;
+}
+
+// ─── Driver ───────────────────────────────────────────────────────────────────
+
+export async function runBuildMode(input: BuildModeInput): Promise<BuildState> {
+  let state: BuildState = (await loadState(input.session_id)) ?? {
+    stage: "clarify",
+    original_prompt: input.prompt,
+    design: null,
+    todos: [],
+    iteration: 0,
+    max_iterations: 30,
+  };
+
+  // Resume from saved state if applicable. If the user is sending a new prompt
+  // and we're already in clarify with pending questions, treat the prompt as
+  // the answer and continue.
+  if (state.stage === "clarify" && state.pending_clarification && input.prompt !== state.original_prompt) {
+    const next = await continueAfterClarification(input.session_id, input.prompt, input.model_id, input.provider_id);
+    if (next) state = next;
+  }
+
+  // Run stages until we hit a terminal state, a user prompt, or iteration cap.
+  // Each stage advances state.stage. We save after every stage transition.
+  let safety = 0;
+  while (state.stage !== "done" && state.stage !== "failed" && safety < 50) {
+    safety++;
+    const before = state.stage;
+
+    if (state.stage === "clarify") {
+      state = await stageClarify(state, input);
+      await saveState(input.session_id, state);
+      // If we asked the user questions, exit and wait for their answer.
+      if (state.pending_clarification) break;
+    } else if (state.stage === "plan") {
+      state = await stagePlan(state, input);
+      await saveState(input.session_id, state);
+    } else if (state.stage === "execute") {
+      state = await stageExecute(state, input);
+      await saveState(input.session_id, state);
+    } else if (state.stage === "verify") {
+      state = await stageVerify(state, input);
+      await saveState(input.session_id, state);
+    }
+
+    if (state.stage === before) break; // safety: no progress
+  }
+
+  return state;
+}
+
+// ─── Trigger detection ────────────────────────────────────────────────────────
+
+/**
+ * Heuristic: should this prompt go through build mode rather than the
+ * regular agent loop? Build-mode prompts are project-scoped — "build me",
+ * "create a", "design and implement", "make a full" — vs ad-hoc questions.
+ */
+export function isBuildPrompt(prompt: string): boolean {
+  const p = prompt.toLowerCase().trim();
+  if (p.length < 20) return false;
+  const triggers = [
+    /\bbuild\s+(me|a|an|the)\b/,
+    /\bcreate\s+(a|an|the|me)\s+(?:full|complete|whole|new)\b/,
+    /\bcreate\s+(?:a|an|the)\b.*\bfrom\s+scratch\b/,
+    /\bdesign\s+and\s+(?:implement|build|create)\b/,
+    /\bimplement\s+(?:a|an|the)\s+(?:full|complete|whole)\b/,
+    /\bmake\s+(?:a|an|the)\s+(?:full|complete|whole|new)\b/,
+    /\bproject\s+(?:from\s+scratch|to)\b/,
+    /\bsimulation\s+(?:with|using|of)\b/,
+    /\bbackend\s+(?:for|with|using)\b/,
+    /\bspec(?:ification)?\s+(?:for|of)\b/,
+    /\bend[- ]to[- ]end\b/,
+  ];
+  return triggers.some((re) => re.test(p));
+}