toolroll 0.5.0

package/dist/approval-policy.js

@@ -0,0 +1,137 @@
+/**
+ * Separation of duties (v102): a project's approval rules. Two can be on at
+ * once, and neither changes a thing until a project turns it on.
+ *
+ * - The person who filed a task can't approve it ("not the requester").
+ * - Protected work (the whole project, or tasks that touch protected paths)
+ *   needs two different people to approve the same exact scope, and an AI
+ *   teammate or an operating mode can never decide it.
+ *
+ * The store enforces these at the one place every approval is sealed
+ * (`Store.sealScopeApproval`); this module holds the pure parts.
+ */
+/** A filer from a name as the ledger writes it: an AI teammate's ends " (AI)"; a coordinator's starts "coordinator:"; none is automation. */
+export function filerFor(name) {
+    if (name == null || name === "")
+        return { name: null, kind: "automation" };
+    if (name.endsWith(" (AI)"))
+        return { name, kind: "teammate" };
+    if (name.startsWith("coordinator:"))
+        return { name, kind: "coordinator" };
+    return { name, kind: "person" };
+}
+export const NO_RULES = { notRequester: false, protectProject: false, protectedPaths: [] };
+/** A path as the rules compare it: forward slashes, no "." or "..", lower case (macOS
+ * checkouts ignore case). null when it climbs out of the checkout. */
+function normal(path) {
+    const parts = [];
+    for (const part of path.trim().replace(/\\/g, "/").toLowerCase().split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (parts.length === 0)
+                return null;
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.join("/");
+}
+const clean = (path) => normal(path) ?? "";
+const wild = /[*?[{]/;
+const literalPrefix = (glob) => { const at = glob.search(wild); return at === -1 ? glob : glob.slice(0, at); };
+function globRegex(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*" && glob[i + 1] === "*") {
+            out += ".*";
+            i++;
+            if (glob[i + 1] === "/")
+                i++;
+        }
+        else if (c === "*")
+            out += "[^/]*";
+        else if (c === "?")
+            out += "[^/]";
+        else
+            out += c.replace(/[.+^${}()|\\[\]]/g, "\\$&");
+    }
+    return new RegExp(`^${out}(?:/.*)?$`);
+}
+/** Whether a task that says it touches `touch` may touch something under
+ * `protectedGlob`, or a changed file is protected. A plain path covers
+ * itself and everything under it; a pattern with no slash matches at any
+ * depth (as in .gitignore); two patterns that could reach the same files
+ * count as overlapping; a path that climbs out of the checkout is
+ * protected. Every doubt errs toward protecting. */
+export function touchesProtected(touch, protectedGlob) {
+    const g = normal(protectedGlob);
+    if (g === null || g === "")
+        return false;
+    const b = g.includes("/") ? g : `**/${g}`;
+    const a = normal(touch);
+    if (a === null || a === "")
+        return true;
+    const pattern = globRegex(b);
+    if (!wild.test(a)) {
+        if (pattern.test(a))
+            return true;
+        // A protected pattern that lives inside this path (".github" holding ".github/workflows/**") is reached, whatever the name looks like.
+        const pb = literalPrefix(b);
+        if (pb === a || pb.startsWith(`${a}/`))
+            return true;
+        // A file ("docs/readme.md") is only itself; a folder ("infra", or a name with no extension) may hold anything a pattern reaches.
+        if (/\.[^/.]+$/.test(a))
+            return false;
+        return pattern.test(`${a}/x`) || pattern.test(`${a}/x/y.z`) || `${a}/`.startsWith(pb);
+    }
+    const pa = literalPrefix(a), pb = literalPrefix(b);
+    return pa.startsWith(pb) || pb.startsWith(pa);
+}
+/** The changed files (from a build's diff) that the rules protect. */
+export function protectedChanges(rules, changed) {
+    if (rules.protectProject)
+        return [...changed];
+    return changed.filter(file => rules.protectedPaths.some(glob => touchesProtected(file, glob)));
+}
+/** Whether a task's declared paths reach protected work. A task that
+ * declares no paths can't show it stays clear, so it counts as protected. */
+export function isProtectedWork(rules, touches) {
+    if (rules.protectProject)
+        return true;
+    if (rules.protectedPaths.length === 0)
+        return false;
+    if (touches.length === 0)
+        return true;
+    return touches.some(touch => rules.protectedPaths.some(glob => touchesProtected(touch, glob)));
+}
+/** Protected paths as a person types them: one per line or comma separated, trimmed, deduplicated, at most 50. */
+export function parseProtectedPaths(raw) {
+    const paths = [...new Set(raw.split(/[\n,]/).map(clean).filter(one => one !== ""))];
+    if (paths.length > 50)
+        return { ok: false, problem: "Protect at most 50 paths." };
+    const long = paths.find(one => one.length > 200);
+    if (long !== undefined)
+        return { ok: false, problem: "A protected path is 200 characters at most." };
+    return { ok: true, paths };
+}
+/** The rules in a line, for the ledger's before → after. */
+export function rulesWords(rules) {
+    const parts = [
+        rules.notRequester ? "requester can't approve" : null,
+        rules.protectProject ? "whole project protected" : rules.protectedPaths.length > 0 ? `protected: ${rules.protectedPaths.join(", ")}` : null,
+    ].filter((one) => one !== null);
+    return parts.length === 0 ? "no rules" : parts.join("; ");
+}
+/** What a person reads when the rules stop an approval. */
+export function gateWords(gate) {
+    if (gate.verdict === "vote")
+        return gate.already
+            ? "You've already approved this. It needs a second approver."
+            : `Your approval is recorded (${gate.have} of ${gate.need}). This work is protected, so a second person needs to approve it.`;
+    return gate.reason === "requester"
+        ? "You filed this task, and this project needs someone else to approve it."
+        : "This work is protected: a person has to approve it, not an operating mode, a routine or an AI teammate.";
+}

package/dist/approval-rules-ui.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Settings → Approval rules (v102): a project's separation of duties. An
+ * instance operator sets them (with their password, or a fresh sign-in with
+ * the identity provider); everyone else reads them. Every change is in the
+ * ledger, before → after.
+ */
+import type { ApprovalRules } from "./approval-policy.js";
+export declare const APPROVAL_RULES_CSS: string;
+export type ApprovalRulesView = {
+    repo: string;
+    name: string;
+    rules: ApprovalRules & {
+        updatedBy: string | null;
+        updatedAt: string | null;
+    };
+    canChange: boolean;
+    /** People who can approve on this project (two approvers need two). */
+    approvers: number;
+};
+/** The rules in plain words, for anyone who can see the project. */
+export declare function rulesSummary(rules: ApprovalRules): string;
+export declare function approvalRulesHtml(view: ApprovalRulesView, csrf: string, notice: {
+    said?: string | null;
+    problem?: string | null;
+}): string;

package/dist/approval-rules-ui.js

@@ -0,0 +1,39 @@
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export const APPROVAL_RULES_CSS = `.approval-rules{max-width:720px;min-width:0}.approval-rules fieldset{border:0;padding:0;margin:18px 0 0;min-width:0}` +
+    `.approval-rules legend{font-weight:600;font-size:.875rem;margin-bottom:8px}.approval-rules .choice{display:grid;grid-template-columns:auto minmax(0,1fr);gap:10px;align-items:start;margin:0 0 10px;font-weight:400}` +
+    `.approval-rules .choice input{margin:.2rem 0 0}.approval-rules .choice strong{display:block;font-size:.875rem;font-weight:500}.approval-rules .choice small{display:block;color:var(--muted-foreground);font-size:.8125rem;margin-top:2px}` +
+    `.approval-rules textarea{min-height:88px;font-family:var(--font-mono);font-size:.8125rem}.approval-rules .paths{margin:4px 0 0 26px}` +
+    `.approval-rules .current{margin:0 0 4px}.approval-rules .step-up{margin-top:16px}.approval-rules button[type=submit]{margin-top:14px}`;
+/** The rules in plain words, for anyone who can see the project. */
+export function rulesSummary(rules) {
+    const parts = [];
+    if (rules.notRequester)
+        parts.push("The person who filed a task can't approve it.");
+    if (rules.protectProject)
+        parts.push("All work here is protected: two people approve it, never an AI teammate or an operating mode.");
+    else if (rules.protectedPaths.length > 0)
+        parts.push(`Work touching ${rules.protectedPaths.join(", ")} is protected: two people approve it, never an AI teammate or an operating mode.`);
+    return parts.length === 0 ? "No approval rules: anyone who can approve on this project can approve its work, including their own." : parts.join(" ");
+}
+export function approvalRulesHtml(view, csrf, notice) {
+    const note = notice.problem ? `<p class="problem" role="alert">${e(notice.problem)}</p>` : notice.said ? `<p role="status">${e(notice.said)}</p>` : "";
+    const changed = view.rules.updatedBy === null ? "" : ` <span class="meta">Changed by ${e(view.rules.updatedBy)} on ${e((view.rules.updatedAt ?? "").slice(0, 10))}.</span>`;
+    const current = `<p class="current">${e(rulesSummary(view.rules))}${changed}</p>`;
+    if (!view.canChange)
+        return `<section class="approval-rules">${note}${current}<p class="meta">An instance operator sets these.</p></section>`;
+    const protect = view.rules.protectProject ? "project" : view.rules.protectedPaths.length > 0 ? "paths" : "none";
+    const radio = (value, title, hint) => `<label class="choice"><input type="radio" name="protect" value="${value}"${protect === value ? " checked" : ""}><span><strong>${title}</strong><small>${hint}</small></span></label>`;
+    const few = view.approvers < 2 ? `<p class="meta">Only ${view.approvers === 1 ? "one person" : "no one"} can approve on this project, so protected work would wait for a second approver. Add one in People first.</p>` : "";
+    return `<section class="approval-rules">${note}${current}` +
+        `<form method="post" action="/settings/approval"><input type="hidden" name="csrf" value="${e(csrf)}"><input type="hidden" name="repo" value="${e(view.repo)}">` +
+        `<fieldset><legend>Who approves</legend><label class="choice"><input type="checkbox" name="not_requester" value="1"${view.rules.notRequester ? " checked" : ""}>` +
+        `<span><strong>Someone other than the requester</strong><small>The person who filed a task, or asked for a revision, can't approve it. Operating modes stop approving their signer's own filings here.</small></span></label></fieldset>` +
+        `<fieldset><legend>Protected work</legend>` +
+        radio("none", "Nothing protected", "One approval is enough.") +
+        radio("project", "The whole project", "Every task needs two different people to approve the same scope.") +
+        radio("paths", "Only these paths", "Tasks that touch them, or don't say what they touch, need two people.") +
+        `<div class="paths"><label>Protected paths, one per line<textarea name="paths" spellcheck="false" placeholder="infra/**&#10;migrations/**">${e(view.rules.protectedPaths.join("\n"))}</textarea></label></div>` +
+        few + `</fieldset>` +
+        `<div class="step-up"><label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label></div>` +
+        `<button type="submit">Save rules</button></form></section>`;
+}

package/dist/assignment-adapters.d.ts

@@ -0,0 +1,180 @@
+import { type AssignmentSnapshot } from "./assignment.js";
+import type { Store } from "./store.js";
+export declare const ASSIGNMENT_ACTIONS: readonly ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
+export type AssignmentOperation = typeof ASSIGNMENT_ACTIONS[number];
+type Args = Record<string, unknown>;
+type Failure = {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare const ASSIGNMENT_TOOLS: readonly [{
+    readonly name: "get_assignment";
+    readonly operation: "show";
+    readonly description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "list_assignment_updates";
+    readonly operation: "updates";
+    readonly description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "claim_assignment";
+    readonly operation: "claim";
+    readonly description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "acknowledge_assignment";
+    readonly operation: "check";
+    readonly description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "get_assignment_brief";
+    readonly operation: "brief";
+    readonly description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "get_assignment_inbox";
+    readonly operation: "inbox";
+    readonly description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}, {
+    readonly name: "acknowledge_assignment_delivery";
+    readonly operation: "ack";
+    readonly description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.";
+    readonly inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+}];
+/** The CLI and MCP use the same bounded input contract. MCP also validates its
+ * descriptor before dispatch; this check protects direct adapter callers. */
+export declare function assignmentArgumentProblem(operation: AssignmentOperation, args: Args): string | null;
+/** Every read and mutation authenticates inside the same transaction as its
+ * projection. A cached name/allowlist cannot keep a revoked identity alive. */
+export declare function assignmentForCoordinator(store: Store, token: string, operation: AssignmentOperation, args: Args, now: Date, evidenceRoot?: string): Failure | {
+    ok: true;
+    body: import("./assignment-brief.js").AssignmentCatchUp;
+} | {
+    ok: true;
+    body: {
+        events: {
+            id: number;
+            createdAt: string;
+            rootId: string;
+            digest: string;
+            superseded: boolean;
+            assignment: {
+                version: 1;
+                rootId: string;
+                activeTaskId: string;
+                state: "cancelled" | "checking" | "complete" | "needs-decision" | "ready-to-check" | "working";
+                detail: string;
+                owner: (import("./assignment.js").AssignmentOwner & {
+                    active: boolean;
+                }) | null;
+                primaryAction: import("./work-summary.js").WorkAction | null;
+                attention: string[];
+                attempts: number;
+                handoff: {
+                    kind: "result" | "decision" | "attention";
+                    digest: string;
+                    acknowledged: boolean;
+                } | null;
+                completion: {
+                    actor: string;
+                    at: string;
+                    digest: string;
+                } | null;
+                result: {
+                    digest: string;
+                    taskId: string;
+                    runId: number;
+                    base: string | null;
+                    head: string | null;
+                    completionKind: "accepted-exception" | "checked-build" | "finished-build" | "research-report" | "verified-build" | null;
+                    checks: import("./assignment.js").AssignmentChecks;
+                    proofAcceptance: import("./store.js").ProofAcceptanceRow | null;
+                    verdict: "attested" | "refuted" | "short" | "verified" | null;
+                    criteria: {
+                        passed: number;
+                        total: number;
+                    };
+                    evidence: "recorded";
+                } | null;
+                publication: {
+                    state: string;
+                    prUrl: string | null;
+                    remoteState: string | null;
+                } | null;
+                deployment: {
+                    status: "not-recorded";
+                };
+            };
+        }[];
+        nextCursor: number;
+        hasMore: boolean;
+    };
+} | {
+    ok: true;
+    body: AssignmentSnapshot;
+} | {
+    ok: true;
+    body: {
+        ok: true;
+        batch: import("./assignment-delivery.js").AssignmentDeliveryBatch;
+        replayed: boolean;
+    } | {
+        ok: true;
+        alreadyAcknowledged: boolean;
+        cursor: number;
+    };
+};
+export type AssignmentCliContext = {
+    commandName?: string;
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    now: Date;
+    evidenceRoot?: string;
+    env?: NodeJS.ProcessEnv;
+};
+/** Explicit secret source only. Never print secret values or discover default
+ * files. A bad explicit credential must not fall back to a local read. */
+export declare function coordinatorToken(flags: Map<string, string | true>, env: NodeJS.ProcessEnv): {
+    token: string | null;
+} | Failure;
+export declare function runAssignmentCommand(positional: readonly string[], flags: Map<string, string | true>, context: AssignmentCliContext): number;
+export {};

package/dist/assignment-adapters.js

@@ -0,0 +1,239 @@
+/** Assignment reads and delivery acknowledgments. These adapters never start
+ * work, answer a decision, accept proof, or change an approval. */
+import { readFileSync, statSync } from "node:fs";
+import { authenticateCoordinator } from "./coordinator.js";
+import { assignmentOf, assignmentUpdates, claimAssignment, checkAssignment } from "./assignment.js";
+import { assignmentCatchUp } from "./assignment-brief.js";
+import { assignmentInbox, acknowledgeAssignmentDelivery } from "./assignment-delivery.js";
+import { syncAssignmentStatuses } from "./assignment-status.js";
+import { envelopeJson } from "./envelope.js";
+export const ASSIGNMENT_ACTIONS = ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
+const failure = (reason, message) => ({ ok: false, reason, message });
+const reference = { type: "string", minLength: 1, maxLength: 64 };
+const digest = { type: "string", minLength: 64, maxLength: 64, pattern: "^[a-f0-9]{64}$" };
+const batchId = { type: "string", minLength: 32, maxLength: 32, pattern: "^[a-f0-9]{32}$" };
+const consumer = { type: "string", minLength: 1, maxLength: 64, pattern: "^[a-z0-9][a-z0-9-]{0,63}$" };
+const object = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+export const ASSIGNMENT_TOOLS = [
+    { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.", inputSchema: object({ ref: reference }, ["ref"]) },
+    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.", inputSchema: object({ after: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER }, limit: { type: "integer", minimum: 1, maximum: 100 } }) },
+    { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.", inputSchema: object({ ref: reference }, ["ref"]) },
+    { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.", inputSchema: object({ ref: reference, digest }, ["ref", "digest"]) },
+    { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.", inputSchema: object({ repo: { type: "string", minLength: 1, maxLength: 4096 }, limit: { type: "integer", minimum: 1, maximum: 25 } }) },
+    { name: "get_assignment_inbox", operation: "inbox", description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.", inputSchema: object({ consumer, limit: { type: "integer", minimum: 1, maximum: 100 } }, ["consumer"]) },
+    { name: "acknowledge_assignment_delivery", operation: "ack", description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.", inputSchema: object({ consumer, batchId }, ["consumer", "batchId"]) },
+];
+/** The CLI and MCP use the same bounded input contract. MCP also validates its
+ * descriptor before dispatch; this check protects direct adapter callers. */
+export function assignmentArgumentProblem(operation, args) {
+    if (!ASSIGNMENT_ACTIONS.includes(operation))
+        return "Choose show, updates, claim, check, brief, inbox, or ack.";
+    const allowed = operation === "brief" ? ["repo", "limit"] : operation === "inbox" ? ["consumer", "limit"] : operation === "ack" ? ["consumer", "batchId"] : operation === "updates" ? ["after", "limit"] : operation === "check" ? ["ref", "digest"] : ["ref"];
+    for (const key of Object.keys(args))
+        if (!allowed.includes(key))
+            return `Unknown argument: ${key}.`;
+    if (["show", "claim", "check"].includes(operation) && (typeof args["ref"] !== "string" || args["ref"].length < 1 || args["ref"].length > 64 || /[\u0000-\u001f\u007f]/.test(args["ref"])))
+        return "Choose a task id, 1–64 characters without control characters.";
+    if (operation === "check" && (typeof args["digest"] !== "string" || !/^[a-f0-9]{64}$/.test(args["digest"])))
+        return "Use the exact 64-character receipt digest from assignment show.";
+    if ((operation === "inbox" || operation === "ack") && (typeof args["consumer"] !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(args["consumer"])))
+        return "Use a stable consumer name with 1–64 lowercase letters, digits or hyphens.";
+    if (operation === "ack" && (typeof args["batchId"] !== "string" || !/^[a-f0-9]{32}$/.test(args["batchId"])))
+        return "Use the exact batchId from assignment inbox.";
+    if (args["repo"] !== undefined && (typeof args["repo"] !== "string" || args["repo"].length < 1 || args["repo"].length > 4096 || /[\u0000-\u001f\u007f]/.test(args["repo"])))
+        return "Choose a project path without control characters.";
+    for (const [name, min, max] of [["after", 0, Number.MAX_SAFE_INTEGER], ["limit", 1, operation === "brief" ? 25 : 100]]) {
+        const value = args[name];
+        if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max))
+            return `${name} must be an integer from ${min} to ${max}.`;
+    }
+    return null;
+}
+function readAssignment(store, operation, args, now, access, root) {
+    if (operation === "brief")
+        return { ok: true, body: assignmentCatchUp(store, now, access, { ...(args["repo"] === undefined ? {} : { repo: String(args["repo"]) }), ...(args["limit"] === undefined ? {} : { limit: Number(args["limit"]) }) }, root) };
+    if (operation === "updates")
+        return { ok: true, body: assignmentUpdates(store, now, access, { after: Number(args["after"] ?? 0), limit: Number(args["limit"] ?? 50) }, root) };
+    const assignment = assignmentOf(store, String(args["ref"]), now, access, root);
+    return assignment === null ? failure("not-found", "No assignment with that task id is available in your projects.") : { ok: true, body: assignment };
+}
+/** Every read and mutation authenticates inside the same transaction as its
+ * projection. A cached name/allowlist cannot keep a revoked identity alive. */
+export function assignmentForCoordinator(store, token, operation, args, now, evidenceRoot) {
+    const problem = assignmentArgumentProblem(operation, args);
+    if (problem !== null)
+        return failure("usage", problem);
+    // Authenticate before maintenance, then authenticate again inside delivery.
+    // Reconciliation owns one short transaction per family and cannot sit under
+    // the delivery transaction's writer reservation.
+    if (operation === 'inbox') {
+        const authenticated = authenticateCoordinator(store, token);
+        if (!authenticated.ok)
+            return failure('unauthenticated', 'The coordinator credential is unavailable or revoked.');
+        syncAssignmentStatuses(store, now, authenticated.who.repos, evidenceRoot);
+    }
+    const project = () => {
+        const authenticated = authenticateCoordinator(store, token);
+        if (!authenticated.ok)
+            return failure("unauthenticated", "The coordinator credential is unavailable or revoked.");
+        const { who } = authenticated;
+        if (operation === "show" || operation === "updates" || operation === "brief")
+            return readAssignment(store, operation, args, now, { principal: "coordinator", repos: who.repos }, evidenceRoot);
+        const owner = { kind: "coordinator", id: who.cid, label: who.name };
+        if (operation === "inbox" || operation === "ack") {
+            const delivered = operation === "inbox"
+                ? assignmentInbox(store, owner, { consumer: String(args["consumer"]), ...(args["limit"] === undefined ? {} : { limit: Number(args["limit"]) }) }, now)
+                : acknowledgeAssignmentDelivery(store, owner, { consumer: String(args["consumer"]), batchId: String(args["batchId"]) }, now);
+            return delivered.ok ? { ok: true, body: delivered } : delivered;
+        }
+        const result = operation === "claim"
+            ? claimAssignment(store, String(args["ref"]), owner, now, evidenceRoot)
+            : checkAssignment(store, String(args["ref"]), String(args["digest"]), owner, now, evidenceRoot);
+        return result.ok ? { ok: true, body: result.assignment } : result;
+    };
+    return operation === 'show' || operation === 'updates' || operation === 'brief'
+        ? store.savepoint(project) : store.transact(project);
+}
+function assignmentLines(assignment) {
+    const receipt = assignment.receipt;
+    return [
+        `${assignment.rootId} · ${assignment.state}`,
+        assignment.detail,
+        `Current task: ${assignment.activeTaskId}`,
+        `Lead: ${assignment.owner === null ? "unclaimed" : `${assignment.owner.label}${assignment.owner.active ? "" : " (no longer has access)"}`}`,
+        ...(receipt === null ? [] : [
+            `Result: ${receipt.taskId} · run ${receipt.runId}`,
+            `Result type: ${receipt.completionKind === "verified-build" ? "verified build" : receipt.completionKind === "checked-build" ? "checks passed; lead review" : receipt.completionKind === "finished-build" ? "finished work; inspect check results" : receipt.completionKind === "research-report" ? "research report" : receipt.completionKind === "accepted-exception" ? "accepted exception" : "execution needs attention"}`,
+            ...(receipt.proofAcceptance === null ? [] : [`Recorded acceptance: ${receipt.proofAcceptance.approver}${receipt.proofAcceptance.note === null ? "" : ` · ${receipt.proofAcceptance.note}`}`]),
+            `Candidate: ${receipt.head ?? "not recorded"} (base ${receipt.base ?? "not recorded"})`,
+            `Checks: ${receipt.checks.detail}${receipt.checks.command === null ? "" : ` (${receipt.checks.command})`}`,
+            `Proof: ${receipt.proof?.verdict ?? "not recorded"} · evidence ${receipt.evidence}`,
+            ...(receipt.proof === null ? [] : [`Criteria: ${receipt.proof.matrix.filter(row => row.state === "pass").length}/${receipt.proof.matrix.length} recorded as passed`]),
+            ...receipt.caveats.map(one => `Recorded limitation: ${one}`),
+            ...(receipt.agentReport === null ? [] : [`Agent report: ${receipt.agentReport}`]),
+            `Receipt: ${receipt.digest}`,
+        ]),
+        ...(assignment.savedContext === undefined ? [] : [
+            ...(assignment.savedContext.goal === null ? [] : [`Goal: ${assignment.savedContext.goal}`]),
+            ...(assignment.savedContext.outOfScope === null ? [] : [`Out of scope: ${assignment.savedContext.outOfScope}`]),
+            ...assignment.savedContext.excerpts.map(one => `Saved ${one.kind} #${one.artifactId} (run ${one.runId}, ${one.sha256})${one.shortened ? " [shortened]" : ""}:\n${one.text ?? one.problem}`),
+        ]),
+        ...(assignment.completion === null ? [] : [`Handled by: ${assignment.completion.actor} at ${assignment.completion.at}`]),
+        ...assignment.attention.filter(one => one !== assignment.detail).map(one => `Attention: ${one}`),
+        ...(assignment.primaryAction === null ? [] : [`Next: ${assignment.primaryAction.label} (${assignment.primaryAction.access})`]),
+        `Publication: ${assignment.publication === null ? "not recorded" : assignment.publication.state}${assignment.publication?.prUrl ? ` · ${assignment.publication.prUrl}` : ""}`,
+        "Deployment: not recorded",
+    ];
+}
+function resultLines(body) {
+    if ("rootId" in body)
+        return assignmentLines(body);
+    if ("batch" in body)
+        return [
+            body.batch.events.length === 0 ? "No new assignment updates." : `${body.batch.events.length} assignment update${body.batch.events.length === 1 ? "" : "s"}.`,
+            ...body.batch.events.map(event => JSON.stringify(event)),
+            ...(body.batch.id === null ? [] : [`After handling: assignment ack --consumer ${body.batch.consumer} --batch ${body.batch.id}`]),
+            ...(body.batch.hasMore ? ["More updates remain after this batch."] : []),
+        ];
+    if ("alreadyAcknowledged" in body)
+        return [body.alreadyAcknowledged ? "This delivery was already acknowledged." : "Delivery acknowledged. Task status is unchanged."];
+    if ("assignments" in body)
+        return [
+            `Catch-up · ${body.asOf}`,
+            ...(body.assignments.length === 0 ? ["No assignments in this snapshot."] : body.assignments.flatMap(one => [
+                `${one.title} · ${one.state}`,
+                one.detail,
+                ...(one.goal === null ? [] : [`Goal: ${one.goal}`]),
+                ...(one.outcome === null ? [] : [`Saved agent report: ${one.outcome}`]),
+                ...one.decisions.filter(decision => decision.state !== "answered").map(decision => `Question: ${decision.question}`),
+                `Read: assignment show ${one.rootId}`,
+            ])),
+            ...body.projects.flatMap(project => [
+                `Knowledge: ${project.repo} · ${project.knowledge.status}${project.knowledge.revision === null ? "" : ` (version ${project.knowledge.revision})`}`,
+                ...(project.knowledge.instructions ? [project.knowledge.instructions] : []),
+            ]),
+            ...(body.omissions.assignments || body.omissions.decisions || body.omissions.projects || body.omissions.textFields
+                ? [`Shortened: ${body.omissions.assignments} assignments, ${body.omissions.decisions} decisions, ${body.omissions.projects} projects, ${body.omissions.textFields} text fields.`] : []),
+            ...body.omissions.notes,
+        ];
+    return [
+        ...(body.events.length === 0 ? ["No new assignment updates."] : body.events.flatMap(event => [
+            `Update ${event.id}${event.superseded ? " (superseded; inspect the current assignment)" : ""}`,
+            `${event.assignment.rootId} · ${event.assignment.state}`,
+            event.assignment.detail,
+            `Current task: ${event.assignment.activeTaskId}`,
+            `Read: assignment show ${event.assignment.rootId}`,
+        ])),
+        `Next cursor: ${body.nextCursor}${body.hasMore ? " · more updates available" : ""}`,
+    ];
+}
+/** Explicit secret source only. Never print secret values or discover default
+ * files. A bad explicit credential must not fall back to a local read. */
+export function coordinatorToken(flags, env) {
+    const envName = flags.get("token-env"), path = flags.get("token-file");
+    if (envName !== undefined && path !== undefined)
+        return failure("usage", "Choose either --token-env NAME or --token-file PATH.");
+    if (envName === undefined && path === undefined)
+        return { token: null };
+    let raw;
+    if (typeof envName === "string") {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(envName))
+            return failure("usage", "--token-env names an environment variable.");
+        raw = env[envName];
+    }
+    else if (typeof path === "string") {
+        try {
+            const info = statSync(path);
+            if (!info.isFile() || info.size > 16_384)
+                return failure("usage", "The explicit token file must be a regular file no larger than 16 KiB.");
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
+            return failure("unauthenticated", "The explicit token file could not be read.");
+        }
+    }
+    const token = raw?.trim();
+    if (!token || token.length > 4096 || /\s/.test(token))
+        return failure("unauthenticated", "The explicit credential source must contain one coordinator token.");
+    return { token };
+}
+export function runAssignmentCommand(positional, flags, context) {
+    const operation = positional[0];
+    const command = context.commandName ?? (ASSIGNMENT_ACTIONS.includes(operation) ? `assignment ${operation}` : "assignment");
+    const emit = (result) => {
+        if (context.json)
+            context.write(envelopeJson(result.ok ? { ok: true, command, result: result.body } : { ...result, command }));
+        else if (!result.ok)
+            context.write(result.message);
+        else
+            context.write(resultLines(result.body).join("\n"));
+        return result.ok ? 0 : result.reason === "usage" ? 2 : 3;
+    };
+    if (!ASSIGNMENT_ACTIONS.includes(operation))
+        return emit(failure("usage", "Use assignment show <task>, updates, claim <task>, check <task> --digest <receipt>, brief, inbox --consumer <name>, or ack --consumer <name> --batch <id>."));
+    const operationFlags = operation === "brief" ? ["repo", "limit"] : operation === "inbox" ? ["consumer", "limit"] : operation === "ack" ? ["consumer", "batch"] : operation === "updates" ? ["after", "limit"] : operation === "check" ? ["digest"] : [];
+    const allowed = new Set(["json", "db", "token-env", "token-file", ...operationFlags]);
+    for (const flag of flags.keys())
+        if (!allowed.has(flag))
+            return emit(failure("usage", `--${flag} is not an assignment ${operation} option.`));
+    const hasTask = ["show", "claim", "check"].includes(operation);
+    if (positional.length !== (hasTask ? 2 : 1))
+        return emit(failure("usage", hasTask ? `assignment ${operation} takes exactly one task id.` : `assignment ${operation} takes no task argument.`));
+    const args = hasTask ? { ref: positional[1] } : {};
+    for (const flag of operationFlags) {
+        const value = flags.get(flag);
+        if (value !== undefined)
+            args[flag === "batch" ? "batchId" : flag] = ["after", "limit"].includes(flag) ? typeof value === "string" && /^\d+$/.test(value) ? Number(value) : NaN : value;
+    }
+    const problem = assignmentArgumentProblem(operation, args);
+    if (problem !== null)
+        return emit(failure("usage", problem));
+    const credential = coordinatorToken(flags, context.env ?? process.env);
+    if ("ok" in credential)
+        return emit(credential);
+    if (credential.token !== null)
+        return emit(assignmentForCoordinator(context.store, credential.token, operation, args, context.now, context.evidenceRoot));
+    if (operation === "claim" || operation === "check" || operation === "inbox" || operation === "ack")
+        return emit(failure("unauthenticated", "Use --token-env NAME or --token-file PATH with your coordinator credential to own an assignment or receive and acknowledge its updates."));
+    return emit(readAssignment(context.store, operation, args, context.now, { principal: "operator", repos: null, includeUnplaced: true }, context.evidenceRoot));
+}