@hienlh/ppm 0.22.10 → 0.23.0

package/src/services/design/design-lock.ts

@@ -0,0 +1,74 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { resolve } from "node:path";
+
+/**
+ * One in-process mutex per design (`projectPath::slug`). Every operation that reads and
+ * then rewrites a design's files or its `.design/` data — snapshot, restore, manifest
+ * rename, comments, canvas write-backs — runs inside it, so a turn snapshot can never copy
+ * a tree a restore is halfway through replacing.
+ *
+ * Entries are dropped once their chain settles with nobody waiting, so a long-running
+ * server holds one entry per design currently in use rather than one per design ever
+ * touched.
+ *
+ * Reentrant within one async call chain: a caller already holding the lock (a canvas
+ * write-back taking its `before-edit` snapshot) runs straight through instead of queueing
+ * behind itself forever.
+ */
+
+interface LockEntry {
+  tail: Promise<void>;
+  holders: number;
+}
+
+const locks = new Map<string, LockEntry>();
+const held = new AsyncLocalStorage<ReadonlySet<string>>();
+
+/** Canonical key; case-folded on Windows, where two spellings name one folder. */
+export function designLockKey(projectPath: string, slug: string): string {
+  const project = resolve(projectPath);
+  return `${process.platform === "win32" ? project.toLowerCase() : project}::${slug}`;
+}
+
+export async function withDesignLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const current = held.getStore();
+  if (current?.has(key)) return fn();
+
+  let entry = locks.get(key);
+  if (!entry) {
+    entry = { tail: Promise.resolve(), holders: 0 };
+    locks.set(key, entry);
+  }
+  entry.holders++;
+  const previous = entry.tail;
+  let release!: () => void;
+  const mine = new Promise<void>((r) => {
+    release = r;
+  });
+  entry.tail = previous.then(() => mine);
+
+  try {
+    await previous;
+    const next = new Set(current ?? []);
+    next.add(key);
+    return await held.run(next, fn);
+  } finally {
+    release();
+    entry.holders--;
+    if (entry.holders === 0 && locks.get(key) === entry) locks.delete(key);
+  }
+}
+
+/**
+ * Run `fn` as if no design lock were held. Reentrancy follows the async context, and a
+ * timer inherits the context it was created in, so deferred work (a debounced snapshot)
+ * scheduled from inside a lock would otherwise skip the queue when it fires later.
+ */
+export function detachFromDesignLocks<T>(fn: () => T): T {
+  return held.exit(fn);
+}
+
+/** Number of designs with a live lock entry; exposed for leak tests. */
+export function activeDesignLockCount(): number {
+  return locks.size;
+}

package/src/services/design/design-manifest.ts

