From 9d38cbf51aa6f6c04c5166abbacef09d5ac55c33 Mon Sep 17 00:00:00 2001
From: Codeman maintainer <noreply@anthropic.com>
Date: Fri, 9 Oct 2026 09:47:22 +0200
Subject: [PATCH] fix(build,docs): dependency preflight before the build wipes
 dist, docs drift for 1.40.0

- scripts/build.mjs resolves exceljs/dist/exceljs.min.js and fflate first,
  before tsc and before rm -rf dist/web/public. A tree whose node_modules
  predate those devDependencies (pulled but never ran npm install) used to
  fail in prepare-spreadsheet-assets.mjs with the live dist assets already
  deleted, so the running server served an index.html whose hashed files
  were gone. It now exits 1 with "run `npm install` first", nothing touched.
  test/spreadsheet-assets.test.ts pins the order, that the list covers every
  require.resolve in the prepare script, and runs a relocated copy of the
  build to prove the exit and message.
- CLAUDE.md: the header visibility rule's stock desktop default now lists
  Tiles (1180px and wider), which ships ON on desktop.
- docs/wiki/Agent-CLIs.md: "Before 1.36.0" becomes "Before 1.40.0" (four
  places); 1.36.0 never ships.
- docs/wiki/Home.md: the "Everything in the manual" index lists Tile Grid
  and Custom Model Endpoints, matching the sidebar. test/wiki-home-index
  fails when a sidebar page is missing from that index.
- docs/wiki/Tile-Grid.md: the Tiles default is off on tablets too since the
  touch-primary default landed, not only on phones.
- docs/browser-testing-guide.md: the fixed port table and new WebServer(PORT)
  snippet give way to the port-0 pattern (new WebServer(0, false, true),
  server.boundPort) that test/test-ports-guard.test.ts enforces; the
  examples that opened localhost:3000, the live instance, use BASE_URL.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                       |  2 +-
 docs/browser-testing-guide.md   | 37 +++++++++-------
 docs/wiki/Agent-CLIs.md         |  8 ++--
 docs/wiki/Home.md               |  2 +
 docs/wiki/Tile-Grid.md          |  3 +-
 scripts/build.mjs               | 27 ++++++++++++
 test/spreadsheet-assets.test.ts | 76 ++++++++++++++++++++++++++++++++-
 test/wiki-home-index.test.ts    | 37 ++++++++++++++++
 8 files changed, 169 insertions(+), 23 deletions(-)
 create mode 100644 test/wiki-home-index.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 00988773..9e6e7518 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -353,7 +353,7 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
 
 **Settings surface** (`#appSettingsModal` + `#sessionOptionsModal` + `#createCaseModal`): one `set-*` language shared through a single `:is(...)` id scope in styles.css. App Settings' rail is a table of contents over ONE scrolling document (`switchSettingsTab` scrolls); Session Options and Add Case really switch (`switchOptionsTab` / `switchCaseModalTab`), and their larger per-modal size blocks are the design, not drift. ⚠️ **The load/save contract is `getElementById` by id**: renaming or dropping a control id silently stops it loading or saving. ⚠️ The Session Options "Session" entry still keys off `context` (label-only rename). ⚠️ Add Case keeps its legacy `.form-row` markup via an adapter; every `<details>` there needs `.set-adv-chev` plus both marker suppressions. ⚠️ Model cards and the effort segment are views over hidden `<select>`s, which stay the source of truth. ⚠️ `.modal-tabs*` classes are retired; `admin-ui.js` needs `.set-rail-items` + `.set-doc` to survive any restructure. Guard: `test/app-settings-structure.test.ts`. → [architecture-invariants#settings-surface-app-settings-session-options-add-case](docs/architecture-invariants.md#settings-surface-app-settings-session-options-add-case)
 
