toolroll 0.9.88 → 0.9.90

package/dist/person-proof.js

@@ -3,6 +3,9 @@
 const METHOD_IS_PERSON = {
     "password-now": true, "sso-now": true, "fresh-password": true, "fresh-sso": true, "session": true, "cli-login": true,
     "remote-token": false, "lead-token": false,
+    // Easy-start C1: the laptop's own owner in an allowlisted act — a person, standing only while local mode stays on at
+    // the generation it was given under (approval-authority.ts localSealStandsSql).
+    "local-owner": true,
 };
 /** Proofs that aren't credential methods: the paired-chat tap, and the phone plan's passkey ceremony. */
 const OTHER_PERSON_PROOFS = new Set(["chat", "passkey"]);

package/dist/project-access.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isAbsolute, resolve } from "node:path";
 import { canonicalProject } from "./project.js";
+import { FolderUnavailable } from "./folder-gate.js";
 export function normalizeProjectAccess(value) {
     if (value === null)
         return null;
@@ -26,7 +27,20 @@ export function readProjectAccess(value) {
     }
 }
 export function projectAccessAllows(access, repo) {
-    return access === null || (repo !== null && access.includes(canonicalProject(repo) ?? resolve(repo)));
+    if (access === null)
+        return true;
+    if (repo === null)
+        return false;
+    // A folder the console's gate holds back (folder-gate.ts) is unavailable: access to it is denied, never decided by
+    // its spelling.
+    try {
+        return access.includes(canonicalProject(repo) ?? resolve(repo));
+    }
+    catch (error) {
+        if (error instanceof FolderUnavailable)
+            return false;
+        throw error;
+    }
 }
 /** SQL: projectAccessAllows for an `approver` row (`alias`) and a project path expression, for the dispatch belts. A
  * null list reaches every project; an unreadable one reaches none. */

package/dist/project-admission.d.ts

@@ -42,9 +42,11 @@ export type Released = {
     removed: boolean;
 };
 export declare const PROJECT_ADDED = "project added";
+/** A folder's real path (a folder), null (not one), or "no-answer" (it didn't answer in time). */
+export type FolderResolver = (path: string) => Promise<string | null | "no-answer">;
 export declare const PROJECT_REMOVED = "project removed";
 /** The checkout root a folder belongs to, canonical; never a shell. */
