elanous 0.2.0 → 0.2.5

package/src/nexus/api/design-check.ts

@@ -1,4 +1,4 @@
-// NEXUS · GET /v1/design-check — the craft-rulebook verdict, over the wire
+// NEXUS · GET /v1/design-check and POST /v1/design-direction
 //
 // `elanous repo design-check` already answers "which craft rulebooks does this
 // repository's DESIGN.md declare, and which of them cannot be found?" — but
@@ -6,48 +6,28 @@
 // `resolveDesignCheck`, not re-derived here) to the PWA, so the browser panel
 // and the CLI can never drift apart.
 //
-// ⭐ Two roots, deliberately different — this is the whole subtlety:
-//
-//   DESIGN.md       ← the ACTIVE REPOSITORY, found the way `/v1/worktrees`
-//                     finds it (`git rev-parse --show-toplevel` from the
-//                     daemon's cwd). The daemon watches one checkout; that
-//                     checkout's design document is the subject.
-//   craft/          ← ELANOUS'S INSTALLATION directory. `#11793` established
-//                     that the rulebooks travel with elanous, not with the
-//                     project under inspection, so a project outside the
-//                     elanous tree still resolves them.
-//
-// Reading either root from the other would reintroduce exactly the
-// `process.cwd()` coupling `#11793` removed.
-//
-// Wire shape:
-//   { repoRoot: string | null,
-//     ok: true,  documentPath, craftDirectory,
-//                availableRulebooks[], declaredRulebooks[], unavailableRulebooks[],
-//                exitCode: 0 | 1 }
-//   { repoRoot: string | null,
-//     ok: false, blockedOn: 'no-repository' | 'craft-directory' | 'design-document',
-//                path: string | null, exitCode: 1 }
-//
-// ⛔ `blockedOn` is carried through rather than flattened to an error string:
-//    a renderer must be able to tell "nothing is missing" from "I could not
-//    read the directory", and prose cannot be switched on reliably.
-//
-// Read-only · no auth (mirrors `/v1/worktrees` under the same same-origin
-// enforcement layer).
+// DESIGN.md comes from the configured harness.defaultRepo when present (no
+// fallback if it is invalid), otherwise the daemon's checkout. The craft and
+// bundled system directories always come from the elanous installation.
+// A blocked verdict is still a GET result, not an HTTP error. POST writes are
+// authenticated at http-server's /v1 owner-auth gate before this handler runs.
 
 import { readFileSync, readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 
+import { debug } from '../../debug/log.js';
+import { applyDesignDirection, type ApplyDesignDirectionResult } from '../../design/apply-direction.js';
 import { designCheckExitCode, resolveDesignCheck, type DesignCheckDeps } from '../../design/design-check.js';
-import { directionFromDesignMd, listDesignDirections, parseDeclaredDirection } from '../../design/design-directions.js';
-import { jsonResponse } from './http-server.js';
+import { directionFromDesignMd, listAllDesignDirections, parseDeclaredDirection } from '../../design/design-directions.js';
+import { defaultDesignSystemsDir, listDesignSystems } from '../../design/design-systems.js';
+import { getUserConfig } from '../../user-config.js';
+import { jsonResponse } from './json-response.js';
 import { detectRepoRoot } from './worktrees.js';
 
 export interface DesignCheckRouteDeps extends DesignCheckDeps {
-  /** Active repository root, or null outside a checkout. Injected so the
-   *  route can be tested without spawning git. */
-  repoRoot: () => string | null;
+  /** Detect a checkout from the configured path, or from the daemon cwd. */
+  repoRoot: (cwd?: string) => string | null;
+  defaultRepo?: () => string | undefined;
   /** Absolute path of elanous's vendored craft rulebook directory. */
   craftDirectory: () => string;
 }
@@ -59,23 +39,44 @@ function installedCraftDirectory(): string {
   return resolve(import.meta.dir, '..', '..', '..', 'docs', 'design', 'craft');
 }
 
-const liveDeps: DesignCheckRouteDeps = {
+export const designCheckLiveDeps: DesignCheckRouteDeps = {
   readFile: (path, encoding) => readFileSync(path, encoding),
   readdir: (path) => readdirSync(path),
-  repoRoot: () => detectRepoRoot(),
+  repoRoot: (cwd) => detectRepoRoot(cwd === undefined ? {} : { cwd }),
+  defaultRepo: () => getUserConfig().harness?.defaultRepo,
   craftDirectory: installedCraftDirectory,
 };
 
-/** Pure — builds the wire body from injected reads. Exported for tests so the
- *  route's shape is pinned without booting an HTTP server. */
+const liveDeps: DesignCheckRouteDeps = designCheckLiveDeps;
+
+export interface DesignDirectionRouteDeps extends DesignCheckRouteDeps {
+  applyDirection: typeof applyDesignDirection;
+  logSelection: (repoRoot: string, direction: string) => void;
+}
+
+const directionDeps: Pick<DesignDirectionRouteDeps, 'applyDirection' | 'logSelection'> = {
+  applyDirection: applyDesignDirection,
+  logSelection: (repoRoot, direction) => debug.log('nexus.design-direction', 'selected', { repoRoot, direction }),
+};
+
+export type DesignRepository = { repoRoot: string | null; repoSource: 'config' | 'cwd' | null };
+
+/** Same repository the design-check verdict reads: harness.defaultRepo, else daemon cwd. */
+export function resolveDesignRepository(deps: DesignCheckRouteDeps): DesignRepository {
+  const configured = (deps.defaultRepo ?? (() => getUserConfig().harness?.defaultRepo))();
+  if (configured !== undefined) {
+    return { repoRoot: isAbsolute(configured) ? deps.repoRoot(configured) : null, repoSource: 'config' };
+  }
+  const repoRoot = deps.repoRoot();
+  return { repoRoot, repoSource: repoRoot ? 'cwd' : null };
+}
+
+/** Builds the wire body from injected reads. Exported for tests without booting HTTP. */
 export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> = {}): Record<string, unknown> {
   const deps = { ...liveDeps, ...overrides };
-  const repoRoot = deps.repoRoot();
+  const { repoRoot, repoSource } = resolveDesignRepository(deps);
   if (!repoRoot) {
-    // ⛔ Distinct from a read failure. "The daemon is not inside a checkout"
-    // is a deployment fact the operator can act on; collapsing it into
-    // `design-document` would send them hunting for a missing file instead.
-    return { repoRoot: null, ok: false, blockedOn: 'no-repository', path: null, exitCode: 1 };
+    return { repoRoot: null, repoSource, ok: false, blockedOn: 'no-repository', path: null, exitCode: 1 };
   }
   const outcome = resolveDesignCheck(
     join(repoRoot, 'DESIGN.md'),
@@ -84,7 +85,7 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
   );
   const exitCode = designCheckExitCode(outcome);
   if (!outcome.ok) {
-    return { repoRoot, ok: false, blockedOn: outcome.blockedOn, path: outcome.path, exitCode };
+    return { repoRoot, repoSource, ok: false, blockedOn: outcome.blockedOn, path: outcome.path, exitCode };
   }
   // B5 — 방향은 «같은 문서»에서 나온다. 두 번째 라우트를 만들면 두 번째
   // 「어느 저장소의 DESIGN.md 인가」 답이 생긴다. 여기서 같이 실어 보낸다.
@@ -95,23 +96,23 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
   try {
     document = deps.readFile(outcome.documentPath, 'utf8');
   } catch { /* 방금 읽힌 문서다. 사라졌으면 「선언 없음」과 같은 화면이 맞다. */ }
-  // ⭐ 방향은 «둘»에서 온다: 테마 레지스트리(여섯) ⊕ ***이 문서 자신***.
-  //    🩸 2026-09-08 실측: 여섯은 전부 «터미널 색 스킴»이라 웹 레퍼런스에서 뽑은 팔레트·서체는
-  //       ***어느 이름으로도 선언할 수 없었다*** — 선언하면 늘 `unavailable` 로 떨어졌다.
-  //    ⛔ 문서 방향을 «항상» 만들지 않는다. 선언이 테마에 없을 때만 «그 이름으로» 시도한다 —
-  //       그래야 오타가 조용히 「스스로 선언한 방향」으로 둔갑하지 않는다(팔레트를 못 읽으면 null).
-  const themeDirections = listDesignDirections();
-  const declaredAmongThemes = parseDeclaredDirection(document, themeDirections);
-  const documentDirection = declaredAmongThemes.unavailable === null
+  // Bundled terminal themes and web systems are selectable; a document-defined
+  // direction is added only when its declared ID is not already bundled and
+  // its palette supplies a usable swatch (never turn a typo into a direction).
+  const bundledDirections = listAllDesignDirections();
+  const declaredAmongBundled = parseDeclaredDirection(document, bundledDirections);
+  const documentDirection = declaredAmongBundled.unavailable === null
     ? null
-    : directionFromDesignMd(document, declaredAmongThemes.unavailable);
+    : directionFromDesignMd(document, declaredAmongBundled.unavailable);
   const availableDirections = documentDirection === null
-    ? themeDirections
-    : [...themeDirections, documentDirection];
+    ? bundledDirections
+    : [...bundledDirections, documentDirection];
+  const systemCategories = new Map(listDesignSystems(defaultDesignSystemsDir()).map((system) => [system.id, system.category]));
   const direction = parseDeclaredDirection(document, availableDirections);
 
   return {
     repoRoot,
+    repoSource,
     ok: true,
     documentPath: outcome.documentPath,
     craftDirectory: outcome.craftDirectory,
@@ -123,9 +124,9 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
       declared: direction.declared,
       unavailable: direction.unavailable,
       available: availableDirections.map((d) => ({
-        id: d.id, mood: d.mood, isDark: d.isDark, isPastel: d.isPastel, swatch: d.swatch,
-        // ⛔ 「테마에서 왔다」와 「이 문서가 스스로 정했다」를 화면이 가를 수 있어야 한다.
+        id: d.id, label: d.label, mood: d.mood, isDark: d.isDark, isPastel: d.isPastel, swatch: d.swatch,
         source: d.source ?? 'theme', typography: d.typography ?? null,
+        category: systemCategories.get(d.id) ?? null,
       })),
     },
   };
@@ -138,3 +139,33 @@ export function buildDesignCheckView(overrides: Partial<DesignCheckRouteDeps> =
 export function handleDesignCheck(): Response {
   return jsonResponse(buildDesignCheckView(), 200);
 }
+
+/** The HTTP dispatcher must run owner checkAuth before invoking this write handler. */
+export async function handleDesignDirectionPost(
+  req: Request,
+  overrides: Partial<DesignDirectionRouteDeps> = {},
+): Promise<Response> {
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ ok: false, reason: 'invalid-json' }, 400); }
+  if (!body || typeof body !== 'object' || Array.isArray(body)
+    || typeof (body as { id?: unknown }).id !== 'string'
+    || !(body as { id: string }).id.trim()) {
+    return jsonResponse({ ok: false, reason: 'id-required' }, 400);
+  }
+  const id = (body as { id: string }).id;
+  const deps = { ...liveDeps, ...directionDeps, ...overrides };
+  const { repoRoot, repoSource } = resolveDesignRepository(deps);
+  if (!repoRoot) return jsonResponse({ ok: false, reason: 'no-repository', repoRoot, repoSource }, 409);
+  let result: ApplyDesignDirectionResult;
+  try { result = deps.applyDirection(join(repoRoot, 'DESIGN.md'), id); }
+  catch (error) {
+    debug.log('nexus.design-direction', 'failed', { repoRoot, direction: id, error: String(error) }, { level: 'error' });
+    return jsonResponse({ ok: false, reason: 'cannot-write' }, 500);
+  }
+  if (!result.ok) {
+    return jsonResponse(result, result.reason === 'unknown-direction' ? 400 : result.reason === 'conflicting-system-file' ? 409 : 500);
+  }
+  deps.logSelection(repoRoot, id);
+  return jsonResponse({ ...result, repoRoot, repoSource }, 200);
+}

