elanous 0.2.10 → 0.2.12

package/src/nexus/api/personas.ts

@@ -1,27 +1,13 @@
-// NEXUS · personas REST handlers (§6.4 · 2026-05-09).
-//
-// Endpoints
-//   GET  /v1/personas              — list all loaded personas
-//   GET  /v1/personas/:personaId   — single persona profile
-//
-// Architecture: read-only thin wrapper over the global PersonaRegistry
-// (`src/persona/global-registry.ts`). Disk yaml is the source of truth;
-// editing requires text editor + `elanous persona reload` (or fs.watch
-// auto-reload). PWA Showroom consumes this for the per-panel persona
-// picker (§6.4 Q2 = REST read-only).
-//
-// PLAN: 내부 문서 `PLAN-cv-3-showroom-mvp-2026-05-07` §6.4
-// Cross-ref: src/persona/global-registry.ts (singleton accessor)
-//            src/persona/types.ts (PersonaProfile shape)
-
-import { homedir } from 'node:os';
-import { join } from 'node:path';
+// NEXUS · personas REST handlers. Presets clone into the state persona store;
+// writes reload the global registry so subsequent reads see the saved profile.
 
 import {
   awaitGlobalPersonaLoad,
   getGlobalPersonaRegistry,
   reloadGlobalPersonaRegistry,
+  resolveStatePersonaDir,
 } from '../../persona/global-registry.js';
+import { clonePreset, editPersona, loadPresets } from '../../persona/presets.js';
 import type { PersonaRegistryEvent } from '../../persona/registry.js';
 import type { PersonaProfile } from '../../persona/types.js';
 import {
@@ -193,22 +179,41 @@ export function handlePersonasEvents(
   });
 }
 