@@ -0,0 +1,92 @@
+import { isDesignKind, type DesignKind } from "../../shared/design-types.ts";
+
+/**
+ * `designs/<slug>/design.json`. The agent edits this file too (it declares `tweaks` there),
+ * so parsing is tolerant: known fields are validated and fall back to defaults one by one,
+ * and every field this module does not own is carried through verbatim, so a rename never
+ * drops what the agent or a later feature wrote.
+ */
+
+export const MANIFEST_FILE = "design.json";
+export const DEFAULT_ENTRY = "index.html";
+export const MAX_TITLE_LENGTH = 120;
+
+export interface DesignManifest {
+  title: string;
+  kind: DesignKind;
+  entry: string;
+  createdAt: string;
+  updatedAt: string;
+  /** Every other top-level field, `tweaks` included, kept as found. */
+  extra: Record<string, unknown>;
+}
+
+const OWN_FIELDS = new Set(["title", "kind", "entry", "createdAt", "updatedAt"]);
+
+/** Trimmed, control characters removed, at most {@link MAX_TITLE_LENGTH}; null when empty. */
+export function normalizeTitle(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const title = value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (!title) return null;
+  return Array.from(title).slice(0, MAX_TITLE_LENGTH).join("");
+}
+
+/**
+ * An entry is a relative `.html`/`.htm` path inside the design, built from plain segments.
+ * No `..`, no leading dot segment (that would reach `.design/`), no separators other than `/`.
+ */
+export function isSafeEntry(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > 200) return false;
+  if (!/\.html?$/i.test(value)) return false;
+  return value.split("/").every((seg) => /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(seg));
+}
+
+function isIsoDate(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 40 && !Number.isNaN(Date.parse(value));
+}
+
+export interface ParsedManifest {
+  manifest: DesignManifest;
+  /** False when the file was missing, not JSON, or not an object; the manifest is then all defaults. */
+  valid: boolean;
+}
+
+export function parseManifest(raw: string | null, fallback: { slug: string; now: string }): ParsedManifest {
+  let data: unknown = null;
+  if (raw !== null) {
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      data = null;
+    }
+  }
+  const valid = typeof data === "object" && data !== null && !Array.isArray(data);
+  const obj: Record<string, unknown> = valid ? (data as Record<string, unknown>) : {};
+  const extra: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!OWN_FIELDS.has(key)) extra[key] = value;
+  }
+  const createdAt = isIsoDate(obj.createdAt) ? obj.createdAt : fallback.now;
+  return {
+    valid,
+    manifest: {
+      title: normalizeTitle(obj.title) ?? fallback.slug,
+      kind: isDesignKind(obj.kind) ? obj.kind : "page",
+      entry: isSafeEntry(obj.entry) ? obj.entry : DEFAULT_ENTRY,
+      createdAt,
+      updatedAt: isIsoDate(obj.updatedAt) ? obj.updatedAt : createdAt,
+      extra,
+    },
+  };
+}
+
+export function serializeManifest(manifest: DesignManifest): string {
+  const { extra, ...own } = manifest;
+  return `${JSON.stringify({ ...own, ...withoutOwnFields(extra) }, null, 2)}\n`;
+}
+
+function withoutOwnFields(extra: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(extra)) if (!OWN_FIELDS.has(key)) out[key] = value;
+  return out;
+}

package/src/services/design/design-paths.ts