package/src/nexus/api/design-previews-route.ts

@@ -0,0 +1,182 @@
+// NEXUS · GET /v1/design-previews and GET /v1/design-previews/<system>
+//
+// RFC design loop §A2 — HTML previews written under
+// `<repo>/design/previews/<system>.html`. The repository is the same one
+// `GET /v1/design-check` reads (`resolveDesignRepository`). Preview HTML is
+// untrusted agent output: this route only returns the file bytes. The PWA
+// paints them in a sandboxed iframe with no scripts and no same-origin.
+
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+
+import { debug } from '../../debug/log.js';
+import {
+  designCheckLiveDeps,
+  resolveDesignRepository,
+} from './design-check.js';
+import { jsonResponse } from './json-response.js';
+import { DESIGN_PREVIEW_PATH_PREFIX, DESIGN_PREVIEWS_PATH } from './rest-route-paths.js';
+
+/** `<system>.html` — system id is the stem of this pattern. */
+export const PREVIEW_FILE_RE = /^[a-z0-9][a-z0-9-]*\.html$/;
+export const PREVIEW_SYSTEM_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** 512 KiB. Larger documents are refused rather than streamed into the PWA. */
+export const PREVIEW_MAX_BYTES = 512 * 1024;
+
+export interface DesignPreviewEntry {
+  system: string;
+  bytes: number;
+  modifiedAt: string;
+}
+
+export interface DesignPreviewsRouteDeps {
+  resolveRepository: () => { repoRoot: string | null; repoSource: 'config' | 'cwd' | null };
+  readdir: (path: string) => string[];
+  stat: (path: string) => { size: number; mtimeMs: number };
+  readFile: (path: string) => string;
+  realpath: (path: string) => string;
+}
+
+const liveDeps: DesignPreviewsRouteDeps = {
+  resolveRepository: () => resolveDesignRepository(designCheckLiveDeps),
+  readdir: (path) => readdirSync(path),
+  stat: (path) => {
+    const st = statSync(path);
+    return { size: st.size, mtimeMs: st.mtimeMs };
+  },
+  readFile: (path) => readFileSync(path, 'utf8'),
+  realpath: (path) => realpathSync(path),
+};
+
+function previewsDir(repoRoot: string): string {
+  return join(repoRoot, 'design', 'previews');
+}
+
+function isInsidePreviews(previewsRoot: string, candidate: string): boolean {
+  const root = previewsRoot.endsWith(sep) ? previewsRoot : previewsRoot + sep;
+  return candidate === previewsRoot || candidate.startsWith(root);
+}
+
+export function listDesignPreviews(
+  overrides: Partial<DesignPreviewsRouteDeps> = {},
+): { repoRoot: string | null; repoSource: 'config' | 'cwd' | null; previews: DesignPreviewEntry[] } {
+  const deps = { ...liveDeps, ...overrides };
+  const { repoRoot, repoSource } = deps.resolveRepository();
+  if (!repoRoot) {
+    debug.log('design.previews', 'listed', { repoRoot, reason: 'no-repository' });
+    return { repoRoot, repoSource, previews: [] };
+  }
+  const dir = previewsDir(repoRoot);
+  let names: string[];
+  try {
+    names = deps.readdir(dir);
+  } catch {
+    debug.log('design.previews', 'listed', { repoRoot, reason: 'no-directory' });
+    return { repoRoot, repoSource, previews: [] };
+  }
+  // The list must not reveal what serving refuses: a link that escapes
+  // design/previews/ would otherwise leak its target's size and time here.
+  let rootReal: string | null = null;
+  try { rootReal = resolve(deps.realpath(dir)); } catch { rootReal = null; }
+  const previews: DesignPreviewEntry[] = [];
+  for (const name of names) {
+    if (!PREVIEW_FILE_RE.test(name)) continue;
+    const file = join(dir, name);
+    let fileReal: string;
+    try { fileReal = resolve(deps.realpath(file)); }
+    catch { continue; }
+    if (!rootReal || !isInsidePreviews(rootReal, fileReal)) continue;
+    let st: { size: number; mtimeMs: number };
+    try { st = deps.stat(fileReal); }
+    catch { continue; }
+    previews.push({
+      system: name.slice(0, -'.html'.length),
+      bytes: st.size,
+      modifiedAt: new Date(st.mtimeMs).toISOString(),
+    });
+  }
+  previews.sort((a, b) => a.system.localeCompare(b.system));
+  debug.log('design.previews', 'listed', { repoRoot });
+  return { repoRoot, repoSource, previews };
+}
+
+export type ServePreviewResult =
+  | { status: 200; body: { system: string; html: string } }
+  | { status: 400 | 404 | 413; body: { error: string; reason: string } };
+
+export function serveDesignPreview(
+  system: string,
+  overrides: Partial<DesignPreviewsRouteDeps> = {},
+): ServePreviewResult {
+  const deps = { ...liveDeps, ...overrides };
+  const { repoRoot } = deps.resolveRepository();
+  if (!PREVIEW_SYSTEM_RE.test(system) || system.includes('..') || system.includes('/') || system.includes('\\')) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'bad-name' });
+    return { status: 400, body: { error: 'bad-name', reason: 'bad-name' } };
+  }
+  if (!repoRoot) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'no-repository' });
+    return { status: 404, body: { error: 'not-found', reason: 'no-repository' } };
+  }
+  const dir = previewsDir(repoRoot);
+  let rootReal: string;
+  try { rootReal = deps.realpath(dir); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  const file = join(dir, `${system}.html`);
+  let fileReal: string;
+  try { fileReal = deps.realpath(file); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  if (!isInsidePreviews(resolve(rootReal), resolve(fileReal))) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'escape' });
+    return { status: 404, body: { error: 'not-found', reason: 'escape' } };
+  }
+  let st: { size: number; mtimeMs: number };
+  try { st = deps.stat(fileReal); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  if (st.size > PREVIEW_MAX_BYTES) {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'too-large' });
+    return { status: 413, body: { error: 'too-large', reason: 'too-large' } };
+  }
+  let html: string;
+  try { html = deps.readFile(fileReal); }
+  catch {
+    debug.log('design.previews', 'refused', { repoRoot, system, reason: 'not-found' });
+    return { status: 404, body: { error: 'not-found', reason: 'not-found' } };
+  }
+  debug.log('design.previews', 'served', { repoRoot, system });
+  return { status: 200, body: { system, html } };
+}
+
+function systemFromPath(pathname: string): string | null {
+  if (pathname === DESIGN_PREVIEWS_PATH) return null;
+  if (!pathname.startsWith(DESIGN_PREVIEW_PATH_PREFIX)) return null;
+  const raw = pathname.slice(DESIGN_PREVIEW_PATH_PREFIX.length);
+  if (!raw || raw.includes('/')) return '';
+  try { return decodeURIComponent(raw); }
+  catch { return raw; }
+}
+
+/** GET dispatcher. Auth is the shared `/v1` owner gate in http-server. */
+export function handleDesignPreviews(pathname: string, overrides: Partial<DesignPreviewsRouteDeps> = {}): Response {
+  if (pathname === DESIGN_PREVIEWS_PATH) {
+    return jsonResponse(listDesignPreviews(overrides), 200);
+  }
+  const system = systemFromPath(pathname);
+  if (system === null || system === '') {
+    const { repoRoot } = (overrides.resolveRepository ?? liveDeps.resolveRepository)();
+    debug.log('design.previews', 'refused', { repoRoot, reason: 'bad-name' });
+    return jsonResponse({ error: 'bad-name', reason: 'bad-name' }, 400);
+  }
+  const result = serveDesignPreview(system, overrides);
+  return jsonResponse(result.body, result.status);
+}

