toolroll 0.9.45 → 0.9.47

package/dist/task-activity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a running agent did last, recorded and read (live tasks).
+ *
+ * The recorder sits beside the live log on the agent's stream and keeps one
+ * row per run: a fixed kind from live.ts's vocabulary and when. No text, no
+ * tool names, no arguments are ever kept, so nothing here can leak a secret.
+ * The reader picks the newer of that row and the run's latest progress
+ * checkpoint, and asks the runner's heartbeat whether the worker still
+ * answers. Neither side reads or stats a live-log file.
+ */
+import { type RunActivity } from "./activity-line.js";
+import type { Store } from "./store.js";
+type Observer = {
+    observe(event: Record<string, unknown>): void;
+    close(): void;
+};
+/** Watch a run's stream for what the agent does, alongside its live log (which may be null). Fail-soft: a write
+ * that fails never touches the run. */
+export declare function withRunActivity(liveLog: Observer | null, store: Pick<Store, "recordRunActivity">, run: number, clock: () => Date): Observer;
+/** A live run's last activity: the newer of its recorded kind and its latest progress checkpoint, else when it
+ * started; and "offline" only when its registered worker's heartbeat has lapsed. */
+export declare function runActivityOf(store: Store, run: {
+    id: number;
+    runner: string;
+    startedAt: string;
+}, now: Date): RunActivity;
+export {};

package/dist/task-activity.js

@@ -0,0 +1,53 @@
+/**
+ * What a running agent did last, recorded and read (live tasks).
+ *
+ * The recorder sits beside the live log on the agent's stream and keeps one
+ * row per run: a fixed kind from live.ts's vocabulary and when. No text, no
+ * tool names, no arguments are ever kept, so nothing here can leak a secret.
+ * The reader picks the newer of that row and the run's latest progress
+ * checkpoint, and asks the runner's heartbeat whether the worker still
+ * answers. Neither side reads or stats a live-log file.
+ */
+import { ACTIVITY_WORDS } from "./activity-line.js";
+import { liveActivityKind } from "./live.js";
+import { isAlive } from "./runner.js";
+/** At most one write per run this often while the kind stays the same: the age is in seconds, not milliseconds. */
+const SAME_KIND_EVERY_MS = 5_000;
+/** Watch a run's stream for what the agent does, alongside its live log (which may be null). Fail-soft: a write
+ * that fails never touches the run. */
+export function withRunActivity(liveLog, store, run, clock) {
+    let last = null;
+    return {
+        observe(event) {
+            liveLog?.observe(event);
+            const kind = liveActivityKind(event);
+            if (kind === null)
+                return;
+            try {
+                const now = clock();
+                if (last !== null && last.kind === kind && now.getTime() - last.at < SAME_KIND_EVERY_MS)
+                    return;
+                store.recordRunActivity(run, kind, now);
+                last = { kind, at: now.getTime() };
+            }
+            catch { /* display state: the next event tries again */ }
+        },
+        close() { liveLog?.close(); },
+    };
+}
+/** A live run's last activity: the newer of its recorded kind and its latest progress checkpoint, else when it
+ * started; and "offline" only when its registered worker's heartbeat has lapsed. */
+export function runActivityOf(store, run, now) {
+    const recorded = store.runActivity(run.id);
+    let what = ACTIVITY_WORDS["started"], at = run.startedAt;
+    if (recorded.kind !== null && recorded.at !== null && recorded.at >= at) {
+        what = ACTIVITY_WORDS[recorded.kind] ?? ACTIVITY_WORDS["tool"];
+        at = recorded.at;
+    }
+    if (recorded.progressAt !== null && recorded.progressAt > at) {
+        what = ACTIVITY_WORDS["progress"];
+        at = recorded.progressAt;
+    }
+    const worker = store.getRunner(run.runner)?.runner;
+    return { what, at, worker: worker === undefined || isAlive(worker, now) ? "online" : "offline" };
+}

package/dist/task-live.d.ts

