toolroll 0.9.33 → 0.9.36

package/dist/browser-crew.js

@@ -47,6 +47,7 @@ export function browserCrewFromIndex(page, conversationId) {
             id: summary.rootId, title: summary.title, project: summary.repo,
             state: summary.assignmentState, label: status.label, tone: status.tone, href: link(href), resultHref: resultHref === null ? null : link(resultHref),
             action: action === null || actionHref === null ? null : { label: action.label, href: link(actionHref) },
+            updatedAt: summary.updatedAt,
             ...(summary.lead === undefined ? {} : { lead: summary.lead }),
         };
         return { item, rank: status.rank };

package/dist/browser-workspace.d.ts

@@ -47,6 +47,8 @@ export type BrowserCrewItem = {
         label: string;
         href: string;
     } | null;
+    /** When the task family last changed (the index's own sort time), shown as the row's age. */
+    updatedAt: string;
     /** "<name> is on it.": the person's own lead took it on, by the name they gave it. */
     lead?: string;
 };
@@ -800,9 +802,9 @@ export type BrowserFlowStage = {
     wait?: {
         for: "reply" | "time" | "hours";
         minutes: number;
-        from?: string;
-        to?: string;
-        timeZone?: string;
+        from?: string | undefined;
+        to?: string | undefined;
+        timeZone?: string | undefined;
     };
     /** A Pull request zone merges once checks pass (after a person approved), this way. */
     merge?: "squash" | "merge" | "rebase" | undefined;

package/dist/builder.js

@@ -63,6 +63,7 @@ import { openLiveLog } from "./live.js";
 import { CheckProgressTracker } from "./check-progress.js";
 import { captureParkEvidence, captureTerminalDiff, captureBaseTree, evidenceRoot, handoffName, isImagePath, WORKTREE_EVIDENCE_DIR, storeHandoffArtifact, looksLikeProtocolFile, mailboxName, progressFileName, proofFileName, rubricFileName, proposalFileName, quarantineMailboxes, readMailbox, readVerifiedArtifact, scanForSecrets, redactSecretLines, storeEvidence, validateScreenshotBytes, imageDimensions, SCREENSHOT_BYTE_CAP, boundStreamHeadTail } from "./evidence.js";
 import { PROOF_LIMITS, parseProof, serializeProof, adjudicate, artifactManifestOnly, sameDiffStatFacts } from "./proof.js";
+import { parseHandoffArtifact } from "./contracts/handoff.js";
 import { captureReviewContext } from "./review-context.js";
 import { authoritySnapshotDigest, classifyRevisionAuthority, isMilestoneRegression, milestonesOf, parseExecutionPlanDocument, parsePlanRevisionProposal, parseProgressSnapshot, renderExecutionPlanDocument, PROGRESS_LIMITS, REVISION_LIMITS, } from "./plan.js";
 import { maybeSettleRepairChain } from "./dispose.js";
@@ -1115,11 +1116,9 @@ export async function build(store, request) {
             try {
                 const verified = readVerifiedArtifact(root, handoffArtifact);
                 if (verified.ok) {
-                    const parsed = JSON.parse(verified.content.toString("utf8"));
-                    if (parsed.branch === branch &&
-                        typeof parsed.conclusion === "string" &&
-                        parsed.freshness?.currentAsOf === baseRevision) {
-                        previousHandoff = `A previous attempt (${String(parsed.outcome ?? "finished")}) left the branch exactly where it now stands and concluded: ${parsed.conclusion}`;
+                    const parsed = parseHandoffArtifact(verified.content.toString("utf8"));
+                    if (parsed.ok && parsed.value.branch === branch && parsed.value.freshness.currentAsOf === baseRevision) {
+                        previousHandoff = `A previous attempt (${parsed.value.outcome}) left the branch exactly where it now stands and concluded: ${parsed.value.conclusion}`;
                     }
                 }
             }
@@ -1740,7 +1739,6 @@ export async function settleProviderOutcome(captured, result) {
         store.setRunPhase(request.runId, "capturing-evidence");
         const diffEvidence = await captureTerminalDiff(store, git, worktree, pinnedBase, baseRevision, root, request.runId, clock());
         storeHandoffArtifact(store, root, {
-            schema: 1,
             taskId,
             runId: request.runId,
             provider,
@@ -1835,7 +1833,6 @@ export async function settleProviderOutcome(captured, result) {
             store.setRunPhase(request.runId, "capturing-evidence");
             const diffEvidence = await captureTerminalDiff(store, git, worktree, pinnedBase, head, root, request.runId, clock());
             storeHandoffArtifact(store, root, {
-                schema: 1,
                 taskId,
                 runId: request.runId,
                 provider,

package/dist/chat-acceptance.d.ts

@@ -45,7 +45,7 @@ export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprov
                 note: string | null;
             } | null;
             evidence: {
-                kind: import("./scope.js").EvidenceKind;
+                kind: "changed-path" | "check" | "manual-review" | "screenshot";
                 reference: string | null;
             }[];
             coverageGaps: (string | null)[];

package/dist/cli.d.ts

@@ -39,7 +39,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> connect one (no path: the repo you are in)\n  toolroll repos remove <path>\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)\n  toolroll repos remove <path>\n                                   take it out of the console; its tasks and results stay\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with

package/dist/cli.js

@@ -14,7 +14,9 @@ import { existsSync, lstatSync, realpathSync, unlinkSync, writeFileSync } from "
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { configPath, loadRepos, addRepos, removeRepos, updateRepos } from "./repos.js";
+import { configPath, loadRepos } from "./repos.js";
+import { addedWords, admitProject, commandLineActor, consoleRunning, proveProjectRoot, registryBeside, releaseProject } from "./project-admission.js";
+import { envValue } from "./names.js";
 import { CAPABILITIES, ENVELOPE_VERSION, capturedEnvelope, envelopeJson, onEnvelopeCaptured, resetCapturedEnvelope } from "./envelope.js";
 import { applyClaudeCodeInstall, applyInstall, contextBlock, defaultClaudeCodeSkillDir, planClaudeCodeInstall, planInstall, } from "./skills.js";
 import { GUIDES, guideNamed } from "./guides.js";
@@ -42,8 +44,9 @@ Usage
   toolroll pulls            report what is waiting on a person
   toolroll graph            report which work graph is already here
   toolroll repos            list connected repositories, and how to adjust
-  toolroll repos add <path> connect one (no path: the repo you are in)
+  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)
   toolroll repos remove <path>
+                                   take it out of the console; its tasks and results stay
   toolroll repos add-from-github <owner/name> --root <dir>
                                    preview, then clone and connect (--yes)
   toolroll link             put \`toolroll\` on your PATH
@@ -545,15 +548,26 @@ async function runReposCommand(argv, write, onboard) {
     // `repos` honors the machine contract like everything else (audit TG-3):
     // --json answers with one envelope, whatever the outcome.
     const json = argv.includes("--json");
-    const bare = argv.filter(argument => argument !== "--json");
+    // The lead adds with its token (--token or TOOLROLL_LEAD_TOKEN); the owner needs none.
+    const tokenAt = argv.indexOf("--token");
+    const tokenFlag = tokenAt === -1 ? undefined : argv[tokenAt + 1];
+    const bare = argv.filter((argument, index) => argument !== "--json" && (tokenAt === -1 || (index !== tokenAt && index !== tokenAt + 1)));
     const [action, ...paths] = bare;
-    const file = configFile();
+    const databaseFile = databasePath(process.env, homedir());
+    const file = registryBeside(databaseFile);
+    if (tokenAt !== -1 && (tokenFlag === undefined || tokenFlag.startsWith("-"))) {
+        const message = "--token needs the lead token";
+        write(json ? envelopeJson({ ok: false, command: `repos ${action ?? ""}`.trim(), reason: "usage", message }) : message);
+        return USAGE_EXIT;
+    }
+    const envLead = envValue(process.env, "LEAD_TOKEN");
+    const leadToken = tokenFlag ?? (envLead === undefined || envLead === "" ? undefined : envLead);
     // Dispatched BEFORE the registry load (verification finding 3): a
     // malformed registry must not mask this command's own parsing, its
     // read-only preview, or its taxonomy — enrollment reads the registry
     // through the locked primitive at the moment it writes.
     if (action === "add-from-github") {
-        return addFromGithubCommand(bare.slice(1), json, file, write, onboard);
+        return addFromGithubCommand(bare.slice(1), json, write, { databaseFile, registryFile: file, ...(leadToken === undefined ? {} : { leadToken }) }, onboard);
     }
     const loaded = await loadRepos(file);
     if ("error" in loaded) {
@@ -574,24 +588,45 @@ async function runReposCommand(argv, write, onboard) {
     }
     // `repos add` with no path means the repository you are standing in.
     const targets = (paths.length > 0 ? paths : [process.cwd()]).map(path => resolve(path));
+    const lines = [];
+    const said = {};
+    const say = json ? (line) => lines.push(line) : write;
+    const code = await withAdmission({ databaseFile, registryFile: file, ...(leadToken === undefined ? {} : { leadToken }) }, say, said, admission => action === "add" ? addToRepos(admission, targets, say, said) : removeFromRepos(admission, targets, say, said));
     if (json) {
-        const lines = [];
-        const said = {};
-        const code = action === "add"
-            ? await addToRepos(loaded.repos, targets, file, line => lines.push(line), said)
-            : await removeFromRepos(loaded.repos, targets, file, line => lines.push(line), said);
         write(envelopeJson({
             ok: code === 0,
             command: `repos ${action}`,
             ...(code === 0 ? {} : { reason: said.reason ?? "usage" }),
             message: lines.join(" "),
             targets,
+            ...(said.projects === undefined ? {} : { projects: said.projects }),
         }));
-        return code;
     }
-    return action === "add"
-        ? addToRepos(loaded.repos, targets, file, write)
-        : removeFromRepos(loaded.repos, targets, file, write);
+    return code;
+}
+/** Open this installation's database as the owner (or its lead) for one addition or removal. */
+async function withAdmission(where, write, said, body) {
+    let store;
+    try {
+        store = openStore(where.databaseFile);
+    }
+    catch (error) {
+        said.reason = "database";
+        write(`Toolroll's database couldn't be opened (${String(error.message ?? error)}). Nothing changed.`);
+        return 1;
+    }
+    try {
+        const actor = commandLineActor(store, { databaseFile: where.databaseFile, ...(where.leadToken === undefined ? {} : { leadToken: where.leadToken }) });
+        if ("ok" in actor) {
+            said.reason = "refused";
+            write(actor.message);
+            return 3;
+        }
+        return await body({ store, registryFile: where.registryFile, actor });
+    }
+    finally {
+        store.close();
+    }
 }
 function listRepos(repos, file, write) {
     if (repos.length === 0) {
@@ -606,59 +641,67 @@ function listRepos(repos, file, write) {
     for (const repo of repos)
         write(`  ${repo}${existsSync(repo) ? "" : "   (missing)"}`);
     write("");
-    write("  toolroll repos add <path>      connect another");
-    write("  toolroll repos remove <path>   disconnect one");
+    write("  toolroll repos add <path>      add another; it is in the console at once");
+    write("  toolroll repos remove <path>   take one out of the console; its tasks stay");
     write("  toolroll repos add-from-github <owner/name> --root <dir>   clone from GitHub and connect");
     write("  toolroll --all                 report everything, ignoring this list");
     write(`  ${file}`);
     return 0;
 }
-async function addToRepos(existing, targets, file, write, said) {
-    // Enrolling something that is not a repository would fail later and further
-    // away, so it fails here instead.
-    const rejected = targets.filter(path => !existsSync(join(path, ".git")));
-    if (rejected.length > 0) {
-        for (const path of rejected)
-            write(`${path} is not a git repository.`);
-        if (said !== undefined)
-            said.reason = "usage";
-        return USAGE_EXIT;
-    }
-    const added = targets.filter(path => !existing.includes(path));
-    const wrote = await updateRepos(file, repos => addRepos(repos, targets));
-    if (!wrote.ok) {
-        // The updater's own taxonomy survives (verification finding 4): a held
-        // lock or a malformed registry is an operational fact, never "usage".
-        if (said !== undefined)
-            said.reason = wrote.reason;
-        write(`could not update the connected list — ${wrote.message}`);
-        return 1;
+/** The exit code an admission failure answers with: a folder problem is the caller's to fix (usage). */
+function admissionExit(reason) {
+    return reason === "not-git" || reason === "unavailable" ? USAGE_EXIT : 1;
+}
+async function addToRepos(admission, targets, write, said) {
+    // Every folder is proved before anything is written: one that is not a
+    // repository fails here, not later and further away.
+    let refused = false;
+    for (const path of targets) {
+        const proved = await proveProjectRoot(path);
+        if (!proved.ok) {
+            write(proved.message);
+            said.reason ??= proved.reason;
+            refused = true;
+        }
     }
-    if (added.length === 0) {
-        write(`Already connected: ${targets.join(", ")}`);
-        return 0;
+    if (refused)
+        return USAGE_EXIT;
+    const now = new Date();
+    const running = consoleRunning(admission.store, now);
+    const projects = [];
+    for (const path of targets) {
+        const admitted = await admitProject(admission.store, { registryFile: admission.registryFile, path, actor: admission.actor, now });
+        if (!admitted.ok) {
+            // The updater's own taxonomy survives (verification finding 4): a held
+            // lock or a malformed registry is an operational fact, never "usage".
+            said.reason = admitted.reason;
+            said.projects = projects;
+            write(admitted.message);
+            return admissionExit(admitted.reason);
+        }
+        projects.push({ repo: admitted.repo, name: admitted.name, added: admitted.added });
+        write(addedWords(admitted.name, admitted.added, running));
     }
-    for (const path of added)
-        write(`Connected ${path}`);
-    write("");
-    write("`toolroll` now reports these. `toolroll --all` still shows everything.");
+    said.projects = projects;
     return 0;
 }
-async function removeFromRepos(existing, targets, file, write, said) {
-    const removed = targets.filter(path => existing.includes(path));
-    if (removed.length === 0) {
-        write(`Not connected: ${targets.join(", ")}`);
-        return 0;
-    }
-    const wrote = await updateRepos(file, repos => removeRepos(repos, targets));
-    if (!wrote.ok) {
-        if (said !== undefined)
-            said.reason = wrote.reason;
-        write(`could not update the connected list — ${wrote.message}`);
-        return 1;
+async function removeFromRepos(admission, targets, write, said) {
+    const now = new Date();
+    const projects = [];
+    for (const path of targets) {
+        const released = await releaseProject(admission.store, { registryFile: admission.registryFile, path, actor: admission.actor, now });
+        if (!released.ok) {
+            said.reason = released.reason;
+            said.projects = projects;
+            write(released.message);
+            return admissionExit(released.reason);
+        }
+        projects.push({ repo: released.repo, name: released.name, removed: released.removed });
+        write(released.removed
+            ? `Removed ${released.name}; it is no longer in the console. Its tasks and results stay saved.`
+            : `${released.name} isn't added, so nothing changed.`);
     }
-    for (const path of removed)
-        write(`Disconnected ${path}`);
+    said.projects = projects;
     return 0;
 }
 /**
@@ -669,7 +712,7 @@ async function removeFromRepos(existing, targets, file, write, said) {
  * primitive. Preview by default; --yes clones. Windows refuses like the
  * console does — tree death cannot be proven there.
  */
-async function addFromGithubCommand(argv, json, file, write, onboard) {
+async function addFromGithubCommand(argv, json, write, where, onboard) {
     const command = "repos add-from-github";
     const answer = (reason, message, code, extra = {}) => {
         write(json ? envelopeJson({ ok: false, command, reason, message, ...extra }) : message);
@@ -761,6 +804,12 @@ async function addFromGithubCommand(argv, json, file, write, onboard) {
     if (large && !largeOk) {
         return answer("large", `${previewed.preview.nameWithOwner} is large or of unknown size (${size}) — add --large-ok to clone it anyway; nothing was written`, 3);
     }
+    // Who may add is settled before anything is cloned.
+    const said = {};
+    const problems = [];
+    const allowed = await withAdmission(where, line => problems.push(line), said, async () => 0);
+    if (allowed !== 0)
+        return answer(said.reason ?? "refused", problems.join(" "), allowed);
     const cloned = await (onboard?.clone ?? cloneGithubRepo)(previewed.preview.nameWithOwner, root, async (cwd) => {
         const proof = await execRun("git", ["rev-parse", "--show-toplevel"], { cwd, timeoutMs: 15_000 });
         return { code: proof.code, stdout: proof.stdout };
@@ -770,15 +819,27 @@ async function addFromGithubCommand(argv, json, file, write, onboard) {
     if (cloned.target !== target) {
         return answer("malformed", "the clone answered with a different path than the preview promised — refused; nothing was connected", 1);
     }
-    const enrolled = await updateRepos(file, repos => addRepos(repos, [cloned.target]));
-    if (!enrolled.ok) {
-        return answer(enrolled.reason, `${cloned.target} is cloned but not connected — ${enrolled.message}; connect it with \`repos add ${cloned.target}\``, 1);
-    }
+    // The clone joins through the same admission as `repos add` and the console.
+    let words = "";
+    const code = await withAdmission(where, line => problems.push(line), said, async (admission) => {
+        const now = new Date();
+        const admitted = await admitProject(admission.store, { registryFile: admission.registryFile, path: cloned.target, actor: admission.actor, now });
+        if (!admitted.ok) {
+            said.reason = admitted.reason;
+            problems.push(`${cloned.target} is cloned but not added — ${admitted.message} Add it with \`repos add ${cloned.target}\`.`);
+            return 1;
+        }
+        words = addedWords(admitted.name, admitted.added, consoleRunning(admission.store, now));
+        return 0;
+    });
+    if (code !== 0)
+        return answer(said.reason ?? "failed", problems.join(" "), code);
     if (json) {
         write(envelopeJson({ ok: true, command, target: cloned.target, nameWithOwner: previewed.preview.nameWithOwner }));
         return 0;
     }
-    write(`Cloned ${previewed.preview.nameWithOwner} into ${cloned.target} and connected it.`);
+    write(`Cloned ${previewed.preview.nameWithOwner} into ${cloned.target}.`);
+    write(words);
     write("Large-file objects were not downloaded — run `git lfs pull` in the repository when you need them.");
     return 0;
 }

package/dist/contracts/contract-test.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The contract test every schema gets (docs/plans/zod-revamp.md, ground rule 7), framework-neutral so any test file
+ * can use it: each check returns the failures it found (empty when the contract holds), and `assertContract` throws
+ * them all at once.
+ *
+ * - The round trip toJSONSchema → fromJSONSchema → toJSONSchema loses no keyword.
+ * - Listed valid samples parse, including payloads saved by older versions.
+ * - Listed invalid samples are refused, and the refusal names each listed path (`steps[0].routes[0].goesTo: ...`).
+ */
+import { z } from "zod";
+/** Every keyword in a JSON Schema as `pointer keyword=value`, sorted, so two schemas compare keyword by keyword. */
+export declare function jsonSchemaKeywords(schema: unknown, pointer?: string): string[];
+/** The keywords the JSON Schema round trip drops or changes; empty when it loses nothing. */
+export declare function roundTripLoss(schema: z.ZodType): string[];
+/** What a contract's reader says about one input: accepted, or refused with path-named lines. */
+export type SampleVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    lines: readonly string[];
+};
+export type ValidSample = {
+    name: string;
+    input: unknown;
+};
+/** An input the contract refuses; `paths` are the paths its refusal must name (`goal`, `acceptance[0].evidence[0]`). */
+export type InvalidSample = {
+    name: string;
+    input: unknown;
+    paths: readonly string[];
+};
+export type ContractSpec = {
+    /** The model-facing schema, when the contract has one: its JSON Schema must survive the round trip. */
+    schema?: z.ZodType;
+    /** The contract's reader, the same one production uses. */
+    read: (input: unknown) => SampleVerdict;
+    valid: readonly ValidSample[];
+    invalid: readonly InvalidSample[];
+};
+/** Every way the samples disagree with the contract: a valid one refused, an invalid one accepted, a path unnamed. */
+export declare function replaySamples(spec: Pick<ContractSpec, "read" | "valid" | "invalid">): string[];
+/** Every failure of the contract test, round trip and samples together. */
+export declare function contractFailures(spec: ContractSpec): string[];
+/** Throws every failure at once; returns quietly when the contract holds. */
+export declare function assertContract(spec: ContractSpec): void;

package/dist/contracts/contract-test.js

@@ -0,0 +1,69 @@
+/**
+ * The contract test every schema gets (docs/plans/zod-revamp.md, ground rule 7), framework-neutral so any test file
+ * can use it: each check returns the failures it found (empty when the contract holds), and `assertContract` throws
+ * them all at once.
+ *
+ * - The round trip toJSONSchema → fromJSONSchema → toJSONSchema loses no keyword.
+ * - Listed valid samples parse, including payloads saved by older versions.
+ * - Listed invalid samples are refused, and the refusal names each listed path (`steps[0].routes[0].goesTo: ...`).
+ */
+import { z } from "zod";
+import { toModelSchema } from "./contract.js";
+/** Every keyword in a JSON Schema as `pointer keyword=value`, sorted, so two schemas compare keyword by keyword. */
+export function jsonSchemaKeywords(schema, pointer = "") {
+    if (Array.isArray(schema))
+        return schema.flatMap((item, index) => jsonSchemaKeywords(item, `${pointer}/${index}`)).sort();
+    if (schema === null || typeof schema !== "object")
+        return [];
+    const out = [];
+    for (const [key, value] of Object.entries(schema)) {
+        if (value !== null && typeof value === "object") {
+            if (Array.isArray(value) && value.every(item => item === null || typeof item !== "object"))
+                out.push(`${pointer} ${key}=${JSON.stringify(value)}`);
+            else
+                out.push(...jsonSchemaKeywords(value, `${pointer}/${key}`));
+        }
+        else {
+            out.push(`${pointer} ${key}=${JSON.stringify(value)}`);
+        }
+    }
+    return out.sort();
+}
+/** The keywords the JSON Schema round trip drops or changes; empty when it loses nothing. */
+export function roundTripLoss(schema) {
+    const before = toModelSchema(schema);
+    const after = toModelSchema(z.fromJSONSchema(before));
+    const kept = new Set(jsonSchemaKeywords(after));
+    return jsonSchemaKeywords(before).filter(keyword => !kept.has(keyword)).map(keyword => `lost in the round trip: ${keyword}`);
+}
+/** Every way the samples disagree with the contract: a valid one refused, an invalid one accepted, a path unnamed. */
+export function replaySamples(spec) {
+    const failures = [];
+    for (const sample of spec.valid) {
+        const verdict = spec.read(sample.input);
+        if (!verdict.ok)
+            failures.push(`${sample.name}: refused — ${verdict.lines.join("; ")}`);
+    }
+    for (const sample of spec.invalid) {
+        const verdict = spec.read(sample.input);
+        if (verdict.ok) {
+            failures.push(`${sample.name}: accepted, expected a refusal naming ${sample.paths.join(", ")}`);
+            continue;
+        }
+        for (const path of sample.paths) {
+            if (!verdict.lines.some(line => line.startsWith(`${path}:`)))
+                failures.push(`${sample.name}: no line names ${path} — ${verdict.lines.join("; ")}`);
+        }
+    }
+    return failures;
+}
+/** Every failure of the contract test, round trip and samples together. */
+export function contractFailures(spec) {
+    return [...(spec.schema === undefined ? [] : roundTripLoss(spec.schema)), ...replaySamples(spec)];
+}
+/** Throws every failure at once; returns quietly when the contract holds. */
+export function assertContract(spec) {
+    const failures = contractFailures(spec);
+    if (failures.length > 0)
+        throw new Error(`the contract does not hold:\n${failures.map(one => `- ${one}`).join("\n")}`);
+}

package/dist/contracts/contract.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The one way Toolroll describes a contract (docs/plans/zod-revamp.md): one Zod schema, and everything else — the
+ * TypeScript type, the runtime check, the JSON Schema a model gets, the text limits — derived from it.
+ *
+ * The helpers here hold the ground rules every contract shares: limits come from TEXT_LIMITS, persisted payloads are
+ * versioned, refusals name the path, and a model-facing schema is exactly what its JSON Schema says (no refinements or
+ * transforms; those checks run in plain code after parsing, with a named error).
+ */
+import { z } from "zod";
+import { type TextLimitKey } from "../text-limits.js";
+/**
+ * A string bounded by its TEXT_LIMITS entry, never a literal. The limit rule rides along as the field's description,
+ * so a model reads the bound before it writes. Zod counts UTF-16 code units; for a limit named in bytes this is the
+ * schema's necessary bound (a string within N bytes is within N code units), and the byte count itself is checked in
+ * plain code after parsing.
+ */
+export declare function limited(field: string, limitKey: TextLimitKey): z.ZodString;
+/** A versioned payload envelope: a strict object whose `version` is exactly `version`. */
+export declare function versioned<V extends number, S extends z.ZodRawShape>(version: V, shape: S): z.ZodObject<{
+    version: z.ZodLiteral<V>;
+} & S extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strict>;
+/** One path-named refusal: where, what kind, and the line a person (or the repair turn) reads. */
+export type ContractIssue = {
+    /** `steps[0].routes[0].goesTo`; `payload` for the top level. */
+    path: string;
+    kind: "required" | "empty" | "unknown-key" | "too-long" | "too-many" | "too-few" | "wrong-type" | "bad-value" | "newer-version" | "invalid";
+    /** The line itself: `steps[0].routes[0].goesTo: required`. */
+    line: string;
+};
+/** `["steps", 0, "routes", 0, "goesTo"]` as `steps[0].routes[0].goesTo`. */
+export declare function pathOf(path: readonly PropertyKey[]): string;
+/**
+ * How a contract names a key it doesn't know: the keys a person or model often writes for one it does (`onFail` for
+ * `ifFails`, `to` for `goesTo`), tried in order against the keys allowed at that place. Without one that fits, a key
+ * spelled close to an allowed one (a case or a letter or two off) is suggested.
+ */
+export type ContractOptions = {
+    aliases?: Readonly<Record<string, readonly string[]>>;
+};
+type Where = {
+    schema?: z.ZodType;
+    input?: unknown;
+    options?: ContractOptions;
+};
+/**
+ * A Zod error as path-named issues, in the error's own order. Given the schema and input it came from, an unknown key
+ * also says which allowed key it most likely meant (`unknown key 'onFail' (did you mean ifFails?)`).
+ */
+export declare function contractIssues(error: z.ZodError, where?: Where): ContractIssue[];
+/** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
+export declare function contractError(error: z.ZodError, where?: Where): string[];
+/** A refusal as a reader reports it: a stable reason code, and the path-named line as the message. */
+export type ContractProblem = {
+    reason: string;
+    message: string;
+};
+/**
+ * A contract issue as a problem with a reason code built from its path — `missing-goal`, `criteria[0].how-too-long`,
+ * `checks-too-many`, `payload-unknown-key`, `bad-version`, `newer-version` — so callers that branch on a reason, and
+ * durable outcomes that recorded one, read the same as before the contract.
+ */
+export declare function contractProblemOf(issue: ContractIssue): ContractProblem;
+export type ContractResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: ContractIssue[];
+};
+/** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
+export declare function parseContract<T>(schema: z.ZodType<T>, input: unknown, options?: ContractOptions): ContractResult<T>;
+/**
+ * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
+ * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
+ * refused plainly; anything else is an unknown version.
+ */
+export declare function readVersioned<T>(schema: z.ZodType<T> & {
+    shape: {
+        version: z.ZodLiteral<number>;
+    };
+}, input: unknown, upgrades?: Readonly<Record<number, (payload: Record<string, unknown>) => unknown>>, options?: ContractOptions): ContractResult<T>;
+/**
+ * The JSON Schema a model gets for `schema` (Claude's `--json-schema`). Throws when the schema uses refine,
+ * superRefine, transform or preprocess anywhere: what a model is told must be everything the schema checks.
+ */
+export declare function toModelSchema(schema: z.ZodType): Record<string, unknown>;
+export {};