-export declare function proveProjectRoot(path: string, exec?: ProjectExec): Promise<{
+export declare function proveProjectRoot(path: string, exec?: ProjectExec, resolveFolder?: FolderResolver): Promise<{
     ok: true;
     repo: string;
 } | AdmissionFailure>;
@@ -63,6 +65,9 @@ export declare function admitProject(store: Store, input: {
     /** The caller's authority, asked again about the proved repo inside the locked registry update and inside the
      * database transaction (the console: nothing it proved before an await moved, and the repo is still visible). */
     stillAllowed?: (repo: string) => boolean;
+    /** How the folder and its checkout root are resolved (the console: off its thread, under a deadline). Absent:
+     * canonicalProject. */
+    resolveFolder?: FolderResolver;
 }): Promise<Admitted | AdmissionFailure>;
 /**
  * Remove one project from the lists and the builder. Its tasks, results and

package/dist/project-admission.js

@@ -17,6 +17,7 @@ import { run } from "./exec.js";
 import { canonicalProject, projectName, sameRepo } from "./project.js";
 import { remoteUrlProblem } from "./remote-main.js";
 import { addRepos, loadProjectRegistry, removeRepos, updateRepos } from "./repos.js";
+import { FolderUnavailable } from "./folder-gate.js";
 const ADMISSION_GIT = {
     envAllowlist: ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"],
     env: { GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_NO_REPLACE_OBJECTS: "1" },
@@ -24,15 +25,23 @@ const ADMISSION_GIT = {
 export const PROJECT_ADDED = "project added";
 export const PROJECT_REMOVED = "project removed";
 /** The checkout root a folder belongs to, canonical; never a shell. */
-export async function proveProjectRoot(path, exec = run) {
+export async function proveProjectRoot(path, exec = run, resolveFolder) {
     if (path.trim() === "" || path.length > 4096 || /[\x00-\x1f]/.test(path)) {
         return { ok: false, reason: "unavailable", message: "Choose a valid project folder." };
     }
-    const canonical = canonicalProject(path);
+    // The console resolves both folders off its thread (project-identity.ts resolveNow): its thread never waits on one.
+    const canon = async (one) => resolveFolder === undefined ? canonicalProject(one) : resolveFolder(one);
+    const didntAnswer = (one) => ({ ok: false, reason: "unavailable", message: `${one} didn't answer. It may be on a drive that's disconnected, or waiting on macOS; try again in a moment.` });
+    const canonical = await canon(path);
+    if (canonical === "no-answer")
+        return didntAnswer(path);
     if (canonical === null)
         return { ok: false, reason: "unavailable", message: `${path} isn't a folder on this computer.` };
     const top = await exec("git", ["rev-parse", "--show-toplevel"], { cwd: canonical, timeoutMs: 5_000, ...ADMISSION_GIT });
-    const repo = top.code === 0 ? canonicalProject(top.stdout.trim()) : null;
+    const topReal = top.code === 0 ? await canon(top.stdout.trim()) : null;
+    if (topReal === "no-answer")
+        return didntAnswer(top.stdout.trim());
+    const repo = topReal;
     if (repo === null)
         return { ok: false, reason: "not-git", message: `${path} isn't a Git repository. Run git init there first, or choose a folder inside one.` };
     return { ok: true, repo };
@@ -48,7 +57,7 @@ async function originOf(repo, exec) {
 }
 /** Registry first, then the project and its audit records in one transaction. Re-adds preserve trust. */
 export async function admitProject(store, input) {
-    const proved = await proveProjectRoot(input.path, input.exec);
+    const proved = await proveProjectRoot(input.path, input.exec, input.resolveFolder);
     if (!proved.ok)
         return proved;
     const { repo } = proved;
@@ -110,12 +119,40 @@ export async function admitProject(store, input) {
  * saved project changes nothing.
  */
 export async function releaseProject(store, input) {
-    const asked = canonicalProject(input.path) ?? resolve(input.path);
+    // Removing only narrows: a folder the console's gate holds back (folder-gate.ts) is removed by its exact saved path,
+    // and matches no other spelling.
+    // Latched for the whole removal: once its folder was unavailable, a later answer (during an await below) never
+    // widens it to other spellings.
+    const unavailable = (error) => error instanceof FolderUnavailable;
+    let asked, exactOnly = false;
+    try {
+        asked = canonicalProject(input.path) ?? resolve(input.path);
+    }
+    catch (error) {
+        if (!unavailable(error))
+            throw error;
+        asked = resolve(input.path);
+        exactOnly = true;
+    }
+    const same = (one) => {
+        if (exactOnly)
+            return false;
+        try {
+            return sameRepo(one, asked);
+        }
+        catch (error) {
+            if (unavailable(error)) {
+                exactOnly = true;
+                return false;
+            }
+            throw error;
+        }
+    };
     const loaded = input.registryFile === null ? { repos: [] } : await loadProjectRegistry(input.registryFile);
     if ("error" in loaded)
         return { ok: false, reason: "registry", message: loaded.error };
-    const entries = loaded.repos.filter(one => one === asked || sameRepo(one, asked));
-    const rows = store.listProjects().filter(one => one.path === asked || sameRepo(one.path, asked)).map(one => one.path);
+    const entries = loaded.repos.filter(one => one === asked || same(one));
+    const rows = store.listProjects().filter(one => one.path === asked || same(one.path)).map(one => one.path);
     const repo = entries[0] ?? rows[0] ?? asked;
     if (entries.length === 0 && rows.length === 0)
         return { ok: true, repo, name: projectName(repo), removed: false };

package/dist/project-identity.d.ts

@@ -16,6 +16,7 @@
  *
  * An embedder or test that passes no identities gets `syncProjectIdentities`: the old synchronous reads, unchanged.
  */
+import { type FolderGate } from "./folder-gate.js";
 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
@@ -36,9 +37,16 @@ export type ProjectIdentities = {
     /** 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;
+    /** Whether a synchronous read inside `path` may happen on the console's thread now (folder-gate.ts): the folder it is
+     * in answered a look within the last few minutes, and no look at it since went unanswered. Reads nothing. */
+    answering: (path: string) => boolean;
 };
 /** 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;
+/** The console's folder gate (folder-gate.ts): its own data folders (the database's, evidence, build checkouts) are read
+ * freely when the console names them; a path read from a file a build can write (`pointer`), and anything else, only
+ * while `answering` vouches for where it leads. */
+export declare function consoleFolderGate(identities: ProjectIdentities, own: readonly (string | undefined)[]): FolderGate;

package/dist/project-identity.js

@@ -17,10 +17,14 @@
  * An embedder or test that passes no identities gets `syncProjectIdentities`: the old synchronous reads, unchanged.
  */
 import { resolve } from "node:path";
+import { insideFolder } from "./folder-gate.js";
 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 long an answer vouches that its folder answers, for `answering`: past it (the background pass every 30 s
+ * renews it each minute), a synchronous read waits for the next look. */
+const ANSWERING_MS = 3 * STALE_MS;
 /** 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) {
@@ -137,6 +141,37 @@ export function projectIdentities(look = {}, now = Date.now) {
             passes = pass.then(() => undefined, () => undefined);
             return pass;
         },
+        answering: path => {
+            const when = now();
+            const recent = (at) => when - at < ANSWERING_MS;
+            // Decided on real paths only. First the spelling: a path under an answered spelling (the longest) is read where
+            // that answer says it leads, and only while that answer is recent, since a link can be pointed elsewhere.
+            let real = resolve(path);
+            let spelled = null;
+            for (const [key, answer] of answers) {
+                if (answer.real !== null && insideFolder(real, key) && (spelled === null || key.length > spelled.key.length))
+                    spelled = { key, real: answer.real, at: answer.at };
+            }
+            if (spelled !== null) {
+                if (!recent(spelled.at))
+                    return false;
+                real = resolve(spelled.real, `.${real.slice(spelled.key.length)}`);
+            }
+            // A folder whose last look didn't answer holds back every read inside where it leads, whatever older answer stands.
+            for (const key of suspect)
+                if (insideFolder(real, answers.get(key)?.real ?? key))
+                    return false;
+            // Otherwise the nearest real folder an answer names decides, by its newest answer; "/" vouches for nothing below it.
+            let nearest = null;
+            for (const answer of answers.values()) {
+                const folder = answer.real;
+                if (folder === null || (folder === "/" && real !== "/") || !insideFolder(real, folder))
+                    continue;
+                if (nearest === null || folder.length > nearest.folder.length || (folder.length === nearest.folder.length && answer.at > nearest.at))
+                    nearest = { folder, at: answer.at };
+            }
+            return nearest !== null && recent(nearest.at);
+        },
     };
 }
 /** The synchronous reads, as before: for embedders and tests that pass no identities. */
@@ -149,5 +184,13 @@ export function syncProjectIdentities() {
         resolveNow: async (path) => canonicalProject(path),
         generation: () => 0,
         refresh: async () => true,
+        answering: () => true,
     };
 }
+/** The console's folder gate (folder-gate.ts): its own data folders (the database's, evidence, build checkouts) are read
+ * freely when the console names them; a path read from a file a build can write (`pointer`), and anything else, only
+ * while `answering` vouches for where it leads. */
+export function consoleFolderGate(identities, own) {
+    const folders = [...new Set(own.filter((one) => typeof one === "string" && one !== "").map(one => resolve(one)))];
+    return (path, pointer) => (!pointer && folders.some(folder => insideFolder(path, folder))) || identities.answering(path);
+}

package/dist/project-knowledge.d.ts

@@ -22,19 +22,18 @@ export type KnowledgeView = ReturnType<typeof knowledgeView>;
 export declare function knowledgeVersion(store: Store, repo: string, actor: string, revision: number): Knowledge;
 /** 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): {
-    history?: never;
+    content?: never;
     revision: number;
     stale: boolean;
     notice: string;
     decision?: never;
     title?: never;
-    content?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
 } | {
-    revision?: never;
-    history?: never;
+    content?: never;
     stale?: never;
     decision: {
         repo: string;
@@ -52,26 +51,27 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
     };
     notice: string;
     title?: never;
-    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;
 } | {
+    content?: never;
     stale?: never;
     decision?: never;
     title?: never;
-    content?: never;
     revision: number;
     history: {
         revision: number;

package/dist/project.d.ts

@@ -16,6 +16,7 @@ export type ProjectExec = (file: string, args: readonly string[], options?: RunO
  * One canonicalization for every path that becomes project identity:
  * startup config, a session open, task placement. Comparisons elsewhere
  * fall back to raw equality for legacy rows written before this existed.
+ * Throws FolderUnavailable when the console's folder gate holds the read back (folder-gate.ts).
  */
 export declare function canonicalProject(path: string): string | null;
 /** Two repo identities, canonical when possible, raw-equal as the legacy fallback. */

package/dist/project.js

@@ -13,12 +13,18 @@
 import { realpathSync, statSync } from "node:fs";
 import { basename, resolve, sep } from "node:path";
 import { run } from "./exec.js";
+import { folderAnswers, FolderUnavailable } from "./folder-gate.js";
 /**
  * One canonicalization for every path that becomes project identity:
  * startup config, a session open, task placement. Comparisons elsewhere
  * fall back to raw equality for legacy rows written before this existed.
+ * Throws FolderUnavailable when the console's folder gate holds the read back (folder-gate.ts).
  */
 export function canonicalProject(path) {
+    // In the console, a folder that hasn't answered a look lately is not read on its thread (folder-gate.ts). That is
+    // "unavailable", never "not a folder": it throws, so no caller falls back to the path's spelling because of it.
+    if (!folderAnswers(path))
+        throw new FolderUnavailable(resolve(path));
     try {
         const real = realpathSync(resolve(path));
         return statSync(real).isDirectory() ? real : null;

package/dist/proposal.js

@@ -30,6 +30,7 @@ export { validateTaskText } from "./task-text.js";
 import { resolve } from "node:path";
 import { canonicalProject } from "./project.js";
 import { heuristicSizing, planningSignals, refineFiledSizing } from "./task-sizing.js";
+import { FolderUnavailable } from "./folder-gate.js";
 /** Provenance tokens are part of the audit surface: lowercase, bounded,
  * nothing that could render as anything but itself. */
 const FILED_VIA = /^[a-z][a-z0-9:-]{0,63}$/;
@@ -75,7 +76,16 @@ function checkRepo(given, admitted) {
     // directory resolves through symlinks; a path that does not exist yet
     // still normalizes, because filing must not depend on this machine
     // seeing every repo the plane knows about.
-    const canonical = canonicalProject(given) ?? resolve(given);
+    let canonical;
+    // A folder the console's gate holds back (folder-gate.ts) is unavailable: refused, never filed by its spelling.
+    try {
+        canonical = canonicalProject(given) ?? resolve(given);
+    }
+    catch (error) {
+        if (error instanceof FolderUnavailable)
+            return refuse("bad-repo", "that repository's folder didn't answer — it may be on a drive that's disconnected; try again in a moment");
+        throw error;
+    }
     if (admitted !== undefined && !admitted.includes(canonical)) {
         return refuse("outside-ceiling", "that repository is outside what this surface was configured to show");
     }

package/dist/quick-start.d.ts

@@ -1,4 +1,4 @@
-import { type AttachSeams } from "./console-instance.js";
+import { type AttachProof, type AttachSeams } from "./console-instance.js";
 export type QuickStartSeams = {
     databaseFile: string;
     cwd: string;
@@ -20,5 +20,7 @@ export type QuickStartSeams = {
 };
 /** Whether argv is a bare `toolroll` (nothing, or only --json). */
 export declare const isBareInvocation: (argv: readonly string[]) => boolean;
+/** This database's console, proved live without creating, migrating or changing anything (also easy-start.ts's). */
+export declare function proveConsoleReadOnly(databaseFile: string, build: string, attach?: AttachSeams): Promise<AttachProof>;
 /** null: not this command (outside a repository) — the caller scans as before. */
 export declare function runQuickStart(argv: readonly string[], write: (line: string) => void, seams: QuickStartSeams): Promise<number | null>;

package/dist/quick-start.js

@@ -45,7 +45,12 @@ function databasePresence(file) {
         return error.code === "ENOENT" ? "absent" : "unknown";
     }
 }
-async function prove(seams) {
+function prove(seams) {
+    return proveConsoleReadOnly(seams.databaseFile, seams.build, seams.attach ?? {});
+}
+/** This database's console, proved live without creating, migrating or changing anything (also easy-start.ts's). */
+export async function proveConsoleReadOnly(databaseFile, build, attach = {}) {
+    const seams = { databaseFile, build, attach };
     // Read only, never created or migrated, never cleaned up: proving changes nothing. "None" only when nothing of this
     // build can be running on it (no database yet, or one older than this build, which `up` brings up to date); a
     // database that can't be read, is mid-upgrade or is newer than this build can't be checked, so it is refused.

package/dist/recipes.js

@@ -12,6 +12,7 @@ import { applyModeToNewFiling } from "./plan-auto.js";
 import { canonicalProject } from "./project.js";
 import { RECIPE_FORMAT, RECIPE_LIMITS, readRecipeDocument } from "./contracts/recipes.js";
 import { resolve } from "node:path";
+import { FolderUnavailable } from "./folder-gate.js";
 export const RECIPE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS workflow_recipe (
   id TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),
@@ -47,7 +48,17 @@ export class RecipeError extends Error {
     }
 }
 const honest = (text) => !hasForbiddenControls(text) && !hasDisguisedText(text);
-const recipeProject = (repo) => canonicalProject(repo) ?? resolve(repo);
+const recipeProject = (repo) => {
+    // A project folder the console's gate holds back (folder-gate.ts) is unavailable, never matched by its spelling.
+    try {
+        return canonicalProject(repo) ?? resolve(repo);
+    }
+    catch (error) {
+        if (error instanceof FolderUnavailable)
+            throw new RecipeError("This project's folder didn't answer. Try again in a moment.", 503);
+        throw error;
+    }
+};
 /** What a refusal at each top-level field tells the person, after the path-named line. */
 const FIELD_ADVICE = {
     name: "Name, goal, exclusions, and allowed paths must be readable text.", description: "Name, goal, exclusions, and allowed paths must be readable text.",

package/dist/release-cli.js

@@ -297,7 +297,8 @@ function installedGateWorld() {
             db.exec("PRAGMA busy_timeout=5000");
             return db;
         },
-        servicePlists: () => ["com.toolroll.browser", "com.standing-orders.browser"].map(label => join(agents, `${label}.plist`))
+        // The laptop service too: two services on one database is a conflict the gate names, never one it skips.
+        servicePlists: () => ["com.toolroll.browser", "com.standing-orders.browser", "com.toolroll.up"].map(label => join(agents, `${label}.plist`))
             .filter(path => existsSync(path)).map(path => ({ path, text: readFileSync(path, "utf8") })),
     };
 }

package/dist/runner-process.d.ts

@@ -65,3 +65,12 @@ export declare function recordedHolderProvedGone(file: string, holder: {
     gone: false;
     why: string;
 };
+/**
+ * Whether a record is authentic for exactly this registration on this host (the checks holderProvedGone makes before
+ * it looks at any process): sealed with the stored credential hash, for this runner, host, registration and
+ * credential. Null when it stands; otherwise why not. It says nothing about which processes still run.
+ */
+export declare function recordStandsFor(record: RunnerProcessRecord | null, holder: {
+    runner: Runner;
+    credentialHash: string;
+}, host: string): string | null;

package/dist/runner-process.js

@@ -217,3 +217,21 @@ export function recordedHolderProvedGone(file, holder, host, probe = realProcess
         return { gone: false, why: "its process record changed during the exit proof" };
     return proof;
 }
+/**
+ * Whether a record is authentic for exactly this registration on this host (the checks holderProvedGone makes before
+ * it looks at any process): sealed with the stored credential hash, for this runner, host, registration and
+ * credential. Null when it stands; otherwise why not. It says nothing about which processes still run.
+ */
+export function recordStandsFor(record, holder, host) {
+    if (record === null)
+        return "no readable record of its processes";
+    const expected = sealRunnerProcessRecord(record, holder.credentialHash).signature;
+    if (typeof record.signature !== "string" || !/^[a-f0-9]{64}$/.test(record.signature)
+        || !timingSafeEqual(Buffer.from(record.signature, "hex"), Buffer.from(expected, "hex")))
+        return "its process record is not authenticated";
+    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || record.host !== host)
+        return "its record is for another worker or machine";
+    if (record.registeredAt !== holder.runner.registeredAt || record.credential !== credentialDigest(holder.credentialHash))
+        return "its record is from an earlier start";
+    return null;
+}

package/dist/sample-project.d.ts

@@ -0,0 +1,31 @@
+import { type ExecResult, type RunOptions } from "./exec.js";
+import type { Store } from "./store.js";
+export type GitRun = (file: string, args: readonly string[], options: RunOptions) => Promise<ExecResult>;
+export type SampleOutcome = {
+    ok: true;
+    path: string;
+    created: boolean;
+} | {
+    ok: false;
+    reason: "no-root" | "exists" | "failed";
+    message: string;
+};
+/** Make (or find again) the sample project in `root`, the folder projects go in. */
+export declare function createSampleProject(root: string | null, git?: GitRun): Promise<SampleOutcome>;
+/** The sample's own check: its one test file, run by Node's test runner. Fixed here; never anyone's input. */
+export declare const SAMPLE_CHECK_COMMAND = "node --test";
+/** Who the sample's check is recorded as approved by: Toolroll itself, never the person who clicked (no step-up). */
+export declare const SAMPLE_CHECK_ACTOR = "toolroll";
+/**
+ * The sample project's check, set as part of making it, so its first result reads checked: the fixed command above,
+ * recorded as Toolroll's (SAMPLE_CHECK_ACTOR), with the person who added the sample named in the ledger line. Only
+ * for a sample this request just made (the caller passes createSampleProject's `created: true`; a folder found again
+ * is never armed), only for the folder this made (our marker in its .git), and only while the project has never had
+ * a check at all (no verify_command row, live or revoked, for it or its quick check): a check someone cleared stays
+ * cleared, and one someone approved is never replaced. It takes no command: this is not a way to set a project's
+ * check. True when it set one now.
+ */
+export declare function registerSampleCheck(store: Pick<Store, "transact" | "handle" | "setVerifyCommand" | "recordAction">, made: {
+    path: string;
+    created: boolean;
+}, repo: string, addedBy: string, now: Date): boolean;

package/dist/sample-project.js

@@ -0,0 +1,141 @@
+/**
+ * The sample project the welcome offers ("Try a sample project"): a small real git repository — a README, one function
+ * and its test — made in the project folder, so a first task has something true to change. It is registered like any
+ * other project by its caller (project-admission.ts).
+ *
+ * The folder is claimed with an exclusive mkdir; a folder already there is used again only when it is ours (a real
+ * directory, not a link, holding our marker inside its .git), and refused otherwise: nothing in someone else's folder
+ * is touched. Git runs hardened (no system or global config, no hooks or hook templates, no fsmonitor, no signing, no
+ * prompts, an allowlisted environment), and a folder this call made is removed again when making it fails.
+ */
+import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { run } from "./exec.js";
+import { SAMPLE_PROJECT_NAME } from "./first-run.js";
+import { ENV, ENV_ALLOWLIST } from "./remote-main.js";
+import { TEARDOWN_FLAGS } from "./teardown-git.js";
+/** Inside the sample's .git: says the folder is the one this made (never tracked, so the work tree stays clean). */
+const MARKER = "toolroll-sample";
+const MARKER_TEXT = "Made by Toolroll's welcome as the sample project.\n";
+const FILES = {
+    "README.md": `# Toolroll sample
+
+A tiny project to try Toolroll on. \`src/price.js\` has one function, and \`test/price.test.js\` checks it.
+
+Run the tests with \`npm test\` (Node.js 22 or newer, nothing to install).
+
+Things to ask for:
+
+- Round prices to whole cents and add a test for it.
+- Refuse a negative discount with a clear error.
+- Add a short usage example to this README.
+`,
+    "package.json": `${JSON.stringify({ name: "toolroll-sample", version: "1.0.0", private: true, type: "module", scripts: { test: "node --test" } }, null, 2)}\n`,
+    "src/price.js": `/** The price after a percentage discount: priceWithDiscount(80, 25) is 60. */
+export function priceWithDiscount(price, percent) {
+  return price - (price * percent) / 100;
+}
+`,
+    "test/price.test.js": `import assert from "node:assert/strict";
+import { test } from "node:test";
+import { priceWithDiscount } from "../src/price.js";
+
+test("takes the discount off the price", () => {
+  assert.equal(priceWithDiscount(80, 25), 60);
+});
+`,
+    ".gitignore": "node_modules/\n",
+};
+/** Git for the sample: fixed settings first, an allowlisted environment with no system or global config. */
+const SAMPLE_FLAGS = [
+    ...TEARDOWN_FLAGS, "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false", "-c", "init.templateDir=",
+    "-c", "user.name=Toolroll", "-c", "user.email=sample@toolroll.invalid", "-c", "core.autocrlf=false",
+];
+function kindOf(path) {
+    try {
+        const seen = lstatSync(path);
+        return seen.isDirectory() && !seen.isSymbolicLink() ? "dir" : "other";
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "missing" : "other";
+    }
+}
+/** Ours: a real folder whose .git is a real folder holding our marker, a regular file with our words. */
+function isOurs(target) {
+    if (kindOf(target) !== "dir" || kindOf(join(target, ".git")) !== "dir")
+        return false;
+    const marker = join(target, ".git", MARKER);
+    try {
+        const seen = lstatSync(marker);
+        return seen.isFile() && seen.size === Buffer.byteLength(MARKER_TEXT) && readFileSync(marker, "utf8") === MARKER_TEXT;
+    }
+    catch {
+        return false;
+    }
+}
+/** Make (or find again) the sample project in `root`, the folder projects go in. */
+export async function createSampleProject(root, git = run) {
+    if (root === null || root === "" || !isAbsolute(root) || kindOf(root) !== "dir") {
+        return { ok: false, reason: "no-root", message: "There's no project folder to put the sample in." };
+    }
+    const target = join(root, SAMPLE_PROJECT_NAME);
+    if (isOurs(target))
+        return { ok: true, path: target, created: false };
+    try {
+        mkdirSync(target); // the claim: exclusive, and never through a link
+    }
+    catch {
+        return { ok: false, reason: "exists", message: `A folder named ${SAMPLE_PROJECT_NAME} is already there, so nothing was changed.` };
+    }
+    const fail = () => {
+        try {
+            rmSync(target, { recursive: true, force: true });
+        }
+        catch { /* left for a person to remove */ }
+        return { ok: false, reason: "failed", message: "The sample project couldn't be made. Nothing was added." };
+    };
+    try {
+        for (const [file, body] of Object.entries(FILES)) {
+            const path = join(target, file);
+            mkdirSync(join(path, ".."), { recursive: true });
+            writeFileSync(path, body, { flag: "wx" });
+        }
+        const options = { cwd: target, env: ENV, envAllowlist: ENV_ALLOWLIST, timeoutMs: 30_000 };
+        for (const args of [["init", "-q", "--template=", "-b", "main"], ["add", "--", "."], ["commit", "-q", "--no-verify", "-m", "Sample project"]]) {
+            const ran = await git("git", [...SAMPLE_FLAGS, ...args], options);
+            if (ran.code !== 0)
+                return fail();
+        }
+        writeFileSync(join(target, ".git", MARKER), MARKER_TEXT, { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        return fail();
+    }
+    return { ok: true, path: target, created: true };
+}
+/** The sample's own check: its one test file, run by Node's test runner. Fixed here; never anyone's input. */
+export const SAMPLE_CHECK_COMMAND = "node --test";
+const SAMPLE_CHECK_TIMEOUT_MS = 60_000;
+/** Who the sample's check is recorded as approved by: Toolroll itself, never the person who clicked (no step-up). */
+export const SAMPLE_CHECK_ACTOR = "toolroll";
+/**
+ * The sample project's check, set as part of making it, so its first result reads checked: the fixed command above,
+ * recorded as Toolroll's (SAMPLE_CHECK_ACTOR), with the person who added the sample named in the ledger line. Only
+ * for a sample this request just made (the caller passes createSampleProject's `created: true`; a folder found again
+ * is never armed), only for the folder this made (our marker in its .git), and only while the project has never had
+ * a check at all (no verify_command row, live or revoked, for it or its quick check): a check someone cleared stays
+ * cleared, and one someone approved is never replaced. It takes no command: this is not a way to set a project's
+ * check. True when it set one now.
+ */
+export function registerSampleCheck(store, made, repo, addedBy, now) {
+    if (!made.created || !isAbsolute(repo) || !isOurs(repo))
+        return false;
+    return store.transact(() => {
+        if (store.handle.prepare("SELECT 1 FROM verify_command WHERE repo IN (?, ?) LIMIT 1").get(repo, `quick:${repo}`) !== undefined)
+            return false;
+        store.setVerifyCommand({ repo, command: SAMPLE_CHECK_COMMAND, timeoutMs: SAMPLE_CHECK_TIMEOUT_MS, approvedBy: SAMPLE_CHECK_ACTOR }, now);
+        store.recordAction({ at: now.toISOString(), actor: SAMPLE_CHECK_ACTOR, repo, taskId: null, runId: null, action: "check approved", outcome: "approved", source: "policy",
+            detail: `the sample project's own test (${SAMPLE_CHECK_COMMAND}), set by Toolroll when ${addedBy} added the sample` });
+        return true;
+    });
+}