cursedbelt 1.0.0 → 2.3.0

package/src/react/nav/SideNavCustomize.tsx

@@ -29,6 +29,7 @@ import { useDragReorder } from '../hooks/useDragReorder';
 import { NavItemMenu } from './NavItemMenu';
 import { type IconResolver, renderIcon } from './navShared';
 import { Tooltip } from '../components/Tooltip';
+import { TAP_TARGET } from '../lib/tapTarget';
 
 export interface ReorderableRowsProps {
   domains: NavDomain[];
@@ -98,7 +99,7 @@ export function RowCustomizeControls({
             // pointer affordance only and must NOT be a Tab stop, so keyboard users tab
             // cleanly through the nav links (a11y gotcha #NavItemMenu).
             tabIndex={-1}
-            className={`inline-flex size-6 cursor-grab items-center justify-center rounded text-muted-foreground hover:text-foreground ${'pointer-coarse:min-h-11 pointer-coarse:min-w-11'}`}
+            className={`inline-flex size-6 cursor-grab items-center justify-center rounded text-muted-foreground hover:text-foreground ${TAP_TARGET}`}
           >
             <GripVertical className='size-4' />
           </button>

package/src/react/palette/CommandPalette.tsx

@@ -42,6 +42,7 @@ import {
   CommandList,
 } from './Command';
 import { useShortcutRegistry } from './useShortcutRegistry';
+import { TAP_TARGET_HEIGHT } from '../lib/tapTarget';
 
 export interface CommandPaletteProps {
   /** The single navigation registry (task 13) — the palette's page source of truth. */
@@ -540,7 +541,7 @@ function PinsQuickBar({
             data-cb-pin-add=''
             tooltip='Pin this page'
             leftIcon={<Plus className='size-3.5' aria-hidden='true' />}
-            className='h-auto shrink-0 rounded-full border border-dashed border-border px-2.5 py-1 text-xs font-medium text-muted-foreground hover:bg-muted hover:text-foreground pointer-coarse:min-h-11'
+            className={`h-auto shrink-0 rounded-full border border-dashed border-border px-2.5 py-1 text-xs font-medium text-muted-foreground hover:bg-muted hover:text-foreground ${TAP_TARGET_HEIGHT}`}
           >
             Pin this page
           </Button>
@@ -616,7 +617,7 @@ function PinChip({
             }
           : undefined
       }
-      className='h-auto shrink-0 rounded-full border-border bg-surface px-2.5 py-1 text-xs font-medium text-foreground hover:bg-muted pointer-coarse:min-h-11'
+      className={`h-auto shrink-0 rounded-full border-border bg-surface px-2.5 py-1 text-xs font-medium text-foreground hover:bg-muted ${TAP_TARGET_HEIGHT}`}
     >
       {icon != null ? (
         <span

package/src/server/ctgr.ts

@@ -2,7 +2,7 @@
  * ctgr Hono transport — the server half of the GET-tunnel: the `unGETify` middleware
  * that decodes a `/ctgr<XX>` twin's query params back into the original request, and
  * the `buildRoutes` registrar that wires the real verb route and its GET twin from one
- * call. The codec is `cursedbelt/ctgr`; the browser side is `cursedbelt/client`.
+ * call. The codec re-exports from `cursedbelt/server`; the browser side is `cursedbelt/client`.
  *
  * Protection is unchanged and lives elsewhere by design: the getOnly-claim 403 keys
  * off the RAW request method (always GET on a twin) in the auth middleware, and the

package/src/server/drivers/pooledControlStores.pg.test.ts

@@ -31,6 +31,7 @@ const URL_ = process.env.CC_PG_URL;
 let sql: SQL;
 let pool: SaasPool;
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!URL_)('the shared control-plane stores against a real Postgres (04 §1)', () => {
   // 120s, not Bun's default 5s. This hook drops and re-creates a role, a database
   // and a whole migration chain against a REAL Postgres; on a shared 4-core CI

package/src/server/drivers/pooledIdentityStore.pg.test.ts

@@ -44,6 +44,7 @@ let store: RegistryIdentityStore;
 
 const NOW = '2026-07-26T00:00:00.000Z';
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!URL_)('the saas identity tier against a real Postgres (04 §1a)', () => {
   // 120s, not Bun's default 5s. This hook drops and re-creates a role, a database
   // and a whole migration chain against a REAL Postgres; on a shared 4-core CI

package/src/server/drivers/retentionPolicy.pg.test.ts

@@ -35,6 +35,7 @@ const URL_ = process.env.CC_PG_URL;
 let sql: SQL;
 let executor: StatementExecutor;
 
+// SKIPPED unless CC_PG_URL names a throwaway Postgres — this suite's subject IS the engine. `bun run test:pg` supplies one.
 describe.skipIf(!URL_)('the retention policy table against a real Postgres (D30)', () => {
   beforeAll(async () => {
     sql = new SQL(URL_ as string);

package/src/server/guard/argon2Binding.ts

@@ -167,7 +167,7 @@ export const registerArgon2idBinding = (binding: RawArgon2idBinding): void => {
  * module exists to prevent.
  *
  * The same indirection that hides the specifier from a bundler hides it from
- * every static import walker, so `cursedbelt/guard`'s peer map would report
+ * every static import walker, so the guard's peer map would report
  * this edge as absent. The pragma is what puts it back.
  *
  * @peer @node-rs/argon2

package/src/server/incidents/store.ts

@@ -21,9 +21,9 @@
  * (`checks.ts`) does not call `reconcile` at all for a check that threw.
  *
  * ── Where the file lives ────────────────────────────────────────────────────
- * Whatever `Database` the caller opens. The console keeps it under
- * `~/.app-managed/cursed-satellites/incidents/`, deliberately NOT in the metrics
- * database: metrics are capped, regenerable telemetry that trims on write, and
+ * Whatever `Database` the caller opens. The console keeps it in an incidents
+ * database of its own under the host's app-data root, deliberately NOT in the
+ * metrics database: metrics are capped, regenerable telemetry that trims on write, and
  * an incident is a governed record whose whole value is that it survives — most
  * of all across the restart a deploy of the console itself performs.
  */

package/src/server/index.ts

@@ -117,7 +117,7 @@ export {
 } from './jobs';
 // ── Media adapter (task 19): image rendering via sharp (lazy/optional peer) + ──
 //    video trim / probe / thumbnail via native ffmpeg. Also at the dedicated
-//    `cursedbelt/server/media` entry; sharp is imported lazily inside renderImage,
+//    media-bun entry below; sharp is imported lazily inside renderImage,
 //    so importing this barrel never loads the native binary.
 export {
   buildProbeArgs,

package/src/server/master-lock/masterLock.spec.ts

@@ -209,6 +209,22 @@ describe("the idle clock", () => {
 	});
 });
 
+/**
+ * 🔴 The two tests below declare their own budget, and it is not padding.
+ *
+ * Every `unlock()` runs a real argon2id verification — that IS the thing under test — and
+ * these two are the only ones in the file that do it in bulk: 9 attempts and 17 attempts.
+ * Measured 2026-09-13 on this machine: 4.5s and 7.2s against bun's DEFAULT per-test budget
+ * of 5000ms, so the second failed on every run and the first was one hiccup behind it. The
+ * file's header says it "leans on the repo's per-test budget"; this repo's `bunfig.toml`
+ * declares none, so that budget is 5s and the claim was simply false.
+ *
+ * Stated per test rather than raised in `bunfig.toml`, deliberately: a repo-wide 20s would
+ * buy these two nothing the line below does not, and would cost all 5,200 other tests the
+ * fast failure that tells you something is HUNG rather than slow.
+ */
+const KDF_BULK_MS = 20_000;
+
 describe("the guess throttle", () => {
 	test("five failures are free, the sixth costs a wait, and a success clears it", async () => {
 		let now = 1_000_000;
@@ -230,7 +246,7 @@ describe("the guess throttle", () => {
 		now += 30_001;
 		expect((await lock.unlock(VERIFIER)).ok).toBe(true);
 		expect(lock.status().retryAfterMs).toBe(0);
-	});
+	}, KDF_BULK_MS);
 
 	test("a windowed refusal does not advance the counter", async () => {
 		let now = 1_000_000;
@@ -242,7 +258,7 @@ describe("the guess throttle", () => {
 		// cost nothing.
 		const next = await lock.unlock("wrong");
 		expect(next.ok === false && next.retryAfterMs).toBe(60_000);
-	});
+	}, KDF_BULK_MS);
 });
 
 describe("rotation", () => {

package/src/server/master-lock/masterLock.ts

@@ -83,7 +83,7 @@ export interface MasterLockOptions {
 	 * The BOOTSTRAP record, as JSON, used only when the store is empty — the same shape as
 	 * {@link MasterLockRecord} with `idleMs` optional.
 	 *
-	 * It arrives 0600 in `~/.app-managed/deploy/secrets/<app>.env` as `MASTER_LOCK_SEED`,
+	 * It arrives as `MASTER_LOCK_SEED` in the app's own 0600 deploy-secrets env file,
 	 * copied from the vault's own `vault_keys` row, so the lock is armed from the first
 	 * request rather than from whenever somebody remembers to set one. A lock that has to
 	 * be configured before it protects anything protects nothing on the day it matters —

package/src/server/media-bun/image.spec.ts

@@ -19,6 +19,7 @@ async function jpeg(w: number, h: number, color = { r: 200, g: 50, b: 50 }): Pro
     .toBuffer();
 }
 
+// SKIPPED when the OPTIONAL `sharp` peer is not installed — it is this suite's subject. Runs by default when it is.
 describe.skipIf(!sharp)('renderImage (sharp)', () => {
   test('resize + format-convert → webp with the right dimensions (acceptance #8)', async () => {
     const src = await jpeg(400, 300);

package/src/server/media-bun/index.ts

@@ -1,4 +1,4 @@
-// cursedbelt/server/media (media-bun) — the Bun server adapter for the media-core
+// src/server/media-bun — the Bun server adapter, re-exported from `cursedbelt/server`, for the media-core
 // specs: image rendering via sharp (lazy/optional), video trim + probe + thumbnail
 // via native ffmpeg/ffprobe. App handlers keep auth, FsNode lookup, quota, and
 // storeFile; this owns the actual pixel/codec work.

package/src/server/media-bun/video.spec.ts

@@ -52,6 +52,7 @@ afterAll(() => {
   if (dir) rmSync(dir, { recursive: true, force: true });
 });
 
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
 describe.skipIf(!haveFfmpeg)('media-bun video (ffmpeg)', () => {
   test('probeMedia reads dimensions + duration', async () => {
     const meta = await probeMedia(source);

package/src/server/paths/appDataHome.spec.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "bun:test";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome, XDG_DATA_HOME_ENV } from "./appDataHome";
+
+/**
+ * The published-library defect this file is the gate for: a resolver that knows
+ * the name of a directory in one person's home. Every assertion below is either
+ * "the caller decides" or "the OS decides"; there is no third source.
+ */
+describe("the app-data home", () => {
+	it("takes an explicit argument over everything else", () => {
+		expect(
+			resolveAppDataHome({
+				override: "/srv/data",
+				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
+			}),
+		).toBe("/srv/data");
+	});
+
+	it("reads APP_DATA_HOME — the one env var — before any convention", () => {
+		expect(
+			resolveAppDataHome({
+				env: { [APP_DATA_HOME_ENV]: "/env/data", [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" },
+			}),
+		).toBe("/env/data");
+	});
+
+	it("honors XDG_DATA_HOME on every platform, macOS included", () => {
+		for (const platform of ["darwin", "linux"]) {
+			expect(resolveAppDataHome({ env: { [XDG_DATA_HOME_ENV]: "/xdg", HOME: "/home/x" }, platform })).toBe("/xdg");
+		}
+	});
+
+	it("falls back to the macOS convention, not to anybody's dotfolder", () => {
+		const resolved = resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "darwin" });
+		expect(resolved).toBe(join("/home/x", "Library", "Application Support"));
+	});
+
+	it("falls back to the XDG default path elsewhere", () => {
+		expect(resolveAppDataHome({ env: { HOME: "/home/x" }, platform: "linux" })).toBe(
+			join("/home/x", ".local", "share"),
+		);
+	});
+
+	// Whitespace is how an env var gets "set" by a shell script that meant to unset
+	// it; treating it as configuration points every app at the filesystem root.
+	it("treats a blank setting as no setting", () => {
+		expect(
+			resolveAppDataHome({
+				override: "  ",
+				env: { [APP_DATA_HOME_ENV]: " ", [XDG_DATA_HOME_ENV]: "", HOME: "/home/x" },
+				platform: "linux",
+			}),
+		).toBe(join("/home/x", ".local", "share"));
+	});
+
+	it("falls back to the process's own home when the env names none", () => {
+		expect(resolveAppDataHome({ env: {}, platform: "linux" })).toBe(join(homedir(), ".local", "share"));
+	});
+
+	/**
+	 * 🔴 The assertion this module exists for. It is deliberately a property of the
+	 * OUTPUT rather than of the source text, so it still holds if somebody
+	 * reintroduces the old folder through a variable, a `join`, or a constant.
+	 */
+	it("never resolves a previous generation's private directory", () => {
+		const envs: Array<Record<string, string | undefined>> = [
+			{},
+			{ HOME: "/home/x" },
+			{ HOME: "/home/x", [APP_DATA_HOME_ENV]: "/srv/data" },
+			{ HOME: "/home/x", [XDG_DATA_HOME_ENV]: "/xdg" },
+			// The previous generation's own env var must no longer steer anything: the
+			// value below is deliberately unlike any convention, so a resolver that
+			// still read this var could not produce a passing answer by accident.
+			{ HOME: "/home/x", APP_MANAGED_HOME: "/nowhere/inherited" },
+		];
+		for (const env of envs) {
+			for (const platform of ["darwin", "linux"]) {
+				const resolved = resolveAppDataHome({ env, platform });
+				expect(resolved).not.toContain("app-managed");
+				expect(resolved).not.toContain("code-retiring");
+				expect(resolved).not.toContain("Master-Docs");
+			}
+		}
+	});
+});

package/src/server/paths/appDataHome.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a machine keeps an app's data — as CONFIGURATION, never as a convention
+ * baked into the library.
+ *
+ * ## What this replaces, and why it is a defect rather than untidiness
+ *
+ * Until 2026-09-13 three live modules in this package joined the ambient home
+ * directory to a hardcoded dotfolder belonging to the previous generation: the
+ * retention store, the archive, and `resolveAppDataRoot`. This package is
+ * PUBLISHED. Anybody who installed it got a library that went looking for a
+ * directory in their home that has nothing to do with them, and — worse — wrote
+ * into it if it happened to exist.
+ *
+ * A library may not know the name of a directory in somebody's home. It may know
+ * two things: what the caller told it, and what the operating system says the
+ * convention is. That is the whole ladder below.
+ *
+ * ## The ladder
+ *
+ *   1. an explicit `override` — a `--data-root` flag, a host's own resolution;
+ *   2. `$APP_DATA_HOME` — the ONE env var, for a machine that keeps every app's
+ *      data under one root so a fleet-wide tool can see all of it at once;
+ *   3. `$XDG_DATA_HOME` — the user already told the OS where data goes;
+ *   4. the platform default: `~/Library/Application Support` on macOS,
+ *      `~/.local/share` everywhere else.
+ *
+ * `$XDG_DATA_HOME` is honored on macOS too. It is not the platform's own
+ * convention there, but a user who sets it has stated a preference, and a
+ * preference outranks a default on any platform.
+ *
+ * Nothing here touches the filesystem: it is a pure mapping from environment to
+ * path, so a caller can reason about the answer before creating anything, and a
+ * test can assert both platforms on one machine.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The one env var. A machine with a shared data root sets this and nothing else. */
+export const APP_DATA_HOME_ENV = "APP_DATA_HOME";
+
+/** The cross-desktop convention this honors ahead of the platform default. */
+export const XDG_DATA_HOME_ENV = "XDG_DATA_HOME";
+
+export interface ResolveAppDataHomeOptions {
+	/** An explicit answer from the caller. Wins outright — this is the "argument" half. */
+	readonly override?: string;
+	/** Environment to read. Injected by tests; defaults to the process's own. */
+	readonly env?: Record<string, string | undefined>;
+	/**
+	 * Platform to resolve for. Injected by tests so both branches are proved on one
+	 * machine; defaults to the running platform.
+	 */
+	readonly platform?: string;
+}
+
+/** Trimmed, or undefined — an env var set to whitespace is not a configuration. */
+function configured(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+/**
+ * The machine's app-data home. See the module note for the ordering rationale.
+ */
+export function resolveAppDataHome(options: ResolveAppDataHomeOptions = {}): string {
+	const env = options.env ?? process.env;
+	const override = configured(options.override);
+	if (override) return override;
+
+	const appDataHome = configured(env[APP_DATA_HOME_ENV]);
+	if (appDataHome) return appDataHome;
+
+	const xdg = configured(env[XDG_DATA_HOME_ENV]);
+	if (xdg) return xdg;
+
+	// `env.HOME` rather than `homedir()` alone, so a caller passing an env object
+	// gets a resolution it can actually control — every test below depends on it,
+	// and so does any host that boots an app under a different account.
+	const home = configured(env.HOME) ?? homedir();
+	const platform = options.platform ?? process.platform;
+	return platform === "darwin"
+		? join(home, "Library", "Application Support")
+		: join(home, ".local", "share");
+}

package/src/server/retention/archive.spec.ts

@@ -9,6 +9,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveAppDataHome } from "../paths/appDataHome";
 import {
 	archiveStamp,
 	createJsonlArchive,
@@ -133,18 +134,39 @@ describe("pendingBytes — the staleness signal a deployed box can actually obse
 });
 
 describe("resolveArchiveHome", () => {
-	test("the Mac's shared home is TERMINAL and is the path the owner's plan names", () => {
+	test("the shared OS-convention home is TERMINAL — the archive simply grows there", () => {
 		const root = tmp();
-		mkdirSync(join(root, ".app-managed"), { recursive: true });
+		const conventional = resolveAppDataHome({ env: { HOME: root } });
+		mkdirSync(conventional, { recursive: true });
 		const resolved = resolveArchiveHome("notes", { HOME: root });
 		expect(resolved).toEqual({
-			dir: join(root, ".app-managed", "cursed-satellites", "archive", "notes"),
+			dir: join(conventional, "cursed-satellites", "archive", "notes"),
 			terminal: true,
 		});
 	});
 
+	test("APP_DATA_HOME is honored before the convention, and before it exists", () => {
+		const configured = join(tmp(), "managed");
+		expect(resolveArchiveHome("notes", { APP_DATA_HOME: configured })).toEqual({
+			dir: join(configured, "cursed-satellites", "archive", "notes"),
+			terminal: true,
+		});
+	});
+
+	/**
+	 * 🔴 Up to 2026-09-13 this resolved a hardcoded dotfolder in the owner's home —
+	 * in a PUBLISHED package. Asserted on the output, so it still holds if the
+	 * folder comes back through a variable.
+	 */
+	test("resolves nothing from a previous generation, whatever the env says", () => {
+		const root = tmp();
+		const resolved = resolveArchiveHome("notes", { HOME: root, APP_MANAGED_HOME: "/nowhere/inherited" });
+		expect(resolved.dir).not.toContain("app-managed");
+		expect(resolved.dir).not.toContain("/nowhere/inherited");
+	});
+
 	test("🔴 a deployed box falls back to the data dir and is STAGED — something must collect it", () => {
-		const root = tmp(); // no ~/.app-managed, which is every deployed box
+		const root = tmp(); // no shared data home, which is every deployed box
 		const dataDir = join(tmp(), "data");
 		mkdirSync(dataDir, { recursive: true });
 		expect(resolveArchiveHome("notes", { HOME: root, APP_DATA_DIR: dataDir })).toEqual({

package/src/server/retention/archive.ts

@@ -28,10 +28,13 @@
  * prefix and then delete the rest. A sealed file cannot be half a file.
  *
  * ── Terminal vs staged, and the staleness refusal ───────────────────────────
- * On this Mac the archive is home: `~/.app-managed/cursed-satellites/archive/
- * <app>/`, it is `terminal`, and it simply grows. On a deployed box there is no
- * `~/.app-managed`, so it resolves to `$APP_DATA_DIR/archive` and is `staged` —
- * something else has to come and get it. That distinction is what lets the
+ * On a workstation the archive is home: `<app-data-home>/cursed-satellites/
+ * archive/<app>/`, it is `terminal`, and it simply grows. The home is
+ * CONFIGURATION ({@link resolveAppDataHome}) — `$APP_DATA_HOME`, else the OS's own
+ * convention — never a folder this library invented in somebody's home; that was
+ * the published defect fixed 2026-09-13. On a deployed box nothing outside the
+ * app's own data dir is writable, so it resolves to `$APP_DATA_DIR/archive` and
+ * is `staged` — something else has to come and get it. That distinction is what lets the
  * sweeper honor "refuse to trim if the last successful pull is stale" using a
  * fact the box can actually observe: how many bytes of sealed segments are still
  * sitting there uncollected. If the collector stops, the archive fills to its
@@ -54,8 +57,8 @@ import {
 	writeFileSync,
 	writeSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { APP_DATA_HOME_ENV, resolveAppDataHome } from "../paths/appDataHome";
 
 /** One sealed archive file. */
 export interface ArchiveSegment {
@@ -127,10 +130,9 @@ function isUsable(dir: string): boolean {
  * Where this app's archive lives on THIS machine, and whether the machine keeps
  * it.
  *
- * The path is the one the owner's plan names —
- * `~/.app-managed/cursed-satellites/archive/<app>/` — reached through the same
- * env ladder the retention home uses, so a test, a container and a deployed box
- * each land somewhere writable rather than somewhere assumed.
+ * `<app-data-home>/cursed-satellites/archive/<app>/`, reached through the same env
+ * ladder the retention home uses, so a test, a container and a deployed box each
+ * land somewhere writable rather than somewhere assumed.
  */
 export function resolveArchiveHome(
 	app: string,
@@ -141,16 +143,19 @@ export function resolveArchiveHome(
 	if (env.RETENTION_ARCHIVE_HOME) {
 		candidates.push({ dir: join(env.RETENTION_ARCHIVE_HOME, app), terminal: true });
 	}
-	if (env.APP_MANAGED_HOME) {
+	// An explicitly CONFIGURED home is used whether or not it exists yet — the
+	// operator naming it is the statement that it is the right place.
+	const configured = env[APP_DATA_HOME_ENV]?.trim();
+	if (configured) {
 		candidates.push({
-			dir: join(env.APP_MANAGED_HOME, "cursed-satellites", "archive", app),
+			dir: join(configured, "cursed-satellites", "archive", app),
 			terminal: true,
 		});
 	}
-	const conventional = join(env.HOME ?? homedir(), ".app-managed");
-	// Only prefer the Mac's shared home when it already exists: creating it on a
-	// deployed box would strand the archive where no collector looks.
-	if (existsSync(conventional)) {
+	const conventional = resolveAppDataHome({ env });
+	// The OS convention is only PREFERRED when it is already there: creating it on
+	// a deployed box would strand the archive where no collector looks.
+	if (!configured && existsSync(conventional)) {
 		candidates.push({
 			dir: join(conventional, "cursed-satellites", "archive", app),
 			terminal: true,

package/src/server/retention/index.ts

@@ -4,7 +4,7 @@
  * ── Why this lives in cursedbelt ────────────────────────────────────────────
  * Retention used to be spoken in three unrelated vocabularies: this
  * category-based opt-in design (born in `cursed-satellites/satellite-kit`), the
- * DB-backed audit|meter WINDOWS in `cursedbelt/server/drivers/retentionPolicy`
+ * DB-backed audit|meter WINDOWS in `cursedbelt/server/drivers`' retentionPolicy
  * (billing evidence — a genuinely different concern that keeps the name
  * {@link RetentionWindows}), and `deploy-engine/backupRetention`'s artifact
  * pruning. DEDUP-8(c) made THIS one canonical and moved it here, so a single

package/src/server/retention/policy.ts

@@ -8,7 +8,7 @@
  * `ai_check_runs` keeps N per check, the proposal ledger caps at 200,
  * orch's own `eventRetention` was a whole bespoke sweeper with its own timer, and `deploy-engine/backupRetention.ts` a second one with different
  * rules. Meanwhile the things nobody had written a rule for grew without limit:
- * `~/.app-managed/orch` reached **1.0 GB** — 74 MB of attempt transcripts and a
+ * orch's own state directory reached **1.0 GB** — 74 MB of attempt transcripts and a
  * single 70 MB peer-link `dedupe.json` holding 118 entries — with no policy, no
  * backup, and nothing that could report it.
  *
@@ -178,7 +178,7 @@ export type RetentionUnit = "rows" | "files";
  * why `retentionPolicies.test.ts` pins the ids too.
  */
 export interface RetentionDeclaration {
-	/** App key, matching `Master-Docs/fleet/registry/apps-tracking.csv` (`orch`, `notes`, …). */
+	/** App key, matching the fleet registry's app-tracking rows (`orch`, `notes`, …). */
 	app: string;
 	/** Stable, app-scoped id. The override key is `<app>:<id>`. */
 	id: string;

package/src/server/retention/store.spec.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveAppDataHome } from "../paths/appDataHome";
 import type { RetentionDeclaration } from "./policy";
 import {
 	publishRetention,
@@ -169,23 +170,32 @@ describe("resolveRetentionHome", () => {
 		expect(resolveRetentionHome({ RETENTION_HOME: explicit })).toBe(explicit);
 	});
 
-	test("APP_MANAGED_HOME is honored before any conventional path", () => {
+	test("APP_DATA_HOME — the one env var — is honored before any convention", () => {
 		setRetentionHomeForTests(null);
-		expect(resolveRetentionHome({ APP_MANAGED_HOME: home })).toBe(join(home, "retention"));
+		expect(resolveRetentionHome({ APP_DATA_HOME: home })).toBe(join(home, "retention"));
 	});
 
-	test("the shared Mac home wins over APP_DATA_DIR so the station sees ONE fleet", () => {
-		// orch's APP_DATA_DIR is ~/.app-managed/orch; publishing there instead of
-		// the shared home would hide it from every other app's view of the fleet.
+	test("a configured home is used even before it exists — naming it is the statement", () => {
 		setRetentionHomeForTests(null);
-		mkdirSync(join(home, ".app-managed"), { recursive: true });
+		const fresh = join(home, "not-yet");
+		expect(resolveRetentionHome({ APP_DATA_HOME: fresh, APP_DATA_DIR: join(home, "data") })).toBe(
+			join(fresh, "retention"),
+		);
+	});
+
+	test("the shared OS-convention home wins over APP_DATA_DIR so the station sees ONE fleet", () => {
+		// An app's own APP_DATA_DIR is private to it; publishing there instead of the
+		// shared home would hide it from every other app's view of the fleet.
+		setRetentionHomeForTests(null);
+		const conventional = resolveAppDataHome({ env: { HOME: home } });
+		mkdirSync(conventional, { recursive: true });
 		expect(resolveRetentionHome({ HOME: home, APP_DATA_DIR: join(home, "data") })).toBe(
-			join(home, ".app-managed", "retention"),
+			join(conventional, "retention"),
 		);
 	});
 
-	test("a deployed box — no app-managed home — falls through to APP_DATA_DIR", () => {
-		// prod-ec2 has no ~/.app-managed, and under ProtectSystem=strict only the
+	test("a deployed box — no shared data home — falls through to APP_DATA_DIR", () => {
+		// prod-ec2 has no shared data home, and under ProtectSystem=strict only the
 		// data dir is writable. The app still sweeps; its fleet is that box's.
 		setRetentionHomeForTests(null);
 		const dataDir = join(home, "data");
@@ -199,10 +209,28 @@ describe("resolveRetentionHome", () => {
 		const dataDir = join(home, "data2");
 		expect(
 			resolveRetentionHome({
-				APP_MANAGED_HOME: "/proc/definitely-not-writable",
+				APP_DATA_HOME: "/proc/definitely-not-writable",
 				HOME: join(home, "nonexistent-home"),
 				APP_DATA_DIR: dataDir,
 			}),
 		).toBe(join(dataDir, "retention"));
 	});
+
+	/**
+	 * 🔴 The published defect, asserted on the OUTPUT rather than on the source: up
+	 * to 2026-09-13 this resolved a hardcoded dotfolder in the owner's home, so
+	 * every installer of `cursedbelt` got a library reaching into a directory that
+	 * had nothing to do with them.
+	 */
+	test("resolves nothing from a previous generation, whatever the env says", () => {
+		for (const env of [
+			{ HOME: join(home, "nonexistent-home") },
+			{ HOME: join(home, "nonexistent-home"), APP_MANAGED_HOME: "/nowhere/inherited" },
+		]) {
+			setRetentionHomeForTests(null);
+			const resolved = resolveRetentionHome(env);
+			expect(resolved).not.toContain("app-managed");
+			expect(resolved).not.toContain("/nowhere/inherited");
+		}
+	});
 });