@vincentt-xr/cli 0.12.3 → 0.14.0

package/dist/dx/consent.js

@@ -0,0 +1,197 @@
+/**
+ * The ACCOUNT half of unattended-send authorization.
+ *
+ * `vincentt dx enable` used to require a TTY, which dead-ends the flow this feature is
+ * actually for: a creator drives the CLI through a coding agent, the agent has no
+ * terminal, and the command refuses. Consent therefore moves to the console, where a
+ * human can actually read the disclosure and click — the CLI opens a browser and waits.
+ *
+ * The grant is PER-ACCOUNT, not per-machine: one decision covers every machine the
+ * creator signs in on. That is a wider blast radius than the local flag, which is why
+ * the console page carries the full disclosure (including that an agent may compose a
+ * note the user has not read) and why the visibility line names the console as the
+ * source — a creator who wants it off needs to know that clearing a local flag is not
+ * enough.
+ *
+ * Every call is isolated behind ConsentBackend so the command layer is unit-testable
+ * with no network.
+ */
+import { randomBytes } from "node:crypto";
+import { waitForLoopbackCallback } from "../login/loopback.js";
+import { browserPage } from "../login/pkceLogin.js";
+import { stateMatches } from "../login/pkce.js";
+import { getFreePort } from "../preview/net.js";
+import { authFailureMessage } from "../shared/authError.js";
+import { clientHeaders } from "../shared/clientHeader.js";
+import { readAccountConsent } from "./enablement.js";
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Unwrap the `meEnvelope` GET /me and both /me/dx-consent verbs return.
+ *
+ * The envelope is `{ me: {...}, csrfToken }`, but a bare user object is tolerated for the
+ * same reason normalizeMe tolerates it: a contract wording change should not silently
+ * turn a granted account into a refusal. Note the tolerance is on the SHAPE ONLY — the
+ * consent VALUE is still read `=== true`, so a resilient unwrap never becomes a lenient
+ * authorization read.
+ */
+function unwrapMe(raw) {
+    const envelope = (raw ?? {});
+    return envelope.me && typeof envelope.me === "object" ? envelope.me : envelope;
+}
+/** The real HTTP-backed ConsentBackend, pointed at a Vincentt API base URL. */
+export function httpConsentBackend() {
+    const strip = (u) => u.replace(/\/$/, "");
+    return {
+        async read(apiUrl, pat, now) {
+            const res = await fetch(`${strip(apiUrl)}/me`, {
+                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
+            });
+            if (!res.ok) {
+                throw new Error(authFailureMessage("Could not read your account", res.status, await safeText(res)));
+            }
+            return readAccountConsent(unwrapMe(await res.json()), now);
+        },
+        async grant(apiUrl, pat, now) {
+            const res = await fetch(`${strip(apiUrl)}/me/dx-consent`, {
+                method: "POST",
+                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
+            });
+            if (!res.ok) {
+                throw new Error(authFailureMessage("Could not record consent", res.status, await safeText(res)));
+            }
+            return readAccountConsent(unwrapMe(await res.json()), now);
+        },
+        async revoke(apiUrl, pat) {
+            const res = await fetch(`${strip(apiUrl)}/me/dx-consent`, {
+                method: "DELETE",
+                headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
+            });
+            if (!res.ok) {
+                throw new Error(authFailureMessage("Could not revoke consent", res.status, await safeText(res)));
+            }
+        },
+    };
+}
+/**
+ * The console URL the browser opens for the consent decision:
+ * `<console>/cli-dx-consent?redirect_uri=<loopback>&state=…`.
+ *
+ * Mirrors buildCliAuthUrl deliberately, including the param NAMES — the console's page
+ * reads exactly `redirect_uri` and `state`, and it validates that redirect_uri is a
+ * 127.0.0.1 loopback. No PKCE material rides here: unlike login, nothing is being
+ * redeemed. The callback carries only a decision, and `state` is what binds that
+ * decision to this CLI invocation.
+ */
+export function buildConsentUrl(consoleBase, redirectUri, state) {
+    const base = /^https?:\/\//i.test(consoleBase)
+        ? consoleBase
+        : `${/^(localhost|127\.0\.0\.1)(:|\/|$)/i.test(consoleBase) ? "http" : "https"}://${consoleBase}`;
+    const u = new URL("/cli-dx-consent", base);
+    u.searchParams.set("redirect_uri", redirectUri);
+    u.searchParams.set("state", state);
+    return u.toString();
+}
+/**
+ * Interpret the loopback callback (`?state=…&result=granted|denied`).
+ *
+ * State is verified constant-time FIRST, before `result` is even read, so a stray or
+ * forged callback can never grant consent — the same discipline as parseCallback, and
+ * for a higher-stakes decision: here the forged value would not be a code that still has
+ * to survive a PKCE exchange, it would be the answer itself.
+ *
+ * Anything that is not exactly "granted" reads as DENIED rather than as an error, so an
+ * unrecognized result can only ever fail closed.
+ */
+export function parseConsentCallback(params, expectedState, stateMatches) {
+    if (!stateMatches(expectedState, params.get("state"))) {
+        return {
+            ok: false,
+            reason: "state_mismatch",
+            message: "State mismatch — ignoring an unexpected callback.",
+        };
+    }
+    const result = params.get("result");
+    if (result === null) {
+        return {
+            ok: false,
+            reason: "missing_result",
+            message: "The browser returned no answer.",
+        };
+    }
+    return { ok: true, decision: result === "granted" ? "granted" : "denied" };
+}
+/** Thrown when the human never answers in the browser. */
+export class ConsentTimeoutError extends Error {
+    constructor() {
+        super("Timed out waiting for an answer in the browser (5 minutes).");
+        this.name = "ConsentTimeoutError";
+    }
+}
+/**
+ * Open the console's consent page and wait for the human's answer.
+ *
+ * The mechanics are the SHARED loopback helper, not a second copy of it: listener up
+ * before the browser, `state` verified constant-time on every callback, a stray callback
+ * answered but not accepted, and a bounded wait. The only thing that differs from login
+ * is what comes back — a decision instead of an auth code.
+ *
+ * Nothing is written here. This function reports what the human said; persisting it is
+ * the command layer's job, so the "denied writes nothing" rule lives in one place.
+ */
+export async function runConsentInBrowser(opts) {
+    // 24 bytes of CSPRNG, matching the login flow's state. This is the only thing binding
+    // the browser's answer to this invocation, so it is minted per call and never reused.
+    const state = (opts.mintState ?? defaultState)();
+    return waitForLoopbackCallback({
+        pickPort: opts.pickPort ?? getFreePort,
+        buildUrl: (redirectUri) => buildConsentUrl(opts.consoleUrl, redirectUri, state),
+        openBrowser: opts.openBrowser ?? defaultOpenBrowser,
+        timeoutMs: opts.timeoutMs ?? 5 * 60_000,
+        onTimeout: () => new ConsentTimeoutError(),
+        onProgress: opts.onProgress,
+        parse: (params) => {
+            const result = parseConsentCallback(params, state, stateMatches);
+            if (result.ok) {
+                const granted = result.decision === "granted";
+                return {
+                    ok: true,
+                    value: result.decision,
+                    page: {
+                        status: 200,
+                        html: browserPage(granted, granted ? "Reports allowed" : "Not enabled", "Return to your terminal — you can close this tab."),
+                    },
+                };
+            }
+            return {
+                ok: false,
+                // A state mismatch keeps waiting: it is a stray or forged callback, and letting
+                // it end the flow would let anyone who can reach the loopback port cancel a
+                // legitimate consent round trip.
+                retry: result.reason === "state_mismatch",
+                message: result.message,
+                page: {
+                    status: 400,
+                    html: browserPage(false, "Something went wrong", result.message),
+                },
+            };
+        },
+    });
+}
+function defaultState() {
+    return randomBytes(24)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function defaultOpenBrowser(url) {
+    // Lazy import keeps this module importable in tests that never open a browser.
+    void Promise.all([import("node:child_process"), import("../login/pkceLogin.js")]).then(([{ spawn }, { launchBrowser }]) => launchBrowser(url, spawn));
+}

package/dist/dx/enablement.d.ts

@@ -10,10 +10,22 @@
  * raise.
  */
 export declare const DX_UNATTENDED_SUNSET: number;
+/**
+ * WHERE the grant was made. Consent can now be given in the console (per-ACCOUNT, so it
+ * covers every machine the creator signs in on) or at this terminal (per-MACHINE).
+ *
+ * The source is carried rather than inferred because the two have different blast radii
+ * and different places to revoke. A creator reading `ENABLED` on a machine they never
+ * ran `dx enable` on has no way to act on it without being told the grant lives in their
+ * account — they would go looking for a local flag that is not there.
+ */
+export type EnablementSource = "console" | "machine";
 export interface Enablement {
     enabled: boolean;
     /** The raw ISO8601 grant time. Present only when `enabled` is true. */
     at?: string;
+    /** Where the grant came from. Present only when `enabled` is true. */
+    source?: EnablementSource;
 }
 /**
  * Decide enablement from an already-parsed config object. Pure, and STRICT:
@@ -26,6 +38,18 @@ export interface Enablement {
  * that reads a creator's "off" as "on" is inverted, not merely loose.
  */
 export declare function readEnablement(cfg: unknown, now: number): Enablement;
+/**
+ * Decide enablement from the ACCOUNT's `/me` fields, with the same strictness as the
+ * local read.
+ *
+ * `=== true` is not defensive noise here either: this value crosses the wire, so it
+ * arrives as whatever JSON the server (or anything between) actually sent. A truthiness
+ * read would treat the string "false" — the exact shape a serializer bug or a hand-rolled
+ * proxy produces — as consent. The sunset applies identically: past it, an account grant
+ * stops being honored too, or "forgetting the sunset turns the feature off" would only be
+ * true of the local half.
+ */
+export declare function readAccountConsent(raw: unknown, now: number): Enablement;
 /**
  * Read enablement from the real machine config.
  *
@@ -42,10 +66,20 @@ export declare function grantedOn(at: string): string;
 /**
  * The one visibility line, in the single pinned shape every human surface uses:
  *
- *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted in the console
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted on this machine
  *
  * Returns undefined when not enabled. Nothing is printed in that case, on
  * purpose: a line that prints unconditionally is a line readers learn to skip,
  * which would cost exactly the attention the enabled line needs.
+ *
+ * The AGE stays exactly where it was — it remains the entire mitigation for having no
+ * expiry, and the source is appended AFTER it rather than woven in, so the number a
+ * reader is meant to notice is not pushed off the front of the line.
+ *
+ * The source clause answers the question the age raises: having seen "145 days", the
+ * creator's next move is to turn it off, and that is a different place depending on
+ * where it was granted. A line that says ENABLED without saying where sends someone
+ * looking for a local flag that may not exist.
  */
 export declare function enablementLine(e: Enablement, now: number): string | undefined;

package/dist/dx/enablement.js

@@ -1,11 +1,16 @@
 /**
  * Durable authorization for unattended `vincentt dx --send`.
  *
- * `--send` transmits only when the session is interactive OR this machine has
- * been explicitly enabled by a person, at a terminal, via `vincentt dx enable`.
- * The state is two fields in ~/.vincentt/config.json, set by `enable`, cleared by
- * `disable` and by `logout`, and it has NO expiry — it stays on until the creator
- * turns it off.
+ * `--send` transmits only when the session is interactive, OR this MACHINE has been
+ * enabled via `vincentt dx enable`, OR the creator's ACCOUNT carries the grant they
+ * gave in the console. `enable` collects that consent in the browser by default and
+ * at the terminal when there is one; either way a person answers, never the caller.
+ *
+ * The machine half is two fields in ~/.vincentt/config.json, set by `enable`, cleared
+ * by `disable` and by `logout`. The account half is read from `/me` and cleared by
+ * `disable` or in the console — NOT by `logout`, since signing out of one machine is
+ * not a decision about the account. Neither has an expiry: both stay on until the
+ * creator turns them off.
  *
  * Because there is no expiry, VISIBILITY is the entire mitigation, and the AGE is
  * the load-bearing half of it: `ENABLED` alone reads as configuration, while
@@ -50,7 +55,35 @@ export function readEnablement(cfg, now) {
         return DISABLED;
     if (now >= DX_UNATTENDED_SUNSET)
         return DISABLED;
-    return { enabled: true, at: dxSendEnabledAt };
+    // The local flag is by definition a grant made on THIS machine — `dx enable` is the
+    // only writer, whether it took the browser path or the terminal one. An account grant
+    // never lands in this file; it is read from /me and reported separately.
+    return { enabled: true, at: dxSendEnabledAt, source: "machine" };
+}
+/**
+ * Decide enablement from the ACCOUNT's `/me` fields, with the same strictness as the
+ * local read.
+ *
+ * `=== true` is not defensive noise here either: this value crosses the wire, so it
+ * arrives as whatever JSON the server (or anything between) actually sent. A truthiness
+ * read would treat the string "false" — the exact shape a serializer bug or a hand-rolled
+ * proxy produces — as consent. The sunset applies identically: past it, an account grant
+ * stops being honored too, or "forgetting the sunset turns the feature off" would only be
+ * true of the local half.
+ */
+export function readAccountConsent(raw, now) {
+    if (typeof raw !== "object" || raw === null)
+        return DISABLED;
+    const { dxReportsConsent, dxReportsConsentAt } = raw;
+    if (dxReportsConsent !== true)
+        return DISABLED;
+    if (typeof dxReportsConsentAt !== "string")
+        return DISABLED;
+    if (!Number.isFinite(Date.parse(dxReportsConsentAt)))
+        return DISABLED;
+    if (now >= DX_UNATTENDED_SUNSET)
+        return DISABLED;
+    return { enabled: true, at: dxReportsConsentAt, source: "console" };
 }
 /**
  * Read enablement from the real machine config.
@@ -83,15 +116,30 @@ export function grantedOn(at) {
 /**
  * The one visibility line, in the single pinned shape every human surface uses:
  *
- *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted in the console
+ *   Unattended send: ENABLED since 2026-04-01 (145 days) · granted on this machine
  *
  * Returns undefined when not enabled. Nothing is printed in that case, on
  * purpose: a line that prints unconditionally is a line readers learn to skip,
  * which would cost exactly the attention the enabled line needs.
+ *
+ * The AGE stays exactly where it was — it remains the entire mitigation for having no
+ * expiry, and the source is appended AFTER it rather than woven in, so the number a
+ * reader is meant to notice is not pushed off the front of the line.
+ *
+ * The source clause answers the question the age raises: having seen "145 days", the
+ * creator's next move is to turn it off, and that is a different place depending on
+ * where it was granted. A line that says ENABLED without saying where sends someone
+ * looking for a local flag that may not exist.
  */
 export function enablementLine(e, now) {
     if (!e.enabled || e.at === undefined)
         return undefined;
     const days = ageInDays(e.at, now);
-    return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})`;
+    const where = e.source === "console"
+        ? " · granted in the console"
+        : e.source === "machine"
+            ? " · granted on this machine"
+            : "";
+    return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})${where}`;
 }

