toolroll 0.9.4 → 0.9.5

package/dist/flow-pull-request.js

@@ -15,6 +15,7 @@
 import { createHash } from "node:crypto";
 import { assignmentOf } from "./assignment.js";
 import { cardFollowers, notifyPeople } from "./flow-people.js";
+import { adoptPublishedPullRequest } from "./publish.js";
 import { failingCheckOf, mergePullRequest, owePullRequest, pullRequestBlocker, pullRequestFollowOf } from "./pull-request-flow.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
@@ -56,6 +57,15 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
             body: `${said}${stage.onFail === null ? "" : `\n\nIt's back in ${titleOf(stage.onFail)}${revision === null ? "" : `, as revision ${revision}`}.`}` }, now);
         return true;
     };
+    // Publishing that can't proceed is not the build's fault: rebuilding wouldn't change it, so the card waits here,
+    // saying what to do, and the people on it hear once. It carries on by itself once the cause is fixed.
+    const stuck = (said) => {
+        if (!waiting(said))
+            return false;
+        const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
+        notifyPeople(store, card, people, null, { key: `pr-stuck:${card.entry}`, subject: `${stage.title} is waiting on you for “${card.title}”`, attention: true, body: said }, now);
+        return true;
+    };
     // With no failure path, a card that didn't pass waits for a person to move it (a move is a fresh visit).
     if (stage.onFail === null && card.waiting !== null && card.waiting.endsWith(" Fix it, then move the card to try again."))
         return false;
