toolroll 0.9.82 → 0.9.83

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.9.83 — 2026-10-31
+
+- **A folder that doesn't answer can't freeze the console.** A disconnected
+  drive, an iCloud-synced Documents folder or a pending macOS privacy prompt
+  used to stall the whole console at startup. Folder reads now run in a
+  separate, time-limited process: the console keeps answering, and the one
+  page that needed the folder says it didn't answer.
+- **Projects come back by themselves.** A saved project whose folder was
+  away when Toolroll started connects as soon as the folder returns, with no
+  restart. It reconnects only to the same folder it was saved as, and a
+  project you remove stays removed.
+- **Safer project paths.** A project's access is decided from its real,
+  resolved location, never from how its path is spelled.
+
 ## 0.9.82 — 2026-10-31
 
 - **A failing nightly holds your releases.** Turn it on with

package/dist/desktop-update.d.ts

@@ -97,6 +97,7 @@ export declare function sqliteLock(file: string, busyTimeoutMs?: number): Databa
 export declare function lockHeld(file: string): boolean;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -110,7 +111,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/first-tasks-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/first-tasks-child.js

@@ -0,0 +1,11 @@
+/**
+ * Started only by learning-look.ts: one project's first-task suggestions (first-run.ts findFirstTasks), in a process
+ * of its own so the hardened git's synchronous reads of the project's folder never hold the console's thread. Its one
+ * argument is JSON naming the project; it prints the suggestions as JSON and ends.
+ */
+import { findFirstTasks } from "./first-run.js";
+const input = JSON.parse(process.argv[2] ?? "null");
+if (input === null || typeof input.repo !== "string" || input.repo === "" || input.repo.includes("\0"))
+    process.exit(2);
+const found = await findFirstTasks(input.repo);
+process.stdout.write(JSON.stringify(found), () => process.exit(0));

package/dist/folder-look.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Reads of a person's own folders, kept off the console's thread.
+ *
+ * A folder can stop answering: a drive that disconnected without unmounting, a folder macOS keeps in iCloud (Desktop &
+ * Documents), or one behind a privacy prompt nobody has answered. Opening it then blocks until the system answers, and
+ * a synchronous read on the console's thread freezes every page with it (the 0.9.82 deploy, 2026-10-31: the console
+ * listened for twenty minutes without answering, its main thread inside a directory read). So every such read runs in a
+ * child process, the same read it always was, and the console waits for it only as long as a deadline allows: a folder
+ * that didn't answer degrades the one thing that needed it, in plain words, and the next look tries again.
+ *
+ * A look never goes into another mounted drive, /Volumes, or the protected folders under ~/Library, unless that is the
+ * folder the person chose. Its answers are filesystem data, read exactly as before (directory names, a repository's
+ * `.git/config` as a plain bounded file never followed through a link), and the caller still checks every path against
+ * its own ceiling.
+ */
+/** How long the console waits for a look before saying the folder didn't answer. */
+export declare const FOLDER_LOOK_MS = 4000;
+/** The `url` of `[remote "origin"]` in a git config's text. Plain JavaScript with no outside names: the look's child
+ * runs this same function (its source is sent along), so the parent and the child read a config one way. */
+export declare function originUrlIn(config: string): string | null;
+export type FolderLookRequest = 
+/** One folder's sub-folders, as the browse page shows them: at most 400 kept of 2,000 entries read, links resolved
+ * and kept only inside a root. */
+{
+    op: "list";
+    path: string;
+    roots: readonly string[];
+    home: string;
+}
+/** The origin of each registered project, and of each repository directly in a root (at most 400 folders a root). */
+ | {
+    op: "origins";
+    registered: readonly string[];
+    roots: readonly string[];
+    home: string;
+}
+/** Where each path really is (its real path, when that is a folder): a project's identity, resolved off the thread. */
+ | {
+    op: "identities";
+    paths: readonly string[];
+}
+/** A project's own `.mcp.json`, read as a plain bounded file and parsed (null when absent or not a JSON object). */
+ | {
+    op: "projectMcp";
+    path: string;
+};
+/** One look under way: its answer, and when its process has ended (a stuck child can outlive its answer). */
+export type FolderLookRun = {
+    answer: Promise<unknown>;
+    ended: Promise<void>;
+};
+/** Starts one look. Production starts a child process; tests pass their own. */
+export type FolderLookRunner = (request: FolderLookRequest, deadlineMs: number) => FolderLookRun;
+export type FolderLook<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    why: "no-answer" | "failed";
+};
+/** At most this many look processes at once, stuck ones included: a folder that never answers costs one each. */
+export declare const FOLDER_LOOK_CHILDREN = 8;
+/** The production look: the script above in a child process of this same Node (or Electron as Node), killed at its
+ * deadline. Its environment carries nothing of this process's (no NODE_OPTIONS, no secrets). At the deadline its pipe
+ * is closed and nothing of it keeps this process alive; `ended` settles only when the process has really gone. */
+export declare const childLook: FolderLookRunner;
+/** How many look processes are running now (stuck ones included). */
+export declare function folderLooksRunning(): number;
+/**
+ * One look, answered within `deadlineMs` whatever the folder does: its value, or that the folder didn't answer (it ran
+ * past the deadline, the same look is still stuck, or every child slot is held) or the look failed. A look already
+ * under way for the same request is joined, never started twice.
+ */
+export declare function lookFolders(request: FolderLookRequest, options?: {
+    runner?: FolderLookRunner;
+    deadlineMs?: number;
+}): Promise<FolderLook<unknown>>;
+export type FolderEntry = {
+    name: string;
+    path: string;
+    git: boolean;
+};
+export type FolderLookOptions = {
+    runner?: FolderLookRunner;
+    deadlineMs?: number;
+    home?: string;
+};
+/** A folder's sub-folders for the browse page (null `at`: outside every root, or not a folder). */
+export declare function listFolder(path: string, roots: readonly string[], options?: FolderLookOptions): Promise<FolderLook<{
+    at: string | null;
+    entries: FolderEntry[];
+}>>;
+/** The origin URL of each registered project, and the repositories directly in each root with theirs. */
+export declare function localOrigins(registered: readonly string[], roots: readonly string[], options?: FolderLookOptions): Promise<FolderLook<{
+    registered: {
+        path: string;
+        url: string | null;
+    }[];
+    found: {
+        path: string;
+        url: string | null;
+    }[];
+}>>;
+/** Each path's identity (its real path when that is a folder, else null), resolved off the thread. */
+export declare function lookIdentities(paths: readonly string[], options?: FolderLookOptions): Promise<FolderLook<Map<string, string | null>>>;
+/** A project's own `.mcp.json` (parsed object, or null when absent or not one), read off the thread. */
+export declare function lookProjectMcp(repo: string, options?: FolderLookOptions): Promise<FolderLook<Record<string, unknown> | null>>;