-**Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`, and the desktop-gated `btn-split--hidden` / `btn-tile-grid--hidden`, which also need a `@media (max-width: 1179px)` backstop) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
+**Header button visibility**: most header controls are opt-in and hidden by a marker class (`btn-multimonitor--hidden`, `btn-response-viewer-header--hidden`, `btn-file-viewer--hidden`, `btn-cron--hidden`, and the desktop-gated `btn-split--hidden` / `btn-tile-grid--hidden`, which also need a `@media (max-width: 1179px)` backstop) that `applyHeaderVisibilitySettings()` (settings-ui.js) toggles after settings load; the multi-monitor button is instead stripped at render by `renderIndexHtml`. ⚠️ Hiding must go through the marker class: the base rules are `display:inline-flex !important`, so an inline style cannot override them. Current desktop default is WS/CPU/MEM + File Viewer + Tiles (1180px and wider) + gear, with the token chip and lifecycle-log button OFF. ⚠️ New header controls must not leak onto phones; `test/mobile-header-buttons-policy.test.ts` is the static guard. → [architecture-invariants#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron](docs/architecture-invariants.md#header-button-visibility-multi-monitor-response-viewer-file-viewer-cron)
 
 **Gesture control** (camera hand-tracking overlay, opt-in, default OFF): `CODEMAN_GESTURE=1` makes the feature *available*; `gestureControlEnabled` turns it on. The bundle is injected by `renderIndexHtml` only when enabled, which is why that method is `async` and reads settings with `readSettings(true)` (a fresh read: a post-save reload lands inside the 2s cache TTL and would otherwise render the pre-toggle state). **Source lives in `packages/gesture-control/`; edit there, run `npm run build:gesture`, and commit the regenerated bundle** because dev serves the committed bundle with no runtime bundler. The MediaPipe wasm + model are fetched separately and gitignored. ⚠️ Keep `MP_VERSION` in `fetch-gesture-assets.mjs` in sync with `@mediapipe/tasks-vision`. → [architecture-invariants#gesture-control-the-source-package](docs/architecture-invariants.md#gesture-control-the-source-package)
 
diff --git a/docs/browser-testing-guide.md b/docs/browser-testing-guide.md
index ad11297a..405ef5f5 100644
--- a/docs/browser-testing-guide.md
+++ b/docs/browser-testing-guide.md
@@ -71,17 +71,21 @@ We tested three browser automation frameworks against the Codeman web UI:
 
 ## Test File Structure
 
-### Port Allocation
+### Ports
 
-| Port Range | Test File |
-|------------|-----------|
-| 3150-3153 | browser-e2e.test.ts (existing) |
-| 3154 | file-link-click.test.ts |
-| 3155 | browser-playwright.test.ts |
-| 3156 | browser-puppeteer.test.ts |
-| 3157 | browser-agent.test.ts |
-| 3158-3160 | browser-comparison.test.ts |
-| 3180-3182 | scripts/browser-comparison.mjs |
+A test that starts a server binds an ephemeral port, never a fixed one:
+
+- `WebServer`: `new WebServer(0, false, true)`, then read the port the OS handed out from
+  `server.boundPort` after `await server.start()`. `test/test-ports-guard.test.ts` fails
+  any `WebServer` built under `test/` on a non-zero port (a shrink-only legacy list
+  excepted).
+- A raw Fastify or `ws` server: `listen({ port: 0 })`, then `address().port`.
+- The mobile suite (`test/mobile/**`, via `createTestServer(PORT)`) keeps the fixed-port
+  convention in `test/mobile/README.md` for now.
+- Never port 3000: that is the live instance.
+
+`scripts/browser-comparison.mjs` is a standalone script outside the guard and still uses
+fixed ports 3180-3182.
 
 ### File Purposes
 
@@ -106,7 +110,7 @@ const browser = await chromium.launch({
 });
 
 const page = await browser.newPage();
-await page.goto('http://localhost:3000');
+await page.goto(BASE_URL);
 
 // Auto-waiting selectors
 await page.click('.btn-claude');
@@ -140,7 +144,7 @@ const browser = await puppeteer.launch({
 });
 
 const page = await browser.newPage();
-await page.goto('http://localhost:3000');
+await page.goto(BASE_URL);
 
 // Manual waiting often needed
 await page.click('.btn-claude');
@@ -186,7 +190,7 @@ function agentBrowserJson<T>(cmd: string): T {
 }
 
 // Usage
-agentBrowser('open http://localhost:3000');
+agentBrowser(`open ${BASE_URL}`);
 agentBrowser('click ".btn-claude"');
 const title = agentBrowserJson<{title: string}>('get title');
 
@@ -246,11 +250,14 @@ npx playwright install chromium
 ### 4. Wait for Server Startup
 
 ```typescript
-const server = new WebServer(PORT);
+const server = new WebServer(0, false, true); // port 0 (the OS picks one), no TLS, testMode
 await server.start();
-await new Promise(r => setTimeout(r, 1000)); // Allow server to stabilize
+const BASE_URL = `http://localhost:${server.boundPort}`;
 ```
 
+`boundPort` holds the real port only once `start()` has resolved. The `BASE_URL` used by the
+other snippets on this page is this one.
+
 ### 5. Clean Up Sessions
 
 Track created sessions for cleanup:
diff --git a/docs/wiki/Agent-CLIs.md b/docs/wiki/Agent-CLIs.md
index ea8bdeca..037fe1e1 100644
--- a/docs/wiki/Agent-CLIs.md
+++ b/docs/wiki/Agent-CLIs.md
@@ -124,7 +124,7 @@ environment is injected through socket-scoped `tmux setenv` rather than the comm
 Working and idle come from the screen: while a turn runs, OpenCode draws a small spinner at
 the start of its footer (`⬝■■■■■■⬝  esc interrupt`), and Codeman reads that to tell a working
 session from an idle one. A pending permission prompt shows as idle, since it is waiting on
-you. Before 1.36.0 an OpenCode session that had run a tool showed as working for good.
+you. Before 1.40.0 an OpenCode session that had run a tool showed as working for good.
 
 Integration detail: [`docs/opencode-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/opencode-integration.md).
 
@@ -164,7 +164,7 @@ only the CLI you spawned yourself.
 
 Working and idle come from the screen: while a turn runs, Gemini CLI draws a spinner line
 (`⠦ Thinking... (esc to cancel, 6s)`) above its composer, and Codeman reads that. A tool
-confirmation that waits for you shows as idle. Before 1.36.0 a Gemini session showed as
+confirmation that waits for you shows as idle. Before 1.40.0 a Gemini session showed as
 working for good after its first turn.
 
 ### Antigravity
@@ -190,7 +190,7 @@ Pi needs the opposite instincts from every other CLI here.
   once. They stay out.
 - **Work detection reads Pi's composer rule.** Pi has no prompt glyph; while a turn runs it
   puts a spinner into the rule above the composer (`── ⠏ Working ───`), and Codeman reads
-  that to tell working from idle. Before 1.36.0 a Pi session that had started a turn showed
+  that to tell working from idle. Before 1.40.0 a Pi session that had started a turn showed
   as working for good.
 
 Guide: [`docs/pi-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/pi-integration.md).
@@ -246,7 +246,7 @@ flag from Codeman; change that in OMP's own config, not here.
 
 OMP conversations appear in Past Sessions and can be resumed, and a respawn continues the
 same conversation with `--continue`. Codeman tells working from idle by reading OMP's status
-bar, where a spinner and the elapsed time replace the `π` while a turn runs. Before 1.36.0
+bar, where a spinner and the elapsed time replace the `π` while a turn runs. Before 1.40.0
 an OMP session that had started a turn showed as working for good.
 
 Guide: [`docs/omp-integration.md`](https://github.com/Ark0N/Codeman/blob/master/docs/omp-integration.md).
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
index 6f469007..7be48771 100644
--- a/docs/wiki/Home.md
+++ b/docs/wiki/Home.md
@@ -62,7 +62,9 @@ codeman web    # then open http://localhost:3000
 | Page                                       | What it answers                                            |
 | ------------------------------------------ | ---------------------------------------------------------- |
 | [The Dashboard](The-Dashboard)             | What is the UI telling me?                                 |
+| [Tile Grid](Tile-Grid)                     | How do I watch and drive several sessions side by side?    |
 | [Agent CLIs](Agent-CLIs)                   | Which agent should this session run, and how do I set it up? |
+| [Custom Model Endpoints](Custom-Model-Endpoints) | How do I point a session at my own OpenAI-compatible endpoint? |
 | [Working With Files](Working-With-Files)   | How do I read, edit, and attach files?                     |
 | [Input And Voice](Input-And-Voice)         | How do I talk to an agent, including by voice?             |
 | [Mobile Guide](Mobile-Guide)               | How well does this work on a phone?                        |
diff --git a/docs/wiki/Tile-Grid.md b/docs/wiki/Tile-Grid.md
index 49964747..c88bb50f 100644
--- a/docs/wiki/Tile-Grid.md
+++ b/docs/wiki/Tile-Grid.md
@@ -10,7 +10,8 @@ never offered in a popped-out session window.
 ## Turning it on
 
 **App Settings → Header & Panels → Tiles.** This is a per-device setting, on by default
-everywhere except phones, and the button only appears in a window at least 1180px wide.
+on desktops and laptops and off on phones and tablets, and the button only appears in a
+window at least 1180px wide.
 It shows a **Tiles** button in the header, beside Split, and enables `Ctrl+Shift+G`.
 
 ## Opening a grid
diff --git a/scripts/build.mjs b/scripts/build.mjs
index 8e50b36f..65db3881 100644
--- a/scripts/build.mjs
+++ b/scripts/build.mjs
@@ -4,6 +4,7 @@
  * Extracted from the package.json one-liner for readability and debuggability.
  *
  * Steps:
+ *   0. Preflight: the build-time packages resolve (nothing is touched before it)
  *   1. TypeScript compilation
  *   2. Copy static assets (web/public, templates)
  *   3. Build vendor xterm bundles
@@ -13,6 +14,7 @@
  */
 
 import { execSync } from 'child_process';