@@ -0,0 +1,97 @@
+import { join, resolve } from "node:path";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { assertAllowed, assertNotPpmDir } from "../fs-path-guard.service.ts";
+import { isInsideDir } from "../fs-ops/fs-real-path.ts";
+import { isValidDesignSlug } from "./design-slug.ts";
+import { DesignError } from "./design-error.ts";
+
+/** Folder under the project root that holds every design and the shared design system. */
+export const DESIGNS_DIR = "designs";
+/** Per-design working data (snapshots, comments, restore journal). Never part of the design. */
+export const DOT_DESIGN = ".design";
+
+/** `<project>/designs`, lexically. Use {@link resolveDesignsRoot} before touching the disk. */
+export function designsRoot(projectPath: string): string {
+  return join(resolve(projectPath), DESIGNS_DIR);
+}
+
+/** lstat that answers null for "not there" instead of throwing. */
+export async function lstatOrNull(path: string): Promise<Stats | null> {
+  try {
+    return await lstat(path);
+  } catch (e) {
+    const code = (e as { code?: string }).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return null;
+    throw e;
+  }
+}
+
+const refuse = (message: string): DesignError => new DesignError(403, "EDESIGNPATH", message);
+
+/**
+ * `designs/` resolved to its real path, or null when it does not exist yet.
+ *
+ * A symlinked `designs/` is refused outright rather than followed: every design path is
+ * built from it, so a link there would silently move every read, write, snapshot and
+ * delete to wherever it points — including the PPM directory.
+ */
+export async function resolveDesignsRoot(projectPath: string, opts: { create?: boolean } = {}): Promise<string | null> {
+  const project = resolve(projectPath);
+  assertAllowed(project);
+  const root = designsRoot(project);
+  assertNotPpmDir(root);
+  let st = await lstatOrNull(root);
+  if (!st && opts.create) {
+    // Non-recursive on purpose: the project folder exists, and a recursive mkdir can throw
+    // EEXIST on Windows folders carrying the read-only attribute.
+    try {
+      await mkdir(root);
+    } catch (e) {
+      if ((e as { code?: string }).code !== "EEXIST") throw e;
+    }
+    st = await lstatOrNull(root);
+  }
+  if (!st) return null;
+  if (st.isSymbolicLink() || !st.isDirectory()) throw refuse(`${DESIGNS_DIR}/ must be a real directory`);
+  const [realProject, realRoot] = await Promise.all([realpath(project), realpath(root)]);
+  if (!isInsideDir(realRoot, realProject)) throw refuse(`${DESIGNS_DIR}/ resolves outside the project`);
+  assertNotPpmDir(realRoot);
+  return realRoot;
+}
+
+/**
+ * Absolute real path of `designs/<slug>/`, after validating the slug, refusing a symlinked
+ * `designs/` or design folder, and checking realpath containment plus the credential guard.
+ *
+ * `mustExist: false` returns the would-be path of a design that does not exist yet (used by
+ * creation), still under the same checks for everything that does exist.
+ */
+export async function resolveDesignDir(
+  projectPath: string,
+  slug: string,
+  opts: { mustExist?: boolean } = {},
+): Promise<string> {
+  const mustExist = opts.mustExist ?? true;
+  if (!isValidDesignSlug(slug)) throw new DesignError(400, "EBADSLUG", "Invalid design slug");
+  const root = await resolveDesignsRoot(projectPath, { create: !mustExist });
+  const notFound = new DesignError(404, "ENOENT", `Design not found: ${slug}`);
+  if (!root) throw notFound;
+  const dir = join(root, slug);
+  const st = await lstatOrNull(dir);
+  if (!st) {
+    if (mustExist) throw notFound;
+    return dir;
+  }
+  if (st.isSymbolicLink()) throw refuse("A design folder may not be a symlink");
+  if (!st.isDirectory()) throw mustExist ? notFound : refuse(`${DESIGNS_DIR}/${slug} is not a directory`);
+  const real = await realpath(dir);
+  if (real === root || !isInsideDir(real, root)) throw refuse("Design folder resolves outside designs/");
+  assertNotPpmDir(real);
+  return real;
+}
+
+/** `designs/<slug>/.design`, for a design dir already returned by {@link resolveDesignDir}. */
+export function dotDesignDir(designDir: string): string {
+  return join(designDir, DOT_DESIGN);
+}

package/src/services/design/design-restore-journal.ts