-/** Resolve personas dir same way `global-registry.ts` does, so the PATCH
- *  endpoint targets the file the registry will reload. */
-function resolvePersonasDir(): string {
-  const env = process.env.ELANOUS_PERSONAS_DIR;
-  if (env && env.length > 0) return env;
-  return join(homedir(), '.elanous', 'personas');
+/** GET /v1/persona-presets — shipped preset catalog in index order. */
+export function handlePersonaPresets(req: Request, opts: PersonaRouteOpts = {}): Response {
+  if (opts.checkAuth && !opts.checkAuth(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  return jsonResponse({ presets: loadPresets() }, 200);
 }
 
-/** PATCH /v1/personas/:personaId — update description.
- *
- *  Body: `{ description: "<string, ≤ 280 chars>" }` — empty string clears.
- *  Other fields ignored (yaml surgical edit pattern).
- *
- *  Returns 200 with the updated `PersonaWire` after reload, 400 / 404 /
- *  500 with structured `{ error, reason? }`.
- */
+/** POST /v1/personas — clone a shipped preset into the user's persona store. */
+export async function handlePersonaCreate(req: Request, opts: PersonaRouteOpts = {}): Promise<Response> {
+  if (opts.checkAuth && !opts.checkAuth(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'invalid-json' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'invalid-body' }, 400);
+  const { preset, name } = body as Record<string, unknown>;
+  if (typeof preset !== 'string' || !preset.trim() || typeof name !== 'string' || !name.trim()) {
+    return jsonResponse({ error: 'preset-and-name-required' }, 400);
+  }
+  await awaitGlobalPersonaLoad();
+  if (!loadPresets().some((p) => p.personaId === preset)) return notFound(`preset ${preset} not found`);
+  try {
+    const created = clonePreset(preset, name.trim(), { dir: resolveStatePersonaDir() });
+    await reloadGlobalPersonaRegistry();
+    const persona = getGlobalPersonaRegistry().get(created.personaId);
+    if (!persona) return notFound(`persona ${created.personaId} not found after reload`);
+    return jsonResponse({ persona: toWire(persona) }, 201);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('persona name already exists:')) {
+      return jsonResponse({ error: 'persona-name-conflict' }, 409);
+    }
+    return jsonResponse({ error: 'create-failed' }, 500);
+  }
+}
+
+/** PATCH /v1/personas/:personaId — description-only edits retain the
+ *  existing surgical YAML behavior; multi-field edits use the persona store. */
 export async function handlePersonaPatch(
   req: Request,
   personaId: string,
@@ -217,17 +222,23 @@ export async function handlePersonaPatch(
   if (opts.checkAuth && !opts.checkAuth(req)) {
     return jsonResponse({ error: 'unauthorized' }, 401);
   }
-  let body: { description?: unknown };
-  try {
-    body = (await req.json()) as { description?: unknown };
-  } catch {
-    return jsonResponse({ error: 'invalid-json' }, 400);
+  let parsed: unknown;
+  try { parsed = await req.json(); }
+  catch { return jsonResponse({ error: 'invalid-json' }, 400); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return jsonResponse({ error: 'invalid-body' }, 400);
   }
-  if (typeof body.description !== 'string') {
-    return jsonResponse({ error: 'description-required' }, 400);
+  const body = parsed as Record<string, unknown>;
+  const fields = Object.keys(body);
+  if (!fields.length) return jsonResponse({ error: 'description-required' }, 400);
+  if (fields.some((field) => !['displayName', 'description', 'systemPrompt'].includes(field))) {
+    return jsonResponse({ error: 'invalid-persona-field' }, 400);
   }
-  if (body.description.length > MAX_PERSONA_DESCRIPTION_LENGTH * 4) {
-    // Guard against pathological inputs before the helper trims.
+  if (fields.some((field) => typeof body[field] !== 'string')
+    || (body.displayName !== undefined && !(body.displayName as string).trim())) {
+    return jsonResponse({ error: 'invalid-persona-field' }, 400);
+  }
+  if (typeof body.description === 'string' && body.description.length > MAX_PERSONA_DESCRIPTION_LENGTH * 4) {
     return jsonResponse({ error: 'description-too-long' }, 400);
   }
 
@@ -237,14 +248,37 @@ export async function handlePersonaPatch(
     return notFound(`persona ${personaId} not found`);
   }
 
-  const dir = resolvePersonasDir();
-  const result = updatePersonaDescription(dir, personaId, body.description);
-  if (!result.ok) {
-    const status = result.reason === 'file-not-found' ? 404 : 400;
-    return jsonResponse({ error: 'patch-failed', reason: result.reason }, status);
+  const dir = resolveStatePersonaDir();
+  if (fields.length === 1 && typeof body.description === 'string') {
+    const result = updatePersonaDescription(dir, personaId, body.description);
+    if (!result.ok) {
+      const status = result.reason === 'file-not-found' ? 404 : 400;
+      return jsonResponse({ error: 'patch-failed', reason: result.reason }, status);
+    }
+  } else {
+    const edits: Record<string, unknown> = {};
+    for (const field of fields) edits[field] = body[field];
+    if (typeof edits.description === 'string') {
+      const description = edits.description.trim();
+      edits.description = description;
+      if (description.length > MAX_PERSONA_DESCRIPTION_LENGTH) {
+        return jsonResponse({ error: 'description-too-long' }, 400);
+      }
+    }
+    try {
+      editPersona(personaId, edits, { dir });
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('persona not found:')) {
+        return notFound(`persona ${personaId} not found in state store`);
+      }
+      if (error instanceof Error && error.message.startsWith('persona name already exists:')) {
+        return jsonResponse({ error: 'persona-name-conflict' }, 409);
+      }
+      return jsonResponse({ error: 'patch-failed', reason: error instanceof Error ? error.message : 'invalid-persona' }, 400);
+    }
   }
 
-  // Reload so the in-memory registry reflects the new description on the
+  // Reload so the in-memory registry reflects the saved fields on the
   // next GET. fs.watch would auto-reload but is async + race-y vs the
   // immediate echo below.
   await reloadGlobalPersonaRegistry();
@@ -255,7 +289,7 @@ export async function handlePersonaPatch(
   return jsonResponse({ persona: toWire(reloaded) }, 200);
 }
 
-/** Combined dispatcher — `/v1/personas[/:id]` + `/v1/personas/events`.
+/** Combined dispatcher — `/v1/persona-presets` + `/v1/personas[/:id]` + `/v1/personas/events`.
  *  Returns null when the pathname doesn't match so the caller chains. */
 export async function dispatchPersonaRoute(
   req: Request,
@@ -263,11 +297,14 @@ export async function dispatchPersonaRoute(
   opts: PersonaRouteOpts = {},
 ): Promise<Response | null> {
   const method = req.method.toUpperCase();
+  if (pathname === '/v1/persona-presets') {
+    if (method !== 'GET') return jsonResponse({ error: 'method not allowed' }, 405);
+    return handlePersonaPresets(req, opts);
+  }
   if (pathname === '/v1/personas') {
-    if (method !== 'GET') {
-      return jsonResponse({ error: 'method not allowed' }, 405);
-    }
-    return handlePersonasList(req, opts);
+    if (method === 'GET') return handlePersonasList(req, opts);
+    if (method === 'POST') return handlePersonaCreate(req, opts);
+    return jsonResponse({ error: 'method not allowed' }, 405);
   }
   // SSE — must come BEFORE the single-persona regex so that the
   // literal "events" segment isn't misread as a personaId.
@@ -279,8 +316,13 @@ export async function dispatchPersonaRoute(
   }
   const match = pathname.match(/^\/v1\/personas\/([^/]+)$/);
   if (!match) return null;
-  const personaId = decodeURIComponent(match[1]!);
+  let personaId: string;
+  try { personaId = decodeURIComponent(match[1]!); }
+  catch { return jsonResponse({ error: 'invalid-persona-id' }, 400); }
   if (method === 'PATCH') {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(personaId)) {
+      return jsonResponse({ error: 'invalid-persona-id' }, 400);
+    }
     return handlePersonaPatch(req, personaId, opts);
   }
   if (method !== 'GET') {

package/src/nexus/api/seat-requests.ts

@@ -6,12 +6,14 @@ import { resolveAttachmentPath } from '../../boot/attachment-store.js';
 import { runGh } from '../../decisions/decision-cards.js';
 import { openMsgStore, canonicalSeatId } from '../../msg/msg-store.js';
 import { dispatchCeoTask, type CeoCommandDeps } from '../../seat-dispatch/ceo-commands.js';
+import { acknowledgeSeatAnswers, askSeat, deliverSeatAnswers, parseSeatAsk, type SeatAskDeps } from '../../seat-dispatch/seat-ask.js';
 import { getUserConfig } from '../../user-config.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
 import { submitIntakeWork } from '../../intake-plane/submit-intake-work.js';
 import { parseSeatAddress, resolveSeat } from '../../seat-address/seat-address.js';
 import trackData from '../../../scripts/coord-tracks.json';
 import { jsonResponse } from './json-response.js';
+import { publishInsideEvent } from './inside-events.js';
 
 export const SEAT_REQUESTS_PATH = '/v1/seat-requests';
 
@@ -50,6 +52,7 @@ export interface SeatRequestsDeps {
   resolveAttachment?: typeof resolveAttachmentPath;
   dispatch?: typeof dispatchCeoTask;
   ceoDeps?: () => CeoCommandDeps;
+  askDeps?: SeatAskDeps;
 }
 
 const seats = trackData.tracks.filter((entry): entry is typeof entry & { title: string } => 'title' in entry)
@@ -189,6 +192,18 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   const path = file((deps.root ?? effectiveInstanceRoot)());
   if (req.method === 'GET') {
     const params = new URL(req.url).searchParams;
+    if (params.get('answers') === '1') {
+      const clientId = req.headers.get('x-seat-ask-client');
+      if (!clientId || !/^[a-f0-9-]{36}$/i.test(clientId)) return jsonResponse({ error: 'bad_request' }, 400);
+      const base = deps.askDeps;
+      const messages: Array<{ id: string; text: string; status: 'answered' | 'expired' }> = [];
+      await deliverSeatAnswers({ ...base, channel: 'pwa', clientId, send: async (origin, text) => {
+        if (origin.channel !== 'pwa' || origin.clientId !== clientId) return;
+        const match = /\(([^)]+)\)/.exec(text);
+        if (match) messages.push({ id: match[1]!, text, status: text.startsWith('CTO 답변') ? 'answered' : 'expired' });
+      } });
+      return jsonResponse({ items: messages });
+    }
     const requestedSeat = params.get('seat');
     const seat = requestedSeat ? requestSeat(requestedSeat) : undefined;
     if (requestedSeat && !seat) return unknownSeat();
@@ -204,6 +219,19 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   }
   if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
 
+  if (new URL(req.url).searchParams.get('answers') === 'ack') {
+    const clientId = req.headers.get('x-seat-ask-client');
+    if (!clientId || !/^[a-f0-9-]{36}$/i.test(clientId)) return jsonResponse({ error: 'bad_request' }, 400);
+    let body: unknown;
+    try { body = await req.json(); } catch { return jsonResponse({ error: 'bad_request' }, 400); }
+    const ids = (body as { ids?: unknown } | null)?.ids;
+    if (!Array.isArray(ids) || ids.length > 100 || ids.some((id) => typeof id !== 'string' || !/^[a-f0-9-]{36}$/i.test(id))) {
+      return jsonResponse({ error: 'bad_request' }, 400);
+    }
+    acknowledgeSeatAnswers(clientId, ids as string[], deps.askDeps?.open);
+    return jsonResponse({ ok: true });
+  }
+
   let body: unknown;
   try { body = await req.json(); }
   catch { return jsonResponse({ error: 'bad_request' }, 400); }
@@ -219,10 +247,22 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
   const prefix = parsed ? `@${parsed.seats.join(',')}` : '';
   const firstAddress = parsed && input.text.startsWith(prefix)
     && (input.text.length === prefix.length || /[ \t\r\n]/.test(input.text[prefix.length]!)) ? parsed : null;
-  const address = input.seat ?? (firstAddress?.seats.length === 1 ? firstAddress.seats[0] : undefined);
+  const address = input.seat ?? (firstAddress?.seats.length === 1 ? firstAddress.seats[0] : undefined)
+    ?? (parseSeatAsk(input.text) ? 'TC' : undefined);
   const seat = address ? requestSeat(address) : undefined;
   if (!seat) return unknownSeat();
-  const text = input.seat === undefined ? firstAddress!.body.trim() : input.text.trim();
+  const text = input.seat === undefined ? (firstAddress?.body ?? input.text).trim() : input.text.trim();
+  if (canonicalSeatIdSafe(seat.id) === 'TC' && parseSeatAsk(text)) {
+    if (input.attachments !== undefined) return jsonResponse({ error: 'attachments-unsupported' }, 400);
+    const clientId = req.headers.get('x-seat-ask-client');
+    if (!clientId || !/^[a-f0-9-]{36}$/i.test(clientId)) return jsonResponse({ error: 'bad_request' }, 400);
+    let ask: string;
+    try {
+      ask = await askSeat(text, { channel: 'pwa', clientId }, (deps.ceoDeps ?? defaultCeoDeps)(),
+        deps.askDeps ?? { channel: 'pwa', send: async () => { throw new Error('PWA seat ask requires polling'); } });
+    } catch { return unavailable(); }
+    return jsonResponse({ reply: ask }, 202);
+  }
   if (!text) {
     debug.log('seat-address.pwa', 'rejected', { reason: 'empty-text', seat: seat.id });
     return jsonResponse({ error: 'bad_request' }, 400);
@@ -304,6 +344,7 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
       };
       try { persistOutcome(path, item, deps.append ?? append); }
       catch { return unavailable(); }
+      publishInsideEvent({ kind: 'seat', seat: item.seat, receiptId: item.receiptId, status: item.status, ts: item.queuedAt });
       return receipt(item);
     }
     let result: Awaited<ReturnType<typeof submitIntakeWork>>;
@@ -325,6 +366,7 @@ export async function handleSeatRequests(req: Request, deps: SeatRequestsDeps =
     try { persistOutcome(path, item, deps.append ?? append); }
     catch { return unavailable(); }
     debug.log('seat-address.pwa', 'enqueued', { seat: seat.id, receiptId: item.receiptId });
+    publishInsideEvent({ kind: 'seat', seat: item.seat, receiptId: item.receiptId, status: item.status, ts: item.queuedAt });
     return receipt(item);
   })();
   inFlight.set(lock, { payload, task });

package/src/nexus/api/sessions-store.ts

@@ -18,11 +18,9 @@ import {
   isHarnessSessionOrigin,
   type SessionMeta,
 } from '../../session/index.js';
-import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
 import { getProject } from '../../project/project-store.js';
-import { sessionRoot } from '../../session/index.js';
+import { sessionRoot, updateSessionMeta } from '../../session/index.js';
+import { debug } from '../../debug/log.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './http-server.js';
 
@@ -181,43 +179,24 @@ export async function handleSessionsStorePatch(req: Request, id: string, opts: M
     return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
   }
   const projectId = (body as { projectId: unknown }).projectId;
-  if (projectId !== null && (typeof projectId !== 'string' || !getProject(projectId))) {
+  if (projectId !== null && typeof projectId !== 'string') {
     return jsonResponse({ ok: false, error: 'invalid_project_id' }, 400);
   }
-
-  const root = sessionRoot();
-  const lock = join(root, '.index.lock');
-  const deadline = Date.now() + 10_000;
-  for (;;) {
-    try { mkdirSync(lock); break; }
-    catch {
-      if (!existsSync(lock)) continue;
-      try {
-        if (Date.now() - statSync(lock).mtimeMs > 30_000) { rmdirSync(lock); continue; }
-      } catch { continue; }
-      if (Date.now() >= deadline) throw new Error(`timed out acquiring lock ${lock}`);
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-    }
-  }
-  try {
-    const path = join(root, 'index.json');
-    const entries = JSON.parse(readFileSync(path, 'utf8')) as SessionMeta[];
-    const pos = entries.findIndex((meta) => meta.id === id);
-    if (pos < 0) return jsonResponse({ ok: false, error: 'not_found' }, 404);
-    const meta = { ...entries[pos] };
-    if (projectId === null) delete meta.projectId;
-    else meta.projectId = projectId;
-    entries[pos] = meta;
-    const temp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
-    writeFileSync(temp, JSON.stringify(entries, null, 2) + '\n', 'utf8');
-    renameSync(temp, path);
-    return jsonResponse({ ok: true, meta }, 200);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return jsonResponse({ ok: false, error: 'not_found' }, 404);
-    throw error;
-  } finally {
-    rmdirSync(lock);
+  // 모양은 맞는데 없는 프로젝트 = 찾을 수 없음(404) — 요청 형식 오류(400)와 가른다(IA1b).
+  if (projectId !== null && !getProject(projectId)) {
+    return jsonResponse({ ok: false, error: 'project-not-found' }, 404);
   }
+
+  let previous: string | null = null;
+  // 잠금 안에서 최신 목록 위에 고친다 — 동시 appendMessage 가 이 projectId 를 덮지 않는다.
+  const meta = updateSessionMeta(id, (m) => {
+    previous = m.projectId ?? null;
+    if (projectId === null) delete m.projectId;
+    else m.projectId = projectId;
+  }, sessionRoot());
+  if (!meta) return jsonResponse({ ok: false, error: 'not_found' }, 404);
+  debug.log('project', 'assign', { sessionId: id, projectId, previous });
+  return jsonResponse({ ok: true, meta }, 200);
 }
 
 /** DELETE /v1/sessions/store/:id — on-disk 세션 삭제(index.json + <id>.jsonl 제거).

package/src/nexus/api/sub-seat-charters.ts

@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+
+export interface SubSeatCharter { id: string; seat: string; sub: string; title: string }
+
+export function listSubSeatCharters(root = join(import.meta.dir, '..', '..', '..', 'docs', 'roles'), onUnreadable?: () => void): SubSeatCharter[] {
+  try {
+    readdirSync(root);
+    const charters: SubSeatCharter[] = [];
+    for (const seat of ['OP', 'MK', 'TC', 'UX']) {
+      let entries;
+      try { entries = readdirSync(join(root, seat), { withFileTypes: true }); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      for (const entry of entries) {
+        if (!entry.isFile() || !/^[a-z][a-z0-9-]{0,31}\.md$/.test(entry.name)) continue;
+        const sub = entry.name.slice(0, -3);
+        const id = `${seat}/${sub}`;
+        const content = readFileSync(join(root, seat, entry.name), 'utf8');
+        const heading = content.split(/\r?\n/).find((line) => line.startsWith('# '));
+        const title = heading?.slice(2).startsWith(`${id} — `) ? heading.slice(2 + id.length + 3).trim() || id : id;
+        charters.push({ id, seat, sub, title });
+      }
+    }
+    return charters.sort((a, b) => a.id.localeCompare(b.id));
+  } catch (error) {
+    debug.log('ops.seats', 'charters-unreadable', { root, error: error instanceof Error ? error.message : String(error) });
+    onUnreadable?.();
+    return [];
+  }
+}

package/src/nexus/api/tabs-mutations.ts

@@ -78,6 +78,8 @@ interface CreateTabBody {
   kind?: string;
   id?: string;
   label?: string;
+  /** Conversation owning a newly created webterm. */
+  sessionId?: string;
   /** Kind-specific factory opts (passed through to the factory). */
   kindOpts?: Record<string, unknown>;
   /** When true (default), supervisor.startTab is called immediately
@@ -95,7 +97,7 @@ function buildTabSpec(body: CreateTabBody, id: string): { spec: TabSpec; reason?
     case 'chat':
       return { spec: createChatTabSpec(opts as Parameters<typeof createChatTabSpec>[0]) };
     case 'webterm':
-      return { spec: createWebtermTabSpec(opts as Parameters<typeof createWebtermTabSpec>[0]) };
+      return { spec: createWebtermTabSpec({ ...opts, sessionId: body.sessionId ?? opts.sessionId } as Parameters<typeof createWebtermTabSpec>[0]) };
     case 'daemon':
       return { spec: createDaemonTabSpec(opts as Parameters<typeof createDaemonTabSpec>[0]) };
     case 'pwa-host':

package/src/nexus/api/task-cards-api.ts

@@ -1,6 +1,25 @@
 import { CardStore } from '../../task-cards/card-store.js';
+import { createWishCard } from '../../intake-plane/wish-card.js';
 import { jsonResponse } from './json-response.js';
 
+export async function handleTaskCardsWishPost(req: Request, root?: string): Promise<Response> {
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return jsonResponse({ error: 'bad_request' }, 400);
+  const { text, ref } = body as Record<string, unknown>;
+  if (typeof text !== 'string' || !text.trim() || typeof ref !== 'string' || !ref.trim()) {
+    return jsonResponse({ error: 'bad_request' }, 400);
+  }
+  const store = new CardStore(root);
+  try {
+    const card = createWishCard({ text, source: 'pwa', ref }, store);
+    return jsonResponse(card, card.created ? 201 : 200);
+  } finally {
+    store.close();
+  }
+}
+
 /** Read-only card API; route registration and authorization belong to the HTTP server. */
 export function handleTaskCardsGet(pathname: string, root?: string): Response {
   if (pathname !== '/v1/task-cards' && !/^\/v1\/task-cards\/[^/]+$/.test(pathname)) {

package/src/nexus/api/trace.ts

@@ -9,6 +9,7 @@ import { checkAuth, type MetaApiOpts } from './meta-api.js';
 import { jsonResponse } from './json-response.js';
 import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
 import { scanStoresForRun } from './trace-run-scan.js';
+import { listSessions } from '../../session/index.js';
 
 export type TraceLevel = 'L0' | 'L1' | 'L2' | 'L3';
 export interface TraceEvent {
@@ -17,6 +18,7 @@ export interface TraceEvent {
   universe: string;
   machine?: string;
   runId?: string;
+  projectId?: string;
   parentRunId?: string;
   phase?: string;
   shard?: string;
@@ -83,6 +85,7 @@ function eventFor(row: LogStoreRow): TraceEvent {
     id: evidenceRef(universe, row.id), ts: row.ts, universe,
     ...(machine ? { machine } : {}),
     ...(runId ? { runId } : {}),
+    ...(text(data.projectId) ? { projectId: text(data.projectId) } : {}),
     ...(text(data.parentRunId) ? { parentRunId: text(data.parentRunId) } : {}),
     ...(text(data.phase) ? { phase: text(data.phase) } : {}),
     ...(text(data.shard) ? { shard: text(data.shard) } : {}),
@@ -259,11 +262,15 @@ function options(url: URL): { level: TraceLevel; limit: number; from?: number; t
   if (from === null || to === null || (from !== undefined && to !== undefined && from > to)) return { level, limit: n, error: 'invalid time range' };
   return { level, limit: Math.min(n, TRACE_LIMIT), ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}) };
 }
-function matches(row: LogStoreRow, url: URL): boolean {
+function matches(row: LogStoreRow, url: URL, projectSessions?: ReadonlySet<string>): boolean {
   const data = dataFor(row);
   const runId = url.searchParams.get('runId');
   const universe = url.searchParams.get('universe');
   const kind = url.searchParams.get('kind');
+  const projectId = url.searchParams.get('projectId');
+  if (projectId !== null && (Object.hasOwn(data, 'projectId')
+    ? data.projectId !== projectId
+    : !projectSessions?.has(row.session_id ?? '') && !projectSessions?.has(text(data.sessionId) ?? ''))) return false;
   const q = url.searchParams.get('q')?.toLowerCase();
   if (runId && data.runId !== runId && data.run_id !== runId) return false;
   if (universe && row.instance !== universe) return false;
@@ -295,6 +302,8 @@ function findRunUniverse(runId: string, selected: readonly string[], deps: Trace
 export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {}): Response {
   if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
   const url = new URL(req.url);
+  const projectId = url.searchParams.get('projectId');
+  const projectSessions = projectId === null ? undefined : new Set(listSessions({ projectId }).map(session => session.id));
   const parsed = options(url);
   if (parsed.error) return jsonResponse({ ok: false, error: 'bad_request', reason: parsed.error }, 400);
   const names = storeNames(url, deps);
@@ -315,7 +324,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
       for (const entry of stores) {
         if (!entry.store) { failures.push({ name: entry.name, reason: entry.error ?? 'log-store-unavailable' }); continue; }
         try {
-          const page = entry.store.aggregateRuns({ sinceMs: parsed.from, untilMs: parsed.to }, RUN_LIMIT);
+          const page = entry.store.aggregateRuns({ sinceMs: parsed.from, untilMs: parsed.to,
+            ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) }, RUN_LIMIT);
           if (page.length >= RUN_LIMIT) runLimitReached = true;
           runs.push(...page.map((run) => ({ ...run, universe: entry.name })));
           opened++;
@@ -334,7 +344,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     for (const entry of stores) {
       if (!entry.store) { failures.push({ name: entry.name, reason: entry.error ?? 'log-store-unavailable' }); continue; }
       try {
-        const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1 };
+        const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1,
+          ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) };
         const search = url.searchParams.get('q');
         if (search) query.grep = search;
         // Restrict a run before paging; other JSON-only filters still apply to the bounded window.
@@ -349,7 +360,7 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
     const runId = url.searchParams.get('runId');
     let resolution: { universe?: string; checked: number; truncated?: boolean; unresolved?: boolean } | undefined;
     let resolvedFrom: 'ledger' | 'log-scan' | undefined;
-    if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url)) && !requestedUniverse) {
+    if ((parsed.level === 'L2' || parsed.level === 'L3') && runId && !rows.some((row) => matches(row, url, projectSessions)) && !requestedUniverse) {
       // A store with no log db at all («has no log store yet» — e.g. the daemon's own tree-derived universe) cannot
       // hold the run, so it must not block the ledger lookup. A store that exists but failed to open/read still does:
       // «could not read» is never answered as «not there». The reply keeps `failedStores` either way.
@@ -379,7 +390,8 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
         if (!entry?.store) return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: entry?.error ?? 'log-store-unavailable' }] }, 503);
         stores.push(entry);
         try {
-          const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1 };
+          const query: LogQuery = { sinceMs: parsed.from, untilMs: parsed.to, limit: TRACE_LIMIT + 1,
+            ...(projectId !== null ? { projectId, projectSessionIds: [...projectSessions!] } : {}) };
           const search = url.searchParams.get('q');
           if (search) query.grep = search;
           const page = entry.store.queryTraceRun(runId, query);
@@ -388,7 +400,7 @@ export function handleTrace(req: Request, opts: MetaApiOpts, deps: TraceDeps = {
         } catch (e) { return jsonResponse({ ok: false, error: 'log-store-unavailable', failedStores: [{ name, reason: e instanceof Error ? e.message : String(e) }] }, 503); }
       }
     }
-    const filtered = rows.filter((row) => matches(row, url)).sort(sortRows);
+    const filtered = rows.filter((row) => matches(row, url, projectSessions)).sort(sortRows);
     const trace = buildTrace(filtered.slice(0, parsed.limit), parsed.level, filtered.length > parsed.limit || candidateLimitReached || failures.length > 0 || resolution?.truncated === true);
     try { (deps.queryLog ?? ((details) => debug.log('logs.trace', 'query', details)))({ stores: names, level: parsed.level, count: trace.events.length, truncated: trace.truncated, mode: 'rows', runs: trace.nodes.filter((node) => node.level === 'L1' && node.count > 0).length }); } catch { /* query logging must not block reads */ }
     return jsonResponse({ ok: true, ...trace, stores: names, registeredStores: registeredStoreCount(deps), ...(resolution ? resolution.universe ? { resolvedFrom, runUniverse: resolution.universe, ...(resolvedFrom === 'log-scan' ? { checked: resolution.checked } : {}) } : { runUniverse: resolution.truncated || resolution.unresolved ? 'unresolved' as const : 'not-found' as const, checked: resolution.checked } : {}), ...(failures.length ? { failedStores: failures } : {}) }, 200);

package/src/nexus/api/workflow-history.ts

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getGlobalWorkflowDir, getProjectWorkflowDir } from '../../workflow-runtime/discovery.js';
+
+export interface WorkflowHistoryOpts {
+  scope?: 'project' | 'global';
+  cwd?: string;
+}
+
+export interface WorkflowHistoryVersion {
+  id: string;
+  createdAt: string;
+  size: number;
+}
+
+const MAX_VERSIONS = 20;
+const VERSION_ID = /^(\d{13})-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function safeName(name: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
+    throw new Error('invalid workflow name');
+  }
+}
+
+function safeVersionId(id: string): void {
+  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error('invalid workflow history version id');
+}
+
+function workflowDir(opts: WorkflowHistoryOpts): string {
+  return opts.scope === 'global'
+    ? getGlobalWorkflowDir()
+    : getProjectWorkflowDir(opts.cwd ?? process.cwd());
+}
+
+function historyDir(name: string, opts: WorkflowHistoryOpts): string {
+  safeName(name);
+  return join(workflowDir(opts), '.history', name);
+}
+
+/** Capture the current YAML before its caller overwrites it; a missing file has no history. */
+export function snapshotBeforeSave(name: string, opts: WorkflowHistoryOpts = {}): WorkflowHistoryVersion | null {
+  const dir = historyDir(name, opts);
+  const source = join(workflowDir(opts), `${name}.yaml`);
+  if (!existsSync(source)) return null;
+  const content = readFileSync(source);
+  const previous = listWorkflowHistory(name, opts)[0];
+  if (previous && readFileSync(join(dir, `${previous.id}.yaml`)).equals(content)) return null;
+
+  mkdirSync(dir, { recursive: true });
+  const timestamp = Math.max(Date.now(), previous ? Number(previous.id.slice(0, 13)) + 1 : 0);
+  const id = `${String(timestamp).padStart(13, '0')}-${randomUUID()}`;
+  const version: WorkflowHistoryVersion = {
+    id,
+    createdAt: new Date(Number(id.slice(0, 13))).toISOString(),
+    size: content.byteLength,
+  };
+  writeFileSync(join(dir, `${id}.yaml`), content, { flag: 'wx' });
+  for (const old of listWorkflowHistory(name, opts).slice(MAX_VERSIONS)) {
+    unlinkSync(join(dir, `${old.id}.yaml`));
+  }
+  return version;
+}
+
+/** Enumerate only this workflow's snapshots, newest first. */
+export function listWorkflowHistory(name: string, opts: WorkflowHistoryOpts = {}): WorkflowHistoryVersion[] {
+  const dir = historyDir(name, opts);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(file => file.endsWith('.yaml') && VERSION_ID.test(file.slice(0, -5)))
+    .map(file => {
+      const id = file.slice(0, -5);
+      const filePath = join(dir, file);
+      const stat = statSync(filePath);
+      return stat.isFile() ? { id, createdAt: new Date(Number(id.slice(0, 13))).toISOString(), size: stat.size } : null;
+    })
+    .filter((version): version is WorkflowHistoryVersion => version !== null)
+    .sort((a, b) => b.id.localeCompare(a.id));
+}
+
+/** A missing (well-formed) version returns null rather than an empty YAML draft. */
+export function getWorkflowHistoryVersion(name: string, id: string, opts: WorkflowHistoryOpts = {}): string | null {
+  const dir = historyDir(name, opts);
+  safeVersionId(id);
+  const file = join(dir, `${id}.yaml`);
+  if (!VERSION_ID.test(id) || !existsSync(file)) return null;
+  return readFileSync(file, 'utf-8');
+}