@1agh/maude 0.60.7 → 1.0.3

package/apps/studio/exporters/jobs.ts

@@ -28,6 +28,7 @@ import { mkdir, rm } from 'node:fs/promises';
 import path from 'node:path';
 
 import type { Bus } from '../context.ts';
+import { resolveRenderLane } from '../workspace-mode.ts';
 import {
   type ExportContext,
   type ExportDegradation,
@@ -37,7 +38,16 @@ import {
   runExport,
   type Scope,
 } from './index.ts';
-import type { ResolveScopeArgs } from './scope.ts';
+import {
+  formatNeedsBrowser,
+  NoRenderServiceError,
+  REMOTE_UNSUPPORTED_FORMATS,
+  REMOTE_UNSUPPORTED_MESSAGE,
+  type RemoteCanvasAccess,
+  renderRemotely,
+  resolveRenderService,
+} from './remote.ts';
+import { type ResolveScopeArgs, resolveScope } from './scope.ts';
 
 /** Extended shape of the old Phase 6.5 T10 history entry — additive fields only. */
 export interface ExportHistoryEntry {
@@ -85,6 +95,14 @@ export interface EnqueueArgs {
   options: ExportOptions;
   resolve: Omit<ResolveScopeArgs, 'scope'>;
   ctx: ExportContext;
+  /**
+   * feature-cloud-export-render-workers (DDR-230) — how the render service
+   * reaches this project's canvas when the job dispatches remotely: the
+   * PUBLIC canvas origin plus the requesting member's own render token,
+   * forwarded from the enqueue request. Absent on a desktop, where the lane
+   * is `local` and this is never read.
+   */
+  remoteCanvas?: RemoteCanvasAccess;
 }
 
 export type DownloadResult =
@@ -310,7 +328,33 @@ export function createExportJobQueue(bus: Bus, designRoot: string): ExportJobQue
 
     const controller = new AbortController();
 
+    // DDR-230 — where this job renders. `local` is the pre-render-workers
+    // spine, byte-identical. In a workspace the browser formats dispatch to
+    // the maude-render service (`remote`) or refuse with a remedy (`none`);
+    // browser-free formats (zip) run in-cell in every lane, because there is
+    // nothing to evaluate. Resolved per job, not per process, so tests can
+    // exercise the lanes without a reboot.
+    const lane = resolveRenderLane();
+    const dispatchRemote = lane !== 'local' && formatNeedsBrowser(args.format);
+
     const result = (async (): Promise<ExportResult> => {
+      // Fail BEFORE taking a render slot: a job that can never render must not
+      // queue behind ones that can, and the refusal message is the remedy the
+      // export dialog shows (belt to the client's own lane gate).
+      const laneRefusal =
+        lane !== 'local' && REMOTE_UNSUPPORTED_FORMATS.has(args.format)
+          ? REMOTE_UNSUPPORTED_MESSAGE
+          : dispatchRemote && lane === 'none'
+            ? new NoRenderServiceError().message
+            : null;
+      if (laneRefusal) {
+        job.status = 'failed';
+        job.finishedAt = new Date().toISOString();
+        job.error = laneRefusal;
+        emit(job);
+        await persistAndEvict();
+        throw new Error(laneRefusal);
+      }
       const release = await semaphore.acquire();
       // Started here, not at enqueue — the timeout bounds RENDER time (the
       // intent), not queue-wait time. A job can legitimately sit `queued`
@@ -323,20 +367,38 @@ export function createExportJobQueue(bus: Bus, designRoot: string): ExportJobQue
         job.startedAt = new Date().toISOString();
         emit(job);
 
-        const res = await runExport({
-          format: args.format,
-          scope: args.scope,
-          options: args.options,
-          resolve: args.resolve,
-          ctx: args.ctx,
-          hooks: {
-            signal: controller.signal,
-            onProgress: (update) => {
-              job.progress = update;
-              emit(job);
-            },
-          },
-        });
+        const res = dispatchRemote
+          ? await renderRemotely({
+              format: args.format,
+              // Scope resolves HERE, against the cell's own checkout — Target
+              // is pure data, and the render service holds no tenant store to
+              // resolve against (DDR-230 §1).
+              targets: await resolveScope({
+                scope: args.scope,
+                ...args.resolve,
+                options: args.options,
+              }),
+              options: args.options,
+              canvas: args.remoteCanvas ?? { origin: '' },
+              // resolveRenderService() is non-null on the `remote` lane by
+              // construction (the lane IS the presence of MAUDE_RENDER_URL).
+              service: resolveRenderService()!,
+              signal: controller.signal,
+            })
+          : await runExport({
+              format: args.format,
+              scope: args.scope,
+              options: args.options,
+              resolve: args.resolve,
+              ctx: args.ctx,
+              hooks: {
+                signal: controller.signal,
+                onProgress: (update) => {
+                  job.progress = update;
+                  emit(job);
+                },
+              },
+            });
 
         job.status = 'done';
         job.finishedAt = new Date().toISOString();

package/apps/studio/exporters/remote.ts

@@ -0,0 +1,201 @@
+// Remote render dispatch — feature-cloud-export-render-workers (DDR-230).
+//
+// In a workspace cell the browser-needing exporters cannot run: no browser
+// enters the image (DDR-209 A′1, unchanged). What a cell CAN do is resolve the
+// export's scope against its own checkout (Target is pure data) and hand the
+// fully-resolved job to the `maude-render` service, which holds a Chromium and
+// NOTHING ELSE — no HUB_SECRET, no tenant store, no provider keys (DDR-230).
+// The service reaches the canvas exactly the way the member's browser does:
+// through the public canvas origin, authenticated by the member's own
+// short-lived read-only render token, forwarded from the enqueue request.
+//
+// This module is deliberately dumb: one POST, the artifact (or a typed error)
+// back. Progress is coarse in v1 — queued → running → done; the per-frame
+// stream stays a local-lane feature until the service grows a progress channel.
+
+import path from 'node:path';
+
+import type { ExportDegradation } from './degraded.ts';
+import type { ExportOptions, ExportResult, Format } from './index.ts';
+import type { Target } from './scope.ts';
+
+// The render service is the fleet's LEAST-trusted process (DDR-230 — it is the
+// one place tenant TSX is evaluated in Chromium). Everything crossing back from
+// it is untrusted, so its response is sanitized at THIS boundary before it
+// reaches disk or the job record — security-review defender findings, 2026-08-21.
+
+/**
+ * Cap on the artifact a render worker may return — a hostile one must not OOM
+ * the cell. Read per-call (not a module const) so the deployment can tune it
+ * and tests can exercise the ceiling.
+ */
+function artifactCap(): number {
+  return Math.max(
+    1_000_000,
+    Number(process.env.MAUDE_RENDER_MAX_ARTIFACT_BYTES) || 512 * 1024 * 1024
+  );
+}
+
+/**
+ * Reduce whatever the render service put in `x-maude-filename` to a safe
+ * basename. This value has TWO untrusted sinks (security-review): it lands in
+ * `Bun.write(path.join(jobsDir, id, name), …)` (jobs.ts), so `../../…` is an
+ * arbitrary-path write; and it is reflected into a `Content-Disposition:
+ * attachment; filename="…"` header (http.ts), so a quote or CR/LF is header
+ * injection. A strict allowlist charset closes BOTH: keep only letters, digits,
+ * dot, dash, underscore — drop everything else (separators, quotes, control
+ * chars) — then reject a name that is only dots.
+ */
+function safeArtifactName(raw: string | null, format: Format): string {
+  const fallback = `export.${format === 'canva' ? 'zip' : format}`;
+  if (!raw) return fallback;
+  const base = path.basename(raw).replace(/[^A-Za-z0-9._-]/g, '');
+  if (!base || /^\.+$/.test(base)) return fallback;
+  return base.slice(0, 255);
+}
+
+/** Read a response body with a hard byte ceiling — `arrayBuffer()` has none. */
+async function readCapped(res: Response, max: number): Promise<Uint8Array> {
+  const declared = Number(res.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > max) {
+    throw new Error(`render artifact too large (${declared} bytes > ${max})`);
+  }
+  const reader = res.body?.getReader();
+  if (!reader) return new Uint8Array(0);
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel().catch(() => {});
+      throw new Error(`render artifact exceeded ${max} bytes mid-stream`);
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
+/**
+ * Formats that never touch a browser. `zip` is JSZip over project files — it
+ * runs in-cell in every lane. Everything else captures through the Playwright
+ * spine and must dispatch (or refuse) in a workspace.
+ */
+export const BROWSER_FREE_FORMATS: ReadonlySet<Format> = new Set<Format>(['zip']);
+
+export function formatNeedsBrowser(format: Format): boolean {
+  return !BROWSER_FREE_FORMATS.has(format);
+}
+
+/**
+ * Formats the render service cannot produce: `canva` bundles PNG captures WITH
+ * project files (CSV, README, sources), and the service holds no tenant store
+ * to read them from (DDR-230 §1). In a workspace these refuse with a
+ * use-the-desktop remedy on BOTH the `remote` and `none` lanes.
+ */
+export const REMOTE_UNSUPPORTED_FORMATS: ReadonlySet<Format> = new Set<Format>(['canva']);
+
+export const REMOTE_UNSUPPORTED_MESSAGE =
+  'Canva handoff bundles project files the render service can’t reach — export it from the desktop app.';
+
+/** Where the render service lives, from the cell/hub environment (T6 wiring). */
+export interface RenderService {
+  /** `MAUDE_RENDER_URL` — origin of the maude-render service. */
+  url: string;
+  /** `MAUDE_RENDER_SECRET` — shared ingress bearer. Never a hub secret. */
+  secret: string;
+}
+
+/** How the render service reaches the tenant's canvas — the member's own grant. */
+export interface RemoteCanvasAccess {
+  /** PUBLIC canvas origin (what the member's browser iframes load from). */
+  origin: string;
+  /** The member's render token (x-maude-canvas-token), forwarded verbatim. */
+  token?: string;
+  /** designRoot-relative tokens CSS path (`?tokens=` on the shell URL). */
+  tokensCssRel?: string;
+  /** designRoot-relative shared components CSS path, when the DS has one. */
+  componentsCssRel?: string;
+}
+
+export function resolveRenderService(env: NodeJS.ProcessEnv = process.env): RenderService | null {
+  const url = env.MAUDE_RENDER_URL;
+  if (!url) return null;
+  return { url: url.replace(/\/+$/, ''), secret: env.MAUDE_RENDER_SECRET ?? '' };
+}
+
+/** The message a lane-`none` refusal carries — surfaced verbatim in the job UI. */
+export const NO_RENDER_SERVICE_MESSAGE =
+  'This format needs the render service, which this workspace doesn’t have configured. ' +
+  'ZIP still works here; for rendered formats use the desktop app, or add the maude-render ' +
+  'service (see the self-hosting docs).';
+
+export class NoRenderServiceError extends Error {
+  constructor() {
+    super(NO_RENDER_SERVICE_MESSAGE);
+    this.name = 'NoRenderServiceError';
+  }
+}
+
+/**
+ * POST one fully-resolved export job to the render service and return the
+ * artifact as a normal `ExportResult`. Degradation travels back as a JSON
+ * header rather than a wrapped body so the artifact bytes stream unmodified.
+ */
+export async function renderRemotely(args: {
+  format: Format;
+  targets: Target[];
+  options: ExportOptions;
+  canvas: RemoteCanvasAccess;
+  service: RenderService;
+  signal?: AbortSignal;
+}): Promise<ExportResult> {
+  const { format, targets, options, canvas, service, signal } = args;
+  // The exporters' per-navigation timeouts (png.ts goto `--timeout`, etc.)
+  // default to ~8s — tuned for the DESKTOP path where the canvas origin is
+  // loopback and already warm. The render worker instead loads the canvas from
+  // the REMOTE canvas origin, and a cold cell builds the tenant's TSX in its
+  // sandbox on first access, so `_canvas-shell.html` can take far longer than
+  // 8s to fire `load`. Give the remote path a generous floor (unless the
+  // caller asked for more) so a cold-cell first render doesn't time out.
+  const remoteOptions: ExportOptions = {
+    ...options,
+    timeoutSec: Math.max(Number((options as { timeoutSec?: number }).timeoutSec) || 0, 60),
+  };
+  const res = await fetch(`${service.url}/render`, {
+    method: 'POST',
+    signal,
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${service.secret}`,
+    },
+    body: JSON.stringify({ format, targets, options: remoteOptions, canvas }),
+  });
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => '')) || `${res.status}`;
+    throw new Error(`render service refused the job: ${detail}`);
+  }
+  // Sanitize the filename BEFORE it can reach `Bun.write` in jobs.ts — the
+  // service is untrusted (DDR-230), and this header would otherwise choose the
+  // write path.
+  const filename = safeArtifactName(res.headers.get('x-maude-filename'), format);
+  const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+  let degraded: ExportDegradation | undefined;
+  const degradedHeader = res.headers.get('x-maude-degraded');
+  if (degradedHeader) {
+    try {
+      degraded = JSON.parse(degradedHeader) as ExportDegradation;
+    } catch {
+      /* a malformed degradation note must not fail a real artifact */
+    }
+  }
+  const body = await readCapped(res, artifactCap());
+  return { filename, contentType, body, ...(degraded ? { degraded } : {}) };
+}

package/apps/studio/exporters/video-encode-lib.ts

@@ -76,11 +76,16 @@ async function decodeToBitmap(
   b64: string,
   mime: 'image/png' | 'image/jpeg' = 'image/png'
 ): Promise<ImageBitmap> {
-  return createImageBitmap(new Blob([b64ToBytes(b64)], { type: mime }));
+  // Uint8Array<ArrayBufferLike> vs BlobPart — see saveAsset in api.ts.
+  return createImageBitmap(new Blob([b64ToBytes(b64) as Uint8Array<ArrayBuffer>], { type: mime }));
 }
 
 let vstate: {
   output: Output;
+  // Held alongside `output` because mediabunny's `Output` types `target` as the
+  // Target union — the concrete BufferTarget (the only one this encoder ever
+  // constructs) is what carries `.buffer`.
+  target: BufferTarget;
   source: CanvasSource;
   canvas: OffscreenCanvas;
   ctx: OffscreenCanvasRenderingContext2D;
@@ -123,7 +128,8 @@ const api: MaudeEnc = {
     }
     if (!codec) throw new Error('no encodable video codec available in this browser');
 
-    const output = new Output({ format: outFormat, target: new BufferTarget() });
+    const target = new BufferTarget();
+    const output = new Output({ format: outFormat, target });
     // `latencyMode: 'quality'` is pinned, not left to the default. Per WebCodecs
     // §7.11 `realtime` explicitly permits the encoder to DROP frames to hit a
     // bitrate/framerate target, while `quality` MUST NOT — and mediabunny flips
@@ -139,7 +145,7 @@ const api: MaudeEnc = {
     output.addVideoTrack(source, { frameRate: fps });
     await output.start();
     const container = outFormat instanceof Mp4OutputFormat ? 'mp4' : 'webm';
-    vstate = { output, source, canvas, ctx, fps, frame: 0, container, codec };
+    vstate = { output, target, source, canvas, ctx, fps, frame: 0, container, codec };
     return { container, codec };
   },
 
@@ -170,7 +176,7 @@ const api: MaudeEnc = {
   async finishVideo() {
     if (!vstate) throw new Error('startVideo not called');
     await vstate.output.finalize();
-    const buf = vstate.output.target.buffer;
+    const buf = vstate.target.buffer;
     if (!buf) throw new Error('encode produced no buffer');
     const res: EncodeResult = {
       b64: bytesToB64(buf),

package/apps/studio/figma/to-strokes.ts

@@ -40,6 +40,7 @@ import {
   type Stroke,
   type TextStroke,
 } from '../annotations-model.ts';
+import type { ArrowLineType } from '../canvas-arrowheads.ts';
 import {
   attrValue,
   type Bounds,
@@ -107,14 +108,15 @@ const CAP_MAP: Readonly<Record<string, 'none' | 'triangle' | 'line'>> = Object.a
   }
 );
 
-const LINE_TYPE_MAP: Readonly<Record<string, 'straight' | 'elbow' | 'curve'>> = Object.assign(
-  Object.create(null),
-  {
-    STRAIGHT: 'straight',
-    ELBOWED: 'elbow',
-    CURVED: 'curve',
-  }
-);
+// Values are ArrowLineType — 'curved', not 'curve'. The old 'curve' matched no
+// arm of the renderer's `lineType === 'curved'` checks, so every curved FigJam
+// connector imported as a stroke nothing could draw as curved (it fell through
+// to straight). Typed against the real union so a third spelling cannot recur.
+const LINE_TYPE_MAP: Readonly<Record<string, ArrowLineType>> = Object.assign(Object.create(null), {
+  STRAIGHT: 'straight',
+  ELBOWED: 'elbow',
+  CURVED: 'curved',
+});
 
 export interface PendingImage {
   /** The stroke whose `href` must be rewritten once the asset lands. */
@@ -184,7 +186,7 @@ function imageRef(node: FigmaNode): string | null {
 export function nearestStickyColor(hex: string | null): string {
   const target = hex ? hexToRgb01(hex) : null;
   if (!target) return STICKY_PALETTE[0];
-  let best = STICKY_PALETTE[0];
+  let best: (typeof STICKY_PALETTE)[number] = STICKY_PALETTE[0];
   let bestDist = Number.POSITIVE_INFINITY;
   for (const candidate of STICKY_PALETTE) {
     const c = hexToRgb01(candidate);

package/apps/studio/gifenc.d.ts

@@ -0,0 +1,51 @@
+// Ambient types for `gifenc` — the package ships no declarations, so without
+// this the GIF export lane was `any` end to end (and, before the A2 tsconfig
+// completion, checked by nothing at all).
+//
+// Narrowed to the surface exporters/video-encode-lib.ts actually calls; widen
+// it here rather than casting at a call site.
+
+declare module 'gifenc' {
+  export type Palette = number[][];
+
+  export interface WriteFrameOptions {
+    palette?: Palette;
+    /** Frame delay in milliseconds. */
+    delay?: number;
+    transparent?: boolean;
+    transparentIndex?: number;
+    repeat?: number;
+    dispose?: number;
+  }
+
+  export interface GifEncoder {
+    writeFrame(
+      index: Uint8Array | number[],
+      width: number,
+      height: number,
+      opts?: WriteFrameOptions
+    ): void;
+    finish(): void;
+    bytes(): Uint8Array;
+    bytesView(): Uint8Array;
+    reset(): void;
+  }
+
+  export function GIFEncoder(opts?: { auto?: boolean; initialCapacity?: number }): GifEncoder;
+
+  export function quantize(
+    rgba: Uint8Array | Uint8ClampedArray,
+    maxColors: number,
+    opts?: {
+      format?: 'rgb565' | 'rgb444' | 'rgba4444';
+      oneBitAlpha?: boolean;
+      clearAlpha?: boolean;
+    }
+  ): Palette;
+
+  export function applyPalette(
+    rgba: Uint8Array | Uint8ClampedArray,
+    palette: Palette,
+    format?: 'rgb565' | 'rgb444' | 'rgba4444'
+  ): Uint8Array;
+}

package/apps/studio/git/log-format.ts

@@ -0,0 +1,88 @@
+// The shape of a History row — the one answer both committers produce.
+//
+// A commit row is drawn by the same `GitPanel` renderer whether it came from
+// the desktop's own repo (`git/service.ts` → `/_api/git/log`) or from the cloud
+// cell that owns a linked project's history (`apps/hub/src/history.mjs` →
+// `/api/history`). Two spellings of "how a log line is asked for and parsed" is
+// how a cloud row and a local row come to differ in a field the renderer reads
+// — and the drift would surface as a blank author or an unparseable date on ONE
+// of the two surfaces, which is precisely the class of bug nobody notices until
+// the surface they don't use every day is the one that matters.
+//
+// ONE COPY, TWO RUNTIMES (the `apps/hub/Dockerfile` rule). The hub imports this
+// file rather than re-typing it in `.mjs`, exactly as it does for
+// `sync/autocommit.ts`, `sync/canvas-path.ts` and `cloud/mirror.mjs`: re-typing
+// a guarantee is re-typing it without its tests. Hence React-free and
+// dependency-free — no `node:*`, nothing a plain-Node hub or a bun-compiled
+// sidecar has to resolve.
+
+/** One commit, as every History surface renders it. */
+export interface GitLogRecord {
+  sha: string;
+  message: string;
+  author: string;
+  email: string;
+  /** ISO-8601 commit date. */
+  date: string;
+}
+
+/**
+ * Unit-separator field delimiter, record-separator line delimiter — survives
+ * any message punctuation (a commit subject may contain newlines, tabs, quotes
+ * and every separator a "sensible" format would have picked).
+ */
+export const GIT_LOG_FORMAT = '%H%x1f%s%x1f%an%x1f%ae%x1f%aI%x1e';
+
+/**
+ * `git log` argv for `limit` commits, optionally scoped to one `filepath`.
+ *
+ * The `--` terminator makes `filepath` strictly positional — git can't read it
+ * as an option (no argument injection even if it began with a dash, which the
+ * caller's containment validation already rejects upstream).
+ *
+ * THE CALLER MUST ALSO SET `GIT_LITERAL_PATHSPECS=1` whenever `filepath` is
+ * present — see `gitLogEnv`. That hardening is a recorded phase-27.1 security
+ * re-review outcome, and it lives beside the argv precisely so a second call
+ * site cannot pick up one half of the pair.
+ */
+export function gitLogArgs(limit: number, filepath?: string): string[] {
+  const args = ['log', `-n${limit}`, `--pretty=format:${GIT_LOG_FORMAT}`];
+  if (filepath) args.push('--', filepath);
+  return args;
+}
+
+/**
+ * The env `gitLogArgs`'s output must run under, or undefined when unscoped.
+ *
+ * GIT_LITERAL_PATHSPECS — match `filepath` VERBATIM, never as pathspec magic
+ * (`:(top)`, `:(exclude)`, globs). Callers already restrict it to the design
+ * tree; this makes system-git treat it as a plain path regardless, closing the
+ * pathspec-magic surface the `--` terminator alone doesn't.
+ */
+export function gitLogEnv(filepath?: string): { GIT_LITERAL_PATHSPECS: '1' } | undefined {
+  return filepath ? { GIT_LITERAL_PATHSPECS: '1' } : undefined;
+}
+
+/**
+ * Parse `git log --pretty=format:GIT_LOG_FORMAT` stdout into records.
+ *
+ * Total and forgiving in one direction only: a record short of its five fields
+ * yields empty strings rather than `undefined`, so a renderer never has to
+ * defend against a half-parsed row. Garbage in is an empty list, never a throw.
+ */
+export function parseGitLog(stdout: string): GitLogRecord[] {
+  return String(stdout ?? '')
+    .split('\x1e')
+    .map((rec) => rec.replace(/^\n/, '').trim())
+    .filter(Boolean)
+    .map((rec) => {
+      const [sha, message, author, email, date] = rec.split('\x1f');
+      return {
+        sha: sha ?? '',
+        message: message ?? '',
+        author: author ?? '',
+        email: email ?? '',
+        date: date ?? '',
+      };
+    });
+}

package/apps/studio/git/safe-rel.ts

@@ -0,0 +1,96 @@
+/**
+ * One place that decides whether a relative path is safe to hand to git.
+ *
+ * WHY A HELPER AND NOT A REGEX PER CALL SITE (F-13 / B12). `designRel` and the
+ * per-file rels built on top of it reach git from four directions — the status
+ * prefix (`git/endpoints.ts`, `git/watch.ts`), the porcelain filter
+ * (`git/service.ts`), and the autocommit staging batch (`sync/autocommit.ts`).
+ * Three of those grew their own partial normalisation (`normPrefix` strips
+ * slashes and nothing else), and a rule spelled four ways is a rule with three
+ * chances to be spelled wrong.
+ *
+ * WHAT IS AND IS NOT THE RISK HERE, stated plainly so the next reader does not
+ * re-derive it:
+ *
+ *   - **Argv injection is already defused** and this helper is not what defuses
+ *     it. Every `runGit` / `run` call that carries a dynamic path puts it after
+ *     a `--` separator, so a rel beginning with `-` is a filename to git, not a
+ *     flag. The leading-`-` check below is belt-and-braces for a FUTURE call
+ *     site that forgets the separator — a cheap guard, not the load-bearing one.
+ *   - **Containment is the real risk**, and `--` does nothing about it. A rel
+ *     carrying `..` is a perfectly well-formed pathspec that simply names a file
+ *     outside the design root: `../../.github/workflows/release.yml` staged by
+ *     an autocommit is a repo-wide write primitive reached from a path that is
+ *     supposed to be scoped to `.design/`. That is what this refuses.
+ *
+ * The rules mirror `sync/file-membership.ts`'s `relShape` deliberately — the
+ * file plane already refuses exactly these shapes on the way in, and a second
+ * gate that disagreed with the first would just be a bug with two spellings.
+ */
+
+/** Matches `file-membership.ts` MAX_REL_LEN — the same cap, on purpose. */
+export const MAX_GIT_REL_LEN = 512;
+
+/**
+ * Is `rel` safe to use as a git pathspec or as a containment prefix?
+ *
+ * Total: any input that is not a plainly safe repo-relative path is `false`.
+ * Never throws, never normalises — callers that want a normalised value use
+ * `safeGitPrefix`.
+ */
+export function isSafeGitRel(rel: unknown): rel is string {
+  if (typeof rel !== 'string' || rel.length === 0 || rel.length > MAX_GIT_REL_LEN) return false;
+  // NUL and other control characters: a NUL truncates the path at the syscall
+  // boundary, so `assets/a\0../../x` is two different paths depending on who
+  // is looking at it.
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing them is the point.
+  if (/[\u0000-\u001f\u007f]/.test(rel)) return false;
+  // Absolute, Windows-absolute, or backslash-separated — none of these are a
+  // repo-relative path, and each reads differently to git than to `path.join`.
+  if (rel.startsWith('/') || rel.includes('\\') || /^[A-Za-z]:/.test(rel)) return false;
+  // A leading `-` at the START of the whole rel. See the docblock: this is the
+  // guard for a future call site that forgets `--`.
+  if (rel.startsWith('-')) return false;
+  for (const seg of rel.split('/')) {
+    if (!seg || seg === '.' || seg === '..') return false;
+    // A trailing space is invisible in every UI that would show this path and
+    // makes two different files look like one.
+    if (/ $/.test(seg)) return false;
+  }
+  return true;
+}
+
+/**
+ * Normalise a design-root prefix, or `null` when it is not safe to use.
+ *
+ * `''` is a legitimate ANSWER, not a refusal: an absent prefix means "no
+ * containment filter", which is what `gitStatus` has always done for a caller
+ * that passes none. `null` means the caller supplied something and it was
+ * refused — a caller must not silently treat that as "no filter", because that
+ * would widen the scope rather than narrow it.
+ */
+export function safeGitPrefix(raw: unknown): string | null {
+  if (raw === undefined || raw === null || raw === '') return '';
+  if (typeof raw !== 'string') return null;
+  const normalised = raw.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+  if (normalised === '') return '';
+  return isSafeGitRel(normalised) ? normalised : null;
+}
+
+/**
+ * Split a batch of rels into the ones git may be handed and the ones it may not.
+ *
+ * Batch-shaped rather than throw-shaped because the autocommit caller must keep
+ * making progress on the rest of a batch: one poisoned path is not a reason to
+ * stop committing a person's actual work, and a throw there would wedge the
+ * whole queue (the failure mode `partitionForStaging` was written to avoid).
+ */
+export function partitionSafeGitRels(rels: readonly string[]): {
+  safe: string[];
+  refused: string[];
+} {
+  const safe: string[] = [];
+  const refused: string[] = [];
+  for (const rel of rels) (isSafeGitRel(rel) ? safe : refused).push(rel);
+  return { safe, refused };
+}