@@ -0,0 +1,143 @@
+import { readdir, readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isSnapshotId } from "../../shared/design-types.ts";
+import { DOT_DESIGN, dotDesignDir, lstatOrNull, resolveDesignDir } from "./design-paths.ts";
+import { writeFileAtomic } from "./design-fs.ts";
+import { designLockKey, withDesignLock } from "./design-lock.ts";
+
+/**
+ * The crash-safety half of restore.
+ *
+ * A restore replaces the design's working files with a snapshot's. It stages a full copy
+ * in `.design/tmp-<id>/`, records `.design/restore-journal.json`, and only then swaps:
+ *
+ *   staged   → the working tree is untouched; recovery discards the staged copy.
+ *   swapping → the working tree may be half replaced; recovery *finishes* the swap from
+ *              tmp, which by then is the only full copy of the target state, and is never
+ *              deleted before the swap completes.
+ *
+ * Both the live restore and recovery go through {@link completeSwap}, which is idempotent:
+ * each top-level entry is moved by one `rename`, so it sits either in tmp or in the working
+ * tree, and the journal's `names` (the staged top-level names) tells the two apart after a
+ * crash. A working entry that is also still in tmp is the old version; a staged name that
+ * is no longer in tmp has already been moved in and is kept.
+ */
+
+export const RESTORE_JOURNAL = "restore-journal.json";
+const TMP_PREFIX = "tmp-";
+
+export interface RestoreJournal {
+  id: string;
+  /** Staging directory name under `.design/`, always `tmp-<id>`. */
+  tmp: string;
+  phase: "staged" | "swapping";
+  /** Top-level entry names of the staged copy. */
+  names: string[];
+}
+
+/** Test seam: called after each durable step so a test can "crash" there by throwing. */
+export const restoreCrashPoints: { hit?: (step: string) => void } = {};
+
+export function crashPoint(step: string): void {
+  restoreCrashPoints.hit?.(step);
+}
+
+function isPlainName(name: unknown): name is string {
+  return typeof name === "string" && name.length > 0 && name.length <= 255
+    && name !== "." && name !== ".." && name !== DOT_DESIGN && !/[\\/\0]/.test(name);
+}
+
+function parseJournal(raw: string): RestoreJournal | null {
+  let data: Partial<RestoreJournal>;
+  try {
+    data = JSON.parse(raw) as Partial<RestoreJournal>;
+  } catch {
+    return null;
+  }
+  if (!data || !isSnapshotId(data.id) || data.tmp !== `${TMP_PREFIX}${data.id}`) return null;
+  if (data.phase !== "staged" && data.phase !== "swapping") return null;
+  if (!Array.isArray(data.names) || !data.names.every(isPlainName)) return null;
+  return { id: data.id, tmp: data.tmp, phase: data.phase, names: data.names };
+}
+
+export async function writeRestoreJournal(designDir: string, journal: RestoreJournal): Promise<void> {
+  await writeFileAtomic(join(dotDesignDir(designDir), RESTORE_JOURNAL), `${JSON.stringify(journal)}\n`);
+}
+
+/**
+ * Make the working tree equal the staged copy. Safe to call again after any crash inside
+ * it, and after it has fully completed.
+ */
+export async function completeSwap(designDir: string, journal: RestoreJournal): Promise<void> {
+  const tmpDir = join(dotDesignDir(designDir), journal.tmp);
+  const staged = new Set(journal.names);
+  const inTmp = new Set(await readdir(tmpDir).catch(() => [] as string[]));
+  for (const name of await readdir(designDir)) {
+    if (name === DOT_DESIGN) continue;
+    if (staged.has(name) && !inTmp.has(name)) continue; // already moved in by an earlier attempt
+    // rm removes a symlink itself, never what it points to.
+    await rm(join(designDir, name), { recursive: true, force: true });
+    crashPoint(`cleared:${name}`);
+  }
+  for (const name of [...inTmp].sort()) {
+    if (!staged.has(name)) continue; // not part of the staged copy; left for cleanup below
+    await rename(join(tmpDir, name), join(designDir, name));
+    crashPoint(`moved:${name}`);
+  }
+}
+
+/** Journal first, then the (now empty) staging dir: a crash between leaves only a stale tmp. */
+export async function finishRestore(designDir: string, journal: RestoreJournal): Promise<void> {
+  await rm(join(dotDesignDir(designDir), RESTORE_JOURNAL), { force: true });
+  await rm(join(dotDesignDir(designDir), journal.tmp), { recursive: true, force: true });
+}
+
+export type RecoveryOutcome = "none" | "discarded" | "completed";
+
+/**
+ * Bring a design back to a consistent state after a restore that did not finish. Runs at
+ * the start of every locked design operation, so the next snapshot, restore or edit after
+ * a crash sees either the old tree or the restored one — never a mix.
+ */
+export async function recoverRestoreJournal(designDir: string): Promise<RecoveryOutcome> {
+  const dot = dotDesignDir(designDir);
+  const dotSt = await lstatOrNull(dot);
+  if (!dotSt || dotSt.isSymbolicLink() || !dotSt.isDirectory()) return "none";
+  const journalPath = join(dot, RESTORE_JOURNAL);
+  const raw = (await lstatOrNull(journalPath))?.isFile() ? await readFile(journalPath, "utf8") : null;
+  const journal = raw === null ? null : parseJournal(raw);
+  if (journal?.phase === "swapping") {
+    await completeSwap(designDir, journal);
+    await finishRestore(designDir, journal);
+    console.warn(`[design] finished an interrupted restore of ${journal.id} in ${designDir}`);
+    return "completed";
+  }
+  if (raw !== null) {
+    if (!journal) console.warn(`[design] ignoring an unreadable restore journal in ${designDir}`);
+    await rm(journalPath, { force: true });
+  }
+  // Staged copies with no journal left to say they matter: a staged-phase crash, or a crash
+  // between removing a finished journal and its empty staging dir. `.tmp-` files are
+  // atomic writes (journal, manifest) cut short by a crash.
+  for (const name of await readdir(dot)) {
+    if (name.startsWith(TMP_PREFIX) || name.startsWith(".tmp-")) await rm(join(dot, name), { recursive: true, force: true });
+  }
+  return journal?.phase === "staged" ? "discarded" : "none";
+}
+
+/**
+ * Run `fn` on a design under its lock, after resolving (and guarding) its folder and
+ * recovering any interrupted restore. The entry point for every operation that modifies a
+ * design's files or its `.design/` data.
+ */
+export async function withRecoveredDesign<T>(
+  projectPath: string,
+  slug: string,
+  fn: (designDir: string) => Promise<T>,
+): Promise<T> {
+  return withDesignLock(designLockKey(projectPath, slug), async () => {
+    const designDir = await resolveDesignDir(projectPath, slug);
+    await recoverRestoreJournal(designDir);
+    return fn(designDir);
+  });
+}

