toolroll 0.9.59 → 0.9.61

package/dist/assignment-status.js

@@ -1,11 +1,22 @@
 /** Private lead catch-up, separate from human notification delivery. These are
  * observed assignment transitions, not a promise to capture every intermediate
- * state between scans. Recording or reading them never dispatches agent work. */
+ * state between scans. Recording or reading them never dispatches agent work.
+ * One stream serves every lead: a coordinator's or team lead's events are
+ * recorded under its owner, and the built-in lead's crew updates under its
+ * follow grant (`follow:<grant>`, lead-follow.ts); each reads its own through
+ * the delivery inbox (assignment-delivery.ts). */
 import { createHash } from "node:crypto";
 import { assignmentOf } from "./assignment.js";
 import { publicChatText } from "./chat-display.js";
+import { sweepIfMoved } from "./sweep-gate.js";
 export const ASSIGNMENT_STATUS_ACTION = "assignment status observed";
+/** A reader's first sight of a task that is not news: the state later events are compared to, never delivered. */
+export const ASSIGNMENT_STATUS_BASELINE = "assignment status baseline";
 export const ASSIGNMENT_STATUS_SOURCE = "work";
+/** The states that wake a lead: a result to check, a question, completion, or cancellation. */
+export const LEAD_WAKE_STATES = ["ready-to-check", "needs-decision", "complete", "cancelled"];
+/** The built-in lead's events, one stream per follow grant. */
+export const followActor = (grant) => `follow:${grant}`;
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const text = publicChatText;
 /** No saved artifact contents, credential bytes, or polling timestamps. Exact
@@ -51,7 +62,7 @@ export function parseAssignmentStatusEvent(value) {
             !Array.isArray(a["attention"]) || a["attention"].length > 8 || !a["attention"].every(one => string(one, 500)))
             return null;
         const owner = a["owner"], action = a["primaryAction"], result = a["result"], completion = a["completion"], publication = a["publication"];
-        if (!object(owner) || !keys(owner, ["kind", "id", "label"]) || !["coordinator", "lead"].includes(String(owner["kind"])) || !string(owner["id"], 128) || !string(owner["label"], 100))
+        if (owner !== null && (!object(owner) || !keys(owner, ["kind", "id", "label"]) || !["coordinator", "lead"].includes(String(owner["kind"])) || !string(owner["id"], 128) || !string(owner["label"], 100)))
             return null;
         if (action !== null && (!object(action) || !keys(action, ["code", "label", "target"]) || !string(action["code"], 80) || !string(action["label"], 160) ||
             !object(action["target"]) || !keys(action["target"], ["taskId", "runId", "decisionId"]) || !string(action["target"]["taskId"], 64) || !id(action["target"]["runId"]) || !id(action["target"]["decisionId"])))
@@ -103,50 +114,70 @@ export function noteAssignmentStatus(store, snapshot, now) {
             if (!Array.isArray(repos) || !repos.includes(snapshot.repo))
                 return null;
         }
-        const assignment = assignmentStatusBrief(snapshot);
-        if (assignment.owner === null)
+        if (assignmentStatusBrief(snapshot).owner === null)
             return null;
-        const stateDigest = hash(assignment);
-        const previous = store.handle.prepare("SELECT id,outcome FROM action_ledger WHERE task_id=? AND action=? AND source=? ORDER BY id DESC LIMIT 1")
-            .get(snapshot.rootId, ASSIGNMENT_STATUS_ACTION, ASSIGNMENT_STATUS_SOURCE);
-        if (previous !== undefined) {
-            try {
-                if (JSON.parse(String(previous["outcome"]))?.stateDigest === stateDigest)
-                    return null;
-            }
-            catch { /* Preserve an unreadable older event; append the current observation. */ }
-        }
-        const digest = hash({ rootRef: ref.id, owner: owner.id, previous: previous === undefined ? null : Number(previous["id"]), stateDigest });
-        const event = { version: 1, digest, stateDigest, assignment: { ...assignment, owner: assignment.owner } };
-        return store.recordAction({ at: now.toISOString(), actor: `${owner.kind}:${owner.id}`, repo: snapshot.repo,
-            taskId: snapshot.rootId, runId: assignment.runId, action: ASSIGNMENT_STATUS_ACTION,
-            outcome: JSON.stringify(event), source: ASSIGNMENT_STATUS_SOURCE });
+        return appendStatusEvent(store, `${owner.kind}:${owner.id}`, owner.id, ref.id, snapshot, now);
     });
 }