package/dist/folder-look.js

@@ -0,0 +1,302 @@
+/**
+ * Reads of a person's own folders, kept off the console's thread.
+ *
+ * A folder can stop answering: a drive that disconnected without unmounting, a folder macOS keeps in iCloud (Desktop &
+ * Documents), or one behind a privacy prompt nobody has answered. Opening it then blocks until the system answers, and
+ * a synchronous read on the console's thread freezes every page with it (the 0.9.82 deploy, 2026-10-31: the console
+ * listened for twenty minutes without answering, its main thread inside a directory read). So every such read runs in a
+ * child process, the same read it always was, and the console waits for it only as long as a deadline allows: a folder
+ * that didn't answer degrades the one thing that needed it, in plain words, and the next look tries again.
+ *
+ * A look never goes into another mounted drive, /Volumes, or the protected folders under ~/Library, unless that is the
+ * folder the person chose. Its answers are filesystem data, read exactly as before (directory names, a repository's
+ * `.git/config` as a plain bounded file never followed through a link), and the caller still checks every path against
+ * its own ceiling.
+ */
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+/** How long the console waits for a look before saying the folder didn't answer. */
+export const FOLDER_LOOK_MS = 4_000;
+/** The `url` of `[remote "origin"]` in a git config's text. Plain JavaScript with no outside names: the look's child
+ * runs this same function (its source is sent along), so the parent and the child read a config one way. */
+export function originUrlIn(config) {
+    let inOrigin = false;
+    for (const line of config.split("\n")) {
+        if (/^\s*\[/.test(line)) {
+            inOrigin = /^\s*\[remote "origin"\]\s*$/.test(line);
+            continue;
+        }
+        if (!inOrigin)
+            continue;
+        const url = /^\s*url\s*=\s*(.+)$/.exec(line)?.[1];
+        if (url !== undefined)
+            return url.trim();
+    }
+    return null;
+}
+/** At most this many look processes at once, stuck ones included: a folder that never answers costs one each. */
+export const FOLDER_LOOK_CHILDREN = 8;
+/**
+ * The child's script: plain CommonJS, given the request as its one argument, printing one JSON answer. Every file it
+ * reads is opened without following a link and without waiting on a FIFO, checked to be a regular file under its cap
+ * on the open descriptor, and read only up to its limit; every folder is read through a bounded iterator.
+ */
+const LOOK_SCRIPT = `"use strict";
+const fs = require("fs"), path = require("path");
+const originUrlIn = ${originUrlIn.toString()};
+const request = JSON.parse(process.argv[1]);
+const within = (p, root) => p === root || p.startsWith(root === "/" ? "/" : root + "/");
+const home = request.home || "/nonexistent";
+const fenced = [path.join(home, "Library"), "/Volumes", "/System/Volumes", "/Network", "/net", "/private/var/automount"];
+// A place the look never enters, unless the path is inside a folder the person chose there (that root itself, not any
+// root that happens to lie in the same protected tree).
+const offLimits = (p, roots) => fenced.some(one => within(p, one) && !roots.some(root => within(root, one) && within(p, root)));
+const rootOf = (p, roots) => roots.filter(root => within(p, root)).sort((a, b) => b.length - a.length)[0];
+// A plain file read bounded by construction (ghlist review, finding 1): never through a link (O_NOFOLLOW), never
+// waiting on a FIFO (O_NONBLOCK), a regular file under the cap by the opened descriptor, at most the limit read.
+function readBounded(file, cap, limit) {
+  let fd = null;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > cap) return null;
+    const buffer = Buffer.alloc(Math.min(limit, stat.size));
+    const read = buffer.length === 0 ? 0 : fs.readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.toString("utf8", 0, read);
+  } catch { return null; }
+  finally { if (fd !== null) { try { fs.closeSync(fd); } catch {} } }
+}
+function origin(repo) {
+  const config = readBounded(path.join(repo, ".git", "config"), 1024 * 1024, 64 * 1024);
+  return config === null ? null : originUrlIn(config);
+}
+function children(folder, roots, links) {
+  const out = [];
+  const folderDev = fs.statSync(folder).dev;
+  const dir = fs.opendirSync(folder);
+  try {
+    for (let seen = 0; seen < 2000 && out.length < 400; seen++) {
+      const entry = dir.readSync();
+      if (entry === null) break;
+      if (!(entry.isDirectory() || (links && entry.isSymbolicLink()))) continue;
+      const spelled = path.join(folder, entry.name);
+      if (offLimits(spelled, roots)) continue;
+      let real, stat;
+      try { real = fs.realpathSync(spelled); } catch { continue; }
+      if (offLimits(real, roots) || !roots.some(root => within(real, root))) continue;
+      try { stat = fs.statSync(real); } catch { continue; }
+      if (!stat.isDirectory()) continue;
+      // Another drive mounted here: not entered unless it is itself a chosen folder.
+      if (stat.dev !== folderDev && !roots.includes(real)) continue;
+      out.push({ name: entry.name, path: real });
+    }
+  } finally { dir.closeSync(); }
+  return out;
+}
+function look() {
+  if (request.op === "projectMcp") {
+    const text = readBounded(path.join(request.path, ".mcp.json"), 1024 * 1024, 1024 * 1024);
+    if (text === null) return { config: null };
+    try { const parsed = JSON.parse(text); return { config: parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null }; }
+    catch { return { config: null }; }
+  }
+  if (request.op === "identities") {
+    return { paths: request.paths.slice(0, 500).map(one => {
+      try { const real = fs.realpathSync(path.resolve(one)); return { path: one, real: fs.statSync(real).isDirectory() ? real : null }; }
+      catch { return { path: one, real: null }; }
+    }) };
+  }
+  const roots = request.roots;
+  if (request.op === "list") {
+    const at = fs.realpathSync(request.path);
+    const root = rootOf(at, roots);
+    if (root === undefined || offLimits(at, roots) || !fs.statSync(at).isDirectory()) return { at: null, entries: [] };
+    // A folder on another drive than the root that allows it is not entered (the root itself may be one).
+    if (at !== root && fs.statSync(at).dev !== fs.statSync(root).dev) return { at: null, entries: [] };
+    const entries = children(at, roots, true)
+      .filter(one => !one.name.startsWith(".") && one.name !== "node_modules")
+      .map(one => ({ name: one.name, path: one.path, git: fs.existsSync(path.join(one.path, ".git")) }));
+    return { at, entries };
+  }
+  const registered = request.registered.slice(0, 500).map(repo => ({ path: repo, url: origin(repo) }));
+  const found = [];
+  for (const root of roots) {
+    let listed = [];
+    try { listed = children(root, roots, false); } catch { continue; }
+    for (const child of listed) {
+      if (!fs.existsSync(path.join(child.path, ".git"))) continue;
+      found.push({ path: child.path, url: origin(child.path) });
+    }
+  }
+  return { registered, found };
+}
+let answer;
+try { answer = { ok: true, value: look() }; } catch (error) { answer = { ok: false, code: error && error.code || null }; }
+process.stdout.write(JSON.stringify(answer));
+`;
+/** The production look: the script above in a child process of this same Node (or Electron as Node), killed at its
+ * deadline. Its environment carries nothing of this process's (no NODE_OPTIONS, no secrets). At the deadline its pipe
+ * is closed and nothing of it keeps this process alive; `ended` settles only when the process has really gone. */
+export const childLook = (request, deadlineMs) => {
+    const child = spawn(process.execPath, ["-e", LOOK_SCRIPT, JSON.stringify(request)], {
+        stdio: ["ignore", "pipe", "ignore"],
+        env: { PATH: process.env["PATH"] ?? "/usr/bin:/bin", ELECTRON_RUN_AS_NODE: "1" },
+        killSignal: "SIGKILL",
+    });
+    child.unref();
+    const ended = new Promise(resolveEnded => {
+        child.once("exit", () => resolveEnded());
+        child.once("error", () => resolveEnded());
+    });
+    const answer = new Promise((resolveAnswer, reject) => {
+        const chunks = [];
+        let size = 0;
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            // A child stuck in the kernel can't be reaped yet: its pipe is closed now, so it holds nothing here.
+            child.stdout.destroy();
+            reject(new Error("the look didn't answer"));
+        }, deadlineMs);
+        timer.unref();
+        child.stdout.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > 8 * 1024 * 1024) {
+                child.kill("SIGKILL");
+                child.stdout.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        child.once("error", error => { clearTimeout(timer); reject(error); });
+        child.once("close", code => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`the look ended with ${code}`));
+                return;
+            }
+            try {
+                resolveAnswer(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+    answer.catch(() => { });
+    return { answer, ended };
+};
+/** Looks whose process hasn't ended, by request: callers asking the same thing share one; each holds a child slot
+ * until its process is gone. */
+const inFlight = new Map();
+/** The same request however its paths were spelled: resolved paths, roots in order. */
+function lookKey(request) {
+    const sorted = (paths) => paths.map(one => resolve(one)).sort();
+    switch (request.op) {
+        case "list": return JSON.stringify([request.op, resolve(request.path), sorted(request.roots), request.home]);
+        case "origins": return JSON.stringify([request.op, sorted(request.registered), sorted(request.roots), request.home]);
+        case "identities": return JSON.stringify([request.op, sorted(request.paths)]);
+        case "projectMcp": return JSON.stringify([request.op, resolve(request.path)]);
+    }
+}
+/** How many look processes are running now (stuck ones included). */
+export function folderLooksRunning() {
+    return inFlight.size;
+}
+/**
+ * One look, answered within `deadlineMs` whatever the folder does: its value, or that the folder didn't answer (it ran
+ * past the deadline, the same look is still stuck, or every child slot is held) or the look failed. A look already
+ * under way for the same request is joined, never started twice.
+ */
+export async function lookFolders(request, options = {}) {
+    const deadlineMs = options.deadlineMs ?? FOLDER_LOOK_MS;
+    const key = lookKey(request);
+    let run = inFlight.get(key);
+    if (run === undefined) {
+        if (inFlight.size >= FOLDER_LOOK_CHILDREN)
+            return { ok: false, why: "no-answer" };
+        try {
+            run = (options.runner ?? childLook)(request, deadlineMs);
+        }
+        catch {
+            return { ok: false, why: "failed" };
+        }
+        const mine = run;
+        inFlight.set(key, mine);
+        const forget = () => { if (inFlight.get(key) === mine)
+            inFlight.delete(key); };
+        mine.ended.then(forget, forget);
+    }
+    let timer;
+    const late = new Promise(resolveLate => { timer = setTimeout(() => resolveLate("late"), deadlineMs); });
+    try {
+        const first = await Promise.race([run.answer.then(value => ({ value }), () => "failed"), late]);
+        if (first === "late")
+            return { ok: false, why: "no-answer" };
+        if (first === "failed")
+            return { ok: false, why: "failed" };
+        const answer = first.value;
+        if (answer === null || typeof answer !== "object" || answer.ok !== true)
+            return { ok: false, why: "failed" };
+        return { ok: true, value: answer.value };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const text = (value) => typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\0");
+/** A folder's sub-folders for the browse page (null `at`: outside every root, or not a folder). */
+export async function listFolder(path, roots, options = {}) {
+    const looked = await lookFolders({ op: "list", path, roots: [...roots], home: options.home ?? homedir() }, options);
+    if (!looked.ok)
+        return looked;
+    const value = looked.value;
+    if (value === null || typeof value !== "object" || !(value.at === null || text(value.at)) || !Array.isArray(value.entries))
+        return { ok: false, why: "failed" };
+    const entries = value.entries.flatMap((one) => {
+        const row = one;
+        return row !== null && typeof row === "object" && text(row.name) && text(row.path) && typeof row.git === "boolean" ? [{ name: row.name, path: row.path, git: row.git }] : [];
+    });
+    return { ok: true, value: { at: value.at, entries } };
+}
+/** The origin URL of each registered project, and the repositories directly in each root with theirs. */
+export async function localOrigins(registered, roots, options = {}) {
+    const looked = await lookFolders({ op: "origins", registered: [...registered], roots: [...roots], home: options.home ?? homedir() }, options);
+    if (!looked.ok)
+        return looked;
+    const value = looked.value;
+    if (value === null || typeof value !== "object" || !Array.isArray(value.registered) || !Array.isArray(value.found))
+        return { ok: false, why: "failed" };
+    const rows = (list) => list.flatMap((one) => {
+        const row = one;
+        return row !== null && typeof row === "object" && text(row.path) && (row.url === null || text(row.url)) ? [{ path: row.path, url: row.url }] : [];
+    });
+    return { ok: true, value: { registered: rows(value.registered), found: rows(value.found) } };
+}
+/** Each path's identity (its real path when that is a folder, else null), resolved off the thread. */
+export async function lookIdentities(paths, options = {}) {
+    const looked = await lookFolders({ op: "identities", paths: [...paths] }, options);
+    if (!looked.ok)
+        return looked;
+    const value = looked.value;
+    if (value === null || typeof value !== "object" || !Array.isArray(value.paths))
+        return { ok: false, why: "failed" };
+    const out = new Map();
+    for (const one of value.paths) {
+        const row = one;
+        if (row !== null && typeof row === "object" && text(row.path) && (row.real === null || text(row.real)))
+            out.set(row.path, row.real);
+    }
+    return { ok: true, value: out };
+}
+/** A project's own `.mcp.json` (parsed object, or null when absent or not one), read off the thread. */
+export async function lookProjectMcp(repo, options = {}) {
+    const looked = await lookFolders({ op: "projectMcp", path: repo }, options);
+    if (!looked.ok)
+        return looked;
+    const value = looked.value;
+    if (value === null || typeof value !== "object")
+        return { ok: false, why: "failed" };
+    const config = value.config;
+    return { ok: true, value: config !== null && typeof config === "object" && !Array.isArray(config) ? config : null };
+}

package/dist/learning-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/learning-child.js

@@ -0,0 +1,34 @@
+/**
+ * Started only by learning-look.ts: one project's learning recovery (project-learning.ts acceptedIdentities and
+ * recoverLearning) in a process of its own, so its synchronous reads of the project's Git folder can never hold the
+ * console's thread. It opens the database without migrating, does that one project, and ends; the console kills it
+ * at its deadline. Its one argument is JSON naming the database, the evidence folder and the project.
+ */
+import { acceptedIdentities, recoverLearning } from "./project-learning.js";
+import { openStoreNoMigrate } from "./store.js";
+const input = JSON.parse(process.argv[2] ?? "null");
+const text = (value) => typeof value === "string" && value !== "" && !value.includes("\0");
+if (input === null || !text(input.databaseFile) || !text(input.evidenceRoot) || !text(input.repo))
+    process.exit(2);
+const opened = openStoreNoMigrate(input.databaseFile);
+if (!opened.ok)
+    process.exit(3);
+let code = 0;
+try {
+    try {
+        acceptedIdentities(opened.store, input.repo);
+    }
+    catch {
+        code = 1;
+    }
+    try {
+        recoverLearning(opened.store, input.evidenceRoot, input.repo);
+    }
+    catch {
+        code = 1;
+    }
+}
+finally {
+    opened.store.close();
+}
+process.exit(code);

package/dist/learning-look.d.ts

@@ -0,0 +1,25 @@
+import { type FirstTaskSuggestion } from "./first-run.js";
+/** How long one project's recovery may take before it is stopped (the next pass tries again). */
+export declare const LEARNING_LOOK_MS = 60000;
+/** How long reading one project's first-task suggestions may take. */
+export declare const FIRST_TASKS_LOOK_MS = 20000;
+export type LearningOutcome = "done" | "failed" | "no-answer";
+export type LearningRunner = (input: {
+    databaseFile: string;
+    evidenceRoot: string;
+    repo: string;
+}, deadlineMs: number) => Promise<LearningOutcome>;
+/** The production learning runner: learning-child in its own process. */
+export declare const learningChild: LearningRunner;
+/** Recover learning for each project in turn, each in its own bounded process. */
+export declare function recoverLearningOffThread(input: {
+    databaseFile: string;
+    evidenceRoot: string;
+    repos: readonly string[];
+}, options?: {
+    runner?: LearningRunner;
+    deadlineMs?: number;
+}): Promise<Map<string, LearningOutcome>>;
+/** One project's first-task suggestions (first-run.ts findFirstTasks: its issues through gh, its TODOs through the
+ * hardened git) read in a process of its own. Rejects when it failed or didn't answer: the caller keeps the generic ones. */
+export declare function firstTasksOffThread(repo: string, deadlineMs?: number): Promise<FirstTaskSuggestion[]>;

package/dist/learning-look.js

@@ -0,0 +1,72 @@
+/**
+ * Work that reads a project's own folder synchronously, run in a process of its own and killed at a deadline, so a
+ * folder that doesn't answer (a disconnected drive, an iCloud folder macOS is holding) costs that one piece of work,
+ * never the console's thread: learning recovery (learning-child.ts) and Chat's first-task suggestions
+ * (first-tasks-child.ts).
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {} from "./first-run.js";
+/** How long one project's recovery may take before it is stopped (the next pass tries again). */
+export const LEARNING_LOOK_MS = 60_000;
+/** How long reading one project's first-task suggestions may take. */
+export const FIRST_TASKS_LOOK_MS = 20_000;
+/** Only what git and gh need from the environment (no NODE_OPTIONS, no other secrets). */
+const CHILD_ENV = ["PATH", "HOME", "TMPDIR", "LANG", "USER", "XDG_CONFIG_HOME", "GH_TOKEN", "GITHUB_TOKEN", "GH_HOST", "GH_CONFIG_DIR"];
+/** One of this build's own child entries, given `input` as JSON, killed at the deadline. Its stdout, bounded. */
+function ownChild(name, input, deadlineMs) {
+    return new Promise(resolveOutcome => {
+        const source = import.meta.url.endsWith(".ts");
+        const entry = fileURLToPath(new URL(source ? `./${name}.ts` : `./${name}.js`, import.meta.url));
+        const env = { ELECTRON_RUN_AS_NODE: "1" };
+        for (const one of CHILD_ENV)
+            if (process.env[one] !== undefined)
+                env[one] = process.env[one];
+        const child = spawn(process.execPath, [...(source ? ["--import", import.meta.resolve("tsx")] : []), entry, JSON.stringify(input)], {
+            stdio: ["ignore", "pipe", "ignore"], env, killSignal: "SIGKILL",
+        });
+        child.unref();
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.stdout.destroy();
+            resolveOutcome({ outcome, stdout: Buffer.concat(chunks).toString("utf8") });
+        };
+        const timer = setTimeout(() => { child.kill("SIGKILL"); settle("no-answer"); }, deadlineMs);
+        timer.unref();
+        child.stdout.on("data", (chunk) => { size += chunk.length; if (size <= 1024 * 1024)
+            chunks.push(chunk); });
+        child.once("error", () => settle("failed"));
+        child.once("close", code => settle(code === 0 ? "done" : "failed"));
+    });
+}
+/** The production learning runner: learning-child in its own process. */
+export const learningChild = async (input, deadlineMs) => (await ownChild("learning-child", input, deadlineMs)).outcome;
+/** Recover learning for each project in turn, each in its own bounded process. */
+export async function recoverLearningOffThread(input, options = {}) {
+    const outcomes = new Map();
+    for (const repo of input.repos) {
+        outcomes.set(repo, await (options.runner ?? learningChild)({ databaseFile: input.databaseFile, evidenceRoot: input.evidenceRoot, repo }, options.deadlineMs ?? LEARNING_LOOK_MS));
+    }
+    return outcomes;
+}
+/** One project's first-task suggestions (first-run.ts findFirstTasks: its issues through gh, its TODOs through the
+ * hardened git) read in a process of its own. Rejects when it failed or didn't answer: the caller keeps the generic ones. */
+export async function firstTasksOffThread(repo, deadlineMs = FIRST_TASKS_LOOK_MS) {
+    const ran = await ownChild("first-tasks-child", { repo }, deadlineMs);
+    if (ran.outcome !== "done")
+        throw new Error(`the first-task read ${ran.outcome === "no-answer" ? "didn't answer" : "failed"}`);
+    const parsed = JSON.parse(ran.stdout);
+    if (!Array.isArray(parsed))
+        throw new Error("the first-task read answered something else");
+    return parsed.flatMap((one) => {
+        const row = one;
+        return row !== null && typeof row === "object" && (row.source === "issue" || row.source === "todo" || row.source === "generic") && typeof row.label === "string" && typeof row.draft === "string"
+            ? [{ source: row.source, label: row.label.slice(0, 500), draft: row.draft.slice(0, 4000) }] : [];
+    });
+}

package/dist/operate.d.ts

@@ -9,6 +9,7 @@ import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
 import { type RolePort, type UpRoleStart } from "./up-processes.js";
 import { type TelegramTransport } from "./telegram.js";
+import { type FolderLookOptions } from "./folder-look.js";
 import { type LeadCliSeams } from "./lead-cli.js";
 import { type Principal, type RemoteRun, type RemoteSource } from "./operate-remote.js";
 import { type PublishExec } from "./publish.js";
@@ -271,3 +272,34 @@ export declare function refreshGithubNightlies(store: Store, now: () => Date, re
  * - `recover [--abandon <campaign>]`: settle campaigns whose runner stopped; with --abandon, a person ends a stuck one.
  */
 export declare function evalsCommand(positional: readonly string[], flags: Map<string, string | true>, context: Context): Promise<number>;
+/**
+ * The saved projects an `up` start couldn't reach (upCommand): each is proved again every `everyMs` while the worker
+ * runs, by `prove` (upProveSaved), so a folder that answers again connects without a restart. Only what the start itself
+ * read from the saved list is here, and the set only shrinks: a line connected, removed from the saved list
+ * (`keepOnly`) or come back as some other checkout (`revoke`) is gone for good, so a line saved again later needs its
+ * recorded admission like any other addition. `retry` answers the proof when one is due and answered, else null.
+ */
+export declare function upDeferredRetry<T>(inputs: readonly string[], prove: (input: string) => Promise<T | null>, everyMs?: number, now?: () => number): {
+    has: (input: string) => boolean;
+    list: () => string[];
+    retry: (input: string) => Promise<T | null>;
+    revoke: (input: string) => void;
+    keepOnly: (saved: readonly string[]) => boolean;
+};
+/**
+ * Whether a saved project's folder is a Git checkout now, read without blocking this thread: `git rev-parse
+ * --show-toplevel` (bounded, its own process), then the real paths of the saved line and of the checkout, resolved off
+ * the thread under a deadline (folder-look.ts). Null when it isn't one, or didn't answer.
+ */
+export declare function upProveSaved(gitRun: (file: string, args: readonly string[], opts?: {
+    cwd?: string;
+}) => Promise<{
+    code: number | null;
+    stdout: string;
+}>, input: string, look?: FolderLookOptions): Promise<{
+    line: string;
+    root: string;
+} | null>;
+/** What `up` hands its next worker after the worker reports which saved projects it still holds start authority for:
+ * only what both still hold. A worker's report can give up an authority, never add or give back one. */
+export declare function upNarrowDeferred(held: readonly string[], reported: readonly string[]): string[];