claude-code-session-manager 0.37.1 → 0.38.0

package/src/main/lib/__tests__/localAdminHttp.test.cjs

@@ -0,0 +1,120 @@
+/**
+ * localAdminHttp.test.cjs — unit tests for the generic loopback-only HTTP
+ * transport (PRD 689 — extracted from the former standalone admin HTTP server
+ * module). Covers
+ * only transport concerns: auth rejection, token persistence, route dispatch,
+ * and 404 on unknown routes. Route *logic* tests live beside their owning
+ * module (scheduler.cjs's admin routes, prdCreate.cjs's create-prd route).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/localAdminHttp.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const http = require('node:http');
+const fs = require('node:fs');
+const { createAdminHttp, TOKEN_PATH } = require('../localAdminHttp.cjs');
+
+function request(port, { method = 'GET', path: reqPath, token, body }) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (token !== undefined) headers.Authorization = `Bearer ${token}`;
+    let payload;
+    if (body !== undefined) {
+      payload = JSON.stringify(body);
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = Buffer.byteLength(payload);
+    }
+    const req = http.request({ hostname: '127.0.0.1', port, method, path: reqPath, headers }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null;
+        try { json = JSON.parse(text); } catch { /* leave null for non-JSON bodies */ }
+        resolve({ status: res.statusCode, json, text });
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+test('request without bearer token returns 401', async () => {
+  const admin = createAdminHttp();
+  admin.registerRoute('GET', '/ping', async (req, res) => { res.writeHead(200); res.end('{}'); });
+  const { port } = await admin.start();
+  try {
+    const res = await request(port, { path: '/ping' });
+    expect(res.status).toBe(401);
+    expect(res.json.ok).toBe(false);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('request with wrong bearer token returns 401', async () => {
+  const admin = createAdminHttp();
+  admin.registerRoute('GET', '/ping', async (req, res) => { res.writeHead(200); res.end('{}'); });
+  const { port } = await admin.start();
+  try {
+    const res = await request(port, { path: '/ping', token: 'not-the-token' });
+    expect(res.status).toBe(401);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('registered route with correct token is dispatched', async () => {
+  const admin = createAdminHttp();
+  admin.registerRoute('GET', '/ping', async (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, pong: true }));
+  });
+  const { port, token } = await admin.start();
+  try {
+    const res = await request(port, { path: '/ping', token });
+    expect(res.status).toBe(200);
+    expect(res.json).toEqual({ ok: true, pong: true });
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('unregistered path/method returns 404', async () => {
+  const admin = createAdminHttp();
+  const { port, token } = await admin.start();
+  try {
+    const res = await request(port, { path: '/nope', token });
+    expect(res.status).toBe(404);
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('server binds only to 127.0.0.1', async () => {
+  const admin = createAdminHttp();
+  await admin.start();
+  try {
+    expect(admin.server.address().address).toBe('127.0.0.1');
+  } finally {
+    await admin.stop();
+  }
+});
+
+test('start() persists token file with port + token, mode 0600', async () => {
+  const admin = createAdminHttp();
+  const { port, token } = await admin.start();
+  try {
+    const raw = fs.readFileSync(TOKEN_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.port).toBe(port);
+    expect(parsed.token).toBe(token);
+    const mode = fs.statSync(TOKEN_PATH).mode & 0o777;
+    expect(mode).toBe(0o600);
+  } finally {
+    await admin.stop();
+  }
+});

package/src/main/lib/classifyTranscriptLine.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+const MAX_RAW_STR = 4096;
+
+// Block types whose text/content fields are parsed structurally by
+// orchestrator.ts / race.ts — truncating them produces mid-token "…" and
+// unparseable JSON, so they are exempt from the size cap.
+const EXEMPT_TYPES = new Set(['tool_result', 'tool_use']);
+
+/**
+ * Cap string fields in a content block array so arbitrary tool output doesn't
+ * bloat the ring buffer. Blocks whose type is in EXEMPT_TYPES are passed
+ * through intact so that structured result payloads survive to the digest
+ * parsers in race.ts / orchestrator.ts.
+ */
+function trimContentArray(content) {
+  if (!Array.isArray(content)) return content;
+  return content.map((block) => {
+    if (!block || typeof block !== 'object') return block;
+    if (EXEMPT_TYPES.has(block.type)) return block;
+    const b = { ...block };
+    if (typeof b.text === 'string' && b.text.length > MAX_RAW_STR) {
+      b.text = b.text.slice(0, MAX_RAW_STR) + '…';
+    }
+    if (typeof b.content === 'string' && b.content.length > MAX_RAW_STR) {
+      b.content = b.content.slice(0, MAX_RAW_STR) + '…';
+    }
+    if (Array.isArray(b.content)) {
+      b.content = trimContentArray(b.content);
+    }
+    return b;
+  });
+}
+
+/** Build the slim raw projection used by race.ts and orchestrator.ts. */
+function makeRaw(obj) {
+  const msgContent = obj?.message?.content;
+  return { message: { content: trimContentArray(msgContent) } };
+}
+
+/**
+ * Parse one JSONL line defensively. Real schema drifts, so we pass through
+ * anything that parses and tag a coarse `kind`.
+ */
+function classifyLine(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  // Many shapes exist — try several common fields.
+  const type = obj.type || obj.event || obj.role;
+  const msg = obj.message || obj;
+  const content = msg?.content;
+
+  // Usage rollups arrive as summary events.
+  if (obj.usage || msg?.usage) {
+    return { kind: 'usage', data: obj.usage || msg.usage, raw: makeRaw(obj) };
+  }
+
+  // Tool uses: scan content array for tool_use blocks.
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block?.type === 'tool_use') {
+        if (block.name === 'TodoWrite') {
+          return { kind: 'todo_write', data: block.input?.todos || block.input || [], raw: makeRaw(obj) };
+        }
+        if (block.name === 'ExitPlanMode' || block.name === 'EnterPlanMode') {
+          return { kind: 'plan', data: block.input, raw: makeRaw(obj) };
+        }
+        if (block.name === 'Agent' || block.name === 'Task') {
+          // Include block.id as toolUseId so the live store can match the
+          // corresponding tool_result and update per-agent lastActivityAt.
+          return { kind: 'agent_spawn', data: { ...block.input, toolUseId: block.id }, raw: makeRaw(obj) };
+        }
+        return {
+          kind: 'tool_use',
+          data: { name: block.name, input: block.input, id: block.id },
+          raw: makeRaw(obj),
+        };
+      }
+      // tool_result carries the tool_use_id of the completed Task/Agent call.
+      // The live store uses this to update the agent's lastActivityAt bookend.
+      if (block?.type === 'tool_result' && block.tool_use_id) {
+        return { kind: 'tool_result', data: { toolUseId: block.tool_use_id }, raw: makeRaw(obj) };
+      }
+    }
+  }
+
+  return { kind: type || 'message', data: obj, raw: makeRaw(obj) };
+}
+
+module.exports = { MAX_RAW_STR, EXEMPT_TYPES, trimContentArray, makeRaw, classifyLine };

package/src/main/lib/localAdminHttp.cjs

@@ -0,0 +1,157 @@
+/**
+ * localAdminHttp.cjs — generic loopback-only HTTP transport with bearer-token
+ * auth, extracted from the former standalone admin HTTP server module
+ * (PRD 689). This module owns
+ * ONLY the transport: token bootstrap/persistence, timing-safe comparison,
+ * body reading, JSON responses, and a route-registration/dispatch mechanism.
+ * Route *logic* (job-management, PRD creation) lives beside the module that
+ * already owns that capability — see scheduler.cjs's registerAdminRoutes and
+ * prdCreate.cjs's registerAdminRoute.
+ *
+ * Security posture (unchanged from the former module):
+ *   - Binds 127.0.0.1 only, OS-assigned ephemeral port. Never reachable
+ *     off-box.
+ *   - Bearer token, regenerated every app boot, written to
+ *     ~/.claude/session-manager/admin-api.json with 0600 perms.
+ *   - Token compared with crypto.timingSafeEqual to avoid a timing
+ *     side-channel on the comparison itself.
+ */
+
+'use strict';
+
+const http = require('node:http');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const config = require('../config.cjs');
+
+const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.json');
+
+function timingSafeEqualStrings(a, b) {
+  const bufA = Buffer.from(String(a ?? ''));
+  const bufB = Buffer.from(String(b ?? ''));
+  if (bufA.length !== bufB.length) {
+    // Compare against a same-length buffer anyway so the failure path still
+    // takes constant time relative to the (fixed) token length, rather than
+    // returning early on a length mismatch.
+    crypto.timingSafeEqual(bufA, bufA);
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+function readBody(req, maxBytes = 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let total = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        reject(new Error('body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+/**
+ * Create the admin HTTP transport. Route handlers are registered via
+ * `registerRoute(method, url, handler)`, where `handler` is
+ * `async (req, res, rawBody) => void` — raw body reading is the transport's
+ * job (routes call `JSON.parse` themselves as needed, matching the original
+ * per-route body handling in the former module).
+ */
+function createAdminHttp() {
+  let server = null;
+  let token = null;
+  const routes = new Map();
+
+  async function ensureToken() {
+    token = crypto.randomBytes(32).toString('hex');
+    await config.writeJson(TOKEN_PATH, { port: null, token });
+    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* best-effort on platforms without POSIX perms */ }
+    return token;
+  }
+
+  async function persistPort(port) {
+    await config.writeJson(TOKEN_PATH, { port, token });
+    try { await fsp.chmod(TOKEN_PATH, 0o600); } catch { /* */ }
+  }
+
+  function authorized(req) {
+    const header = req.headers.authorization || '';
+    const match = /^Bearer (.+)$/.exec(header);
+    if (!match) return false;
+    return timingSafeEqualStrings(match[1], token);
+  }
+
+  function registerRoute(method, url, handler) {
+    routes.set(`${method} ${url}`, handler);
+  }
+
+  async function handleRequest(req, res) {
+    if (!authorized(req)) {
+      sendJson(res, 401, { ok: false, error: 'unauthorized' });
+      return;
+    }
+    try {
+      const handler = routes.get(`${req.method} ${req.url}`);
+      if (!handler) {
+        sendJson(res, 404, { ok: false, error: 'not found' });
+        return;
+      }
+      await handler(req, res);
+    } catch (e) {
+      sendJson(res, 500, { ok: false, error: e?.message ?? 'internal error' });
+    }
+  }
+
+  async function start() {
+    await ensureToken();
+    server = http.createServer((req, res) => {
+      handleRequest(req, res).catch(() => {
+        try { sendJson(res, 500, { ok: false, error: 'internal error' }); } catch { /* */ }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const { port } = server.address();
+    await persistPort(port);
+    return { port, token };
+  }
+
+  async function stop() {
+    if (!server) return;
+    await new Promise((resolve) => server.close(() => resolve()));
+    server = null;
+  }
+
+  return {
+    start,
+    stop,
+    registerRoute,
+    get token() { return token; },
+    get server() { return server; },
+  };
+}
+
+module.exports = {
+  createAdminHttp,
+  TOKEN_PATH,
+  timingSafeEqualStrings,
+  readBody,
+  sendJson,
+};

package/src/main/lib/personaImportHealth.cjs

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * personaImportHealth.cjs — integrity check for Claude Code's `@path` import
+ * syntax in ~/.claude/CLAUDE.md.
+ *
+ * The `@path` import resolves a missing/moved target to nothing with zero
+ * warning — a renamed or deleted persona file silently drops that entire
+ * block of instructions from every session. This module parses the import
+ * chain (recursively, since imported files can themselves import further
+ * files) and asserts every resolved target exists and is non-empty, plus
+ * reports git ahead/behind for each unique repo the imports live in.
+ *
+ * Pure functions taking explicit inputs (a root file path), following the
+ * evaluateTickLiveness/readFreshHeartbeat pattern in health.cjs so this is
+ * independently unit-testable without touching the real home directory.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const MAX_IMPORT_DEPTH = 5;
+// Matches a line consisting of `@` followed by an absolute or ~-relative path,
+// e.g. "@/home/user/foo.md" or "@~/Projects/Agents/shared/core.md".
+const IMPORT_LINE_RE = /^@(~?\/\S+)\s*$/;
+
+function resolveImportPath(rawPath) {
+  if (rawPath.startsWith('~/')) return path.join(os.homedir(), rawPath.slice(2));
+  if (rawPath === '~') return os.homedir();
+  return rawPath;
+}
+
+// Extracts every `@<path>` import reference from a file's raw text content.
+function extractImportPaths(content) {
+  const paths = [];
+  for (const line of content.split('\n')) {
+    const match = IMPORT_LINE_RE.exec(line.trim());
+    if (match) paths.push(resolveImportPath(match[1]));
+  }
+  return paths;
+}
+
+// Recursively walks the import chain starting at rootPath, collecting a
+// result per resolved import: { importPath, exists, nonEmpty, ok }.
+// Depth-capped to guard against a cyclic-import pathological case. Visited
+// paths are deduped so a diamond-shaped import graph doesn't get reported
+// twice or blow the depth budget.
+function walkImports(rootPath, depth = MAX_IMPORT_DEPTH, seen = new Set()) {
+  const results = [];
+  if (depth <= 0) return results;
+  if (!fs.existsSync(rootPath)) return results;
+
+  let content;
+  try {
+    content = fs.readFileSync(rootPath, 'utf8');
+  } catch {
+    return results;
+  }
+
+  for (const importPath of extractImportPaths(content)) {
+    if (seen.has(importPath)) continue;
+    seen.add(importPath);
+
+    let exists = false;
+    let nonEmpty = false;
+    try {
+      const stat = fs.statSync(importPath);
+      exists = true;
+      nonEmpty = stat.size > 0;
+    } catch {
+      exists = false;
+    }
+
+    results.push({ importPath, exists, nonEmpty, ok: exists && nonEmpty });
+
+    if (exists && nonEmpty) {
+      results.push(...walkImports(importPath, depth - 1, seen));
+    }
+  }
+
+  return results;
+}
+
+// Walks upward from startDir looking for a `.git` directory, bounded at
+// os.homedir() or the filesystem root.
+function findGitRepoRoot(startDir) {
+  const home = os.homedir();
+  let dir = startDir;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    if (dir === home) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Reports ahead/behind vs upstream for a git repo, without ever fetching
+// (rev-list reports against whatever the local remote-tracking ref already
+// has cached). Non-fatal on any failure — no upstream configured, detached
+// HEAD, git not installed — annotated as a caveat, never thrown.
+function checkRepoAheadBehind(repoRoot) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['-C', repoRoot, 'rev-list', '--left-right', '--count', 'HEAD...@{upstream}'],
+      { encoding: 'utf8', timeout: 5000 }
+    ).trim();
+    const [ahead, behind] = out.split(/\s+/).map(Number);
+    return { repoRoot, ok: true, ahead, behind };
+  } catch (e) {
+    return {
+      repoRoot,
+      ok: false,
+      noUpstream: true,
+      error: (e.message || String(e)).split('\n')[0],
+    };
+  }
+}
+
+// Top-level entry point: parses ~/.claude/CLAUDE.md's import chain, checks
+// every resolved target, and reports ahead/behind for each unique repo those
+// imports live in. claudeMdPath is injectable for testing.
+function checkPersonaImports(claudeMdPath = path.join(os.homedir(), '.claude', 'CLAUDE.md')) {
+  if (!fs.existsSync(claudeMdPath)) {
+    return { ok: true, path: claudeMdPath, exists: false, imports: [], repos: [] };
+  }
+
+  const imports = walkImports(claudeMdPath);
+  const broken = imports.filter((i) => !i.ok);
+
+  const repoRoots = new Set();
+  for (const imp of imports) {
+    if (!imp.ok) continue;
+    const repoRoot = findGitRepoRoot(path.dirname(imp.importPath));
+    if (repoRoot) repoRoots.add(repoRoot);
+  }
+
+  const repos = [...repoRoots].map(checkRepoAheadBehind);
+
+  return {
+    ok: broken.length === 0,
+    path: claudeMdPath,
+    exists: true,
+    imports,
+    brokenImports: broken,
+    repos,
+  };
+}
+
+module.exports = {
+  checkPersonaImports,
+  walkImports,
+  extractImportPaths,
+  resolveImportPath,
+  findGitRepoRoot,
+  checkRepoAheadBehind,
+  MAX_IMPORT_DEPTH,
+};

package/src/main/lib/prdCreate.cjs

@@ -1,22 +1,28 @@
 /**
- * prdCreate.cjs — PRD-body builder for the create-prd admin route (PRD 549,
- * gh-issue-6). Pure functions only: no filesystem writes, no NN allocation,
- * no HTTP. adminServer.cjs owns orchestration (auth, cwd validation via
- * config.cjs's validatePath, NN allocation via the injected remote,
- * writing via remote.writePrd -> config.cjs's writeTextAtomic) so this
- * module stays trivially unit-testable.
+ * prdCreate.cjs — PRD-body builder + create-prd admin HTTP route (PRD 549,
+ * gh-issue-6; route consolidated here from the former standalone admin HTTP
+ * server module by PRD 689). buildPrdBody/deriveSlugFromTitle/readStandards are pure
+ * functions: no filesystem writes, no NN allocation, no HTTP. registerAdminRoute
+ * owns orchestration (auth is the injected transport's job, cwd validation
+ * via config.cjs's validatePath, NN allocation via the injected remote,
+ * writing via remote.writePrd -> config.cjs's writeTextAtomic).
  *
- * Standards are read fresh from disk on every call (no in-process caching)
- * so a live edit to standards.md is picked up by the next create-prd call
- * without an app restart — same one-concept-one-implementation reasoning
- * that keeps the /develop skill re-reading it fresh per PRD (see SKILL.md).
+ * Neither this route nor the /develop skill embeds standards.md's contents
+ * anymore — both just point the headless executor at STANDARDS_PATH with an
+ * instruction to read it before starting. There's nothing to go stale: the
+ * executor always reads the live file at run time, same one-concept-one-
+ * implementation reasoning that keeps the two PRD-creation paths in sync
+ * (see SKILL.md).
  */
 'use strict';
 
 const fsp = require('node:fs/promises');
 const path = require('node:path');
-const { PRD_CREATE_SLUG_RE } = require('../ipcSchemas.cjs');
+const { schemas, PRD_CREATE_SLUG_RE } = require('../ipcSchemas.cjs');
 const { kebabCase } = require('./kebabCase.cjs');
+const config = require('../config.cjs');
+const { expandHome } = require('./expandHome.cjs');
+const { readBody, sendJson } = require('./localAdminHttp.cjs');
 
 const STANDARDS_PATH = path.join(
   __dirname, '..', '..', '..',
@@ -33,12 +39,13 @@ function deriveSlugFromTitle(title) {
 }
 
 /**
- * Build the full PRD markdown body (frontmatter + required sections +
- * verbatim engineering standards), matching the structure `/develop`'s
- * SKILL.md documents: frontmatter, then Goal / Acceptance criteria /
- * Implementation notes / Out of scope / Engineering standards, in order.
+ * Build the full PRD markdown body (frontmatter + required sections + a
+ * pointer at the engineering standards file), matching the structure
+ * `/develop`'s SKILL.md documents: frontmatter, then Goal / Acceptance
+ * criteria / Implementation notes / Out of scope / Engineering standards,
+ * in order.
  */
-function buildPrdBody(input, standardsText) {
+function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
     implementationNotes, outOfScope,
@@ -53,21 +60,104 @@ function buildPrdBody(input, standardsText) {
   const oosSource = outOfScope && outOfScope.length ? outOfScope : ['(none)'];
   const oosLines = oosSource.map((line) => `- ${line}`).join('\n');
 
+  const standardsPointer = [
+    `Before writing any code, read \`${STANDARDS_PATH}\` — it has the Performance, Debugging,`,
+    'API-reuse, TDD, and Execution-discipline rules that apply to this PRD. Every rule in it is',
+    'mandatory, especially Execution discipline (bounded commands, verify before done, the',
+    'finish-protocol sentinel).',
+  ].join('\n');
+
   const bodyLines = [
     '# Goal', '', goal, '',
     '# Acceptance criteria', '', acLines, '',
     '# Implementation notes', '', implementationNotes, '',
     '# Out of scope', '', oosLines, '',
-    '## Engineering standards', '', standardsText.trimEnd(), '',
+    '## Engineering standards', '', standardsPointer, '',
   ];
 
   return `${fmLines.join('\n')}${bodyLines.join('\n')}`;
 }
 
+/**
+ * Registers the create-prd admin HTTP route (PRD 689 — moved verbatim out of
+ * the former standalone admin HTTP server module's handleRequest, no behavior
+ * change) against an injected localAdminHttp.cjs transport. `remote` is
+ * scheduler.cjs's remote object, passed explicitly (not required directly) so
+ * this stays testable without booting Electron, matching that former
+ * module's original dependency-injection pattern.
+ */
+function registerAdminRoute(adminHttp, remote) {
+  adminHttp.registerRoute('POST', '/admin/scheduler/create-prd', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+      return;
+    }
+
+    let input;
+    try {
+      input = schemas.schedulerCreatePrd.parse(parsed);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: 'invalid PRD payload', details: e?.issues ?? e?.message });
+      return;
+    }
+
+    // cwd is untrusted: this is the first *creating* mutation on a
+    // token-authed API whose product is "a command that will later run
+    // with --dangerously-skip-permissions in a chosen cwd". Route it
+    // through config.cjs's validatePath (allowedRoots = home dir) —
+    // same boundary every other fs-touching IPC handler uses — never a
+    // bespoke check here.
+    try {
+      config.validatePath(expandHome(input.cwd));
+    } catch (e) {
+      sendJson(res, 400, { ok: false, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` });
+      return;
+    }
+
+    const slug = input.slug || deriveSlugFromTitle(input.title);
+    if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
+      sendJson(res, 400, { ok: false, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' });
+      return;
+    }
+
+    // NN allocation is delegated to allocateParallelGroup() (PRD 548) via
+    // the injected remote — never re-derived here — unless the caller
+    // opted into an existing group explicitly.
+    const nn = input.parallelGroup ?? await remote.allocateParallelGroup();
+    const filenameSlug = `${nn}-${slug}`;
+
+    // An explicit `parallelGroup` bypasses allocateParallelGroup()'s
+    // collision-proof reservation, so re-check for an existing file at
+    // this exact destination before writing — remote.writePrd itself has
+    // no existence guard (by design, it doubles as the edit-in-place
+    // path for Scheduler UI PRD edits), so "create" must not silently
+    // clobber an existing job's PRD.
+    const existing = await remote.readPrd(filenameSlug);
+    if (existing?.ok) {
+      sendJson(res, 409, { ok: false, error: `PRD already exists: ${filenameSlug}.md` });
+      return;
+    }
+
+    const body = buildPrdBody(input);
+    const writeResult = await remote.writePrd(filenameSlug, body);
+    if (!writeResult?.ok) {
+      sendJson(res, 500, { ok: false, error: writeResult?.error ?? 'write failed' });
+      return;
+    }
+
+    sendJson(res, 200, { nn, filename: `${filenameSlug}.md`, status: 'queued' });
+  });
+}
+
 module.exports = {
   PRD_CREATE_SLUG_RE,
   STANDARDS_PATH,
   readStandards,
   deriveSlugFromTitle,
   buildPrdBody,
+  registerAdminRoute,
 };