package/dist/lib/listProjects.d.ts

@@ -1,5 +1,8 @@
 import type { ProjectView } from "./backend.js";
 import type { ResolvedConfig } from "../shared/config.js";
+import { type LocationStore } from "../shared/locationStore.js";
+/** The unknown case, printed rather than omitted. Repeated verbatim in the scaffolded agent contract. */
+export declare const NO_LOCATION = "no folder known on this machine";
 export interface ListProjectsDeps {
     print: (line: string) => void;
     /** The machine's API host + PAT, or undefined when nothing is signed in. */
@@ -16,6 +19,14 @@ export interface ListProjectsDeps {
         message: string;
     }>;
     list: (cfg: ResolvedConfig, orgSlug: string) => Promise<ProjectView[]>;
+    /**
+     * The machine's location store. REQUIRED as a dep, not optional: without it
+     * this command acquires a hard dependency on the real home directory and the
+     * header's claim above stops being true.
+     */
+    store?: LocationStore;
+    /** The verification predicate, injectable so the drop-or-report decision needs no filesystem. */
+    verify?: (dir: string, projectId: string) => boolean;
 }
 export interface ListProjectsOptions {
     json?: boolean;
@@ -38,4 +49,4 @@ export declare function listProjectsCommand(deps: ListProjectsDeps, opts?: ListP
  * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
  * address on staging and dev.
  */
-export declare function projectRows(projects: ProjectView[]): string[];
+export declare function projectRows(projects: ProjectView[], locations?: Map<string, string[]>): string[];

package/dist/lib/listProjects.js

@@ -10,8 +10,21 @@
 // were bad: guess an id, tell the creator to open the console and copy one, or
 // fail. `link` needs an id, and until now nothing printed one.
 //
-// The IO boundary (print, backend, org) is injected, so every branch is testable
-// with no API, no HOME, and no network.
+// It also answers WHERE, for a project this machine has worked on before, by
+// joining the machine-local location store on the project id. The store is a
+// hint pointing at a hint: every candidate folder is verified against the
+// binding it claims to hold before it is reported, and the server re-authorizes
+// on every request regardless. It is the ONLY reader of the store in the
+// product.
+//
+// The IO boundary (print, backend, org, store, verify) is injected, so every
+// branch is testable with no API, no HOME, and no network.
+import { compactEntries, fileLocationStore, } from "../shared/locationStore.js";
+import { joinLocations, verifyLocation } from "./locations.js";
+/** The unknown case, printed rather than omitted. Repeated verbatim in the scaffolded agent contract. */
+export const NO_LOCATION = "no folder known on this machine";
+/** The row's own two spaces, plus four. A CONSTANT — never aligned to a column. */
+const CONTINUATION_INDENT = "      ";
 /**
  * The columns are `id`, `slug`, `name` and where it stands.
  *
@@ -32,13 +45,32 @@ export async function listProjectsCommand(deps, opts = {}) {
         return 1;
     }
     const projects = await deps.list(cfg, org.org.slug);
+    // The store is not consulted when there is nothing to join against: a creator
+    // with no projects must not learn that a location feature exists, and the
+    // location is a property of a project ROW.
+    const located = projects.length === 0
+        ? { byProject: new Map(), compact: () => { } }
+        : readLocationsFor(deps, projects);
     if (opts.json) {
         // `{projects: [...]}` — the server's own envelope, holding the SAME
         // `ProjectView` every other verb in this CLI parses a project into. It is a
         // projection of the wire row (the API also sends version/timestamp fields),
         // and it is deliberately the shared one rather than a listing-specific
         // shape: a second projection here would be a second thing that can drift.
-        deps.print(JSON.stringify({ projects }, null, 2));
+        //
+        // `locations` is COMPOSED alongside the parsed row rather than added to
+        // `ProjectView`. That type's contract is "what the API returned", and
+        // putting a purely local filesystem fact inside it is how a never-transmitted
+        // value comes to look transmittable to the next reader — the property this
+        // whole design rests on. It is the LAST key for the same reason: the object
+        // is the API row plus one local fact, and the reading order says where the
+        // wire ends.
+        const rows = projects.map((p) => ({
+            ...p,
+            locations: located.byProject.get(p.id) ?? [],
+        }));
+        deps.print(JSON.stringify({ projects: rows }, null, 2));
+        located.compact();
         return 0;
     }
     if (projects.length === 0) {
@@ -52,12 +84,51 @@ export async function listProjectsCommand(deps, opts = {}) {
     }
     deps.print(`${projects.length} project${projects.length === 1 ? "" : "s"} in ${org.org.name}`);
     deps.print("");
-    for (const line of projectRows(projects))
+    for (const line of projectRows(projects, located.byProject))
         deps.print(line);
     deps.print("");
     deps.print("  Link a folder to one:  vincentt link <project-id>");
+    // AFTER the answer has printed, never before: a compaction that fails must
+    // not delay or break it.
+    located.compact();
     return 0;
 }
+/**
+ * Read the store, verify what this listing joins against, and hand back both the
+ * answer and a deferred compaction.
+ *
+ * Nothing here throws: a store that cannot be read yields no locations, every
+ * project reports unknown, and that is BYTE-IDENTICAL to a fresh install — which
+ * is the correct blast radius for a broken shortcut index.
+ */
+function readLocationsFor(deps, projects) {
+    const store = deps.store ?? fileLocationStore;
+    const verify = deps.verify ?? verifyLocation;
+    try {
+        const entries = store.read();
+        const joined = joinLocations(entries, projects.map((p) => p.id), verify);
+        return {
+            byProject: joined.byProject,
+            compact: () => {
+                try {
+                    const next = compactEntries(joined.survivors);
+                    // A read that dropped nothing and is already inside the bound has
+                    // nothing to rewrite, and a rename window nobody needs is a window an
+                    // append can be lost in.
+                    if (!joined.dropped && next.length === entries.length)
+                        return;
+                    store.compact(next);
+                }
+                catch {
+                    // The answer is already printed.
+                }
+            },
+        };
+    }
+    catch {
+        return { byProject: new Map(), compact: () => { } };
+    }
+}
 /**
  * Aligned on the widest id and slug so the block reads as a table in a terminal
  * and stays greppable in an agent's transcript.
@@ -67,11 +138,31 @@ export async function listProjectsCommand(deps, opts = {}) {
  * so a client that assembled `<slug>.vincentt.app` itself would print the wrong
  * address on staging and dev.
  */
-export function projectRows(projects) {
+export function projectRows(projects, locations = new Map()) {
     const idWidth = Math.max(...projects.map((p) => p.id.length));
     const slugWidth = Math.max(...projects.map((p) => p.slug.length));
-    return projects.map((p) => {
+    const out = [];
+    for (const p of projects) {
         const state = p.publishState === "live" && p.liveUrl ? p.liveUrl : p.publishState;
-        return `  ${p.id.padEnd(idWidth)}   ${p.slug.padEnd(slugWidth)}   ${p.name}   ${state}`;
-    });
+        out.push(`  ${p.id.padEnd(idWidth)}   ${p.slug.padEnd(slugWidth)}   ${p.name}   ${state}`);
+        // EVERY row carries exactly one non-empty `↳` block. That regularity is the
+        // design: the reader learns the shape once and never has to decide whether a
+        // missing line means UNKNOWN or NOT PRINTED — and it makes an older CLI,
+        // which prints no `↳` at all, a visible difference rather than an ambiguity.
+        //
+        // Nothing marks one of several as preferred: no `(newest)`, no bullet, no
+        // count, no bold. Ordering is most-recently-worked-in first and is
+        // presentation only, deliberately not printed, because a printed "newest" is
+        // the hint that becomes a pick.
+        //
+        // The path is never truncated. A wrapped path is ugly; a path a creator
+        // cannot copy is a bug report.
+        const dirs = locations.get(p.id) ?? [];
+        if (dirs.length === 0)
+            out.push(`${CONTINUATION_INDENT}↳ ${NO_LOCATION}`);
+        else
+            for (const d of dirs)
+                out.push(`${CONTINUATION_INDENT}↳ ${d}`);
+    }
+    return out;
 }

package/dist/lib/locations.d.ts

@@ -0,0 +1,59 @@
+import type { LocationEntry } from "../shared/locationStore.js";
+/**
+ * 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 declare 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 declare function verifyLocation(dir: string, projectId: string): boolean;
+export interface JoinResult {
+    /** Verified folders, newest first, keyed by project id. */
+    byProject: Map<string, string[]>;
+    /** Every entry that should survive compaction, oldest-first as the file holds it. */
+    survivors: LocationEntry[];
+    /** Whether anything was dropped, so a clean read can skip the rewrite. */
+    dropped: boolean;
+}
+/**
+ * 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 declare function joinLocations(entries: LocationEntry[], projectIds: string[], verify?: (dir: string, projectId: string) => boolean): JoinResult;