+import { createRequire } from 'module';
 import { appendFileSync, readFileSync, writeFileSync, renameSync } from 'fs';
 import { createHash } from 'crypto';
 import { fileURLToPath } from 'url';
@@ -25,6 +27,31 @@ function run(label, cmd) {
   execSync(cmd, { stdio: 'inherit', cwd: ROOT, shell: true });
 }
 
+// 0. Preflight: resolve the build-time packages the asset stage reads only AFTER it has
+// deleted dist/web/public (step 2), before anything is touched. A tree whose node_modules
+// predate them (a deploy that pulled but never ran `npm install`) used to fail mid-build
+// with dist/web/public already wiped, so the running server kept serving an index.html
+// whose hashed assets were gone. Keep the list in step with every require.resolve in
+// scripts/prepare-spreadsheet-assets.mjs (test/spreadsheet-assets.test.ts checks it).
+// Only specifiers that resolve without an exports map in the way: a subpath of a package
+// that has one (@xterm/*) can throw ERR_PACKAGE_PATH_NOT_EXPORTED while installed.
+// A hand-run of the asset stage alone (past a blocked tsc) skips this check.
+const BUILD_TIME_MODULES = ['exceljs/dist/exceljs.min.js', 'fflate'];
+const requireFromBuild = createRequire(import.meta.url);
+const missingModules = BUILD_TIME_MODULES.filter((specifier) => {
+  try {
+    requireFromBuild.resolve(specifier);
+    return false;
+  } catch {
+    return true;
+  }
+});
+if (missingModules.length > 0) {
+  console.error(`[build] missing build dependency: ${missingModules.join(', ')}`);
+  console.error('[build] run `npm install` first, then `npm run build` again. Nothing was built or deleted.');
+  process.exit(1);
+}
+
 // 1. TypeScript compilation
 run('tsc', 'tsc');
 run('chmod dist/index.js', 'chmod +x dist/index.js');
