toolroll 0.9.82 → 0.9.84

package/dist/project-identity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Project identities as the console uses them, without touching a person's folders on its thread.
+ *
+ * A project's identity is its real path (project.ts canonicalProject). Resolving one reads the folder, and a folder can
+ * stop answering (folder-look.ts), so the console never resolves one on a page or at startup on its own thread, and
+ * never waits for one before it answers:
+ *
+ * - `hot` (display and grouping only): the last answer, else the path as saved. Nothing is started by asking.
+ * - `strict` (visibility and authorization): only a resolved identity; an unknown one fails closed until the next
+ *   refresh resolves it, so a stored path that leads outside its root never passes on its spelling.
+ * - `vouched` (a path a request names): only a path whose identity is known, or one that is exactly a saved identity.
+ *   Anything else is refused this time and resolved by the next background pass, never resolved inline.
+ * - `resolveNow` (an action that needs a path checked now, a POST): resolved off the thread under the look's deadline.
+ * - `refresh` (the console's background pass, the first started right after it listens): resolves what was asked about
+ *   and what has gone stale. The console answers before any of it does; until a path answers it fails closed.
+ *
+ * An embedder or test that passes no identities gets `syncProjectIdentities`: the old synchronous reads, unchanged.
+ */
+import { type FolderLookOptions } from "./folder-look.js";
+export type ProjectIdentities = {
+    /** For display and grouping only: the last known identity, else the path as saved (resolved lexically). Reads
+     * nothing. Never an authorization answer: use `strict`. */
+    hot: (path: string) => string;
+    /** For authorization: the known real folder path, else null (unknown or not a folder: fail closed until resolved).
+     * Reads nothing; an unknown path is asked about on the next refresh. */
+    strict: (path: string) => string | null;
+    /** The known identity: a real folder path, null (not a folder), or undefined (never answered). Reads nothing. */
+    known: (path: string) => string | null | undefined;
+    /** A request's path: its known identity, or the path itself when it is exactly one of `saved` (projects the plane
+     * itself proved and admitted); else undefined. */
+    vouched: (path: string, saved: () => Iterable<string>) => string | undefined;
+    /** This path's identity now, off the thread: a real folder path, null, or "no-answer" past the deadline. */
+    resolveNow: (path: string) => Promise<string | null | "no-answer">;
+    /** Resolve `paths`, everything asked about since, and answers older than a minute. False when some didn't answer. */
+    refresh: (paths: Iterable<string>) => Promise<boolean>;
+    /** Moves whenever a known identity changes or goes: a decision made before an await is re-checked against it right
+     * before its write. */
+    generation: () => number;
+};
+/** How many folders a pass looks at side by side when they're looked at one by one (within FOLDER_LOOK_CHILDREN). */
+export declare const IDENTITY_LOOKS = 4;
+export declare function projectIdentities(look?: FolderLookOptions, now?: () => number): ProjectIdentities;
+/** The synchronous reads, as before: for embedders and tests that pass no identities. */
+export declare function syncProjectIdentities(): ProjectIdentities;

package/dist/project-identity.js

@@ -0,0 +1,153 @@
+/**
+ * Project identities as the console uses them, without touching a person's folders on its thread.
+ *
+ * A project's identity is its real path (project.ts canonicalProject). Resolving one reads the folder, and a folder can
+ * stop answering (folder-look.ts), so the console never resolves one on a page or at startup on its own thread, and
+ * never waits for one before it answers:
+ *
+ * - `hot` (display and grouping only): the last answer, else the path as saved. Nothing is started by asking.
+ * - `strict` (visibility and authorization): only a resolved identity; an unknown one fails closed until the next
+ *   refresh resolves it, so a stored path that leads outside its root never passes on its spelling.
+ * - `vouched` (a path a request names): only a path whose identity is known, or one that is exactly a saved identity.
+ *   Anything else is refused this time and resolved by the next background pass, never resolved inline.
+ * - `resolveNow` (an action that needs a path checked now, a POST): resolved off the thread under the look's deadline.
+ * - `refresh` (the console's background pass, the first started right after it listens): resolves what was asked about
+ *   and what has gone stale. The console answers before any of it does; until a path answers it fails closed.
+ *
+ * An embedder or test that passes no identities gets `syncProjectIdentities`: the old synchronous reads, unchanged.
+ */
+import { resolve } from "node:path";
+import { lookIdentities } from "./folder-look.js";
+import { canonicalProject } from "./project.js";
+/** How long an answer stands before the background pass resolves the path again. */
+const STALE_MS = 60_000;
+/** How many folders a pass looks at side by side when they're looked at one by one (within FOLDER_LOOK_CHILDREN). */
+export const IDENTITY_LOOKS = 4;
+export function projectIdentities(look = {}, now = Date.now) {
+    /** Each answer with when the look that answered it started (folder-look.ts `started`, kept across joined looks): an
+     * answer from a look started earlier never overwrites one from a look started later. */
+    const answers = new Map();
+    const wanted = new Set();
+    /** Paths whose last look didn't answer: looked at only on their own (joining a look still under way), never in a
+     * batch, so one folder that never answers holds one child, not one per differently made-up batch. */
+    const suspect = new Set();
+    let generation = 0;
+    const known = (path) => answers.get(resolve(path))?.real;
+    const put = (key, real, at, seq) => {
+        const before = answers.get(key);
+        // A known identity that changes (or goes) moves authority: anything decided on the old one is out of date.
+        if (before !== undefined && before.real !== real)
+            generation++;
+        answers.set(key, { real, at, seq });
+    };
+    const store = (found, seq) => {
+        const at = now();
+        for (const [path, real] of found) {
+            const key = resolve(path);
+            // Superseded: a later lookup already answered for this path. Its real path's entry goes with it.
+            if ((answers.get(key)?.seq ?? -1) > seq)
+                continue;
+            put(key, real, at, seq);
+            wanted.delete(key);
+            // A real path is its own identity.
+            if (real !== null && (answers.get(real)?.seq ?? -1) <= seq)
+                put(real, real, at, seq);
+        }
+    };
+    const resolveNow = async (path) => {
+        const key = resolve(path);
+        const looked = await lookIdentities([key], look);
+        if (!looked.ok) {
+            suspect.add(key);
+            return "no-answer";
+        }
+        suspect.delete(key);
+        // No start known: older than every answer, so it only fills what nothing answered yet.
+        store(looked.value, looked.started ?? 0);
+        return answers.get(key)?.real ?? null;
+    };
+    const refreshNow = async (paths) => {
+        const at = now();
+        const due = new Set(wanted);
+        for (const one of paths) {
+            const key = resolve(one);
+            const answer = answers.get(key);
+            if (answer === undefined || at - answer.at >= STALE_MS)
+                due.add(key);
+        }
+        for (const [key, answer] of answers)
+            if (at - answer.at >= STALE_MS)
+                due.add(key);
+        if (due.size === 0)
+            return true;
+        const alone = [...due].filter(one => suspect.has(one));
+        const batched = [...due].filter(one => !suspect.has(one));
+        if (batched.length > 0) {
+            const batch = await lookIdentities(batched, look);
+            if (batch.ok)
+                store(batch.value, batch.started ?? 0);
+            else
+                alone.push(...batched);
+        }
+        // One folder that doesn't answer mustn't hold the others: each on its own, a few at a time (inside the looks'
+        // child cap, leaving room for a person's actions), each under its deadline, each stored as soon as it answers.
+        let missed = false;
+        const worker = async () => {
+            for (let one = alone.shift(); one !== undefined; one = alone.shift())
+                if (await resolveNow(one) === "no-answer")
+                    missed = true;
+        };
+        await Promise.all(Array.from({ length: Math.min(IDENTITY_LOOKS, alone.length) }, worker));
+        return !missed;
+    };
+    let passes = Promise.resolve();
+    return {
+        hot: path => {
+            const key = resolve(path);
+            const answer = answers.get(key);
+            if (answer === undefined)
+                wanted.add(key);
+            return answer?.real ?? key;
+        },
+        known,
+        strict: path => {
+            const key = resolve(path);
+            const answer = answers.get(key);
+            if (answer === undefined)
+                wanted.add(key);
+            return answer?.real ?? null;
+        },
+        vouched: (path, saved) => {
+            const key = resolve(path);
+            const answer = answers.get(key);
+            if (answer !== undefined && answer.real !== null)
+                return answer.real;
+            for (const one of saved())
+                if (one === key)
+                    return key;
+            wanted.add(key);
+            return undefined;
+        },
+        resolveNow,
+        generation: () => generation,
+        refresh: paths => {
+            // One pass at a time: a pass asked for while another runs waits for it, then resolves only what is still due.
+            const asked = [...paths];
+            const pass = passes.then(() => refreshNow(asked));
+            passes = pass.then(() => undefined, () => undefined);
+            return pass;
+        },
+    };
+}
+/** The synchronous reads, as before: for embedders and tests that pass no identities. */
+export function syncProjectIdentities() {
+    return {
+        hot: path => canonicalProject(path) ?? path,
+        known: path => canonicalProject(path),
+        strict: path => canonicalProject(path),
+        vouched: path => canonicalProject(path) ?? undefined,
+        resolveNow: async (path) => canonicalProject(path),
+        generation: () => 0,
+        refresh: async () => true,
+    };
+}

package/dist/project-knowledge.d.ts

@@ -23,19 +23,17 @@ export declare function knowledgeVersion(store: Store, repo: string, actor: stri
 /** Chat reads only an admitted project. Keep the full source in the project UI. */
 export declare function conversationKnowledge(store: Store, repo: string, actor: string, reference?: string, decision?: number): {
     title?: never;
-    content?: never;
-    history?: never;
     revision: number;
     stale: boolean;
     notice: string;
     decision?: never;
+    content?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
     title?: never;
-    content?: never;
-    history?: never;
     stale?: never;
     decision: {
         repo: string;
@@ -52,26 +50,28 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
         id: number;
     };
     notice: string;
+    content?: never;
     revision?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
-    history?: never;
     stale?: never;
     decision?: never;
     revision: number;
     title: string;
     content: string;
     notice: string;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
     title?: never;
-    content?: never;
     stale?: never;
     decision?: never;
+    content?: never;
     revision: number;
     history: {
         revision: number;

package/dist/project-tools.d.ts

@@ -103,7 +103,7 @@ export type FoundTool = {
  * Codex's (from `codex mcp list --json`, passed in). The first of each
  * name wins; unusable entries are left out.
  */
-export declare function discoverTools(repo: string, codexServers: unknown[] | null, home?: string, environment?: NodeJS.ProcessEnv): FoundTool[];
+export declare function discoverTools(repo: string, codexServers: unknown[] | null, home?: string, environment?: NodeJS.ProcessEnv, projectConfig?: Record<string, unknown> | null): FoundTool[];
 /** Start the server once, ask for its tools, and stop it: the proof a build can use it. */
 export declare function testTool(spec: ToolSpec, values: Record<string, string>, options: {
     timeoutMs?: number;
@@ -313,3 +313,6 @@ export declare function toolServerFor(store: ToolServerStore, repo: string, opti
     home?: string;
     available?: () => boolean;
 }): ToolServer;
+/** Each project's `.mcp.json` as the console last read it off its thread (its background pass): what its pages and the
+ * lead offer, so neither reads a project folder on the console's thread. */
+export declare const savedProjectMcp: Map<string, Record<string, unknown> | null>;

package/dist/project-tools.js

@@ -496,7 +496,7 @@ function fromCodexEntry(raw, environment) {
  * Codex's (from `codex mcp list --json`, passed in). The first of each
  * name wins; unusable entries are left out.
  */
-export function discoverTools(repo, codexServers, home = homedir(), environment = process.env) {
+export function discoverTools(repo, codexServers, home = homedir(), environment = process.env, projectConfig) {
     const found = [];
     const add = (one) => { if (one !== null && !found.some(other => other.spec.name === one.spec.name))
         found.push(one); };
@@ -509,7 +509,9 @@ export function discoverTools(repo, codexServers, home = homedir(), environment
             return null;
         }
     };
-    const project = readJson(join(repo, ".mcp.json"));
+    // The project's own file as given (the console reads it off its thread: folder-look.ts), else as last read there
+    // (savedProjectMcp), else read here (the CLI and the worker).
+    const project = projectConfig !== undefined ? projectConfig : savedProjectMcp.has(repo) ? savedProjectMcp.get(repo) ?? null : readJson(join(repo, ".mcp.json"));
     for (const [name, raw] of Object.entries((project?.["mcpServers"] ?? {})))
         add(fromClaudeEntry(name, raw, "this project's .mcp.json"));
     const claude = readJson(join(home, ".claude.json"));
@@ -1149,3 +1151,6 @@ export function toolServerFor(store, repo, options = {}) {
     const untrusted = existsSync(cache) ? [realpathSync(cache)] : [];
     return { fence: fenceFor("tool-server", { databaseFile, worktree: null, home, boundary: null, binding: null, runFolders: runFolders(null), poolRoots, extra: untrusted }) };
 }
+/** Each project's `.mcp.json` as the console last read it off its thread (its background pass): what its pages and the
+ * lead offer, so neither reads a project folder on the console's thread. */
+export const savedProjectMcp = new Map();

package/dist/project.d.ts

@@ -29,6 +29,9 @@ export type ProjectCeiling = {
     repos: readonly string[];
     /** Canonical directories: any git repo under one is authorized. */
     roots: readonly string[];
+    /** How this ceiling resolves a path it is asked about (project-identity.ts): the console's saved identities, which
+     * read no folder. Absent: canonicalProject, a synchronous read. */
+    canon?: (path: string) => string | null;
 };
 /**
  * Resolve the startup configuration once. A configured path that does not
@@ -36,7 +39,7 @@ export type ProjectCeiling = {
  * dropping would silently *widen* the server toward unscoped mode, and a
  * ceiling that loosens itself when a disk is unmounted is not a ceiling.
  */
-export declare function resolveCeiling(repos: readonly string[], roots: readonly string[]): {
+export declare function resolveCeiling(repos: readonly string[], roots: readonly string[], canon?: (path: string) => string | null | undefined): {
     ceiling: ProjectCeiling;
     unresolved: string[];
 };

package/dist/project.js

@@ -67,10 +67,10 @@ export async function projectSelection(paths, exec = run) {
  * dropping would silently *widen* the server toward unscoped mode, and a
  * ceiling that loosens itself when a disk is unmounted is not a ceiling.
  */
-export function resolveCeiling(repos, roots) {
+export function resolveCeiling(repos, roots, canon = canonicalProject) {
     const unresolved = [];
     const keep = (paths) => [...new Set(paths.map(path => {
-            const canonical = canonicalProject(path);
+            const canonical = canon(path) ?? null;
             if (canonical !== null)
                 return canonical;
             unresolved.push(path);
@@ -90,7 +90,7 @@ export function unscoped(ceiling) {
 export async function authorizedProject(ceiling, path, exec = run) {
     if (unscoped(ceiling))
         return true;
-    const canonical = canonicalProject(path);
+    const canonical = (ceiling.canon ?? canonicalProject)(path);
     if (canonical === null)
         return false;
     if (ceiling.repos.includes(canonical))
@@ -114,8 +114,15 @@ export function rowVisible(ceiling, repo) {
         return true;
     // Exact saved identities are common. Check the whole set before resolving
     // aliases, so the hundredth project does not stat the other99 directories.
-    if (ceiling.repos.includes(repo) || ceiling.repos.some(one => sameRepo(one, repo)))
+    const canon = ceiling.canon;
+    if (ceiling.repos.includes(repo) || ceiling.repos.some(one => canon === undefined ? sameRepo(one, repo) : (canon(one) ?? null) !== null && canon(one) === canon(repo)))
         return true;
+    // With a resolver (the console's saved identities), an identity it can't vouch for fails closed before any root is
+    // matched: a path's spelling never stands in for where it leads.
+    if (canon !== undefined) {
+        const resolved = canon(repo);
+        return resolved !== null && ceiling.roots.some(root => resolved.startsWith(root + sep));
+    }
     const canonical = canonicalProject(repo) ?? repo;
     return ceiling.roots.some(root => canonical.startsWith(root + sep));
 }

package/dist/repos.d.ts

@@ -57,4 +57,11 @@ export declare function updateProjectRegistry(file: string, transform: (registry
 } | RegistryUpdateFailure>;
 export declare function addRepos(existing: readonly string[], incoming: readonly string[]): string[];
 export declare function removeRepos(existing: readonly string[], targets: readonly string[]): string[];
+/** Beside the saved list: how many times each line has been removed from it (written under its lock). */
+export declare function registryRemovalsFile(file: string): string;
+/**
+ * How many times each saved line has been removed, as recorded under the saved list's lock. A file that can't be read
+ * as one answers null: its caller treats every line as changed (fail closed).
+ */
+export declare function registryRemovals(file: string): Record<string, number> | null;
 export {};

package/dist/repos.js

@@ -10,6 +10,7 @@
  * to edit it by hand or check it into their dotfiles — which also means it is
  * untrusted input and gets validated like any other.
  */
+import { closeSync as closeFd, constants as fsConstants, fstatSync, openSync as openFd, readSync, renameSync as renameFile, writeFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { configBase, namedPath } from "./names.js";
@@ -213,6 +214,11 @@ export async function updateProjectRegistry(file, transform) {
             held = false; // abandon: no unlink, no publication
             return { ok: false, reason: "abandoned", message: "the registry lock aged out before the update could publish — nothing changed; try again" };
         }
+        // Each line this update removes counts one more removal, written BEFORE the list is published: whoever holds a
+        // start's authority for a saved line (upDeferredRetry) sees that it was removed, even if it was saved again since.
+        const gone = current.repos.filter(one => !next.repos.includes(one));
+        if (gone.length > 0)
+            bumpRegistryRemovals(file, gone, `${process.pid}.${token.slice(0, 8)}`);
         const temp = `${file}.${process.pid}.${token.slice(0, 8)}.tmp`;
         const fd = openSync(temp, "wx");
         writeSync(fd, `${JSON.stringify({ version: CONFIG_VERSION, ...next }, null, 2)}
@@ -267,3 +273,54 @@ function readProjectRegistry(parsed) {
 function sortUnique(repos) {
     return [...new Set(repos)].sort();
 }
+/** Beside the saved list: how many times each line has been removed from it (written under its lock). */
+export function registryRemovalsFile(file) {
+    return `${file}.removals.json`;
+}
+/**
+ * How many times each saved line has been removed, as recorded under the saved list's lock. A file that can't be read
+ * as one answers null: its caller treats every line as changed (fail closed).
+ */
+export function registryRemovals(file) {
+    let fd;
+    try {
+        fd = openFd(registryRemovalsFile(file), fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? {} : null;
+    }
+    try {
+        const held = fstatSync(fd);
+        if (!held.isFile() || held.size > 4 * 1024 * 1024)
+            return null;
+        const buffer = Buffer.alloc(held.size);
+        const read = held.size === 0 ? 0 : readSync(fd, buffer, 0, buffer.length, 0);
+        const parsed = JSON.parse(buffer.toString("utf8", 0, read));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const out = {};
+        for (const [line, count] of Object.entries(parsed)) {
+            if (!Number.isSafeInteger(count) || count < 0)
+                return null;
+            out[line] = count;
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeFd(fd);
+    }
+}
+/** One more removal for each of `lines`, written whole and renamed into place. Called only under the list's lock. */
+function bumpRegistryRemovals(file, lines, tag) {
+    const kept = registryRemovals(file);
+    // An unreadable record starts again from the clock, so no count read before can come round again.
+    const counts = kept ?? {};
+    for (const line of lines)
+        counts[line] = kept === null ? Date.now() : (counts[line] ?? 0) + 1;
+    const temp = `${registryRemovalsFile(file)}.${tag}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(counts)}\n`, { flag: "wx", mode: 0o600 });
+    renameFile(temp, registryRemovalsFile(file));
+}