@@ -0,0 +1,17 @@
+import type { ServerResponse } from "node:http";
+import { type Store } from "./store.js";
+export type TaskViewer = {
+    name: string;
+    response: ServerResponse;
+    valid: () => boolean;
+};
+/** What changes when anything on the task page changes: one read over the family, kept short and opaque. */
+export declare function taskFingerprint(store: Store, root: string, now: Date, livenessMs?: number): string | null;
+export type TaskRooms = {
+    /** Keep this page's stream on the task family until it closes; the first events say where it stands and who's here. */
+    join: (root: string, viewer: TaskViewer) => void;
+    /** Every stream, ended (the server is closing). */
+    close: () => void;
+    size: () => number;
+};
+export declare function createTaskRooms(fingerprint: (root: string) => string | null, tickMs?: number): TaskRooms;

package/dist/task-live.js

@@ -0,0 +1,144 @@
+/**
+ * The live task page (live tasks): a task open in several browsers stays the
+ * same in all of them, and each shows who else has it open. The same design
+ * as the live canvas (flow-live.ts):
+ *
+ * - A change nudge. While anyone has a task open, one indexed read a second,
+ *   keyed by the task family's root, takes the family's fingerprint (its
+ *   versions' states, runs, decisions, progress checkpoints, what the agent
+ *   did last, and whether each live run's worker still answers); when it
+ *   changes, every open page hears "change" and reads the task again the
+ *   usual way. The nudge carries no task data.
+ * - Who's here. Everyone else with the task open, by name, one line per
+ *   person however many pages they have. Memory only; it goes when the page
+ *   closes or hides.
+ *
+ * Streams are refresh hints only: nothing here writes, and a page that can't
+ * keep one open reads itself on its usual beat.
+ */
+import { createHash } from "node:crypto";
+import { DEFAULT_LIVENESS_MS } from "./runner.js";
+import { BUILT_IN } from "./store.js";
+const TICK_MS = 1_000;
+const CHECK_EVERY = 15;
+const HEARTBEAT_EVERY = 15;
+const PRESENCE_SETTLE_MS = 150;
+/** What changes when anything on the task page changes: one read over the family, kept short and opaque. */
+export function taskFingerprint(store, root, now, livenessMs = DEFAULT_LIVENESS_MS) {
+    const row = store.handle.prepare(`WITH RECURSIVE family(ref, ext, depth) AS (
+      SELECT id, external_id, 0 FROM task_ref WHERE backend = ?3 AND external_id = ?1
+      UNION
+      SELECT child.id, child.external_id, family.depth + 1 FROM family
+        JOIN task_ref child ON child.backend = ?3 AND child.revision_of = family.ext WHERE family.depth < 63
+    )
+    SELECT (SELECT count(*) || ':' || group_concat(t.state || '@' || t.updated_at, ',') FROM family JOIN task t ON t.id = family.ext) AS tasks,
+      (SELECT count(*) || ':' || coalesce(max(r.id), 0) || ':' || coalesce(sum(r.outcome IS NULL), 0) || ':' || coalesce(max(coalesce(r.finished_at, r.started_at)), '') || ':' || coalesce(group_concat(r.phase), '')
+         FROM run r WHERE r.task_ref IN (SELECT ref FROM family)) AS runs,
+      (SELECT count(*) || ':' || coalesce(max(d.id), 0) || ':' || coalesce(sum(d.state = 'answered'), 0) FROM decision d JOIN run r ON r.id = d.run WHERE r.task_ref IN (SELECT ref FROM family)) AS decisions,
+      (SELECT coalesce(max(c.id), 0) FROM run_checkpoint c WHERE c.task_ref IN (SELECT ref FROM family)) AS progress,
+      (SELECT coalesce(max(a.at), '') FROM run_activity a JOIN run r ON r.id = a.run WHERE r.task_ref IN (SELECT ref FROM family) AND r.outcome IS NULL) AS activity,
+      (SELECT coalesce(group_concat(w.heartbeat_at > ?2), '') FROM run r JOIN runner w ON w.name = r.runner WHERE r.task_ref IN (SELECT ref FROM family) AND r.outcome IS NULL) AS workers
+    WHERE EXISTS (SELECT 1 FROM family)`).get(root, new Date(now.getTime() - livenessMs).toISOString(), BUILT_IN);
+    return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
+}
+export function createTaskRooms(fingerprint, tickMs = TICK_MS) {
+    const rooms = new Map();
+    const write = (viewer, event, data) => {
+        if (viewer.response.writableEnded || viewer.response.destroyed)
+            return;
+        viewer.response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    /** Everyone on the task but you, once each, by name. */
+    const others = (room, me) => [...new Set([...room.viewers].map(one => one.name).filter(name => name !== me))].sort((a, b) => a.localeCompare(b));
+    const announce = (room) => {
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        room.settling = setTimeout(() => {
+            room.settling = null;
+            for (const viewer of room.viewers)
+                write(viewer, "here", { people: others(room, viewer.name) });
+        }, PRESENCE_SETTLE_MS);
+        room.settling.unref();
+    };
+    const leave = (root, viewer) => {
+        const room = rooms.get(root);
+        if (room === undefined || !room.viewers.delete(viewer))
+            return;
+        if (!viewer.response.writableEnded)
+            viewer.response.end();
+        if (room.viewers.size > 0) {
+            announce(room);
+            return;
+        }
+        if (room.timer !== null)
+            clearInterval(room.timer);
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        rooms.delete(root);
+    };
+    const tick = (root, room) => {
+        room.ticks += 1;
+        if (room.ticks % CHECK_EVERY === 0) {
+            // A signed-out or narrowed account stops hearing about the task.
+            for (const viewer of [...room.viewers])
+                if (!viewer.valid()) {
+                    write(viewer, "gone", {});
+                    leave(root, viewer);
+                }
+            if (!rooms.has(root))
+                return;
+        }
+        let now;
+        try {
+            now = fingerprint(root);
+        }
+        catch {
+            return; /* a busy database: the next tick reads again */
+        }
+        if (now === null) {
+            for (const viewer of [...room.viewers]) {
+                write(viewer, "gone", {});
+                leave(root, viewer);
+            }
+            return;
+        }
+        if (now !== room.last) {
+            room.last = now;
+            for (const viewer of room.viewers)
+                write(viewer, "change", { at: now });
+        }
+        else if (room.ticks % HEARTBEAT_EVERY === 0) {
+            for (const viewer of room.viewers)
+                if (!viewer.response.writableEnded)
+                    viewer.response.write(": keep-alive\n\n");
+        }
+    };
+    return {
+        join(root, viewer) {
+            let room = rooms.get(root);
+            if (room === undefined) {
+                let last = null;
+                try {
+                    last = fingerprint(root);
+                }
+                catch { /* the first tick reads it */ }
+                room = { viewers: new Set(), last, timer: null, ticks: 0, settling: null };
+                const created = room;
+                room.timer = setInterval(() => tick(root, created), tickMs);
+                room.timer.unref();
+                rooms.set(root, room);
+            }
+            room.viewers.add(viewer);
+            write(viewer, "change", { at: room.last });
+            write(viewer, "here", { people: others(room, viewer.name) });
+            announce(room);
+            viewer.response.once("close", () => leave(root, viewer));
+        },
+        close() {
+            for (const [root, room] of [...rooms])
+                for (const viewer of [...room.viewers])
+                    leave(root, viewer);
+        },
+        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
+    };
+}

package/dist/token-notices.d.ts

@@ -0,0 +1,22 @@
+/**
+ * API token notices (v111): 7 days and 1 day before a token expires, its person is told once each, in their own chats
+ * and browsers (a personal notification), and the ledger keeps it. Only the nearest notice newly due is sent, so a
+ * token made with a day left says so once. Replaced and revoked tokens get none. The same pass records the end of each
+ * rotated token whose overlap has passed; it already signs no one in (tokenLive), so a late pass grants nothing.
+ */
+import { tokenLive } from "./api-tokens.js";
+import type { Store } from "./store.js";
+export declare const TOKEN_NOTICE_KIND = "api-token-expiry";
+export declare function tokenNoticePass(store: Store, now: Date): {
+    sent: {
+        token: string;
+        days: number;
+    }[];
+    ended: number;
+};
+/** Whether a token's console card warns that it expires soon (within the first notice's days). */
+export declare function expiresSoon(token: Parameters<typeof tokenLive>[0] & {
+    replacedBy: string | null;
+}, now: number): boolean;
+/** The loop beside the console: a pass a minute. */
+export declare function startTokenNotices(store: Store, everyMs?: number): () => void;

package/dist/token-notices.js

@@ -0,0 +1,52 @@
+/**
+ * API token notices (v111): 7 days and 1 day before a token expires, its person is told once each, in their own chats
+ * and browsers (a personal notification), and the ledger keeps it. Only the nearest notice newly due is sent, so a
+ * token made with a day left says so once. Replaced and revoked tokens get none. The same pass records the end of each
+ * rotated token whose overlap has passed; it already signs no one in (tokenLive), so a late pass grants nothing.
+ */
+import { expiryNoticeDue, EXPIRY_NOTICE_DAYS, tokenLive } from "./api-tokens.js";
+export const TOKEN_NOTICE_KIND = "api-token-expiry";
+export function tokenNoticePass(store, now) {
+    const ended = store.endRotatedApiTokens(now);
+    const sent = [];
+    const at = now.getTime();
+    for (const token of store.apiTokens(null)) {
+        const days = expiryNoticeDue(token, at);
+        if (days === null)
+            continue;
+        const key = (one) => `${TOKEN_NOTICE_KIND}:${token.id}:${one}`;
+        // A nearer notice already sent covers this one.
+        if (EXPIRY_NOTICE_DAYS.filter(one => one <= days).some(one => store.handle.prepare("SELECT 1 AS hit FROM notification WHERE dedupe_key = ?").get(key(one)) !== undefined))
+            continue;
+        const fresh = store.enqueueNotification({
+            dedupeKey: key(days), kind: TOKEN_NOTICE_KIND, pushClass: "attention", link: "/settings/sessions", recipient: token.account,
+            subject: `Your API token ${token.name} expires ${days === 1 ? "tomorrow" : `in ${days} days`}`,
+            body: `It stops working ${token.expiresAt.slice(0, 16).replace("T", " ")} UTC. Rotate it with toolroll tokens rotate, or make a new one in Settings → Sessions & tokens.`,
+            source: { installation: true },
+        }, now);
+        if (!fresh)
+            continue;
+        store.recordAction({ at: now.toISOString(), actor: "system", repo: null, taskId: null, runId: null, action: `API token expiry notice: ${token.name}`, outcome: "notified", source: "access",
+            detail: `${token.account}'s · id ${token.id} · ${days} day${days === 1 ? "" : "s"} left` });
+        sent.push({ token: token.id, days });
+    }
+    return { sent, ended };
+}
+/** Whether a token's console card warns that it expires soon (within the first notice's days). */
+export function expiresSoon(token, now) {
+    return expiryNoticeDue(token, now) !== null;
+}
+/** The loop beside the console: a pass a minute. */
+export function startTokenNotices(store, everyMs = 60_000) {
+    let stopped = false;
+    const tick = () => { if (stopped)
+        return; try {
+        tokenNoticePass(store, new Date());
+    }
+    catch { /* the next pass tries again */ } };
+    const timer = setInterval(tick, everyMs);
+    timer.unref?.();
+    const first = setTimeout(tick, 5_000);
+    first.unref?.();
+    return () => { stopped = true; clearInterval(timer); clearTimeout(first); };
+}

package/dist/tokens-cli.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from "./store.js";
+export declare const TOKENS_ACTIONS: readonly ["create", "list", "revoke", "rotate"];
+/** The most a piped password may be: a password, not a file. */
+export declare const PASSWORD_STDIN_BYTES = 4096;
+export type TokensCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    clock: () => Date;
+    /** Who runs this: a remote caller (an API token, over /api/cli or /mcp) and the lead never manage tokens. */
+    caller: "local" | "remote" | "lead";
+    /** The remembered local login's name only (never its password): the default for --as. */
+    rememberedName: string | null;
+    /** Whether someone is at this terminal to answer a prompt. */
+    interactive: () => boolean;
+    ask: (question: string) => Promise<string>;
+    askHidden: (question: string) => Promise<string>;
+    /** Standard input, read whole up to `limit` bytes; null past the limit. */
+    readStdin: (limit: number) => Promise<string | null>;
+};
+export declare function runTokensCommand(positional: readonly string[], flags: ReadonlyMap<string, string | true>, context: TokensCliContext): Promise<number>;

