plotlink-ows 1.0.33 → 1.2.95

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/routes/wallet.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import fs from "fs";
 import { ENV_FILE } from "../lib/paths";
+import { nextPlotlinkWalletName, resolveActiveWallet, selectActiveWallet, toPublicActiveWallet } from "../lib/active-wallet";
 
 const envPath = ENV_FILE;
 
@@ -21,18 +22,8 @@ function readEnvPassphrase(): string | null {
 /** GET /api/wallet — get wallet info */
 wallet.get("/", async (c) => {
   try {
-    const { getAgentWallet, getBaseAddress } = await import("../../lib/ows/wallet");
-
-    // Try to find existing wallet
-    const { listAgentWallets } = await import("../../lib/ows/wallet");
-    const wallets = listAgentWallets();
-    const plotlinkWallet = wallets.find((w) => w.name.startsWith("plotlink-writer"));
-
-    if (!plotlinkWallet) {
-      return c.json({ exists: false });
-    }
-
-    const address = getBaseAddress(plotlinkWallet);
+    const resolved = await resolveActiveWallet();
+    const activeWallet = resolved.activeWallet;
 
     // Fetch balances on Base via RPC
     let ethBalance = "0";
@@ -40,8 +31,8 @@ wallet.get("/", async (c) => {
     let plotBalance = "0";
     const rpcUrl = process.env.NEXT_PUBLIC_RPC_URL || "https://mainnet.base.org";
 
-    if (address) {
-      const addrPadded = "000000000000000000000000" + address.slice(2).toLowerCase();
+    if (activeWallet?.address) {
+      const addrPadded = "000000000000000000000000" + activeWallet.address.slice(2).toLowerCase();
       const balanceOfSig = "0x70a08231" + addrPadded;
 
       try {
@@ -49,7 +40,7 @@ wallet.get("/", async (c) => {
         const ethRes = await fetch(rpcUrl, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getBalance", params: [address, "latest"] }),
+          body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getBalance", params: [activeWallet.address, "latest"] }),
         });
         const ethData = await ethRes.json() as { result?: string };
         if (ethData.result && ethData.result !== "0x" && ethData.result !== "0x0") {
@@ -82,15 +73,27 @@ wallet.get("/", async (c) => {
       } catch { /* balance fetch best-effort */ }
     }
 
+    if (!activeWallet) {
+      return c.json({
+        exists: resolved.wallets.length > 0,
+        selectionRequired: resolved.selectionRequired,
+        error: resolved.error,
+        wallets: resolved.wallets,
+      });
+    }
+
     return c.json({
       exists: true,
-      walletId: plotlinkWallet.id,
-      name: plotlinkWallet.name,
-      address,
+      walletId: activeWallet.walletId,
+      name: activeWallet.name,
+      address: activeWallet.address,
+      activeWallet: toPublicActiveWallet(activeWallet),
+      selectionRequired: false,
+      wallets: resolved.wallets,
       ethBalance,
       usdcBalance,
       plotBalance,
-      accounts: plotlinkWallet.accounts,
+      accounts: activeWallet.wallet.accounts,
     });
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : "Failed to get wallet";
@@ -98,6 +101,30 @@ wallet.get("/", async (c) => {
   }
 });
 
+/** POST /api/wallet/active — select active OWS wallet */
+wallet.post("/active", async (c) => {
+  const body = await c.req.json<{ walletId?: string; name?: string; address?: string }>();
+  if (!body.walletId && !body.name && !body.address) {
+    return c.json({ error: "walletId, name, or address required" }, 400);
+  }
+
+  const resolved = await selectActiveWallet(body);
+  if (!resolved.activeWallet) {
+    return c.json({
+      error: resolved.error || "Could not select wallet",
+      selectionRequired: resolved.selectionRequired,
+      wallets: resolved.wallets,
+    }, 400);
+  }
+
+  return c.json({
+    ok: true,
+    activeWallet: toPublicActiveWallet(resolved.activeWallet),
+    wallets: resolved.wallets,
+    selectionRequired: false,
+  });
+});
+
 /** POST /api/wallet/create — create OWS wallet */
 wallet.post("/create", async (c) => {
   try {
@@ -106,20 +133,21 @@ wallet.post("/create", async (c) => {
       return c.json({ error: "Passphrase not configured" }, 400);
     }
 
-    const { createAgentWallet, getBaseAddress, listAgentWallets } = await import("../../lib/ows/wallet");
+    const { createAgentWallet, listAgentWallets } = await import("../../lib/ows/wallet");
 
-    // Check if wallet already exists
     const wallets = listAgentWallets();
-    const existing = wallets.find((w) => w.name.startsWith("plotlink-writer"));
-    if (existing) {
-      const address = getBaseAddress(existing);
-      return c.json({ walletId: existing.id, address, alreadyExisted: true });
-    }
-
-    const wallet = createAgentWallet("plotlink-writer", passphrase);
-    const address = getBaseAddress(wallet);
+    const name = nextPlotlinkWalletName(wallets);
+    const createdWallet = createAgentWallet(name, passphrase);
+    const resolved = await selectActiveWallet({ walletId: createdWallet.id, name: createdWallet.name });
 
-    return c.json({ walletId: wallet.id, address, alreadyExisted: false });
+    return c.json({
+      walletId: resolved.activeWallet?.walletId ?? createdWallet.id,
+      name: createdWallet.name,
+      address: resolved.activeWallet?.address,
+      activeWallet: resolved.activeWallet ? toPublicActiveWallet(resolved.activeWallet) : null,
+      wallets: resolved.wallets,
+      alreadyExisted: false,
+    });
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : "Wallet creation failed";
     return c.json({ error: message }, 500);