package/src/services/design/design-restore.service.ts

@@ -0,0 +1,77 @@
+import { mkdir, readdir, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { isSnapshotId } from "../../shared/design-types.ts";
+import { ensureDotDesign } from "./design-fs.ts";
+import { DesignError } from "./design-error.ts";
+import { emitDesignEvent } from "./design-events.ts";
+import {
+  completeSwap, crashPoint, finishRestore, withRecoveredDesign, writeRestoreJournal, type RestoreJournal,
+} from "./design-restore-journal.ts";
+import { readSnapshotInfo, snapshotFilesDir } from "./design-snapshot-history.ts";
+import { readDesignTree, takeSnapshotLocked, writeTreeFiles } from "./design-snapshots.service.ts";
+
+export { recoverRestoreJournal } from "./design-restore-journal.ts";
+
+export interface RestoreResult {
+  restored: string;
+  /**
+   * Snapshot holding the state from just before the restore, i.e. the one to restore to
+   * undo it: the new `pre-restore` snapshot, or the existing snapshot that already equalled
+   * the current state.
+   */
+  previousStateId: string;
+}
+
+/**
+ * Replace a design's working files with a snapshot's, as a journaled swap.
+ *
+ *  1. Snapshot the current state (`pre-restore`), protecting the target from that
+ *     snapshot's pruning so restoring the oldest entry cannot evict the entry itself.
+ *  2. Stage a full copy of the target in `.design/tmp-<id>/`, journal `staged`.
+ *  3. Journal `swapping`, then swap (see `completeSwap`).
+ *  4. Remove the journal and the empty staging dir.
+ *
+ * A crash anywhere after step 2 is repaired by the next locked operation on the design.
+ * The restore is refused when the current state cannot be snapshotted (over the size
+ * budget), because it could then never be undone.
+ */
+export async function restoreSnapshot(projectPath: string, slug: string, id: string): Promise<RestoreResult> {
+  if (!isSnapshotId(id)) throw new DesignError(400, "EBADID", "Invalid snapshot id");
+  const result = await withRecoveredDesign(projectPath, slug, async (designDir) => {
+    if (!(await readSnapshotInfo(designDir, id))) throw new DesignError(404, "ENOENT", `Snapshot not found: ${id}`);
+
+    const before = await takeSnapshotLocked(designDir, "pre-restore", { restoreOf: id }, new Set([id]));
+    if ("skipped" in before && before.skipped !== "unchanged") {
+      throw new DesignError(409, "ETOOLARGE", "The current design is too large to back up, so restoring would lose it");
+    }
+    const previousStateId = "id" in before ? before.id : before.sameAs;
+
+    const staged = await readDesignTree(snapshotFilesDir(designDir, id), { skipDotDesign: true });
+    if (!staged) throw new DesignError(409, "ETOOLARGE", "Snapshot is too large to restore");
+    const dot = await ensureDotDesign(designDir);
+    const journal: RestoreJournal = { id, tmp: `tmp-${id}`, phase: "staged", names: [] };
+    const tmpDir = join(dot, journal.tmp);
+    try {
+      await rm(tmpDir, { recursive: true, force: true });
+      await mkdir(tmpDir);
+      await writeTreeFiles(tmpDir, staged.files);
+      journal.names = await readdir(tmpDir);
+    } catch (e) {
+      // Nothing is journaled yet, so the working tree is untouched and tmp is disposable.
+      await rm(tmpDir, { recursive: true, force: true });
+      throw e;
+    }
+    await writeRestoreJournal(designDir, journal);
+    crashPoint("staged");
+
+    journal.phase = "swapping";
+    await writeRestoreJournal(designDir, journal);
+    crashPoint("swapping");
+    await completeSwap(designDir, journal);
+    crashPoint("swapped");
+    await finishRestore(designDir, journal);
+    return { restored: id, previousStateId };
+  });
+  emitDesignEvent("history_changed", { projectPath: resolve(projectPath), slug });
+  return result;
+}

package/src/services/design/design-safe-walk.ts

@@ -0,0 +1,114 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { isCredentialPath } from "../fs-path-guard.service.ts";
+import { isInsideDir } from "../fs-ops/fs-real-path.ts";
+import { DOT_DESIGN, lstatOrNull } from "./design-paths.ts";
+
+/**
+ * The one tree walker every design tree operation goes through: snapshot, tree hash,
+ * restore staging, and the zip/standalone exports.
+ *
+ * A design folder is written by an agent, so it can contain anything the agent (or a
+ * prompt injected into it) chose to create. The walker therefore:
+ *  - uses `lstat` and skips symlinks, so a link to `ppm.db`, a key file or `/` is never
+ *    read, copied into a snapshot, or packed into an export;
+ *  - skips anything that is not a regular file or a directory — opening a FIFO for reading
+ *    blocks until a writer appears, which would hang the tree hash forever;
+ *  - checks every entry's real path is inside the walked root (a Windows junction or a
+ *    bind mount can pass the symlink test and still point elsewhere);
+ *  - refuses credential paths outright, so a design that somehow sits inside the PPM
+ *    directory fails loudly instead of being copied around.
+ */
+
+export interface SafeWalkEntry {
+  /** Path relative to the walked root, `/`-separated on every platform. */
+  rel: string;
+  abs: string;
+  size: number;
+}
+
+export type SafeWalkErrorCode = "EROOT" | "EOUTSIDE" | "ECREDENTIAL" | "EDEPTH" | "ENOTREG" | "ETOOBIG";
+
+export class SafeWalkError extends Error {
+  readonly status: number;
+  constructor(readonly code: SafeWalkErrorCode, message: string) {
+    super(message);
+    this.name = "SafeWalkError";
+    this.status = code === "ETOOBIG" ? 413 : 403;
+  }
+}
+
+export interface SafeWalkOptions {
+  /** Skip the top-level `.design/` directory (the design's own working data). Default true. */
+  skipDotDesign?: boolean;
+  /** Deepest directory nesting walked before the tree is refused. Default 32. */
+  maxDepth?: number;
+}
+
+async function assertContained(abs: string, realRoot: string): Promise<void> {
+  const real = await realpath(abs);
+  if (!isInsideDir(real, realRoot)) throw new SafeWalkError("EOUTSIDE", `Entry resolves outside the design: ${abs}`);
+  if (isCredentialPath(abs) || isCredentialPath(real)) {
+    throw new SafeWalkError("ECREDENTIAL", "Refusing to read a credential path");
+  }
+}
+
+/** Yields every regular file under `root` in a stable (sorted) order. */
+export async function* safeWalkDesignTree(root: string, opts: SafeWalkOptions = {}): AsyncGenerator<SafeWalkEntry> {
+  const skipDotDesign = opts.skipDotDesign ?? true;
+  const maxDepth = opts.maxDepth ?? 32;
+  const st = await lstat(root);
+  if (st.isSymbolicLink() || !st.isDirectory()) throw new SafeWalkError("EROOT", "Walk root must be a real directory");
+  const realRoot = await realpath(root);
+  if (isCredentialPath(root) || isCredentialPath(realRoot)) {
+    throw new SafeWalkError("ECREDENTIAL", "Refusing to walk a credential path");
+  }
+
+  async function* walk(dirAbs: string, relDir: string, depth: number): AsyncGenerator<SafeWalkEntry> {
+    if (depth > maxDepth) throw new SafeWalkError("EDEPTH", `Design tree nests deeper than ${maxDepth} levels`);
+    // Sorted by code unit rather than locale so the tree hash is identical on every host.
+    const names = (await readdir(dirAbs)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const name of names) {
+      if (depth === 0 && skipDotDesign && name === DOT_DESIGN) continue;
+      const abs = join(dirAbs, name);
+      const rel = relDir ? `${relDir}/${name}` : name;
+      const entry = await lstatOrNull(abs);
+      if (!entry || entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        await assertContained(abs, realRoot);
+        yield* walk(abs, rel, depth + 1);
+      } else if (entry.isFile()) {
+        await assertContained(abs, realRoot);
+        yield { rel, abs, size: entry.size };
+      }
+      // FIFOs, sockets and devices are skipped: nothing in a design needs one.
+    }
+  }
+
+  yield* walk(realRoot, "", 0);
+}
+
+// Where the platform has them: refuse to open through a symlink swapped in after the
+// walk's lstat, and never block opening a FIFO swapped in the same way. Windows has
+// neither flag, and there the lstat immediately before is the protection.
+const SAFE_OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+
+/**
+ * Read one file the walker yielded, re-checking through the open handle that it is still a
+ * regular file. Closes the window between the walk's `lstat` and the read, in which the
+ * entry could have been replaced by a symlink or a FIFO.
+ */
+export async function readDesignFileSafe(abs: string, maxBytes?: number): Promise<Buffer> {
+  const handle = await open(abs, SAFE_OPEN_FLAGS);
+  try {
+    const st = await handle.stat();
+    if (!st.isFile()) throw new SafeWalkError("ENOTREG", `Not a regular file: ${abs}`);
+    if (maxBytes !== undefined && st.size > maxBytes) {
+      throw new SafeWalkError("ETOOBIG", `File exceeds ${maxBytes} bytes: ${abs}`);
+    }
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}

package/src/services/design/design-slug.ts

@@ -0,0 +1,35 @@
+/**
+ * A design slug names the folder `designs/<slug>/` and is interpolated into the agent's
+ * instructions, so it must be a single safe path segment: lowercase ASCII letters, digits
+ * and hyphens, starting with a letter or digit, at most 63 characters. Anything that could
+ * form `..`, a separator, or a drive letter is rejected by construction rather than by a
+ * blocklist.
+ */
+export const DESIGN_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+const MAX_SLUG_LENGTH = 63;
+
+export function isValidDesignSlug(value: unknown): value is string {
+  return typeof value === "string" && DESIGN_SLUG_RE.test(value);
+}
+
+/**
+ * Derive a slug from a human title ("Landing page — v2" → "landing-page-v2").
+ * Accents are folded to ASCII first so a Vietnamese or French title keeps its letters
+ * instead of collapsing to hyphens. Returns "" when nothing usable remains, so the caller
+ * decides the fallback name rather than this function inventing one.
+ */
+export function slugFromTitle(title: string): string {
+  const folded = title
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    // Vietnamese đ/Đ is a letter of its own, not a base letter plus a mark.
+    .replace(/[đĐ]/g, "d")
+    .toLowerCase();
+  const slug = folded
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, MAX_SLUG_LENGTH)
+    .replace(/-+$/, "");
+  return isValidDesignSlug(slug) ? slug : "";
+}