runcastle 1.0.25 → 1.0.27

package/index.js

@@ -21,19 +21,38 @@ __export(exports_paths, {
   worktreeDir: () => worktreeDir,
   sessionDir: () => sessionDir,
   sandboxBuildDir: () => sandboxBuildDir,
+  sameDataDir: () => sameDataDir,
+  projectWorktreesDir: () => projectWorktreesDir,
+  prodDataDir: () => prodDataDir,
   logsDir: () => logsDir,
   featureDocsRel: () => featureDocsRel,
   envPath: () => envPath,
+  devDataDir: () => devDataDir,
   dbPath: () => dbPath,
   dataDir: () => dataDir,
   configPath: () => configPath,
   burnCacheDir: () => burnCacheDir
 });
 import { homedir } from "os";
-import { join } from "path";
-function dataDir() {
+import { join, resolve } from "path";
+function prodDataDir() {
   return join(homedir(), ".runcastle");
 }
+function devDataDir() {
+  const override = process.env.RUNCASTLE_DEV_DATA_DIR;
+  return override ? resolve(override) : join(homedir(), ".runcastle-dev");
+}
+function dataDir() {
+  const override = process.env.RUNCASTLE_DATA_DIR;
+  return override ? resolve(override) : prodDataDir();
+}
+function sameDataDir(a, b) {
+  const canon = (p) => {
+    const abs = resolve(p).replace(/[\\/]+$/, "");
+    return process.platform === "win32" ? abs.toLowerCase().replace(/\//g, "\\") : abs;
+  };
+  return canon(a) === canon(b);
+}
 function dbPath() {
   return join(dataDir(), "runcastle.db");
 }
@@ -49,8 +68,11 @@ function logsDir() {
 function sessionDir(id) {
   return join(dataDir(), "sessions", id);
 }
+function projectWorktreesDir(projectId) {
+  return join(dataDir(), "worktrees", projectId);
+}
 function worktreeDir(projectId, slug) {
-  return join(dataDir(), "worktrees", projectId, slug);
+  return join(projectWorktreesDir(projectId), slug);
 }
 function burnCacheDir(pm) {
   return join(dataDir(), "cache", pm);
@@ -116,6 +138,7 @@ var init_config = __esm(() => {
     model: z.string().default("claude-opus-5"),
     stepModels: z.partialRecord(ModelStep, z.string()).default({ smoke: DEFAULT_SMOKE_MODEL }),
     sandbox: z.enum(["docker", "podman", "noSandbox"]).default("docker"),
+    sessionMcp: z.enum(["inherit", "runcastleOnly"]).default("inherit"),
     mainBranch: z.string().default("main"),
     sandboxImage: z.string().optional(),
     burnConcurrency: z.number().int().min(1).max(8).default(3),
@@ -157,6 +180,8 @@ function loadConfig(env = process.env) {
     overrides.smokeModel = env.RUNCASTLE_SMOKE_MODEL;
   if (env.RUNCASTLE_SANDBOX)
     overrides.sandbox = env.RUNCASTLE_SANDBOX;
+  if (env.RUNCASTLE_SESSION_MCP)
+    overrides.sessionMcp = env.RUNCASTLE_SESSION_MCP;
   if (env.RUNCASTLE_MAIN_BRANCH)
     overrides.mainBranch = env.RUNCASTLE_MAIN_BRANCH;
   if (env.RUNCASTLE_SANDBOX_IMAGE)
@@ -229,7 +254,7 @@ var init_schemas = __esm(() => {
     "shipped"
   ]);
   TicketStatus = z2.enum(["pending", "burning", "done", "failed", "cancelled"]);
-  SessionKind = z2.enum(["ideation", "qa", "waypoint", "converge", "revisit"]);
+  SessionKind = z2.enum(["ideation", "qa", "waypoint", "converge", "revisit", "prepare"]);
   RunStatus = z2.enum(["running", "succeeded", "failed", "cancelled"]);
   FeatureStatus = z2.enum(["active", "shipped", "archived"]);
   SessionStatus = z2.enum(["launching", "live", "ended"]);
@@ -246,6 +271,7 @@ var init_schemas = __esm(() => {
     featureId: z2.string(),
     seq: z2.number(),
     status: TicketStatus,
+    lap: z2.number(),
     commits: z2.array(z2.string()),
     error: z2.string().optional(),
     attemptBranch: z2.string().optional(),
@@ -276,10 +302,13 @@ var init_schemas = __esm(() => {
     "verifyCommands",
     "knownFailures",
     "devCommand",
+    "driveSetupCommand",
+    "driveStopCommand",
+    "driveEnv",
     "dbResetCommand"
   ];
   PreparedKey = z2.enum(PREPARED_KEYS);
-  FindingSource = z2.enum(["prep", "human"]);
+  FindingSource = z2.enum(["prep", "human", "session"]);
   Project = z2.object({
     id: z2.string(),
     name: z2.string(),
@@ -290,7 +319,10 @@ var init_schemas = __esm(() => {
     setupCommand: z2.string().optional(),
     verifyCommands: z2.string().optional(),
     knownFailures: z2.string().optional(),
-    dbResetCommand: z2.string().optional()
+    dbResetCommand: z2.string().optional(),
+    driveSetupCommand: z2.string().optional(),
+    driveStopCommand: z2.string().optional(),
+    driveEnv: z2.string().optional()
   });
   ProjectFinding = z2.object({
     key: PreparedKey,
@@ -317,6 +349,7 @@ var init_schemas = __esm(() => {
     title: z2.string(),
     oneLiner: z2.string(),
     mapped: z2.boolean(),
+    lap: z2.number(),
     phase: Phase,
     branch: z2.string(),
     baseBranch: z2.string().optional(),
@@ -325,7 +358,8 @@ var init_schemas = __esm(() => {
   });
   SessionRow = z2.object({
     id: z2.string(),
-    featureId: z2.string(),
+    featureId: z2.string().optional(),
+    projectId: z2.string().optional(),
     kind: SessionKind,
     ccSessionId: z2.string().optional(),
     transcriptPath: z2.string().optional(),
@@ -452,7 +486,7 @@ function nextGate(feature) {
     return MAPPED_G1;
   return gate;
 }
-var PIPELINE, ORDER, REVIEW_LOOP_BACK, MAPPED_G1;
+var PIPELINE, ORDER, REVIEW_LOOP_BACK, RETHINK_LOOP_BACK, MAPPED_G1;
 var init_pipeline = __esm(() => {
   PIPELINE = [
     { phase: "ideation" },
@@ -499,6 +533,7 @@ var init_pipeline = __esm(() => {
   ];
   ORDER = PIPELINE.map((p) => p.phase);
   REVIEW_LOOP_BACK = { from: "review", to: "implementation" };
+  RETHINK_LOOP_BACK = { from: "review", to: "ideation" };
   MAPPED_G1 = {
     id: "G1",
     description: "Every waypoint resolved or dropped before converging",
@@ -522,7 +557,10 @@ var init_db_schema = __esm(() => {
     setupCommand: text("setup_command"),
     verifyCommands: text("verify_commands"),
     knownFailures: text("known_failures"),
-    dbResetCommand: text("db_reset_command")
+    dbResetCommand: text("db_reset_command"),
+    driveSetupCommand: text("drive_setup_command"),
+    driveStopCommand: text("drive_stop_command"),
+    driveEnv: text("drive_env")
   });
   projectFindings = sqliteTable("project_findings", {
     projectId: text("project_id").notNull(),
@@ -548,6 +586,7 @@ var init_db_schema = __esm(() => {
     title: text("title").notNull(),
     oneLiner: text("one_liner").notNull(),
     mapped: integer("mapped", { mode: "boolean" }).notNull().default(false),
+    lap: integer("lap").notNull().default(1),
     phase: text("phase").notNull().$type(),
     branch: text("branch").notNull(),
     baseBranch: text("base_branch"),
@@ -556,7 +595,9 @@ var init_db_schema = __esm(() => {
   });
   sessions = sqliteTable("sessions", {
     id: text("id").primaryKey(),
-    featureId: text("feature_id").notNull(),
+    featureId: text("feature_id"),
+    projectId: text("project_id"),
+    lap: integer("lap").notNull().default(1),
     kind: text("kind").notNull().$type(),
     ccSessionId: text("cc_session_id"),
     transcriptPath: text("transcript_path"),
@@ -573,6 +614,7 @@ var init_db_schema = __esm(() => {
     acceptanceCriteria: text("acceptance_criteria", { mode: "json" }).notNull().$type(),
     seams: text("seams", { mode: "json" }).notNull().$type(),
     blockedBy: text("blocked_by", { mode: "json" }).notNull().$type(),
+    lap: integer("lap").notNull().default(1),
     status: text("status").notNull().$type(),
     commits: text("commits", { mode: "json" }).notNull().$type(),
     error: text("error"),
@@ -608,6 +650,7 @@ var init_db_schema = __esm(() => {
     featureId: text("feature_id"),
     runId: text("run_id"),
     ticketId: text("ticket_id"),
+    lap: integer("lap").notNull().default(1),
     ts: integer("ts").notNull(),
     type: text("type").notNull(),
     message: text("message").notNull(),
@@ -668,11 +711,11 @@ var init_client = __esm(() => {
 
 // src/launcher/asset-paths.ts
 import { existsSync as existsSync2 } from "fs";
-import { join as join3, resolve } from "path";
+import { join as join3, resolve as resolve2 } from "path";
 function resolveAsset(envVar, fallback) {
   const override = process.env[envVar];
   if (override) {
-    const abs = resolve(override);
+    const abs = resolve2(override);
     if (existsSync2(abs))
       return abs;
     throw new Error(`${envVar}=${override} does not exist (resolved ${abs})`);
@@ -1346,16 +1389,28 @@ function projectIdForFeature(ctx, featureId) {
     throw new NotFoundError(`feature ${featureId} not found`);
   return row.projectId;
 }
+function lapForFeature(ctx, featureId) {
+  const row = ctx.db.select({ lap: features.lap }).from(features).where(eq(features.id, featureId)).get();
+  return row?.lap ?? 1;
+}
 function emit(ctx, featureId, e) {
   return insertEvent(ctx, projectIdForFeature(ctx, featureId), featureId, e);
 }
 function emitProject(ctx, projectId, e) {
   return insertEvent(ctx, projectId, null, e);
 }
+function emitForSession(ctx, session, e) {
+  if (session.featureId)
+    return emit(ctx, session.featureId, e);
+  if (session.projectId)
+    return emitProject(ctx, session.projectId, e);
+  return null;
+}
 function insertEvent(ctx, projectId, featureId, e) {
   const row = ctx.db.insert(events).values({
     projectId,
     featureId,
+    lap: featureId ? lapForFeature(ctx, featureId) : 1,
     runId: e.runId ?? null,
     ticketId: e.ticketId ?? null,
     ts: Date.now(),
@@ -1396,6 +1451,7 @@ function rowToFeature(row) {
     title: row.title,
     oneLiner: row.oneLiner,
     mapped: row.mapped,
+    lap: row.lap,
     phase: row.phase,
     branch: row.branch,
     baseBranch: row.baseBranch ?? undefined,
@@ -1414,7 +1470,10 @@ function rowToProject(row) {
     setupCommand: row.setupCommand ?? undefined,
     verifyCommands: row.verifyCommands ?? undefined,
     knownFailures: row.knownFailures ?? undefined,
-    dbResetCommand: row.dbResetCommand ?? undefined
+    dbResetCommand: row.dbResetCommand ?? undefined,
+    driveSetupCommand: row.driveSetupCommand ?? undefined,
+    driveStopCommand: row.driveStopCommand ?? undefined,
+    driveEnv: row.driveEnv ?? undefined
   };
 }
 function rowToRun(row) {
@@ -1431,7 +1490,8 @@ function rowToRun(row) {
 function rowToSession(row) {
   return {
     id: row.id,
-    featureId: row.featureId,
+    featureId: row.featureId ?? undefined,
+    projectId: row.projectId ?? undefined,
     kind: row.kind,
     ccSessionId: row.ccSessionId ?? undefined,
     transcriptPath: row.transcriptPath ?? undefined,
@@ -1648,7 +1708,7 @@ function releaseForSession(ctx, claimant) {
   const held = ctx.db.select().from(waypoints).where(and3(eq3(waypoints.claimedBy, claimant), eq3(waypoints.status, "claimed"))).all().map(rowToWaypoint);
   return held.map((w) => release(ctx, w.id));
 }
-function resolve2(ctx, id, disposition, summary) {
+function resolve3(ctx, id, disposition, summary) {
   const wp = getWaypoint(ctx, id);
   const before = listByFeature(ctx, wp.featureId);
   const bySeqBefore = new Map(before.map((w) => [w.seq, w]));
@@ -1691,7 +1751,9 @@ import { and as and4, desc as desc2, eq as eq4, inArray, isNotNull, sql as sql2
 function createSessionRow(ctx, input) {
   const row = ctx.db.insert(sessions).values({
     id: newId("sess"),
-    featureId: input.featureId,
+    featureId: input.featureId ?? null,
+    projectId: input.projectId ?? null,
+    lap: input.featureId ? getFeatureRow(ctx, input.featureId).lap : 1,
     kind: input.kind,
     ccSessionId: null,
     transcriptPath: null,
@@ -1723,6 +1785,9 @@ function markSessionLive(ctx, id, input = {}) {
   }
   return getSessionRow(ctx, id);
 }
+function lapKickoff(lap) {
+  return `Proceed with your task: invoke the /runcastle:revisit skill for LAP ${lap} REVIEW ITERATION. ` + `Call get_feature_context, then read this feature's test-notes.md (the "## Lap ${lap - 1}" ` + 'section \u2014 what the last drive surfaced) and the "## Later laps" section of its spec.md. ' + "EITHER MAY NOT EXIST YET; that is normal, not an error \u2014 say so and carry on from what I " + "tell you. Interview me about what the test drive taught: what was wrong, what was missing, " + "what I want next. Write what we settle on into decisions.md and amend spec.md for this lap " + '(pruning anything you promote out of "## Later laps"), then call emit_tickets for this ' + `lap's work. Finish in THIS session: complete_phase through ideation \u2192 spec \u2192 tickets, then ` + "tell me to review the cards and click Burn.";
+}
 function kickoffLineFor(kind, override) {
   return override ?? KICKOFF_LINES[kind];
 }
@@ -1788,7 +1853,7 @@ function attemptKickoff(ctx, session, d, delayMs, clearFirst = false) {
       writeKickoffSequence(d.line, {
         write: io.write,
         alive: io.alive,
-        onSubmitted: () => emit(ctx, session.featureId, {
+        onSubmitted: () => emitForSession(ctx, session, {
           type: "session.kickoff",
           message: attempt === 1 ? `${session.kind} session kicked off automatically` : `${session.kind} kickoff re-sent (attempt ${attempt}) \u2014 the first was never acknowledged`,
           data: { sessionId: session.id, kind: session.kind, attempt }
@@ -1812,7 +1877,7 @@ function armConfirmation(ctx, session, d) {
 function settleUndelivered(ctx, session, d, reason) {
   d.settled = true;
   stopTimers(d);
-  emit(ctx, session.featureId, {
+  emitForSession(ctx, session, {
     type: "session.kickoff_undelivered",
     message: reason === "superseded" ? `the ${session.kind} briefing was never delivered \u2014 you typed first, so runcastle stopped injecting it` : `the ${session.kind} briefing was typed ${d.attempts}\xD7 but Claude Code never acknowledged it \u2014 send it again from the session strip`,
     data: { sessionId: session.id, kind: session.kind, reason, attempts: d.attempts, line: d.line }
@@ -1876,7 +1941,7 @@ function armSessionReadyWatchdog(ctx, session) {
       return;
     if (!ptyIo(session.id).alive())
       return;
-    emit(ctx, session.featureId, {
+    emitForSession(ctx, session, {
       type: "session.not_ready",
       message: `the ${session.kind} terminal is open but Claude Code has not reported ready \u2014 check it for a prompt or dialog waiting on you, then send the briefing`,
       data: { sessionId: session.id, kind: session.kind }
@@ -1906,6 +1971,14 @@ function mostRecentResumableSession(ctx, featureId, kind) {
   const row = ctx.db.select().from(sessions).where(and4(eq4(sessions.featureId, featureId), eq4(sessions.status, "ended"), isNotNull(sessions.ccSessionId), ...kind ? [eq4(sessions.kind, kind)] : [])).orderBy(desc2(sql2`rowid`)).limit(1).get();
   return row ? rowToSession(row) : null;
 }
+function activeProjectSession(ctx, projectId, kind) {
+  const row = ctx.db.select().from(sessions).where(and4(eq4(sessions.projectId, projectId), eq4(sessions.kind, kind), inArray(sessions.status, ["launching", "live"]))).orderBy(desc2(sql2`rowid`)).limit(1).get();
+  return row ? rowToSession(row) : null;
+}
+function mostRecentResumableProjectSession(ctx, projectId, kind) {
+  const row = ctx.db.select().from(sessions).where(and4(eq4(sessions.projectId, projectId), eq4(sessions.kind, kind), eq4(sessions.status, "ended"), isNotNull(sessions.ccSessionId))).orderBy(desc2(sql2`rowid`)).limit(1).get();
+  return row ? rowToSession(row) : null;
+}
 function mostRecentLiveSession(ctx) {
   const row = ctx.db.select().from(sessions).where(eq4(sessions.status, "live")).orderBy(desc2(sql2`rowid`)).limit(1).get();
   return row ? rowToSession(row) : null;
@@ -1924,7 +1997,8 @@ var init_sessions = __esm(() => {
     qa: "Proceed with your task: invoke the /runcastle:qa skill and answer questions from the " + "docs and code \u2014 do not advance phases or emit tickets.",
     waypoint: "Proceed with your task: invoke the /runcastle:waypoint skill and work your assigned " + "waypoint to a resolution.",
     converge: CONVERGE_KICKOFF_LINE,
-    revisit: "Proceed with your task: invoke the /runcastle:revisit skill and work through what the " + "human brings up."
+    revisit: "Proceed with your task: invoke the /runcastle:revisit skill and work through what the " + "human brings up.",
+    prepare: "Proceed with your task: work through the unestablished preparation fields with the human. " + "Start by telling them which fields are still open and what you need from them for each; " + "ask before running anything that touches their database or services."
   };
   RESUME_KICKOFF_PREFIX = "We are picking this conversation back up \u2014 runcastle restarted and closed the terminal, " + "but this conversation is intact. Do NOT start over: tell me in one or two lines where we " + "left off and what is next, then carry on. Your original instruction was: ";
   pendingKickoffOverrides = new Map;
@@ -1942,7 +2016,7 @@ function reconcileStaleSessions(ctx) {
       continue;
     markSessionEnded(ctx, session.id);
     const released = releaseForSession(ctx, session.id);
-    emit(ctx, session.featureId, {
+    emitForSession(ctx, session, {
       type: "session.reconciled",
       message: `session marked ended at boot \u2014 the server restarted while it was ${session.status}`,
       data: {
@@ -1966,11 +2040,11 @@ var init_reconcile = __esm(() => {
 
 // src/launcher/skills-root.ts
 import { existsSync as existsSync5 } from "fs";
-import { dirname, join as join5, resolve as resolve3 } from "path";
+import { dirname, join as join5, resolve as resolve4 } from "path";
 function resolveSkillsRoot(fromDir) {
   const override = process.env[SKILLS_DIR_ENV];
   if (override) {
-    const root = resolve3(override);
+    const root = resolve4(override);
     if (existsSync5(join5(root, SKILLS_MARKER)))
       return root;
     throw new Error(`${SKILLS_DIR_ENV}=${override} is not a runcastle skills root (missing ${SKILLS_MARKER})`);
@@ -2011,7 +2085,7 @@ function devSpawnTarget(devCommand) {
   return { file: "/bin/sh", args: ["-c", devCommand] };
 }
 function startDevPane(input) {
-  const { ctx, featureId, repoPath, devCommand, onUrl } = input;
+  const { ctx, featureId, repoPath, devCommand, env, onUrl } = input;
   const paneId = drivePaneId(featureId);
   const { file, args } = devSpawnTarget(devCommand);
   try {
@@ -2019,7 +2093,7 @@ function startDevPane(input) {
       sessionId: paneId,
       cmd: file,
       args,
-      opts: { cwd: repoPath, env: process.env, cols: 80, rows: 24, useConpty: true }
+      opts: { cwd: repoPath, env: env ?? process.env, cols: 80, rows: 24, useConpty: true }
     });
   } catch (err) {
     emit(ctx, featureId, {
@@ -2069,10 +2143,179 @@ var init_dev_pane = __esm(() => {
   init_registry();
 });
 
+// src/services/drive-hooks.ts
+import { spawn as spawn2 } from "child_process";
+function tailLines(text2, max = OUTPUT_TAIL_LINES) {
+  const lines = text2.replace(/\r\n/g, `
+`).split(`
+`);
+  while (lines.length > 0 && lines[lines.length - 1]?.trim() === "")
+    lines.pop();
+  return lines.slice(-max).join(`
+`).trim();
+}
+function hookSpawnTarget(command) {
+  if (process.platform === "win32") {
+    return {
+      file: process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/c", `"${command}"`],
+      verbatim: true
+    };
+  }
+  return { file: "/bin/sh", args: ["-c", command], verbatim: false };
+}
+function runDriveHook(command, opts) {
+  const spawnFn = opts.spawnFn ?? spawn2;
+  const now = opts.now ?? Date.now;
+  const timeoutMs = opts.timeoutMs ?? DRIVE_HOOK_TIMEOUT_MS;
+  const startedAt = now();
+  const { file, args, verbatim } = hookSpawnTarget(command);
+  return new Promise((resolve5) => {
+    let output = "";
+    let timedOut = false;
+    let settled = false;
+    let timer;
+    const finish = (exitCode) => {
+      if (settled)
+        return;
+      settled = true;
+      if (timer)
+        clearTimeout(timer);
+      resolve5({
+        ok: !timedOut && exitCode === 0,
+        exitCode,
+        timedOut,
+        output: tailLines(output),
+        durationMs: now() - startedAt
+      });
+    };
+    let child;
+    try {
+      child = spawnFn(file, args, {
+        cwd: opts.cwd,
+        env: opts.env ?? process.env,
+        windowsHide: true,
+        windowsVerbatimArguments: verbatim
+      });
+    } catch (err) {
+      output = err instanceof Error ? err.message : String(err);
+      finish(null);
+      return;
+    }
+    timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+      const grace = setTimeout(() => finish(null), KILL_GRACE_MS);
+      grace.unref?.();
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on("data", (d) => {
+      output += d.toString();
+    });
+    child.stderr?.on("data", (d) => {
+      output += d.toString();
+    });
+    child.on("error", (err) => {
+      output += `
+${err instanceof Error ? err.message : String(err)}`;
+      finish(null);
+    });
+    child.on("close", (code) => {
+      finish(code);
+    });
+  });
+}
+function describeHookResult(command, result) {
+  const secs = Math.max(1, Math.round(result.durationMs / 1000));
+  if (result.timedOut)
+    return `\`${command}\` timed out after ${secs}s`;
+  if (result.ok)
+    return `\`${command}\` finished in ${secs}s`;
+  return `\`${command}\` exited ${result.exitCode ?? "without a code"} after ${secs}s`;
+}
+var DRIVE_HOOK_TIMEOUT_MS, OUTPUT_TAIL_LINES = 40, KILL_GRACE_MS = 2000;
+var init_drive_hooks = __esm(() => {
+  DRIVE_HOOK_TIMEOUT_MS = 10 * 60000;
+});
+
+// src/services/drive-env.ts
+import { createHash } from "crypto";
+function identifierSafe(slug, max = MAX_ID_LENGTH) {
+  const cleaned = slug.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  const safe = cleaned === "" || /^[0-9]/.test(cleaned) ? `x_${cleaned}` : cleaned;
+  if (safe.length <= max)
+    return safe;
+  const digest = createHash("sha1").update(slug).digest("hex").slice(0, 6);
+  return `${safe.slice(0, max - digest.length - 1)}_${digest}`;
+}
+function driveVars(identity) {
+  return {
+    slug: identity.slug,
+    branch: identity.branch,
+    id: identifierSafe(identity.slug)
+  };
+}
+function renderTemplate(value, vars) {
+  const unknown2 = [];
+  const out = value.replace(PLACEHOLDER_RE, (match, name) => {
+    const replacement = vars[name];
+    if (replacement === undefined) {
+      if (!unknown2.includes(name))
+        unknown2.push(name);
+      return match;
+    }
+    return replacement;
+  });
+  return { value: out, unknown: unknown2 };
+}
+function parseDriveEnv(raw, identity) {
+  const vars = {};
+  const unknown2 = [];
+  if (!raw?.trim())
+    return { vars, unknown: unknown2 };
+  const substitutions = driveVars(identity);
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#"))
+      continue;
+    const eq5 = trimmed.indexOf("=");
+    if (eq5 <= 0)
+      continue;
+    const key = trimmed.slice(0, eq5).trim().replace(/^export\s+/, "");
+    if (key === "")
+      continue;
+    const rendered = renderTemplate(unquote(trimmed.slice(eq5 + 1).trim()), substitutions);
+    vars[key] = rendered.value;
+    for (const name of rendered.unknown)
+      if (!unknown2.includes(name))
+        unknown2.push(name);
+  }
+  return { vars, unknown: unknown2 };
+}
+function unquote(value) {
+  if (value.length < 2)
+    return value;
+  const first = value[0];
+  if ((first === '"' || first === "'") && value.endsWith(first))
+    return value.slice(1, -1);
+  return value;
+}
+function driveProcessEnv(overrides, base = process.env) {
+  return { ...base, ...overrides };
+}
+function describeDriveEnv(vars) {
+  const keys = Object.keys(vars);
+  return `drive environment: ${keys.join(", ")}`;
+}
+var MAX_ID_LENGTH = 40, PLACEHOLDER_RE;
+var init_drive_env = __esm(() => {
+  PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+});
+
 // src/services/git.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync2, mkdtempSync, realpathSync, rmSync } from "fs";
 import { tmpdir } from "os";
-import { dirname as dirname2, join as join6, resolve as resolve4 } from "path";
+import { dirname as dirname2, join as join6, resolve as resolve5 } from "path";
 import { simpleGit } from "simple-git";
 function migrationPaths(paths) {
   return paths.filter((p) => MIGRATION_DIR_RE.test(p) || DRIZZLE_SQL_RE.test(p));
@@ -2087,7 +2330,7 @@ function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
 function canon(p) {
-  let abs = resolve4(p);
+  let abs = resolve5(p);
   try {
     abs = realpathSync.native(abs);
   } catch {}
@@ -2582,7 +2825,7 @@ async function deleteFeatureBranches(repoPath, slug) {
   return { deleted, kept };
 }
 async function commitDocs(worktreePath, message) {
-  if (!existsSync6(resolve4(worktreePath, DOCS_PATHSPEC)))
+  if (!existsSync6(resolve5(worktreePath, DOCS_PATHSPEC)))
     return;
   const g = git(worktreePath);
   await g.add([DOCS_PATHSPEC]);
@@ -2627,6 +2870,7 @@ async function testDrive(ctx, project, feature, action) {
     const devPaneId = testDriveState.devPaneId;
     if (devPaneId)
       stopDevPane(devPaneId);
+    const teardownFailure = await runDriveHookStep(ctx, feature.id, project.repoPath, "teardown", project.driveStopCommand, driveEnvFor(ctx, project, feature, branch));
     const carriedChanges = await dirtyPaths(g);
     await g.checkout(previousBranch2);
     if (detachedWorktree2)
@@ -2649,7 +2893,8 @@ async function testDrive(ctx, project, feature, action) {
       ok: true,
       branch: previousBranch2,
       ...carriedChanges.length > 0 ? { carriedChanges } : {},
-      ...dbDrift ? { dbDrift } : {}
+      ...dbDrift ? { dbDrift } : {},
+      ...teardownFailure ? { hookFailure: teardownFailure } : {}
     };
   }
   const porcelain = (await g.raw(["status", "--porcelain"])).trim();
@@ -2674,18 +2919,76 @@ async function testDrive(ctx, project, feature, action) {
     message: `test driving ${branch} (was on ${previousBranch})`,
     data: { branch, previousBranch }
   });
+  const driveEnv = driveEnvFor(ctx, project, feature, branch);
+  const setupFailure = await runDriveHookStep(ctx, feature.id, project.repoPath, "setup", project.driveSetupCommand, driveEnv);
   if (project.devCommand) {
     const devPaneId = startDevPane({
       ctx,
       featureId: feature.id,
       repoPath: project.repoPath,
       devCommand: project.devCommand,
+      env: driveEnv,
       onUrl: (url) => recordDriveUrl(ctx, feature.id, url)
     });
     if (devPaneId)
       testDriveState.devPaneId = devPaneId;
   }
-  return { ok: true, branch };
+  return { ok: true, branch, ...setupFailure ? { hookFailure: setupFailure } : {} };
+}
+function driveEnvFor(ctx, project, feature, branch) {
+  const { vars, unknown: unknown2 } = parseDriveEnv(project.driveEnv, { slug: feature.slug, branch });
+  if (unknown2.length > 0) {
+    emit(ctx, feature.id, {
+      type: "testdrive.env_unknown_placeholder",
+      message: `drive environment left ${unknown2.map((u) => `{{${u}}}`).join(", ")} unsubstituted \u2014 known variables are {{slug}}, {{branch}}, {{id}}`,
+      data: { unknown: unknown2 }
+    });
+  }
+  if (Object.keys(vars).length > 0) {
+    emit(ctx, feature.id, {
+      type: "testdrive.env",
+      message: describeDriveEnv(vars),
+      data: { keys: Object.keys(vars) }
+    });
+  }
+  return driveProcessEnv(vars);
+}
+async function runDriveHookStep(ctx, featureId, repoPath, phase, command, env) {
+  const cmd = command?.trim();
+  if (!cmd)
+    return;
+  emit(ctx, featureId, {
+    type: `testdrive.${phase}_started`,
+    message: phase === "setup" ? `preparing environment: \`${cmd}\`` : `tearing down environment: \`${cmd}\``,
+    data: { command: cmd }
+  });
+  const result = await runDriveHook(cmd, { cwd: repoPath, env });
+  if (result.ok) {
+    emit(ctx, featureId, {
+      type: `testdrive.${phase}_ok`,
+      message: describeHookResult(cmd, result),
+      data: { command: cmd, durationMs: result.durationMs }
+    });
+    return;
+  }
+  emit(ctx, featureId, {
+    type: `testdrive.${phase}_failed`,
+    message: `${describeHookResult(cmd, result)}${result.output ? `
+${result.output}` : ""}`,
+    data: {
+      command: cmd,
+      exitCode: result.exitCode,
+      timedOut: result.timedOut,
+      output: result.output
+    }
+  });
+  return {
+    phase,
+    command: cmd,
+    exitCode: result.exitCode,
+    timedOut: result.timedOut,
+    output: result.output
+  };
 }
 async function dirtyPaths(g) {
   try {
@@ -2776,6 +3079,8 @@ var init_git = __esm(() => {
   init_paths();
   init_errors();
   init_dev_pane();
+  init_drive_hooks();
+  init_drive_env();
   init_events();
   init_repo();
   MIGRATION_DIR_RE = /(^|\/)(migrations|migrate)\//i;
@@ -2961,7 +3266,7 @@ function detectCycle(tickets2) {
   }
   return null;
 }
-function renderTemplate(template, values) {
+function renderTemplate2(template, values) {
   let out = template;
   for (const [key, value] of Object.entries(values)) {
     out = out.split(`{{${key}}}`).join(value);
@@ -2969,7 +3274,7 @@ function renderTemplate(template, values) {
   return out;
 }
 function renderTicketPrompt(template, values) {
-  return renderTemplate(template, values);
+  return renderTemplate2(template, values);
 }
 function buildTicketJson(ticket) {
   return JSON.stringify({
@@ -3057,6 +3362,9 @@ function detectPackageManager(tc) {
     return "npm";
   return tc.hasPackageJson ? "npm" : undefined;
 }
+function orFallback(strict, permissive) {
+  return `( ${strict} || ${permissive} )`;
+}
 function resolveSetupCommand(tc, override) {
   const trimmed = override?.trim();
   if (trimmed)
@@ -3066,13 +3374,13 @@ function resolveSetupCommand(tc, override) {
     return;
   switch (pm) {
     case "bun":
-      return tc.lockfiles.bun ? "bun install --frozen-lockfile" : "bun install";
+      return tc.lockfiles.bun ? orFallback("bun install --frozen-lockfile", "bun install") : "bun install";
     case "pnpm":
-      return tc.lockfiles.pnpm ? "corepack pnpm install --frozen-lockfile" : "corepack pnpm install";
+      return tc.lockfiles.pnpm ? orFallback("corepack pnpm install --frozen-lockfile", "corepack pnpm install") : "corepack pnpm install";
     case "yarn":
-      return tc.lockfiles.yarn ? "corepack yarn install --frozen-lockfile" : "corepack yarn install";
+      return tc.lockfiles.yarn ? orFallback("corepack yarn install --frozen-lockfile", "corepack yarn install") : "corepack yarn install";
     case "npm":
-      return tc.lockfiles.npm ? "npm ci" : "npm install";
+      return tc.lockfiles.npm ? orFallback("npm ci", "npm install") : "npm install";
   }
 }
 function cacheMountFor(pm, hostPath) {
@@ -3156,7 +3464,7 @@ function readRepoToolchain(repoPath) {
     }
   };
 }
-function createStreamThrottle(emit2, opts = {}) {
+function createStreamThrottle(emit3, opts = {}) {
   const intervalMs = opts.intervalMs ?? 2000;
   const maxChars = opts.maxChars ?? 500;
   const now = opts.now ?? Date.now;
@@ -3166,7 +3474,7 @@ function createStreamThrottle(emit2, opts = {}) {
   const flushText = () => {
     if (buffer.length === 0)
       return;
-    emit2({ type: "burn.text", message: buffer, data: { iteration: lastIteration } });
+    emit3({ type: "burn.text", message: buffer, data: { iteration: lastIteration } });
     buffer = "";
     lastFlush = now();
   };
@@ -3181,7 +3489,7 @@ function createStreamThrottle(emit2, opts = {}) {
       flushText();
       const rawArgs = event.formattedArgs ?? "";
       const args = rawArgs.length > 200 ? `${rawArgs.slice(0, 200)}\u2026` : rawArgs;
-      emit2({
+      emit3({
         type: "burn.tool",
         message: args.length > 0 ? `${event.name} ${args}` : event.name,
         data: { name: event.name, args: rawArgs, iteration: event.iteration }
@@ -3293,18 +3601,18 @@ function buildRetryNotes(input) {
 `);
 }
 function delayUnlessAborted(ms, signal) {
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     if (signal.aborted) {
-      resolve5();
+      resolve6();
       return;
     }
     const onAbort = () => {
       clearTimeout(t);
-      resolve5();
+      resolve6();
     };
     const t = setTimeout(() => {
       signal.removeEventListener("abort", onAbort);
-      resolve5();
+      resolve6();
     }, ms);
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -3658,7 +3966,7 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
   const runResolver = async (input) => {
     const resolveBranch = ticketBranchName(feature.slug, ticket.seq, newId("r").slice(2, 10));
     const otherSide = await commitSummaries(project.repoPath, input.branch, feature.branch);
-    const prompt = renderTemplate(readFileSync3(resolverTemplatePath(), "utf8"), {
+    const prompt = renderTemplate2(readFileSync3(resolverTemplatePath(), "utf8"), {
       TICKET_JSON: ticketJson,
       FEATURE_BRIEF: featureBrief,
       DOCS_DIGEST: docsDigest,
@@ -4138,8 +4446,11 @@ function errorHeadline2(s) {
   const causes = lines.filter((l) => /^(fatal|error):/i.test(l));
   return causes.at(-1) ?? lines[0] ?? "";
 }
-function createPrepStreamThrottle(emit2, opts = {}) {
-  return createStreamThrottle((e) => emit2({ ...e, type: e.type.replace(/^burn\./, "prep.") }), opts);
+function createPrepStreamThrottle(emit3, opts = {}) {
+  return createStreamThrottle((e) => emit3({ ...e, type: e.type.replace(/^burn\./, "prep.") }), opts);
+}
+function nonFatalSetup(setupCommand) {
+  return `( ${setupCommand} || true )`;
 }
 function prepTemplatePath() {
   const here = dirname4(fileURLToPath3(import.meta.url));
@@ -4172,10 +4483,11 @@ async function realExecutePrepRun(ctx, config2, token, model) {
   if (setupCommand) {
     ctx.emitEvent({
       type: "prep.setup",
-      message: `installing deps before the agent starts: ${setupCommand}`
+      message: `attempting a dependency install before the agent starts (best-effort): ${setupCommand}`
     });
   }
-  const hookCommand = workspaceMode === "isolated" ? buildIsolatedSetupCommand(branch, setupCommand, pm) : setupCommand;
+  const prepSetupCommand = setupCommand ? nonFatalSetup(setupCommand) : undefined;
+  const hookCommand = workspaceMode === "isolated" ? buildIsolatedSetupCommand(branch, prepSetupCommand, pm) : prepSetupCommand;
   const runOptions = {
     agent: buildBurnAgent(config2, token, model),
     sandbox: selectSandbox(config2, mounts),
@@ -4275,6 +4587,9 @@ var init_project_prep = __esm(() => {
     verifyCommands: "**`verifyCommands`** \u2014 the exact typecheck / test / lint commands for this repo, one per line. In a monorepo these must include the correct workspace filter names. Run each one and confirm it executes the thing it claims to.",
     knownFailures: '**`knownFailures`** \u2014 which tests are ALREADY failing on this checkout, before anything is changed. Run the full suite once and report the count plus the failing suite names. "0 known failures" is a real, useful answer.',
     devCommand: "**`devCommand`** \u2014 the command that starts this project's dev server on a developer's own machine. Read it from config; do not run it here.",
+    driveSetupCommand: "**`driveSetupCommand`** \u2014 a single shell command that takes this repo from a fresh checkout to \"the dev server would actually work\": backing services up, schema applied, whatever this project needs. Chain steps with `&&`. Read it from the repo's own config (compose file, Makefile, package scripts, README); do not run it here. Omit it if the dev command alone is enough \u2014 an empty answer is better than a guessed one, because this runs on a developer's real machine.",
+    driveStopCommand: "**`driveStopCommand`** \u2014 the matching teardown for `driveSetupCommand`, if this project has one (`docker compose down`, a stop script). Read it from config; do not run it here. Omit it if setup leaves nothing that needs stopping.",
+    driveEnv: "**`driveEnv`** \u2014 `KEY=VALUE` lines (one per line) overlaid on the dev server's environment during a test drive, with `{{slug}}`, `{{branch}}` and `{{id}}` (an identifier-safe slug) rendered per drive. Its purpose is giving a branch its own database, e.g. `DATABASE_URL=postgres://localhost:5432/myapp_{{id}}` paired with a `driveSetupCommand` that creates it. Report it ONLY if you can read the real connection variable's name and shape out of the repo's own config or `.env.example`; a connection string you assembled from defaults points at the wrong database convincingly, which is worse than omitting the key. Omit it if the project has no database or you had to guess the host, port or credentials.",
     dbResetCommand: "**`dbResetCommand`** \u2014 the command that rebuilds the dev database from the migrations currently in the working tree. Read it from config; do not run it here. Omit it entirely if this repo has no database."
   };
 });
@@ -4381,6 +4696,9 @@ var init_findings = __esm(() => {
     verifyCommands: projects.verifyCommands,
     knownFailures: projects.knownFailures,
     devCommand: projects.devCommand,
+    driveSetupCommand: projects.driveSetupCommand,
+    driveStopCommand: projects.driveStopCommand,
+    driveEnv: projects.driveEnv,
     dbResetCommand: projects.dbResetCommand
   };
   COLUMN_NAME = {
@@ -4388,13 +4706,16 @@ var init_findings = __esm(() => {
     verifyCommands: "verifyCommands",
     knownFailures: "knownFailures",
     devCommand: "devCommand",
+    driveSetupCommand: "driveSetupCommand",
+    driveStopCommand: "driveStopCommand",
+    driveEnv: "driveEnv",
     dbResetCommand: "dbResetCommand"
   };
   PREPARED_SET = new Set(PREPARED_KEYS);
 });
 
 // src/services/prep.ts
-import { desc as desc3, eq as eq6 } from "drizzle-orm";
+import { and as and6, desc as desc3, eq as eq6 } from "drizzle-orm";
 function isPreparing(projectId) {
   return controllers.has(projectId);
 }
@@ -4403,6 +4724,13 @@ function keysToPrepare(ctx, project, opts = {}) {
   const candidates = opts.keys ?? (opts.refresh ? PREPARED_KEYS : [...unset]);
   return candidates.filter((key) => (opts.refresh || unset.has(key)) && isOverwritable(ctx, project.id, key));
 }
+function shouldAutoPrepare(ctx, project) {
+  if (!ctx.config.autoPrepare)
+    return false;
+  if (latestPrep(ctx, project.id))
+    return false;
+  return keysToPrepare(ctx, project).length > 0;
+}
 async function startPrep(ctx, projectId, opts = {}) {
   const project = requireProjectById(ctx, projectId);
   if (controllers.has(projectId)) {
@@ -4522,6 +4850,11 @@ function latestPrep(ctx, projectId) {
     ...row.headSha !== null ? { headSha: row.headSha } : {}
   };
 }
+function latestPrepNotes(ctx, projectId) {
+  const row = ctx.db.select({ data: events.data }).from(events).where(and6(eq6(events.projectId, projectId), eq6(events.type, "prep.notes"))).orderBy(desc3(events.id)).get();
+  const notes = row?.data?.notes;
+  return typeof notes === "string" && notes.trim() !== "" ? notes : undefined;
+}
 function reconcilePreps(ctx) {
   const stale = ctx.db.select({ id: projectPreps.id, projectId: projectPreps.projectId }).from(projectPreps).where(eq6(projectPreps.status, "running")).all().filter((row) => !controllers.has(row.projectId));
   for (const row of stale) {
@@ -4576,7 +4909,7 @@ var init_feature_docs = __esm(() => {
 });
 
 // src/services/tickets.ts
-import { and as and6, asc as asc3, eq as eq7 } from "drizzle-orm";
+import { and as and7, asc as asc3, eq as eq7 } from "drizzle-orm";
 function rowToTicket(row) {
   return {
     id: row.id,
@@ -4588,6 +4921,7 @@ function rowToTicket(row) {
     acceptanceCriteria: row.acceptanceCriteria,
     seams: row.seams,
     blockedBy: row.blockedBy,
+    lap: row.lap,
     status: row.status,
     commits: row.commits,
     error: row.error ?? undefined,
@@ -4610,6 +4944,7 @@ function listByFeature2(ctx, featureId) {
 function storeTickets(ctx, featureId, inputs) {
   if (inputs.length === 0)
     return [];
+  const { lap } = getFeatureRow(ctx, featureId);
   const existing = ctx.db.select({ seq: tickets.seq }).from(tickets).where(eq7(tickets.featureId, featureId)).all();
   const startSeq = existing.reduce((max, r) => Math.max(max, r.seq), 0) + 1;
   const resolved = resolveBlocking(inputs, startSeq);
@@ -4623,6 +4958,7 @@ function storeTickets(ctx, featureId, inputs) {
     acceptanceCriteria: t.acceptanceCriteria,
     seams: t.seams,
     blockedBy: resolved[i].blockedBy,
+    lap,
     status: "pending",
     commits: [],
     error: null,
@@ -4687,7 +5023,7 @@ function cancelTicket(ctx, id, reason) {
   return getTicket(ctx, id);
 }
 function sweepOrphanedBurning(ctx, featureId, reason) {
-  const orphaned = ctx.db.select().from(tickets).where(and6(eq7(tickets.featureId, featureId), eq7(tickets.status, "burning"))).all().map(rowToTicket);
+  const orphaned = ctx.db.select().from(tickets).where(and7(eq7(tickets.featureId, featureId), eq7(tickets.status, "burning"))).all().map(rowToTicket);
   for (const t of orphaned) {
     updateTicket(ctx, t.id, { status: "failed", error: reason });
     emit(ctx, featureId, {
@@ -4730,6 +5066,7 @@ var init_tickets = __esm(() => {
   init_schema();
   init_errors();
   init_events();
+  init_repo();
   MUTABLE_STATUSES = new Set(["pending", "failed"]);
 });
 
@@ -4753,7 +5090,7 @@ function checkGate(ctx, check, feature) {
     case "spec-file-exists":
       return fileGate(ctx, feature, "spec.md", "write the spec (spec.md) before breaking into tickets");
     case "tickets-approved": {
-      const count = listByFeature2(ctx, feature.id).filter((t) => t.status !== "cancelled").length;
+      const count = listByFeature2(ctx, feature.id).filter((t) => t.lap === feature.lap && t.status !== "cancelled").length;
       return count >= 1 ? { satisfied: true } : { satisfied: false, reason: "no tickets to burn" };
     }
     case "all-tickets-terminal": {
@@ -4810,7 +5147,7 @@ var init_gates = __esm(() => {
 
 // src/services/knowledge.ts
 import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync5, readdirSync as readdirSync3, writeFileSync } from "fs";
-import { join as join10, relative, resolve as resolve5, sep } from "path";
+import { join as join10, relative, resolve as resolve6, sep } from "path";
 function scaffoldDocs(ctx, feature) {
   const project = projectForFeature(ctx, feature);
   const dir = featureDocsDir(project, feature);
@@ -4870,8 +5207,8 @@ function listDocs(ctx, feature) {
 function readDoc(ctx, feature, relPath) {
   const project = projectForFeature(ctx, feature);
   const dir = featureDocsDir(project, feature);
-  const root = resolve5(dir);
-  const target = resolve5(dir, relPath);
+  const root = resolve6(dir);
+  const target = resolve6(dir, relPath);
   const rel = relative(root, target);
   if (rel === "" || rel.startsWith("..") || rel.split(sep).includes("..")) {
     throw new InvalidInputError(`doc path escapes the feature docs dir: ${relPath}`);
@@ -4912,7 +5249,7 @@ function endSession(ctx, sessionId) {
   const session = markSessionEnded(ctx, sessionId);
   if (session) {
     releaseForSession(ctx, sessionId);
-    emit(ctx, session.featureId, {
+    emitForSession(ctx, session, {
       type: "session.ended",
       message: "session ended by user",
       data: { sessionId, killed }
@@ -4984,8 +5321,8 @@ function errorHeadline3(s) {
   const causes = lines.filter((l) => /^(fatal|error):/i.test(l));
   return causes.at(-1) ?? lines[0] ?? "";
 }
-function createResearchStreamThrottle(emit2, opts = {}) {
-  return createStreamThrottle((e) => emit2({ ...e, type: e.type.replace(/^burn\./, "research.") }), opts);
+function createResearchStreamThrottle(emit3, opts = {}) {
+  return createStreamThrottle((e) => emit3({ ...e, type: e.type.replace(/^burn\./, "research.") }), opts);
 }
 function renderResearchPrompt(template, values) {
   let out = template;
@@ -5193,7 +5530,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
     input: opts.input,
     modelOverride: opts.modelOverride,
     resolveWaypoint: (id, disposition, summary) => {
-      resolve2(ctx, id, disposition, summary);
+      resolve3(ctx, id, disposition, summary);
     },
     signal: controller.signal
   };
@@ -5288,6 +5625,7 @@ async function createFeature(ctx, input) {
     title: input.title,
     oneLiner: input.oneLiner,
     mapped: false,
+    lap: 1,
     phase: "ideation",
     branch,
     baseBranch,
@@ -5372,7 +5710,8 @@ async function burn(ctx, featureId, opts = {}) {
   const feature = getFeatureRow(ctx, featureId);
   const running = hasActiveRun(ctx, featureId);
   let tickets2 = listByFeature2(ctx, featureId);
-  const pending = tickets2.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
+  const lapTickets = tickets2.filter((t) => t.lap === feature.lap);
+  const pending = lapTickets.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
   const restarting = feature.phase === "implementation" && !running;
   const iterating = feature.phase === "review" && !running && pending.length >= 1;
   if (feature.phase !== "tickets" && !restarting && !iterating) {
@@ -5385,8 +5724,8 @@ async function burn(ctx, featureId, opts = {}) {
       why = `feature must be in the tickets phase to burn (currently ${feature.phase})`;
     throw new GateError(why);
   }
-  if (tickets2.filter((t) => t.status !== "cancelled").length < 1) {
-    throw new GateError(tickets2.length > 0 ? "no burnable tickets \u2014 every ticket is cancelled" : "no tickets to burn");
+  if (lapTickets.filter((t) => t.status !== "cancelled").length < 1) {
+    throw new GateError(lapTickets.length > 0 ? "no burnable tickets \u2014 every ticket is cancelled" : "no tickets to burn");
   }
   if (restarting) {
     sweepOrphanedBurning(ctx, featureId, "orphaned \u2014 the previous run died while it was burning");
@@ -5410,6 +5749,22 @@ async function burn(ctx, featureId, opts = {}) {
   });
   return { runId };
 }
+function rethink(ctx, featureId) {
+  const feature = getFeatureRow(ctx, featureId);
+  if (feature.phase !== RETHINK_LOOP_BACK.from) {
+    throw new GateError(`feature must be in the review phase to rethink (currently ${feature.phase})`);
+  }
+  if (hasActiveRun(ctx, featureId)) {
+    throw new GateError("a run is burning this feature \u2014 cancel or wait for it before rethinking");
+  }
+  const live = activeSessionsForFeature(ctx, featureId);
+  if (live.length > 0) {
+    throw new GateError(`a ${live[0].kind} session is already live for ${feature.slug} \u2014 only one terminal per feature; end or resume it first`);
+  }
+  const lap = feature.lap + 1;
+  ctx.db.update(features).set({ lap }).where(eq9(features.id, featureId)).run();
+  return setPhase(ctx, featureId, RETHINK_LOOP_BACK.to, "lap.started", `rethink \u2014 lap ${lap}`);
+}
 async function retryTicket(ctx, ticketId, opts = {}) {
   const ticket = getTicket(ctx, ticketId);
   const feature = getFeatureRow(ctx, ticket.featureId);
@@ -5591,6 +5946,7 @@ var init_features = __esm(() => {
   init_git();
   init_knowledge();
   init_repo();
+  init_sessions();
   init_end_session();
   init_tickets();
   init_waypoints();
@@ -5618,8 +5974,14 @@ function resolveSession(ctx, sessionId) {
   }
   return mostRecentLiveSession(ctx);
 }
+function requireFeatureId(session) {
+  if (!session.featureId) {
+    throw new GateError(`this tool needs a feature, and a ${session.kind} session is project-scoped. ` + "Use record_finding to store what you establish about the project.");
+  }
+  return session.featureId;
+}
 function toolGetFeatureContext(ctx, session) {
-  const feature = getFeatureRow(ctx, session.featureId);
+  const feature = getFeatureRow(ctx, requireFeatureId(session));
   const docs = listDocs(ctx, feature).map((d) => {
     try {
       return { relPath: d.relPath, content: readDoc(ctx, feature, d.relPath).content };
@@ -5630,6 +5992,7 @@ function toolGetFeatureContext(ctx, session) {
   const context = {
     feature,
     phase: feature.phase,
+    lap: feature.lap,
     docs,
     tickets: listByFeature2(ctx, feature.id)
   };
@@ -5641,17 +6004,17 @@ function toolGetFeatureContext(ctx, session) {
   return context;
 }
 function toolResolveWaypoint(ctx, _session, input) {
-  resolve2(ctx, input.id, input.disposition, input.summary);
+  resolve3(ctx, input.id, input.disposition, input.summary);
   return { ok: true };
 }
 function toolEmitTickets(ctx, session, input) {
-  const feature = getFeatureRow(ctx, session.featureId);
+  const feature = getFeatureRow(ctx, requireFeatureId(session));
   const stored = storeTickets(ctx, feature.id, input.tickets);
   return { stored: stored.length, ids: stored.map((t) => t.id) };
 }
 function requireOwnTicket(ctx, session, ticketId) {
   const ticket = getTicket(ctx, ticketId);
-  if (ticket.featureId !== session.featureId) {
+  if (ticket.featureId !== requireFeatureId(session)) {
     throw new GateError(`ticket ${ticketId} does not belong to this session's feature`);
   }
   return ticket;
@@ -5666,10 +6029,10 @@ function toolCancelTicket(ctx, session, input) {
   return { ok: true, ticket: cancelTicket(ctx, input.id, input.reason) };
 }
 function toolEscalateToMap(ctx, session, input) {
-  return escalateToMap(ctx, session.featureId, input);
+  return escalateToMap(ctx, requireFeatureId(session), input);
 }
 function toolEmitWaypoints(ctx, session, input) {
-  const feature = getFeatureRow(ctx, session.featureId);
+  const feature = getFeatureRow(ctx, requireFeatureId(session));
   if (!feature.mapped) {
     throw new GateError("feature is not mapped \u2014 call escalate_to_map before emitting waypoints");
   }
@@ -5677,7 +6040,7 @@ function toolEmitWaypoints(ctx, session, input) {
   return { stored: stored.length, ids: stored.map((w) => w.id) };
 }
 function toolRecordEvent(ctx, session, input) {
-  emit(ctx, session.featureId, {
+  emit(ctx, requireFeatureId(session), {
     type: input.type,
     message: input.message,
     data: { source: "mcp" }
@@ -5685,7 +6048,7 @@ function toolRecordEvent(ctx, session, input) {
   return { ok: true };
 }
 function toolCompletePhase(ctx, session, input) {
-  const feature = getFeatureRow(ctx, session.featureId);
+  const feature = getFeatureRow(ctx, requireFeatureId(session));
   emit(ctx, feature.id, {
     type: "phase.complete_requested",
     message: `session marked phase '${input.phase}' complete`,
@@ -5714,13 +6077,46 @@ async function commitDocsCheckpoint(ctx, session, message) {
   try {
     await commitDocs(session.worktreePath, message);
   } catch (e) {
-    emit(ctx, session.featureId, {
+    emit(ctx, requireFeatureId(session), {
       type: "git.commit_pending",
       message: isNotImplemented(e) ? "docs checkpoint skipped (git service pending)" : `docs checkpoint failed: ${e instanceof Error ? e.message : String(e)}`,
       data: { message }
     });
   }
 }
+function requireProject(ctx, session) {
+  if (!session.projectId) {
+    throw new GateError(`record_finding is for a project-scoped preparation session; this is a ${session.kind} session.`);
+  }
+  const project = getProjectById(ctx, session.projectId);
+  if (!project)
+    throw new GateError(`project ${session.projectId} not found`);
+  return project;
+}
+function toolRecordFinding(ctx, session, input) {
+  const project = requireProject(ctx, session);
+  const source = input.userSupplied ? "human" : "session";
+  if (!isOverwritable(ctx, project.id, input.key) && !input.userSupplied) {
+    return {
+      ok: true,
+      key: input.key,
+      source,
+      skipped: `${input.key} was set by a human and is not auto-overwritable \u2014 ask them to clear it first if it should change`
+    };
+  }
+  recordFinding(ctx, project.id, {
+    key: input.key,
+    value: input.value,
+    source,
+    ...input.evidence ? { evidence: input.evidence } : {}
+  });
+  emitProject(ctx, project.id, {
+    type: "prep.finding_recorded",
+    message: `preparation session established ${input.key} (${source})`,
+    data: { key: input.key, source, sessionId: session.id }
+  });
+  return { ok: true, key: input.key, source };
+}
 function ok(result) {
   return { content: [{ type: "text", text: JSON.stringify(result) }] };
 }
@@ -5742,6 +6138,21 @@ async function resolveCtxSession(extra) {
 }
 function buildMcpServer() {
   const server = new McpServer({ name: "runcastle", version: "0.1.0" });
+  server.registerTool("record_finding", {
+    title: "Record a preparation finding",
+    description: "Store one established project setting from a preparation conversation. " + "Set userSupplied: true ONLY when the human gave you this value or confirmed it verbatim \u2014 " + "that marks it as theirs and stops any future automatic run from overwriting it. " + "Anything you worked out yourself must leave it false, even if they were watching. " + "Always include evidence: what you ran, or what the human told you.",
+    inputSchema: {
+      key: PreparedKey,
+      value: z4.string(),
+      evidence: z4.string().optional(),
+      userSupplied: z4.boolean().optional()
+    }
+  }, async (args, extra) => {
+    const rs = await resolveCtxSession(extra);
+    if (!rs)
+      return noSession();
+    return ok(toolRecordFinding(rs.ctx, rs.session, args));
+  });
   server.registerTool("get_feature_context", {
     title: "Get feature context",
     description: "Full context for the current feature: the feature row, its phase, all docs/features/<slug>/*.md contents, and its tickets.",
@@ -5864,6 +6275,7 @@ var init_server = __esm(() => {
   init_sessions();
   init_features();
   init_events();
+  init_findings();
   init_git();
   init_knowledge();
   init_repo();
@@ -5974,6 +6386,57 @@ function handleSessionStart(ctx, sessionId, feature, payload) {
     }
   };
 }
+function handlePrepareSessionStart(ctx, session, payload) {
+  const ccSessionId = typeof payload?.session_id === "string" ? payload.session_id : undefined;
+  const transcriptPath = typeof payload?.transcript_path === "string" ? payload.transcript_path : undefined;
+  const source = typeof payload?.source === "string" ? payload.source : undefined;
+  const wasLive = getSessionRow(ctx, session.id)?.status === "live";
+  markSessionLive(ctx, session.id, { ccSessionId, transcriptPath });
+  if (!wasLive) {
+    emitForSession(ctx, session, {
+      type: "session.started",
+      message: source === "resume" ? "preparation session live (resumed)" : "preparation session live",
+      data: { sessionId: session.id, ccSessionId, transcriptPath, source: source ?? null }
+    });
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: prepareStartContext(ctx, session)
+    }
+  };
+}
+function handlePrepareUserPrompt(ctx, session, payload) {
+  const prompt = typeof payload?.prompt === "string" ? payload.prompt : undefined;
+  noteKickoffPrompt(ctx, session.id, prompt);
+  return {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: `[runcastle] preparation session (project-scoped, no feature)`
+    }
+  };
+}
+function handlePrepareSessionEnd(ctx, session) {
+  markSessionEnded(ctx, session.id);
+  emitForSession(ctx, session, {
+    type: "session.ended",
+    message: "preparation session ended",
+    data: { sessionId: session.id }
+  });
+  return {};
+}
+function prepareStartContext(ctx, session) {
+  const project = session.projectId ? getProjectById(ctx, session.projectId) : null;
+  if (!project)
+    return "[runcastle] preparation session \u2014 project not found";
+  const remaining = keysToPrepare(ctx, project);
+  return [
+    `[runcastle] preparation session for ${project.name} (${project.repoPath}).`,
+    remaining.length > 0 ? `Still unestablished: ${remaining.join(", ")}.` : "Every prepared field currently has a value.",
+    "Record what you establish with the `record_finding` MCP tool \u2014 a value the user",
+    "gives you or confirms verbatim is theirs (userSupplied: true), anything you measured is not."
+  ].join(" ");
+}
 function handleUserPrompt(ctx, sessionId, feature, payload) {
   const prompt = typeof payload?.prompt === "string" ? payload.prompt : undefined;
   noteKickoffPrompt(ctx, sessionId, prompt);
@@ -6015,6 +6478,7 @@ var hooks, hooks_default;
 var init_hooks = __esm(() => {
   init_sessions();
   init_events();
+  init_prep();
   init_repo();
   init_tickets();
   init_waypoints();
@@ -6036,6 +6500,18 @@ var init_hooks = __esm(() => {
       const session = getSessionRow(ctx, sessionId);
       if (!session)
         return c.json({});
+      if (!session.featureId) {
+        switch (event) {
+          case "session-start":
+            return c.json(handlePrepareSessionStart(ctx, session, body.payload));
+          case "user-prompt":
+            return c.json(handlePrepareUserPrompt(ctx, session, body.payload));
+          case "session-end":
+            return c.json(handlePrepareSessionEnd(ctx, session));
+          default:
+            return c.json({});
+        }
+      }
       const feature = tryGetFeature(ctx, session.featureId);
       if (!feature)
         return c.json({});
@@ -6110,7 +6586,7 @@ var init_stream = __esm(() => {
 // src/routes/web.ts
 import { existsSync as existsSync13, statSync } from "fs";
 import { readFile } from "fs/promises";
-import { extname, join as join12, normalize, resolve as resolve6, sep as sep2 } from "path";
+import { extname, join as join12, normalize, resolve as resolve7, sep as sep2 } from "path";
 function contentType(path) {
   return MIME[extname(path).toLowerCase()] ?? "application/octet-stream";
 }
@@ -6136,11 +6612,11 @@ function safeJoin(root, pathname) {
 function resolveWebDist() {
   const override = process.env.RUNCASTLE_WEB_DIST;
   if (override)
-    return resolve6(override);
-  return resolve6(import.meta.dirname, "..", "..", "..", "..", "apps", "web", "dist");
+    return resolve7(override);
+  return resolve7(import.meta.dirname, "..", "..", "..", "..", "apps", "web", "dist");
 }
 function mountWebApp(app, distDir) {
-  const root = resolve6(distDir);
+  const root = resolve7(distDir);
   const indexHtml = join12(root, "index.html");
   app.get("*", async (c, next) => {
     const { pathname } = new URL(c.req.url);
@@ -6431,6 +6907,69 @@ function renderRevisitPrompt(feature) {
   ].join(`
 `);
 }
+function renderPreparePrompt(brief) {
+  const { project, remainingKeys, established, notes } = brief;
+  return [
+    `# runcastle \u2014 preparing ${project.name}`,
+    "",
+    "This is a **preparation session**: a project-scoped conversation whose job is to",
+    "establish the settings every later agent depends on, and to record them with evidence.",
+    "There is no feature here and no pipeline to advance.",
+    "",
+    "## Where this runs \u2014 and why that matters",
+    `You are on the developer's own machine, in \`${project.repoPath}\`, NOT in a sandbox.`,
+    "A headless preparation run measures the repo in a throwaway container, which means it",
+    "can never verify anything about *this* machine: the dev server, the local database,",
+    "docker, credentials. Those keys \u2014 `devCommand`, `driveSetupCommand`, `driveStopCommand`,",
+    "`driveEnv`, `dbResetCommand` \u2014 are exactly what it has to leave as proposals.",
+    "You can actually run them. That is the point of this session.",
+    "",
+    "The same access is why you must **ask before you act**. Anything that starts or stops a",
+    "service, creates or migrates a database, or writes outside the repo needs the human to",
+    "agree first \u2014 say what you are about to run and why, then wait.",
+    "",
+    ...established.length > 0 ? [
+      "## Already established \u2014 do not re-derive",
+      "These are recorded findings. Treat them as true unless the human says otherwise;",
+      "replacing a measured value with a fresh guess makes preparation worse, not better.",
+      "",
+      ...established.map((f) => `- \`${f.key}\` (${f.source})${f.evidence ? ` \u2014 ${f.evidence}` : ""}`),
+      ""
+    ] : [],
+    ...notes ? [
+      "## What the last run could not settle",
+      "Its own words. Where it says it declined to guess, it was right to \u2014 that is the",
+      "gap you are here to close, and closing it usually means asking one direct question.",
+      "",
+      notes,
+      ""
+    ] : [],
+    "## Still open",
+    remainingKeys.length > 0 ? remainingKeys.map((k) => `- \`${k}\``).join(`
+`) : "_Nothing is unset. Confirm the existing values still hold, then say so and stop._",
+    "",
+    "## Recording what you establish",
+    "- `record_finding({ key, value, evidence, userSupplied })` \u2014 one call per key.",
+    "- `userSupplied: true` means the human GAVE you this value or confirmed it verbatim.",
+    "  That marks it as theirs and permanently stops automatic runs from overwriting it.",
+    "- Leave it false for anything you worked out yourself, even with them watching \u2014",
+    "  that stays improvable by a later run. Getting this backwards silently retires a",
+    "  field from preparation forever, and the only way back is the human clearing it.",
+    "- `evidence` is not optional in spirit: record what you ran and what it printed, or",
+    "  what the human told you. A value with no account of itself is a guess with a source field.",
+    "",
+    "## Secrets",
+    "This is a development environment and the human has agreed to supply real connection",
+    "strings and credentials here. Store them as given. Do not paste a secret into a timeline",
+    "note or a commit message \u2014 `record_finding` is the only place a value belongs.",
+    "",
+    "## Your task",
+    "Open by telling the human which fields are still open and what you need from them for",
+    "each. Work them one at a time: propose, ask, run it if they agree, then record it.",
+    ""
+  ].join(`
+`);
+}
 function renderSettings(hookClient) {
   const cmd = (event) => ({
     type: "command",
@@ -6461,13 +7000,16 @@ function renderMcpConfig(session, config2) {
   };
 }
 async function writeSessionArtifacts(input) {
-  const { session, feature, config: config2, waypoint } = input;
+  const { session, feature, config: config2, waypoint, prepare } = input;
   const dir = sessionDir(session.id);
   mkdirSync7(dir, { recursive: true });
   const systemPromptPath = join13(dir, "system-prompt.md");
   const settingsPath = join13(dir, "settings.json");
   const mcpConfigPath = join13(dir, "mcp.json");
-  writeFileSync2(systemPromptPath, renderSystemPrompt(feature, session.kind, waypoint), "utf8");
+  const systemPrompt = feature ? renderSystemPrompt(feature, session.kind, waypoint) : prepare ? renderPreparePrompt(prepare) : (() => {
+    throw new Error(`session ${session.id} has neither a feature nor a preparation brief`);
+  })();
+  writeFileSync2(systemPromptPath, systemPrompt, "utf8");
   writeFileSync2(settingsPath, JSON.stringify(renderSettings(hookClientPath()), null, 2), "utf8");
   writeFileSync2(mcpConfigPath, JSON.stringify(renderMcpConfig(session, config2), null, 2), "utf8");
   return { systemPromptPath, settingsPath, mcpConfigPath };
@@ -6485,7 +7027,8 @@ var init_artifacts = __esm(() => {
     "mcp__runcastle__complete_phase",
     "mcp__runcastle__escalate_to_map",
     "mcp__runcastle__emit_waypoints",
-    "mcp__runcastle__resolve_waypoint"
+    "mcp__runcastle__resolve_waypoint",
+    "mcp__runcastle__record_finding"
   ];
   SESSION_BASH_ALLOW_RULES = [
     "Bash(git status:*)",
@@ -6502,9 +7045,9 @@ var init_artifacts = __esm(() => {
 
 // src/launcher/launcher.ts
 import { existsSync as existsSync14 } from "fs";
-import { dirname as dirname6, join as join14, resolve as resolve7 } from "path";
+import { dirname as dirname6, join as join14, resolve as resolve8 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
-import { and as and7, eq as eq10 } from "drizzle-orm";
+import { and as and8, eq as eq10 } from "drizzle-orm";
 function ptyExitMessage(exitCode) {
   const label = typeof exitCode === "number" ? String(exitCode) : "unknown";
   return `terminal exited (code ${label})`;
@@ -6518,7 +7061,7 @@ function buildClaudeArgs(input) {
     input.settingsPath,
     "--mcp-config",
     input.mcpConfigPath,
-    "--strict-mcp-config",
+    ...input.strictMcp ? ["--strict-mcp-config"] : [],
     "--plugin-dir",
     input.pluginDir,
     "--append-system-prompt-file",
@@ -6539,7 +7082,7 @@ function resolvePluginDir(fromDir = dirname6(fileURLToPath6(import.meta.url))) {
   const rel = join14("packages", "skills", "packs", "runcastle");
   const override = process.env[SKILLS_DIR_ENV];
   if (override) {
-    const dir2 = join14(resolve7(override), "packs", "runcastle");
+    const dir2 = join14(resolve8(override), "packs", "runcastle");
     if (existsSync14(dir2))
       return dir2;
     throw new Error(`${SKILLS_DIR_ENV}=${override} has no plugin dir at ${dir2}`);
@@ -6561,7 +7104,7 @@ function resolvePluginDir(fromDir = dirname6(fileURLToPath6(import.meta.url))) {
   `)}`);
 }
 function activeRunFor(ctx, featureId) {
-  const row = ctx.db.select().from(runs).where(and7(eq10(runs.featureId, featureId), eq10(runs.status, "running"))).limit(1).get();
+  const row = ctx.db.select().from(runs).where(and8(eq10(runs.featureId, featureId), eq10(runs.status, "running"))).limit(1).get();
   return row ? rowToRun(row) : null;
 }
 function assertSpawnable(ctx, feature, excludeSessionId) {
@@ -6574,6 +7117,29 @@ function assertSpawnable(ctx, feature, excludeSessionId) {
     throw new GateError(`a ${running.workflow} run is in progress on ${feature.slug} \u2014 it holds the feature branch; terminals are available when it finishes`);
   }
 }
+function sessionFinished(ctx, feature, session) {
+  if (session.kind !== "waypoint")
+    return feature.mapped;
+  const own = listByFeature(ctx, feature.id).find((w) => w.lastSessionId === session.id);
+  return !!own && (own.status === "resolved" || own.status === "dropped");
+}
+function sweepActiveSessions(ctx, feature, endLive) {
+  for (const session of activeSessionsForFeature(ctx, feature.id)) {
+    const finished = sessionFinished(ctx, feature, session);
+    if (!finished && !endLive)
+      continue;
+    endSession(ctx, session.id);
+    emit(ctx, feature.id, {
+      type: "session.auto_ended",
+      message: finished ? `ended the finished ${session.kind} session to work the next waypoint` : `abandoned the in-flight ${session.kind} session to work the next waypoint`,
+      data: {
+        sessionId: session.id,
+        kind: session.kind,
+        reason: finished ? "finished" : "abandoned"
+      }
+    });
+  }
+}
 async function ensureWorktree(ctx, project, feature) {
   try {
     return await ensureTalkWorktree(project, feature);
@@ -6681,7 +7247,8 @@ async function launchSession(ctx, input, opts = {}) {
     mcpConfigPath: artifacts.mcpConfigPath,
     systemPromptPath: artifacts.systemPromptPath,
     model: resolveModel(input.kind, ctx.config, project),
-    resumeSessionId
+    resumeSessionId,
+    strictMcp: ctx.config.sessionMcp === "runcastleOnly"
   };
   if (opts.spawn === false) {
     emit(ctx, feature.id, {
@@ -6701,6 +7268,75 @@ async function launchSession(ctx, input, opts = {}) {
   });
   return { sessionId: session.id };
 }
+async function launchPrepareSession(ctx, input, opts = {}) {
+  const project = requireProjectById(ctx, input.projectId);
+  const session = createSessionRow(ctx, {
+    projectId: project.id,
+    kind: "prepare",
+    worktreePath: project.repoPath
+  });
+  const resumeSessionId = mostRecentResumableProjectSession(ctx, project.id, "prepare")?.ccSessionId;
+  emitProject(ctx, project.id, {
+    type: "session.launching",
+    message: "launching preparation session",
+    data: { sessionId: session.id, kind: "prepare", worktreePath: project.repoPath }
+  });
+  if (resumeSessionId) {
+    emitProject(ctx, project.id, {
+      type: "session.resumed",
+      message: "resuming the previous preparation conversation",
+      data: { sessionId: session.id, resumeSessionId }
+    });
+  }
+  const artifacts = await writeSessionArtifacts({
+    session,
+    project,
+    config: ctx.config,
+    prepare: await buildPrepareBrief(ctx, project)
+  });
+  const serverUrl = serverUrlFor(ctx.config);
+  const buildInput = {
+    sessionId: session.id,
+    serverUrl,
+    featureTitle: `preparing ${project.name}`,
+    worktreePath: project.repoPath,
+    pluginDir: resolvePluginDir(),
+    settingsPath: artifacts.settingsPath,
+    mcpConfigPath: artifacts.mcpConfigPath,
+    systemPromptPath: artifacts.systemPromptPath,
+    model: resolveModel("prepare", ctx.config, project),
+    resumeSessionId,
+    strictMcp: ctx.config.sessionMcp === "runcastleOnly"
+  };
+  if (opts.spawn === false) {
+    emitProject(ctx, project.id, {
+      type: "session.launched",
+      message: "preparation session prepared (terminal spawn skipped)",
+      data: {
+        sessionId: session.id,
+        command: ["claude", ...buildClaudeArgs(buildInput)].join(" "),
+        spawned: false
+      }
+    });
+    return { sessionId: session.id };
+  }
+  spawnEmbeddedPty(ctx, undefined, session, project.repoPath, serverUrl, buildClaudeArgs(buildInput), { resumeSessionId });
+  return { sessionId: session.id };
+}
+async function buildPrepareBrief(ctx, project) {
+  const findings = await listFindings(ctx, project);
+  const notes = latestPrepNotes(ctx, project.id);
+  return {
+    project,
+    remainingKeys: keysToPrepare(ctx, project),
+    established: findings.map((f) => ({
+      key: f.key,
+      source: f.source,
+      ...f.evidence ? { evidence: f.evidence } : {}
+    })),
+    ...notes ? { notes } : {}
+  };
+}
 async function workWaypoint(ctx, input, opts = {}) {
   const feature = getFeatureRow(ctx, input.featureId);
   if (!feature.mapped) {
@@ -6717,6 +7353,7 @@ async function workWaypoint(ctx, input, opts = {}) {
     });
     return { runId };
   }
+  sweepActiveSessions(ctx, feature, input.endLive === true);
   assertSpawnable(ctx, feature);
   return launchSession(ctx, { featureId: feature.id, kind: "waypoint", waypointId: wp.id }, opts);
 }
@@ -6773,7 +7410,7 @@ function handlePtyExit(ctx, feature, session, meta, exitCode) {
   releaseForSession(ctx, session.id);
   if (diedBeforeLive && meta.resumeSessionId) {
     const label = meta.waypoint ? `waypoint ${meta.waypoint.seq} (${meta.waypoint.title})` : session.kind;
-    emit(ctx, feature.id, {
+    emitForSession(ctx, session, {
       type: "session.resume_failed",
       message: `resume failed for ${label} \u2014 the session exited before starting (code ${exitCode ?? "unknown"}); the previous conversation is still resumable`,
       data: {
@@ -6784,7 +7421,7 @@ function handlePtyExit(ctx, feature, session, meta, exitCode) {
       }
     });
   }
-  emit(ctx, feature.id, {
+  emitForSession(ctx, session, {
     type: "session.pty_exited",
     message: ptyExitMessage(exitCode),
     data: { sessionId: session.id, exitCode: exitCode ?? null }
@@ -6807,7 +7444,7 @@ function spawnEmbeddedPty(ctx, feature, session, worktreePath, serverUrl, claude
       opts: { cwd: worktreePath, env, cols: 80, rows: 24, useConpty: true },
       onExit: ({ exitCode }) => handlePtyExit(ctx, feature, session, meta, exitCode)
     });
-    emit(ctx, feature.id, {
+    emitForSession(ctx, session, {
       type: "session.launched",
       message: "embedded terminal spawned",
       data: { sessionId: session.id, mode: "embedded", pid: entry.pty.pid }
@@ -6816,7 +7453,7 @@ function spawnEmbeddedPty(ctx, feature, session, worktreePath, serverUrl, claude
   } catch (err) {
     markSessionEnded(ctx, session.id);
     releaseForSession(ctx, session.id);
-    emit(ctx, feature.id, {
+    emitForSession(ctx, session, {
       type: "session.spawn_failed",
       message: `failed to spawn embedded terminal: ${err instanceof Error ? err.message : String(err)}`,
       data: { sessionId: session.id, mode: "embedded" }
@@ -6831,6 +7468,7 @@ var init_launcher = __esm(() => {
   init_skills_root();
   init_schema();
   init_errors();
+  init_end_session();
   init_registry();
   init_events();
   init_gates();
@@ -6839,6 +7477,8 @@ var init_launcher = __esm(() => {
   init_tickets();
   init_waypoints();
   init_runner();
+  init_findings();
+  init_prep();
   init_artifacts();
   init_sessions();
   init_sessions();
@@ -6861,6 +7501,7 @@ var gateId, featureRouter;
 var init_feature = __esm(() => {
   init_src();
   init_launcher();
+  init_sessions();
   init_events();
   init_features();
   init_gates();
@@ -6882,8 +7523,16 @@ var init_feature = __esm(() => {
       kind: SessionKind,
       kickoffLine: z7.string().min(1).optional()
     })).mutation(({ ctx, input }) => launchSession(ctx, input)),
-    workWaypoint: publicProcedure.input(z7.object({ featureId: z7.string(), waypointId: z7.string() })).mutation(({ ctx, input }) => workWaypoint(ctx, input)),
+    workWaypoint: publicProcedure.input(z7.object({ featureId: z7.string(), waypointId: z7.string(), endLive: z7.boolean().optional() })).mutation(({ ctx, input }) => workWaypoint(ctx, input)),
     converge: publicProcedure.input(z7.object({ featureId: z7.string(), overrideReason: z7.string().min(1).optional() })).mutation(({ ctx, input }) => converge(ctx, { featureId: input.featureId, overrideReason: input.overrideReason })),
+    rethink: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => {
+      const feature = rethink(ctx, input.featureId);
+      return launchSession(ctx, {
+        featureId: input.featureId,
+        kind: "revisit",
+        kickoffLine: lapKickoff(feature.lap)
+      });
+    }),
     resendKickoff: publicProcedure.input(z7.object({ sessionId: z7.string() })).mutation(({ ctx, input }) => resendKickoff(ctx, input.sessionId)),
     endSession: publicProcedure.input(z7.object({ sessionId: z7.string() })).mutation(({ ctx, input }) => endSession(ctx, input.sessionId)),
     advance: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => advance(ctx, input.featureId)),
@@ -6923,7 +7572,7 @@ var init_feature = __esm(() => {
 // src/services/fsbrowse.ts
 import { existsSync as existsSync15, readdirSync as readdirSync5, statSync as statSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { basename, dirname as dirname7, isAbsolute, join as join15, resolve as resolve8, sep as sep3 } from "path";
+import { basename, dirname as dirname7, isAbsolute, join as join15, resolve as resolve9, sep as sep3 } from "path";
 function expandPath(input, home = homedir2()) {
   const trimmed = input.trim();
   if (trimmed === "")
@@ -6933,7 +7582,7 @@ function expandPath(input, home = homedir2()) {
     out = home;
   else if (out.startsWith("~/") || out.startsWith("~\\"))
     out = join15(home, out.slice(2));
-  return resolve8(out);
+  return resolve9(out);
 }
 function looksLikeRepo(dir) {
   try {
@@ -7086,6 +7735,7 @@ async function openProject(ctx, rawPath) {
       message: `project ${existing.name} re-opened at ${repoPath} (${mainBranch})`
     });
     warnIfTranslatedMount(ctx, existing.id, repoPath);
+    maybeAutoPrepare(ctx, reopened);
     return reopened;
   }
   const row = {
@@ -7107,7 +7757,7 @@ async function openProject(ctx, rawPath) {
   return project;
 }
 function maybeAutoPrepare(ctx, project) {
-  if (!ctx.config.autoPrepare)
+  if (!shouldAutoPrepare(ctx, project))
     return;
   startPrep(ctx, project.id).catch((e) => {
     emitProject(ctx, project.id, {
@@ -7182,6 +7832,8 @@ var init_project = __esm(() => {
   init_fsbrowse();
   init_git();
   init_prep();
+  init_launcher();
+  init_sessions();
   init_projects();
   init_repo();
   init_context();
@@ -7204,6 +7856,8 @@ var init_project = __esm(() => {
       });
       return { prepId, keys };
     }),
+    talkToPrep: publicProcedure.input(z8.object({ projectId: z8.string() })).mutation(({ ctx, input }) => launchPrepareSession(ctx, { projectId: input.projectId })),
+    prepSession: publicProcedure.input(z8.object({ projectId: z8.string() })).query(({ ctx, input }) => activeProjectSession(ctx, input.projectId, "prepare")),
     cancelPrepare: publicProcedure.input(z8.object({ projectId: z8.string() })).mutation(({ input }) => {
       cancelPrep(input.projectId);
       return { ok: true };
@@ -7278,7 +7932,10 @@ function projectOverrides(ctx, projectId) {
     setupCommand: projects.setupCommand,
     verifyCommands: projects.verifyCommands,
     knownFailures: projects.knownFailures,
-    dbResetCommand: projects.dbResetCommand
+    dbResetCommand: projects.dbResetCommand,
+    driveSetupCommand: projects.driveSetupCommand,
+    driveStopCommand: projects.driveStopCommand,
+    driveEnv: projects.driveEnv
   }).from(projects).where(eq12(projects.id, projectId)).get();
   return {
     model: row?.model ?? null,
@@ -7287,7 +7944,10 @@ function projectOverrides(ctx, projectId) {
     setupCommand: row?.setupCommand ?? null,
     verifyCommands: row?.verifyCommands ?? null,
     knownFailures: row?.knownFailures ?? null,
-    dbResetCommand: row?.dbResetCommand ?? null
+    dbResetCommand: row?.dbResetCommand ?? null,
+    driveSetupCommand: row?.driveSetupCommand ?? null,
+    driveStopCommand: row?.driveStopCommand ?? null,
+    driveEnv: row?.driveEnv ?? null
   };
 }
 function resolveField(desc5, layers) {
@@ -7473,6 +8133,14 @@ var init_settings = __esm(() => {
       valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
+    {
+      key: "sessionMcp",
+      configKey: "sessionMcp",
+      envVar: "RUNCASTLE_SESSION_MCP",
+      restartRequired: false,
+      valueSchema: z10.enum(["inherit", "runcastleOnly"]),
+      parseEnv: idEnv
+    },
     {
       key: "burnConcurrency",
       configKey: "burnConcurrency",
@@ -7569,6 +8237,27 @@ var init_settings = __esm(() => {
       restartRequired: false,
       valueSchema: z10.string().min(1),
       parseEnv: idEnv
+    },
+    {
+      key: "driveSetupCommand",
+      projectColumn: "driveSetupCommand",
+      restartRequired: false,
+      valueSchema: z10.string().min(1),
+      parseEnv: idEnv
+    },
+    {
+      key: "driveStopCommand",
+      projectColumn: "driveStopCommand",
+      restartRequired: false,
+      valueSchema: z10.string().min(1),
+      parseEnv: idEnv
+    },
+    {
+      key: "driveEnv",
+      projectColumn: "driveEnv",
+      restartRequired: false,
+      valueSchema: z10.string().min(1),
+      parseEnv: idEnv
     }
   ];
   DEFAULTS = RuncastleConfig.parse({});
@@ -7750,13 +8439,13 @@ var init_doctor = __esm(() => {
 });
 
 // src/doctor/system-exec.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 function createSystemExec(opts = {}) {
-  return (command, args) => new Promise((resolve9) => {
+  return (command, args) => new Promise((resolve10) => {
     const { file, args: spawnArgs } = resolveSpawnTarget(command, args);
     let stdout = "";
     let stderr = "";
-    const child = spawn2(file, spawnArgs, { cwd: opts.cwd, windowsHide: true });
+    const child = spawn3(file, spawnArgs, { cwd: opts.cwd, windowsHide: true });
     child.stdout?.on("data", (d) => {
       stdout += d.toString();
     });
@@ -7764,10 +8453,10 @@ function createSystemExec(opts = {}) {
       stderr += d.toString();
     });
     child.on("error", (err) => {
-      resolve9({ ok: false, code: null, stdout, stderr: stderr || String(err) });
+      resolve10({ ok: false, code: null, stdout, stderr: stderr || String(err) });
     });
     child.on("close", (code) => {
-      resolve9({ ok: true, code: code ?? 0, stdout, stderr });
+      resolve10({ ok: true, code: code ?? 0, stdout, stderr });
     });
   });
 }
@@ -8216,7 +8905,7 @@ import { Hono as Hono4 } from "hono";
 function buildApp(ctx) {
   const app = new Hono4;
   setRuntimeCtx(ctx);
-  app.get("/health", (c) => c.json({ ok: true }));
+  app.get("/health", (c) => c.json({ ok: true, dataDir: dataDir() }));
   app.use("/api/trpc/*", async (c, next) => {
     await next();
     if (c.res.headers.get("content-type") === "application/json") {
@@ -8261,7 +8950,7 @@ async function startServer() {
     },
     websocket: terminalWebSocket
   });
-  console.log(`runcastle server listening on http://localhost:${config2.serverPort}`);
+  console.log(`runcastle${process.env.RUNCASTLE_DEV ? " [dev]" : ""} server listening on ` + `http://localhost:${config2.serverPort} \u2014 data dir: ${dataDir()}`);
   const SHUTDOWN_KEY = Symbol.for("runcastle.shutdown.wired");
   const g = globalThis;
   if (!g[SHUTDOWN_KEY]) {