fix: resolve a leading ~ in every configured path, not just some

[selfcontained]

Problem

Dispatch reads ten path-ish values from configuration. Only TLS_CERT and TLS_KEY expanded a leading ~, via a local expandHome() helper in config.ts. MEDIA_ROOT did not.

So the same ~/foo string meant two different things depending on which variable you wrote it in. For media it became a directory literally named ~ beside the process working directory — writes succeeded, and nothing could ever find them again. Silent, not loud.

Configuration is not read by a shell, so a ~ arrives as a literal character; the only question is whether the program expands it. Dispatch had already answered yes — resolveTilde exists in shared/lib/ and is used for user-supplied paths in routes/jobs.ts, routes/templates.ts and routes/system.ts — it just wasn't applied to configured paths consistently.

Before / after, from the same live endpoint

An agent row with media_dir = '~/dispatch-devtest-media/agt_legacytilde' and the real file present at the expanded location:

	GET /api/v1/agents/{id}/media/legacy-shot.png	dispatch_list_media → filePath
before	404 {"error":"Media file not found."}	~/dispatch-devtest-media/agt_legacytilde/legacy-shot.png
after	200, correct body	/Users/brad/dispatch-devtest-media/agt_legacytilde/legacy-shot.png

The fix

One resolver, applied everywhere a path comes from configuration.

• apps/server/src/shared/lib/resolve-tilde.ts gains resolveConfiguredPath(value) — resolveTilde plus path.resolve. It builds on the helper already in the repo rather than adding a third one.
• Applied at every configured-path site: MEDIA_ROOT, TLS_CERT/TLS_KEY, the four store paths (DISPATCH_APPLIED_MIGRATIONS_STORE_PATH, DISPATCH_ASSISTED_UPDATE_STORE_PATH, DISPATCH_RELEASE_CANDIDATE_STORE_PATH, DISPATCH_RELEASE_STORE_PATH), DISPATCH_RELEASE_CACHE_DIR, DISPATCH_RUNTIME_PATH, DISPATCH_SERVICE_DEFINITION_PATH, DISPATCH_RELEASE_AUTHORING_REPO_DIR, and DISPATCH_SERVER_DIR.
• resolveMediaDir() and listMedia() also resolve the stored media_dir column, which inherits its value from mediaRoot.
• config.ts drops its local expandHome(); process.env.HOME ?? "/tmp" becomes os.homedir().
• docs/10-operations-runbook.md — the runbook documented MEDIA_ROOT's default as ~/.dispatch/media, which is both wrong (the code default is absolute) and precisely the value that triggers the bug when copied into .env. Corrected.

Behaviour is unchanged for existing installs: every default was already absolute via os.homedir(), so only the configured branch is affected, and path.resolve on an absolute path is a no-op.

Why there is no migration

Earlier revisions of this branch carried a required assisted update, a bin/migrate-legacy-media bash migrator and a manifest. All removed:

• Dispatch never shipped a tilde default. config.ts has used path.join(HOME, ".dispatch", "media") since the initial commit (v0.11.12), and bin/install-dispatch.sh never writes MEDIA_ROOT into .env. A stock install cannot reach the bug.
• The vector was the docs, corrected above.
• No stranded data exists. On the one machine known to have hit this, MEDIA_ROOT is unset and the only literal-tilde directory present is empty — zero files.

A required update that stops every agent to migrate nothing was the wrong trade.

Verification

• pnpm run check clean; pnpm run test — 2808 passing; pnpm run test:e2e — 181 passed, 12 skipped.
• Live against an isolated dev stack: server boots healthy with the resolver on every config path; the media before/after above, including the dispatch_share write path creating no literal ~ directory.
• apps/server/test/configured-paths.test.ts covers both resolution shapes present in the codebase — one store resolving per call, one at module load — asserting the file lands at the expanded location and that no ~ directory is created. All three were confirmed to fail against the unfixed stores.
• Helper-level coverage in apps/server/test/resolve-tilde.test.ts.

🤖 Generated with Claude Code