@vincentt-xr/cli 0.12.3 → 0.14.0

package/dist/lib/locations.js

@@ -0,0 +1,117 @@
+/**
+ * The read half of the location store: verify a candidate folder, and join the
+ * store against the listing's API rows.
+ *
+ * Kept out of `listProjects.ts` so the predicate is a pure function a human can
+ * reproduce with one `cat` and no CLI — which is the whole triage story for the
+ * report that will actually arrive ("it says it does not know where my project
+ * is, and I am looking at the folder").
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * At most this many folder checks per listing. 64 reads is ~1-3 ms against an
+ * API call the listing already spent 50-200 ms on. The ceiling exists so a
+ * pathological store — an agent looping `create` in generated folders — cannot
+ * turn a listing into a filesystem walk, and it FAILS TOWARD "unknown", never
+ * toward "here is a path we did not check", which is the only direction the
+ * verify-at-read rule permits.
+ */
+export const VERIFY_LIMIT = 64;
+/**
+ * Does `dir` still hold a binding naming `projectId`?
+ *
+ *   ENOENT                          → dead (deleted, moved, drive unmounted, unbound)
+ *   present but unparseable         → dead
+ *   present with no projectId       → dead
+ *   projectId !== the entry's       → dead (bound to a different project)
+ *   otherwise                       → live
+ *
+ * A DIRECT read, not `locateProjectBinding`'s upward walk. The store recorded
+ * the directory that HOLDS the file, and walking upward from it would let a
+ * PARENT repo's binding validate a child folder the store should have dropped —
+ * answering with a plausible-but-wrong path, which is precisely what
+ * verify-at-read exists to prevent.
+ *
+ * Exactly one `readFile` of an ~80-byte file. Not a `stat` then a read: ENOENT
+ * is the negative answer.
+ */
+export function verifyLocation(dir, projectId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(dir, ".vincentt", "project.json"), "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return false;
+        return parsed.projectId === projectId;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Join the store against the ids in this listing, verify newest-first, and
+ * report what survives.
+ *
+ * Verification is SCOPED TO THE JOIN: entries for projects in another workspace
+ * are not read, not touched, and not dropped. That is a correctness rule before
+ * it is a cost one — dropping an entry because you listed a DIFFERENT workspace
+ * would be a bug, and scoping to the join makes it unrepresentable.
+ *
+ * Candidates are sorted by `t` DESCENDING before the ceiling applies, and the
+ * ordering is part of the contract. Store order (append order, oldest first) is
+ * the implementation a reader falls into without deciding, and its failure is
+ * the worst shape available: a creator with 70 stale entries and one live one
+ * spends all 64 reads on the oldest dead ones, is told their project has no
+ * known folder, and then compaction drops those 64 so the NEXT listing succeeds
+ * — an intermittent failure that heals itself, which is the hardest possible
+ * triage. Newest-first fails as "you have not touched this folder in a very long
+ * time", which is diagnosable.
+ *
+ * Presentation order and verification order are the same sort, applied once.
+ */
+export function joinLocations(entries, projectIds, verify = verifyLocation) {
+    // Exact equality on the FULL project id — never a prefix or a substring. Ids
+    // are 12-char opaque hex, and a truncating join looks reasonable to a future
+    // reader while silently leaking another tenant's folder into this listing.
+    const inScope = new Set(projectIds);
+    const candidates = [];
+    const untouched = [];
+    for (const e of entries) {
+        if (inScope.has(e.p))
+            candidates.push(e);
+        else
+            untouched.push(e);
+    }
+    const ordered = [...candidates].sort((a, b) => (b.t ?? "").localeCompare(a.t ?? ""));
+    const byProject = new Map();
+    const live = [];
+    let reads = 0;
+    const dead = new Set();
+    for (const e of ordered) {
+        if (reads >= VERIFY_LIMIT)
+            break;
+        reads += 1;
+        if (verify(e.d, e.p)) {
+            live.push(e);
+            const at = byProject.get(e.p);
+            if (at)
+                at.push(e.d);
+            else
+                byProject.set(e.p, [e.d]);
+        }
+        else {
+            dead.add(e);
+        }
+    }
+    // Beyond the ceiling an entry is neither reported nor dropped: it was not
+    // checked, and dropping what you did not check is the one thing the ceiling
+    // must not do.
+    const survivors = entries.filter((e) => !dead.has(e));
+    return { byProject, survivors, dropped: dead.size > 0 };
+}

package/dist/login/loopback.d.ts

@@ -0,0 +1,72 @@
+/** Thrown when the wait elapses with no answer from the browser. */
+export declare class LoopbackTimeoutError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the callback is a terminal failure (a cancel, a malformed answer). */
+export declare class LoopbackCallbackError extends Error {
+    constructor(message: string);
+}
+/**
+ * What the caller's parser decided about one callback.
+ *
+ * `retry` is the third state and the reason this is not a boolean: a state mismatch is
+ * a stray or forged callback, and the right response is to answer it and KEEP WAITING
+ * for the genuine one. Treating it as a failure would let anyone who can reach the
+ * loopback port cancel a legitimate consent flow.
+ */
+export type CallbackDecision<T> = {
+    ok: true;
+    value: T;
+    page: LoopbackPage;
+} | {
+    ok: false;
+    retry: boolean;
+    message: string;
+    page: LoopbackPage;
+};
+export interface LoopbackPage {
+    status: number;
+    html: string;
+}
+export interface LoopbackWaitOptions<T> {
+    /** Pick a free loopback port. Injected so tests never race a real ephemeral picker. */
+    pickPort: () => Promise<number>;
+    /** Build the console URL the browser opens, given the loopback redirect_uri. */
+    buildUrl: (redirectUri: string) => string;
+    /** Launch the browser. A no-op fake in tests; never fatal in production. */
+    openBrowser: (url: string) => void;
+    /** Interpret one callback's query params. Must verify `state` itself. */
+    parse: (params: URLSearchParams) => CallbackDecision<T>;
+    /** Abort if the round trip does not complete in time. */
+    timeoutMs: number;
+    /** Built when the wait times out, so each flow words its own transcript. */
+    onTimeout: () => Error;
+    /**
+     * Built when a callback is a TERMINAL failure. Injected for the same reason as
+     * onTimeout: each flow keeps its own error type, so callers can keep matching on
+     * theirs rather than on a shared one this extraction happened to introduce.
+     */
+    onCallbackError?: (message: string) => Error;
+    /** Narration (the "→ Opening…" / printed-URL / "Waiting…" lines). */
+    onProgress?: (line: string) => void;
+    /** The loopback path the console redirects to. Defaults to /callback. */
+    path?: string;
+}
+/**
+ * Run one loopback round trip and resolve with whatever `parse` extracted.
+ *
+ * Ordering is security-load-bearing and is the reason this function exists at all:
+ *   1. pick the port and START LISTENING,
+ *   2. only then open the browser + print the fallback URL,
+ *   3. verify `state` on every callback before reading anything else from it,
+ *   4. bound the wait.
+ */
+export declare function waitForLoopbackCallback<T>(opts: LoopbackWaitOptions<T>): Promise<T>;
+/**
+ * Verify `state` constant-time and hand back the remaining params.
+ *
+ * State is checked FIRST, always, before any other field is read, so a forged or stray
+ * callback can never drive a decision. Shared with pkce.parseCallback's discipline; kept
+ * here as a helper so a caller writing its own `parse` cannot forget it.
+ */
+export declare function verifiedState(params: URLSearchParams, expected: string): boolean;

package/dist/login/loopback.js

@@ -0,0 +1,119 @@
+// The browser round-trip primitive: start a loopback listener on 127.0.0.1, open the
+// browser at a console URL, and wait for the console to redirect back with a verified
+// `state`.
+//
+// EXTRACTED from pkceLogin.ts rather than copied. `vincentt login` (PKCE) and
+// `vincentt dx enable` (account consent) are two flows with the same security-critical
+// skeleton, and the skeleton is exactly the part that must not drift between them: the
+// listener comes up BEFORE the browser (a browser that redirects to a port nobody is
+// listening on loses the answer), `state` is verified constant-time on every callback,
+// a mismatch is answered but NOT accepted, and the wait is bounded. Two copies of that
+// would mean a fix applied to one and not the other — and the un-fixed one is a consent
+// gate.
+//
+// Every external boundary stays injected (port picker, listen, browser open, clock) so
+// callers are unit-testable with no real socket.
+import { createServer } from "node:http";
+import { stateMatches } from "./pkce.js";
+/** Thrown when the wait elapses with no answer from the browser. */
+export class LoopbackTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LoopbackTimeoutError";
+    }
+}
+/** Thrown when the callback is a terminal failure (a cancel, a malformed answer). */
+export class LoopbackCallbackError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LoopbackCallbackError";
+    }
+}
+/**
+ * Run one loopback round trip and resolve with whatever `parse` extracted.
+ *
+ * Ordering is security-load-bearing and is the reason this function exists at all:
+ *   1. pick the port and START LISTENING,
+ *   2. only then open the browser + print the fallback URL,
+ *   3. verify `state` on every callback before reading anything else from it,
+ *   4. bound the wait.
+ */
+export function waitForLoopbackCallback(opts) {
+    const callbackPath = opts.path ?? "/callback";
+    return new Promise((resolve, reject) => {
+        void (async () => {
+            let port;
+            try {
+                port = await opts.pickPort();
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
+            const redirectUri = `http://127.0.0.1:${port}${callbackPath}`;
+            const url = opts.buildUrl(redirectUri);
+            const progress = opts.onProgress ?? (() => { });
+            const server = createServer((req, res) => {
+                // A received request always carries a url; the base makes it absolute for parsing.
+                const parsed = new URL(req.url, `http://127.0.0.1:${port}`);
+                if (parsed.pathname !== callbackPath) {
+                    res.writeHead(404, { "content-type": "text/plain" });
+                    res.end("Not found");
+                    return;
+                }
+                const decision = opts.parse(parsed.searchParams);
+                res.writeHead(decision.page.status, {
+                    "content-type": "text/html; charset=utf-8",
+                });
+                res.end(decision.page.html);
+                if (decision.ok) {
+                    server.close();
+                    resolve(decision.value);
+                }
+                else if (!decision.retry) {
+                    server.close();
+                    reject(opts.onCallbackError?.(decision.message) ??
+                        new LoopbackCallbackError(decision.message));
+                }
+                // retry === true: answered, still listening for the genuine callback.
+            });
+            server.on("error", reject);
+            server.listen(port, "127.0.0.1", () => {
+                for (const line of progressLines(url))
+                    progress(line);
+                opts.openBrowser(url);
+            });
+            const timer = setTimeout(() => {
+                server.close();
+                reject(opts.onTimeout());
+            }, opts.timeoutMs);
+            timer.unref();
+        })();
+    });
+}
+/**
+ * The narration, including the printed URL.
+ *
+ * The URL is printed on EVERY run, not only when the open fails, because the CLI cannot
+ * tell whether a browser actually appeared — `open`/`xdg-open` exits 0 on a headless box
+ * with nothing to show. On the agent-driven flow this whole feature exists for, the
+ * printed URL is frequently the only way the human ever reaches the page.
+ */
+function progressLines(url) {
+    return [
+        "→ Opening your browser…",
+        `  If it doesn't open, visit: ${url}`,
+        "",
+        "  Waiting for you to answer in the browser…",
+    ];
+}
+/**
+ * Verify `state` constant-time and hand back the remaining params.
+ *
+ * State is checked FIRST, always, before any other field is read, so a forged or stray
+ * callback can never drive a decision. Shared with pkce.parseCallback's discipline; kept
+ * here as a helper so a caller writing its own `parse` cannot forget it.
+ */
+export function verifiedState(params, expected) {
+    return stateMatches(expected, params.get("state"));
+}

package/dist/login/pkceLogin.d.ts

@@ -43,6 +43,7 @@ type SpawnLike = (cmd: string, args: string[], opts: {
 };
 /** Launch the browser via an injected spawn; a throw is swallowed (fallback = the printed URL). */
 export declare function launchBrowser(url: string, spawn: SpawnLike, platform?: string): void;
+export declare function browserPage(ok: boolean, heading: string, body: string): string;
 /**
  * Run the loopback + PKCE exchange, persist the PAT, and confirm identity via /me.
  * Resolves with the confirmed identity + the config path; rejects with LoginTimeoutError

package/dist/login/pkceLogin.js

@@ -11,11 +11,11 @@
 // Every external boundary is injected (getFreePort, listen, openBrowser, backend, clock/
 // timeout, config write) so the whole flow is unit-testable against a stub backend + fake
 // browser + temp config dir, with no real socket or network.
-import { createServer } from "node:http";
 import { getFreePort } from "../preview/net.js";
 import { writeMachineConfig } from "../shared/config.js";
 import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.js";
 import { httpAuthBackend } from "./authBackend.js";
+import { waitForLoopbackCallback } from "./loopback.js";
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export class LoginTimeoutError extends Error {
     constructor() {
@@ -57,7 +57,10 @@ function defaultOpenBrowser(url) {
 // AuthLayout auth-card is mirrored here token-for-token: --color-sand page, white
 // --color-surface card (rounded-2xl, p-7), the terminal glyph on --color-primary-faint,
 // and the light/dark palette. A subtle green/red tints only the glyph on ok/failure.
-function browserPage(ok, heading, body) {
+//
+// Exported so `dx enable`'s consent round trip renders the SAME page rather than growing
+// a second, drifting copy of the console's card.
+export function browserPage(ok, heading, body) {
     // The terminal glyph the console uses on the Grant-CLI screen (icons.terminal).
     const glyph = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" ' +
         'stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
@@ -102,51 +105,44 @@ export async function runPkceLogin(opts) {
         ((apiUrl, pat) => writeMachineConfig({ apiUrl, pat, consoleUrl: opts.consoleUrl }));
     const progress = opts.onProgress ?? (() => { });
     const material = makePkceMaterial();
-    const port = await pickPort();
-    const redirectUri = `http://127.0.0.1:${port}/callback`;
-    const authUrl = buildCliAuthUrl(opts.consoleUrl, redirectUri, material);
-    // (4) await the loopback callback; verify state; hand back the auth_code.
-    const code = await new Promise((resolve, reject) => {
-        const server = createServer((req, res) => {
-            // A received request always carries a url; the base makes it absolute for parsing.
-            const url = new URL(req.url, `http://127.0.0.1:${port}`);
-            if (url.pathname !== "/callback") {
-                res.writeHead(404, { "content-type": "text/plain" });
-                res.end("Not found");
-                return;
-            }
-            const result = parseCallback(url.searchParams, material.state);
-            res.writeHead(result.ok ? 200 : 400, {
-                "content-type": "text/html; charset=utf-8",
-            });
-            res.end(result.ok
-                ? browserPage(true, "You're all set", "Return to your terminal — you can close this tab.")
-                : browserPage(false, "Sign-in failed", result.message));
+    // (1)–(4): listener up first, browser second, state verified on every callback,
+    // bounded wait. The mechanics live in waitForLoopbackCallback, shared with
+    // `dx enable` so the two flows cannot drift apart.
+    const code = await waitForLoopbackCallback({
+        pickPort,
+        buildUrl: (redirectUri) => buildCliAuthUrl(opts.consoleUrl, redirectUri, material),
+        openBrowser,
+        timeoutMs: opts.timeoutMs ?? 5 * 60_000,
+        onTimeout: () => new LoginTimeoutError(),
+        onCallbackError: (message) => new LoginCallbackError(message),
+        onProgress: (line) => {
+            // The login transcript says "sign in" where the generic narration says
+            // "answer" — same lines, this flow's words.
+            progress(line
+                .replace("→ Opening your browser…", "→ Opening your browser to sign in…")
+                .replace("  Waiting for you to answer in the browser…", "  Waiting for you to approve access in the browser…"));
+        },
+        parse: (params) => {
+            const result = parseCallback(params, material.state);
             if (result.ok) {
-                server.close();
-                resolve(result.code);
-            }
-            else if (result.reason !== "state_mismatch") {
-                // A cancel is a real, terminal failure. A state mismatch is a stray/forged
-                // callback — answer it but keep waiting for the genuine one (or the timeout).
-                server.close();
-                reject(new LoginCallbackError(result.message));
+                return {
+                    ok: true,
+                    value: result.code,
+                    page: {
+                        status: 200,
+                        html: browserPage(true, "You're all set", "Return to your terminal — you can close this tab."),
+                    },
+                };
             }
-        });
-        server.on("error", reject);
-        // (1) listener up FIRST; only then (3) open the browser + print the fallback.
-        server.listen(port, "127.0.0.1", () => {
-            progress("→ Opening your browser to sign in…");
-            progress(`  If it doesn't open, visit: ${authUrl}`);
-            progress("");
-            progress("  Waiting for you to approve access in the browser…");
-            openBrowser(authUrl);
-        });
-        const timer = setTimeout(() => {
-            server.close();
-            reject(new LoginTimeoutError());
-        }, opts.timeoutMs ?? 5 * 60_000);
-        timer.unref();
+            // A cancel is a real, terminal failure. A state mismatch is a stray/forged
+            // callback — answer it but keep waiting for the genuine one (or the timeout).
+            return {
+                ok: false,
+                retry: result.reason === "state_mismatch",
+                message: result.message,
+                page: { status: 400, html: browserPage(false, "Sign-in failed", result.message) },
+            };
+        },
     });
     // (5) redeem the code for the raw PAT; (6) persist then confirm identity.
     const pat = await backend.exchange(code, material.codeVerifier);

package/dist/shared/config.d.ts

@@ -56,6 +56,14 @@ export declare function writeDxEnablement(next: {
  * other field by design, which would leave a disconnected machine still armed to
  * transmit for whoever signs in next — a creator who disconnects a machine has
  * disconnected it.
+ *
+ * The ACCOUNT-WIDE grant is deliberately NOT revoked here, and that asymmetry is the
+ * point: the local flag is a statement about this machine, so disconnecting the machine
+ * retracts it, while the account grant is a separate deliberate decision that lives in
+ * the console and covers machines this one knows nothing about. Signing out of a laptop
+ * is not a statement about a desktop. `vincentt dx disable` is the verb that revokes the
+ * account grant; `logout` only ever clears local state, which also keeps it free of a
+ * network call that could fail and strand a sign-out.
  */
 export declare function clearMachineToken(): Promise<{
     path: string;

package/dist/shared/config.js

@@ -12,6 +12,7 @@ import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { recordLocation } from "./recordLocation.js";
 export const MACHINE_CONFIG_PATH = path.join(os.homedir(), ".vincentt", "config.json");
 const BINDING_DIR = ".vincentt";
 const BINDING_FILE = "project.json";
@@ -111,6 +112,14 @@ export async function writeDxEnablement(next) {
  * other field by design, which would leave a disconnected machine still armed to
  * transmit for whoever signs in next — a creator who disconnects a machine has
  * disconnected it.
+ *
+ * The ACCOUNT-WIDE grant is deliberately NOT revoked here, and that asymmetry is the
+ * point: the local flag is a statement about this machine, so disconnecting the machine
+ * retracts it, while the account grant is a separate deliberate decision that lives in
+ * the console and covers machines this one knows nothing about. Signing out of a laptop
+ * is not a statement about a desktop. `vincentt dx disable` is the verb that revokes the
+ * account grant; `logout` only ever clears local state, which also keeps it free of a
+ * network call that could fail and strand a sign-out.
  */
 export async function clearMachineToken() {
     const current = await loadMachineConfig();
@@ -137,8 +146,12 @@ export async function locateProjectBinding(cwd) {
     let dir = path.resolve(cwd);
     for (;;) {
         const binding = await readJsonIfExists(projectBindingPath(dir));
-        if (binding)
+        if (binding) {
+            // The ONE success return, so every verb that resolves a binding records
+            // its folder without a per-verb checklist. Best-effort and synchronous.
+            recordLocation(binding.projectId, dir);
             return { binding, dir, path: projectBindingPath(dir) };
+        }
         if (await isGitRoot(dir))
             return undefined;
         const parent = path.dirname(dir);
@@ -165,6 +178,10 @@ export async function writeProjectBinding(cwd, binding) {
     const p = projectBindingPath(cwd);
     await fs.writeFile(p, JSON.stringify(binding, null, 2) + "\n", "utf8");
     await ensureGitignored(cwd, `${BINDING_DIR}/`);
+    // `create` and `link` WRITE a binding rather than resolve one, so they never
+    // pass through the resolver's hook. Between the two, every way a folder comes
+    // to name a project records that folder.
+    recordLocation(binding.projectId, path.resolve(cwd));
     return p;
 }
 /** Remove the per-tree binding so the directory can be re-created/rebound. */

package/dist/shared/locationStore.d.ts

@@ -0,0 +1,82 @@
+export interface LocationEntry {
+    /** The project id — the join key against the listing's API rows. */
+    p: string;
+    /**
+     * The absolute directory holding `.vincentt/project.json`, REALPATH-resolved.
+     * Not the cwd: the cwd may be a subdirectory of it.
+     */
+    d: string;
+    /** ISO8601 UTC, when the entry was last written. The presentation tiebreak. */
+    t: string;
+}
+/**
+ * An entry is a DISTINCT FOLDER, not a run, so the bound is far smaller than the
+ * journal's 2000. 500 folders is beyond any real creator and holds the file
+ * under ~60 KB.
+ */
+export declare const MAX_ENTRIES = 500;
+/**
+ * Resolved per call rather than captured at module load — the same discipline
+ * and the same reason as `journalPath()`: the home directory is the seam tests
+ * move, and a frozen path silently writes the developer's real one.
+ */
+export declare function locationsPath(): string;
+/** The store's whole surface, so the listing can be driven with no filesystem. */
+export interface LocationStore {
+    read(): LocationEntry[];
+    append(entry: LocationEntry): void;
+    compact(keep: LocationEntry[]): void;
+}
+/**
+ * Read oldest-first. Malformed lines are skipped, and an unreadable file yields
+ * an empty list — a store that FAILS is indistinguishable from a store that is
+ * EMPTY, which is the correct blast radius: a fresh install is exactly that
+ * state and is fully supported.
+ */
+export declare function readLocations(): LocationEntry[];
+/**
+ * Does the file end in a newline, or is there nothing there yet?
+ *
+ * Two syscalls against the page cache (`statSync` for the size, a one-byte read
+ * at `size - 1`), skipped entirely when the file is absent or empty. Writing
+ * `"\n" + line` unconditionally was rejected: it makes a leading blank line the
+ * normal case the reader must then tolerate, hiding the torn-write signal
+ * instead of repairing it.
+ */
+export declare function needsLeadingNewline(file: string): boolean;
+/**
+ * Append one entry. Never throws, for the journal's stated reason:
+ * instrumentation that breaks the tool it measures is worse than none. Every
+ * failure mode here (a read-only home, a full disk, a directory where the file
+ * should be) is one the creator would rather have silently ignored than turned
+ * into a failed `publish`.
+ *
+ * `locationsPath()` is INSIDE the try because it calls `os.homedir()`, which can
+ * itself throw on a hostile environment.
+ */
+export declare function appendLocation(entry: LocationEntry): void;
+/**
+ * Collapse duplicate `(p, d)` pairs to their newest `t`, then keep the newest
+ * MAX_ENTRIES. Returned oldest-first, which is the order the file holds.
+ */
+export declare function compactEntries(entries: LocationEntry[]): LocationEntry[];
+/**
+ * Rewrite the store with the survivors, ATOMICALLY: a unique temp file at 0600,
+ * chmod'ed explicitly, renamed over the target, and removed if the rename fails.
+ * The discipline `persistMachineConfig` already uses for the credential file.
+ *
+ * Rewrite-with-survivors rather than delete-lines, so a crash leaves either the
+ * original file or the fully compacted one and never a truncated store — which
+ * would be indistinguishable from an empty one BY DESIGN, and therefore
+ * invisible at every behavioral tier.
+ *
+ * An append landing inside the rename window is lost. That is accepted and
+ * self-healing (the folder that appended is a folder a verb just ran in), and it
+ * is the one place the no-lock choice has a visible cost.
+ *
+ * Never throws: it runs AFTER the answer has printed, and a compaction that
+ * fails must not delay or break it.
+ */
+export declare function compactLocations(keep: LocationEntry[]): void;
+/** The real store, reading and writing the creator's own home directory. */
+export declare const fileLocationStore: LocationStore;