toolroll 0.9.5 → 0.9.7

package/dist/surface.js

@@ -135,8 +135,27 @@ export const COMMAND_GUIDE = [
         flags: [jsonFlag, dbFlag, keyFlag,
             { name: "id", takesValue: true, meaning: "choose the task id" },
             { name: "repo", takesValue: true, meaning: "which repository the task belongs to" },
-            { name: "report", takesValue: false, meaning: "a scout task: the deliverable is a report, never a branch" }],
-        notableReasons: ["duplicate", "usage"] },
+            { name: "report", takesValue: false, meaning: "a scout task: the deliverable is a report, never a branch" },
+            { name: "replaces", takesValue: true, meaning: "the task this one replaces: it is cancelled and reads \"Replaced by <id>\"" },
+            { name: "token", takesValue: true, meaning: "a lead token: filed as the lead, so it pings nobody" },
+            { name: "checks", takesValue: true, meaning: "quick|full|off: this task's checks, overriding the project's level (\"skip the tests\" is off)" }],
+        notableReasons: ["duplicate", "usage", "unknown-task", "unauthenticated"] },
+    { invocation: "task ask", synopsis: "hand a task to a person: one message saying why, and the task is theirs", audience: "agent", agentMayInvoke: true, mutation: "unkeyed",
+        positionals: [{ name: "id", required: true, meaning: "the task" }],
+        flags: [jsonFlag, dbFlag,
+            { name: "person", takesValue: true, meaning: "who to ask (someone who can see the task's project)" },
+            { name: "why", takesValue: true, meaning: "what they need to do, one line" },
+            { name: "token", takesValue: true, meaning: "the lead token (or TOOLROLL_LEAD_TOKEN)" }],
+        notableReasons: ["unknown-task", "unknown-person", "unplaced", "unauthenticated"] },
+    { invocation: "task checks", synopsis: "run checks on the task's latest result, on its exact commit, now; a pass upgrades its status and a failure stays visible",
+        audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "task", required: true, meaning: "any version of the task" }],
+        flags: [jsonFlag, dbFlag, { name: "level", takesValue: true, meaning: "quick (default) or full" }],
+        notableReasons: ["no-result", "no-check", "checks-failed"] },
+    { invocation: "task add-tests", synopsis: "file a small task to write tests for the task's latest change; it waits for approval like any task",
+        audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
+        positionals: [{ name: "task", required: true, meaning: "any version of the task" }], flags: [jsonFlag, dbFlag],
+        notableReasons: ["no-result"] },
     { invocation: "task list", synopsis: "a page of saved task status", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag, dbFlag, { name: "state", takesValue: true, meaning: "queued|running|done|failed|cancelled" },
             { name: "view", takesValue: true, meaning: "all|needs-you|running|completed" },
@@ -168,8 +187,9 @@ export const COMMAND_GUIDE = [
     { invocation: "task merge", synopsis: "merge the task's pull request once its checks pass — the console's Merge, behind the approver's password; the project's method (squash by default), branch deleted, recorded in the ledger",
         audience: "operator", agentMayInvoke: false, mutation: "identity-idempotent",
         positionals: [{ name: "task", required: true, meaning: "any version of the task" }],
-        flags: [jsonFlag, dbFlag, { name: "as", takesValue: true, meaning: "the approver merging" }, { name: "token", takesValue: true, meaning: "their password" }],
-        notableReasons: ["usage", "not-an-approver"] },
+        flags: [jsonFlag, dbFlag, { name: "as", takesValue: true, meaning: "the approver merging" }, { name: "token", takesValue: true, meaning: "their password" },
+            { name: "anyway", takesValue: false, meaning: "merge a Quick or Off result without waiting for its full check" }],
+        notableReasons: ["usage", "not-an-approver", "full-checks"] },
     ...["show", "updates", "claim", "check", "brief", "inbox", "ack"].map(action => ({
         invocation: `assignment ${action}`,
         synopsis: action === "show" ? "read the root, current work, owner and exact receipt"
@@ -193,7 +213,8 @@ export const COMMAND_GUIDE = [
             ...(action === "ack" ? [{ name: "batch", takesValue: true, meaning: "exact batch ID returned by assignment inbox" }] : []),
         ],
     })),
-    operator("task state", "set a task's state by hand — an operator correction, not a workflow step"),
+    operator("task state", "set a task's state by hand — an operator correction, not a workflow step (--replaced-by <id> with cancelled)"),
+    operator("lead token", "mint the lead's credential behind your password (--revoke ends it): its own work pings nobody"),
     { invocation: "task block", synopsis: "make one task wait for another", audience: "agent", agentMayInvoke: true, mutation: "keyed",
         positionals: [{ name: "id", required: true, meaning: "the waiting task" }],
         flags: [jsonFlag, dbFlag, keyFlag, { name: "on", takesValue: true, meaning: "the blocker's id" }],
@@ -289,7 +310,7 @@ export const COMMAND_GUIDE = [
         positionals: [{ name: "id", required: true, meaning: "the routine" }], flags: [jsonFlag, dbFlag] },
     { invocation: "config show", synopsis: "phase and spend configuration", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
     { invocation: "setup show", synopsis: "installation setup", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
-    { invocation: "verify show", synopsis: "the repository's approved verification command, if one exists", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
+    { invocation: "verify show", synopsis: "the repository's check level, its approved full and quick commands, and a suggested quick command", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
     { invocation: "intake show", synopsis: "intake configuration", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "providers", synopsis: "which agent providers this binary can drive, and their transports; --report records this machine's readiness under its runner", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag,
@@ -309,6 +330,7 @@ export const COMMAND_GUIDE = [
     operator("runner retire", "retire a worker"),
     operator("runner bind", "replace which repositories a worker may build in"),
     operator("runner capacity", "set how many tasks a worker runs at once; running work carries on, the new number applies at the next claim"),
+    operator("project concurrency", "set how many of a project's tasks build at once (default 2, never past the worker's capacity); running work carries on"),
     operator("coordinator mint", "mint the MCP filing credential — repo-bound, rate-limited, token shown once"),
     operator("coordinator revoke", "revoke an MCP filing credential"),
     operator("mcp", "serve the MCP gateway over stdio — the coordinator credential is the only key it accepts"),
@@ -340,8 +362,9 @@ export const COMMAND_GUIDE = [
     operator("config set", "set phase or spend configuration"),
     operator("config clear", "clear phase or spend configuration"),
     operator("setup clear", "clear installation setup"),
-    operator("verify set", "approve the one shell command the plane re-runs after every future commit; --self-heal binds one approved-setup replay when a required project executable is missing"),
-    operator("verify clear", "revoke a repository's approved verification command"),
+    operator("verify set", "approve the one shell command the plane re-runs after every future commit (--quick \"<cmd>\" approves the fast check Quick runs); --self-heal binds one approved-setup replay when a required project executable is missing"),
+    operator("verify clear", "revoke a repository's approved verification command; --level quick revokes only the quick command"),
+    operator("verify level", "set a project's checks after each build: quick (the approved quick command), full, or off — an approver's act, in the ledger"),
     operator("intake grant", "grant an intake source"),
     operator("intake run", "run intake now"),
     operator("intake preview", "preview what intake would file"),

package/dist/tailnet.d.ts

@@ -0,0 +1,11 @@
+type Runner = (file: string, args: readonly string[], options: {
+    timeoutMs: number;
+}) => Promise<{
+    code: number | null;
+    stdout: string;
+    notFound?: boolean;
+}>;
+/** The full MagicDNS name first (machine.tailnet.ts.net), then its short form (machine). Empty when Tailscale isn't running. */
+export declare function tailnetNamesOf(statusJson: string): string[];
+export declare function readTailnetNames(runner?: Runner, platform?: NodeJS.Platform): Promise<string[]>;
+export {};

package/dist/tailnet.js

@@ -0,0 +1,47 @@
+/**
+ * This computer's own names on its tailnet, when Tailscale is up: the console
+ * answers to them on its port without an --allow-host, and the phone card
+ * names the address to type. Read with `tailscale status --json`, which
+ * spends nothing and changes nothing; any failure means no tailnet.
+ */
+import { existsSync } from "node:fs";
+import { run } from "./exec.js";
+/** The Mac app ships its command line inside the app bundle. */
+const MAC_APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
+const NAME = /^[a-z0-9]([a-z0-9-]{0,62})(\.[a-z0-9]([a-z0-9-]{0,62}))*$/;
+/** The full MagicDNS name first (machine.tailnet.ts.net), then its short form (machine). Empty when Tailscale isn't running. */
+export function tailnetNamesOf(statusJson) {
+    let status;
+    try {
+        status = JSON.parse(statusJson);
+    }
+    catch {
+        return [];
+    }
+    if (typeof status !== "object" || status === null)
+        return [];
+    const body = status;
+    if (body.BackendState !== "Running" || typeof body.Self?.DNSName !== "string")
+        return [];
+    const full = body.Self.DNSName.replace(/\.$/, "").toLowerCase();
+    if (!NAME.test(full) || full.length > 253)
+        return [];
+    const short = full.split(".")[0];
+    return short === full ? [full] : [full, short];
+}
+export async function readTailnetNames(runner = run, platform = process.platform) {
+    const candidates = ["tailscale", ...(platform === "darwin" && existsSync(MAC_APP_CLI) ? [MAC_APP_CLI] : [])];
+    for (const file of candidates) {
+        try {
+            const answer = await runner(file, ["status", "--json"], { timeoutMs: 3_000 });
+            if (answer.notFound === true)
+                continue;
+            if (answer.code === 0)
+                return tailnetNamesOf(answer.stdout);
+        }
+        catch {
+            // No Tailscale here: no tailnet names.
+        }
+    }
+    return [];
+}

package/dist/task-outcome-cli.js

@@ -126,7 +126,7 @@ export async function runTaskMergeCommand(positional, flags, context) {
         return result.ok ? 0 : result.reason === 'usage' ? 2 : 3;
     };
     const fail = (reason, message) => emit({ ok: false, reason, message });
-    const allowed = new Set(['json', 'db', 'as', 'token']);
+    const allowed = new Set(['json', 'db', 'as', 'token', 'anyway']);
     for (const key of flags.keys())
         if (!allowed.has(key))
             return fail('usage', `--${key} is not a task merge option.`);
@@ -147,7 +147,7 @@ export async function runTaskMergeCommand(positional, flags, context) {
     const view = newestPullRequestOf(store, family.versions.map(one => one.id));
     if (view === null)
         return fail('no-pr', 'This task has no pull request. Open one with task complete --pull-request.');
-    const merged = await mergeAsPerson(store, { runId: view.runId, name: acting.name, password: acting.token, ...(context.exec === undefined ? {} : { exec: context.exec }), clock: context.clock });
+    const merged = await mergeAsPerson(store, { runId: view.runId, name: acting.name, password: acting.token, ...(flags.get('anyway') === true ? { anyway: true } : {}), ...(context.exec === undefined ? {} : { exec: context.exec }), clock: context.clock });
     if (!merged.ok)
         return emit({ ...merged, reason: merged.reason === 'password' ? 'not-an-approver' : merged.reason, pullRequest: view });
     const after = newestPullRequestOf(store, family.versions.map(one => one.id));

package/dist/task-status.d.ts

@@ -0,0 +1,186 @@
+/** One answer per task, then the details (docs/design/task-status.md). Every
+ * surface — the Tasks list, the task page, the build page, Crew, the Chat
+ * result, the Telegram/Slack/Discord/Teams cards and `toolroll status` — reads
+ * its headline, sentence, tone and detail rows from `taskStatusOf`, so the
+ * words cannot drift apart again. Pure: it reads facts the existing
+ * projections already recorded and never changes a check, approval or
+ * completion.
+ *
+ * Severity: red belongs to the Failed headline alone. A detail problem that
+ * doesn't undo the outcome (a pull request that couldn't open, shortened
+ * output) is an amber note on its own row with one action; the exact
+ * technical reason stays one tap away in `why`. */
+import type { AssignmentSnapshot } from "./assignment.js";
+/** A cancelled task with a successor reads "Replaced by <id>" everywhere, never "Cancelled". */
+export declare const replacedWords: (successor: string) => string;
+export declare const HEADLINES: readonly ["Queued", "Planning", "Needs you", "Building", "Ready for review", "Complete", "Failed", "Stopped"];
+export type Headline = (typeof HEADLINES)[number];
+export type HeadlineTone = "neutral" | "live" | "attention" | "ready" | "success" | "danger";
+export declare const HEADLINE_TONE: Readonly<Record<Headline, HeadlineTone>>;
+export type DetailKey = "checks" | "pull-request" | "requirements" | "evidence";
+/** The row's small icon: the only coloured part of a detail. `failed` is red
+ * and only ever appears under the Failed headline; `note` is amber. */
+export type DetailMark = "ok" | "running" | "none" | "note" | "failed";
+export type StatusAction = {
+    label: string;
+    href: string | null;
+};
+export type StatusDetail = {
+    key: DetailKey;
+    label: string;
+    text: string;
+    mark: DetailMark;
+    href: string | null;
+    action: StatusAction | null;
+    why: string | null;
+};
+export type TaskStatus = {
+    headline: Headline;
+    tone: HeadlineTone;
+    sentence: string;
+    details: StatusDetail[];
+    primaryAction: StatusAction | null;
+    why: string[];
+};
+export type TaskStage = "queued" | "planning" | "needs-you" | "building" | "checking" | "finished" | "complete" | "failed" | "stopped";
+export type ChecksFact = {
+    status: "passed" | "failed" | "running" | "not-run" | "unavailable";
+    exitCode: number | null;
+    head: string | null;
+    /** The check level that ran (check-levels.ts). Off never reads Ready; a quick pass says so. */
+    level?: "quick" | "full" | "off" | null;
+    /** A follow-up check (Run checks) waiting or running on this commit. */
+    running?: "quick" | "full" | null;
+};
+export type PullRequestFact = {
+    state: "none" | "opening" | "open" | "merged" | "closed" | "failed";
+    number: number | null;
+    url: string | null;
+    ci: "running" | "passing" | "failing" | null;
+    error: string | null;
+    /** GitHub's compare page for the pushed branch: where a person opens it by hand. */
+    compareUrl?: string | null;
+    /** Who merged it and its merge commit, shown on request. */
+    note?: string | null;
+};
+export type TaskStatusFacts = {
+    stage: TaskStage;
+    /** Needs you: what a person is asked for. The sentence names it. */
+    need?: "approval" | "answer" | "sign-in" | "other";
+    /** The recorded reason in plain words, when the stage has one. */
+    reason?: string | null;
+    /** A research report rather than a code change. */
+    report?: boolean;
+    checks?: ChecksFact | null;
+    pullRequest?: PullRequestFact | null;
+    requirements?: {
+        met: number;
+        total: number;
+        yours: number;
+    } | null;
+    evidence?: {
+        shortened: number;
+        missing: number;
+        damaged: number;
+    } | null;
+    completedBy?: string | null;
+    action?: StatusAction | null;
+    /** Where a row's one action leads: the result (and its Checks tab), the task's pull request, Run checks. */
+    links?: {
+        result?: string | null;
+        checks?: string | null;
+        pullRequest?: string | null;
+        runChecks?: string | null;
+    };
+    /** Exact technical reasons, shown only on request. */
+    why?: readonly string[];
+};
+export declare function headlineOf(facts: Pick<TaskStatusFacts, "stage" | "checks" | "report">): Headline;
+export declare function taskStatusOf(facts: TaskStatusFacts): TaskStatus;
+export declare function plainReasonOf(stage: TaskStage, code: string, detail: string | null | undefined): string | null;
+export declare function stageOfCode(code: string, options?: {
+    needsPerson?: boolean;
+    planning?: boolean;
+    operatorHold?: boolean;
+}): {
+    stage: TaskStage;
+    need?: TaskStatusFacts["need"];
+};
+/** The pull request as the task page's follower reports it, or the bare publication row. */
+export declare function pullRequestFactOf(publication: {
+    state: string;
+    prNumber?: number | null;
+    prUrl: string | null;
+    remoteState: string | null;
+    lastCheckState?: string | null;
+    lastError?: string | null;
+    merged?: boolean;
+    githubRepo?: string;
+    base?: string;
+    head?: string;
+} | null): PullRequestFact | null;
+/** The assignment's stage. The work status, when the caller read one, names
+ * the exact reason (a running planner, a pause, a failed attempt, a sign-in). */
+export declare function assignmentStageOf(assignment: Pick<AssignmentSnapshot, "state" | "primaryAction">, work?: {
+    token: string;
+    views?: readonly string[];
+} | null, planning?: boolean): {
+    stage: TaskStage;
+    need?: TaskStatusFacts["need"];
+};
+/** Requirements from the stored matrix: met, the ones only a person confirms, and the total. */
+export declare function requirementsOf(matrix: readonly {
+    state: string;
+    assessment?: {
+        evidenceState?: string;
+    } | undefined;
+    review?: unknown;
+}[] | null | undefined): NonNullable<TaskStatusFacts["requirements"]> | null;
+/** Saved evidence health from the receipt's artifact list and its caveats. */
+export declare function evidenceOf(receipt: AssignmentSnapshot["receipt"], problems?: readonly string[]): NonNullable<TaskStatusFacts["evidence"]> | null;
+/** The status facts of one assignment, as every surface reads them. */
+export declare function assignmentStatusFacts(assignment: AssignmentSnapshot, options?: {
+    work?: {
+        token: string;
+        views?: readonly string[];
+        detail?: string;
+    } | null;
+    planning?: boolean;
+    pullRequest?: PullRequestFact | null;
+    action?: StatusAction | null;
+    links?: TaskStatusFacts["links"];
+    evidence?: TaskStatusFacts["evidence"];
+    why?: readonly string[];
+}): TaskStatusFacts;
+/** The legacy work tone each headline wears where a surface still keys off StatusTone. */
+export declare function workToneOf(headline: Headline): "attention" | "problem" | "live" | "ready" | "done" | "muted";
+/** One plain-text line per detail for chat cards: an icon, the label, the words. */
+export declare function statusDetailLines(status: TaskStatus): string[];
+/** The headline's emoji for chat cards (colour is never the only signal: the words follow). */
+export declare function headlineEmoji(headline: Headline): string;
+export declare const statusIconSvg: (mark: DetailMark) => string;
+/** The detail rows as server HTML: quiet rows, colour only on the icon. */
+export declare function statusDetailsHtml(status: TaskStatus): string;
+/** The technical reasons, one tap away. */
+export declare function statusWhyHtml(status: TaskStatus, extra?: readonly string[], diagnostics?: readonly {
+    token: string;
+    label: string;
+    detail: string;
+}[]): string;
+/** Shared CSS for the server-rendered status: neutral rows, coloured icons. */
+export declare const TASK_STATUS_CSS = ".status-headline{display:flex;align-items:center;gap:.6rem;margin:0;font-size:1.125rem;font-weight:600;color:var(--foreground)}.status-headline i{width:.625rem;height:.625rem;border-radius:999px;flex-shrink:0;background:var(--muted-foreground)}[data-headline-tone=live] .status-headline i{background:var(--so-info,#0d74ce)}[data-headline-tone=attention] .status-headline i{background:var(--so-attention,var(--attention))}[data-headline-tone=ready] .status-headline i{background:transparent;box-shadow:inset 0 0 0 2px var(--so-success,#218358)}[data-headline-tone=success] .status-headline i{background:var(--so-success,#218358)}[data-headline-tone=danger] .status-headline i{background:var(--so-danger,#c4320a)}.status-sentence{margin:.35rem 0 0;color:var(--muted-foreground)}.status-details{list-style:none;margin:.75rem 0 0;padding:.25rem 0 0;border-top:1px solid var(--so-line,var(--border))}.status-detail{display:grid;grid-template-columns:14px 7.5rem minmax(0,1fr);align-items:center;gap:.6rem;padding:.4rem 0;font-size:.8125rem;color:var(--foreground)}.status-detail .status-icon{align-self:center;color:var(--muted-foreground)}.status-detail--ok .status-icon{color:var(--so-success,#218358)}.status-detail--running .status-icon{color:var(--so-info,#0d74ce)}.status-detail--note .status-icon{color:var(--so-warning,#ab6400)}.status-detail--failed .status-icon{color:var(--so-danger,#c4320a)}.status-detail-label{color:var(--muted-foreground)}.status-detail-text{display:flex;flex-wrap:wrap;align-items:baseline;gap:0 .6rem;min-width:0;overflow-wrap:anywhere}.status-detail-text a{color:inherit}.status-detail-act{font-weight:600;white-space:nowrap}.status-detail--note .status-detail-act{color:var(--so-warning,#ab6400)}@media(max-width:480px){.status-detail{grid-template-columns:14px 6.5rem minmax(0,1fr);min-height:2.75rem;padding:.25rem 0}.status-detail-text a{display:inline-block;padding:.75rem 0;margin:-.75rem 0}}.status-why{border:0;padding:0;margin:.25rem 0 0;background:transparent;box-shadow:none}.status-why>summary{cursor:pointer;min-height:2.75rem;display:list-item;align-content:center;font-size:.8125rem;color:var(--muted-foreground)}.status-why p{margin:.25rem 0 .5rem}.receipt-note{display:flex;align-items:center;gap:.45rem;font-size:.8125rem;color:var(--foreground)}.receipt-note .status-icon{color:var(--so-warning,#ab6400)}";
+/** A dispatch diagnosis as its stage, for the phone and CLI reads that hold
+ * no assignment. A done task is Complete once a person marked its result;
+ * a refuted result whose project check failed is Failed. */
+export declare function stageOfDispatch(d: {
+    code: string;
+    condition: string;
+    action: string | null;
+    role?: string | null;
+    detail?: string;
+}, options?: {
+    completed?: boolean;
+}): {
+    stage: TaskStage;
+    need?: TaskStatusFacts["need"];
+};