commit 6a947f4363450a40cd14314b241c3d673a869970
parent 316b8c43933406205651ab53810f75c71310c6e7
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Mon, 28 Sep 2026 02:46:35 -0400
docs: the seeded-worker claim corrected; WORKTREES points at the one port table (review Q5, L4)
- Q5: AGENTS.md, the docker/entrypoint.sh comment (comment only, the seed
is unchanged) and RUNNING_IN_DOCKER said a settings file with no workers
means zero workers. With no `workers` key, or no file, getSettings()
synthesizes `parallelTranscriptions` (default 2) enabled whisper.cpp
workers — two CPU slots, never parakeet in the Vulkan image; zero workers
only for a file that says `"workers": []`. That is why the seed pins one
worker for the image's engine.
- L4: WORKTREES.md's hand-kept port table (missing the three newly offset
ports, the homepage called "(hub)") is a pointer to ENVIRONMENT.md →
Ports, generated from ports.mjs, whose descriptions gain the `pnpm dev:*`
commands the table had. umtool's playwright config comment names
ports.mjs instead of `worktree.mjs PORT_BASES`.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Diffstat:
7 files changed, 34 insertions(+), 36 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -195,8 +195,12 @@ Two things the image cannot bake, and the reasons matter:
the `site` service serves.
- **whisper models.** 142 MB to 3 GB, and the choice is the operator's.
`docker/entrypoint.sh` fetches one on first boot — and seeds a `settings.json`
- carrying one enabled worker, because `defaults()` returns `workers: []` and zero
- workers means auto-transcribe silently does nothing.
+ carrying one enabled worker for the image's engine: with no `workers` key (or no
+ file), `getSettings()` synthesizes `parallelTranscriptions` (default 2) enabled
+ workers of the default app, whisper.cpp — two CPU whisper slots, and never
+ parakeet in the Vulkan image. (`defaults()` alone has `workers: []`; zero workers
+ — auto-transcribe silently doing nothing — only happens for a file that says
+ `"workers": []`.)
`ARCHILYZER_IDLE_BOOT=1` boots the editor without arming the heartbeat or any of
the four auto-queue lane runners (`common/lib/idleBoot.ts`) — for pointing a fresh
diff --git a/ENVIRONMENT.md b/ENVIRONMENT.md
@@ -95,17 +95,17 @@ Every local server's default port, from `common/lib/ports.mjs`. The primary chec
| Variable | Default | What it does | Read by |
|---|---|---|---|
-| `EDITOR_PORT` | `3001` | Editor real dev/start. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
+| `EDITOR_PORT` | `3001` | Editor real dev/start (`pnpm dev:editor`). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `PORT` | `3011` | Editor test server + Playwright editor baseURL. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `EXPORT_PORT` | `3010` | Export server launched by the editor e2e. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
-| `EXPORT_DEV_PORT` | `3000` | Export real dev. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
+| `EXPORT_DEV_PORT` | `3000` | Export real dev (`pnpm dev:export`). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `EXPORT_E2E_PORT` | `3020` | Export's own Playwright suite. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `OLLAMA_STUB_PORT` | `11435` | Digest-lane stub server in the editor e2e suite. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
-| `HOMEPAGE_DEV_PORT` | `3030` | Homepage real dev. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
+| `HOMEPAGE_DEV_PORT` | `3030` | Homepage real dev (`pnpm dev:homepage`). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `HOMEPAGE_PORT` | `3031` | Homepage static `serve out` (start:homepage). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `HOMEPAGE_E2E_PORT` | `3040` | Homepage's own Playwright suite. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `HUB_PORT` | `3041` | Export's hub Playwright suite (e2e:hub). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
-| `UMTOOL_PORT` | `3050` | Umtool real dev/start. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
+| `UMTOOL_PORT` | `3050` | Umtool real dev/start (`pnpm dev:umtool`). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `UMTOOL_E2E_PORT` | `3051` | Umtool's own Playwright suite. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `EDITOR_STUB_PORT` | `3052` | Stub editor the umtool e2e suite fetches clips from. A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
| `ORIGIN_B_PORT` | `4610` | Export's two-origin suite: the member site (e2e:2origin). A worktree adds its offset (`pnpm wt list`). | common/lib/ports.mjs |
diff --git a/RUNNING_IN_DOCKER.md b/RUNNING_IN_DOCKER.md
@@ -29,9 +29,12 @@ apps. Afterwards, `docker compose up -d` is seconds.
On first boot the container also:
- creates the corpus, config, models and builds volumes;
-- writes a `settings.json` **with one enabled whisper.cpp worker** (a settings
- file with zero workers means zero transcription slots, and auto-transcribe
- would report `no-workers` and quietly do nothing);
+- writes a `settings.json` **with one enabled worker for the image's engine**
+ (whisper.cpp here, parakeet.cpp in the Vulkan image). With no `workers` key, or
+ no file, `getSettings()` would synthesize `parallelTranscriptions` (default 2)
+ enabled whisper.cpp workers — two CPU slots, and never parakeet; a file that
+ says `"workers": []` has zero slots, and auto-transcribe would report
+ `no-workers` and quietly do nothing;
- downloads the `base.en` whisper model (~142 MB) into the models volume.
Every key that `settings.json` can carry, with its default, is in [SETTINGS.md](SETTINGS.md).
diff --git a/WORKTREES.md b/WORKTREES.md
@@ -15,21 +15,10 @@ Each worktree gets an offset of `index * 100`, where `index` is the worktree's p
`git worktree list`. The **main** worktree is always first, so it keeps the original
defaults — nothing changes for the primary checkout.
-| Env var | Base (main) | Used by |
-|---|---|---|
-| `EDITOR_PORT` | 3001 | editor real dev/start (`pnpm dev:editor`) |
-| `PORT` | 3011 | editor test server + Playwright editor baseURL |
-| `EXPORT_PORT` | 3010 | export server launched by the editor e2e suite |
-| `EXPORT_DEV_PORT` | 3000 | export real dev (`pnpm dev:export`) |
-| `EXPORT_E2E_PORT` | 3020 | export's own Playwright suite |
-| `OLLAMA_STUB_PORT` | 11435 | digest-lane stub server in the editor e2e suite |
-| `HOMEPAGE_DEV_PORT` | 3030 | homepage (hub) real dev (`pnpm dev:homepage`) |
-| `HOMEPAGE_PORT` | 3031 | homepage static `serve out` (`pnpm start:homepage`) |
-| `HOMEPAGE_E2E_PORT` | 3040 | homepage's own Playwright suite |
-| `UMTOOL_PORT` | 3050 | um-clip triage tool real dev (`pnpm dev:umtool`) |
-| `UMTOOL_E2E_PORT` | 3051 | umtool's own Playwright suite |
-| `EDITOR_STUB_PORT` | 3052 | stub editor the umtool e2e suite fetches clips from |
-| `PLAYWRIGHT_BASE_URL` | `http://localhost:3011` | node-side fetches in specs |
+The port table itself is `common/lib/ports.mjs` — one copy, which `scripts/worktree.mjs`
+offsets and `pnpm archilyzer doctor` reports. Every port, its base and what uses it is in
+**[ENVIRONMENT.md → Ports](ENVIRONMENT.md#ports)** (generated from it). The injector also
+sets `PLAYWRIGHT_BASE_URL` (`http://localhost:<PORT>`) for node-side fetches in specs.
So worktree #1 runs editor on **3101**, test server on **3111**, export on **3110**, etc.
The hundreds digit is the worktree index. The allocator never overrides a variable already
diff --git a/common/lib/ports.mjs b/common/lib/ports.mjs
@@ -32,17 +32,17 @@
/** @type {Readonly<Record<string, PortDecl>>} */
export const PORTS = Object.freeze({
- EDITOR_PORT: { base: 3001, what: "editor real dev/start" },
+ EDITOR_PORT: { base: 3001, what: "editor real dev/start (`pnpm dev:editor`)" },
PORT: { base: 3011, what: "editor test server + Playwright editor baseURL" },
EXPORT_PORT: { base: 3010, what: "export server launched by the editor e2e" },
- EXPORT_DEV_PORT: { base: 3000, what: "export real dev" },
+ EXPORT_DEV_PORT: { base: 3000, what: "export real dev (`pnpm dev:export`)" },
EXPORT_E2E_PORT: { base: 3020, what: "export's own Playwright suite" },
OLLAMA_STUB_PORT: { base: 11435, what: "digest-lane stub server in the editor e2e suite" },
- HOMEPAGE_DEV_PORT: { base: 3030, what: "homepage real dev" },
+ HOMEPAGE_DEV_PORT: { base: 3030, what: "homepage real dev (`pnpm dev:homepage`)" },
HOMEPAGE_PORT: { base: 3031, what: "homepage static `serve out` (start:homepage)" },
HOMEPAGE_E2E_PORT: { base: 3040, what: "homepage's own Playwright suite" },
HUB_PORT: { base: 3041, what: "export's hub Playwright suite (e2e:hub)" },
- UMTOOL_PORT: { base: 3050, what: "umtool real dev/start" },
+ UMTOOL_PORT: { base: 3050, what: "umtool real dev/start (`pnpm dev:umtool`)" },
UMTOOL_E2E_PORT: { base: 3051, what: "umtool's own Playwright suite" },
EDITOR_STUB_PORT: { base: 3052, what: "stub editor the umtool e2e suite fetches clips from" },
ORIGIN_B_PORT: { base: 4610, what: "export's two-origin suite: the member site (e2e:2origin)" },
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
@@ -47,14 +47,16 @@ mkdir -p \
# ---------------------------------------------------------------------------
# 2. Seed settings.json — with a worker.
#
-# defaults() in common/lib/settings.ts returns `workers: []`, and zero workers
-# means zero transcription slots: auto-transcribe reports `no-workers` and does
-# nothing at all, silently. A fresh container that looks healthy and transcribes
-# nothing is the worst possible first run, so the seed carries exactly one local
-# whisper.cpp worker.
+# With no `workers` key (or no file), getSettings() synthesizes
+# `parallelTranscriptions` (default 2) enabled workers of the default app,
+# whisper.cpp — two CPU whisper slots, and never parakeet in the Vulkan image.
+# (defaults() alone has `workers: []`; zero workers — auto-transcribe silently
+# doing nothing — only happens for a file that says `"workers": []`.) So the
+# seed carries exactly one local worker for the image's engine.
#
# Everything else is left out on purpose. getSettings() merges a partial file
-# over defaults(), so a short seed is a FEATURE: keys we don't write here keep
+# over defaults() (every key but `workers`, above), so a short seed is a
+# FEATURE: keys we don't write here keep
# tracking the app's own defaults as those move, instead of being frozen at
# whatever they were the day this image was built.
#
diff --git a/umtool/playwright.config.ts b/umtool/playwright.config.ts
@@ -6,8 +6,8 @@ const PORT = Number(process.env.UMTOOL_E2E_PORT ?? 3051);
// The editor stub's port. Named, because the queue lock's port PREFLIGHT only
// checks the ports it is given: a bare PORT+1 was outside it, so a second
// checkout's stub could already hold the port and this run would drive it. It
-// is in scripts/worktree.mjs PORT_BASES (so a worktree gets its own) and in
-// package.json's --ports spec (so the preflight sees it).
+// is in common/lib/ports.mjs (so scripts/worktree.mjs gives a worktree its own)
+// and in package.json's --ports spec (so the preflight sees it).
const STUB_PORT = Number(process.env.EDITOR_STUB_PORT ?? PORT + 1);
// The package is "type": "module", so there is no __dirname here.
const FIXTURE = path.join(path.dirname(fileURLToPath(import.meta.url)), ".e2e-song");