package/dist/tokens-cli.js

@@ -0,0 +1,184 @@
+/**
+ * `toolroll tokens create|list|revoke|rotate` (v111): a person's own API tokens, from the terminal of the machine that
+ * keeps the database. Every verb is a step-up: the person's own password, typed at a hidden prompt or piped with
+ * --password-stdin, never an argument, never the remembered login, a lead token or a remote caller's token. A new
+ * secret is written once, in the answer to create or rotate; nothing else ever shows it, and only its hash is kept.
+ */
+import { envelopeJson } from "./envelope.js";
+import { daysLeft, mintApiToken, ROTATION_OVERLAP_MAX_MINUTES, ROTATION_OVERLAP_MINUTES, TOKEN_DAYS, tokenLive, tokenRotationProblem, MCP_ROTATION_REFUSAL } from "./api-tokens.js";
+import { canonicalProject, projectName } from "./project.js";
+import { authenticateAccount } from "./scope.js";
+export const TOKENS_ACTIONS = ["create", "list", "revoke", "rotate"];
+/** The most a piped password may be: a password, not a file. */
+export const PASSWORD_STDIN_BYTES = 4096;
+/** Flags that would put a credential in argv. Refused by name, their values never echoed. */
+const SECRET_FLAGS = ["password", "token", "token-file", "token-env"];
+const EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
+export async function runTokensCommand(positional, flags, context) {
+    const { store, write, json } = context;
+    const action = positional[0];
+    const command = action === undefined ? "tokens" : `tokens ${action}`;
+    const fail = (reason, message, code = EXIT.refused) => { write(json ? envelopeJson({ ok: false, command, reason, message }) : message); return code; };
+    const succeed = (data, lines) => { write(json ? envelopeJson({ ok: true, command, ...data }) : lines.join("\n")); return EXIT.ok; };
+    const text = (name) => { const value = flags.get(name); return typeof value === "string" ? value : undefined; };
+    if (action === undefined || !TOKENS_ACTIONS.includes(action)) {
+        return fail("usage", `Use toolroll tokens ${TOKENS_ACTIONS.join("|")}.`, EXIT.usage);
+    }
+    if (context.caller === "remote")
+        return fail("remote-refused", "API tokens are managed in the console or on the server's own machine, never with a token.");
+    if (context.caller === "lead")
+        return fail("lead-refused", "The lead can't manage your API tokens. Run this yourself.");
+    const secretFlag = SECRET_FLAGS.find(name => flags.has(name));
+    if (secretFlag !== undefined)
+        return fail("usage", `--${secretFlag} isn't accepted here: type your password at the prompt, or pipe it with --password-stdin.`, EXIT.usage);
+    // Check the terms before asking for anything, so a typo never spends a password try.
+    const verb = action;
+    const terms = verb === "create" ? createTerms(flags) : null;
+    if (terms !== null && "problem" in terms)
+        return fail("usage", terms.problem, EXIT.usage);
+    const ref = positional[1]?.trim() ?? "";
+    if ((verb === "revoke" || verb === "rotate") && (ref === "" || positional.length > 2))
+        return fail("usage", `Use toolroll tokens ${verb} <name|id>.`, EXIT.usage);
+    if ((verb === "create" || verb === "list") && positional.length > 1)
+        return fail("usage", `toolroll tokens ${verb} takes no other words.`, EXIT.usage);
+    const overlap = verb === "rotate" ? overlapMinutes(text("overlap")) : null;
+    if (overlap !== null && typeof overlap === "string")
+        return fail("usage", overlap, EXIT.usage);
+    // Who, then their password: never the remembered login's password, never an argument.
+    let name = text("as")?.trim() ?? context.rememberedName ?? undefined;
+    const fromStdin = flags.has("password-stdin");
+    if (!fromStdin && (!context.interactive() || json))
+        return fail("usage", "Type your password at the prompt (run this in a terminal), or pipe it with --password-stdin.", EXIT.usage);
+    if (name === undefined || name === "") {
+        if (fromStdin || !context.interactive())
+            return fail("usage", "Say who you are with --as <your name>.", EXIT.usage);
+        name = (await context.ask("username: ")).trim();
+    }
+    let password;
+    if (fromStdin) {
+        const piped = await context.readStdin(PASSWORD_STDIN_BYTES);
+        password = piped === null ? null : piped.replace(/\r?\n$/, "");
+        if (password === null)
+            return fail("usage", "Pipe only your password into --password-stdin.", EXIT.usage);
+    }
+    else {
+        password = await context.askHidden("password: ");
+    }
+    if (name === "" || password === "")
+        return fail("unauthenticated", "Your name and password are needed.");
+    const signedIn = authenticateAccount(store, name, password);
+    password = null;
+    if (!signedIn.ok)
+        return fail(signedIn.reason === "locked" ? "locked" : "unauthenticated", signedIn.reason === "locked" ? "Too many wrong passwords: wait a while, then try again." : "That name and password don't match an account.");
+    const now = context.clock();
+    const mine = () => store.apiTokens(name);
+    if (verb === "list") {
+        const tokens = mine().filter(one => tokenLive(one, now.getTime())).map(one => listed(one, now));
+        return succeed({ tokens }, tokens.length === 0 ? ["You have no API tokens. Make one with toolroll tokens create."] : tokens.map(one => `${one.name} · ${one.id} · ${one.access === "act" ? "acts" : "reads"} · ${one.projects === null ? "all your projects" : one.projects.length === 0 ? "no projects" : one.projects.map(projectName).join(", ")} · ` +
+            `made ${one.createdAt.slice(0, 10)} · last used ${one.lastUsedAt === null ? "never" : one.lastUsedAt.slice(0, 10)} · ` +
+            (one.stopsAt !== null ? `replaced; stops ${one.stopsAt.slice(0, 16).replace("T", " ")} UTC` : `expires ${one.expiresAt.slice(0, 10)}${one.daysLeft <= 7 ? ` (in ${one.daysLeft} day${one.daysLeft === 1 ? "" : "s"})` : ""}`)));
+    }
+    if (verb === "create") {
+        const { tokenName, access, days, projectWords } = terms;
+        if (access === "act" && signedIn.role !== "approver")
+            return fail("viewer", "Your account can watch, not act, so its tokens can only read. Use --access read.");
+        const projects = projectWords === null ? null : resolveProjects(store, name, projectWords);
+        if (projects !== null && "problem" in projects)
+            return fail("unknown-project", projects.problem);
+        const minted = mintApiToken();
+        const expiresAt = new Date(now.getTime() + days * 86_400_000).toISOString();
+        store.createApiToken({ id: minted.id, account: name, name: tokenName, secretHash: minted.hash, access, expiresAt, by: name, projects: projects?.paths ?? null }, now);
+        const row = store.apiTokenSecret(minted.id).row;
+        return succeed({ token: minted.token, ...listed(row, now) }, shownOnce(row, minted.token));
+    }
+    const found = resolveToken(mine(), ref, now, verb === "rotate");
+    if ("problem" in found)
+        return fail(found.reason, found.problem);
+    if (verb === "revoke") {
+        store.revokeApiToken(found.row.id, name, now);
+        return succeed({ id: found.row.id, name: found.row.name }, [`Revoked ${found.row.name}. Anything using it stops working now.`]);
+    }
+    const rotationProblem = tokenRotationProblem(found.row);
+    if (rotationProblem !== null)
+        return fail("mcp-managed", rotationProblem);
+    const minted = mintApiToken();
+    const rotated = store.rotateApiToken(found.row.id, { id: minted.id, secretHash: minted.hash }, name, now, overlap * 60_000);
+    if (!rotated.ok && rotated.reason === "mcp-managed")
+        return fail("mcp-managed", MCP_ROTATION_REFUSAL);
+    if (!rotated.ok)
+        return fail(rotated.reason === "replaced" ? "replaced" : "not-found", rotated.reason === "replaced" ? "That token was already replaced. Rotate its replacement instead." : "No live token of yours has that name or id.");
+    const stops = store.apiTokenSecret(found.row.id).row.overlapUntil;
+    return succeed({ token: minted.token, replaced: { id: found.row.id, stopsAt: stops }, ...listed(rotated.row, now) }, [
+        ...shownOnce(rotated.row, minted.token),
+        `The old ${found.row.name} (${found.row.id}) keeps working until ${stops.slice(0, 16).replace("T", " ")} UTC, then stops.`,
+    ]);
+}
+function createTerms(flags) {
+    const text = (name) => { const value = flags.get(name); return typeof value === "string" ? value : undefined; };
+    const tokenName = (text("name") ?? "").trim().replace(/[\u0000-\u001f\u007f]+/g, " ");
+    if (tokenName === "" || tokenName.length > 60)
+        return { problem: "Name the token with --name, in 60 characters or fewer." };
+    const access = text("access");
+    if (access !== "read" && access !== "act")
+        return { problem: "Choose what it can do: --access read or --access act." };
+    const daysText = text("days");
+    const days = Number(daysText);
+    if (daysText === undefined || !TOKEN_DAYS.includes(days))
+        return { problem: `Choose when it expires: --days ${TOKEN_DAYS.join(", ")}.` };
+    const projectsText = text("projects");
+    const projectWords = projectsText === undefined ? null : projectsText.split(",").map(one => one.trim()).filter(one => one !== "");
+    if (projectWords !== null && projectWords.length === 0)
+        return { problem: "Name at least one project with --projects, or leave it out for all your projects." };
+    return { tokenName, access, days, projectWords };
+}
+function overlapMinutes(given) {
+    if (given === undefined)
+        return ROTATION_OVERLAP_MINUTES;
+    const minutes = Number(given);
+    return Number.isInteger(minutes) && minutes >= 0 && minutes <= ROTATION_OVERLAP_MAX_MINUTES ? minutes : `--overlap is whole minutes, 0 to ${ROTATION_OVERLAP_MAX_MINUTES}.`;
+}
+/** Each named project, by path or by its name, among the projects this person may use now. */
+function resolveProjects(store, account, words) {
+    const mine = [...new Set([...store.listProjects().map(one => one.path), ...store.knownRepos()])].filter(repo => store.accountCanAccess(account, repo));
+    const paths = [];
+    for (const word of words) {
+        const exact = mine.find(repo => repo === word || repo === canonicalProject(word));
+        const named = mine.filter(repo => projectName(repo) === word);
+        const path = exact ?? (named.length === 1 ? named[0] : undefined);
+        if (path === undefined)
+            return { problem: named.length > 1 ? `More than one of your projects is called ${word}: give its path.` : `${word} isn't one of your projects.` };
+        if (!paths.includes(path))
+            paths.push(path);
+    }
+    return { paths };
+}
+/** A token of this person's by exact id, else by a name only one of their current tokens has. */
+function resolveToken(tokens, ref, now, current) {
+    const live = tokens.filter(one => tokenLive(one, now.getTime()));
+    const byId = live.find(one => one.id === ref);
+    if (byId !== undefined) {
+        if (current && byId.replacedBy !== null)
+            return { reason: "replaced", problem: "That token was already replaced. Rotate its replacement instead." };
+        return { row: byId };
+    }
+    const named = live.filter(one => one.name === ref && one.replacedBy === null);
+    if (named.length > 1)
+        return { reason: "ambiguous", problem: `More than one of your tokens is called ${ref}: use its id (toolroll tokens list).` };
+    if (named.length === 0)
+        return { reason: "not-found", problem: "No live token of yours has that name or id." };
+    return { row: named[0] };
+}
+/** What may be shown about a token: everything but its secret, which is never kept. */
+function listed(row, now) {
+    return {
+        id: row.id, name: row.name, access: row.access, projects: row.projects, createdAt: row.createdAt, lastUsedAt: row.lastUsedAt, expiresAt: row.expiresAt,
+        daysLeft: daysLeft(row.expiresAt, now.getTime()), stopsAt: row.replacedBy === null ? null : row.overlapUntil,
+    };
+}
+function shownOnce(row, token) {
+    return [
+        `Your API token ${row.name}, shown once. Only a hash is kept, so copy it now:`,
+        `  ${token}`,
+        `It ${row.access === "act" ? "acts as you (never approves)" : "reads"} in ${row.projects === null ? "all your projects" : row.projects.map(projectName).join(", ")} until ${row.expiresAt.slice(0, 10)}.`,
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.45",
+  "version": "0.9.47",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"