@polderlabs/bizar 8.1.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/routes/fs.mjs

@@ -0,0 +1,429 @@
+/**
+ * src/server/routes/fs.mjs
+ *
+ * GET  /api/fs?path=<absolute>            — list directory entries
+ * POST /api/fs/mkdir                      — create a new subdirectory
+ *
+ * Read-only filesystem browser for the Add Project dialog. The
+ * frontend passes an absolute path; the server resolves it against
+ * the allow-list (`os.homedir()` + the user's configured
+ * `dashboard.projectsDirectory` + each entry in
+ * `dashboard.allowedRoots`) and returns the immediate children.
+ *
+ * Security boundaries:
+ *   - Only absolute, resolved paths under an allowed root are
+ *     honoured. Anything else returns 403.
+ *   - First-level dotdirs under home (`.ssh`, `.aws`, `.gnupg`,
+ *     …) are silently skipped in listings and refused as roots.
+ *   - The GET endpoint never writes to disk. The POST endpoint
+ *     creates exactly one new directory; nothing else.
+ *   - All filesystem errors map to structured JSON, never an
+ *     unhandled exception.
+ *   - GET responses are capped at `MAX_ENTRIES` so a directory
+ *     with millions of children (a `node_modules` clone, a Go
+ *     module cache) cannot OOM the browser.
+ */
+import { Router } from 'express';
+import { mkdir, readdir, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { wrap, readSettings } from './_shared.mjs';
+import {
+  resolveSafePath,
+  buildAllowedRootsFromSettings,
+} from '../lib/path-safe.mjs';
+
+/**
+ * v3.11.0 — Hard cap on the number of entries returned by GET
+ * /api/fs. Sliced (not paginated) to keep the response shape
+ * stable and the round-trip cheap; the client gets a `truncated`
+ * flag so it can show "showing 500 of N" feedback.
+ */
+const MAX_ENTRIES = 500;
+
+/**
+ * v3.11.0 — Hard cap on the new-directory name length. 255 chars
+ * matches the typical ext4/NTFS max-component limit; longer names
+ * are almost certainly a bug or an attack.
+ */
+const MAX_NAME_LENGTH = 255;
+
+/**
+ * Build the per-request allow-list. We always include `os.homedir()`,
+ * and additionally include every entry in `settings.dashboard.allowedRoots`
+ * plus `settings.dashboard.projectsDirectory` — but only after
+ * re-validating each one against home so a tampered settings file
+ * can't widen the boundary.
+ *
+ * @returns {string[]}
+ */
+function buildAllowedRoots() {
+  const settings = readSettings();
+  return buildAllowedRootsFromSettings({
+    settings: settings.data,
+    home: homedir(),
+  });
+}
+
+/**
+ * Decide whether a given directory entry should be visible to the
+ * file browser. We hide dotfiles / dotdirs at every depth — keeps
+ * the browser focused on real user-visible projects and prevents
+ * accidental click-throughs into things like `node_modules/.cache`.
+ *
+ * (Dotdir *roots* under home are blocked at a different layer by
+ * resolveSafePath; this is the in-listing filter.)
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isHiddenEntry(name) {
+  return typeof name === 'string' && name.startsWith('.');
+}
+
+/**
+ * Sort entries: directories first (case-insensitive), then files
+ * (case-insensitive). Stable for ties.
+ *
+ * @param {{ isDir: boolean, name: string }[]} entries
+ */
+function sortEntries(entries) {
+  return [...entries].sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+  });
+}
+
+/**
+ * v3.11.0 — Validate a new-directory name. Defense in depth: the
+ * frontend should validate too, but the server is the boundary.
+ *
+ * Returns `null` on success, or a human-readable error message on
+ * failure. Designed to surface as `400 { error: "bad_request",
+ * message }` to the client.
+ *
+ * Rules:
+ *   - must be a non-empty string
+ *   - length 1..255
+ *   - must NOT be `.` or `..`
+ *   - must NOT start with `-` (could be confused with a CLI flag)
+ *   - must NOT contain `/`, `\`, NUL, `:`, `*`, `?`, `"`, `<`, `>`, `|`
+ *
+ * @param {unknown} name
+ * @returns {string | null}
+ */
+function validateDirName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return 'name is required';
+  }
+  if (name.length > MAX_NAME_LENGTH) {
+    return `name is too long (max ${MAX_NAME_LENGTH} characters)`;
+  }
+  if (name === '.' || name === '..') {
+    return 'name may not be "." or ".."';
+  }
+  if (name.startsWith('-')) {
+    return 'name may not start with "-"';
+  }
+  // Denylist of characters that have a special meaning on the shell,
+  // Windows, or POSIX paths. Listed as discrete substrings (some are
+  // multi-character escapes) for an explicit denylist with clear
+  // error messages.
+  const denylist = ['/', '\\', '\0', ':', '*', '?', '"', '<', '>', '|'];
+  for (const c of denylist) {
+    if (name.includes(c)) {
+      return `name may not contain "${c}"`;
+    }
+  }
+  return null;
+}
+
+/**
+ * v3.11.0 — Build the absolute path of the would-be new directory,
+ * verifying it remains inside the allow-list. A symlink or
+ * pre-existing weirdness in the parent could in principle make
+ * `path.join` produce a target that escapes; the re-check is
+ * cheap and prevents the race.
+ *
+ * @param {string} safeParent
+ * @param {string} name
+ * @param {string[]} allowedRoots
+ * @returns {string | null}
+ */
+function resolveTargetUnderParent(safeParent, name, allowedRoots) {
+  const target = join(safeParent, name);
+  return resolveSafePath(target, allowedRoots);
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.state
+ * @returns {import('express').Router}
+ */
+export function createFsRouter({ state }) {
+  const router = Router();
+
+  router.get('/fs', wrap(async (req, res) => {
+    const requested = typeof req.query.path === 'string' ? req.query.path : '';
+    const allowedRoots = buildAllowedRoots();
+    const safe = resolveSafePath(requested, allowedRoots);
+    if (!safe) {
+      res.status(403).json({
+        error: 'forbidden',
+        message: 'path is outside the allowed roots (home + dashboard.projectsDirectory + dashboard.allowedRoots)',
+      });
+      return;
+    }
+
+    let dirStat;
+    try {
+      dirStat = await stat(safe);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        res.status(404).json({ error: 'not_found' });
+        return;
+      }
+      if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+        res.status(403).json({ error: 'permission_denied' });
+        return;
+      }
+      throw err;
+    }
+
+    if (!dirStat.isDirectory()) {
+      res.status(400).json({ error: 'not_a_directory' });
+      return;
+    }
+
+    let dirents;
+    try {
+      dirents = await readdir(safe, { withFileTypes: true });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        res.status(404).json({ error: 'not_found' });
+        return;
+      }
+      if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+        res.status(403).json({ error: 'permission_denied' });
+        return;
+      }
+      throw err;
+    }
+
+    const entries = [];
+    for (const dirent of dirents) {
+      const name = dirent.name;
+      // Hide dotfile / dotdir entries at every depth.
+      if (isHiddenEntry(name)) continue;
+      const sep = safe.includes('\\') && !safe.includes('/') ? '\\' : '/';
+      const entryPath = safe.endsWith(sep) ? safe + name : safe + sep + name;
+      // Defaults — used when stat fails. dirent.isDirectory() is a
+      // cheap, reliable indicator that does not require an extra
+      // syscall, so prefer it for isDir.
+      let isDir = dirent.isDirectory();
+      let isSymlink = dirent.isSymbolicLink();
+      try {
+        // Follow the symlink (if any) so the user can see whether
+        // it resolves to a real directory.
+        const s = await stat(entryPath);
+        if (s.isDirectory()) isDir = true;
+        if (s.isSymbolicLink()) isSymlink = true;
+      } catch {
+        // Best-effort. Common cases:
+        //  - EACCES on a sibling we can't stat (parent only readable
+        //    to us, entry mode 000). Trust the dirent.
+        //  - ENOENT means the entry disappeared between readdir and
+        //    stat (rare race). Drop it.
+        if (dirent.isSymbolicLink() && !isDir) {
+          // Symlink whose target we can't read — show it as a
+          // symlink, not a directory, so the user knows to be
+          // careful before entering.
+          isDir = false;
+        }
+      }
+      entries.push({ name, path: entryPath, isDir, isSymlink });
+    }
+
+    const sorted = sortEntries(entries);
+    const totalEntries = sorted.length;
+    // v3.11.0 — Cap the response so a 50k-entry `node_modules`
+    // clone cannot OOM the browser. We always include the
+    // `truncated` flag (and `totalEntries`) for type stability —
+    // the client can rely on the shape even when no truncation
+    // happened.
+    const truncated = totalEntries > MAX_ENTRIES;
+    const capped = truncated ? sorted.slice(0, MAX_ENTRIES) : sorted;
+    const parent = dirname(safe);
+    // The "parent" we return should be null when we're already at
+    // the filesystem root — Express/Node will give us '/' there.
+    const isRoot = parent === safe;
+    res.json({
+      path: safe,
+      parent: isRoot ? null : parent,
+      entries: capped,
+      truncated,
+      totalEntries,
+    });
+  }));
+
+  /**
+   * v3.11.0 — Create a new directory. This is the FIRST write
+   * endpoint in the file-browser surface, so it is paranoid about
+   * race conditions: check-then-create (EEXIST → 409), and
+   * validate the result via `stat` after creation.
+   *
+   * Auth: mounted under `/api`, so `requireAuth` in server.mjs
+   * gates this automatically.
+   *
+   * Rate limiting: not yet implemented at the server side. The
+   * frontend should debounce the click. Follow-up: add a per-IP
+   * token bucket if abuse becomes a concern.
+   */
+  router.post('/fs/mkdir', wrap(async (req, res) => {
+    const parent = typeof req.body?.parent === 'string' ? req.body.parent : '';
+    const name = typeof req.body?.name === 'string' ? req.body.name : '';
+
+    if (!parent) {
+      res.status(400).json({
+        error: 'bad_request',
+        message: 'parent is required',
+      });
+      return;
+    }
+
+    const allowedRoots = buildAllowedRoots();
+
+    // 1. Parent must be inside the allow-list.
+    const safeParent = resolveSafePath(parent, allowedRoots);
+    if (!safeParent) {
+      res.status(403).json({
+        error: 'forbidden',
+        message: 'parent is outside the allowed roots',
+      });
+      return;
+    }
+
+    // 2. Name must pass the denylist validation.
+    const nameError = validateDirName(name);
+    if (nameError) {
+      res.status(400).json({ error: 'bad_request', message: nameError });
+      return;
+    }
+
+    // 3. Compute target and re-validate it is in the allow-list
+    //    (defense against symlinks or pre-existing weirdness in
+    //    the parent).
+    const safeTarget = resolveTargetUnderParent(safeParent, name, allowedRoots);
+    if (!safeTarget) {
+      res.status(403).json({
+        error: 'forbidden',
+        message: 'target is outside the allowed roots',
+      });
+      return;
+    }
+
+    // 4. Parent must exist and be a directory.
+    let parentStat;
+    try {
+      parentStat = await stat(safeParent);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        res.status(404).json({ error: 'not_found', message: 'parent does not exist' });
+        return;
+      }
+      if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+        res.status(403).json({ error: 'permission_denied' });
+        return;
+      }
+      throw err;
+    }
+    if (!parentStat.isDirectory()) {
+      res.status(400).json({ error: 'not_a_directory' });
+      return;
+    }
+
+    // 5. Pre-check existence (best-effort; EEXIST from mkdir is
+    //    authoritative).
+    try {
+      await stat(safeTarget);
+      res.status(409).json({
+        error: 'already_exists',
+        message: `an entry named "${name}" already exists in this directory`,
+      });
+      return;
+    } catch (err) {
+      if (err && err.code !== 'ENOENT') throw err;
+      // ENOENT is the expected "good to go" case.
+    }
+
+    // 6. Create the directory. recursive:false — we want a flat
+    //    one-level create, never a multi-level path.
+    try {
+      await mkdir(safeTarget, { recursive: false });
+    } catch (err) {
+      if (err && err.code === 'EEXIST') {
+        // Race: someone else created the dir between our stat
+        // and our mkdir. Surface as 409.
+        res.status(409).json({
+          error: 'already_exists',
+          message: `an entry named "${name}" already exists in this directory`,
+        });
+        return;
+      }
+      if (err && (err.code === 'EACCES' || err.code === 'EPERM')) {
+        res.status(403).json({
+          error: 'permission_denied',
+          message: err.message,
+        });
+        return;
+      }
+      if (err && err.code === 'ENOSPC') {
+        res.status(500).json({
+          error: 'mkdir_failed',
+          message: 'no space left on device',
+        });
+        return;
+      }
+      res.status(500).json({
+        error: 'mkdir_failed',
+        message: err?.message || String(err),
+      });
+      return;
+    }
+
+    // 7. Verify the result via stat. Catches a vanishingly rare
+    //    race where something removed the dir between mkdir and
+    //    stat, and any other weirdness (e.g. EPERM on a follow-up
+    //    stat due to a mode change).
+    let createdStat;
+    try {
+      createdStat = await stat(safeTarget);
+    } catch (err) {
+      res.status(500).json({
+        error: 'mkdir_verify_failed',
+        message: err?.message || String(err),
+      });
+      return;
+    }
+    if (!createdStat.isDirectory()) {
+      res.status(409).json({
+        error: 'already_exists',
+        message: `an entry named "${name}" is no longer a directory`,
+      });
+      return;
+    }
+
+    res.status(201).json({
+      path: safeTarget,
+      parent: safeParent,
+      name,
+    });
+  }));
+
+  // Keep `state` referenced so this router follows the same factory
+  // signature as the others (settings/overview/etc.). Future fs
+  // operations may broadcast state changes.
+  void state;
+
+  return router;
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/server/routes/goal-planner.mjs