@@ -68,14 +78,27 @@ export async function pullRequestStep(store, flow, definition, stage, card, now,
     if (publication === null || pullRequestFollowOf(store, publication.id) === null) {
         if (publication === null) {
             const blocked = pullRequestBlocker(store, runId);
+            // Only a result that can't be published as built goes back to be built again.
+            if (blocked !== null && (blocked === "This result has no commit to publish." || blocked.includes("looks like a secret")))
+                return failed(blocked);
+            if (blocked === "Pull requests aren't set up for this project.")
+                return stuck("Pull requests aren't set up for this project. Turn them on in Projects → Pull requests (or run toolroll publish setup); the card carries on by itself.");
             if (blocked !== null)
-                return failed(blocked === "Pull requests aren't set up for this project." ? "Pull requests aren't set up for this project. Turn them on in Projects → Pull requests, then move the card back here." : blocked);
+                return stuck(blocked);
         }
         publication = owePullRequest(store, runId, `flow ${flow.name}`, card.id, now);
     }
+    if (publication.state === "failed") {
+        const said = `Couldn't open the pull request: ${publication.lastError ?? "GitHub refused it"}. The commit is safe locally. Fix that, then move the card back to Build for a fresh result.`;
+        if (card.waiting === said)
+            return false;
+        // A pull request opened for this commit anyway (another pass, or a person) is the card's pull request.
+        if (await adoptPublishedPullRequest(store, publication, io.gh, () => now))
+            publication = store.publicationForRun(runId);
+        else
+            return stuck(said);
+    }
     const pr = publication.prNumber === null ? "the pull request" : `PR #${publication.prNumber}`;
-    if (publication.state === "failed")
-        return failed(`Couldn't open the pull request: ${publication.lastError ?? "GitHub refused it"}. The commit is safe locally.`);
     if (publication.state !== "opened")
         return waiting(publication.lastError === null ? "Opening the pull request…" : `Opening the pull request. Retrying: ${publication.lastError}`);
     const link = publication.prUrl ?? pr;

package/dist/operate.js

@@ -178,7 +178,7 @@ import { scout as scoutTask } from "./scout.js";
 import { profileDigestOf, chainDigestOf, entryDigestOf } from "./scope.js";
 import { PROVIDER_KEY_ENV, SUBSCRIPTION_CAPABLE, clearProviderKey, keyStatus, readAuthMode, readAuthModeStrict, readProviderKey, saveProviderKey, setAuthMode, verifyProviderKey, verdictWords } from "./keys.js";
 import { run, terminateLiveProviders, run as execRun } from "./exec.js";
-import { containmentStatus, currentContainment, describeContainment, resolveContainment } from "./containment.js";
+import { containmentNotice, containmentStatus, currentContainment, describeContainment, resolveContainment } from "./containment.js";
 import { readPulls } from "./pulls.js";
 import { startMaintenance } from "./maintenance.js";
 import { livePin, modelWatchPass } from "./model-catalog.js";
@@ -367,7 +367,9 @@ External trackers — build what a tracker nominates, under local approvals
                                         refuses to spawn where none exists
                                         (macOS) instead of downgrading.
                                         Also read by watch, tick and
-                                        daemon install.
+                                        daemon install. --verbose prints
+                                        the exact containment status (a
+                                        service log always has it).
   toolroll reconcile --repo <path>   the morning sweep: recover dead
                                         runners, reap expired leases, adopt
                                         or forget orphaned worktrees. Run it
@@ -612,6 +614,8 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "saved",
     // task complete: also open the result's pull request.
     "pull-request",
+    // up: the exact start-up details (containment) in the terminal too.
+    "verbose",
 ]);
 export function parseOperateArgs(argv, ownValues = new Set()) {
     const positional = [];
@@ -7131,7 +7135,8 @@ async function runWatchLoop(args) {
     }
     // What this runner's spawns actually get, in one honest line: native
     // and which backend, observed, or a required policy that will refuse.
-    progress(`watch: ${describeContainment(currentContainment())}`);
+    for (const line of args.containmentLines?.(currentContainment()) ?? [`watch: ${describeContainment(currentContainment())}`])
+        progress(line);
     // The night is a row, not "the last 24 hours": everything this watch does
     // attributes to this episode by runner and window, and `brief
     // --latest-watch` bounds itself to exactly it.
@@ -8157,6 +8162,18 @@ async function upCommand(flags, context) {
         return copy;
     };
     const prefix = (repo) => (activeRepos.size > 1 ? `[${projectName(repo)}] ` : "");
+    // Containment at start: one plain sentence, once, for a person at a
+    // terminal; the exact status line with --verbose, in a service log (no
+    // terminal), and always when a required policy will refuse spawns.
+    const containmentDetail = flags.has("verbose") || !(context.upSeams?.terminal ?? process.stdout.isTTY === true);
+    let containmentSaid = false;
+    const containmentLines = (effective) => {
+        const notice = containmentNotice(effective);
+        if (notice !== null && !containmentSaid)
+            progress(notice);
+        containmentSaid = true;
+        return containmentDetail || effective.refusal !== null ? [`watch: ${describeContainment(effective)}`] : [];
+    };
     const loopResults = new Map();
     const launchRepo = async (repo, bind) => {
         if (loopResults.has(repo) || stopping)
@@ -8184,6 +8201,7 @@ async function upCommand(flags, context) {
             progress: line => progress(`${prefix(repo)}${line}`),
             isStopping: () => stopping,
             onFollowController: controller => followControllers.push(controller),
+            containmentLines,
             onReady: () => {
                 markReady();
                 if (bind)
@@ -8323,10 +8341,10 @@ async function upCommand(flags, context) {
             }
             write(repos.length === 0
                 ? `  builder   ${runnerName} is ready — add a local folder or GitHub repository in Projects`
-                : `  builder   ${runnerName} is watching ${repos.length === 1 ? repos[0] : `${repos.length} repositories`}`);
+                : `  builder   watching ${repos.length === 1 ? repos[0] : `${repos.length} repositories`}`);
             if (projectRoots.length > 0)
                 write(`  projects  new repositories under ${projectRoots.length === 1 ? projectRoots[0] : `${projectRoots.length} saved folders`} connect automatically`);
-            write("  The inbox checklist shows what remains before approved work builds unattended.");
+            write("  Chat shows the steps to your first result.");
             write("  Ctrl-C stops Toolroll on this machine.");
         }
         if (!json && !flags.has("no-open") && terminal)
@@ -8335,7 +8353,7 @@ async function upCommand(flags, context) {
     // 10. Supervise to the end.
     await stopped;
     await registrySupervisor;
-    const results = await Promise.all([...loopResults.values()]);
+    await Promise.all([...loopResults.values()]);
     clearInterval(runnerHeartbeat);
     if (runTimer !== undefined)
         clearTimeout(runTimer);
@@ -8368,9 +8386,7 @@ async function upCommand(flags, context) {
         process.stderr.write(`up: ${fatal}\n`);
         return EXIT.failed;
     }
-    const ticks = results.reduce((sum, one) => sum + one.result.ticks, 0);
-    const built = results.reduce((sum, one) => sum + one.result.built, 0);
-    progress(`up: stopped cleanly — ${ticks} pass(es), ${built} with work. Run \`toolroll up\` anywhere on this machine to reconnect every saved project.`);
+    progress("Toolroll stopped. Run `toolroll up` anywhere on this machine to start it again with every saved project.");
     return EXIT.ok;
 }
 // ---- the telegram bridge ---------------------------------------------------

package/dist/proof.d.ts

@@ -332,6 +332,15 @@ export declare function manualReviewOnly(proof: {
     reasons: readonly string[];
     matrix?: readonly CriterionMatrixRow[];
 } | null): boolean;
+/** The criterion id a stored "needs a person's check" reason names, or null
+ * for any other reason. The stored words stay as recorded; pages say them
+ * through `personCheckWords`. */
+export declare function manualReviewCriterionOf(reason: string): string | null;
+/** A stored verification reason as a person would say it, for pages and
+ * cards. The record keeps its exact words; unknown reasons pass through. */
+export declare function plainReasonWords(reason: string): string;
+/** A requirement only a person can confirm, as a person would say it. */
+export declare function personCheckWords(statement: string | null): string;
 export type CriterionMatrixRow = {
     /** Controller-captured evidence for direct goal assessment. Kept separately
      * from the final row state: available evidence is not a satisfied goal. */

package/dist/proof.js

@@ -509,7 +509,31 @@ export function manualReviewOnly(proof) {
     return proof?.verdict === "short" && (proof.matrix === undefined || (proof.matrix.some(row => row.state === "manual-review")
         && proof.matrix.every(row => row.state === "pass" || row.state === "manual-review")))
         && proof.reasons.length > 0
-        && proof.reasons.every(reason => /^criterion "[^"]+" requires manual-review evidence — an operator must accept it before this can verify$/.test(reason));
+        && proof.reasons.every(reason => manualReviewCriterionOf(reason) !== null);
+}
+/** The criterion id a stored "needs a person's check" reason names, or null
+ * for any other reason. The stored words stay as recorded; pages say them
+ * through `personCheckWords`. */
+export function manualReviewCriterionOf(reason) {
+    return /^criterion "([^"]+)" requires manual-review evidence — an operator must accept it before this can verify$/.exec(reason)?.[1] ?? null;
+}
+/** A stored verification reason as a person would say it, for pages and
+ * cards. The record keeps its exact words; unknown reasons pass through. */
+export function plainReasonWords(reason) {
+    if (manualReviewCriterionOf(reason) !== null)
+        return "A requirement needs your own check.";
+    const unassigned = /^caveat [0-9]+ names no criterion — every caveat is an exception to exactly one signed criterion, named by its exact id \(an unrelated idea belongs in the handoff's follow-ups\): ([\s\S]*)$/.exec(reason);
+    if (unassigned !== null)
+        return `The agent left a note without saying which requirement it affects: ${unassigned[1]}`;
+    const reviewed = /^(?:reviewer:)?([^\s"]+) (contradicts|needs more evidence for) criterion "[^"]+": ([\s\S]*)$/i.exec(reason);
+    if (reviewed !== null)
+        return `${reviewed[1]} ${reviewed[2].toLowerCase() === "contradicts" ? "says a requirement is not met" : "isn't sure a requirement is met"}: ${reviewed[3]}`;
+    return reason;
+}
+/** A requirement only a person can confirm, as a person would say it. */
+export function personCheckWords(statement) {
+    const plain = statement?.trim() ?? "";
+    return plain === "" ? "You check this one yourself." : `You check this one: ${plain}`;
 }
 /** Set equality, exactly — the "must equal the complete sealed git diff
  * exactly" rule (v39) needs both directions, unlike the legacy subset

package/dist/publish.d.ts

@@ -25,6 +25,15 @@ import type { Publication, PublicationGrant, Store } from "./store.js";
 export declare const BODY_TEMPLATE_VERSION = 2;
 /** After this many failed attempts a publication stops retrying and pages instead. */
 export declare const MAX_PUBLISH_ATTEMPTS = 5;
+/**
+ * The one grant lookup for a task's publication: its project is the task's repo, and that project's live grant
+ * governs it. The publisher, Complete → pull request and a flow's Pull request zone all ask here, so none of them
+ * can judge a publication by another project's grant. `fallback`: the repo to assume for a task with none recorded.
+ */
+export declare function publicationGrantOf(store: Store, taskRef: number, fallback?: string | null): {
+    repo: string | null;
+    grant: PublicationGrant | null;
+};
 export type PublishExec = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
 /** The grant's terms, in the words the approver must be shown before agreeing. */
 export declare function describePublicationGrant(grant: {
@@ -65,6 +74,12 @@ export declare function permitsPublication(grant: PublicationGrant | null, publi
     ok: false;
     message: string;
 };
+/**
+ * A publication given up on whose pull request exists anyway — a pass that gave up while another opened it, or a
+ * person who opened it by hand: the PR on its exact head and base, carrying its exact commit, is adopted as opened
+ * (merged or closed ones too; the next observation records which). Whether one was found.
+ */
+export declare function adoptPublishedPullRequest(store: Store, publication: Publication, exec: PublishExec, clock: () => Date): Promise<boolean>;
 export type CheckReport = {
     observed: number;
     failing: number;

package/dist/publish.js

@@ -31,6 +31,15 @@ export const BODY_TEMPLATE_VERSION = 2;
 /** After this many failed attempts a publication stops retrying and pages instead. */
 export const MAX_PUBLISH_ATTEMPTS = 5;
 const EXEC_TIMEOUT_MS = 60_000;
+/**
+ * The one grant lookup for a task's publication: its project is the task's repo, and that project's live grant
+ * governs it. The publisher, Complete → pull request and a flow's Pull request zone all ask here, so none of them
+ * can judge a publication by another project's grant. `fallback`: the repo to assume for a task with none recorded.
+ */
+export function publicationGrantOf(store, taskRef, fallback = null) {
+    const repo = store.refById(taskRef)?.repo ?? fallback;
+    return { repo, grant: repo === null ? null : store.publicationGrantFor(repo) };
+}
 /** The grant's terms, in the words the approver must be shown before agreeing. */
 export function describePublicationGrant(grant) {
     return [
@@ -107,9 +116,15 @@ export async function publishPass(store, options) {
             concede(store, publication, "the accepted diff carries a detected secret — rewrite the branch before anything publishes", report, clock);
             continue;
         }
+        // Each project's watch publishes its own project's work: the push runs in
+        // that checkout, under that project's grant. Another project's pass must
+        // not touch it — judging it by the wrong grant once recorded "no live
+        // grant" errors until it gave up, while its own pass opened the PR.
         // The grant is re-read per publication, live: revocation is immediate,
         // and an intent created under a grant that has since died goes nowhere.
-        const grant = store.publicationGrantFor(options.repo);
+        const { repo, grant } = publicationGrantOf(store, publication.taskRef, options.repo);
+        if (repo !== options.repo)
+            continue;
         const verdict = permitsPublication(grant, publication);
         if (!verdict.ok) {
             report.problems.push(`publication ${publication.id}: ${verdict.message}`);
@@ -243,6 +258,31 @@ async function openOrAdopt(store, publication, grant, exec, clock) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * A publication given up on whose pull request exists anyway — a pass that gave up while another opened it, or a
+ * person who opened it by hand: the PR on its exact head and base, carrying its exact commit, is adopted as opened
+ * (merged or closed ones too; the next observation records which). Whether one was found.
+ */
+export async function adoptPublishedPullRequest(store, publication, exec, clock) {
+    if (publication.state !== "failed")
+        return false;
+    const listed = await exec("gh", ["pr", "list", "--repo", publication.githubRepo, "--head", publication.head, "--base", publication.base, "--state", "all", "--json", "number,url,headRefOid"], { timeoutMs: EXEC_TIMEOUT_MS });
+    if (listed.code !== 0)
+        return false;
+    let found;
+    try {
+        found = JSON.parse(listed.stdout || "[]");
+    }
+    catch {
+        return false;
+    }
+    const pr = Array.isArray(found) ? found.find(one => one.headRefOid === publication.headSha && typeof one.number === "number" && typeof one.url === "string") : undefined;
+    if (pr === undefined)
+        return false;
+    store.markPublicationOpened(publication.id, pr.number, pr.url, clock());
+    enqueueOpened(store, publication, pr.url, clock);
+    return true;
+}
 /**
  * Read CI for every PR this control plane opened — structured rollup and the
  * exact head OID, never a command's exit status (finding 18). Episodes are

package/dist/pull-request-flow.js

@@ -16,7 +16,7 @@
  */
 import { createHash } from "node:crypto";
 import { run as execRun } from "./exec.js";
-import { bodyHashOf, publicationBody } from "./publish.js";
+import { bodyHashOf, publicationBody, publicationGrantOf } from "./publish.js";
 import { failingChecks, summarizeChecks } from "./pulls.js";
 import { assignmentOf, checkAssignmentAsOperator } from "./assignment.js";
 import { requestResultChanges } from "./result-actions.js";
@@ -137,7 +137,7 @@ export function pullRequestBlocker(store, runId) {
     const ref = run === null ? null : store.refById(run.taskRef);
     if (run === null || ref === null)
         return "No such result.";
-    const grant = ref.repo === null ? null : store.publicationGrantFor(ref.repo);
+    const { grant } = publicationGrantOf(store, run.taskRef);
     if (grant === null || !grant.capabilities.includes("push-branch") || !grant.capabilities.includes("open-pr"))
         return "Pull requests aren't set up for this project.";
     if (run.headRevision === null || run.committed === false)
@@ -184,7 +184,7 @@ export function owePullRequest(store, runId, actor, flowCard, now) {
     return store.transact(() => {
         const run = store.getRun(runId);
         const ref = store.refById(run.taskRef);
-        const grant = store.publicationGrantFor(ref.repo);
+        const grant = publicationGrantOf(store, run.taskRef).grant;
         let publication = store.publicationForRun(run.id);
         if (publication === null) {
             const id = store.createPublicationIntent({

package/dist/serve.d.ts

@@ -18,6 +18,8 @@ import type { RevisionLineage } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 import { type InstallMethod } from "./install-method.js";
 export type ServeOptions = {
+    /** `toolroll demo`: the scripted lead that answers Chat instead of a model. */
+    demoLead?: import("./demo.js").DemoLead;
     /** Tests: the bin whose real path says how Toolroll was installed (Settings → Updates' command). */
     installBin?: string;
     /** Native coding workspace injection for isolated integration tests. */