runcastle 1.0.24 → 1.0.26

package/bin/runcastle.js

@@ -22,19 +22,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");
 }
@@ -50,8 +69,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);
@@ -69,6 +91,20 @@ import * as z from "zod";
 function resolveSandboxImage(config) {
   return config.sandboxImage ?? DEFAULT_SANDBOX_IMAGE;
 }
+function resolvePreparedSettings(config, project) {
+  const pick = (a, b) => {
+    const own = a?.trim();
+    if (own)
+      return own;
+    const inherited = b?.trim();
+    return inherited || undefined;
+  };
+  return {
+    setupCommand: pick(project?.setupCommand, config.setupCommand),
+    verifyCommands: pick(project?.verifyCommands, config.verifyCommands),
+    knownFailures: pick(project?.knownFailures, config.knownFailures)
+  };
+}
 function resolveModel(step, config, project, runOverride) {
   return runOverride ?? config.stepModels[step] ?? project?.model ?? config.model;
 }
@@ -94,6 +130,7 @@ var init_config = __esm(() => {
     "revisit",
     "research",
     "implement",
+    "prepare",
     "smoke"
   ];
   ModelStep = z.enum(MODEL_STEPS);
@@ -102,6 +139,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),
@@ -110,6 +148,7 @@ var init_config = __esm(() => {
     burnMaxIterations: z.number().int().min(1).max(10).default(3),
     burnAttempts: z.number().int().min(1).max(5).default(3),
     burnConflictAttempts: z.number().int().min(0).max(3).default(2),
+    autoPrepare: z.boolean().default(true),
     setupCommand: z.string().optional(),
     verifyCommands: z.string().optional(),
     knownFailures: z.string().optional(),
@@ -142,6 +181,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)
@@ -203,7 +244,7 @@ var init_ids = () => {};
 
 // ../core/src/schemas.ts
 import * as z2 from "zod";
-var Phase, TicketStatus, SessionKind, RunStatus, FeatureStatus, SessionStatus, TicketInput, Ticket, WaypointType, WaypointStatus, WaypointDisposition, WaypointInput, Waypoint, Project, Feature, SessionRow, Run, SettingSource, SettingScope, SettingField, SettingsView, SettingsUpdateInput, EventRow;
+var Phase, TicketStatus, SessionKind, RunStatus, FeatureStatus, SessionStatus, TicketInput, Ticket, WaypointType, WaypointStatus, WaypointDisposition, WaypointInput, Waypoint, PREPARED_KEYS, PreparedKey, FindingSource, Project, ProjectFinding, PrepStatus, PrepRun, Feature, SessionRow, Run, SettingSource, SettingScope, SettingField, SettingsView, SettingsUpdateInput, EventRow;
 var init_schemas = __esm(() => {
   Phase = z2.enum([
     "ideation",
@@ -214,7 +255,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"]);
@@ -256,13 +297,50 @@ var init_schemas = __esm(() => {
     lastSessionId: z2.string().optional(),
     summary: z2.string().optional()
   });
+  PREPARED_KEYS = [
+    "setupCommand",
+    "verifyCommands",
+    "knownFailures",
+    "devCommand",
+    "driveSetupCommand",
+    "driveStopCommand",
+    "driveEnv",
+    "dbResetCommand"
+  ];
+  PreparedKey = z2.enum(PREPARED_KEYS);
+  FindingSource = z2.enum(["prep", "human", "session"]);
   Project = z2.object({
     id: z2.string(),
     name: z2.string(),
     repoPath: z2.string(),
     mainBranch: z2.string(),
     devCommand: z2.string().optional(),
-    model: z2.string().optional()
+    model: z2.string().optional(),
+    setupCommand: z2.string().optional(),
+    verifyCommands: z2.string().optional(),
+    knownFailures: z2.string().optional(),
+    dbResetCommand: z2.string().optional(),
+    driveSetupCommand: z2.string().optional(),
+    driveStopCommand: z2.string().optional(),
+    driveEnv: z2.string().optional()
+  });
+  ProjectFinding = z2.object({
+    key: PreparedKey,
+    source: FindingSource,
+    evidence: z2.string().optional(),
+    establishedAt: z2.number(),
+    establishedSha: z2.string().optional(),
+    staleCommits: z2.number().optional()
+  });
+  PrepStatus = z2.enum(["running", "succeeded", "failed", "cancelled"]);
+  PrepRun = z2.object({
+    id: z2.string(),
+    projectId: z2.string(),
+    status: PrepStatus,
+    startedAt: z2.number(),
+    endedAt: z2.number().optional(),
+    summary: z2.string().optional(),
+    headSha: z2.string().optional()
   });
   Feature = z2.object({
     id: z2.string(),
@@ -279,7 +357,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(),
@@ -461,8 +540,8 @@ var init_pipeline = __esm(() => {
 });
 
 // ../core/src/db-schema.ts
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
-var projects, features, sessions, tickets, waypoints, runs, events, gateOverrides;
+import { integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+var projects, projectFindings, projectPreps, features, sessions, tickets, waypoints, runs, events, gateOverrides;
 var init_db_schema = __esm(() => {
   projects = sqliteTable("projects", {
     id: text("id").primaryKey(),
@@ -472,7 +551,31 @@ var init_db_schema = __esm(() => {
     devCommand: text("dev_command"),
     model: text("model"),
     sandbox: text("sandbox"),
-    closedAt: integer("closed_at")
+    closedAt: integer("closed_at"),
+    setupCommand: text("setup_command"),
+    verifyCommands: text("verify_commands"),
+    knownFailures: text("known_failures"),
+    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(),
+    key: text("key").notNull(),
+    source: text("source").notNull().$type(),
+    evidence: text("evidence"),
+    establishedAt: integer("established_at").notNull(),
+    establishedSha: text("established_sha")
+  }, (t) => [primaryKey({ columns: [t.projectId, t.key] })]);
+  projectPreps = sqliteTable("project_preps", {
+    id: text("id").primaryKey(),
+    projectId: text("project_id").notNull(),
+    status: text("status").notNull().$type(),
+    startedAt: integer("started_at").notNull(),
+    endedAt: integer("ended_at"),
+    summary: text("summary"),
+    headSha: text("head_sha")
   });
   features = sqliteTable("features", {
     id: text("id").primaryKey(),
@@ -489,7 +592,8 @@ 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"),
     kind: text("kind").notNull().$type(),
     ccSessionId: text("cc_session_id"),
     transcriptPath: text("transcript_path"),
@@ -576,7 +680,9 @@ var init_schema = __esm(() => {
     waypoints,
     runs,
     events,
-    gateOverrides
+    gateOverrides,
+    projectFindings,
+    projectPreps
   };
 });
 
@@ -599,11 +705,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})`);
@@ -1283,6 +1389,13 @@ function emit(ctx, 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,
@@ -1341,7 +1454,14 @@ function rowToProject(row) {
     repoPath: row.repoPath,
     mainBranch: row.mainBranch,
     devCommand: row.devCommand ?? undefined,
-    model: row.model ?? undefined
+    model: row.model ?? undefined,
+    setupCommand: row.setupCommand ?? undefined,
+    verifyCommands: row.verifyCommands ?? undefined,
+    knownFailures: row.knownFailures ?? undefined,
+    dbResetCommand: row.dbResetCommand ?? undefined,
+    driveSetupCommand: row.driveSetupCommand ?? undefined,
+    driveStopCommand: row.driveStopCommand ?? undefined,
+    driveEnv: row.driveEnv ?? undefined
   };
 }
 function rowToRun(row) {
@@ -1358,7 +1478,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,
@@ -1575,7 +1696,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]));
@@ -1618,7 +1739,8 @@ 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,
     kind: input.kind,
     ccSessionId: null,
     transcriptPath: null,
@@ -1673,34 +1795,159 @@ function writeKickoffSequence(line, io, submitDelayMs = KICKOFF_SUBMIT_DELAY_MS)
   }, submitDelayMs);
   submit.unref?.();
 }
-function scheduleKickoff(ctx, session) {
-  const line = kickoffLineFor(session.kind, pendingKickoffOverrides.get(session.id));
-  pendingKickoffOverrides.delete(session.id);
-  const timer = setTimeout(() => {
+function stopTimers(d) {
+  for (const t of d.timers)
+    clearTimeout(t);
+  d.timers.clear();
+}
+function forgetKickoff(sessionId) {
+  const d = deliveries.get(sessionId);
+  if (d)
+    stopTimers(d);
+  deliveries.delete(sessionId);
+  pendingKickoffOverrides.delete(sessionId);
+}
+function ptyIo(sessionId) {
+  return {
+    write: (data) => ptyRegistry().get(sessionId)?.pty.write(data),
+    alive: () => {
+      const entry = ptyRegistry().get(sessionId);
+      return !!entry && !entry.exited;
+    }
+  };
+}
+function track(d, timer) {
+  timer.unref?.();
+  d.timers.add(timer);
+}
+function attemptKickoff(ctx, session, d, delayMs, clearFirst = false) {
+  track(d, setTimeout(() => {
+    if (d.settled)
+      return;
+    const io = ptyIo(session.id);
+    if (!io.alive()) {
+      d.settled = true;
+      return;
+    }
+    d.attempts += 1;
+    const attempt = d.attempts;
     try {
-      writeKickoffSequence(line, {
-        write: (data) => ptyRegistry().get(session.id)?.pty.write(data),
-        alive: () => {
-          const entry = ptyRegistry().get(session.id);
-          return !!entry && !entry.exited;
-        },
-        onSubmitted: () => {
-          emit(ctx, session.featureId, {
-            type: "session.kickoff",
-            message: `${session.kind} session kicked off automatically`,
-            data: { sessionId: session.id, kind: session.kind }
-          });
-        }
+      if (clearFirst)
+        io.write(CLEAR_INPUT);
+      writeKickoffSequence(d.line, {
+        write: io.write,
+        alive: io.alive,
+        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 }
+        })
       });
     } catch {}
-  }, KICKOFF_DELAY_MS);
+    armConfirmation(ctx, session, d);
+  }, delayMs));
+}
+function armConfirmation(ctx, session, d) {
+  track(d, setTimeout(() => {
+    if (d.settled || d.confirmed)
+      return;
+    if (d.attempts < KICKOFF_MAX_ATTEMPTS && ptyIo(session.id).alive()) {
+      attemptKickoff(ctx, session, d, 0, true);
+      return;
+    }
+    settleUndelivered(ctx, session, d, "unacknowledged");
+  }, KICKOFF_CONFIRM_MS));
+}
+function settleUndelivered(ctx, session, d, reason) {
+  d.settled = true;
+  stopTimers(d);
+  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 }
+  });
+}
+function noteKickoffPrompt(ctx, sessionId, prompt) {
+  const d = deliveries.get(sessionId);
+  if (!d || d.confirmed)
+    return;
+  const session = getSessionRow(ctx, sessionId);
+  if (!session)
+    return;
+  if (promptMatchesKickoff(d.line, prompt)) {
+    d.confirmed = true;
+    d.settled = true;
+    stopTimers(d);
+    return;
+  }
+  if (d.settled)
+    return;
+  settleUndelivered(ctx, session, d, "superseded");
+}
+function promptMatchesKickoff(line, prompt) {
+  if (!prompt)
+    return false;
+  const norm = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+  const want = norm(line);
+  const got = norm(prompt);
+  if (!want || !got)
+    return false;
+  return got.includes(want.slice(0, MATCH_PREFIX));
+}
+function resendKickoff(ctx, sessionId) {
+  const session = getSessionRow(ctx, sessionId);
+  if (!session)
+    throw new Error(`unknown session ${sessionId}`);
+  if (session.status === "ended")
+    throw new Error("that session has ended \u2014 open a new terminal");
+  if (!ptyIo(sessionId).alive())
+    throw new Error("the terminal for that session is no longer running");
+  const existing = deliveries.get(sessionId);
+  const d = existing ?? {
+    line: kickoffLineFor(session.kind, pendingKickoffOverrides.get(sessionId)),
+    attempts: 0,
+    confirmed: false,
+    settled: false,
+    timers: new Set
+  };
+  stopTimers(d);
+  d.attempts = 0;
+  d.confirmed = false;
+  d.settled = false;
+  deliveries.set(sessionId, d);
+  attemptKickoff(ctx, session, d, 0, true);
+  return { line: d.line };
+}
+function armSessionReadyWatchdog(ctx, session) {
+  const timer = setTimeout(() => {
+    const row = getSessionRow(ctx, session.id);
+    if (!row || row.status !== "launching")
+      return;
+    if (!ptyIo(session.id).alive())
+      return;
+    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 }
+    });
+  }, SESSION_READY_TIMEOUT_MS);
   timer.unref?.();
 }
+function scheduleKickoff(ctx, session) {
+  const line = kickoffLineFor(session.kind, pendingKickoffOverrides.get(session.id));
+  pendingKickoffOverrides.delete(session.id);
+  const existing = deliveries.get(session.id);
+  if (existing)
+    stopTimers(existing);
+  const d = { line, attempts: 0, confirmed: false, settled: false, timers: new Set };
+  deliveries.set(session.id, d);
+  attemptKickoff(ctx, session, d, KICKOFF_DELAY_MS);
+}
 function markSessionEnded(ctx, id) {
   const existing = getSessionRow(ctx, id);
   if (!existing)
     return null;
-  pendingKickoffOverrides.delete(id);
+  forgetKickoff(id);
   ctx.db.update(sessions).set({ status: "ended" }).where(eq4(sessions.id, id)).run();
   return getSessionRow(ctx, id);
 }
@@ -1708,11 +1955,19 @@ 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;
 }
-var KICKOFF_DELAY_MS = 1500, KICKOFF_SUBMIT_DELAY_MS = 350, CONVERGE_KICKOFF_LINE, KICKOFF_LINES, RESUME_KICKOFF_PREFIX, pendingKickoffOverrides;
+var KICKOFF_DELAY_MS = 1500, KICKOFF_SUBMIT_DELAY_MS = 350, KICKOFF_CONFIRM_MS = 12000, KICKOFF_MAX_ATTEMPTS = 3, CLEAR_INPUT = "\x15", SESSION_READY_TIMEOUT_MS = 25000, CONVERGE_KICKOFF_LINE, KICKOFF_LINES, RESUME_KICKOFF_PREFIX, pendingKickoffOverrides, deliveries, MATCH_PREFIX = 40;
 var init_sessions = __esm(() => {
   init_src();
   init_schema();
@@ -1726,10 +1981,12 @@ 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;
+  deliveries = new Map;
 });
 
 // src/launcher/reconcile.ts
@@ -1743,7 +2000,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: {
@@ -1765,351 +2022,288 @@ var init_reconcile = __esm(() => {
   init_sessions();
 });
 
-// src/launcher/runtime.ts
-function setRuntimeCtx(ctx) {
-  current = ctx;
-}
-async function getRuntimeCtx() {
-  if (current)
-    return current;
-  const [{ createDb: createDb2 }, { dbPath: dbPath2 }, { loadConfig: loadConfig2 }] = await Promise.all([
-    Promise.resolve().then(() => (init_client(), exports_client)),
-    Promise.resolve().then(() => (init_paths(), exports_paths)),
-    Promise.resolve().then(() => (init_config_load(), exports_config_load))
-  ]);
-  const db = createDb2(dbPath2());
-  current = { db, config: loadConfig2() };
-  return current;
-}
-var current = null;
-
-// src/services/feature-docs.ts
+// src/launcher/skills-root.ts
 import { existsSync as existsSync5 } from "fs";
-import { join as join5 } from "path";
-function featureDocsDir(project, feature) {
-  const relSegments = featureDocsRel(feature.slug).split("/");
-  const worktree = worktreeDir(project.id, feature.slug);
-  const base = existsSync5(worktree) ? worktree : project.repoPath;
-  return join5(base, ...relSegments);
-}
-function featureDocPath(project, feature, fileName) {
-  return join5(featureDocsDir(project, feature), fileName);
+import { dirname, join as join5, resolve as resolve4 } from "path";
+function resolveSkillsRoot(fromDir) {
+  const override = process.env[SKILLS_DIR_ENV];
+  if (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})`);
+  }
+  const searched = [];
+  let dir = fromDir;
+  for (let i = 0;i < 8; i += 1) {
+    const candidate = join5(dir, "packages", "skills");
+    searched.push(candidate);
+    if (existsSync5(join5(candidate, SKILLS_MARKER)))
+      return candidate;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  throw new Error(`runcastle skills root not found; searched:
+  ${searched.join(`
+  `)}`);
 }
-var init_feature_docs = __esm(() => {
-  init_paths();
+var SKILLS_DIR_ENV = "RUNCASTLE_SKILLS_DIR", SKILLS_MARKER;
+var init_skills_root = __esm(() => {
+  SKILLS_MARKER = join5("packs", "runcastle");
 });
 
-// src/services/tickets.ts
-import { and as and5, asc as asc3, eq as eq5 } from "drizzle-orm";
-function rowToTicket(row) {
-  return {
-    id: row.id,
-    featureId: row.featureId,
-    seq: row.seq,
-    title: row.title,
-    goal: row.goal,
-    context: row.context,
-    acceptanceCriteria: row.acceptanceCriteria,
-    seams: row.seams,
-    blockedBy: row.blockedBy,
-    status: row.status,
-    commits: row.commits,
-    error: row.error ?? undefined,
-    attemptBranch: row.attemptBranch ?? undefined,
-    conflictFiles: row.conflictFiles ?? undefined
-  };
+// src/pty/dev-pane.ts
+function drivePaneId(featureId) {
+  return `${DRIVE_PREFIX}${featureId}`;
 }
-function resolveBlocking(inputs, startSeq) {
-  try {
-    return resolveBatchBlocking(inputs, { startSeq });
-  } catch (e) {
-    if (e instanceof BlockingEdgeError)
-      throw new InvalidInputError(e.message);
-    throw e;
-  }
+function sniffDevUrl(text2) {
+  const m = text2.match(/https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/[^\s"'<>`\x1b]*)?/i);
+  return m ? m[0] : undefined;
 }
-function listByFeature2(ctx, featureId) {
-  return ctx.db.select().from(tickets).where(eq5(tickets.featureId, featureId)).orderBy(asc3(tickets.seq)).all().map(rowToTicket);
+function devSpawnTarget(devCommand) {
+  if (process.platform === "win32") {
+    return { file: process.env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", devCommand] };
+  }
+  return { file: "/bin/sh", args: ["-c", devCommand] };
 }
-function storeTickets(ctx, featureId, inputs) {
-  if (inputs.length === 0)
-    return [];
-  const existing = ctx.db.select({ seq: tickets.seq }).from(tickets).where(eq5(tickets.featureId, featureId)).all();
-  const startSeq = existing.reduce((max, r) => Math.max(max, r.seq), 0) + 1;
-  const resolved = resolveBlocking(inputs, startSeq);
-  const rows = inputs.map((t, i) => ({
-    id: newId("tkt"),
-    featureId,
-    seq: resolved[i].seq,
-    title: t.title,
-    goal: t.goal,
-    context: t.context,
-    acceptanceCriteria: t.acceptanceCriteria,
-    seams: t.seams,
-    blockedBy: resolved[i].blockedBy,
-    status: "pending",
-    commits: [],
-    error: null,
-    attemptBranch: null,
-    conflictFiles: null
-  }));
-  ctx.db.insert(tickets).values(rows).run();
+function startDevPane(input) {
+  const { ctx, featureId, repoPath, devCommand, env, onUrl } = input;
+  const paneId = drivePaneId(featureId);
+  const { file, args } = devSpawnTarget(devCommand);
+  try {
+    ptyRegistry().create({
+      sessionId: paneId,
+      cmd: file,
+      args,
+      opts: { cwd: repoPath, env: env ?? process.env, cols: 80, rows: 24, useConpty: true }
+    });
+  } catch (err) {
+    emit(ctx, featureId, {
+      type: "testdrive.dev_failed",
+      message: `dev server failed to start: ${err instanceof Error ? err.message : String(err)}`,
+      data: { paneId }
+    });
+    return;
+  }
+  let scanned = "";
+  let found = false;
+  const sniffer = {
+    sendData(chunk) {
+      if (found)
+        return;
+      scanned = (scanned + chunk.toString("utf8")).slice(-SNIFF_WINDOW);
+      const url = sniffDevUrl(scanned);
+      if (url) {
+        found = true;
+        onUrl(url);
+      }
+    },
+    sendControl() {}
+  };
+  ptyRegistry().attach(paneId, sniffer);
   emit(ctx, featureId, {
-    type: "tickets.stored",
-    message: `${rows.length} ticket(s) stored`,
-    data: { count: rows.length, seqs: rows.map((r) => r.seq) }
+    type: "testdrive.dev_started",
+    message: `dev server spawned: ${devCommand}`,
+    data: { paneId }
   });
-  return rows.map(rowToTicket);
+  return paneId;
 }
-function getTicket(ctx, id) {
-  const row = ctx.db.select().from(tickets).where(eq5(tickets.id, id)).get();
-  if (!row)
-    throw new NotFoundError(`ticket ${id} not found`);
-  return rowToTicket(row);
+function stopDevPane(paneId) {
+  const reg = ptyRegistry();
+  const entry = reg.get(paneId);
+  if (entry && !entry.exited && process.platform !== "win32") {
+    try {
+      process.kill(-entry.pty.pid, "SIGTERM");
+    } catch {}
+  }
+  reg.kill(paneId);
+  reg.remove(paneId);
 }
-function assertMutable(t, verb) {
-  if (!MUTABLE_STATUSES.has(t.status)) {
-    throw new InvalidInputError(`cannot ${verb} ticket ${t.seq} \u2014 it is ${t.status}; only pending or failed tickets can be ${verb}${verb.endsWith("l") ? "led" : "ed"}`);
+var DRIVE_PREFIX = "drive:", SNIFF_WINDOW = 8192;
+var init_dev_pane = __esm(() => {
+  init_events();
+  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 editTicket(ctx, id, patch) {
-  const current2 = getTicket(ctx, id);
-  assertMutable(current2, "edit");
-  const set = {};
-  if (patch.title !== undefined)
-    set.title = patch.title;
-  if (patch.goal !== undefined)
-    set.goal = patch.goal;
-  if (patch.context !== undefined)
-    set.context = patch.context;
-  if (patch.acceptanceCriteria !== undefined)
-    set.acceptanceCriteria = patch.acceptanceCriteria;
-  if (patch.seams !== undefined)
-    set.seams = patch.seams;
-  if (Object.keys(set).length === 0) {
-    throw new InvalidInputError("nothing to edit \u2014 pass at least one content field");
-  }
-  ctx.db.update(tickets).set(set).where(eq5(tickets.id, id)).run();
-  emit(ctx, current2.featureId, {
-    type: "ticket.edited",
-    message: `ticket ${current2.seq} content edited (${Object.keys(set).join(", ")})`,
-    ticketId: id,
-    data: { fields: Object.keys(set) }
-  });
-  return getTicket(ctx, id);
-}
-function cancelTicket(ctx, id, reason) {
-  const current2 = getTicket(ctx, id);
-  assertMutable(current2, "cancel");
-  ctx.db.update(tickets).set({ status: "cancelled", error: reason?.trim() ? reason.trim() : null }).where(eq5(tickets.id, id)).run();
-  emit(ctx, current2.featureId, {
-    type: "ticket.cancelled",
-    message: `ticket ${current2.seq} cancelled${reason?.trim() ? `: ${reason.trim()}` : ""}`,
-    ticketId: id,
-    data: { reason: reason ?? null }
-  });
-  return getTicket(ctx, id);
-}
-function sweepOrphanedBurning(ctx, featureId, reason) {
-  const orphaned = ctx.db.select().from(tickets).where(and5(eq5(tickets.featureId, featureId), eq5(tickets.status, "burning"))).all().map(rowToTicket);
-  for (const t of orphaned) {
-    updateTicket(ctx, t.id, { status: "failed", error: reason });
-    emit(ctx, featureId, {
-      type: "ticket.failed",
-      message: `ticket ${t.seq} failed: ${reason}`,
-      ticketId: t.id,
-      data: { error: reason, orphaned: true }
-    });
-  }
-  return orphaned.map((t) => ({ ...t, status: "failed", error: reason }));
-}
-function updateTicket(ctx, id, patch) {
-  const current2 = ctx.db.select().from(tickets).where(eq5(tickets.id, id)).get();
-  if (!current2)
-    throw new NotFoundError(`ticket ${id} not found`);
-  const set = {};
-  if (patch.status !== undefined)
-    set.status = patch.status;
-  if (patch.commits !== undefined)
-    set.commits = patch.commits;
-  if (patch.error !== undefined)
-    set.error = patch.error;
-  if (patch.attemptBranch !== undefined)
-    set.attemptBranch = patch.attemptBranch;
-  if (patch.conflictFiles !== undefined)
-    set.conflictFiles = patch.conflictFiles;
-  ctx.db.update(tickets).set(set).where(eq5(tickets.id, id)).run();
-  emit(ctx, current2.featureId, {
-    type: "ticket.updated",
-    message: `ticket ${current2.seq} \u2192 ${patch.status ?? current2.status}`,
-    ticketId: id,
-    data: patch
-  });
-  const updated = ctx.db.select().from(tickets).where(eq5(tickets.id, id)).get();
-  return rowToTicket(updated);
-}
-var MUTABLE_STATUSES;
-var init_tickets = __esm(() => {
-  init_src();
-  init_schema();
-  init_errors();
-  init_events();
-  MUTABLE_STATUSES = new Set(["pending", "failed"]);
-});
-
-// src/services/gates.ts
-import { existsSync as existsSync6 } from "fs";
-function checkGate(ctx, check, feature) {
-  switch (check) {
-    case "decisions-file-exists":
-      return fileGate(ctx, feature, "decisions.md", "run the ideation session to capture decisions first");
-    case "all-waypoints-terminal": {
-      const wps = listByFeature(ctx, feature.id);
-      if (wps.length === 0) {
-        return { satisfied: false, reason: "no waypoints charted yet \u2014 chart the map before converging" };
-      }
-      const open = wps.filter((w) => w.status !== "resolved" && w.status !== "dropped");
-      return open.length === 0 ? { satisfied: true } : {
-        satisfied: false,
-        reason: notYetTerminal("waypoint", open.map((w) => w.status), ["open", "claimed"])
-      };
-    }
-    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;
-      return count >= 1 ? { satisfied: true } : { satisfied: false, reason: "no tickets to burn" };
-    }
-    case "all-tickets-terminal": {
-      const tickets2 = listByFeature2(ctx, feature.id);
-      if (tickets2.length === 0)
-        return { satisfied: false, reason: "no tickets have run yet" };
-      const open = tickets2.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
-      return open.length === 0 ? { satisfied: true } : {
-        satisfied: false,
-        reason: notYetTerminal("ticket", open.map((t) => t.status), ["pending", "burning"])
-      };
+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;
     }
-    case "human-merge":
-      return { satisfied: false, reason: "use the Merge button to ship" };
-  }
-}
-function notYetTerminal(noun, statuses, order) {
-  const counts = new Map;
-  for (const s of statuses)
-    counts.set(s, (counts.get(s) ?? 0) + 1);
-  const ordered = [
-    ...order.filter((s) => counts.has(s)),
-    ...[...counts.keys()].filter((s) => !order.includes(s))
-  ];
-  const breakdown = ordered.map((s) => `${counts.get(s)} ${s}`).join(", ");
-  return `${statuses.length} ${statuses.length === 1 ? noun : `${noun}s`} not yet terminal (${breakdown})`;
-}
-function fileGate(ctx, feature, fileName, reason) {
-  const project = projectForFeature(ctx, feature);
-  return existsSync6(featureDocPath(project, feature, fileName)) ? { satisfied: true } : { satisfied: false, reason };
-}
-function overrideGate(ctx, featureId, gate, reason) {
-  const feature = getFeatureRow(ctx, featureId);
-  ctx.db.insert(gateOverrides).values({ featureId, gate, reason, ts: Date.now() }).run();
-  emit(ctx, featureId, {
-    type: "gate.overridden",
-    message: `gate ${gate} overridden: ${reason}`,
-    data: { gate, reason }
+    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);
+    });
   });
-  const next = nextPhase(feature);
-  if (next)
-    return setPhase(ctx, featureId, next, "phase.advanced", `advanced to ${next} (override)`);
-  return feature;
 }
-var init_gates = __esm(() => {
-  init_src();
-  init_schema();
-  init_events();
-  init_feature_docs();
-  init_repo();
-  init_tickets();
-  init_waypoints();
+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/pty/dev-pane.ts
-function drivePaneId(featureId) {
-  return `${DRIVE_PREFIX}${featureId}`;
-}
-function sniffDevUrl(text2) {
-  const m = text2.match(/https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)?(?:\/[^\s"'<>`\x1b]*)?/i);
-  return m ? m[0] : undefined;
-}
-function devSpawnTarget(devCommand) {
-  if (process.platform === "win32") {
-    return { file: process.env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", devCommand] };
-  }
-  return { file: "/bin/sh", args: ["-c", devCommand] };
-}
-function startDevPane(input) {
-  const { ctx, featureId, repoPath, devCommand, onUrl } = input;
-  const paneId = drivePaneId(featureId);
-  const { file, args } = devSpawnTarget(devCommand);
-  try {
-    ptyRegistry().create({
-      sessionId: paneId,
-      cmd: file,
-      args,
-      opts: { cwd: repoPath, env: process.env, cols: 80, rows: 24, useConpty: true }
-    });
-  } catch (err) {
-    emit(ctx, featureId, {
-      type: "testdrive.dev_failed",
-      message: `dev server failed to start: ${err instanceof Error ? err.message : String(err)}`,
-      data: { paneId }
-    });
-    return;
-  }
-  let scanned = "";
-  let found = false;
-  const sniffer = {
-    sendData(chunk) {
-      if (found)
-        return;
-      scanned = (scanned + chunk.toString("utf8")).slice(-SNIFF_WINDOW);
-      const url = sniffDevUrl(scanned);
-      if (url) {
-        found = true;
-        onUrl(url);
-      }
-    },
-    sendControl() {}
+// 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)
   };
-  ptyRegistry().attach(paneId, sniffer);
-  emit(ctx, featureId, {
-    type: "testdrive.dev_started",
-    message: `dev server spawned: ${devCommand}`,
-    data: { paneId }
-  });
-  return paneId;
-}
-function stopDevPane(paneId) {
-  const reg = ptyRegistry();
-  const entry = reg.get(paneId);
-  if (entry && !entry.exited && process.platform !== "win32") {
-    try {
-      process.kill(-entry.pty.pid, "SIGTERM");
-    } catch {}
-  }
-  reg.kill(paneId);
-  reg.remove(paneId);
 }
-var DRIVE_PREFIX = "drive:", SNIFF_WINDOW = 8192;
-var init_dev_pane = __esm(() => {
-  init_events();
-  init_registry();
+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 existsSync7, mkdirSync as mkdirSync2, mkdtempSync, realpathSync, rmSync } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, mkdtempSync, realpathSync, rmSync } from "fs";
 import { tmpdir } from "os";
-import { dirname, join as join6, resolve as resolve3 } 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));
+}
 function featureBranch(slug) {
   return `feature/${slug}`;
 }
@@ -2120,14 +2314,14 @@ function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
 function canon(p) {
-  let abs = resolve3(p);
+  let abs = resolve5(p);
   try {
     abs = realpathSync.native(abs);
   } catch {}
   return process.platform === "win32" ? abs.replace(/\\/g, "/").toLowerCase() : abs;
 }
 async function assertRepo(repoPath) {
-  if (!existsSync7(repoPath)) {
+  if (!existsSync6(repoPath)) {
     throw new InvalidInputError(`path does not exist: ${repoPath}`);
   }
   let isRepo = false;
@@ -2216,7 +2410,7 @@ async function ensureTalkWorktree(project, feature) {
   await ensureBranchExists(g, branch, feature.baseBranch ?? project.mainBranch);
   if (await worktreeIsValid(g, worktreePath, branch))
     return worktreePath;
-  mkdirSync2(dirname(worktreePath), { recursive: true });
+  mkdirSync2(dirname2(worktreePath), { recursive: true });
   try {
     await g.raw(["worktree", "add", worktreePath, branch]);
     return worktreePath;
@@ -2239,7 +2433,7 @@ async function ensureBranchExists(g, branch, from) {
   }
 }
 async function worktreeIsValid(g, worktreePath, branch) {
-  if (!existsSync7(worktreePath))
+  if (!existsSync6(worktreePath))
     return false;
   const registered = await registeredWorktrees(g);
   if (!registered.has(canon(worktreePath)))
@@ -2285,7 +2479,7 @@ async function worktreesOnBranch(g, branch, mainRepoPath) {
   return (await listWorktrees(g)).filter((e) => e.branch === branch && canon(e.path) !== main).map((e) => e.path);
 }
 async function detachWorktree(path) {
-  if (!existsSync7(path))
+  if (!existsSync6(path))
     return false;
   const g = git(path);
   let head;
@@ -2300,12 +2494,27 @@ async function detachWorktree(path) {
   return true;
 }
 async function reattachWorktree(path, branch) {
-  if (!existsSync7(path))
+  if (!existsSync6(path))
     return;
   try {
     await git(path).checkout(branch);
   } catch {}
 }
+function prepBranchName(unique) {
+  return `${PREP_BRANCH_PREFIX}${unique}`;
+}
+async function readFileAtRef(repoPath, ref, path) {
+  try {
+    return await git(repoPath).raw(["show", `${ref}:${path}`]);
+  } catch {
+    return;
+  }
+}
+async function deletePrepBranch(repoPath, branch) {
+  try {
+    await deleteBranchDetachingWorktrees(git(repoPath), repoPath, branch);
+  } catch {}
+}
 function tempBranchSlugSegment(slug) {
   return slug.slice(0, TEMP_BRANCH_SLUG_MAX).replace(/-+$/, "");
 }
@@ -2323,14 +2532,14 @@ async function cleanupBurnWorktree(repoPath, branch, opts = {}) {
   const attempts = Math.max(1, opts.attempts ?? 3);
   const delayMs = opts.delayMs ?? 750;
   const g = git(repoPath);
-  for (let attempt = 1;attempt <= attempts && existsSync7(path); attempt++) {
+  for (let attempt = 1;attempt <= attempts && existsSync6(path); attempt++) {
     try {
       await g.raw(["worktree", "remove", "--force", path]);
     } catch {}
-    if (existsSync7(path) && attempt < attempts)
+    if (existsSync6(path) && attempt < attempts)
       await sleep(delayMs);
   }
-  if (existsSync7(path)) {
+  if (existsSync6(path)) {
     try {
       rmSync(path, { recursive: true, force: true });
     } catch {}
@@ -2338,7 +2547,7 @@ async function cleanupBurnWorktree(repoPath, branch, opts = {}) {
   try {
     await g.raw(["worktree", "prune"]);
   } catch {}
-  return !existsSync7(path);
+  return !existsSync6(path);
 }
 function sleep(ms) {
   return new Promise((done) => setTimeout(done, ms));
@@ -2352,16 +2561,42 @@ async function branchCommitsAhead(repoPath, base, branch) {
     return [];
   }
 }
-async function commitSummaries(repoPath, base, branch, limit = 20) {
+async function headSha(repoPath, ref) {
   try {
-    const out = await git(repoPath).raw([
-      "log",
-      `--max-count=${limit}`,
-      "--format=%h %s",
-      `${base}..${branch}`
-    ]);
-    return out.split(`
-`).map((l) => l.trim()).filter(Boolean);
+    const out = (await git(repoPath).revparse([ref])).trim();
+    return out.length > 0 ? out : undefined;
+  } catch {
+    return;
+  }
+}
+async function commitsSince(repoPath, sha, branch) {
+  try {
+    const out = (await git(repoPath).raw(["rev-list", "--count", `${sha}..${branch}`])).trim();
+    const n = Number(out);
+    return Number.isFinite(n) ? n : undefined;
+  } catch {
+    return;
+  }
+}
+async function diffPaths(repoPath, from, to) {
+  try {
+    const out = (await git(repoPath).raw(["diff", "--name-only", from, to])).trim();
+    return out ? out.split(`
+`).map((s) => s.trim()).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+async function commitSummaries(repoPath, base, branch, limit = 20) {
+  try {
+    const out = await git(repoPath).raw([
+      "log",
+      `--max-count=${limit}`,
+      "--format=%h %s",
+      `${base}..${branch}`
+    ]);
+    return out.split(`
+`).map((l) => l.trim()).filter(Boolean);
   } catch {
     return [];
   }
@@ -2547,7 +2782,7 @@ async function removeTalkWorktree(repoPath, worktreePath) {
   try {
     await g.raw(["worktree", "prune"]);
   } catch {}
-  if (existsSync7(worktreePath)) {
+  if (existsSync6(worktreePath)) {
     throw new InvalidInputError(`could not remove talk worktree at ${worktreePath} \u2014 a file may be locked; ` + "close anything using it and retry the delete");
   }
 }
@@ -2574,7 +2809,7 @@ async function deleteFeatureBranches(repoPath, slug) {
   return { deleted, kept };
 }
 async function commitDocs(worktreePath, message) {
-  if (!existsSync7(resolve3(worktreePath, DOCS_PATHSPEC)))
+  if (!existsSync6(resolve5(worktreePath, DOCS_PATHSPEC)))
     return;
   const g = git(worktreePath);
   await g.add([DOCS_PATHSPEC]);
@@ -2619,6 +2854,8 @@ 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)
       await reattachWorktree(detachedWorktree2, branch);
@@ -2628,7 +2865,21 @@ async function testDrive(ctx, project, feature, action) {
       message: `test drive stopped \u2014 back on ${previousBranch2}`,
       data: { branch: previousBranch2 }
     });
-    return { ok: true, branch: previousBranch2 };
+    if (carriedChanges.length > 0) {
+      emit(ctx, feature.id, {
+        type: "testdrive.carried_changes",
+        message: `${carriedChanges.length} uncommitted file(s) came back with you onto ${previousBranch2}: ${carriedChanges.slice(0, 5).join(", ")}${carriedChanges.length > 5 ? ", \u2026" : ""}`,
+        data: { branch: previousBranch2, files: carriedChanges }
+      });
+    }
+    const dbDrift = await detectDbDrift(ctx, project, feature, previousBranch2, branch);
+    return {
+      ok: true,
+      branch: previousBranch2,
+      ...carriedChanges.length > 0 ? { carriedChanges } : {},
+      ...dbDrift ? { dbDrift } : {},
+      ...teardownFailure ? { hookFailure: teardownFailure } : {}
+    };
   }
   const porcelain = (await g.raw(["status", "--porcelain"])).trim();
   if (porcelain !== "")
@@ -2652,18 +2903,105 @@ 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 {
+    const out = (await g.raw(["status", "--porcelain"])).trim();
+    if (!out)
+      return [];
+    return out.split(`
+`).map((line) => line.slice(3).trim()).map((p) => p.includes(" -> ") ? p.split(" -> ").at(-1) ?? p : p).map((p) => p.replace(/^"|"$/g, "")).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function detectDbDrift(ctx, project, feature, previousBranch, driveBranch) {
+  let files;
+  try {
+    files = migrationPaths(await diffPaths(project.repoPath, previousBranch, driveBranch));
+  } catch {
+    return;
+  }
+  if (files.length === 0)
+    return;
+  const resetCommand = project.dbResetCommand?.trim() || undefined;
+  const drift = { files, ...resetCommand ? { resetCommand } : {} };
+  emit(ctx, feature.id, {
+    type: "testdrive.db_drift",
+    message: `${driveBranch} and ${previousBranch} differ by ${files.length} migration file(s) \u2014 ` + "anything you migrated during the drive is still applied to your dev database, so the next " + `migrate on ${previousBranch} may report drift. ` + (resetCommand ? `Rebuild it with: ${resetCommand}` : 'Set a "Database reset command" in project settings to get a one-click fix here.'),
+    data: { files, previousBranch, driveBranch, resetCommand: resetCommand ?? null }
+  });
+  return drift;
 }
 async function mergeFeature(project, feature) {
   const target = feature.baseBranch ?? project.mainBranch;
@@ -2720,171 +3058,20 @@ async function mergeInProgress(g) {
     return false;
   }
 }
-var DOCS_PATHSPEC = "docs/features", DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", RESEARCH_BRANCH_PREFIX = "runcastle/research/", TICKET_BRANCH_PREFIX = "runcastle/ticket/", TEMP_BRANCH_PREFIXES, TEMP_BRANCH_SLUG_MAX = 16, testDriveState;
+var DOCS_PATHSPEC = "docs/features", MIGRATION_DIR_RE, DRIZZLE_SQL_RE, DENY_DIRTY = "Working tree has uncommitted changes \u2014 commit or stash first", DENY_ACTIVE = "A test drive is already active \u2014 stop it first", DENY_ACTIVE_RUN = "Feature has an active run \u2014 wait for it to finish", DENY_NONE_ACTIVE = "No test drive is active", RESEARCH_BRANCH_PREFIX = "runcastle/research/", TICKET_BRANCH_PREFIX = "runcastle/ticket/", PREP_BRANCH_PREFIX = "runcastle/prep/", TEMP_BRANCH_PREFIXES, TEMP_BRANCH_SLUG_MAX = 16, testDriveState;
 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;
+  DRIZZLE_SQL_RE = /(^|\/)drizzle\/.*\.sql$/i;
   TEMP_BRANCH_PREFIXES = [RESEARCH_BRANCH_PREFIX, TICKET_BRANCH_PREFIX];
 });
 
-// src/services/knowledge.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync } from "fs";
-import { join as join7, relative, resolve as resolve4, sep } from "path";
-function scaffoldDocs(ctx, feature) {
-  const project = projectForFeature(ctx, feature);
-  const dir = featureDocsDir(project, feature);
-  mkdirSync3(dir, { recursive: true });
-  const briefPath = featureDocPath(project, feature, "brief.md");
-  if (!existsSync8(briefPath)) {
-    const created = new Date().toISOString();
-    const brief = [
-      `# ${feature.title}`,
-      "",
-      feature.oneLiner,
-      "",
-      `- Slug: ${feature.slug}`,
-      `- Created: ${created}`,
-      ""
-    ].join(`
-`);
-    writeFileSync(briefPath, brief, "utf8");
-  }
-  if (feature.mapped) {
-    scaffoldMapDoc(project, feature);
-  }
-  emit(ctx, feature.id, {
-    type: "docs.scaffolded",
-    message: feature.mapped ? `scaffolded docs/features/${feature.slug}/{brief,map}.md` : `scaffolded docs/features/${feature.slug}/brief.md`
-  });
-}
-function scaffoldMapDoc(project, feature, seed) {
-  mkdirSync3(featureDocsDir(project, feature), { recursive: true });
-  const mapPath = featureDocPath(project, feature, "map.md");
-  if (existsSync8(mapPath))
-    return;
-  writeFileSync(mapPath, mapDocBody(feature, seed), "utf8");
-}
-function mapDocBody(feature, seed) {
-  const seeded = {
-    Destination: seed?.destination?.trim(),
-    Notes: seed?.notes?.trim()
-  };
-  const lines = [`# ${feature.title} \u2014 map`, ""];
-  for (const section of MAP_SECTIONS) {
-    lines.push(`## ${section}`, "");
-    const body = seeded[section];
-    if (body)
-      lines.push(body, "");
-  }
-  return lines.join(`
-`);
-}
-function listDocs(ctx, feature) {
-  const project = projectForFeature(ctx, feature);
-  const dir = featureDocsDir(project, feature);
-  if (!existsSync8(dir))
-    return [];
-  return readdirSync2(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => ({ relPath: e.name, title: readTitle(join7(dir, e.name), e.name) })).sort((a, b) => a.relPath.localeCompare(b.relPath));
-}
-function readDoc(ctx, feature, relPath) {
-  const project = projectForFeature(ctx, feature);
-  const dir = featureDocsDir(project, feature);
-  const root = resolve4(dir);
-  const target = resolve4(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}`);
-  }
-  if (!existsSync8(target))
-    throw new NotFoundError(`doc not found: ${relPath}`);
-  return { content: readFileSync3(target, "utf8") };
-}
-function readTitle(path, fallback) {
-  try {
-    const firstLine = readFileSync3(path, "utf8").split(`
-`, 1)[0] ?? "";
-    const heading = firstLine.match(/^#\s+(.+)$/);
-    return heading ? heading[1].trim() : fallback;
-  } catch {
-    return fallback;
-  }
-}
-var MAP_SECTIONS;
-var init_knowledge = __esm(() => {
-  init_errors();
-  init_events();
-  init_feature_docs();
-  init_repo();
-  MAP_SECTIONS = [
-    "Destination",
-    "Notes",
-    "Not yet specified",
-    "Out of scope"
-  ];
-});
-
-// src/pty/end-session.ts
-function endSession(ctx, sessionId) {
-  const registry = ptyRegistry();
-  const killed = registry.kill(sessionId);
-  registry.remove(sessionId);
-  const session = markSessionEnded(ctx, sessionId);
-  if (session) {
-    releaseForSession(ctx, sessionId);
-    emit(ctx, session.featureId, {
-      type: "session.ended",
-      message: "session ended by user",
-      data: { sessionId, killed }
-    });
-  } else {
-    const existing = getSessionRow(ctx, sessionId);
-    if (!existing)
-      return { sessionId, ok: false, killed };
-  }
-  return { sessionId, ok: true, killed };
-}
-var init_end_session = __esm(() => {
-  init_sessions();
-  init_events();
-  init_waypoints();
-  init_registry();
-});
-
-// src/launcher/skills-root.ts
-import { existsSync as existsSync9 } from "fs";
-import { dirname as dirname2, join as join8, resolve as resolve5 } from "path";
-function resolveSkillsRoot(fromDir) {
-  const override = process.env[SKILLS_DIR_ENV];
-  if (override) {
-    const root = resolve5(override);
-    if (existsSync9(join8(root, SKILLS_MARKER)))
-      return root;
-    throw new Error(`${SKILLS_DIR_ENV}=${override} is not a runcastle skills root (missing ${SKILLS_MARKER})`);
-  }
-  const searched = [];
-  let dir = fromDir;
-  for (let i = 0;i < 8; i += 1) {
-    const candidate = join8(dir, "packages", "skills");
-    searched.push(candidate);
-    if (existsSync9(join8(candidate, SKILLS_MARKER)))
-      return candidate;
-    const parent = dirname2(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  throw new Error(`runcastle skills root not found; searched:
-  ${searched.join(`
-  `)}`);
-}
-var SKILLS_DIR_ENV = "RUNCASTLE_SKILLS_DIR", SKILLS_MARKER;
-var init_skills_root = __esm(() => {
-  SKILLS_MARKER = join8("packs", "runcastle");
-});
-
 // src/services/agent-stream.ts
 function beginTranscript(ticketId) {
   transcripts.set(ticketId, { live: true, chunks: [], nextIndex: 0, bytes: 0 });
@@ -3013,8 +3200,8 @@ var init_burn_guard = __esm(() => {
 });
 
 // src/workflows/ticket-burner.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync4, readFileSync as readFileSync4, readdirSync as readdirSync3 } from "fs";
-import { dirname as dirname3, join as join9 } from "path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { claudeCode, run } from "@ai-hero/sandcastle";
 import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
@@ -3063,7 +3250,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);
@@ -3071,7 +3258,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({
@@ -3130,13 +3317,13 @@ function parseEnvFile(content) {
     if (line.length === 0 || line.startsWith("#"))
       continue;
     const body = line.startsWith("export ") ? line.slice(7).trim() : line;
-    const eq6 = body.indexOf("=");
-    if (eq6 === -1)
+    const eq5 = body.indexOf("=");
+    if (eq5 === -1)
       continue;
-    const key = body.slice(0, eq6).trim();
+    const key = body.slice(0, eq5).trim();
     if (key.length === 0)
       continue;
-    let value = body.slice(eq6 + 1).trim();
+    let value = body.slice(eq5 + 1).trim();
     if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
       value = value.slice(1, -1);
     }
@@ -3159,6 +3346,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)
@@ -3168,13 +3358,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) {
@@ -3237,12 +3427,12 @@ function buildVerifyNotes(config2) {
 `);
 }
 function readRepoToolchain(repoPath) {
-  const pkgPath = join9(repoPath, "package.json");
-  const hasPackageJson = existsSync10(pkgPath);
+  const pkgPath = join7(repoPath, "package.json");
+  const hasPackageJson = existsSync7(pkgPath);
   let packageManagerField;
   if (hasPackageJson) {
     try {
-      const pkg = JSON.parse(readFileSync4(pkgPath, "utf8"));
+      const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
       if (typeof pkg.packageManager === "string")
         packageManagerField = pkg.packageManager;
     } catch {}
@@ -3251,14 +3441,14 @@ function readRepoToolchain(repoPath) {
     hasPackageJson,
     ...packageManagerField !== undefined ? { packageManagerField } : {},
     lockfiles: {
-      bun: existsSync10(join9(repoPath, "bun.lock")) || existsSync10(join9(repoPath, "bun.lockb")),
-      pnpm: existsSync10(join9(repoPath, "pnpm-lock.yaml")),
-      yarn: existsSync10(join9(repoPath, "yarn.lock")),
-      npm: existsSync10(join9(repoPath, "package-lock.json"))
+      bun: existsSync7(join7(repoPath, "bun.lock")) || existsSync7(join7(repoPath, "bun.lockb")),
+      pnpm: existsSync7(join7(repoPath, "pnpm-lock.yaml")),
+      yarn: existsSync7(join7(repoPath, "yarn.lock")),
+      npm: existsSync7(join7(repoPath, "package-lock.json"))
     }
   };
 }
-function createStreamThrottle(emit2, opts = {}) {
+function createStreamThrottle(emit3, opts = {}) {
   const intervalMs = opts.intervalMs ?? 2000;
   const maxChars = opts.maxChars ?? 500;
   const now = opts.now ?? Date.now;
@@ -3268,7 +3458,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();
   };
@@ -3283,7 +3473,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 }
@@ -3429,38 +3619,38 @@ function createSerialQueue() {
   };
 }
 async function landWithResolve(branch, deps) {
-  let current2 = branch;
+  let current = branch;
   for (let attempt = 1;; attempt++) {
-    const merge = await deps.merge(current2);
+    const merge = await deps.merge(current);
     if (merge.ok)
-      return { status: "landed", branch: current2 };
+      return { status: "landed", branch: current };
     const detail = merge.error ?? "merge failed";
     if (!merge.conflict)
-      return { status: "failed", branch: current2, error: detail };
+      return { status: "failed", branch: current, error: detail };
     const files = merge.files ?? [];
     if (attempt > deps.maxResolveAttempts) {
-      return { status: "conflict", branch: current2, files, error: detail };
+      return { status: "conflict", branch: current, files, error: detail };
     }
     const where = files.length > 0 ? `${files.length} file(s)` : "the merge";
     deps.emit({
       type: "merge.conflict.resolving",
       message: `${deps.label}: conflicts with ${deps.featureBranch} on ${where} \u2014 resolving with an agent (pass ${attempt}/${deps.maxResolveAttempts})`,
-      data: { branch: current2, files, attempt, maxAttempts: deps.maxResolveAttempts }
+      data: { branch: current, files, attempt, maxAttempts: deps.maxResolveAttempts }
     });
     const resolved = await deps.resolve({
-      branch: current2,
+      branch: current,
       files,
       attempt,
       maxAttempts: deps.maxResolveAttempts
     });
-    current2 = resolved.branch;
+    current = resolved.branch;
     if (!resolved.ok) {
-      return { status: "conflict", branch: current2, files, error: resolved.error ?? detail };
+      return { status: "conflict", branch: current, files, error: resolved.error ?? detail };
     }
     deps.emit({
       type: "merge.conflict.resolved",
-      message: `${deps.label}: conflict resolved on ${current2} \u2014 landing`,
-      data: { branch: current2, files, attempt }
+      message: `${deps.label}: conflict resolved on ${current} \u2014 landing`,
+      data: { branch: current, files, attempt }
     });
   }
 }
@@ -3618,26 +3808,26 @@ function resolverTemplatePath() {
 }
 function burnerAssetPath(file) {
   const here = dirname3(fileURLToPath2(import.meta.url));
-  return join9(resolveSkillsRoot(here), "burner", file);
+  return join7(resolveSkillsRoot(here), "burner", file);
 }
 function readDocsDigestFromDisk(projectId, slug) {
   const worktree = worktreeDir(projectId, slug);
-  if (!existsSync10(worktree))
+  if (!existsSync7(worktree))
     return "_No talk worktree on disk \u2014 docs digest skipped._";
-  const docsDir = join9(worktree, ...featureDocsRel(slug).split("/"));
-  if (!existsSync10(docsDir))
+  const docsDir = join7(worktree, ...featureDocsRel(slug).split("/"));
+  if (!existsSync7(docsDir))
     return "_No docs/features dir in the talk worktree \u2014 docs digest skipped._";
-  const files = readdirSync3(docsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name)).map((e) => ({ name: e.name, content: readFileSync4(join9(docsDir, e.name), "utf8") }));
+  const files = readdirSync2(docsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name)).map((e) => ({ name: e.name, content: readFileSync3(join7(docsDir, e.name), "utf8") }));
   return buildDocsDigest(files);
 }
 function readBlockedFile(dirs) {
   for (const dir of dirs) {
     if (!dir)
       continue;
-    const p = join9(dir, "BLOCKED.md");
-    if (existsSync10(p)) {
+    const p = join7(dir, "BLOCKED.md");
+    if (existsSync7(p)) {
       try {
-        return readFileSync4(p, "utf8");
+        return readFileSync3(p, "utf8");
       } catch {}
     }
   }
@@ -3690,8 +3880,9 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
   const featureBrief = buildFeatureBrief(feature);
   const docsDigest = readDocsDigestFromDisk(project.id, feature.slug);
   const workspaceNotes = buildWorkspaceNotes(workspaceMode);
-  const verifyNotes = buildVerifyNotes(config2);
-  const basePrompt = renderTicketPrompt(readFileSync4(burnerTemplatePath(), "utf8"), {
+  const prepared = resolvePreparedSettings(config2, project);
+  const verifyNotes = buildVerifyNotes(prepared);
+  const basePrompt = renderTicketPrompt(readFileSync3(burnerTemplatePath(), "utf8"), {
     TICKET_JSON: ticketJson,
     FEATURE_BRIEF: featureBrief,
     DOCS_DIGEST: docsDigest,
@@ -3701,19 +3892,19 @@ async function realExecuteTicketRun(ctx, ticket, config2, token, model, land, en
   });
   const toolchain = readRepoToolchain(project.repoPath);
   const pm = detectPackageManager(toolchain);
-  const setupCommand = resolveSetupCommand(toolchain, config2.setupCommand);
+  const setupCommand = resolveSetupCommand(toolchain, prepared.setupCommand);
   const mounts = [];
   if (config2.sandbox !== "noSandbox" && pm) {
     const mount = cacheMountFor(pm, burnCacheDir(pm));
     if (mount) {
-      mkdirSync4(mount.hostPath, { recursive: true });
+      mkdirSync3(mount.hostPath, { recursive: true });
       mounts.push(mount);
     }
   }
   const guardInstall = config2.burnGuard && config2.sandbox !== "noSandbox" ? buildGuardInstallCommand() : undefined;
   const withGuard = (setup) => guardInstall === undefined ? setup : setup ? `${guardInstall} && ${setup}` : guardInstall;
-  mkdirSync4(logsDir(), { recursive: true });
-  const logFilePath = join9(logsDir(), `burn-${feature.id}-${ticket.seq}.log`);
+  mkdirSync3(logsDir(), { recursive: true });
+  const logFilePath = join7(logsDir(), `burn-${feature.id}-${ticket.seq}.log`);
   const throttle = createStreamThrottle((e) => ctx.emitEvent({ ...e, ticketId: ticket.id }));
   beginTranscript(ticket.id);
   const timer = createToolTimer();
@@ -3759,7 +3950,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(readFileSync4(resolverTemplatePath(), "utf8"), {
+    const prompt = renderTemplate2(readFileSync3(resolverTemplatePath(), "utf8"), {
       TICKET_JSON: ticketJson,
       FEATURE_BRIEF: featureBrief,
       DOCS_DIGEST: docsDigest,
@@ -4062,9 +4253,9 @@ function resolveBurnDeps(ctx) {
 }
 function readTokenFromEnvFile(path) {
   let fromFile;
-  if (existsSync10(path)) {
+  if (existsSync7(path)) {
     try {
-      fromFile = parseEnvFile(readFileSync4(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
+      fromFile = parseEnvFile(readFileSync3(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
     } catch {
       fromFile = undefined;
     }
@@ -4135,19 +4326,933 @@ var init_ticket_burner = __esm(() => {
     /\bapi error\b/i,
     /session capture failed/i
   ];
-  activeTicketAborts = new Map;
-  SETUP_HOOK_TIMEOUT_MS = 15 * 60000;
-  ticketBurner = {
-    id: "ticket-burner",
-    run: (ctx) => burnRun(ctx, resolveBurnDeps(ctx))
-  };
+  activeTicketAborts = new Map;
+  SETUP_HOOK_TIMEOUT_MS = 15 * 60000;
+  ticketBurner = {
+    id: "ticket-burner",
+    run: (ctx) => burnRun(ctx, resolveBurnDeps(ctx))
+  };
+});
+
+// src/workflows/project-prep.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname4, join as join8 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { run as run2 } from "@ai-hero/sandcastle";
+import * as z3 from "zod";
+function parsePrepFindings(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`findings file is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  const outer = RawFindings.safeParse(json);
+  if (!outer.success)
+    throw new Error("findings file is not a JSON object");
+  const warnings = [];
+  const values = {};
+  const known = new Set(PREPARED_KEYS);
+  for (const [key, rawValue] of Object.entries(outer.data)) {
+    if (key === "notes")
+      continue;
+    if (!known.has(key)) {
+      warnings.push(`ignored unknown key "${key}"`);
+      continue;
+    }
+    const parsed = RawFinding.safeParse(rawValue);
+    if (!parsed.success) {
+      warnings.push(`ignored "${key}": not a string or {value, evidence} object`);
+      continue;
+    }
+    const entry = parsed.data;
+    const value = (typeof entry === "string" ? entry : entry.value ?? "").trim();
+    if (value === "")
+      continue;
+    const evidence = typeof entry === "string" ? undefined : entry.evidence?.trim();
+    values[key] = { value, ...evidence ? { evidence } : {} };
+  }
+  const notes = outer.data.notes?.trim();
+  return { findings: { values, ...notes ? { notes } : {} }, warnings };
+}
+function renderPrepPrompt(template, values) {
+  let out = template;
+  for (const key of PLACEHOLDERS) {
+    out = out.split(`{{${key}}}`).join(values[key]);
+  }
+  return out;
+}
+function buildRequestedKeysBlock(keys) {
+  if (keys.length === 0) {
+    return "_Everything is already established. Report an empty findings object and stop._";
+  }
+  const order = new Map(PREPARED_KEYS.map((k, i) => [k, i]));
+  return [...keys].sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0)).map((k) => `- ${KEY_BRIEF[k]}`).join(`
+`);
+}
+async function prepRun(ctx, deps) {
+  if (ctx.keys.length === 0) {
+    ctx.emitEvent({
+      type: "prep.skipped",
+      message: "nothing to prepare \u2014 every field is already set"
+    });
+    return { status: "succeeded", summary: "nothing to prepare" };
+  }
+  if (deps.config.sandbox !== "noSandbox" && !deps.hasAuthToken) {
+    ctx.emitEvent({ type: AUTH_MISSING_EVENT2, message: AUTH_MISSING_MESSAGE2 });
+    return { status: "failed", summary: "preparation aborted: auth token missing" };
+  }
+  ctx.emitEvent({
+    type: "prep.started",
+    message: `preparing ${ctx.project.name} \u2014 establishing ${ctx.keys.join(", ")}`,
+    data: { keys: [...ctx.keys] }
+  });
+  const outcome = await deps.executePrepRun(ctx);
+  if (outcome.status === "failed") {
+    ctx.emitEvent({
+      type: "prep.failed",
+      message: `preparation failed: ${errorHeadline2(outcome.error)}`,
+      data: { error: outcome.error }
+    });
+    return { status: "failed", summary: outcome.error };
+  }
+  for (const warning of outcome.warnings) {
+    ctx.emitEvent({ type: "prep.warning", message: `preparation: ${warning}` });
+  }
+  const found = Object.keys(outcome.findings.values);
+  const missed = ctx.keys.filter((k) => !found.includes(k));
+  const summary = found.length === 0 ? "preparation established nothing" : `established ${found.join(", ")}${missed.length > 0 ? ` (could not establish ${missed.join(", ")})` : ""}`;
+  return { status: "succeeded", summary, findings: outcome.findings };
+}
+function errorHeadline2(s) {
+  const lines = s.split(`
+`).map((l) => l.trim()).filter(Boolean);
+  const causes = lines.filter((l) => /^(fatal|error):/i.test(l));
+  return causes.at(-1) ?? lines[0] ?? "";
+}
+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));
+  return join8(resolveSkillsRoot(here), "burner", "prepare-project.md");
+}
+async function realExecutePrepRun(ctx, config2, token, model) {
+  const { project } = ctx;
+  const branch = prepBranchName(newId("b").slice(2, 10));
+  const toolchain = readRepoToolchain(project.repoPath);
+  const pm = detectPackageManager(toolchain);
+  const prepared = resolvePreparedSettings(config2, project);
+  const setupCommand = resolveSetupCommand(toolchain, prepared.setupCommand);
+  const workspaceMode = resolveBurnWorkspaceMode(config2);
+  const mounts = [];
+  if (config2.sandbox !== "noSandbox" && pm) {
+    const mount = cacheMountFor(pm, burnCacheDir(pm));
+    if (mount) {
+      mkdirSync4(mount.hostPath, { recursive: true });
+      mounts.push(mount);
+    }
+  }
+  const template = readFileSync4(prepTemplatePath(), "utf8");
+  const prompt = renderPrepPrompt(template, {
+    REQUESTED_KEYS: buildRequestedKeysBlock(ctx.keys),
+    SETUP_COMMAND: setupCommand ?? "(no install step detected)"
+  });
+  mkdirSync4(logsDir(), { recursive: true });
+  const logFilePath = join8(logsDir(), `prep-${project.id}.log`);
+  const throttle = createPrepStreamThrottle((e) => ctx.emitEvent(e));
+  if (setupCommand) {
+    ctx.emitEvent({
+      type: "prep.setup",
+      message: `attempting a dependency install before the agent starts (best-effort): ${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),
+    cwd: project.repoPath,
+    prompt,
+    branchStrategy: { type: "branch", branch, baseBranch: project.mainBranch },
+    signal: ctx.signal,
+    name: "prepare",
+    maxIterations: 1,
+    ...hookCommand ? {
+      hooks: {
+        sandbox: {
+          onSandboxReady: [{ command: hookCommand, timeoutMs: PREP_SETUP_TIMEOUT_MS }]
+        }
+      }
+    } : {},
+    logging: { type: "file", path: logFilePath, onAgentStreamEvent: throttle.onEvent }
+  };
+  try {
+    let result;
+    try {
+      result = await run2(runOptions);
+    } catch (err) {
+      throttle.flush();
+      if (ctx.signal.aborted)
+        throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      const salvaged = await readFindings(project.repoPath, branch);
+      if (!salvaged)
+        return { status: "failed", error: msg };
+      ctx.emitEvent({
+        type: "prep.salvaged",
+        message: `the agent finished but sandcastle errored on teardown (${errorHeadline2(msg)}) \u2014 reading the findings it committed anyway`
+      });
+      return salvaged;
+    }
+    throttle.flush();
+    if (result.commits.length === 0) {
+      return {
+        status: "failed",
+        error: `agent produced no commits \u2014 no ${PREP_FINDINGS_PATH} landed`
+      };
+    }
+    const read = await readFindings(project.repoPath, branch);
+    return read ?? {
+      status: "failed",
+      error: `agent committed, but ${PREP_FINDINGS_PATH} is missing from ${branch}`
+    };
+  } finally {
+    await deletePrepBranch(project.repoPath, branch);
+  }
+}
+async function readFindings(repoPath, branch) {
+  const raw = await readFileAtRef(repoPath, branch, PREP_FINDINGS_PATH);
+  if (raw === undefined)
+    return;
+  try {
+    const { findings, warnings } = parsePrepFindings(raw);
+    return { status: "done", findings, warnings };
+  } catch (e) {
+    return { status: "failed", error: e instanceof Error ? e.message : String(e) };
+  }
+}
+function resolvePrepDeps(project) {
+  const config2 = loadConfig();
+  const token = readTokenFromEnvFile(envPath());
+  const model = resolveModel("prepare", config2, project);
+  return {
+    config: config2,
+    hasAuthToken: token !== undefined,
+    executePrepRun: (c) => realExecutePrepRun(c, config2, token, model)
+  };
+}
+async function prepHeadSha(project) {
+  return existsSync8(project.repoPath) ? headSha(project.repoPath, project.mainBranch) : undefined;
+}
+var AUTH_MISSING_EVENT2 = "auth.missing", AUTH_MISSING_MESSAGE2 = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PREP_FINDINGS_PATH = ".runcastle/prep.json", PREP_SETUP_TIMEOUT_MS, RawFinding, RawFindings, PLACEHOLDERS, KEY_BRIEF;
+var init_project_prep = __esm(() => {
+  init_src();
+  init_config_load();
+  init_paths();
+  init_skills_root();
+  init_git();
+  init_ticket_burner();
+  PREP_SETUP_TIMEOUT_MS = 15 * 60000;
+  RawFinding = z3.union([
+    z3.string(),
+    z3.object({
+      value: z3.string().nullish(),
+      evidence: z3.string().nullish()
+    })
+  ]);
+  RawFindings = z3.object({ notes: z3.string().nullish() }).catchall(z3.unknown());
+  PLACEHOLDERS = ["REQUESTED_KEYS", "SETUP_COMMAND"];
+  KEY_BRIEF = {
+    setupCommand: "**`setupCommand`** \u2014 the command that takes a clean checkout to a state where the code builds and tests run: dependency install, plus any codegen or contract build that every task would otherwise discover it needed mid-flight (ORM client generation, protobuf, a `contracts:build` step). Run it and report what worked.",
+    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."
+  };
+});
+
+// src/services/findings.ts
+import { and as and5, eq as eq5 } from "drizzle-orm";
+function isPreparedKey(key) {
+  return PREPARED_SET.has(key);
+}
+function findingRow(ctx, projectId, key) {
+  return ctx.db.select({
+    source: projectFindings.source,
+    evidence: projectFindings.evidence,
+    establishedAt: projectFindings.establishedAt,
+    establishedSha: projectFindings.establishedSha
+  }).from(projectFindings).where(and5(eq5(projectFindings.projectId, projectId), eq5(projectFindings.key, key))).get();
+}
+function isOverwritable(ctx, projectId, key) {
+  return findingRow(ctx, projectId, key)?.source !== "human";
+}
+function recordFinding(ctx, projectId, input) {
+  const { key, value, source, evidence, establishedSha } = input;
+  ctx.db.transaction((tx) => {
+    tx.update(projects).set({ [COLUMN_NAME[key]]: value }).where(eq5(projects.id, projectId)).run();
+    if (value === null) {
+      tx.delete(projectFindings).where(and5(eq5(projectFindings.projectId, projectId), eq5(projectFindings.key, key))).run();
+      return;
+    }
+    tx.insert(projectFindings).values({
+      projectId,
+      key,
+      source,
+      evidence: evidence ?? null,
+      establishedAt: Date.now(),
+      establishedSha: establishedSha ?? null
+    }).onConflictDoUpdate({
+      target: [projectFindings.projectId, projectFindings.key],
+      set: {
+        source,
+        evidence: evidence ?? null,
+        establishedAt: Date.now(),
+        establishedSha: establishedSha ?? null
+      }
+    }).run();
+  });
+}
+function recordHuman(ctx, projectId, key, value) {
+  if (!isPreparedKey(key))
+    return;
+  const existing = findingRow(ctx, projectId, key);
+  if (value === null) {
+    if (existing) {
+      ctx.db.delete(projectFindings).where(and5(eq5(projectFindings.projectId, projectId), eq5(projectFindings.key, key))).run();
+    }
+    return;
+  }
+  ctx.db.insert(projectFindings).values({
+    projectId,
+    key,
+    source: "human",
+    evidence: null,
+    establishedAt: Date.now(),
+    establishedSha: null
+  }).onConflictDoUpdate({
+    target: [projectFindings.projectId, projectFindings.key],
+    set: { source: "human", evidence: null, establishedAt: Date.now(), establishedSha: null }
+  }).run();
+}
+async function listFindings(ctx, project) {
+  const rows = ctx.db.select().from(projectFindings).where(eq5(projectFindings.projectId, project.id)).all();
+  const distances = new Map;
+  for (const row of rows) {
+    const sha = row.establishedSha;
+    if (!sha || distances.has(sha))
+      continue;
+    distances.set(sha, await commitsSince(project.repoPath, sha, project.mainBranch));
+  }
+  const order = new Map(PREPARED_KEYS.map((k, i) => [k, i]));
+  return rows.filter((row) => isPreparedKey(row.key)).sort((a, b) => (order.get(a.key) ?? 0) - (order.get(b.key) ?? 0)).map((row) => {
+    const staleCommits = row.establishedSha ? distances.get(row.establishedSha) : undefined;
+    return {
+      key: row.key,
+      source: row.source,
+      ...row.evidence ? { evidence: row.evidence } : {},
+      establishedAt: row.establishedAt,
+      ...row.establishedSha ? { establishedSha: row.establishedSha } : {},
+      ...staleCommits !== undefined ? { staleCommits } : {}
+    };
+  });
+}
+function unsetPreparedKeys(project) {
+  return PREPARED_KEYS.filter((key) => {
+    const value = project[key];
+    return value === undefined || value.trim() === "";
+  });
+}
+var VALUE_COLUMN, COLUMN_NAME, PREPARED_SET;
+var init_findings = __esm(() => {
+  init_src();
+  init_schema();
+  init_git();
+  VALUE_COLUMN = {
+    setupCommand: projects.setupCommand,
+    verifyCommands: projects.verifyCommands,
+    knownFailures: projects.knownFailures,
+    devCommand: projects.devCommand,
+    driveSetupCommand: projects.driveSetupCommand,
+    driveStopCommand: projects.driveStopCommand,
+    driveEnv: projects.driveEnv,
+    dbResetCommand: projects.dbResetCommand
+  };
+  COLUMN_NAME = {
+    setupCommand: "setupCommand",
+    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 { and as and6, desc as desc3, eq as eq6 } from "drizzle-orm";
+function isPreparing(projectId) {
+  return controllers.has(projectId);
+}
+function keysToPrepare(ctx, project, opts = {}) {
+  const unset = new Set(unsetPreparedKeys(project));
+  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)) {
+    throw new InvalidInputError(`${project.name} is already being prepared`);
+  }
+  const keys = keysToPrepare(ctx, project, opts);
+  const prepId = newId("prep");
+  const headSha2 = await prepHeadSha(project);
+  ctx.db.insert(projectPreps).values({
+    id: prepId,
+    projectId,
+    status: "running",
+    startedAt: Date.now(),
+    endedAt: null,
+    summary: null,
+    headSha: headSha2 ?? null
+  }).run();
+  emitProject(ctx, projectId, {
+    type: "prep.run.started",
+    message: keys.length === 0 ? `preparing ${project.name} \u2014 nothing left to establish` : `preparing ${project.name} \u2014 ${keys.length} field(s) to establish`,
+    data: { prepId, keys }
+  });
+  const controller = new AbortController;
+  controllers.set(projectId, { runId: prepId, controller });
+  const prepCtx = {
+    project,
+    keys,
+    emitEvent: (e) => {
+      emitProject(ctx, projectId, { type: e.type, message: e.message, data: e.data });
+    },
+    signal: controller.signal
+  };
+  const deps = opts.deps ?? resolvePrepDeps(project);
+  const done = finalize(ctx, project, prepId, prepCtx, deps, controller, headSha2);
+  return { prepId, keys, done };
+}
+function cancelPrep(projectId) {
+  controllers.get(projectId)?.controller.abort();
+}
+async function finalize(ctx, project, prepId, prepCtx, deps, controller, headSha2) {
+  let status = "failed";
+  let summary = "preparation failed";
+  let findings;
+  try {
+    const result = await prepRun(prepCtx, deps);
+    status = result.status === "succeeded" ? "succeeded" : "failed";
+    summary = result.summary;
+    findings = result.findings;
+  } catch (e) {
+    if (controller.signal.aborted) {
+      status = "cancelled";
+      summary = "preparation cancelled";
+    } else {
+      status = "failed";
+      summary = e instanceof Error ? e.message : "preparation failed";
+    }
+  } finally {
+    controllers.delete(project.id);
+  }
+  const applied = findings ? applyFindings(ctx, project, findings, headSha2) : [];
+  ctx.db.update(projectPreps).set({ status, endedAt: Date.now(), summary }).where(eq6(projectPreps.id, prepId)).run();
+  emitProject(ctx, project.id, {
+    type: "prep.run.finished",
+    message: `preparation ${status}: ${summary}`,
+    data: { prepId, status, summary, applied }
+  });
+}
+function applyFindings(ctx, project, findings, headSha2) {
+  const applied = [];
+  for (const [key, finding] of Object.entries(findings.values)) {
+    if (!isOverwritable(ctx, project.id, key)) {
+      emitProject(ctx, project.id, {
+        type: "prep.skipped_field",
+        message: `kept your ${key} \u2014 preparation proposed "${truncate(finding.value)}" but you set this by hand`,
+        data: { key, proposed: finding.value }
+      });
+      continue;
+    }
+    recordFinding(ctx, project.id, {
+      key,
+      value: finding.value,
+      source: "prep",
+      ...finding.evidence ? { evidence: finding.evidence } : {},
+      ...headSha2 ? { establishedSha: headSha2 } : {}
+    });
+    applied.push(key);
+    emitProject(ctx, project.id, {
+      type: "prep.established",
+      message: `${key}: ${truncate(finding.value)}`,
+      data: { key, value: finding.value, evidence: finding.evidence }
+    });
+  }
+  if (findings.notes) {
+    emitProject(ctx, project.id, {
+      type: "prep.notes",
+      message: `preparation notes: ${findings.notes}`,
+      data: { notes: findings.notes }
+    });
+  }
+  return applied;
+}
+function truncate(value, max = 120) {
+  const oneLine = value.replace(/\s*\n\s*/g, " \xB7 ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}\u2026` : oneLine;
+}
+function latestPrep(ctx, projectId) {
+  const row = ctx.db.select().from(projectPreps).where(eq6(projectPreps.projectId, projectId)).orderBy(desc3(projectPreps.startedAt)).get();
+  if (!row)
+    return null;
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    status: row.status,
+    startedAt: row.startedAt,
+    ...row.endedAt !== null ? { endedAt: row.endedAt } : {},
+    ...row.summary !== null ? { summary: row.summary } : {},
+    ...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) {
+    ctx.db.update(projectPreps).set({ status: "failed", endedAt: Date.now(), summary: "server stopped while preparing" }).where(eq6(projectPreps.id, row.id)).run();
+  }
+  return stale.length;
+}
+var controllers;
+var init_prep = __esm(() => {
+  init_src();
+  init_schema();
+  init_errors();
+  init_project_prep();
+  init_events();
+  init_findings();
+  init_repo();
+  controllers = new Map;
+});
+
+// src/launcher/runtime.ts
+function setRuntimeCtx(ctx) {
+  current = ctx;
+}
+async function getRuntimeCtx() {
+  if (current)
+    return current;
+  const [{ createDb: createDb2 }, { dbPath: dbPath2 }, { loadConfig: loadConfig2 }] = await Promise.all([
+    Promise.resolve().then(() => (init_client(), exports_client)),
+    Promise.resolve().then(() => (init_paths(), exports_paths)),
+    Promise.resolve().then(() => (init_config_load(), exports_config_load))
+  ]);
+  const db = createDb2(dbPath2());
+  current = { db, config: loadConfig2() };
+  return current;
+}
+var current = null;
+
+// src/services/feature-docs.ts
+import { existsSync as existsSync9 } from "fs";
+import { join as join9 } from "path";
+function featureDocsDir(project, feature) {
+  const relSegments = featureDocsRel(feature.slug).split("/");
+  const worktree = worktreeDir(project.id, feature.slug);
+  const base = existsSync9(worktree) ? worktree : project.repoPath;
+  return join9(base, ...relSegments);
+}
+function featureDocPath(project, feature, fileName) {
+  return join9(featureDocsDir(project, feature), fileName);
+}
+var init_feature_docs = __esm(() => {
+  init_paths();
+});
+
+// src/services/tickets.ts
+import { and as and7, asc as asc3, eq as eq7 } from "drizzle-orm";
+function rowToTicket(row) {
+  return {
+    id: row.id,
+    featureId: row.featureId,
+    seq: row.seq,
+    title: row.title,
+    goal: row.goal,
+    context: row.context,
+    acceptanceCriteria: row.acceptanceCriteria,
+    seams: row.seams,
+    blockedBy: row.blockedBy,
+    status: row.status,
+    commits: row.commits,
+    error: row.error ?? undefined,
+    attemptBranch: row.attemptBranch ?? undefined,
+    conflictFiles: row.conflictFiles ?? undefined
+  };
+}
+function resolveBlocking(inputs, startSeq) {
+  try {
+    return resolveBatchBlocking(inputs, { startSeq });
+  } catch (e) {
+    if (e instanceof BlockingEdgeError)
+      throw new InvalidInputError(e.message);
+    throw e;
+  }
+}
+function listByFeature2(ctx, featureId) {
+  return ctx.db.select().from(tickets).where(eq7(tickets.featureId, featureId)).orderBy(asc3(tickets.seq)).all().map(rowToTicket);
+}
+function storeTickets(ctx, featureId, inputs) {
+  if (inputs.length === 0)
+    return [];
+  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);
+  const rows = inputs.map((t, i) => ({
+    id: newId("tkt"),
+    featureId,
+    seq: resolved[i].seq,
+    title: t.title,
+    goal: t.goal,
+    context: t.context,
+    acceptanceCriteria: t.acceptanceCriteria,
+    seams: t.seams,
+    blockedBy: resolved[i].blockedBy,
+    status: "pending",
+    commits: [],
+    error: null,
+    attemptBranch: null,
+    conflictFiles: null
+  }));
+  ctx.db.insert(tickets).values(rows).run();
+  emit(ctx, featureId, {
+    type: "tickets.stored",
+    message: `${rows.length} ticket(s) stored`,
+    data: { count: rows.length, seqs: rows.map((r) => r.seq) }
+  });
+  return rows.map(rowToTicket);
+}
+function getTicket(ctx, id) {
+  const row = ctx.db.select().from(tickets).where(eq7(tickets.id, id)).get();
+  if (!row)
+    throw new NotFoundError(`ticket ${id} not found`);
+  return rowToTicket(row);
+}
+function assertMutable(t, verb) {
+  if (!MUTABLE_STATUSES.has(t.status)) {
+    throw new InvalidInputError(`cannot ${verb} ticket ${t.seq} \u2014 it is ${t.status}; only pending or failed tickets can be ${verb}${verb.endsWith("l") ? "led" : "ed"}`);
+  }
+}
+function editTicket(ctx, id, patch) {
+  const current2 = getTicket(ctx, id);
+  assertMutable(current2, "edit");
+  const set = {};
+  if (patch.title !== undefined)
+    set.title = patch.title;
+  if (patch.goal !== undefined)
+    set.goal = patch.goal;
+  if (patch.context !== undefined)
+    set.context = patch.context;
+  if (patch.acceptanceCriteria !== undefined)
+    set.acceptanceCriteria = patch.acceptanceCriteria;
+  if (patch.seams !== undefined)
+    set.seams = patch.seams;
+  if (Object.keys(set).length === 0) {
+    throw new InvalidInputError("nothing to edit \u2014 pass at least one content field");
+  }
+  ctx.db.update(tickets).set(set).where(eq7(tickets.id, id)).run();
+  emit(ctx, current2.featureId, {
+    type: "ticket.edited",
+    message: `ticket ${current2.seq} content edited (${Object.keys(set).join(", ")})`,
+    ticketId: id,
+    data: { fields: Object.keys(set) }
+  });
+  return getTicket(ctx, id);
+}
+function cancelTicket(ctx, id, reason) {
+  const current2 = getTicket(ctx, id);
+  assertMutable(current2, "cancel");
+  ctx.db.update(tickets).set({ status: "cancelled", error: reason?.trim() ? reason.trim() : null }).where(eq7(tickets.id, id)).run();
+  emit(ctx, current2.featureId, {
+    type: "ticket.cancelled",
+    message: `ticket ${current2.seq} cancelled${reason?.trim() ? `: ${reason.trim()}` : ""}`,
+    ticketId: id,
+    data: { reason: reason ?? null }
+  });
+  return getTicket(ctx, id);
+}
+function sweepOrphanedBurning(ctx, featureId, reason) {
+  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, {
+      type: "ticket.failed",
+      message: `ticket ${t.seq} failed: ${reason}`,
+      ticketId: t.id,
+      data: { error: reason, orphaned: true }
+    });
+  }
+  return orphaned.map((t) => ({ ...t, status: "failed", error: reason }));
+}
+function updateTicket(ctx, id, patch) {
+  const current2 = ctx.db.select().from(tickets).where(eq7(tickets.id, id)).get();
+  if (!current2)
+    throw new NotFoundError(`ticket ${id} not found`);
+  const set = {};
+  if (patch.status !== undefined)
+    set.status = patch.status;
+  if (patch.commits !== undefined)
+    set.commits = patch.commits;
+  if (patch.error !== undefined)
+    set.error = patch.error;
+  if (patch.attemptBranch !== undefined)
+    set.attemptBranch = patch.attemptBranch;
+  if (patch.conflictFiles !== undefined)
+    set.conflictFiles = patch.conflictFiles;
+  ctx.db.update(tickets).set(set).where(eq7(tickets.id, id)).run();
+  emit(ctx, current2.featureId, {
+    type: "ticket.updated",
+    message: `ticket ${current2.seq} \u2192 ${patch.status ?? current2.status}`,
+    ticketId: id,
+    data: patch
+  });
+  const updated = ctx.db.select().from(tickets).where(eq7(tickets.id, id)).get();
+  return rowToTicket(updated);
+}
+var MUTABLE_STATUSES;
+var init_tickets = __esm(() => {
+  init_src();
+  init_schema();
+  init_errors();
+  init_events();
+  MUTABLE_STATUSES = new Set(["pending", "failed"]);
+});
+
+// src/services/gates.ts
+import { existsSync as existsSync10 } from "fs";
+function checkGate(ctx, check, feature) {
+  switch (check) {
+    case "decisions-file-exists":
+      return fileGate(ctx, feature, "decisions.md", "run the ideation session to capture decisions first");
+    case "all-waypoints-terminal": {
+      const wps = listByFeature(ctx, feature.id);
+      if (wps.length === 0) {
+        return { satisfied: false, reason: "no waypoints charted yet \u2014 chart the map before converging" };
+      }
+      const open = wps.filter((w) => w.status !== "resolved" && w.status !== "dropped");
+      return open.length === 0 ? { satisfied: true } : {
+        satisfied: false,
+        reason: notYetTerminal("waypoint", open.map((w) => w.status), ["open", "claimed"])
+      };
+    }
+    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;
+      return count >= 1 ? { satisfied: true } : { satisfied: false, reason: "no tickets to burn" };
+    }
+    case "all-tickets-terminal": {
+      const tickets2 = listByFeature2(ctx, feature.id);
+      if (tickets2.length === 0)
+        return { satisfied: false, reason: "no tickets have run yet" };
+      const open = tickets2.filter((t) => t.status !== "done" && t.status !== "failed" && t.status !== "cancelled");
+      return open.length === 0 ? { satisfied: true } : {
+        satisfied: false,
+        reason: notYetTerminal("ticket", open.map((t) => t.status), ["pending", "burning"])
+      };
+    }
+    case "human-merge":
+      return { satisfied: false, reason: "use the Merge button to ship" };
+  }
+}
+function notYetTerminal(noun, statuses, order) {
+  const counts = new Map;
+  for (const s of statuses)
+    counts.set(s, (counts.get(s) ?? 0) + 1);
+  const ordered = [
+    ...order.filter((s) => counts.has(s)),
+    ...[...counts.keys()].filter((s) => !order.includes(s))
+  ];
+  const breakdown = ordered.map((s) => `${counts.get(s)} ${s}`).join(", ");
+  return `${statuses.length} ${statuses.length === 1 ? noun : `${noun}s`} not yet terminal (${breakdown})`;
+}
+function fileGate(ctx, feature, fileName, reason) {
+  const project = projectForFeature(ctx, feature);
+  return existsSync10(featureDocPath(project, feature, fileName)) ? { satisfied: true } : { satisfied: false, reason };
+}
+function overrideGate(ctx, featureId, gate, reason) {
+  const feature = getFeatureRow(ctx, featureId);
+  ctx.db.insert(gateOverrides).values({ featureId, gate, reason, ts: Date.now() }).run();
+  emit(ctx, featureId, {
+    type: "gate.overridden",
+    message: `gate ${gate} overridden: ${reason}`,
+    data: { gate, reason }
+  });
+  const next = nextPhase(feature);
+  if (next)
+    return setPhase(ctx, featureId, next, "phase.advanced", `advanced to ${next} (override)`);
+  return feature;
+}
+var init_gates = __esm(() => {
+  init_src();
+  init_schema();
+  init_events();
+  init_feature_docs();
+  init_repo();
+  init_tickets();
+  init_waypoints();
+});
+
+// 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 resolve6, sep } from "path";
+function scaffoldDocs(ctx, feature) {
+  const project = projectForFeature(ctx, feature);
+  const dir = featureDocsDir(project, feature);
+  mkdirSync5(dir, { recursive: true });
+  const briefPath = featureDocPath(project, feature, "brief.md");
+  if (!existsSync11(briefPath)) {
+    const created = new Date().toISOString();
+    const brief = [
+      `# ${feature.title}`,
+      "",
+      feature.oneLiner,
+      "",
+      `- Slug: ${feature.slug}`,
+      `- Created: ${created}`,
+      ""
+    ].join(`
+`);
+    writeFileSync(briefPath, brief, "utf8");
+  }
+  if (feature.mapped) {
+    scaffoldMapDoc(project, feature);
+  }
+  emit(ctx, feature.id, {
+    type: "docs.scaffolded",
+    message: feature.mapped ? `scaffolded docs/features/${feature.slug}/{brief,map}.md` : `scaffolded docs/features/${feature.slug}/brief.md`
+  });
+}
+function scaffoldMapDoc(project, feature, seed) {
+  mkdirSync5(featureDocsDir(project, feature), { recursive: true });
+  const mapPath = featureDocPath(project, feature, "map.md");
+  if (existsSync11(mapPath))
+    return;
+  writeFileSync(mapPath, mapDocBody(feature, seed), "utf8");
+}
+function mapDocBody(feature, seed) {
+  const seeded = {
+    Destination: seed?.destination?.trim(),
+    Notes: seed?.notes?.trim()
+  };
+  const lines = [`# ${feature.title} \u2014 map`, ""];
+  for (const section of MAP_SECTIONS) {
+    lines.push(`## ${section}`, "");
+    const body = seeded[section];
+    if (body)
+      lines.push(body, "");
+  }
+  return lines.join(`
+`);
+}
+function listDocs(ctx, feature) {
+  const project = projectForFeature(ctx, feature);
+  const dir = featureDocsDir(project, feature);
+  if (!existsSync11(dir))
+    return [];
+  return readdirSync3(dir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).map((e) => ({ relPath: e.name, title: readTitle(join10(dir, e.name), e.name) })).sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+function readDoc(ctx, feature, relPath) {
+  const project = projectForFeature(ctx, feature);
+  const dir = featureDocsDir(project, feature);
+  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}`);
+  }
+  if (!existsSync11(target))
+    throw new NotFoundError(`doc not found: ${relPath}`);
+  return { content: readFileSync5(target, "utf8") };
+}
+function readTitle(path, fallback) {
+  try {
+    const firstLine = readFileSync5(path, "utf8").split(`
+`, 1)[0] ?? "";
+    const heading = firstLine.match(/^#\s+(.+)$/);
+    return heading ? heading[1].trim() : fallback;
+  } catch {
+    return fallback;
+  }
+}
+var MAP_SECTIONS;
+var init_knowledge = __esm(() => {
+  init_errors();
+  init_events();
+  init_feature_docs();
+  init_repo();
+  MAP_SECTIONS = [
+    "Destination",
+    "Notes",
+    "Not yet specified",
+    "Out of scope"
+  ];
+});
+
+// src/pty/end-session.ts
+function endSession(ctx, sessionId) {
+  const registry = ptyRegistry();
+  const killed = registry.kill(sessionId);
+  registry.remove(sessionId);
+  const session = markSessionEnded(ctx, sessionId);
+  if (session) {
+    releaseForSession(ctx, sessionId);
+    emitForSession(ctx, session, {
+      type: "session.ended",
+      message: "session ended by user",
+      data: { sessionId, killed }
+    });
+  } else {
+    const existing = getSessionRow(ctx, sessionId);
+    if (!existing)
+      return { sessionId, ok: false, killed };
+  }
+  return { sessionId, ok: true, killed };
+}
+var init_end_session = __esm(() => {
+  init_sessions();
+  init_events();
+  init_waypoints();
+  init_registry();
 });
 
 // src/workflows/research.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync5, readdirSync as readdirSync4 } from "fs";
-import { dirname as dirname4, join as join10 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { run as run2 } from "@ai-hero/sandcastle";
+import { existsSync as existsSync12, mkdirSync as mkdirSync6, readFileSync as readFileSync6, readdirSync as readdirSync4 } from "fs";
+import { dirname as dirname5, join as join11 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { run as run3 } from "@ai-hero/sandcastle";
 import { docker as docker2 } from "@ai-hero/sandcastle/sandboxes/docker";
 import { noSandbox as noSandbox2 } from "@ai-hero/sandcastle/sandboxes/no-sandbox";
 function waypointSlug(waypoint) {
@@ -4164,7 +5269,7 @@ async function researchRun(ctx, deps) {
     return { status: "failed", summary: "no waypoint to research" };
   }
   if (deps.config.sandbox === "docker" && !deps.hasAuthToken) {
-    ctx.emitEvent({ type: AUTH_MISSING_EVENT2, message: AUTH_MISSING_MESSAGE2 });
+    ctx.emitEvent({ type: AUTH_MISSING_EVENT3, message: AUTH_MISSING_MESSAGE3 });
     return { status: "failed", summary: "research aborted: auth token missing" };
   }
   ctx.emitEvent({
@@ -4185,23 +5290,23 @@ async function researchRun(ctx, deps) {
   }
   ctx.emitEvent({
     type: "research.failed",
-    message: `waypoint ${waypoint.seq} research failed: ${errorHeadline2(outcome.error)}`,
+    message: `waypoint ${waypoint.seq} research failed: ${errorHeadline3(outcome.error)}`,
     data: { waypointId: waypoint.id, error: outcome.error }
   });
   return { status: "failed", summary: outcome.error };
 }
-function errorHeadline2(s) {
+function errorHeadline3(s) {
   const lines = s.split(`
 `).map((l) => l.trim()).filter(Boolean);
   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;
-  for (const key of PLACEHOLDERS) {
+  for (const key of PLACEHOLDERS2) {
     out = out.split(`{{${key}}}`).join(values[key]);
   }
   return out;
@@ -4216,32 +5321,32 @@ function interpretResearchResult(result, docRelPath) {
   return { status: "failed", error: "agent produced no commits \u2014 no research summary landed" };
 }
 function researchTemplatePath() {
-  const here = dirname4(fileURLToPath3(import.meta.url));
-  return join10(resolveSkillsRoot(here), "burner", "research-waypoint.md");
+  const here = dirname5(fileURLToPath4(import.meta.url));
+  return join11(resolveSkillsRoot(here), "burner", "research-waypoint.md");
 }
 function readDocsDigestFromDisk2(projectId, slug) {
   const worktree = worktreeDir(projectId, slug);
-  if (!existsSync11(worktree))
+  if (!existsSync12(worktree))
     return "_No talk worktree on disk \u2014 docs digest skipped._";
-  const docsDir = join10(worktree, ...featureDocsRel(slug).split("/"));
-  if (!existsSync11(docsDir))
+  const docsDir = join11(worktree, ...featureDocsRel(slug).split("/"));
+  if (!existsSync12(docsDir))
     return "_No docs/features dir in the talk worktree \u2014 docs digest skipped._";
-  const files = readdirSync4(docsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name)).map((e) => ({ name: e.name, content: readFileSync5(join10(docsDir, e.name), "utf8") }));
+  const files = readdirSync4(docsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md")).sort((a, b) => a.name.localeCompare(b.name)).map((e) => ({ name: e.name, content: readFileSync6(join11(docsDir, e.name), "utf8") }));
   return buildDocsDigest(files);
 }
 async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
   const { project, feature } = ctx;
   const docRelPath = researchDocRel(feature.slug, waypoint);
   const tempBranch = researchBranchName(feature.slug, waypoint.seq, newId("b").slice(2, 10));
-  const template = readFileSync5(researchTemplatePath(), "utf8");
+  const template = readFileSync6(researchTemplatePath(), "utf8");
   const prompt = renderResearchPrompt(template, {
     WAYPOINT_JSON: buildWaypointJson(waypoint),
     FEATURE_BRIEF: buildFeatureBrief(feature),
     DOCS_DIGEST: readDocsDigestFromDisk2(project.id, feature.slug),
     RESEARCH_DOC_PATH: docRelPath
   });
-  mkdirSync5(logsDir(), { recursive: true });
-  const logFilePath = join10(logsDir(), `research-${feature.id}-${waypoint.seq}.log`);
+  mkdirSync6(logsDir(), { recursive: true });
+  const logFilePath = join11(logsDir(), `research-${feature.id}-${waypoint.seq}.log`);
   const throttle = createResearchStreamThrottle((e) => ctx.emitEvent(e));
   const runOptions = {
     agent: buildBurnAgent(config2, token, model),
@@ -4256,7 +5361,7 @@ async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
   let result;
   let salvaged = [];
   try {
-    result = await run2(runOptions);
+    result = await run3(runOptions);
   } catch (err) {
     throttle.flush();
     if (ctx.signal.aborted)
@@ -4268,7 +5373,7 @@ async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
     const removed = await cleanupBurnWorktree(project.repoPath, tempBranch);
     ctx.emitEvent({
       type: "burn.worktree.teardown-failed",
-      message: `waypoint ${waypoint.seq}: agent finished but sandcastle could not remove its worktree (${errorHeadline2(msg)})${removed ? " \u2014 cleaned up" : " \u2014 left on disk"}; landing the ${salvaged.length} commit(s) anyway`,
+      message: `waypoint ${waypoint.seq}: agent finished but sandcastle could not remove its worktree (${errorHeadline3(msg)})${removed ? " \u2014 cleaned up" : " \u2014 left on disk"}; landing the ${salvaged.length} commit(s) anyway`,
       data: { tempBranch, error: msg, cleanedUp: removed }
     });
   }
@@ -4281,7 +5386,7 @@ async function realExecuteResearchRun(ctx, waypoint, config2, token, model) {
     const detail = merge.error ?? "merge failed";
     ctx.emitEvent({
       type: merge.conflict ? "merge.conflict.needs-human" : "research.merge_failed",
-      message: merge.conflict ? `research branch ${tempBranch} conflicts with ${feature.branch} \u2014 merge it manually (git merge ${tempBranch}; resolve; git branch -D ${tempBranch}), then resolve the waypoint` : `could not land ${tempBranch} on ${feature.branch}: ${errorHeadline2(detail)} \u2014 the branch is preserved for manual recovery`,
+      message: merge.conflict ? `research branch ${tempBranch} conflicts with ${feature.branch} \u2014 merge it manually (git merge ${tempBranch}; resolve; git branch -D ${tempBranch}), then resolve the waypoint` : `could not land ${tempBranch} on ${feature.branch}: ${errorHeadline3(detail)} \u2014 the branch is preserved for manual recovery`,
       data: { tempBranch, featureBranch: feature.branch, conflict: merge.conflict ?? false, error: detail }
     });
     return {
@@ -4303,9 +5408,9 @@ function resolveResearchDeps(ctx) {
 }
 function readTokenFromEnvFile2(path) {
   let fromFile;
-  if (existsSync11(path)) {
+  if (existsSync12(path)) {
     try {
-      fromFile = parseEnvFile(readFileSync5(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
+      fromFile = parseEnvFile(readFileSync6(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
     } catch {
       fromFile = undefined;
     }
@@ -4313,7 +5418,7 @@ function readTokenFromEnvFile2(path) {
   const token = fromFile && fromFile.length > 0 ? fromFile : process.env.CLAUDE_CODE_OAUTH_TOKEN;
   return token && token.length > 0 ? token : undefined;
 }
-var AUTH_MISSING_EVENT2 = "auth.missing", AUTH_MISSING_MESSAGE2 = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PLACEHOLDERS, research;
+var AUTH_MISSING_EVENT3 = "auth.missing", AUTH_MISSING_MESSAGE3 = "run `claude setup-token` and put CLAUDE_CODE_OAUTH_TOKEN in ~/.runcastle/.env", PLACEHOLDERS2, research;
 var init_research = __esm(() => {
   init_src();
   init_config_load();
@@ -4321,7 +5426,7 @@ var init_research = __esm(() => {
   init_skills_root();
   init_git();
   init_ticket_burner();
-  PLACEHOLDERS = ["WAYPOINT_JSON", "FEATURE_BRIEF", "DOCS_DIGEST", "RESEARCH_DOC_PATH"];
+  PLACEHOLDERS2 = ["WAYPOINT_JSON", "FEATURE_BRIEF", "DOCS_DIGEST", "RESEARCH_DOC_PATH"];
   research = {
     id: "research",
     run: (ctx) => researchRun(ctx, resolveResearchDeps(ctx))
@@ -4343,12 +5448,12 @@ var init_registry2 = __esm(() => {
 });
 
 // src/workflows/runner.ts
-import { eq as eq6 } from "drizzle-orm";
+import { eq as eq8 } from "drizzle-orm";
 function workflowClaimsFeatureBranch(workflowId) {
   return BRANCH_CLAIMING.has(workflowId);
 }
 function isRunActive(runId) {
-  return controllers.has(runId);
+  return controllers2.has(runId);
 }
 async function startRun(ctx, featureId, workflowId, opts = {}) {
   const feature = getFeatureRow(ctx, featureId);
@@ -4372,7 +5477,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
       claim(ctx, opts.claimWaypointId, runId);
     } catch (e) {
       const summary = e instanceof Error ? e.message : "claim failed";
-      ctx.db.update(runs).set({ status: "failed", endedAt: Date.now(), summary }).where(eq6(runs.id, runId)).run();
+      ctx.db.update(runs).set({ status: "failed", endedAt: Date.now(), summary }).where(eq8(runs.id, runId)).run();
       throw e;
     }
   }
@@ -4383,7 +5488,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
     data: { workflow: workflowId }
   });
   const controller = new AbortController;
-  controllers.set(runId, controller);
+  controllers2.set(runId, controller);
   const talkWorktree = worktreeDir(project.id, feature.slug);
   const talkDetached = workflowClaimsFeatureBranch(workflowId) ? await detachWorktree(talkWorktree) : false;
   const wctx = {
@@ -4405,7 +5510,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
   };
@@ -4416,7 +5521,7 @@ async function startRun(ctx, featureId, workflowId, opts = {}) {
   return { runId, done };
 }
 function cancelRun(runId) {
-  controllers.get(runId)?.abort();
+  controllers2.get(runId)?.abort();
 }
 async function executeRun(ctx, runId, featureId, workflow2, runPromise, controller, cleanup) {
   let status = "failed";
@@ -4435,9 +5540,9 @@ async function executeRun(ctx, runId, featureId, workflow2, runPromise, controll
     }
     emit(ctx, featureId, { type: "run.error", message: summary, runId });
   } finally {
-    controllers.delete(runId);
+    controllers2.delete(runId);
   }
-  ctx.db.update(runs).set({ status, endedAt: Date.now(), summary }).where(eq6(runs.id, runId)).run();
+  ctx.db.update(runs).set({ status, endedAt: Date.now(), summary }).where(eq8(runs.id, runId)).run();
   releaseForSession(ctx, runId);
   if (workflowClaimsFeatureBranch(workflow2)) {
     sweepOrphanedBurning(ctx, featureId, `orphaned \u2014 the run ended (${status}) while it was burning`);
@@ -4467,7 +5572,7 @@ function maybeAutoAdvance(ctx, featureId) {
   if (next)
     setPhase(ctx, featureId, next, "phase.advanced", "auto-advanced to review after successful run");
 }
-var controllers, BRANCH_CLAIMING;
+var controllers2, BRANCH_CLAIMING;
 var init_runner = __esm(() => {
   init_src();
   init_paths();
@@ -4480,12 +5585,12 @@ var init_runner = __esm(() => {
   init_tickets();
   init_waypoints();
   init_registry2();
-  controllers = new Map;
+  controllers2 = new Map;
   BRANCH_CLAIMING = new Set(["ticket-burner"]);
 });
 
 // src/services/features.ts
-import { desc as desc3, eq as eq7 } from "drizzle-orm";
+import { desc as desc4, eq as eq9 } from "drizzle-orm";
 import { rmSync as rmSync2 } from "fs";
 async function createFeature(ctx, input) {
   const project = requireProjectById(ctx, input.projectId);
@@ -4548,7 +5653,7 @@ function getFeatureFull(ctx, id) {
   };
 }
 function list(ctx, projectId) {
-  const rows = ctx.db.select().from(features).where(eq7(features.projectId, projectId)).orderBy(desc3(features.createdAt)).all();
+  const rows = ctx.db.select().from(features).where(eq9(features.projectId, projectId)).orderBy(desc4(features.createdAt)).all();
   return rows.map((row) => {
     const feature = rowToFeature(row);
     const tickets2 = listByFeature2(ctx, feature.id);
@@ -4693,7 +5798,7 @@ function escalateToMap(ctx, featureId, input) {
     return { ok: true, warning: `feature ${feature.slug} is already mapped \u2014 no changes made` };
   }
   const project = projectForFeature(ctx, feature);
-  ctx.db.update(features).set({ mapped: true }).where(eq7(features.id, featureId)).run();
+  ctx.db.update(features).set({ mapped: true }).where(eq9(features.id, featureId)).run();
   scaffoldMapDoc(project, { ...feature, mapped: true }, input);
   emit(ctx, featureId, {
     type: "feature.escalated",
@@ -4710,7 +5815,7 @@ function archiveFeature(ctx, featureId) {
   const live = listSessionsByFeature(ctx, featureId).find((s) => s.status === "live");
   if (live)
     endSession(ctx, live.id);
-  ctx.db.update(features).set({ status: "archived" }).where(eq7(features.id, featureId)).run();
+  ctx.db.update(features).set({ status: "archived" }).where(eq9(features.id, featureId)).run();
   emit(ctx, featureId, {
     type: "feature.archived",
     message: `feature ${feature.slug} archived`,
@@ -4724,7 +5829,7 @@ function unarchiveFeature(ctx, featureId) {
     throw new GateError(`feature ${feature.slug} is not archived`);
   }
   const restored = feature.phase === "shipped" ? "shipped" : "active";
-  ctx.db.update(features).set({ status: restored }).where(eq7(features.id, featureId)).run();
+  ctx.db.update(features).set({ status: restored }).where(eq9(features.id, featureId)).run();
   emit(ctx, featureId, {
     type: "feature.unarchived",
     message: `feature ${feature.slug} unarchived (${restored})`,
@@ -4738,9 +5843,9 @@ async function deleteFeature(ctx, featureId) {
     throw new GateError(`feature ${feature.slug} is shipped \u2014 archive it instead (delete is for non-shipped features)`);
   }
   const project = projectForFeature(ctx, feature);
-  for (const run3 of listRunsByFeature(ctx, featureId)) {
-    if (run3.status === "running")
-      cancelRun(run3.id);
+  for (const run4 of listRunsByFeature(ctx, featureId)) {
+    if (run4.status === "running")
+      cancelRun(run4.id);
   }
   const live = listSessionsByFeature(ctx, featureId).find((s) => s.status === "live");
   if (live)
@@ -4764,13 +5869,13 @@ async function deleteFeature(ctx, featureId) {
   return { ok: true, slug: feature.slug };
 }
 function deleteFeatureRows(ctx, featureId) {
-  ctx.db.delete(tickets).where(eq7(tickets.featureId, featureId)).run();
-  ctx.db.delete(sessions).where(eq7(sessions.featureId, featureId)).run();
-  ctx.db.delete(runs).where(eq7(runs.featureId, featureId)).run();
-  ctx.db.delete(events).where(eq7(events.featureId, featureId)).run();
-  ctx.db.delete(gateOverrides).where(eq7(gateOverrides.featureId, featureId)).run();
-  ctx.db.delete(waypoints).where(eq7(waypoints.featureId, featureId)).run();
-  ctx.db.delete(features).where(eq7(features.id, featureId)).run();
+  ctx.db.delete(tickets).where(eq9(tickets.featureId, featureId)).run();
+  ctx.db.delete(sessions).where(eq9(sessions.featureId, featureId)).run();
+  ctx.db.delete(runs).where(eq9(runs.featureId, featureId)).run();
+  ctx.db.delete(events).where(eq9(events.featureId, featureId)).run();
+  ctx.db.delete(gateOverrides).where(eq9(gateOverrides.featureId, featureId)).run();
+  ctx.db.delete(waypoints).where(eq9(waypoints.featureId, featureId)).run();
+  ctx.db.delete(features).where(eq9(features.id, featureId)).run();
 }
 function gateState(ctx, feature) {
   const gate = nextGate(feature);
@@ -4781,7 +5886,7 @@ function gateState(ctx, feature) {
 }
 function uniqueSlug(ctx, projectId, title) {
   const base = slugify(title);
-  const existing = new Set(ctx.db.select({ slug: features.slug }).from(features).where(eq7(features.projectId, projectId)).all().map((r) => r.slug));
+  const existing = new Set(ctx.db.select({ slug: features.slug }).from(features).where(eq9(features.projectId, projectId)).all().map((r) => r.slug));
   if (!existing.has(base))
     return base;
   let n = 2;
@@ -4813,7 +5918,7 @@ var init_features = __esm(() => {
 import { StreamableHTTPTransport } from "@hono/mcp";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Hono } from "hono";
-import * as z3 from "zod";
+import * as z4 from "zod";
 function headerSessionId(extra) {
   const headers = extra.requestInfo?.headers;
   if (!headers)
@@ -4830,8 +5935,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 };
@@ -4853,17 +5964,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;
@@ -4878,10 +5989,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");
   }
@@ -4889,7 +6000,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" }
@@ -4897,7 +6008,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`,
@@ -4926,13 +6037,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) }] };
 }
@@ -4954,6 +6098,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.",
@@ -4967,7 +6126,7 @@ function buildMcpServer() {
   server.registerTool("emit_tickets", {
     title: "Emit tickets",
     description: "Store the ideation session's ticket batch. Each ticket: title, goal, context, acceptanceCriteria[], seams[], blockedBy[] (1-based positions within THIS batch).",
-    inputSchema: { tickets: z3.array(TicketInput) }
+    inputSchema: { tickets: z4.array(TicketInput) }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -4980,12 +6139,12 @@ function buildMcpServer() {
     title: "Update ticket",
     description: "Rewrite a stored ticket's content \u2014 title, goal, context, acceptanceCriteria, seams (any subset). Only pending or failed tickets can be edited; done/cancelled tickets are history and burning tickets are already running. Use during a revisit when a decision change makes a ticket stale. Get ids from get_feature_context.",
     inputSchema: {
-      id: z3.string(),
-      title: z3.string().optional(),
-      goal: z3.string().optional(),
-      context: z3.string().optional(),
-      acceptanceCriteria: z3.array(z3.string()).optional(),
-      seams: z3.array(z3.string()).optional()
+      id: z4.string(),
+      title: z4.string().optional(),
+      goal: z4.string().optional(),
+      context: z4.string().optional(),
+      acceptanceCriteria: z4.array(z4.string()).optional(),
+      seams: z4.array(z4.string()).optional()
     }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
@@ -4998,7 +6157,7 @@ function buildMcpServer() {
   server.registerTool("cancel_ticket", {
     title: "Cancel ticket",
     description: "Cancel a ticket that is no longer needed (terminal state; only pending or failed tickets). The burner skips cancelled tickets, and tickets blocked by a cancelled one still burn \u2014 cancellation counts as satisfied. Pass a short reason so the timeline explains why.",
-    inputSchema: { id: z3.string(), reason: z3.string().optional() }
+    inputSchema: { id: z4.string(), reason: z4.string().optional() }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -5010,7 +6169,7 @@ function buildMcpServer() {
   server.registerTool("escalate_to_map", {
     title: "Escalate to map",
     description: "Escalate this grilling session into a map when the feature outgrows one context window. Flips the feature to mapped and scaffolds docs/features/<slug>/map.md, seeding Destination + Notes from your arguments (Not-yet-specified and Out-of-scope start empty). Idempotent: calling it on an already-mapped feature warns and changes nothing.",
-    inputSchema: { destination: z3.string(), notes: z3.string().optional() }
+    inputSchema: { destination: z4.string(), notes: z4.string().optional() }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -5024,7 +6183,7 @@ function buildMcpServer() {
   server.registerTool("emit_waypoints", {
     title: "Emit waypoints",
     description: "Batch-create waypoints on the map (the feature must already be mapped \u2014 call escalate_to_map first). Each waypoint: title, type (grilling|research|prototype|task), question, blockedBy[] (1-based positions within THIS batch, and/or ids of already-stored waypoints). Available from any session once mapped \u2014 any session may branch the map.",
-    inputSchema: { waypoints: z3.array(WaypointInput) }
+    inputSchema: { waypoints: z4.array(WaypointInput) }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -5034,7 +6193,7 @@ function buildMcpServer() {
   server.registerTool("resolve_waypoint", {
     title: "Resolve waypoint",
     description: "End the current waypoint: `resolved` (its question is answered) or `dropped` (no longer needed). Write the decision prose to decisions.md (or the gist to map.md Out-of-scope for a drop) FIRST \u2014 this tool flips machinery only (marks the waypoint terminal, frees any dependents on the frontier). `summary` is the one-line gist shown in the UI. Call this exactly once, as the last thing you do.",
-    inputSchema: { id: z3.string(), disposition: WaypointDisposition, summary: z3.string() }
+    inputSchema: { id: z4.string(), disposition: WaypointDisposition, summary: z4.string() }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -5046,7 +6205,7 @@ function buildMcpServer() {
   server.registerTool("record_event", {
     title: "Record event",
     description: "Add a note to the feature timeline (decisions recorded, spec saved, milestones).",
-    inputSchema: { type: z3.string(), message: z3.string() }
+    inputSchema: { type: z4.string(), message: z4.string() }
   }, async (args, extra) => {
     const rs = await resolveCtxSession(extra);
     if (!rs)
@@ -5076,6 +6235,7 @@ var init_server = __esm(() => {
   init_sessions();
   init_features();
   init_events();
+  init_findings();
   init_git();
   init_knowledge();
   init_repo();
@@ -5169,12 +6329,16 @@ import { Hono as Hono2 } from "hono";
 function handleSessionStart(ctx, sessionId, feature, 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, sessionId)?.status === "live";
   markSessionLive(ctx, sessionId, { ccSessionId, transcriptPath });
-  emit(ctx, feature.id, {
-    type: "session.started",
-    message: "session live",
-    data: { sessionId, ccSessionId, transcriptPath }
-  });
+  if (!wasLive) {
+    emit(ctx, feature.id, {
+      type: "session.started",
+      message: source === "resume" ? "session live (conversation resumed)" : "session live",
+      data: { sessionId, ccSessionId, transcriptPath, source: source ?? null }
+    });
+  }
   return {
     hookSpecificOutput: {
       hookEventName: "SessionStart",
@@ -5182,7 +6346,60 @@ function handleSessionStart(ctx, sessionId, feature, payload) {
     }
   };
 }
-function handleUserPrompt(ctx, feature) {
+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);
   const tickets2 = listByFeature2(ctx, feature.id).length;
   return {
     hookSpecificOutput: {
@@ -5221,6 +6438,7 @@ var hooks, hooks_default;
 var init_hooks = __esm(() => {
   init_sessions();
   init_events();
+  init_prep();
   init_repo();
   init_tickets();
   init_waypoints();
@@ -5242,6 +6460,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({});
@@ -5249,7 +6479,7 @@ var init_hooks = __esm(() => {
         case "session-start":
           return c.json(handleSessionStart(ctx, sessionId, feature, body.payload));
         case "user-prompt":
-          return c.json(handleUserPrompt(ctx, feature));
+          return c.json(handleUserPrompt(ctx, sessionId, feature, body.payload));
         case "session-end":
           return c.json(handleSessionEnd(ctx, sessionId, feature));
         default:
@@ -5314,9 +6544,9 @@ var init_stream = __esm(() => {
 });
 
 // src/routes/web.ts
-import { existsSync as existsSync12, statSync } from "fs";
+import { existsSync as existsSync13, statSync } from "fs";
 import { readFile } from "fs/promises";
-import { extname, join as join11, 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";
 }
@@ -5334,7 +6564,7 @@ function safeJoin(root, pathname) {
   } catch {
     return null;
   }
-  const joined = normalize(join11(root, decoded));
+  const joined = normalize(join12(root, decoded));
   if (joined !== root && !joined.startsWith(root + sep2))
     return null;
   return joined;
@@ -5342,12 +6572,12 @@ 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 indexHtml = join11(root, "index.html");
+  const root = resolve7(distDir);
+  const indexHtml = join12(root, "index.html");
   app.get("*", async (c, next) => {
     const { pathname } = new URL(c.req.url);
     if (/^\/(api|mcp|ws|health)(\/|$)/.test(pathname))
@@ -5367,7 +6597,7 @@ function mountWebApp(app, distDir) {
 }
 function mountWebAppIfBuilt(app) {
   const dist = resolveWebDist();
-  if (existsSync12(join11(dist, "index.html")))
+  if (existsSync13(join12(dist, "index.html")))
     mountWebApp(app, dist);
 }
 var MIME;
@@ -5414,14 +6644,14 @@ var init_context = __esm(() => {
 });
 
 // src/trpc/routers/docs.ts
-import * as z4 from "zod";
+import * as z5 from "zod";
 var docsRouter;
 var init_docs = __esm(() => {
   init_knowledge();
   init_repo();
   init_context();
   docsRouter = router({
-    read: publicProcedure.input(z4.object({ featureId: z4.string(), relPath: z4.string() })).query(({ ctx, input }) => {
+    read: publicProcedure.input(z5.object({ featureId: z5.string(), relPath: z5.string() })).query(({ ctx, input }) => {
       const feature = getFeatureRow(ctx, input.featureId);
       return readDoc(ctx, feature, input.relPath);
     })
@@ -5429,23 +6659,23 @@ var init_docs = __esm(() => {
 });
 
 // src/trpc/routers/events.ts
-import * as z5 from "zod";
+import * as z6 from "zod";
 var eventsRouter;
 var init_events2 = __esm(() => {
   init_events();
   init_context();
   eventsRouter = router({
-    list: publicProcedure.input(z5.object({ featureId: z5.string(), afterId: z5.number().optional() })).query(({ ctx, input }) => listAfter(ctx, input.featureId, input.afterId)),
-    listByProject: publicProcedure.input(z5.object({ projectId: z5.string(), afterId: z5.number().optional() })).query(({ ctx, input }) => listByProject(ctx, input.projectId, input.afterId))
+    list: publicProcedure.input(z6.object({ featureId: z6.string(), afterId: z6.number().optional() })).query(({ ctx, input }) => listAfter(ctx, input.featureId, input.afterId)),
+    listByProject: publicProcedure.input(z6.object({ projectId: z6.string(), afterId: z6.number().optional() })).query(({ ctx, input }) => listByProject(ctx, input.projectId, input.afterId))
   });
 });
 
 // src/launcher/artifacts.ts
-import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync2 } from "fs";
-import { fileURLToPath as fileURLToPath4 } from "url";
-import { join as join12 } from "path";
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath5 } from "url";
+import { join as join13 } from "path";
 function hookClientPath() {
-  return resolveAsset(ASSET_ENV.hookClient, fileURLToPath4(new URL("./hook-client.ts", import.meta.url)));
+  return resolveAsset(ASSET_ENV.hookClient, fileURLToPath5(new URL("./hook-client.ts", import.meta.url)));
 }
 function serverUrlFor(config2) {
   return `http://localhost:${config2.serverPort}`;
@@ -5637,6 +6867,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",
@@ -5646,7 +6939,10 @@ function renderSettings(hookClient) {
   return {
     permissions: { allow: [...RUNCASTLE_MCP_ALLOW_RULES, ...SESSION_BASH_ALLOW_RULES] },
     hooks: {
-      SessionStart: [{ matcher: "startup", hooks: [cmd("session-start")] }],
+      SessionStart: SESSION_START_SOURCES.map((source) => ({
+        matcher: source,
+        hooks: [cmd("session-start")]
+      })),
       UserPromptSubmit: [{ hooks: [cmd("user-prompt")] }],
       SessionEnd: [{ hooks: [cmd("session-end")] }]
     }
@@ -5664,18 +6960,21 @@ 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);
-  mkdirSync6(dir, { recursive: true });
-  const systemPromptPath = join12(dir, "system-prompt.md");
-  const settingsPath = join12(dir, "settings.json");
-  const mcpConfigPath = join12(dir, "mcp.json");
-  writeFileSync2(systemPromptPath, renderSystemPrompt(feature, session.kind, waypoint), "utf8");
+  mkdirSync7(dir, { recursive: true });
+  const systemPromptPath = join13(dir, "system-prompt.md");
+  const settingsPath = join13(dir, "settings.json");
+  const mcpConfigPath = join13(dir, "mcp.json");
+  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 };
 }
-var RUNCASTLE_MCP_ALLOW_RULES, SESSION_BASH_ALLOW_RULES;
+var RUNCASTLE_MCP_ALLOW_RULES, SESSION_BASH_ALLOW_RULES, SESSION_START_SOURCES;
 var init_artifacts = __esm(() => {
   init_paths();
   init_asset_paths();
@@ -5688,7 +6987,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:*)",
@@ -5700,13 +7000,14 @@ var init_artifacts = __esm(() => {
     "Bash(git branch:*)",
     "Bash(git show:*)"
   ];
+  SESSION_START_SOURCES = ["startup", "resume", "clear", "compact", "fork"];
 });
 
 // src/launcher/launcher.ts
-import { existsSync as existsSync13 } from "fs";
-import { dirname as dirname5, join as join13, resolve as resolve7 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
-import { and as and6, eq as eq8 } from "drizzle-orm";
+import { existsSync as existsSync14 } from "fs";
+import { dirname as dirname6, join as join14, resolve as resolve8 } from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
+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})`;
@@ -5720,7 +7021,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",
@@ -5737,23 +7038,23 @@ function resolveClaudeExecutable() {
 function claudeSpawnTarget(claudeArgs) {
   return spawnTargetFor(resolveClaudeExecutable(), claudeArgs);
 }
-function resolvePluginDir(fromDir = dirname5(fileURLToPath5(import.meta.url))) {
-  const rel = join13("packages", "skills", "packs", "runcastle");
+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 = join13(resolve7(override), "packs", "runcastle");
-    if (existsSync13(dir2))
+    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}`);
   }
   const searched = [];
   let dir = fromDir;
   for (let i = 0;i < 8; i += 1) {
-    const candidate = join13(dir, rel);
+    const candidate = join14(dir, rel);
     searched.push(candidate);
-    if (existsSync13(candidate))
+    if (existsSync14(candidate))
       return candidate;
-    const parent = dirname5(dir);
+    const parent = dirname6(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -5763,7 +7064,7 @@ function resolvePluginDir(fromDir = dirname5(fileURLToPath5(import.meta.url))) {
   `)}`);
 }
 function activeRunFor(ctx, featureId) {
-  const row = ctx.db.select().from(runs).where(and6(eq8(runs.featureId, featureId), eq8(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) {
@@ -5776,6 +7077,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);
@@ -5883,7 +7207,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, {
@@ -5903,6 +7228,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) {
@@ -5919,6 +7313,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);
 }
@@ -5975,7 +7370,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: {
@@ -5986,7 +7381,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 }
@@ -6009,15 +7404,16 @@ 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 }
     });
+    armSessionReadyWatchdog(ctx, session);
   } 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" }
@@ -6032,6 +7428,7 @@ var init_launcher = __esm(() => {
   init_skills_root();
   init_schema();
   init_errors();
+  init_end_session();
   init_registry();
   init_events();
   init_gates();
@@ -6040,8 +7437,11 @@ var init_launcher = __esm(() => {
   init_tickets();
   init_waypoints();
   init_runner();
+  init_findings();
+  init_prep();
   init_artifacts();
   init_sessions();
+  init_sessions();
   init_end_session();
   CC_NESTING_ENV = [
     "CLAUDE_CODE_CHILD_SESSION",
@@ -6056,7 +7456,7 @@ var init_launcher = __esm(() => {
 });
 
 // src/trpc/routers/feature.ts
-import * as z6 from "zod";
+import * as z7 from "zod";
 var gateId, featureRouter;
 var init_feature = __esm(() => {
   init_src();
@@ -6067,37 +7467,38 @@ var init_feature = __esm(() => {
   init_git();
   init_repo();
   init_context();
-  gateId = z6.enum(["G1", "G2", "G3", "G4", "G5"]);
+  gateId = z7.enum(["G1", "G2", "G3", "G4", "G5"]);
   featureRouter = router({
-    create: publicProcedure.input(z6.object({
-      projectId: z6.string(),
-      title: z6.string().min(1),
-      oneLiner: z6.string(),
-      baseBranch: z6.string().optional()
+    create: publicProcedure.input(z7.object({
+      projectId: z7.string(),
+      title: z7.string().min(1),
+      oneLiner: z7.string(),
+      baseBranch: z7.string().optional()
     })).mutation(({ ctx, input }) => createFeature(ctx, input)),
-    list: publicProcedure.input(z6.object({ projectId: z6.string() })).query(({ ctx, input }) => list(ctx, input.projectId)),
-    get: publicProcedure.input(z6.object({ id: z6.string() })).query(({ ctx, input }) => getFeatureFull(ctx, input.id)),
-    launchSession: publicProcedure.input(z6.object({
-      featureId: z6.string(),
+    list: publicProcedure.input(z7.object({ projectId: z7.string() })).query(({ ctx, input }) => list(ctx, input.projectId)),
+    get: publicProcedure.input(z7.object({ id: z7.string() })).query(({ ctx, input }) => getFeatureFull(ctx, input.id)),
+    launchSession: publicProcedure.input(z7.object({
+      featureId: z7.string(),
       kind: SessionKind,
-      kickoffLine: z6.string().min(1).optional()
+      kickoffLine: z7.string().min(1).optional()
     })).mutation(({ ctx, input }) => launchSession(ctx, input)),
-    workWaypoint: publicProcedure.input(z6.object({ featureId: z6.string(), waypointId: z6.string() })).mutation(({ ctx, input }) => workWaypoint(ctx, input)),
-    converge: publicProcedure.input(z6.object({ featureId: z6.string(), overrideReason: z6.string().min(1).optional() })).mutation(({ ctx, input }) => converge(ctx, { featureId: input.featureId, overrideReason: input.overrideReason })),
-    endSession: publicProcedure.input(z6.object({ sessionId: z6.string() })).mutation(({ ctx, input }) => endSession(ctx, input.sessionId)),
-    advance: publicProcedure.input(z6.object({ featureId: z6.string() })).mutation(({ ctx, input }) => advance(ctx, input.featureId)),
-    overrideGate: publicProcedure.input(z6.object({ featureId: z6.string(), gate: gateId, reason: z6.string().min(1) })).mutation(({ ctx, input }) => overrideGate(ctx, input.featureId, input.gate, input.reason)),
-    archive: publicProcedure.input(z6.object({ featureId: z6.string() })).mutation(({ ctx, input }) => archiveFeature(ctx, input.featureId)),
-    unarchive: publicProcedure.input(z6.object({ featureId: z6.string() })).mutation(({ ctx, input }) => unarchiveFeature(ctx, input.featureId)),
-    delete: publicProcedure.input(z6.object({ featureId: z6.string() })).mutation(({ ctx, input }) => deleteFeature(ctx, input.featureId)),
-    burn: publicProcedure.input(z6.object({ featureId: z6.string(), model: z6.string().min(1).optional() })).mutation(({ ctx, input }) => burn(ctx, input.featureId, { modelOverride: input.model })),
-    testDrive: publicProcedure.input(z6.object({ featureId: z6.string(), action: z6.enum(["start", "stop"]) })).mutation(async ({ 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 })),
+    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)),
+    overrideGate: publicProcedure.input(z7.object({ featureId: z7.string(), gate: gateId, reason: z7.string().min(1) })).mutation(({ ctx, input }) => overrideGate(ctx, input.featureId, input.gate, input.reason)),
+    archive: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => archiveFeature(ctx, input.featureId)),
+    unarchive: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => unarchiveFeature(ctx, input.featureId)),
+    delete: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(({ ctx, input }) => deleteFeature(ctx, input.featureId)),
+    burn: publicProcedure.input(z7.object({ featureId: z7.string(), model: z7.string().min(1).optional() })).mutation(({ ctx, input }) => burn(ctx, input.featureId, { modelOverride: input.model })),
+    testDrive: publicProcedure.input(z7.object({ featureId: z7.string(), action: z7.enum(["start", "stop"]) })).mutation(async ({ ctx, input }) => {
       const feature = getFeatureRow(ctx, input.featureId);
       const project = projectForFeature(ctx, feature);
       return testDrive(ctx, project, feature, input.action);
     }),
     driveInfo: publicProcedure.query(() => activeDriveInfo()),
-    merge: publicProcedure.input(z6.object({ featureId: z6.string() })).mutation(async ({ ctx, input }) => {
+    merge: publicProcedure.input(z7.object({ featureId: z7.string() })).mutation(async ({ ctx, input }) => {
       const feature = getFeatureRow(ctx, input.featureId);
       const project = projectForFeature(ctx, feature);
       if (activeTestDriveFeatureId() === feature.id) {
@@ -6120,9 +7521,9 @@ var init_feature = __esm(() => {
 });
 
 // src/services/fsbrowse.ts
-import { existsSync as existsSync14, readdirSync as readdirSync5, statSync as statSync2 } from "fs";
+import { existsSync as existsSync15, readdirSync as readdirSync5, statSync as statSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { basename, dirname as dirname6, isAbsolute, join as join14, 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 === "")
@@ -6131,12 +7532,12 @@ function expandPath(input, home = homedir2()) {
   if (out === "~")
     out = home;
   else if (out.startsWith("~/") || out.startsWith("~\\"))
-    out = join14(home, out.slice(2));
-  return resolve8(out);
+    out = join15(home, out.slice(2));
+  return resolve9(out);
 }
 function looksLikeRepo(dir) {
   try {
-    return existsSync14(join14(dir, ".git"));
+    return existsSync15(join15(dir, ".git"));
   } catch {
     return false;
   }
@@ -6147,20 +7548,20 @@ function listRoots(home = homedir2()) {
     for (let code = 67;code <= 90; code++) {
       const drive = `${String.fromCharCode(code)}:${sep3}`;
       try {
-        if (existsSync14(drive))
+        if (existsSync15(drive))
           roots.push({ label: drive.replace(/\\$/, ""), path: drive, kind: "drive" });
       } catch {}
     }
   } else {
     roots.push({ label: "/", path: "/", kind: "drive" });
   }
-  if (existsSync14(home))
+  if (existsSync15(home))
     roots.push({ label: "Home", path: home, kind: "home" });
   const seen = new Set(roots.map(pathKey));
   for (const name of COMMON_DIRS) {
-    const candidate = join14(home, name);
+    const candidate = join15(home, name);
     const key = pathKey({ path: candidate });
-    if (seen.has(key) || !existsSync14(candidate))
+    if (seen.has(key) || !existsSync15(candidate))
       continue;
     seen.add(key);
     roots.push({ label: name, path: candidate, kind: "common" });
@@ -6175,7 +7576,7 @@ function crumbsFor(dir) {
   let cur = dir;
   for (;; ) {
     out.unshift({ name: basename(cur) || cur, path: cur });
-    const parent = dirname6(cur);
+    const parent = dirname7(cur);
     if (parent === cur)
       break;
     cur = parent;
@@ -6183,7 +7584,7 @@ function crumbsFor(dir) {
   return out;
 }
 function parentOf(dir) {
-  const parent = dirname6(dir);
+  const parent = dirname7(dir);
   return parent === dir ? null : parent;
 }
 function browseDir(input, showHidden = false, home = homedir2()) {
@@ -6191,13 +7592,13 @@ function browseDir(input, showHidden = false, home = homedir2()) {
   if (!isAbsolute(target)) {
     throw new InvalidInputError(`path is not absolute: ${target}`);
   }
-  if (!existsSync14(target)) {
+  if (!existsSync15(target)) {
     throw new InvalidInputError(`path does not exist: ${target}`);
   }
   let dir = target;
   try {
     if (!statSync2(target).isDirectory())
-      dir = dirname6(target);
+      dir = dirname7(target);
   } catch (e) {
     throw new InvalidInputError(`cannot read path: ${target} (${errMsg2(e)})`);
   }
@@ -6219,7 +7620,7 @@ function browseDir(input, showHidden = false, home = homedir2()) {
       continue;
     if (!showHidden && name.startsWith("."))
       continue;
-    const path = join14(dir, name);
+    const path = join15(dir, name);
     const isSymlink = dirent.isSymbolicLink();
     let isDirectory = dirent.isDirectory();
     if (isSymlink) {
@@ -6254,9 +7655,9 @@ var init_fsbrowse = __esm(() => {
 });
 
 // src/services/projects.ts
-import { existsSync as existsSync15 } from "fs";
-import { basename as basename2, join as join15 } from "path";
-import { eq as eq9, isNull } from "drizzle-orm";
+import { existsSync as existsSync16 } from "fs";
+import { basename as basename2, join as join16 } from "path";
+import { eq as eq11, isNull } from "drizzle-orm";
 function listProjects(ctx) {
   return ctx.db.select().from(projects).where(isNull(projects.closedAt)).all().map(rowToProject);
 }
@@ -6278,13 +7679,14 @@ async function openProject(ctx, rawPath) {
   const name = basename2(repoPath) || repoPath;
   const existing = getProjectByRepoPath(ctx, repoPath) ?? findProjectByCanonPath(ctx, repoPath);
   if (existing) {
-    ctx.db.update(projects).set({ mainBranch, repoPath, closedAt: null }).where(eq9(projects.id, existing.id)).run();
+    ctx.db.update(projects).set({ mainBranch, repoPath, closedAt: null }).where(eq11(projects.id, existing.id)).run();
     const reopened = { ...existing, mainBranch, repoPath };
     emitProject(ctx, existing.id, {
       type: "project.opened",
       message: `project ${existing.name} re-opened at ${repoPath} (${mainBranch})`
     });
     warnIfTranslatedMount(ctx, existing.id, repoPath);
+    maybeAutoPrepare(ctx, reopened);
     return reopened;
   }
   const row = {
@@ -6302,14 +7704,25 @@ async function openProject(ctx, rawPath) {
     message: `project ${name} at ${repoPath} (${mainBranch})`
   });
   warnIfTranslatedMount(ctx, project.id, repoPath);
+  maybeAutoPrepare(ctx, project);
   return project;
 }
+function maybeAutoPrepare(ctx, project) {
+  if (!shouldAutoPrepare(ctx, project))
+    return;
+  startPrep(ctx, project.id).catch((e) => {
+    emitProject(ctx, project.id, {
+      type: "prep.run.failed",
+      message: `could not start preparation: ${e instanceof Error ? e.message : String(e)}`
+    });
+  });
+}
 function closeProject(ctx, projectId) {
   const project = requireProjectById(ctx, projectId);
   if (projectHasActiveRun(ctx, projectId)) {
     throw new InvalidInputError(`cannot close ${project.name}: a run is in flight \u2014 wait for it to finish or cancel it first`);
   }
-  ctx.db.update(projects).set({ closedAt: Date.now() }).where(eq9(projects.id, projectId)).run();
+  ctx.db.update(projects).set({ closedAt: Date.now() }).where(eq11(projects.id, projectId)).run();
   emitProject(ctx, projectId, {
     type: "project.closed",
     message: `project ${project.name} closed`
@@ -6318,7 +7731,7 @@ function closeProject(ctx, projectId) {
 }
 function renameProject(ctx, projectId, name) {
   const project = requireProjectById(ctx, projectId);
-  ctx.db.update(projects).set({ name }).where(eq9(projects.id, projectId)).run();
+  ctx.db.update(projects).set({ name }).where(eq11(projects.id, projectId)).run();
   emitProject(ctx, projectId, {
     type: "project.renamed",
     message: `project renamed ${project.name} \u2192 ${name}`,
@@ -6336,7 +7749,7 @@ async function assertRepoTolerant(ctx, repoPath) {
   } catch (e) {
     if (!isNotImplemented(e))
       throw e;
-    if (!existsSync15(join15(repoPath, ".git"))) {
+    if (!existsSync16(join16(repoPath, ".git"))) {
       throw new InvalidInputError(`not a git repository: ${repoPath}`);
     }
   }
@@ -6357,31 +7770,63 @@ var init_projects = __esm(() => {
   init_events();
   init_fsbrowse();
   init_git();
+  init_prep();
   init_repo();
 });
 
 // src/trpc/routers/project.ts
-import * as z7 from "zod";
+import * as z8 from "zod";
 var projectRouter;
 var init_project = __esm(() => {
+  init_src();
+  init_findings();
   init_fsbrowse();
   init_git();
+  init_prep();
+  init_launcher();
+  init_sessions();
   init_projects();
   init_repo();
   init_context();
   projectRouter = router({
     list: publicProcedure.query(({ ctx }) => listProjects(ctx)),
     roots: publicProcedure.query(() => listRoots()),
-    browse: publicProcedure.input(z7.object({ dir: z7.string().optional(), showHidden: z7.boolean().optional() }).optional()).query(({ input }) => browseDir(input?.dir, input?.showHidden ?? false)),
-    branches: publicProcedure.input(z7.object({ projectId: z7.string() })).query(({ ctx, input }) => listBranches(requireProjectById(ctx, input.projectId))),
-    open: publicProcedure.input(z7.object({ repoPath: z7.string().min(1) })).mutation(({ ctx, input }) => openProject(ctx, input.repoPath)),
-    close: publicProcedure.input(z7.object({ projectId: z7.string() })).mutation(({ ctx, input }) => closeProject(ctx, input.projectId)),
-    rename: publicProcedure.input(z7.object({ projectId: z7.string(), name: z7.string().min(1) })).mutation(({ ctx, input }) => renameProject(ctx, input.projectId, input.name))
+    browse: publicProcedure.input(z8.object({ dir: z8.string().optional(), showHidden: z8.boolean().optional() }).optional()).query(({ input }) => browseDir(input?.dir, input?.showHidden ?? false)),
+    branches: publicProcedure.input(z8.object({ projectId: z8.string() })).query(({ ctx, input }) => listBranches(requireProjectById(ctx, input.projectId))),
+    open: publicProcedure.input(z8.object({ repoPath: z8.string().min(1) })).mutation(({ ctx, input }) => openProject(ctx, input.repoPath)),
+    close: publicProcedure.input(z8.object({ projectId: z8.string() })).mutation(({ ctx, input }) => closeProject(ctx, input.projectId)),
+    rename: publicProcedure.input(z8.object({ projectId: z8.string(), name: z8.string().min(1) })).mutation(({ ctx, input }) => renameProject(ctx, input.projectId, input.name)),
+    prepare: publicProcedure.input(z8.object({
+      projectId: z8.string(),
+      refresh: z8.boolean().optional(),
+      keys: z8.array(PreparedKey).optional()
+    })).mutation(async ({ ctx, input }) => {
+      const { prepId, keys } = await startPrep(ctx, input.projectId, {
+        ...input.refresh !== undefined ? { refresh: input.refresh } : {},
+        ...input.keys ? { keys: input.keys } : {}
+      });
+      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 };
+    }),
+    prep: publicProcedure.input(z8.object({ projectId: z8.string() })).query(async ({ ctx, input }) => {
+      const project = requireProjectById(ctx, input.projectId);
+      return {
+        latest: latestPrep(ctx, project.id),
+        running: isPreparing(project.id),
+        pendingKeys: keysToPrepare(ctx, project),
+        findings: await listFindings(ctx, project)
+      };
+    })
   });
 });
 
 // src/trpc/routers/run.ts
-import * as z8 from "zod";
+import * as z9 from "zod";
 var runRouter;
 var init_run = __esm(() => {
   init_agent_stream();
@@ -6389,9 +7834,9 @@ var init_run = __esm(() => {
   init_runner();
   init_context();
   runRouter = router({
-    get: publicProcedure.input(z8.object({ runId: z8.string() })).query(({ ctx, input }) => getRunRow(ctx, input.runId)),
-    agentTranscript: publicProcedure.input(z8.object({ ticketId: z8.string(), after: z8.number().int().optional() })).query(({ input }) => readTranscript(input.ticketId, input.after ?? -1)),
-    cancel: publicProcedure.input(z8.object({ runId: z8.string() })).mutation(({ input }) => {
+    get: publicProcedure.input(z9.object({ runId: z9.string() })).query(({ ctx, input }) => getRunRow(ctx, input.runId)),
+    agentTranscript: publicProcedure.input(z9.object({ ticketId: z9.string(), after: z9.number().int().optional() })).query(({ input }) => readTranscript(input.ticketId, input.after ?? -1)),
+    cancel: publicProcedure.input(z9.object({ runId: z9.string() })).mutation(({ input }) => {
       cancelRun(input.runId);
       return { ok: true };
     })
@@ -6399,15 +7844,15 @@ var init_run = __esm(() => {
 });
 
 // src/services/settings.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname7 } from "path";
-import * as z9 from "zod";
-import { eq as eq10 } from "drizzle-orm";
+import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname8 } from "path";
+import * as z10 from "zod";
+import { eq as eq12 } from "drizzle-orm";
 function readRawConfig(configFile) {
-  if (!existsSync16(configFile))
+  if (!existsSync17(configFile))
     return {};
   try {
-    const parsed = JSON.parse(readFileSync6(configFile, "utf8"));
+    const parsed = JSON.parse(readFileSync7(configFile, "utf8"));
     if (typeof parsed !== "object" || parsed === null)
       return {};
     return foldLegacyModelConfig(parsed);
@@ -6431,33 +7876,51 @@ function stepModelFields(fileRaw) {
   });
 }
 function projectOverrides(ctx, projectId) {
-  const row = ctx.db.select({ model: projects.model, sandbox: projects.sandbox, devCommand: projects.devCommand }).from(projects).where(eq10(projects.id, projectId)).get();
+  const row = ctx.db.select({
+    model: projects.model,
+    sandbox: projects.sandbox,
+    devCommand: projects.devCommand,
+    setupCommand: projects.setupCommand,
+    verifyCommands: projects.verifyCommands,
+    knownFailures: projects.knownFailures,
+    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,
     sandbox: row?.sandbox ?? null,
-    devCommand: row?.devCommand ?? null
+    devCommand: row?.devCommand ?? null,
+    setupCommand: row?.setupCommand ?? null,
+    verifyCommands: row?.verifyCommands ?? null,
+    knownFailures: row?.knownFailures ?? null,
+    dbResetCommand: row?.dbResetCommand ?? null,
+    driveSetupCommand: row?.driveSetupCommand ?? null,
+    driveStopCommand: row?.driveStopCommand ?? null,
+    driveEnv: row?.driveEnv ?? null
   };
 }
-function resolveField(desc4, layers) {
+function resolveField(desc5, layers) {
   const scoped = layers.overrides !== null;
-  const scope = scoped && desc4.projectColumn ? "project" : "global";
-  const base = { key: desc4.key, restartRequired: desc4.restartRequired, scope };
-  if (desc4.envVar) {
-    const raw = layers.env[desc4.envVar];
+  const scope = scoped && desc5.projectColumn ? "project" : "global";
+  const base = { key: desc5.key, restartRequired: desc5.restartRequired, scope };
+  if (desc5.envVar) {
+    const raw = layers.env[desc5.envVar];
     if (raw !== undefined && raw !== "") {
-      return { ...base, value: desc4.parseEnv(raw), source: "env", editable: false };
+      return { ...base, value: desc5.parseEnv(raw), source: "env", editable: false };
     }
   }
-  if (layers.overrides && desc4.projectColumn) {
-    const ov = layers.overrides[desc4.projectColumn];
+  if (layers.overrides && desc5.projectColumn) {
+    const ov = layers.overrides[desc5.projectColumn];
     if (ov !== null && ov !== "") {
       return { ...base, value: ov, source: "project", editable: true };
     }
   }
-  if (desc4.configKey && Object.prototype.hasOwnProperty.call(layers.fileRaw, desc4.configKey)) {
-    return { ...base, value: layers.fileRaw[desc4.configKey], source: "file", editable: true };
+  if (desc5.configKey && Object.prototype.hasOwnProperty.call(layers.fileRaw, desc5.configKey)) {
+    return { ...base, value: layers.fileRaw[desc5.configKey], source: "file", editable: true };
   }
-  const value = desc4.configKey ? DEFAULTS[desc4.configKey] ?? null : null;
+  const value = desc5.configKey ? DEFAULTS[desc5.configKey] ?? null : null;
   return { ...base, value, source: "default", editable: true };
 }
 function getSettings(ctx, projectId, io = {}) {
@@ -6474,59 +7937,61 @@ function updateSettings(ctx, input, io = {}) {
   if (input.key.startsWith("stepModels.")) {
     return updateStepModel(ctx, input, configFile, io);
   }
-  const desc4 = DESCRIPTORS.find((d) => d.key === input.key);
-  if (!desc4)
+  const desc5 = DESCRIPTORS.find((d) => d.key === input.key);
+  if (!desc5)
     throw new InvalidInputError(`unknown setting: ${input.key}`);
-  if (desc4.envVar) {
-    const raw = env[desc4.envVar];
+  if (desc5.envVar) {
+    const raw = env[desc5.envVar];
     if (raw !== undefined && raw !== "") {
-      throw new InvalidInputError(`${desc4.key} is set by environment variable ${desc4.envVar}; unset it to edit`);
+      throw new InvalidInputError(`${desc5.key} is set by environment variable ${desc5.envVar}; unset it to edit`);
     }
   }
-  const toProject = input.projectId !== undefined && desc4.projectColumn !== undefined;
+  const toProject = input.projectId !== undefined && desc5.projectColumn !== undefined;
   if (input.value === null) {
     if (!toProject)
-      throw new InvalidInputError(`${desc4.key} cannot be cleared`);
+      throw new InvalidInputError(`${desc5.key} cannot be cleared`);
     const project = requireProjectById(ctx, input.projectId);
-    ctx.db.update(projects).set({ [desc4.projectColumn]: null }).where(eq10(projects.id, project.id)).run();
+    ctx.db.update(projects).set({ [desc5.projectColumn]: null }).where(eq12(projects.id, project.id)).run();
+    recordHuman(ctx, project.id, desc5.key, null);
     emitProject(ctx, project.id, {
       type: "settings.updated",
-      message: `${desc4.key} override cleared`,
-      data: { key: desc4.key, scope: "project", value: null }
+      message: `${desc5.key} override cleared`,
+      data: { key: desc5.key, scope: "project", value: null }
     });
-    return field(getSettings(ctx, input.projectId, io), desc4.key);
+    return field(getSettings(ctx, input.projectId, io), desc5.key);
   }
-  const parsed = desc4.valueSchema.safeParse(input.value);
+  const parsed = desc5.valueSchema.safeParse(input.value);
   if (!parsed.success) {
-    throw new InvalidInputError(`invalid value for ${desc4.key}: ${parsed.error.issues[0]?.message}`);
+    throw new InvalidInputError(`invalid value for ${desc5.key}: ${parsed.error.issues[0]?.message}`);
   }
   const value = parsed.data;
   if (toProject) {
     const project = requireProjectById(ctx, input.projectId);
-    ctx.db.update(projects).set({ [desc4.projectColumn]: String(value) }).where(eq10(projects.id, project.id)).run();
+    ctx.db.update(projects).set({ [desc5.projectColumn]: String(value) }).where(eq12(projects.id, project.id)).run();
+    recordHuman(ctx, project.id, desc5.key, String(value));
     emitProject(ctx, project.id, {
       type: "settings.updated",
-      message: `${desc4.key} override set to ${String(value)}`,
-      data: { key: desc4.key, scope: "project", value }
+      message: `${desc5.key} override set to ${String(value)}`,
+      data: { key: desc5.key, scope: "project", value }
     });
-    return field(getSettings(ctx, input.projectId, io), desc4.key);
+    return field(getSettings(ctx, input.projectId, io), desc5.key);
   }
-  if (!desc4.configKey) {
-    throw new InvalidInputError(`${desc4.key} is a per-project setting; provide a projectId`);
+  if (!desc5.configKey) {
+    throw new InvalidInputError(`${desc5.key} is a per-project setting; provide a projectId`);
   }
-  writeGlobal(configFile, desc4.configKey, value);
-  ctx.config[desc4.configKey] = value;
+  writeGlobal(configFile, desc5.configKey, value);
+  ctx.config[desc5.configKey] = value;
   emitProject(ctx, GLOBAL_EVENT_KEY, {
     type: "settings.updated",
-    message: `${desc4.key} set to ${String(value)}`,
-    data: { key: desc4.key, scope: "global", value }
+    message: `${desc5.key} set to ${String(value)}`,
+    data: { key: desc5.key, scope: "global", value }
   });
-  return field(getSettings(ctx, input.projectId, io), desc4.key);
+  return field(getSettings(ctx, input.projectId, io), desc5.key);
 }
 function writeGlobal(configFile, configKey, value) {
   const raw = readRawConfig(configFile);
   raw[configKey] = value;
-  mkdirSync7(dirname7(configFile), { recursive: true });
+  mkdirSync8(dirname8(configFile), { recursive: true });
   writeFileSync3(configFile, `${JSON.stringify(raw, null, 2)}
 `);
 }
@@ -6537,7 +8002,7 @@ function updateStepModel(ctx, input, configFile, io) {
   const modelStep = step;
   let value = null;
   if (input.value !== null) {
-    const parsed = z9.string().min(1).safeParse(input.value);
+    const parsed = z10.string().min(1).safeParse(input.value);
     if (!parsed.success) {
       throw new InvalidInputError(`invalid value for ${input.key}: ${parsed.error.issues[0]?.message}`);
     }
@@ -6565,7 +8030,7 @@ function writeStepModel(configFile, step, value) {
   else
     stepModels[step] = value;
   raw.stepModels = stepModels;
-  mkdirSync7(dirname7(configFile), { recursive: true });
+  mkdirSync8(dirname8(configFile), { recursive: true });
   writeFileSync3(configFile, `${JSON.stringify(raw, null, 2)}
 `);
 }
@@ -6582,6 +8047,7 @@ var init_settings = __esm(() => {
   init_schema();
   init_errors();
   init_events();
+  init_findings();
   init_repo();
   DESCRIPTORS = [
     {
@@ -6589,7 +8055,7 @@ var init_settings = __esm(() => {
       configKey: "serverPort",
       envVar: "RUNCASTLE_SERVER_PORT",
       restartRequired: true,
-      valueSchema: z9.number().int().positive(),
+      valueSchema: z10.number().int().positive(),
       parseEnv: (raw) => Number(raw)
     },
     {
@@ -6598,7 +8064,7 @@ var init_settings = __esm(() => {
       envVar: "RUNCASTLE_MODEL",
       projectColumn: "model",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
     {
@@ -6607,7 +8073,7 @@ var init_settings = __esm(() => {
       envVar: "RUNCASTLE_SANDBOX",
       projectColumn: "sandbox",
       restartRequired: false,
-      valueSchema: z9.enum(["docker", "podman", "noSandbox"]),
+      valueSchema: z10.enum(["docker", "podman", "noSandbox"]),
       parseEnv: idEnv
     },
     {
@@ -6615,7 +8081,15 @@ var init_settings = __esm(() => {
       configKey: "sandboxImage",
       envVar: "RUNCASTLE_SANDBOX_IMAGE",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
+      parseEnv: idEnv
+    },
+    {
+      key: "sessionMcp",
+      configKey: "sessionMcp",
+      envVar: "RUNCASTLE_SESSION_MCP",
+      restartRequired: false,
+      valueSchema: z10.enum(["inherit", "runcastleOnly"]),
       parseEnv: idEnv
     },
     {
@@ -6623,7 +8097,7 @@ var init_settings = __esm(() => {
       configKey: "burnConcurrency",
       envVar: "RUNCASTLE_BURN_CONCURRENCY",
       restartRequired: false,
-      valueSchema: z9.number().int().min(1).max(8),
+      valueSchema: z10.number().int().min(1).max(8),
       parseEnv: (raw) => Number(raw)
     },
     {
@@ -6631,7 +8105,7 @@ var init_settings = __esm(() => {
       configKey: "burnMaxIterations",
       envVar: "RUNCASTLE_BURN_MAX_ITERATIONS",
       restartRequired: false,
-      valueSchema: z9.number().int().min(1).max(10),
+      valueSchema: z10.number().int().min(1).max(10),
       parseEnv: (raw) => Number(raw)
     },
     {
@@ -6639,7 +8113,7 @@ var init_settings = __esm(() => {
       configKey: "burnAttempts",
       envVar: "RUNCASTLE_BURN_ATTEMPTS",
       restartRequired: false,
-      valueSchema: z9.number().int().min(1).max(5),
+      valueSchema: z10.number().int().min(1).max(5),
       parseEnv: (raw) => Number(raw)
     },
     {
@@ -6647,7 +8121,7 @@ var init_settings = __esm(() => {
       configKey: "burnConflictAttempts",
       envVar: "RUNCASTLE_BURN_CONFLICT_ATTEMPTS",
       restartRequired: false,
-      valueSchema: z9.number().int().min(0).max(3),
+      valueSchema: z10.number().int().min(0).max(3),
       parseEnv: (raw) => Number(raw)
     },
     {
@@ -6655,31 +8129,42 @@ var init_settings = __esm(() => {
       configKey: "burnCpus",
       envVar: "RUNCASTLE_BURN_CPUS",
       restartRequired: false,
-      valueSchema: z9.number().positive().max(256),
+      valueSchema: z10.number().positive().max(256),
       parseEnv: (raw) => Number(raw)
     },
+    {
+      key: "autoPrepare",
+      configKey: "autoPrepare",
+      envVar: "RUNCASTLE_AUTO_PREPARE",
+      restartRequired: false,
+      valueSchema: z10.boolean(),
+      parseEnv: (raw) => raw !== "0" && raw.toLowerCase() !== "false"
+    },
     {
       key: "setupCommand",
       configKey: "setupCommand",
       envVar: "RUNCASTLE_SETUP_COMMAND",
+      projectColumn: "setupCommand",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
     {
       key: "verifyCommands",
       configKey: "verifyCommands",
       envVar: "RUNCASTLE_VERIFY_COMMANDS",
+      projectColumn: "verifyCommands",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
     {
       key: "knownFailures",
       configKey: "knownFailures",
       envVar: "RUNCASTLE_KNOWN_FAILURES",
+      projectColumn: "knownFailures",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
     {
@@ -6687,14 +8172,42 @@ var init_settings = __esm(() => {
       configKey: "mainBranch",
       envVar: "RUNCASTLE_MAIN_BRANCH",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
       parseEnv: idEnv
     },
     {
       key: "devCommand",
       projectColumn: "devCommand",
       restartRequired: false,
-      valueSchema: z9.string().min(1),
+      valueSchema: z10.string().min(1),
+      parseEnv: idEnv
+    },
+    {
+      key: "dbResetCommand",
+      projectColumn: "dbResetCommand",
+      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
     }
   ];
@@ -6703,14 +8216,14 @@ var init_settings = __esm(() => {
 });
 
 // src/trpc/routers/settings.ts
-import * as z10 from "zod";
+import * as z11 from "zod";
 var settingsRouter;
 var init_settings2 = __esm(() => {
   init_src();
   init_settings();
   init_context();
   settingsRouter = router({
-    get: publicProcedure.input(z10.object({ projectId: z10.string().optional() }).optional()).query(({ ctx, input }) => getSettings(ctx, input?.projectId)),
+    get: publicProcedure.input(z11.object({ projectId: z11.string().optional() }).optional()).query(({ ctx, input }) => getSettings(ctx, input?.projectId)),
     update: publicProcedure.input(SettingsUpdateInput).mutation(({ ctx, input }) => updateSettings(ctx, input))
   });
 });
@@ -6877,13 +8390,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();
     });
@@ -6891,10 +8404,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 });
     });
   });
 }
@@ -6903,9 +8416,9 @@ var init_system_exec = __esm(() => {
 });
 
 // src/services/setup.ts
-import { copyFileSync, existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync7, readdirSync as readdirSync6, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname8, join as join16 } from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
+import { copyFileSync, existsSync as existsSync18, mkdirSync as mkdirSync9, readFileSync as readFileSync8, readdirSync as readdirSync6, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname9, join as join17 } from "path";
+import { fileURLToPath as fileURLToPath7 } from "url";
 async function writeGitIdentity(exec, identity) {
   const name = identity.name.trim();
   const email = identity.email.trim();
@@ -6980,16 +8493,16 @@ async function resolveRuntime(exec, preferred) {
 function resolveSandcastleBin() {
   try {
     const mainUrl = import.meta.resolve("@ai-hero/sandcastle");
-    let dir = dirname8(fileURLToPath6(mainUrl));
+    let dir = dirname9(fileURLToPath7(mainUrl));
     for (let hops = 0;hops < 6; hops++) {
-      const manifestPath = join16(dir, "package.json");
-      if (existsSync17(manifestPath)) {
-        const manifest = JSON.parse(readFileSync7(manifestPath, "utf8"));
+      const manifestPath = join17(dir, "package.json");
+      if (existsSync18(manifestPath)) {
+        const manifest = JSON.parse(readFileSync8(manifestPath, "utf8"));
         if (manifest.name === "@ai-hero/sandcastle" && manifest.bin?.sandcastle) {
-          return join16(dir, manifest.bin.sandcastle);
+          return join17(dir, manifest.bin.sandcastle);
         }
       }
-      const parent = dirname8(dir);
+      const parent = dirname9(dir);
       if (parent === dir)
         break;
       dir = parent;
@@ -7011,21 +8524,21 @@ function terminalSpec(kind, opts) {
   };
 }
 function sandcastleTemplateDir() {
-  return resolveAsset(ASSET_ENV.sandcastleTemplate, fileURLToPath6(new URL("../assets/sandcastle", import.meta.url)));
+  return resolveAsset(ASSET_ENV.sandcastleTemplate, fileURLToPath7(new URL("../assets/sandcastle", import.meta.url)));
 }
 function scaffoldSandcastleConfig(templateDir, targetDir) {
-  const dir = join16(targetDir, ".sandcastle");
-  if (existsSync17(dir))
+  const dir = join17(targetDir, ".sandcastle");
+  if (existsSync18(dir))
     return { scaffolded: false, dir };
-  mkdirSync8(dir, { recursive: true });
+  mkdirSync9(dir, { recursive: true });
   for (const name of readdirSync6(templateDir)) {
-    copyFileSync(join16(templateDir, name), join16(dir, name));
+    copyFileSync(join17(templateDir, name), join17(dir, name));
   }
   return { scaffolded: true, dir };
 }
 function prepareSandboxBuildContext() {
   const target = sandboxBuildDir();
-  mkdirSync8(target, { recursive: true });
+  mkdirSync9(target, { recursive: true });
   scaffoldSandcastleConfig(sandcastleTemplateDir(), target);
   return target;
 }
@@ -7061,9 +8574,9 @@ function createTokenVerifier(exec) {
 function fileAfkTokenIo(exec) {
   const path = envPath();
   return {
-    read: () => existsSync17(path) ? readFileSync7(path, "utf8") : "",
+    read: () => existsSync18(path) ? readFileSync8(path, "utf8") : "",
     write: (content) => {
-      mkdirSync8(dirname8(path), { recursive: true });
+      mkdirSync9(dirname9(path), { recursive: true });
       writeFileSync4(path, content, "utf8");
     },
     verify: createTokenVerifier(exec)
@@ -7078,7 +8591,7 @@ var init_setup = __esm(() => {
 });
 
 // src/trpc/routers/setup.ts
-import * as z11 from "zod";
+import * as z12 from "zod";
 var setupRouter;
 var init_setup2 = __esm(() => {
   init_src();
@@ -7094,9 +8607,9 @@ var init_setup2 = __esm(() => {
       ...ctx.config.sandboxImage ? { imageName: ctx.config.sandboxImage } : {}
     })),
     runtimeGuide: publicProcedure.query(() => runtimeInstallGuide(process.platform)),
-    gitIdentity: publicProcedure.input(z11.object({ name: z11.string(), email: z11.string() })).mutation(({ input }) => writeGitIdentity(createSystemExec(), input)),
-    afkToken: publicProcedure.input(z11.object({ token: z11.string() })).mutation(({ input }) => saveAfkToken(fileAfkTokenIo(createSystemExec()), input.token)),
-    startTerminal: publicProcedure.input(z11.object({ kind: z11.enum(["setup-token", "build-image"]) })).mutation(async ({ ctx, input }) => {
+    gitIdentity: publicProcedure.input(z12.object({ name: z12.string(), email: z12.string() })).mutation(({ input }) => writeGitIdentity(createSystemExec(), input)),
+    afkToken: publicProcedure.input(z12.object({ token: z12.string() })).mutation(({ input }) => saveAfkToken(fileAfkTokenIo(createSystemExec()), input.token)),
+    startTerminal: publicProcedure.input(z12.object({ kind: z12.enum(["setup-token", "build-image"]) })).mutation(async ({ ctx, input }) => {
       const exec = createSystemExec();
       const preferred = ctx.config.sandbox === "podman" ? "podman" : "docker";
       const runtime = await resolveRuntime(exec, preferred);
@@ -7196,16 +8709,16 @@ var init_update_check = __esm(() => {
 });
 
 // src/version.ts
-import { readFileSync as readFileSync8 } from "fs";
-import { dirname as dirname9, join as join17 } from "path";
-import { fileURLToPath as fileURLToPath7 } from "url";
+import { readFileSync as readFileSync9 } from "fs";
+import { dirname as dirname10, join as join18 } from "path";
+import { fileURLToPath as fileURLToPath8 } from "url";
 function runcastleVersion() {
   if (cached2)
     return cached2;
-  const here = dirname9(fileURLToPath7(import.meta.url));
-  for (const pkgPath of [join17(here, "..", "package.json"), join17(here, "package.json")]) {
+  const here = dirname10(fileURLToPath8(import.meta.url));
+  for (const pkgPath of [join18(here, "..", "package.json"), join18(here, "package.json")]) {
     try {
-      const pkg = JSON.parse(readFileSync8(pkgPath, "utf8"));
+      const pkg = JSON.parse(readFileSync9(pkgPath, "utf8"));
       if (typeof pkg.version === "string") {
         cached2 = pkg.version;
         return cached2;
@@ -7231,7 +8744,7 @@ var init_system = __esm(() => {
 });
 
 // src/trpc/routers/ticket.ts
-import * as z12 from "zod";
+import * as z13 from "zod";
 var ticketRouter;
 var init_ticket = __esm(() => {
   init_features();
@@ -7240,8 +8753,8 @@ var init_ticket = __esm(() => {
   init_ticket_burner();
   init_context();
   ticketRouter = router({
-    retry: publicProcedure.input(z12.object({ ticketId: z12.string(), fresh: z12.boolean().optional() })).mutation(({ ctx, input }) => retryTicket(ctx, input.ticketId, { fresh: input.fresh })),
-    stop: publicProcedure.input(z12.object({ ticketId: z12.string() })).mutation(({ ctx, input }) => {
+    retry: publicProcedure.input(z13.object({ ticketId: z13.string(), fresh: z13.boolean().optional() })).mutation(({ ctx, input }) => retryTicket(ctx, input.ticketId, { fresh: input.fresh })),
+    stop: publicProcedure.input(z13.object({ ticketId: z13.string() })).mutation(({ ctx, input }) => {
       if (stopTicketRun(input.ticketId))
         return { stopped: true, swept: false };
       const ticket = getTicket(ctx, input.ticketId);
@@ -7251,7 +8764,7 @@ var init_ticket = __esm(() => {
       }
       return { stopped: false, swept: false };
     }),
-    cancel: publicProcedure.input(z12.object({ ticketId: z12.string(), reason: z12.string().optional() })).mutation(({ ctx, input }) => cancelTicket(ctx, input.ticketId, input.reason))
+    cancel: publicProcedure.input(z13.object({ ticketId: z13.string(), reason: z13.string().optional() })).mutation(({ ctx, input }) => cancelTicket(ctx, input.ticketId, input.reason))
   });
 });
 
@@ -7282,18 +8795,18 @@ var init_router = __esm(() => {
 });
 
 // src/workflows/reconcile-runs.ts
-import { eq as eq11 } from "drizzle-orm";
+import { eq as eq13 } from "drizzle-orm";
 async function reconcileStaleRuns(ctx) {
-  const stale = ctx.db.select().from(runs).where(eq11(runs.status, "running")).all().map(rowToRun);
+  const stale = ctx.db.select().from(runs).where(eq13(runs.status, "running")).all().map(rowToRun);
   const reconciled = [];
-  for (const run3 of stale) {
-    if (isRunActive(run3.id))
+  for (const run4 of stale) {
+    if (isRunActive(run4.id))
       continue;
-    ctx.db.update(runs).set({ status: "failed", endedAt: Date.now(), summary: "orphaned by server restart" }).where(eq11(runs.id, run3.id)).run();
-    const released = releaseForSession(ctx, run3.id);
-    const swept = workflowClaimsFeatureBranch(run3.workflow) ? sweepOrphanedBurning(ctx, run3.featureId, "orphaned by server restart \u2014 retry to resume its commits") : [];
-    if (workflowClaimsFeatureBranch(run3.workflow)) {
-      const feature = tryGetFeature(ctx, run3.featureId);
+    ctx.db.update(runs).set({ status: "failed", endedAt: Date.now(), summary: "orphaned by server restart" }).where(eq13(runs.id, run4.id)).run();
+    const released = releaseForSession(ctx, run4.id);
+    const swept = workflowClaimsFeatureBranch(run4.workflow) ? sweepOrphanedBurning(ctx, run4.featureId, "orphaned by server restart \u2014 retry to resume its commits") : [];
+    if (workflowClaimsFeatureBranch(run4.workflow)) {
+      const feature = tryGetFeature(ctx, run4.featureId);
       const project = feature ? getProjectById(ctx, feature.projectId) : null;
       if (feature && project) {
         try {
@@ -7301,18 +8814,18 @@ async function reconcileStaleRuns(ctx) {
         } catch {}
       }
     }
-    emit(ctx, run3.featureId, {
+    emit(ctx, run4.featureId, {
       type: "run.reconciled",
-      message: `run marked failed at boot \u2014 the server restarted while it was running (${run3.workflow})`,
-      runId: run3.id,
+      message: `run marked failed at boot \u2014 the server restarted while it was running (${run4.workflow})`,
+      runId: run4.id,
       data: {
-        runId: run3.id,
-        workflow: run3.workflow,
+        runId: run4.id,
+        workflow: run4.workflow,
         releasedWaypointIds: released.map((w) => w.id),
         sweptTicketSeqs: swept.map((t2) => t2.seq)
       }
     });
-    reconciled.push(run3);
+    reconciled.push(run4);
   }
   for (const project of allProjects(ctx)) {
     try {
@@ -7343,7 +8856,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") {
@@ -7375,6 +8888,10 @@ async function startServer() {
   if (staleRuns.length > 0) {
     console.log(`reconciled ${staleRuns.length} stale run(s) from a previous server run`);
   }
+  const stalePreps = reconcilePreps(ctx);
+  if (stalePreps > 0) {
+    console.log(`reconciled ${stalePreps} stale preparation run(s) from a previous server run`);
+  }
   const server = Bun.serve({
     port: config2.serverPort,
     fetch(req, srv) {
@@ -7384,7 +8901,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]) {
@@ -7404,6 +8921,7 @@ var init_src2 = __esm(() => {
   init_client();
   init_migrate();
   init_reconcile();
+  init_prep();
   init_server();
   init_registry();
   init_ws();
@@ -7468,7 +8986,7 @@ __export(exports_cli, {
   resolveDoctorEnv: () => resolveDoctorEnv,
   parseMode: () => parseMode
 });
-import { existsSync as existsSync18, readFileSync as readFileSync9 } from "fs";
+import { existsSync as existsSync19, readFileSync as readFileSync10 } from "fs";
 function parseMode(argv) {
   return argv.includes("--gate") || argv.includes("--boot") ? "gate" : "diagnostic";
 }
@@ -7476,8 +8994,8 @@ function envWithToken() {
   const merged = { ...process.env };
   try {
     const path = envPath();
-    if (existsSync18(path)) {
-      const fromFile = parseEnvFile(readFileSync9(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
+    if (existsSync19(path)) {
+      const fromFile = parseEnvFile(readFileSync10(path, "utf8")).CLAUDE_CODE_OAUTH_TOKEN;
       if (fromFile && fromFile.length > 0)
         merged.CLAUDE_CODE_OAUTH_TOKEN = fromFile;
     }
@@ -7519,8 +9037,8 @@ var init_cli = __esm(() => {
 // src/bin/runcastle.ts
 init_asset_paths();
 init_version();
-import { dirname as dirname10, resolve as resolve9 } from "path";
-import { fileURLToPath as fileURLToPath8 } from "url";
+import { dirname as dirname11, resolve as resolve10 } from "path";
+import { fileURLToPath as fileURLToPath9 } from "url";
 function parseCommand(argv) {
   const [first, ...rest] = argv;
   if (first === undefined)
@@ -7544,7 +9062,7 @@ Usage:
   runcastle --help     Show this help
 `;
 async function main(argv) {
-  applyInstalledAssetEnv(resolve9(dirname10(fileURLToPath8(import.meta.url)), ".."));
+  applyInstalledAssetEnv(resolve10(dirname11(fileURLToPath9(import.meta.url)), ".."));
   const { command, args } = parseCommand(argv);
   switch (command) {
     case "version":