@@ -0,0 +1,236 @@
+/**
+ * src/server/routes/goal-planner.mjs
+ *
+ * v6.4.0 — F-036 (Goal Planner UI).
+ *
+ * Single endpoint:
+ *   POST /api/goal-planner/plan { goal } -> Plan
+ *
+ * The planner logic is duplicated here in pure JS so the route
+ * runs without a Vite build step. The canonical implementation
+ * lives in `bizar-dash/src/web/lib/goapPlanner.ts` and produces
+ * the same shape.
+ */
+import { Router } from 'express';
+import { wrap } from './_shared.mjs';
+
+const VERB_TO_ACTION = {
+  research: { name: 'research', cost: 1, agent: 'Odin', effect: 'context_gathered', description: 'Gather context, examples, and prior art.' },
+  investigate: { name: 'research', cost: 1, agent: 'Odin', effect: 'context_gathered', description: 'Probe the unknown regions of the problem.' },
+  explore: { name: 'research', cost: 1, agent: 'Odin', effect: 'context_gathered', description: 'Map the solution space.' },
+  find: { name: 'research', cost: 1, agent: 'Odin', effect: 'context_gathered', description: 'Locate references and prior work.' },
+  analyze: { name: 'analyze', cost: 1, agent: 'Odin', effect: 'goal_analyzed', preconditions: ['context_gathered'], description: 'Decompose the goal into measurable sub-objectives.' },
+  plan: { name: 'plan', cost: 1, agent: 'Odin', effect: 'plan_drafted', preconditions: ['goal_analyzed'], description: 'Sequence the work into milestones.' },
+  design: { name: 'design', cost: 2, agent: 'Tyr', effect: 'design_drafted', preconditions: ['plan_drafted'], description: 'Sketch the architecture and contracts.' },
+  architect: { name: 'design', cost: 2, agent: 'Tyr', effect: 'design_drafted', preconditions: ['plan_drafted'], description: 'Lay out the system structure.' },
+  build: { name: 'build', cost: 3, agent: 'Thor', effect: 'artifact_built', preconditions: ['design_drafted'], description: 'Construct the artifact end-to-end.' },
+  implement: { name: 'implement', cost: 3, agent: 'Thor', effect: 'artifact_built', preconditions: ['design_drafted'], description: 'Wire up the code path.' },
+  create: { name: 'implement', cost: 3, agent: 'Thor', effect: 'artifact_built', preconditions: ['design_drafted'], description: 'Stand up the new module.' },
+  add: { name: 'implement', cost: 2, agent: 'Thor', effect: 'artifact_built', preconditions: ['design_drafted'], description: 'Layer the new capability onto an existing surface.' },
+  write: { name: 'implement', cost: 2, agent: 'Thor', effect: 'artifact_built', description: 'Author the requested artifact.' },
+  fix: { name: 'implement', cost: 2, agent: 'Thor', effect: 'artifact_built', description: 'Repair the reported defect.' },
+  refactor: { name: 'implement', cost: 2, agent: 'Thor', effect: 'artifact_built', description: 'Improve the structure without changing behavior.' },
+  test: { name: 'test', cost: 2, agent: 'Forseti', effect: 'tests_passing', preconditions: ['artifact_built'], description: 'Exercise the artifact against acceptance criteria.' },
+  verify: { name: 'test', cost: 1, agent: 'Forseti', effect: 'tests_passing', preconditions: ['artifact_built'], description: 'Validate against the original goal statement.' },
+  validate: { name: 'test', cost: 1, agent: 'Forseti', effect: 'tests_passing', preconditions: ['artifact_built'], description: 'Cross-check the result against acceptance criteria.' },
+  review: { name: 'review', cost: 1, agent: 'Forseti', effect: 'review_passed', preconditions: ['artifact_built'], description: 'Audit the change for quality and regressions.' },
+  document: { name: 'document', cost: 1, agent: 'Bragi', effect: 'docs_written', preconditions: ['artifact_built'], description: 'Capture the new knowledge in docs.' },
+  deploy: { name: 'deploy', cost: 2, agent: 'Heimdall', effect: 'deployed', preconditions: ['tests_passing', 'review_passed'], description: 'Promote the artifact to production.' },
+  ship: { name: 'deploy', cost: 2, agent: 'Heimdall', effect: 'deployed', preconditions: ['tests_passing', 'review_passed'], description: 'Release the change to users.' },
+  release: { name: 'deploy', cost: 2, agent: 'Heimdall', effect: 'deployed', preconditions: ['tests_passing', 'review_passed'], description: 'Tag and publish a new version.' },
+  publish: { name: 'deploy', cost: 1, agent: 'Heimdall', effect: 'deployed', preconditions: ['tests_passing'], description: 'Make the artifact externally available.' },
+  commit: { name: 'commit', cost: 1, agent: 'Hermod', effect: 'committed', description: 'Land the change in version control.' },
+  save: { name: 'commit', cost: 1, agent: 'Hermod', effect: 'committed', description: 'Persist the work.' },
+};
+
+const DURATION_MS = {
+  research: 30000, analyze: 20000, plan: 25000, design: 60000,
+  build: 120000, implement: 90000, test: 60000, review: 30000,
+  document: 30000, deploy: 60000, commit: 10000,
+};
+
+const FALLBACK = { name: 'research', cost: 1, agent: 'Odin', effect: 'context_gathered', description: 'Investigate the goal.' };
+
+function splitClauses(text) {
+  // Split on terminal punctuation, conjunctions (then/after/before/and
+  // then), AND commas / the word "and" so that "Design, build, test,
+  // and deploy" produces 4 clauses.
+  const parts = text.split(/[.;!?\n]|\bthen\b|\bafter that\b|\bafter\b|\bbefore\b|\band then\b|\s*,\s*|\band\b/gi);
+  const out = [];
+  for (const part of parts) {
+    const t = part.trim();
+    if (!t) continue;
+    if (!/^[a-zA-Z]+\b/.test(t) && t.includes(',')) {
+      for (const sub of t.split(',')) {
+        const s = sub.trim();
+        if (s) out.push(s);
+      }
+    } else {
+      out.push(t);
+    }
+  }
+  return out;
+}
+
+function stripPolite(body) {
+  let out = body;
+  for (let i = 0; i < 4; i++) {
+    const before = out;
+    out = out.replace(/^(?:please\s+|kindly\s+)/i, '');
+    out = out.replace(/^(?:we should|let's|lets|i want to|i need to|i'd like to|i would like to|can you|could you|would you|help me|help us|make sure to|please)\s+/i, '');
+    if (out === before) break;
+  }
+  return out;
+}
+
+function extractVerb(clause) {
+  const body = stripPolite(clause.trim());
+  const first = (body.split(/\s+/)[0] || '').toLowerCase().replace(/[^a-z]/g, '');
+  return first;
+}
+
+function clauseSubject(clause) {
+  const body = stripPolite(clause.trim());
+  const stripped = body.replace(/^[a-zA-Z]+\s+/, '').trim();
+  return stripped.length > 0 ? stripped : clause;
+}
+
+function aStar(actions, goals) {
+  const goalSet = new Set(goals);
+  if (goalSet.size === 0) return actions.slice(0, 1);
+  const heur = (s) => {
+    let u = 0;
+    for (const g of goalSet) if (!s.has(g)) u++;
+    return u;
+  };
+  const keyOf = (s) => Array.from(s).sort().join('|') || 'empty';
+  const start = { sat: new Set(), path: [], cost: 0 };
+  const open = [start];
+  const closed = new Set();
+  let best = start;
+  while (open.length) {
+    open.sort((a, b) => (a.cost + heur(a.sat)) - (b.cost + heur(b.sat)));
+    const node = open.shift();
+    if (heur(node.sat) === 0) return node.path;
+    if (heur(node.sat) < heur(best.sat)) best = node;
+    const k = keyOf(node.sat);
+    if (closed.has(k)) continue;
+    closed.add(k);
+    for (const a of actions) {
+      const pre = a.preconditions || [];
+      if (!pre.every((p) => node.sat.has(p))) continue;
+      const next = new Set(node.sat);
+      next.add(a.effect);
+      open.push({ sat: next, path: [...node.path, a], cost: node.cost + a.cost });
+    }
+  }
+  return best.path;
+}
+
+function inlinePlan(goalText) {
+  const id = `plan_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+  const clauses = splitClauses(goalText);
+  const effective = clauses.length > 0 ? clauses : [(goalText || 'Investigate the goal').trim()];
+  const rawTemplates = effective.map((c) => VERB_TO_ACTION[extractVerb(c)] || FALLBACK);
+  const subjects = effective.map(clauseSubject);
+  const seen = new Set();
+  const dedup = [];
+  for (let i = 0; i < rawTemplates.length; i++) {
+    const t = rawTemplates[i];
+    const s = subjects[i] || `step ${i + 1}`;
+    const sig = `${t.name}::${s.toLowerCase().slice(0, 40)}`;
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    dedup.push({ template: t, subject: s });
+  }
+  const trimmed = dedup.slice(0, 8);
+  const goalEffects = trimmed.map((d) => d.template.effect);
+  const sequence = aStar(trimmed.map((d) => d.template), goalEffects);
+  const idByEffect = new Map();
+  const steps = [];
+  let n = 0;
+  for (const tpl of sequence) {
+    const match = trimmed.find((s) => s.template === tpl);
+    if (!match) continue;
+    n += 1;
+    const sid = `s${n}`;
+    const deps = [];
+    for (const p of tpl.preconditions || []) {
+      const pid = idByEffect.get(p);
+      if (pid) deps.push(pid);
+    }
+    const title = match.subject.charAt(0).toUpperCase() + match.subject.slice(1);
+    steps.push({
+      id: sid,
+      action: tpl.name,
+      title: title.length > 0 ? title : tpl.name,
+      agent: tpl.agent,
+      description: tpl.description,
+      effects: [tpl.effect],
+      deps,
+      status: 'pending',
+      estimatedCost: tpl.cost,
+      estimatedDurationMs: DURATION_MS[tpl.name] || 30000,
+    });
+    idByEffect.set(tpl.effect, sid);
+  }
+  if (steps.length === 0 && trimmed.length > 0) {
+    let idx = 0;
+    for (const { template, subject } of trimmed) {
+      idx += 1;
+      const sid = `s${idx}`;
+      const deps = [];
+      for (const p of template.preconditions || []) {
+        const pid = idByEffect.get(p);
+        if (pid) deps.push(pid);
+      }
+      const title = subject.charAt(0).toUpperCase() + subject.slice(1);
+      steps.push({
+        id: sid,
+        action: template.name,
+        title: title.length > 0 ? title : template.name,
+        agent: template.agent,
+        description: template.description,
+        effects: [template.effect],
+        deps,
+        status: 'pending',
+        estimatedCost: template.cost,
+        estimatedDurationMs: DURATION_MS[template.name] || 30000,
+      });
+      idByEffect.set(template.effect, sid);
+    }
+  }
+  const totalCost = steps.reduce((sum, s) => sum + s.estimatedCost, 0);
+  const totalDurationMs = steps.reduce((sum, s) => sum + s.estimatedDurationMs, 0);
+  return { id, goal: goalText, steps, totalCost, totalDurationMs, goalEffects };
+}
+
+function readGoal(body) {
+  const raw = body && body.goal;
+  if (typeof raw !== 'string' || !raw.trim()) {
+    const err = new Error('goal (non-empty string) is required');
+    err.status = 400;
+    err.code = 'bad_request';
+    throw err;
+  }
+  if (raw.length > 4000) {
+    const err = new Error('goal must be 4000 chars or fewer');
+    err.status = 400;
+    err.code = 'bad_request';
+    throw err;
+  }
+  return raw.trim();
+}
+
+export function createGoalPlannerRouter({ broadcast } = {}) {
+  const router = Router();
+  router.post('/goal-planner/plan', wrap(async (req, res) => {
+    const goal = readGoal(req.body);
+    const plan = inlinePlan(goal);
+    if (broadcast) {
+      try { broadcast({ type: 'goal:planned', planId: plan.id, goal }); } catch { /* best-effort */ }
+    }
+    res.json(plan);
+  }));
+  return router;
+}