diff --git a/test/spreadsheet-assets.test.ts b/test/spreadsheet-assets.test.ts
index 8b728762..812f328a 100644
--- a/test/spreadsheet-assets.test.ts
+++ b/test/spreadsheet-assets.test.ts
@@ -7,8 +7,11 @@
  * that shape plus the pinned versions and the dev/prod vendoring steps.
  */
 
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import { DOCUMENT_ATTACHMENT_EXTENSIONS, isSupportedAttachmentExtension } from '../src/attachment-registry.js';
 
@@ -94,3 +97,72 @@ describe('spreadsheet preview assets', () => {
     expect(read('src/cli.ts')).toContain("DOCUMENT_ATTACHMENT_EXTENSIONS.join(', ')");
   });
 });
+
+/**
+ * The build deletes dist/web/public and only then copies the vendor bundles out of
+ * node_modules. A tree whose node_modules predate exceljs/fflate (a deploy that pulled
+ * but never ran `npm install`) failed there, with the live assets already gone. The
+ * preflight at the top of build.mjs resolves them before anything is touched.
+ */
+describe('build preflight for the spreadsheet vendor packages', () => {
+  const preflightModules = (build: string): string[] => {
+    const list = /const BUILD_TIME_MODULES = \[([^\]]*)\]/.exec(build)?.[1] ?? '';
+    return [...list.matchAll(/'([^']+)'/g)].map((m) => m[1]);
+  };
+
+  it('covers every package prepare-spreadsheet-assets.mjs resolves, and runs before tsc and the clean', () => {
+    const build = read('scripts/build.mjs');
+    const preflight = preflightModules(build);
+    const resolvedByPrepare = [
+      ...read('scripts/prepare-spreadsheet-assets.mjs').matchAll(/require\.resolve\('([^']+)'\)/g),
+    ].map((m) => m[1]);
+    // Parse sanity; the loop below is the actual coverage check.
+    expect(resolvedByPrepare).toContain('exceljs/dist/exceljs.min.js');
+    expect(resolvedByPrepare).toContain('fflate');
+    for (const specifier of resolvedByPrepare) expect(preflight, specifier).toContain(specifier);
+
+    const bail = build.indexOf('[build] run `npm install` first');
+    expect(bail).toBeGreaterThan(-1);
+    expect(bail).toBeLessThan(build.indexOf("run('tsc', 'tsc')"));
+    expect(bail).toBeLessThan(build.indexOf("'rm -rf dist/web/public'"));
+  });
+
+  it('resolves every preflight package in this installed tree', () => {
+    const requireFromBuild = createRequire(resolve(root, 'scripts/build.mjs'));
+    const preflight = preflightModules(read('scripts/build.mjs'));
+    expect(preflight.length).toBeGreaterThan(0);
+    for (const specifier of preflight) expect(() => requireFromBuild.resolve(specifier), specifier).not.toThrow();
+  });
+
+  it('exits with an npm install hint, and touches nothing, where the packages do not resolve', () => {
+    // A copy of build.mjs outside the repo: nothing resolves from there, and its ROOT
+    // (derived from its own location) is the temp dir, so a missing preflight could
+    // only ever act on that throwaway tree.
+    const tree = mkdtempSync(join(tmpdir(), 'codeman-build-preflight-'));
+    try {
+      mkdirSync(join(tree, 'scripts'));
+      const copy = join(tree, 'scripts', 'build.mjs');
+      copyFileSync(resolve(root, 'scripts/build.mjs'), copy);
+      const requireFromCopy = createRequire(copy);
+      const unresolvable = ['exceljs/dist/exceljs.min.js', 'fflate'].filter((specifier) => {
+        try {
+          requireFromCopy.resolve(specifier);
+          return false;
+        } catch {
+          return true;
+        }
+      });
+      // Precondition: this host has no stray node_modules above the temp dir.
+      expect(unresolvable.length).toBeGreaterThan(0);
+
+      const result = spawnSync(process.execPath, [copy], { cwd: tree, encoding: 'utf8', timeout: 20_000 });
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain(`[build] missing build dependency: ${unresolvable.join(', ')}`);
+      expect(result.stderr).toContain('run `npm install` first');
+      expect(result.stdout).not.toContain('[build] tsc');
+      expect(existsSync(join(tree, 'dist'))).toBe(false);
+    } finally {
+      rmSync(tree, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/test/wiki-home-index.test.ts b/test/wiki-home-index.test.ts
new file mode 100644
index 00000000..71b59f26
--- /dev/null
+++ b/test/wiki-home-index.test.ts
@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Static guard: the wiki Home page's "Everything in the manual" index
+ * links every page the sidebar lists.
+ *
+ * docs/wiki/ is mirrored to the GitHub wiki, where _Sidebar.md shows on every page and
+ * Home.md calls itself the whole manual. A new page added to the sidebar alone (Tile
+ * Grid, Custom Model Endpoints) silently dropped out of that index. Compared by link
+ * target, since the two files label some pages differently.
+ *
+ * Port: N/A (pure static analysis).
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const wiki = resolve(import.meta.dirname, '..', 'docs', 'wiki');
+const read = (name: string) => readFileSync(resolve(wiki, name), 'utf8');
+
+/** Internal wiki page targets of `[label](Target)` links, external URLs excluded. */
+const pageTargets = (markdown: string): Set<string> =>
+  new Set(
+    [...markdown.matchAll(/\]\(([^)\s#]+)(?:#[^)]*)?\)/g)]
+      .map((m) => m[1])
+      .filter((target) => !/^[a-z]+:/i.test(target) && target !== 'Home')
+  );
+
+describe('wiki Home index', () => {
+  it('links every page the sidebar lists', () => {
+    const sidebar = pageTargets(read('_Sidebar.md'));
+    expect(sidebar.size).toBeGreaterThan(20);
+    const index = read('Home.md').split('## Everything in the manual')[1] ?? '';
+    expect(index, 'Home.md has an "Everything in the manual" section').not.toBe('');
+    const indexed = pageTargets(index);
+    const missing = [...sidebar].filter((target) => !indexed.has(target));
+    expect(missing, 'add these to the "Everything in the manual" tables in docs/wiki/Home.md').toEqual([]);
+  });
+});