+/** The built-in lead's crew update (lead-follow.ts): the same event, under its follow grant. The
+ * caller has already proved the grant and its projects; the root must still be a placed task. */
+export function noteFollowStatus(store, grant, snapshot, now, action = ASSIGNMENT_STATUS_ACTION) {
+    if (snapshot.repo === null)
+        return null;
+    return store.transact(() => {
+        const ref = store.lookupRef(snapshot.rootId);
+        if (!ref || ref.repo !== snapshot.repo || ref.revisionOf !== null)
+            return null;
+        return appendStatusEvent(store, followActor(grant), followActor(grant), ref.id, snapshot, now, action);
+    });
+}
+/** Each reader's latest event or baseline, not a permanent digest set, deduplicates its retries, so Working → Needs
+ * decision → Working is retained. One reader's events never suppress or duplicate another's. */
+function appendStatusEvent(store, actor, ownerId, rootRef, snapshot, now, action = ASSIGNMENT_STATUS_ACTION) {
+    const assignment = assignmentStatusBrief(snapshot);
+    const stateDigest = hash(assignment);
+    const previous = store.handle.prepare("SELECT id,outcome FROM action_ledger WHERE task_id=? AND action IN (?,?) AND source=? AND actor=? ORDER BY id DESC LIMIT 1")
+        .get(snapshot.rootId, ASSIGNMENT_STATUS_ACTION, ASSIGNMENT_STATUS_BASELINE, ASSIGNMENT_STATUS_SOURCE, actor);
+    if (previous !== undefined) {
+        try {
+            if (JSON.parse(String(previous["outcome"]))?.stateDigest === stateDigest)
+                return null;
+        }
+        catch { /* Preserve an unreadable older event; append the current observation. */ }
+    }
+    const digest = hash({ rootRef, owner: ownerId, previous: previous === undefined ? null : Number(previous["id"]), stateDigest });
+    const event = { version: 1, digest, stateDigest, assignment };
+    return store.recordAction({ at: now.toISOString(), actor, repo: snapshot.repo,
+        taskId: snapshot.rootId, runId: assignment.runId, action,
+        outcome: JSON.stringify(event), source: ASSIGNMENT_STATUS_SOURCE });
+}
 /** At most fifty roots per pass; the cursor survives process restarts. A full
- * pass cycles back, so changes below the cursor are eventually observed too. */
+ * pass cycles back, so changes below the cursor are eventually observed too.
+ * A pass is skipped when nothing moved since the cycle began (sweep-gate.ts). */
 export function syncAssignmentStatuses(store, now, repos, root) {
     if (repos.length === 0)
         return;
     const allowed = [...new Set(repos)].sort();
     const key = `assignment-status:${hash(allowed)}`;
-    const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t
-    WHERE t.backend='built-in' AND t.revision_of IS NULL
-    AND t.repo IN (SELECT value FROM json_each(?)) AND t.id>?
-    AND (t.coordinator_cid IS NOT NULL OR EXISTS(SELECT 1 FROM team_task_owner o WHERE o.task_ref=t.id) OR EXISTS
-      (SELECT 1 FROM action_ledger a WHERE a.task_id=t.external_id AND a.action='assignment claimed' AND a.source='work'))
-    ORDER BY t.id LIMIT 50`).all(JSON.stringify(allowed), store.serviceCursor(key));
-    // Release the writer between families. Each observation and its durable
-    // position still commit together; an interrupted sweep resumes after the
-    // last committed family instead of holding every heartbeat behind a batch.
-    if (rows.length === 0)
-        store.setServiceCursor(key, 0, now);
-    for (const [index, row] of rows.entries()) {
-        store.transact(() => {
-            const snapshot = assignmentOf(store, String(row['external_id']), now, { principal: 'coordinator', repos: allowed }, root);
-            if (snapshot !== null)
-                noteAssignmentStatus(store, snapshot, now);
-            store.setServiceCursor(key, index === rows.length - 1 && rows.length < 50 ? 0 : Number(row['id']), now);
-        });
-    }
+    sweepIfMoved(store, key, now, () => {
+        const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t
+      WHERE t.backend='built-in' AND t.revision_of IS NULL
+      AND t.repo IN (SELECT value FROM json_each(?)) AND t.id>?
+      AND (t.coordinator_cid IS NOT NULL OR EXISTS(SELECT 1 FROM team_task_owner o WHERE o.task_ref=t.id) OR EXISTS
+        (SELECT 1 FROM action_ledger a WHERE a.task_id=t.external_id AND a.action='assignment claimed' AND a.source='work'))
+      ORDER BY t.id LIMIT 50`).all(JSON.stringify(allowed), store.serviceCursor(key));
+        // Release the writer between families. Each observation and its durable
+        // position still commit together; an interrupted sweep resumes after the
+        // last committed family instead of holding every heartbeat behind a batch.
+        if (rows.length === 0)
+            store.setServiceCursor(key, 0, now);
+        for (const [index, row] of rows.entries()) {
+            store.transact(() => {
+                const snapshot = assignmentOf(store, String(row['external_id']), now, { principal: 'coordinator', repos: allowed }, root);
+                if (snapshot !== null)
+                    noteAssignmentStatus(store, snapshot, now);
+                store.setServiceCursor(key, index === rows.length - 1 && rows.length < 50 ? 0 : Number(row['id']), now);
+            });
+        }
+    });
 }

