plotlink-ows 1.0.33 → 1.2.94

package/app/routes/terminal.ts

@@ -4,9 +4,89 @@ import path from "path";
 import fs from "fs";
 import { randomUUID } from "crypto";
 import { STORIES_DIR, DATA_DIR } from "../lib/paths";
+import { readStoryMeta, writeStoryMeta } from "./stories";
+import type { AgentProvider } from "./stories";
+import { writeStoryInstructions } from "../lib/generate-story-instructions";
+import { buildAgentCommand } from "../lib/agent-command";
+import type { AgentMode, AgentCommand } from "../lib/agent-command";
+import { FRESH_SPAWN_SIGNAL } from "../lib/terminal-protocol";
+
+/**
+ * Provider-aware session record (new shape). Written ONLY for Codex sessions.
+ * Claude sessions keep being persisted as a bare string (legacy shape) so a
+ * rollback to an older app version still resumes fiction/Claude stories.
+ */
+export interface SessionRecord {
+  provider: AgentProvider;
+  sessionId: string | null;
+  lastStartedAt?: number;
+}
+export type StoredValue = string | SessionRecord;
+
+export function isSessionRecord(v: StoredValue | undefined): v is SessionRecord {
+  return typeof v === "object" && v !== null && "provider" in v;
+}
+
+/** Resolve a resume id from either stored shape (string → itself, record → .sessionId). */
+export function resumeIdFrom(v: StoredValue | undefined): string | null {
+  if (typeof v === "string") return v;
+  if (isSessionRecord(v)) return typeof v.sessionId === "string" ? v.sessionId : null;
+  return null;
+}
+
+/**
+ * Resolve the concrete agent CLI invocation (argv) for a Codex spawn, given the
+ * stored session value and whether the user requested a resume.
+ *
+ * Codex decouples "resume requested" from "stored id exists" — unlike Claude:
+ * - Claude needs a CONCRETE session id to resume (`--resume <id>`); with no
+ *   stored id it must start fresh (`--session-id <new>`). So Claude resume only
+ *   happens when both resumeRequested AND a stored id exist.
+ * - Codex can resume the most recent session with no id at all
+ *   (`codex resume --last`). So a resume request alone is enough; a stored id
+ *   (when present) just picks a specific session (`codex resume <id>`).
+ *
+ * This is the single code path shared by spawnPty (codex branch) and the
+ * route/session regression tests, so they exercise identical logic.
+ */
+export function resolveAgentCommandForSession(opts: {
+  provider: AgentProvider;
+  mode: AgentMode;
+  resumeRequested: boolean;
+  stored: StoredValue | undefined;
+  newSessionId: string;
+  storyDir: string;
+}): AgentCommand {
+  const { provider, mode, resumeRequested, stored, newSessionId, storyDir } = opts;
+  const storedResumeId = resumeIdFrom(stored);
+
+  if (provider === "claude") {
+    // Claude requires a concrete id to resume; otherwise fall back to fresh.
+    const doResume = !!(resumeRequested && storedResumeId);
+    return buildAgentCommand({
+      provider,
+      mode,
+      resume: doResume,
+      sessionId: doResume ? storedResumeId : null,
+      newSessionId,
+      storyDir,
+    });
+  }
+
+  // Codex: a resume request alone is enough even with no stored id (resume --last).
+  return buildAgentCommand({
+    provider,
+    mode,
+    resume: resumeRequested,
+    sessionId: storedResumeId,
+    newSessionId,
+    storyDir,
+  });
+}
 
 const MAX_SESSIONS = 5;
 const SESSION_FILE = path.join(DATA_DIR, "terminal-sessions.json");
+const WS_OPEN = 1;
 
 const terminal = new Hono();
 
@@ -23,8 +103,12 @@ function safeName(name: string): string | null {
   return name;
 }
 
