Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: correct stale file paths cited in source comments and add a reference guard (#12408)

[._.]/ Adam Eivy6d22371dbd9a
diff --git a/scripts/migrations/044-hunyuan-fp32-deprecated.js b/scripts/migrations/044-hunyuan-fp32-deprecated.js
index 629980683e..22e6d8c255 100644
--- a/scripts/migrations/044-hunyuan-fp32-deprecated.js
+++ b/scripts/migrations/044-hunyuan-fp32-deprecated.js
@@ -1,7 +1,7 @@
/**
* Pin HunyuanVideo to fp32 + mark it deprecated on the macOS video catalog.
*
- * `scripts/generate_hunyuan.py` previously defaulted to fp16, which silently
+ * The Hunyuan generate script (since removed) previously defaulted to fp16, which silently
* trips an MPS matmul assertion ("Destination NDArray and Accumulator NDArray
* cannot have different datatype") within ~2s of the first forward pass.
* Verified empirically that bf16 hits the same assertion — only fp32 across
diff --git a/scripts/migrations/078-song-recording-pitch-analysis.js b/scripts/migrations/078-song-recording-pitch-analysis.js
index 247380fffc..6fd515fd06 100644
--- a/scripts/migrations/078-song-recording-pitch-analysis.js
+++ b/scripts/migrations/078-song-recording-pitch-analysis.js
@@ -1,7 +1,7 @@
/**
* Registration stub for per-take pitch analysis on song recordings (#1027).
*
- * The `Recording` shape (`server/services/songs.js`) gained two OPTIONAL,
+ * The `Recording` shape (`server/services/rounds.js`, formerly `songs.js`) gained two OPTIONAL,
* absent-tolerant fields — `pitchTrack` (a bounded, downsampled tuner trace) and
* `accuracy` (a color-match summary) — so the tuner history and grading aren't
* recomputed on every open. Both are additive: a legacy take simply has neither
diff --git a/scripts/migrations/079-song-training-progress.js b/scripts/migrations/079-song-training-progress.js
index 88f7a71a00..0d7e9a86d4 100644
--- a/scripts/migrations/079-song-training-progress.js
+++ b/scripts/migrations/079-song-training-progress.js
@@ -2,7 +2,7 @@
* Registration stub for song training progress (#1028 — the capstone of the
* #1021 song-system umbrella).
*
- * The song shape (`server/services/songs.js`) gained one OPTIONAL,
+ * The song shape (`server/services/rounds.js`, formerly `songs.js`) gained one OPTIONAL,
* absent-tolerant field — `progress` (`{ history: { <scope>: [attempt…] } }`),
* a bounded per-scope rolling accuracy history for the memorize/learn/track
* training mode. It's additive: a legacy song simply has no `progress` field,
diff --git a/scripts/migrations/120-rename-songs-to-rounds-data.js b/scripts/migrations/120-rename-songs-to-rounds-data.js
index 8e1c4d09cb..c1c23a6769 100644
--- a/scripts/migrations/120-rename-songs-to-rounds-data.js
+++ b/scripts/migrations/120-rename-songs-to-rounds-data.js
@@ -5,7 +5,7 @@
* The a cappella workbench was renamed from "Songs" to "Rounds" (its real
* subject is musical rounds — Hey Ho Nobody Home, the quodlibet trio, the
* 500 Miles worked example). The full-stack rename moved the service from
- * `server/services/songs.js` → `rounds.js` (STATE_PATH `data/songs.json` →
+ * `songs.js` → `rounds.js` (STATE_PATH `data/songs.json` →
* `data/rounds.json`, top-level key `songs: []` → `rounds: []`) and the per-
* record `partnerSongIds` field → `partnerRoundIds`, plus the route
* `/api/songs` → `/api/rounds`. Existing installs already have their data in
diff --git a/scripts/setup-cert.js b/scripts/setup-cert.js
index 982cfa9a79..42d3595402 100644
--- a/scripts/setup-cert.js
+++ b/scripts/setup-cert.js
@@ -201,7 +201,7 @@ function trySelfSigned() {
// Implicit fallback gate. Decides what to do (and what to tell the user) when
// the Tailscale provisioning path didn't run / failed. Three cases — picked by
-// what's actually on disk, because `server/lib/tailscale-https.js` boots HTTPS
+// what's actually on disk, because `lib/tailscale-https.js` boots HTTPS
// purely on cert+key file presence (not on meta.mode):
// 1. Self-signed cert on disk → renewal path (regenerate on IP changes).
// 2. Tailscale (or unknown-mode) cert on disk → keep the existing cert in
diff --git a/server/lib/aiToolkit/runner.js b/server/lib/aiToolkit/runner.js
index e85203238a..dd8ba80abe 100644
--- a/server/lib/aiToolkit/runner.js
+++ b/server/lib/aiToolkit/runner.js
@@ -45,7 +45,7 @@ function deriveRequestCapabilities({ prompt, screenshots, requestCapabilities })
//
// The win32 branch is gated on `instanceof ChildProcess`: stopRun/deleteRun
// below call this with whatever was registered via registerExternalRun,
-// which can be a node-pty `IPty` TUI session (server/lib/tuiPromptRunner.js,
+// which can be a node-pty `IPty` TUI session (server/services/tuiPromptRunner.js,
// via the host's registerActiveRun) — it also exposes `.kill()`/`.pid`, but
// a raw `taskkill` against its pid bypasses node-pty's own Windows teardown
// (releasing its native ConPTY handle), leaking it. Any non-ChildProcess
diff --git a/server/lib/eidoverseProxyRoutes.js b/server/lib/eidoverseProxyRoutes.js
index c42166dedf..58b510aa97 100644
--- a/server/lib/eidoverseProxyRoutes.js
+++ b/server/lib/eidoverseProxyRoutes.js
@@ -1,5 +1,5 @@
/**
- * Root paths the Eidoverse Worlds sequencer owns (from its server/routes.ts
+ * Root paths the Eidoverse Worlds sequencer owns (from its routes.ts
* matchers: exact + prefix). Import-free leaf so Vite, drift guards, and the
* reverse-proxy can share one list without dragging Express into the graph.
*
diff --git a/server/lib/shotGrammar.js b/server/lib/shotGrammar.js
index 95edda8e81..4341cb5f5a 100644
--- a/server/lib/shotGrammar.js
+++ b/server/lib/shotGrammar.js
@@ -6,7 +6,7 @@
*
* Pure and dependency-free (no imports) so it's shared without a cycle by the
* three layers that touch the shot shape:
- * - server/lib/sceneExtractor.js — sanitizes LLM-emitted shots
+ * - server/services/sceneExtractor.js — sanitizes LLM-emitted shots
* - server/lib/validation.js — the Zod enum for the storyboards stage shot schema
* - server/lib/editorial/checkRegistry.js — the visual.shot-continuity check
* reasons over `shotType` (monotony) + `screenDirection` (180°-rule axis reversal)
diff --git a/server/lib/tuiHandshake.js b/server/lib/tuiHandshake.js
index fce44ee2cb..912330d47c 100644
--- a/server/lib/tuiHandshake.js
+++ b/server/lib/tuiHandshake.js
@@ -1,7 +1,7 @@
/**
* Shared TUI invocation + paste-handshake constants.
*
- * Two execution paths need these: `server/lib/tuiPromptRunner.js` (one-shot
+ * Two execution paths need these: `server/services/tuiPromptRunner.js` (one-shot
* prompts from the central handler) and `server/services/agentTuiSpawning.js`
* (long-running CoS agents). Both shell into the same set of TUI binaries
* (Claude Code, Codex, Antigravity) and use identical PTY-paste choreography to
diff --git a/server/services/beeperClient.js b/server/services/beeperClient.js
index 6da2642d03..1d8283e428 100644
--- a/server/services/beeperClient.js
+++ b/server/services/beeperClient.js
@@ -3,11 +3,8 @@
*
* Raw `fetch`, deliberately NOT `@beeper/desktop-api` — the published SDK lags
* the live API and exposes no `Account.status`, no `loginID`, no `/v1/bridges`;
- * `GET /v1/spec` on the running instance is the authoritative reference (see
- * the API-surface research note, `docs/research/2026-08-31-beeper-api-surface.md`
- * on the `research/beeper` branch — not merged onto `beeper/integration`, so the
- * path is not resolvable from this branch alone). Every other Beeper feature
- * (#30-#37) is built on this module.
+ * `GET /v1/spec` on the running instance is the authoritative reference.
+ * Every other Beeper feature (#30-#37) is built on this module.
*
* `server/lib/safeUrlFetch.js` cannot wrap this: it blocks loopback in both
* postures by design, and Beeper Desktop's whole API IS a loopback service
@@ -223,9 +220,7 @@ export async function resolveBeeperConfig({ baseUrl, token } = {}) {
* `POST /v1/assets/download` does NOT share this — it answers `200` with an
* `{ error }` body instead, so this `502` branch never fires for it; that
* shape is validated separately in `downloadAsset` below. Every other status
- * follows the spec's documented meaning (see the
- * API-surface research note, `docs/research/2026-08-31-beeper-api-surface.md`
- * §7, on the `research/beeper` branch); `code` is never a published enum, so
+ * follows the spec's documented meaning; `code` is never a published enum, so
* it rides along under `details` for logging only.
*/
export function mapBeeperResponseError(status, body, { isAssetEndpoint = false, retryEligible = true } = {}) {
diff --git a/server/services/creativeDirector/local.js b/server/services/creativeDirector/local.js
index 0dc5b1c870..1285fa342a 100644
--- a/server/services/creativeDirector/local.js
+++ b/server/services/creativeDirector/local.js
@@ -17,7 +17,7 @@
*
* The first PG init runs a one-time, marker-gated import of any legacy
* data/creative-director-projects.json rows into the table (see
- * scripts/migrateCreativeDirectorToDB.js), so the boot recovery scan — the first
+ * server/scripts/migrateCreativeDirectorToDB.js), so the boot recovery scan — the first
* caller — sees migrated projects.
*
* `trimRuns` is re-exported from projectsLogic.js for the migration + any caller
@@ -46,7 +46,7 @@ const { selectBackend, getBackendName } = createRecordStoreBackendSelector({
loadDbBackend: () => import('./projectsDB.js'),
requireDbMessage: 'Creative Director requires PostgreSQL — run `npm run setup:db` (dev/test only: set PGMODE=file in .env; the launcher maps it to MEMORY_BACKEND=file for the unsupported file backend)',
onDbReady: async () => {
- const { migrateCreativeDirectorToDB } = await import('../../scripts/migrateCreativeDirectorToDB.js');
+ const { migrateCreativeDirectorToDB } = await import('../../server/scripts/migrateCreativeDirectorToDB.js');
await migrateCreativeDirectorToDB();
},
});
diff --git a/server/services/imageGen/fabricationGuard.js b/server/services/imageGen/fabricationGuard.js
index 258b92c9c6..d6313ccdac 100644
--- a/server/services/imageGen/fabricationGuard.js
+++ b/server/services/imageGen/fabricationGuard.js
@@ -71,7 +71,7 @@ export const noFabricationClause = (toolName) =>
*/
export async function checkFabrication(scratchDir, toolName) {
// Recursive listing rather than a hand-rolled walk so the rule is the same at
- // every depth — a `scripts/draw.py` or a nested `__pycache__` counts exactly
+ // every depth — a `draw.py` or a nested `__pycache__` counts exactly
// as much as one dropped beside the output.
//
// A scan that FAILS is not a scan that found nothing. ENOENT is a real clean
diff --git a/server/services/imessageScheduler.js b/server/services/imessageScheduler.js
index de65751075..5357d63b97 100644
--- a/server/services/imessageScheduler.js
+++ b/server/services/imessageScheduler.js
@@ -3,7 +3,7 @@
*
* Registers an interval job that periodically runs the incremental iMessage
* ingestion (see imessageSync.js). Shape shared with the Signal/Spotify/YouTube
- * schedulers via `createSyncScheduler` (server/lib/createSettingsGatedSyncScheduler.js).
+ * schedulers via `createSyncScheduler` (server/services/createSettingsGatedSyncScheduler.js).
*
* OFF by default: the scheduler is only registered when the user has opted in via
* the iMessage Settings drawer on Comms → Messages → iMessage
diff --git a/server/services/runner.js b/server/services/runner.js
index 2855ef6f43..ab84010fa0 100644
--- a/server/services/runner.js
+++ b/server/services/runner.js
@@ -26,7 +26,7 @@ import {
requireToolkit,
} from '../lib/aiToolkitState.js';
-// Re-exported so `server/lib/promptRunner.js` can import via the runner
+// Re-exported so `server/services/promptRunner.js` can import via the runner
// (its existing dependency boundary). The canonical home is now
// `server/lib/providerModels.js` — that's where `server/lib/tuiHandshake.js`
// imports from directly (lib→lib, no service layer violation).
@@ -77,7 +77,7 @@ export async function createRun(options) {
/**
* Returns the configured runs directory. Other execution paths
- * (`server/lib/tuiPromptRunner.js`) need this to write output + metadata
+ * (`server/services/tuiPromptRunner.js`) need this to write output + metadata
* under the same tree as `createRun` — without it, runs configured with a
* non-default `dataDir` end up split across two trees and `/runs` replay
* breaks.
diff --git a/server/services/signalScheduler.js b/server/services/signalScheduler.js
index accb561e4c..ac1ab70a8a 100644
--- a/server/services/signalScheduler.js
+++ b/server/services/signalScheduler.js
@@ -3,7 +3,7 @@
*
* Registers an interval job that periodically runs the incremental Signal
* ingestion (see signalSync.js). Shape shared with the iMessage/Spotify/YouTube
- * schedulers via `createSyncScheduler` (server/lib/createSettingsGatedSyncScheduler.js).
+ * schedulers via `createSyncScheduler` (server/services/createSettingsGatedSyncScheduler.js).
*
* OFF by default: the scheduler is only registered when the user has opted in via
* Settings → Signal (`settings.signal.enabled`). Reading the SQLCipher DB needs
diff --git a/server/services/spotifyScheduler.js b/server/services/spotifyScheduler.js
index 703a1792a7..1067841637 100644
--- a/server/services/spotifyScheduler.js
+++ b/server/services/spotifyScheduler.js
@@ -4,7 +4,7 @@
* Registers an interval job that periodically runs the incremental Spotify
* recently-played ingestion (see spotifySync.js). Shape shared with the
* iMessage/Signal/YouTube schedulers via `createSyncScheduler`
- * (server/lib/createSettingsGatedSyncScheduler.js).
+ * (server/services/createSettingsGatedSyncScheduler.js).
*
* OFF by default: the scheduler is only registered when the user has connected
* Spotify AND opted in via Settings → Spotify (`settings.spotify.enabled`). The
diff --git a/server/services/storyBuilderRunner.js b/server/services/storyBuilderRunner.js
index 69cde5c6a3..d03dd9d32c 100644
--- a/server/services/storyBuilderRunner.js
+++ b/server/services/storyBuilderRunner.js
@@ -13,7 +13,7 @@
* coalesces onto the in-flight run. Late-connecting clients receive the last
* broadcast frame via attachSseClient's replay grace window in lib/sseUtils.js.
*
- * Frame shapes (consumed by client/src/hooks/useStoryStepProgress.js):
+ * Frame shapes (consumed by client/src/hooks/useStoryStepRuns.jsx):
* { type: 'start', runId, stepId, op }
* { type: 'progress', label, phase } // phase labels during the run
* { type: 'complete', runId, stepId, op, changes, rationale, providerId, model }
diff --git a/server/services/universeBuilder/db.js b/server/services/universeBuilder/db.js
index 4a740cf6ef..7393589838 100644
--- a/server/services/universeBuilder/db.js
+++ b/server/services/universeBuilder/db.js
@@ -159,7 +159,7 @@ export async function listStyles() {
* Reads the `deleted` MIRROR COLUMN, not the JSONB flag listUniverses filters
* on. Those cannot disagree: every write path derives both from the same
* `record` in the same statement with the same predicate — `writeRaw` above and
- * the one-time file import (`scripts/migrateUniversesToDB.js`) each bind
+ * the one-time file import (`server/scripts/migrateUniversesToDB.js`) each bind
* `record.deleted === true` into the column, and the sanitizer the service
* filters on (`sanitizeSoftDeleteFields`, lib/syncWire.js) computes
* `raw?.deleted === true` off the same field. There is no third writer, and no
diff --git a/server/services/youtubeScheduler.js b/server/services/youtubeScheduler.js
index a62cd6cff8..0131ab1b7a 100644
--- a/server/services/youtubeScheduler.js
+++ b/server/services/youtubeScheduler.js
@@ -4,7 +4,7 @@
* Registers an interval job that periodically runs the CDP scrape of the
* signed-in YouTube history page (see youtubeSync.js). Shape shared with the
* iMessage/Signal/Spotify schedulers via `createSyncScheduler`
- * (server/lib/createSettingsGatedSyncScheduler.js).
+ * (server/services/createSettingsGatedSyncScheduler.js).
*
* OFF by default: only registered when the user has opted in via Settings →
* YouTube (`settings.youtube.enabled`) AND is logged into YouTube in the managed
diff --git a/server/sourceFileReferences.test.js b/server/sourceFileReferences.test.js
new file mode 100644
index 0000000000..d3e657a435
--- /dev/null
+++ b/server/sourceFileReferences.test.js
@@ -0,0 +1,75 @@
+/**
+ * Tree-wide guard: a repo-root-anchored file path cited in a production source
+ * comment must name a git-tracked file (#12408).
+ *
+ * PortOS comments are written for coding agents, which follow a cited path to
+ * learn a contract. Modules moved from `server/lib/` to `server/services/` and
+ * the comments that named the old path went stale with nothing to catch them.
+ *
+ * Scanned (comment lines only): git-tracked non-test .js/.jsx/.mjs/.cjs under server/, client/src/
+ * and scripts/. Referenced: paths anchored at `server/`, `client/src/`,
+ * `scripts/` or `docs/(research|decisions|plans)/` ending in a file extension.
+ * Placeholder examples (stem of one character, or foo|bar|baz|example) are
+ * skipped. There is no allowlist: fix the path or drop the citation.
+ */
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const REFERENCE = /(?<![\w./-])((?:server|client\/src|scripts|docs\/(?:research|decisions|plans))\/[\w./-]*[\w-]\.[A-Za-z][A-Za-z0-9]*)(?![\w-])/g;
+const PLACEHOLDER_STEM = /^(?:.|foo|bar|baz|example)$/;
+const SOURCE = /\.(?:jsx?|mjs|cjs)$/;
+// Comment text only: a path in a string literal is runtime data (a spawn arg, a
+// test-file list), not a pointer for the reader.
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*)|\s\/\/\s/;
+const TEST_FILE = /\.test\.[cm]?jsx?$/;
+
+const stemOf = (path) => {
+ const base = path.slice(path.lastIndexOf('/') + 1);
+ return base.slice(0, base.indexOf('.') === -1 ? undefined : base.indexOf('.'));
+};
+
+export function findBrokenReferences(src, tracked) {
+ const broken = [];
+ src.split('\n').forEach((line, i) => {
+ if (!COMMENT_LINE.test(line)) return;
+ for (const match of line.matchAll(REFERENCE)) {
+ const ref = match[1].replace(/\.+$/, '');
+ if (PLACEHOLDER_STEM.test(stemOf(ref))) continue;
+ if (!tracked.has(ref)) broken.push({ line: i + 1, ref });
+ }
+ });
+ return broken;
+}
+
+const gitFiles = () => execFileSync('git', ['ls-files'], {
+ cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+}).split('\n').filter(Boolean);
+
+describe('source file references (#12408)', () => {
+ it('flags a moved path and ignores placeholder examples', () => {
+ const tracked = new Set(['server/services/tuiPromptRunner.js']);
+ expect(findBrokenReferences('// see server/lib/tuiPromptRunner.js\n// server/services/tuiPromptRunner.js', tracked))
+ .toEqual([{ line: 1, ref: 'server/lib/tuiPromptRunner.js' }]);
+ expect(findBrokenReferences('// `docs/decisions/x.md` and docs/a/b.md and server/lib/foo.js', tracked)).toEqual([]);
+ });
+
+ it('every cited repo path in production sources exists', () => {
+ const files = gitFiles();
+ expect(files.length).toBeGreaterThan(100);
+ const tracked = new Set(files);
+ const offenders = [];
+ for (const file of files) {
+ if (!SOURCE.test(file) || TEST_FILE.test(file)) continue;
+ if (!/^(?:server|client\/src|scripts)\//.test(file)) continue;
+ for (const { line, ref } of findBrokenReferences(readFileSync(join(REPO_ROOT, file), 'utf8'), tracked)) {
+ offenders.push(`${file}:${line} -> ${ref}`);
+ }
+ }
+ expect(offenders).toEqual([]);
+ });
+});