package/dist/assignment.d.ts

@@ -86,11 +86,13 @@ export type AssignmentSnapshot = {
         }[];
     };
     /** `lead`: marked complete by the person's lead (`toolroll lead token`), shown as "by the lead". */
+    /** `landed`: Toolroll marked it complete because its work is already in main, and why ("its pull request merged"). */
     completion: {
         actor: string;
         at: string;
         digest: string;
         lead?: true;
+        landed?: string;
     } | null;
     handoff: {
         kind: "result" | "decision" | "attention";
@@ -154,6 +156,7 @@ export declare function assignmentBrief(assignment: AssignmentSnapshot | null):
         at: string;
         digest: string;
         lead?: true;
+        landed?: string;
     } | null;
     result: {
         digest: string;
@@ -233,9 +236,13 @@ export declare function acceptAndCompleteAsOperator(store: Store, taskId: string
     receiptDigest: string;
     note: string | null;
 }, who: VerifiedApprover, now: Date, root?: string, finish?: (digest: string) => Finished): Finished;
-/** The ordinary worker reconciles at most 50 owned roots per pass. A lost
- * wakeup is recovered after restart; immutable notification keys dedupe it. */
+/** The ordinary worker reconciles at most 50 owned roots per pass, and skips a
+ * pass when nothing moved (sweep-gate.ts). A lost wakeup is recovered after
+ * restart; immutable notification keys dedupe it. */
 export declare function syncAssignmentHandoffs(store: Store, now: Date, repos: readonly string[], root?: string): void;
