fix(docker): make a default docker build + documented run actually work

Three defects found while bringing up a container from a clean checkout:

- The dashboard's vite build (~5.7k modules) exceeded V8's default old-space on a
  stock Docker Desktop VM and aborted the image build with "Ineffective
  mark-compacts near heap limit" (exit 134). Raise the ceiling for that RUN only.
- The documented `-v fusion-home:/home/node/.fusion` mount seeded a root-owned
  named volume over a path absent from the image, so embedded Postgres initdb hit
  "Permission denied", the supervisor burned its 4 restarts, and the container went
  unhealthy on first run. Pre-create the directory node-owned so a fresh named
  volume inherits it; document that bind mounts still need a host-side chown.
- Drop the dependency-graph plugin's tsconfig path mapping for the taskStuck module
  deleted in 2eae0b2507 / 29d94e0fa3.

Verified: full `docker build` from a clean export of this tree succeeds unpatched,
and a run against brand-new named volumes with no manual chown reaches health=healthy
with /api/health 200.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Dockerfile

@@ -53,7 +53,13 @@ COPY plugins/fusion-plugin-reports/package.json ./plugins/fusion-plugin-reports/
 RUN pnpm install --frozen-lockfile
 
 COPY . .
-RUN pnpm build
+# FNXC:DockerBuild 2026-08-17-23:18: The dashboard's `vite build` transforms ~5.7k modules and
+# exceeded V8's default old-space on a stock Docker Desktop VM (8GB), aborting the whole image
+# build with "FATAL ERROR: Ineffective mark-compacts near heap limit" (exit 134). The ceiling is
+# a cap, not a reservation — V8 only grows to what the build needs — so raising it here costs
+# nothing on larger hosts and is the difference between a working and a failing `docker build`
+# on a default install. Scoped to this RUN so it never leaks into the runner stage's env.
+RUN NODE_OPTIONS=--max-old-space-size=6144 pnpm build
 
 FROM node:22-slim AS runner
 LABEL org.opencontainers.image.source="https://github.com/gsxdsm/fusion"
@@ -96,9 +102,17 @@ COPY --from=builder /app/node_modules/.pnpm/typebox@*/node_modules/typebox /app/
 # the user's project and the container working directory, so `fn dashboard` operates
 # on the mounted project. It must stay empty in the image so a bind mount never
 # shadows application code.
+# FNXC:DockerRun 2026-08-17-23:18: /home/node/.fusion must exist node-owned IN THE IMAGE, because
+# Docker seeds a fresh NAMED volume from the image's content and ownership at the mount path. The
+# documented `-v fusion-home:/home/node/.fusion` invocation previously mounted a root-owned empty
+# volume over a path that did not exist, so embedded Postgres `initdb` failed with "could not create
+# directory ... Permission denied", the dashboard supervisor burned its 4 restarts, and the container
+# went unhealthy on first run. Pre-creating it makes the documented command work with no host-side
+# chown. NOTE: this fixes named volumes only — a BIND mount keeps the host directory's ownership, so
+# a host path bound here must already be writable by uid 1000 (node).
 RUN chown node:node /app \
-  && mkdir -p /workspace \
-  && chown node:node /workspace
+  && mkdir -p /workspace /home/node/.fusion \
+  && chown node:node /workspace /home/node/.fusion
 
 USER node
 

docs/docker.md

@@ -86,6 +86,20 @@ docker run -p 4040:4040 \
 The named volume `fusion-home` persists the embedded database across
 `docker run` invocations; a host directory bind mount works too.
 
+The image pre-creates `/home/node/.fusion` owned by `node`, so a fresh **named
+volume** inherits that ownership and embedded PostgreSQL can initialize on first
+run. A **bind mount** does not inherit it — the host directory's ownership wins —
+so a host path mounted there must already be writable by uid `1000`:
+
+```bash
+mkdir -p /path/to/fusion-home && sudo chown -R 1000:1000 /path/to/fusion-home
+```
+
+Symptom when this is wrong: `initdb: error: could not create directory
+"/home/node/.fusion/embedded-postgres": Permission denied`, followed by the
+dashboard supervisor exhausting its restarts and the container reporting
+`unhealthy`.
+
 ## Complete example
 
 ```bash
@@ -102,6 +116,11 @@ docker run --rm \
 ## Notes
 
 - The container runs as the non-root `node` user.
+- The builder stage runs `pnpm build` with `NODE_OPTIONS=--max-old-space-size=6144`. The dashboard's
+  `vite build` exceeds V8's default old-space on a stock Docker Desktop VM and aborts the image build
+  with `FATAL ERROR: Ineffective mark-compacts near heap limit` (exit 134). The value is a ceiling,
+  not a reservation. If your Docker VM has less than ~8GB, raise its memory allocation rather than
+  lowering this number.
 - `git` must be available in the container runtime. The mounted project volume must preserve `.git` metadata and repository history for worktree operations; Fusion initializes missing repositories during project registration.
 - The root `Dockerfile` installs with `pnpm install --frozen-lockfile` before copying full source, so every current workspace package/plugin manifest selected by `pnpm-workspace.yaml` must be covered by a builder-stage `COPY` before that install. Keep the manifest-only dependency-cache layer; the runner's intentionally filtered production install does not provide builder coverage.
 - `scripts/__tests__/dockerfile-workspace-manifests.test.mjs` expands the current workspace entries and rejects missing or duplicate builder pre-install COPY sources. Run it with `pnpm test:scripts -- scripts/__tests__/dockerfile-workspace-manifests.test.mjs` whenever workspace membership or Docker manifest copies change.

plugins/fusion-plugin-dependency-graph/tsconfig.json

@@ -7,7 +7,6 @@
     "types": ["react"],
     "paths": {
       "@fusion/dashboard/app/components/TaskCard": ["./src/dashboard-interop.d.ts"],
-      "@fusion/dashboard/app/utils/taskStuck": ["./src/dashboard-interop.d.ts"],
       "@fusion/dashboard/app/plugins/types": ["./src/dashboard-interop.d.ts"],
       "@fusion/dashboard/app/utils/projectStorage": ["./src/dashboard-interop.d.ts"]
     }