package/src/nexus/api/design-system-create-route.ts

@@ -0,0 +1,123 @@
+// POST /v1/design-system — URL 또는 팔레트로 라이브러리에 시스템을 하나 만든다.
+// 소유자 인증은 디스패처가 본문을 읽기 전에 한다. 이 핸들러는 그 뒤에만 호출된다.
+// 한 번에 하나만: 진행 중이면 429.
+
+import { debug } from '../../debug/log.js';
+import {
+  createCustomSystemFromPalette,
+  createCustomSystemFromUrl,
+  type CustomSystemCreateDeps,
+  type CustomSystemCreateResult,
+} from '../../design/custom-system-create.js';
+import { jsonResponse } from './json-response.js';
+
+export interface DesignSystemCreateRouteDeps extends CustomSystemCreateDeps {
+  readonly log?: (event: 'created' | 'refused', data: Record<string, unknown>) => void;
+}
+
+let inFlight = false;
+
+export function designSystemCreateInFlight(): boolean {
+  return inFlight;
+}
+
+/** 시험이 프로세스 전역 잠금을 비운다. */
+export function resetDesignSystemCreateGate(): void {
+  inFlight = false;
+}
+
+function hostOnly(url: string): string | undefined {
+  try {
+    return new URL(url).hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function statusFor(result: Extract<CustomSystemCreateResult, { ok: false }>): number {
+  switch (result.reason) {
+    case 'id-taken': return 409;
+    case 'extract-failed': return 502;
+    default: return 400;
+  }
+}
+
+function wire(result: CustomSystemCreateResult): Record<string, unknown> {
+  if (!result.ok) {
+    return { ok: false, reason: result.reason, ...(result.detail === undefined ? {} : { detail: result.detail }) };
+  }
+  return {
+    ok: true,
+    id: result.id,
+    dir: result.dir,
+    tokens: result.tokens,
+    unread: result.unread,
+    warnings: result.warnings,
+    ...(result.extractDir === undefined ? {} : { extractDir: result.extractDir }),
+  };
+}
+
+export async function handleDesignSystemCreate(
+  req: Request,
+  overrides: DesignSystemCreateRouteDeps = {},
+): Promise<Response> {
+  const log = overrides.log ?? ((event: 'created' | 'refused', data: Record<string, unknown>) => {
+    debug.log('design.custom', event, data);
+  });
+  if (inFlight) {
+    log('refused', { reason: 'busy' });
+    return jsonResponse({ ok: false, reason: 'busy' }, 429);
+  }
+  inFlight = true;
+  const started = Date.now();
+  try {
+    let body: unknown;
+    try { body = await req.json(); }
+    catch { return jsonResponse({ ok: false, reason: 'invalid-json' }, 400); }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return jsonResponse({ ok: false, reason: 'invalid-body' }, 400);
+    }
+    const record = body as { kind?: unknown; url?: unknown; colors?: unknown; id?: unknown; name?: unknown; base?: unknown };
+    const id = typeof record.id === 'string' ? record.id : undefined;
+    const name = typeof record.name === 'string' ? record.name : undefined;
+    const base = typeof record.base === 'string' ? record.base : undefined;
+    const deps: CustomSystemCreateDeps = overrides;
+
+    let result: CustomSystemCreateResult;
+    let kind: 'url' | 'palette';
+    let host: string | undefined;
+    if (record.kind === 'url') {
+      kind = 'url';
+      if (typeof record.url !== 'string' || !record.url.trim()) {
+        log('refused', { kind, reason: 'bad-url', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'bad-url' }, 400);
+      }
+      host = hostOnly(record.url);
+      result = await createCustomSystemFromUrl({ url: record.url, id, name, base }, deps);
+    } else if (record.kind === 'palette') {
+      kind = 'palette';
+      if (!Array.isArray(record.colors) || record.colors.some((color) => typeof color !== 'string')) {
+        log('refused', { kind, reason: 'no-colors', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'no-colors' }, 400);
+      }
+      if (typeof record.id !== 'string' || !record.id.trim()) {
+        log('refused', { kind, reason: 'bad-id', ms: Date.now() - started });
+        return jsonResponse({ ok: false, reason: 'bad-id' }, 400);
+      }
+      result = await createCustomSystemFromPalette({ colors: record.colors, id: record.id, name, base }, deps);
+    } else {
+      log('refused', { reason: 'bad-kind', ms: Date.now() - started });
+      return jsonResponse({ ok: false, reason: 'bad-kind' }, 400);
+    }
+
+    const ms = Date.now() - started;
+    if (!result.ok) {
+      log('refused', { kind, ...(host ? { host } : {}), ...(result.detail && result.reason === 'id-taken' ? { id: result.detail } : {}), reason: result.reason, ms });
+      return jsonResponse(wire(result), statusFor(result));
+    }
+    log('created', { kind, id: result.id, ...(host ? { host } : {}), ms });
+    return jsonResponse(wire(result), 201);
+  } finally {
+    inFlight = false;
+  }
+}

package/src/nexus/api/graph-approvals.ts

@@ -0,0 +1,125 @@
+import { existsSync, readFileSync, readdirSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../debug/log.js';
+import { decideGraphApproval, lastJsonObject, type GraphRunState } from '../../graph-runner/runner.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { jsonResponse } from './json-response.js';
+
+export const GRAPH_APPROVALS_PATH = '/v1/graph-approvals';
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+interface GraphApprovalItem {
+  graphId: string;
+  runId: string;
+  nodeId: string;
+  message: string;
+  since: string;
+  path: string[];
+  recent: Array<{ nodeId: string; ok: boolean; outcome?: string; summary?: string }>;
+}
+
+interface GraphApprovalsDeps {
+  authorize?: (request: Request) => boolean;
+  /** Credential the request carries, checked independently of same-origin (`bearerCredential`).
+   * A decision needs a bearer token: same-origin alone is not trusted because behind
+   * `tailscale serve` every tailnet peer (Pod included) arrives from loopback. */
+  authReason?: (request: Request) => string | undefined;
+  root?: string;
+}
+
+const DECISION_AUTH_REASONS = new Set(['bearer-match', 'temp-token', 'noauth']);
+
+function validSegment(value: string): boolean {
+  return SEGMENT.test(value) && value !== '.' && value !== '..';
+}
+
+function readRun(root: string, graphId: string, runId: string): GraphRunState | null {
+  if (!validSegment(graphId) || !validSegment(runId)) return null;
+  try {
+    const state = JSON.parse(readFileSync(join(root, 'graph-runs', graphId, `${runId}.json`), 'utf8')) as GraphRunState;
+    return state.graphId === graphId && state.runId === runId ? state : null;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function undecided(state: GraphRunState, root: string): boolean {
+  return state.status === 'awaiting-approval' && !!state.pending && !state.pending.decision
+    && Array.isArray(state.path) && !existsSync(join(root, 'graph-runs', state.graphId, `${state.runId}.json.${state.path.length}.decision.json`));
+}
+
+function list(root: string): GraphApprovalItem[] {
+  const dir = join(root, 'graph-runs');
+  let graphs: Dirent[];
+  try { graphs = readdirSync(dir, { withFileTypes: true }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const items: GraphApprovalItem[] = [];
+  for (const graph of graphs) {
+    if (!graph.isDirectory() || !validSegment(graph.name)) continue;
+    for (const file of readdirSync(join(dir, graph.name), { withFileTypes: true })) {
+      if (!file.isFile() || !file.name.endsWith('.json') || file.name.endsWith('.decision.json')) continue;
+      const runId = file.name.slice(0, -5);
+      const state = readRun(root, graph.name, runId);
+      if (!state || !undecided(state, root) || !Array.isArray(state.nodes)) continue;
+      const pending = state.pending!;
+      items.push({
+        graphId: state.graphId, runId: state.runId, nodeId: pending.nodeId, message: pending.message,
+        since: pending.since, path: state.path,
+        recent: state.nodes.slice(-5).map((node) => {
+          const output = lastJsonObject(node.output);
+          return {
+            nodeId: node.nodeId, ok: node.ok,
+            ...(typeof output?.outcome === 'string' ? { outcome: output.outcome } : {}),
+            ...(typeof output?.summary === 'string' ? { summary: output.summary } : {}),
+          };
+        }),
+      });
+    }
+  }
+  return items.sort((a, b) => b.since.localeCompare(a.since));
+}
+
+export async function handleGraphApprovals(req: Request, deps: GraphApprovalsDeps = {}): Promise<Response> {
+  const pathname = new URL(req.url).pathname;
+  const match = /^\/v1\/graph-approvals\/([^/]+)\/([^/]+)$/.exec(pathname);
+  if (pathname !== GRAPH_APPROVALS_PATH && !match) return jsonResponse({ error: 'not-found' }, 404);
+  if (!deps.authorize?.(req)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (pathname === GRAPH_APPROVALS_PATH) {
+    if (req.method !== 'GET') return jsonResponse({ error: 'method-not-allowed' }, 405);
+    return jsonResponse({ items: list(deps.root ?? effectiveInstanceRoot()) });
+  }
+  if (req.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405);
+  const authReason = deps.authReason?.(req);
+  if (!authReason || !DECISION_AUTH_REASONS.has(authReason)) {
+    debug.log('approvals.graph', 'refused', { reason: 'pairing-required', auth: authReason ?? null });
+    return jsonResponse({ error: 'pairing-required' }, 403);
+  }
+  let graphId: string;
+  let runId: string;
+  try { graphId = decodeURIComponent(match![1]!); runId = decodeURIComponent(match![2]!); }
+  catch { return jsonResponse({ error: 'not-found' }, 404); }
+  if (!validSegment(graphId) || !validSegment(runId)) return jsonResponse({ error: 'not-found' }, 404);
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return jsonResponse({ error: 'bad_request' }, 400); }
+  const decision = body && typeof body === 'object' && !Array.isArray(body) && 'decision' in body ? body.decision : undefined;
+  if (decision !== 'approved' && decision !== 'rejected') return jsonResponse({ error: 'bad_request' }, 400);
+  const root = deps.root ?? effectiveInstanceRoot();
+  const state = readRun(root, graphId, runId);
+  if (!state) return jsonResponse({ error: 'not-found' }, 404);
+  if (!undecided(state, root)) return jsonResponse({ error: 'already-decided' }, 409);
+  const nodeId = state.pending!.nodeId;
+  try {
+    decideGraphApproval(graphId, runId, decision, `pwa:${authReason}`, root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return jsonResponse({ error: 'not-found' }, 404);
+    if (error instanceof Error && error.message.startsWith('run is not awaiting an undecided approval:')) return jsonResponse({ error: 'already-decided' }, 409);
+    throw error;
+  }
+  debug.log('approvals.graph', 'decided', { graphId, runId, nodeId, decision, by: `pwa:${authReason}` });
+  return jsonResponse({ graphId, runId, decision });
+}