+/** The history of assignment handoffs sent to people (the `assignment-handoff` notifications), read by cursor. It is
+ * not a delivery path: nothing is saved, replayed or acknowledged here. Leads receive their updates through the
+ * assignment inbox (assignment-delivery.ts), the one road results take to a lead. */
 export declare function assignmentUpdates(store: Store, now: Date, access: AssignmentAccess, query: {
     after: number;
     limit: number;
@@ -268,6 +275,7 @@ export declare function assignmentUpdates(store: Store, now: Date, access: Assig
                 at: string;
                 digest: string;
                 lead?: true;
+                landed?: string;
             } | null;
             result: {
                 digest: string;

package/dist/assignment.js

@@ -4,12 +4,13 @@
 import { createHash } from "node:crypto";
 import { currentActor, withActor } from "./actor.js";
 import { replacedWords } from "./task-status.js";
-import { COMPLETION_ACTION, familyChangedFiles } from "./result-completion.js";
+import { COMPLETER_ACTOR, COMPLETION_ACTION, familyChangedFiles, landedReasonOf } from "./result-completion.js";
 import { homedir } from "node:os";
 import { readSchemaVersion, stopFactOf } from "./store.js";
 import { approvalOf } from "./scope.js";
 import { openWorkDecisionOf, taskWorkSummaryOf, workDecisionAction } from "./work-summary.js";
-import { evidenceRoot, readVerifiedArtifact, readVerifiedReport } from "./evidence.js";
+import { evidenceRoot, readVerifiedArtifact, readVerifiedReport, verifyArtifact } from "./evidence.js";
+import { sweepIfMoved } from "./sweep-gate.js";
 import { verificationEvidence } from "./verification-evidence.js";
 import { reproveApprover } from "./principal.js";
 import { noteAssignmentStatus } from "./assignment-status.js";
@@ -163,7 +164,7 @@ export function assignmentOf(store, taskId, now, access, root, memo) {
     });
     const artifacts = result === null ? [] : store.artifactsFor(result.id);
     const reports = artifacts.filter(a => a.kind === "report");
-    const unavailable = family.versions.flatMap(version => store.runsFor(version.refId).flatMap(run => store.artifactsFor(run.id).filter(artifact => root === undefined || !readVerifiedArtifact(root, artifact).ok)
+    const unavailable = family.versions.flatMap(version => store.runsFor(version.refId).flatMap(run => store.artifactsFor(run.id).filter(artifact => root === undefined || !verifyArtifact(root, artifact).ok)
         .map(artifact => `Saved ${artifact.kind} #${artifact.id} (run ${run.id}) is unavailable or changed.`)));
     const ownChecks = result === null ? null : assignmentChecksForRun(store, root, result.id, now);
     // Checks Off: a passing full release check that contains this commit covers it, read now from the existing receipts.
@@ -262,20 +263,22 @@ export function assignmentOf(store, taskId, now, access, root, memo) {
             : completionKind === "accepted-exception" ? "An operator accepted this result with its recorded limitations. The lead can inspect that decision; the recorded checks are unchanged."
                 : receipt.checks.detail;
         primaryAction = { code: "open-result", label: completionKind === "research-report" ? "Read report" : "Open result", target: { taskId: current.id, runId: result.id, decisionId: null }, access: "read", retry: "read-again" };
-        const checked = store.handle.prepare("SELECT actor,at FROM action_ledger WHERE task_id = ? AND run_id = ? AND action = ? AND outcome = ? AND source = 'work' ORDER BY id DESC")
-            .all(family.root.id, result.id, CHECK_ACTION, receipt.digest).find(row => /^(operator|coordinator|lead):.+/.test(String(row["actor"])));
+        const checked = store.handle.prepare("SELECT actor,at,detail FROM action_ledger WHERE task_id = ? AND run_id = ? AND action = ? AND outcome = ? AND source = 'work' ORDER BY id DESC")
+            .all(family.root.id, result.id, CHECK_ACTION, receipt.digest).find(row => COMPLETER_ACTOR.test(String(row["actor"])));
         // This ledger fact was authorized when written. Credential rotation,
         // membership changes and ownership transfer cannot revoke past completion.
         // The exact result digest still fences changes to work, scope and history.
         if (checked !== undefined) {
             const rootRef = store.lookupRef(family.root.id);
             const byLead = rootRef !== null && olderStoreSafe(() => store.taskActs(rootRef.id), []).filter(one => one.act === "completed").at(-1)?.lead === true;
-            completion = { actor: String(checked["actor"]), at: String(checked["at"]), digest: receipt.digest, ...(byLead ? { lead: true } : {}) };
+            const landed = landedReasonOf(String(checked["actor"]), checked["detail"] == null ? null : String(checked["detail"]));
+            completion = { actor: String(checked["actor"]), at: String(checked["at"]), digest: receipt.digest, ...(byLead && landed === null ? { lead: true } : {}), ...(landed === null ? {} : { landed }) };
             state = "complete";
             primaryAction = { ...primaryAction, label: completionKind === "research-report" ? "Read report" : "Open result" };
             const label = byLead ? "the lead" : completion.actor.startsWith("operator:") ? completion.actor.slice(9) : owner && completion.actor === actorOf(owner) ? owner.label : "the previous lead";
-            detail = completionKind === "research-report" ? `Research report checked by ${label}. No deployment is implied.`
-                : `Handled by ${label}. ${receipt.checks.detail} Publication and deployment are separate.`;
+            detail = landed !== null ? `Marked complete automatically: ${landed}. ${receipt.checks.detail}`
+                : completionKind === "research-report" ? `Research report checked by ${label}. No deployment is implied.`
+                    : `Handled by ${label}. ${receipt.checks.detail} Publication and deployment are separate.`;
         }
     }
     else if (work.status.rank === 0 || (!live && (current.state === "done" || current.state === "failed" || work.status.views.includes("needs-you")))) {
@@ -418,7 +421,7 @@ export function assignmentEvidenceIntact(store, root, receipt) {
     try {
         const family = store.taskFamilyOf(receipt.taskId, null, true);
         if (family === null || family.problem !== null || family.root.id !== receipt.rootId ||
-            !family.versions.every(version => store.runsFor(version.refId).every(run => store.artifactsFor(run.id).every(artifact => readVerifiedArtifact(root, artifact).ok))))
+            !family.versions.every(version => store.runsFor(version.refId).every(run => store.artifactsFor(run.id).every(artifact => verifyArtifact(root, artifact).ok))))
             return false;
         if (receipt.completionKind === "research-report") {
             const report = readVerifiedReport(store, root, store.lookupRef(receipt.taskId).id);
@@ -567,13 +570,14 @@ function noteAssignmentHandoff(store, assignment, now) {
         kind: "assignment-handoff", source: { taskRef: ref.id }, subject: assignment.state === "cancelled" ? "Assignment cancelled" : assignment.state === "ready-to-check" ? "Ready" : "Assignment needs a decision",
         body: assignment.detail, link: `/t/${encodeURIComponent(assignment.rootId)}` }, now);
 }
-/** The ordinary worker reconciles at most 50 owned roots per pass. A lost
- * wakeup is recovered after restart; immutable notification keys dedupe it. */
+/** The ordinary worker reconciles at most 50 owned roots per pass, and skips a
+ * pass when nothing moved (sweep-gate.ts). A lost wakeup is recovered after
+ * restart; immutable notification keys dedupe it. */
 export function syncAssignmentHandoffs(store, now, repos, root) {
     if (repos.length === 0)
         return;
-    store.transact(() => {
-        const key = `assignment-handoff:${digest([...new Set(repos)].sort())}`;
+    const key = `assignment-handoff:${digest([...new Set(repos)].sort())}`;
+    sweepIfMoved(store, key, now, () => store.transact(() => {
         const cursor = store.serviceCursor(key);
         const rows = store.handle.prepare(`SELECT t.id,t.external_id FROM task_ref t WHERE t.backend = 'built-in' AND t.revision_of IS NULL
     AND t.repo IN (SELECT value FROM json_each(?)) AND t.id > ?
@@ -587,8 +591,11 @@ export function syncAssignmentHandoffs(store, now, repos, root) {
             }
         }
         store.setServiceCursor(key, rows.length < 50 ? 0 : Number(rows.at(-1)["id"]), now);
-    });
+    }));
 }
+/** The history of assignment handoffs sent to people (the `assignment-handoff` notifications), read by cursor. It is
+ * not a delivery path: nothing is saved, replayed or acknowledged here. Leads receive their updates through the
+ * assignment inbox (assignment-delivery.ts), the one road results take to a lead. */
 export function assignmentUpdates(store, now, access, query, root) {
     const after = Number.isSafeInteger(query.after) && query.after >= 0 ? query.after : 0;
     const limit = Math.max(1, Math.min(100, Math.floor(query.limit) || 50));

package/dist/bin.js

@@ -17,6 +17,15 @@ if (major < 22 || (major === 22 && minor < 13)) {
     process.stderr.write(`Toolroll needs Node 22.13 or newer (this is ${versions.node}) — it uses node:sqlite.\n`);
     process.exit(2);
 }
-const { runCliProcess } = await import("./cli.js");
-await runCliProcess(process.argv.slice(2));
+// --version and the top-level usage answer here, before the CLI and its command families load.
+const argv = process.argv.slice(2);
+const { quickAnswer } = await import("./cli-fast.js");
+const quick = quickAnswer(argv);
+if (quick !== null) {
+    console.log(quick);
+}
+else {
+    const { runCliProcess } = await import("./cli.js");
+    await runCliProcess(argv);
+}
 export {};

package/dist/brief-fence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One line, prefixed, with nothing that can end the block or start a new rule.
+ *
+ * Scope text is written by whoever filed the task. A goal containing a newline
+ * and a bullet would otherwise read to the agent as another rule in the list,
+ * which is how "add a guard" becomes "add a guard, and ignore the rules below".
+ * The same quoting wraps a steering note the agent reads from its mailbox.
+ */
+export declare function fence(text: string): string;

package/dist/brief-fence.js

@@ -0,0 +1,22 @@
+/**
+ * One line, prefixed, with nothing that can end the block or start a new rule.
+ *
+ * Scope text is written by whoever filed the task. A goal containing a newline
+ * and a bullet would otherwise read to the agent as another rule in the list,
+ * which is how "add a guard" becomes "add a guard, and ignore the rules below".
+ * The same quoting wraps a steering note the agent reads from its mailbox.
+ */
+export function fence(text) {
+    // Newlines and other control characters collapse to a space: they are the
+    // only way a value can stop being one line and start looking like a new
+    // rule. The visible text is otherwise left exactly as written — mangling
+    // somebody's scope to defend against it would be its own kind of wrong.
+    return `| ${text
+        // C0/C1 plus the Unicode line and paragraph separators: everything
+        // that could end this physical line (Codex free-text review, finding 5).
+        .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]+/g, " ")
+        // A quoted protocol-shaped name is broken VISIBLY, so untrusted text
+        // can never collide with the real nonce-bearing filename that follows.
+        .replace(/STANDING-ORDERS-/g, "NIGHTORDERS[quoted]-")
+        .trim()}`;
+}