-/** Load stored session UUIDs from disk */
-function loadSessionMap(): Record<string, string> {
+/**
+ * Load stored sessions from disk. Values may be legacy bare strings (Claude
+ * UUIDs) OR new provider-aware records. The file is NEVER migrated wholesale —
+ * only the touched key changes shape when actively updated.
+ */
+function loadSessionMap(): Record<string, StoredValue> {
   try {
     if (fs.existsSync(SESSION_FILE)) {
       return JSON.parse(fs.readFileSync(SESSION_FILE, "utf-8"));
@@ -33,8 +117,8 @@ function loadSessionMap(): Record<string, string> {
   return {};
 }
 
-/** Save session UUIDs to disk */
-function saveSessionMap(map: Record<string, string>) {
+/** Save sessions to disk (mixed legacy-string / record values). */
+function saveSessionMap(map: Record<string, StoredValue>) {
   try {
     const dir = path.dirname(SESSION_FILE);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -42,31 +126,228 @@ function saveSessionMap(map: Record<string, string>) {
   } catch { /* ignore */ }
 }
 
-function spawnPty(storyName: string, opts?: { sessionId?: string; resume?: boolean }) {
+/**
+ * Build the Claude CLI command string for a session.
+ * - resume: reuse an existing session ID
+ * - bypass: add --dangerously-skip-permissions (opt-in, less safe)
+ */
+export function buildClaudeCommand(opts: {
+  resume: boolean;
+  sessionId: string;
+  bypass?: boolean;
+}): string {
+  let cmd = "claude";
+  if (opts.resume) {
+    cmd += ` --resume "${opts.sessionId}"`;
+  } else {
+    cmd += ` --session-id "${opts.sessionId}"`;
+  }
+  if (opts.bypass) {
+    cmd += " --dangerously-skip-permissions";
+  }
+  return cmd;
+}
+
+export function isTerminalSocketOpen(ws: Pick<WebSocket, "readyState">): boolean {
+  return ws.readyState === WS_OPEN;
+}
+
+/**
+ * POSIX single-quote escape for embedding an arbitrary value in a shell string.
+ *
+ * We invoke the agent via a login shell (`pty.spawn(shell, ["-l","-c", cmd])`)
+ * so the user's PATH resolves the `claude`/`codex` binary. That means the argv
+ * is assembled into a single shell-parsed string, so every token must be quoted
+ * safely. Single-quoting (with the `'\''` trick for embedded quotes) is the only
+ * shell quoting that disables ALL special characters ($, `, ", \, spaces), so a
+ * value containing `"`, `$`, or a backtick cannot break out of its token.
+ */
+export function shellQuote(s: string): string {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+// In-memory agent mode per active session name (covers _new_ sessions and
+// reconnects before a story directory / .story.json exists).
+const agentModeBySession = new Map<string, "normal" | "bypass">();
+
+// In-memory agent provider per active session name (covers _new_ sessions and
+// reconnects before a story directory / .story.json exists). Mirrors
+// agentModeBySession exactly.
+const agentProviderBySession = new Map<string, "claude" | "codex">();
+
+/**
+ * Resolve effective permissions-bypass for a spawn.
+ *
+ * The client-supplied bypass flag is only trusted for a brand-new (_new_)
+ * story's first spawn. For existing stories, bypass derives strictly from
+ * server-side state (already-spawned session mode, then stored .story.json),
+ * so a direct WS URL cannot force bypass on a story whose metadata says normal.
+ */
+export function resolveBypass(args: {
+  isNewStory: boolean;
+  optBypass?: boolean;
+  sessionMode?: "normal" | "bypass";
+  storedMode?: "normal" | "bypass";
+}): boolean {
+  if (args.isNewStory) {
+    return args.optBypass ?? args.sessionMode === "bypass";
+  }
+  if (args.sessionMode !== undefined) {
+    return args.sessionMode === "bypass";
+  }
+  return args.storedMode === "bypass";
+}
+
+/**
+ * Resolve the effective agent provider for a spawn.
+ *
+ * Mirrors resolveBypass's trust model: the client-supplied provider flag is only
+ * trusted for a brand-new (_new_) story's first spawn. For existing stories the
+ * provider derives strictly from server-side state (already-spawned session
+ * provider, then stored .story.json), so a direct WS URL cannot force a provider
+ * on a story whose metadata says otherwise.
+ */
+export function resolveProvider(args: {
+  isNewStory: boolean;
+  optProvider?: "claude" | "codex";
+  sessionProvider?: "claude" | "codex";
+  storedProvider?: "claude" | "codex";
+}): "claude" | "codex" {
+  if (args.isNewStory) return args.optProvider ?? args.sessionProvider ?? "claude";
+  if (args.sessionProvider !== undefined) return args.sessionProvider;
+  return args.storedProvider ?? "claude";
+}
+
+type StoryMetaShape = ReturnType<typeof readStoryMeta>;
+
+/**
+ * Decide the `.story.json` metadata to persist when a `_new_*` session is
+ * confirmed/renamed into its real story folder (#295).
+ *
+ * The fresh-cartoon repair-banner bug happened because `agentProvider` was only
+ * persisted by a fire-and-forget client POST after the rename — so if that POST
+ * was dropped (or the page reloaded), a cartoon story had `contentType:"cartoon"`
+ * but no recorded provider and falsely looked "legacy". Persisting here makes the
+ * rename the authoritative confirm step.
+ *
+ * Pure/deterministic: merges the new story's intended fields over whatever the
+ * folder already has. Provider falls back to the carried session provider when
+ * the request body omits it (the server already tracks it per session). Returns
+ * null when there is nothing new to record (no provider and no explicit
+ * contentType) so an unrelated rename never rewrites `.story.json`.
+ */
+export function resolveRenamedStoryMeta(args: {
+  existing: StoryMetaShape;
+  bodyContentType?: string;
+  bodyLanguage?: string;
+  bodyAgentMode?: string;
+  bodyProvider?: string;
+  sessionProvider?: AgentProvider;
+}): StoryMetaShape | null {
+  const provider: AgentProvider | undefined =
+    args.bodyProvider === "claude" || args.bodyProvider === "codex" ? args.bodyProvider : args.sessionProvider;
+  const hasExplicitContentType = args.bodyContentType === "cartoon" || args.bodyContentType === "fiction";
+  if (!provider && !hasExplicitContentType) return null;
+
+  const contentType = hasExplicitContentType
+    ? (args.bodyContentType as "cartoon" | "fiction")
+    : args.existing.contentType;
+
+  return {
+    ...args.existing,
+    contentType,
+    ...(typeof args.bodyLanguage === "string" && args.bodyLanguage ? { language: args.bodyLanguage } : {}),
+    ...(args.bodyAgentMode === "bypass" || args.bodyAgentMode === "normal" ? { agentMode: args.bodyAgentMode } : {}),
+    ...(provider ? { agentProvider: provider } : {}),
+  };
+}
+
+/**
+ * Move a persisted session entry from one key to another, PRESERVING its stored
+ * shape. A `_new_*` Codex session is stored as a provider-aware record
+ * (`{provider:"codex", sessionId, lastStartedAt}`); a Claude session as a bare
+ * string. Renaming must keep that shape so Codex resume metadata survives. Only
+ * when there is no stored entry do we fall back to the live PTY session id (a
+ * bare string, matching legacy Claude behavior). Mutates and returns `map`.
+ */
+export function carrySessionAcrossRename(
+  map: Record<string, StoredValue>,
+  oldName: string,
+  newName: string,
+  fallbackSessionId: string,
+): Record<string, StoredValue> {
+  const existing = map[oldName];
+  delete map[oldName];
+  map[newName] = existing ?? fallbackSessionId;
+  return map;
+}
+
+function spawnPty(storyName: string, opts?: { sessionId?: string; resume?: boolean; bypass?: boolean; provider?: "claude" | "codex" }) {
   // New story sessions spawn in the stories root so Claude can create any folder
   const isNewStory = storyName.startsWith("_new_");
   const storyDir = isNewStory ? STORIES_DIR : path.join(STORIES_DIR, storyName);
   if (!fs.existsSync(storyDir)) fs.mkdirSync(storyDir, { recursive: true });
   const shell = process.env.SHELL || "/bin/zsh";
 
-  // Determine session ID
+  // Resolve effective agent mode (see resolveBypass for the trust model).
+  const bypass = resolveBypass({
+    isNewStory,
+    optBypass: opts?.bypass,
+    sessionMode: agentModeBySession.get(storyName),
+    storedMode: isNewStory ? undefined : readStoryMeta(storyDir).agentMode,
+  });
+  agentModeBySession.set(storyName, bypass ? "bypass" : "normal");
+
+  // Resolve effective provider (see resolveProvider for the trust model). For a
+  // brand-new _new_ session the client flag is trusted; existing stories ignore
+  // it and read from session state then stored .story.json (no migration).
+  const provider: AgentProvider = resolveProvider({
+    isNewStory,
+    optProvider: opts?.provider,
+    sessionProvider: agentProviderBySession.get(storyName),
+    storedProvider: isNewStory ? undefined : readStoryMeta(storyDir).agentProvider,
+  });
+  agentProviderBySession.set(storyName, provider);
+
+  // Write provider-aware CLAUDE.md AFTER provider resolution so a Codex cartoon
+  // session gets the create-the-file contract and a Claude/legacy session gets the
+  // manual prompt-and-import handoff (#274). New (_new_) stories have no named
+  // folder yet — their CLAUDE.md is written when the story is created/named.
+  if (!isNewStory) {
+    writeStoryInstructions(storyDir, readStoryMeta(storyDir).contentType, provider);
+  }
+
+  // Determine resume id (accepts both legacy-string and record shapes).
   const sessionMap = loadSessionMap();
-  let sessionId: string;
-
-  // Build Claude CLI command with session flags
-  // Note: no --cwd flag — Claude CLI uses process cwd, set via pty.spawn({ cwd: storyDir })
-  let claudeCmd = "claude";
-  if (opts?.resume && sessionMap[storyName]) {
-    // Resume: reuse stored session
-    sessionId = sessionMap[storyName];
-    claudeCmd += ` --resume "${sessionId}"`;
+  const stored = sessionMap[storyName];
+  const storedResumeId = resumeIdFrom(stored);
+  // Claude needs a concrete stored id to resume; with none it starts fresh.
+  const doResume = !!(opts?.resume && storedResumeId);
+  // Fresh Claude reuses any explicit opts.sessionId (back-compat) else a new UUID.
+  const sessionId = doResume ? (storedResumeId as string) : (opts?.sessionId || randomUUID());
+
+  let agentCmd: string;
+  if (provider === "claude") {
+    // KEEP BYTE-IDENTICAL: same buildClaudeCommand output as before.
+    agentCmd = buildClaudeCommand({ resume: doResume, sessionId, bypass });
   } else {
-    // Fresh: always generate new UUID
-    sessionId = opts?.sessionId || randomUUID();
-    claudeCmd += ` --session-id "${sessionId}"`;
+    // Codex decouples "resume requested" from "stored id exists": a resume
+    // request alone yields `codex resume --last` (no stored id needed), while a
+    // stored id picks a specific session (`codex resume <id>`). Render argv via
+    // the shared resolver, then quote it into an injection-safe shell string.
+    const { command, args } = resolveAgentCommandForSession({
+      provider,
+      mode: bypass ? "bypass" : "normal",
+      resumeRequested: !!opts?.resume,
+      stored,
+      newSessionId: sessionId,
+      storyDir,
+    });
+    agentCmd = [command, ...args].map(shellQuote).join(" ");
   }
 
-  const term = pty.spawn(shell, ["-l", "-c", claudeCmd], {
+  // No --cwd flag for Claude — it uses process cwd, set via pty.spawn({ cwd }).
+  const term = pty.spawn(shell, ["-l", "-c", agentCmd], {
     name: "xterm-256color",
     cols: 120,
     rows: 30,
@@ -74,8 +355,17 @@ function spawnPty(storyName: string, opts?: { sessionId?: string; resume?: boole
     env: process.env as Record<string, string>,
   });
 
-  // Persist session ID
-  sessionMap[storyName] = sessionId;
+  // Persist session info. Claude keeps the legacy bare-string shape (rollback
+  // safe); Codex writes a provider-aware record (its own id resolves later).
+  if (provider === "claude") {
+    sessionMap[storyName] = sessionId;
+  } else {
+    sessionMap[storyName] = {
+      provider,
+      sessionId: doResume ? sessionId : null,
+      lastStartedAt: Date.now(),
+    };
+  }
   saveSessionMap(sessionMap);
 
   const isResume = !!opts?.resume;
@@ -117,9 +407,10 @@ function spawnPty(storyName: string, opts?: { sessionId?: string; resume?: boole
 
 /** POST /api/terminal/spawn — spawn Claude CLI for a story */
 terminal.post("/spawn", async (c) => {
-  const body = await c.req.json<{ storyName?: string; resume?: boolean }>().catch(() => ({}));
+  const body = await c.req.json<{ storyName?: string; resume?: boolean; provider?: "claude" | "codex" }>().catch(() => ({}));
   const storyName = safeName(body.storyName || "default");
   if (!storyName) return c.json({ error: "Invalid story name" }, 400);
+  const optProvider = body.provider === "claude" || body.provider === "codex" ? body.provider : undefined;
 
   const existing = ptySessions.get(storyName);
   if (existing?.term && existing.state === "running") {
@@ -133,7 +424,7 @@ terminal.post("/spawn", async (c) => {
   }
 
   try {
-    const session = spawnPty(storyName, { resume: body.resume });
+    const session = spawnPty(storyName, { resume: body.resume, provider: optProvider });
     return c.json({ ok: true, pid: session.term.pid, storyName, sessionId: session.sessionId });
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : "Failed to spawn PTY";
@@ -147,7 +438,7 @@ terminal.get("/session/:storyName", (c) => {
   if (!storyName) return c.json({ error: "Invalid story name" }, 400);
 
   const sessionMap = loadSessionMap();
-  const sessionId = sessionMap[storyName] || null;
+  const sessionId = resumeIdFrom(sessionMap[storyName]);
   const active = ptySessions.get(storyName);
 
   return c.json({
@@ -200,7 +491,16 @@ terminal.delete("/:storyName/discard", (c) => {
 
 /** POST /api/terminal/rename — rename a session key without killing the process */
 terminal.post("/rename", async (c) => {
-  const body = await c.req.json<{ oldName?: string; newName?: string }>().catch(() => ({}));
+  const body = await c.req.json<{
+    oldName?: string;
+    newName?: string;
+    // Optional metadata for the confirmed story, persisted atomically with the
+    // rename so a fresh story's contentType/provider/mode survive (#295).
+    contentType?: string;
+    language?: string;
+    agentMode?: string;
+    agentProvider?: string;
+  }>().catch(() => ({}));
   const oldName = body.oldName && safeName(body.oldName);
   const newName = body.newName && safeName(body.newName);
   if (!oldName || !newName) return c.json({ error: "Invalid names" }, 400);
@@ -215,12 +515,52 @@ terminal.post("/rename", async (c) => {
   ptySessions.delete(oldName);
   ptySessions.set(newName, session);
 
-  // Update persisted session map: remove old key, store under new key
+  // Carry the in-memory agent mode across the rename so reconnects stay consistent
+  const oldMode = agentModeBySession.get(oldName);
+  if (oldMode) {
+    agentModeBySession.set(newName, oldMode);
+    agentModeBySession.delete(oldName);
+  }
+
+  // Carry the in-memory agent provider across the rename too (mirrors mode).
+  const oldProvider = agentProviderBySession.get(oldName);
+  if (oldProvider) {
+    agentProviderBySession.set(newName, oldProvider);
+    agentProviderBySession.delete(oldName);
+  }
+
+  // Update persisted session map: carry the stored value across the rename so a
+  // provider-aware Codex record (`{provider,sessionId,...}`) or a legacy Claude
+  // string is PRESERVED, not flattened to the live PTY's fallback UUID. Writing
+  // session.sessionId here corrupted Codex metadata (the fresh-spawn fallback
+  // UUID is not a real Codex session id, so later resume built `codex resume
+  // <uuid>` instead of `codex resume --last`).
   const sessionMap = loadSessionMap();
-  delete sessionMap[oldName];
-  sessionMap[newName] = session.sessionId;
+  carrySessionAcrossRename(sessionMap, oldName, newName, session.sessionId);
   saveSessionMap(sessionMap);
 
+  // Persist the confirmed story's metadata atomically with the rename so a fresh
+  // story's agentProvider/contentType survive the _new_* → real-folder transition
+  // even if the client's follow-up metadata POST is dropped or the page reloads
+  // (#295). Provider falls back to the carried session value the server already
+  // tracks, so a cartoon's Codex provider is recorded without trusting the body.
+  const storyDir = path.join(STORIES_DIR, newName);
+  if (fs.existsSync(storyDir) && fs.statSync(storyDir).isDirectory()) {
+    const meta = resolveRenamedStoryMeta({
+      existing: readStoryMeta(storyDir),
+      bodyContentType: body.contentType,
+      bodyLanguage: body.language,
+      bodyAgentMode: body.agentMode,
+      bodyProvider: body.agentProvider,
+      sessionProvider: agentProviderBySession.get(newName),
+    });
+    if (meta) {
+      writeStoryMeta(storyDir, meta);
+      // Keep CLAUDE.md provider-aware in step with the recorded provider.
+      writeStoryInstructions(storyDir, meta.contentType, meta.agentProvider);
+    }
+  }
+
   return c.json({ ok: true, sessionId: session.sessionId });
 });
 
@@ -252,10 +592,15 @@ terminal.get("/status", (c) => {
  * Attach a raw WebSocket to a story's PTY session.
  * Called from server.ts WebSocket upgrade handler.
  */
-export function attachTerminalWs(ws: WebSocket, storyName?: string, resume?: boolean) {
+export function attachTerminalWs(ws: WebSocket, storyName?: string, resume?: boolean, bypass?: boolean, provider?: "claude" | "codex") {
   const name = storyName && safeName(storyName) ? storyName : "default";
   let session = ptySessions.get(name);
 
+  // Whether this connection SPAWNS a fresh process vs. reconnecting to a live
+  // PTY. A fresh (re)spawn reprints its own banner/history, so the client must
+  // drop any restored scrollback to avoid a duplicated startup banner (#453).
+  const spawnedFresh = !session || session.state !== "running";
+
   // Lazy spawn if no PTY exists
   if (!session || session.state !== "running") {
     // Enforce max concurrent sessions
@@ -266,7 +611,7 @@ export function attachTerminalWs(ws: WebSocket, storyName?: string, resume?: boo
     }
 
     try {
-      session = spawnPty(name, { resume });
+      session = spawnPty(name, { resume, bypass, provider });
     } catch (err) {
       console.error("PTY spawn failed:", err);
       ws.close(1011, "pty-spawn-failed");
@@ -280,9 +625,16 @@ export function attachTerminalWs(ws: WebSocket, storyName?: string, resume?: boo
   }
   session.ws = ws;
 
+  // Signal a fresh spawn as the FIRST frame, before any PTY output, so the
+  // client drops its restored scrollback and shows only the fresh reprint (#453).
+  // A live-PTY reconnect sends nothing, so the client keeps its scrollback.
+  if (spawnedFresh && isTerminalSocketOpen(ws)) {
+    ws.send(FRESH_SPAWN_SIGNAL);
+  }
+
   // PTY output → browser
   const dataDisposable = session.term.onData((data: string) => {
-    if (ws.readyState === WebSocket.OPEN) {
+    if (isTerminalSocketOpen(ws)) {
       ws.send(data);
     }
   });

package/app/server.ts

@@ -22,9 +22,11 @@ import { dashboardRoutes } from "./routes/dashboard";
 import { terminalRoutes, attachTerminalWs } from "./routes/terminal";
 import { storiesRoutes } from "./routes/stories";
 import { settingsRoutes } from "./routes/settings";
-import { initDb } from "./db";
+import { agentRoutes } from "./routes/agent";
+import { codexImagesRoutes } from "./routes/codex-images";
+import { db, initDb } from "./db";
 import { generateClaudeMd } from "./lib/generate-claude-md";
-import { execSync } from "child_process";
+import { loadSchemaStatements } from "./lib/apply-schema";
 import fs from "fs";
 
 const __dirname = __dirnamePre;
@@ -48,6 +50,10 @@ app.use("/api/stories/*", requireAuth);
 app.route("/api/stories", storiesRoutes);
 app.use("/api/settings/*", requireAuth);
 app.route("/api/settings", settingsRoutes);
+app.use("/api/agent/*", requireAuth);
+app.route("/api/agent", agentRoutes);
+app.use("/api/codex/*", requireAuth);
+app.route("/api/codex", codexImagesRoutes);
 
 // App version (read once at startup)
 const appVersion = (() => {
@@ -128,15 +134,36 @@ async function start() {
   // Generate/update ~/.plotlink-ows/CLAUDE.md for agent discovery
   generateClaudeMd();
 
-  // Run Prisma db push to ensure schema is up to date
-  const schemaPath = path.join(__dirname, "prisma", "schema.prisma");
-  execSync(`npx prisma db push --schema ${schemaPath} --skip-generate`, {
-    stdio: "inherit",
-    env: { ...process.env, DATABASE_URL },
-  });
-
-  // Initialize database connection
-  await initDb();
+  // Bring the local SQLite schema up to date WITHOUT the native Prisma
+  // schema-engine. `prisma db push` spawns a platform-specific schema-engine
+  // binary that fails to start in some packed prod-only installs (#484, EPIC
+  // #465: an empty "Schema engine error:" on macOS arm64). Instead we apply the
+  // committed DDL (app/prisma/schema.sql, generated from schema.prisma) through
+  // the Prisma client's library query engine — the same engine the app already
+  // uses for every query, so if the app runs at all, schema setup runs too.
+  // SQLite creates the DB file but NOT its parent dir, so ensure
+  // ~/.plotlink-ows/data exists first (a fresh prod-only install has none).
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const schemaSqlPath = path.join(__dirname, "prisma", "schema.sql");
+  try {
+    await initDb(); // connect the client (library query engine; no schema-engine)
+    // Statements are CREATE TABLE/INDEX IF NOT EXISTS, so this is idempotent and
+    // safe to run on every startup against an existing database.
+    for (const statement of loadSchemaStatements(schemaSqlPath)) {
+      await db.$executeRawUnsafe(statement);
+    }
+  } catch (err) {
+    // Surface a useful diagnostic instead of a raw stack (#479/#484).
+    const home = os.homedir();
+    const redact = (s: string) => s.split(home).join("~");
+    console.error("\n  ✗ Database setup failed (applying schema.sql).");
+    console.error(`    schema:   ${redact(schemaSqlPath)}`);
+    console.error(`    database: ${redact(DATABASE_URL)}`);
+    console.error(`    reason:   ${err instanceof Error ? err.message : String(err)}`);
+    console.error("    This usually means a corrupted install (missing the generated Prisma");
+    console.error("    client/query engine or schema.sql). Reinstall with: npx plotlink-ows@latest\n");
+    process.exit(1);
+  }
 
   const port = Number(process.env.APP_PORT) || 7777;
   const server = serve({ fetch: app.fetch, port }, (info) => {
@@ -159,8 +186,16 @@ async function start() {
         if (!session || session.expiresAt < new Date()) { socket.destroy(); return; }
         const story = url.searchParams.get("story") || undefined;
         const resume = url.searchParams.get("resume") === "true";
+        const bypass = url.searchParams.get("bypass") === "true";
+        const provider = url.searchParams.get("provider");
         wss.handleUpgrade(req, socket, head, (ws) => {
-          attachTerminalWs(ws as unknown as WebSocket, story, resume);
+          attachTerminalWs(
+            ws as unknown as WebSocket,
+            story,
+            resume,
+            bypass,
+            provider === "claude" || provider === "codex" ? provider : undefined,
+          );
         });
       }).catch(() => socket.destroy());
     }

package/app/vite.config.ts

@@ -1,10 +1,16 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
+import path from "path";
 
 export default defineConfig({
   root: "app/web",
   plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      "@app-lib": path.resolve(__dirname, "lib"),
+    },
+  },
   server: {
     port: 5173,
     proxy: {