toolroll 0.5.0

package/dist/mailbox.js

@@ -0,0 +1,150 @@
+/**
+ * Reading mail for Inbox triggers (v89).
+ *
+ * The mailbox is the same account emails are sent from (Settings → Email):
+ * a mail server's IMAP address with the same sign-in, or a connected Google
+ * account (IMAP with XOAUTH2). It is only ever read — opened read-only, and
+ * nothing is marked, moved or deleted — and only mail that arrives after a
+ * trigger is added becomes cards: the first check notes where the mailbox
+ * stands, and each later one reads what came after (by IMAP UID, restarting
+ * from "now" if the server renumbers the folder).
+ *
+ * Each message becomes plain words: the sender, the subject, and the body
+ * without the quoted history of earlier messages. Automatic replies (out of
+ * office, bounces) are left out, so a flow that answers mail can't end up
+ * answering machines. The card keeps the message's ID so a Send email step
+ * replying to the sender stays in the same thread.
+ */
+import { ImapFlow } from "imapflow";
+import { simpleParser } from "mailparser";
+import { googleAccessToken, googleConnected } from "./google-mail.js";
+import { readEmailSettings } from "./email-settings.js";
+const BODY_CHARS = 4000;
+const SOURCE_BYTES = 2 * 1024 * 1024;
+export function mailCursorOf(text) {
+    const match = text === null ? null : /^([0-9]{1,20}):([0-9]{1,12})$/.exec(text);
+    return match === null ? null : { validity: match[1], uid: Number(match[2]) };
+}
+export const mailCursorText = (at) => `${at.validity}:${at.uid}`;
+// ------------------------------------------------------------- the account
+/** Whether Inbox triggers can read mail: a connected Google account, or a mail server with its IMAP address. */
+export function mailboxReady(dir) {
+    return googleConnected(dir) !== null || (readEmailSettings(dir)?.imap ?? null) !== null;
+}
+/** The mailbox to read, signed in: Google when connected, else the mail server's IMAP. */
+export async function mailboxAccess(dir, fetcher) {
+    if (googleConnected(dir) !== null) {
+        const token = await googleAccessToken(dir, fetcher);
+        if (!token.ok)
+            return token;
+        return { ok: true, access: { host: "imap.gmail.com", port: 993, secure: true, user: token.address, accessToken: token.token }, address: token.address };
+    }
+    const server = readEmailSettings(dir);
+    if (server?.imap == null)
+        return { ok: false, said: "Reading mail isn't set up yet. Add the IMAP address in Settings → Email.", permanent: false };
+    return { ok: true, access: { host: server.imap.host, port: server.imap.port, secure: server.imap.secure, user: server.user || server.from, password: server.password }, address: server.from };
+}
+// ------------------------------------------------------------ the words
+/** The new part of a message: no quoted earlier messages, no signature, tidy lines. */
+export function freshText(text) {
+    const lines = text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").split("\n");
+    const kept = [];
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        // Where the history starts: "On <date>, <name> wrote:", an Outlook header block, or a forwarded-message marker.
+        if (/^On .{4,200} wrote:$/.test(trimmed) || /^-{2,}\s*(Original Message|Forwarded message)\s*-{2,}$/i.test(trimmed))
+            break;
+        if (/^From: .+$/.test(trimmed) && (lines[index + 1] ?? "").trim().match(/^(Sent|Date): /) !== null)
+            break;
+        // A signature: the "-- " line and everything after it.
+        if (line === "-- ")
+            break;
+        if (trimmed.startsWith(">"))
+            continue;
+        kept.push(line.trimEnd());
+    }
+    const joined = kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return joined.length > BODY_CHARS ? `${joined.slice(0, BODY_CHARS).trimEnd()}…` : joined;
+}
+const header = (headers, name) => {
+    const value = headers.get(name);
+    return typeof value === "string" ? value : value !== undefined && value !== null && typeof value === "object" && "value" in value ? String(value.value) : "";
+};
+/** One raw message as plain words, and whether a machine sent it. */
+export async function readMail(uid, source) {
+    const parsed = await simpleParser(source, { skipImageLinks: true, skipTextToHtml: true, skipTextLinks: true });
+    const sender = parsed.from?.value[0];
+    const from = (sender?.address ?? "").toLowerCase();
+    const headers = parsed.headers;
+    const auto = header(headers, "auto-submitted").toLowerCase();
+    const precedence = header(headers, "precedence").toLowerCase();
+    const automatic = (auto !== "" && auto !== "no") || headers.has("x-autoreply") || headers.has("x-autorespond") || precedence === "auto_reply"
+        || /^(mailer-daemon|postmaster)@/.test(from) || /multipart\/report/i.test(header(headers, "content-type"));
+    const references = (Array.isArray(parsed.references) ? parsed.references : typeof parsed.references === "string" ? parsed.references.split(/\s+/) : []).filter(one => /^<[^<>\s]{3,250}>$/.test(one)).slice(-20);
+    const replyTo = typeof parsed.inReplyTo === "string" ? /<[^<>\s]{3,250}>/.exec(parsed.inReplyTo)?.[0] ?? null : null;
+    return {
+        uid, messageId: typeof parsed.messageId === "string" && /^<[^<>\s]{3,250}>$/.test(parsed.messageId) ? parsed.messageId : null, inReplyTo: replyTo, references, from,
+        fromName: sender?.name && sender.name !== sender.address ? sender.name.slice(0, 120) : null,
+        subject: (parsed.subject ?? "").replace(/\s+/g, " ").trim().slice(0, 200), text: freshText(parsed.text ?? ""), automatic,
+    };
+}
+// ------------------------------------------------------------ the reader
+function problemOf(error) {
+    const code = String(error?.code ?? ""), text = String(error?.responseText ?? error?.message ?? "");
+    if (error?.authenticationFailed === true || /AUTHENTICATIONFAILED|Invalid credentials|LOGIN failed|authentication failed/i.test(text))
+        return { said: "The mail server didn't accept the sign-in. Check the username and password in Settings → Email (Gmail needs an app password).", permanent: false };
+    if (/NONEXISTENT|doesn't exist|Unknown Mailbox|no such mailbox/i.test(text))
+        return { said: "That folder doesn't exist in the mailbox.", permanent: false };
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return { said: "Couldn't find the mail server. Check its IMAP address in Settings → Email.", permanent: false };
+    if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ECONNRESET" || /timeout/i.test(text))
+        return { said: "Couldn't reach the mail server just now.", permanent: false };
+    return { said: `The mail server said: ${text.split("\n")[0]?.slice(0, 160) || "something went wrong"}.`, permanent: false };
+}
+/** The production reader: one read-only IMAP visit. */
+export const readThroughImap = async (access, folder, after, limit) => {
+    const client = new ImapFlow({
+        host: access.host, port: access.port, secure: access.secure, logger: false, disableAutoIdle: true,
+        auth: access.accessToken !== undefined ? { user: access.user, accessToken: access.accessToken } : { user: access.user, pass: access.password ?? "" },
+        connectionTimeout: 15_000, greetingTimeout: 15_000, socketTimeout: 60_000,
+        // A password never travels unencrypted: without TLS from the start, STARTTLS is required.
+        ...(access.secure ? {} : { doSTARTTLS: true }),
+    });
+    client.on("error", () => { });
+    try {
+        await client.connect();
+        const lock = await client.getMailboxLock(folder, { readOnly: true });
+        try {
+            const box = client.mailbox;
+            if (box === false)
+                return { ok: false, said: "That folder couldn't be opened.", permanent: false };
+            const validity = String(box.uidValidity), last = Math.max(0, Number(box.uidNext) - 1);
+            // The first look, or a renumbered folder: note where it stands, and start from there.
+            if (after === null || after.validity !== validity)
+                return { ok: true, at: { validity, uid: last }, mails: [], renumbered: after !== null, more: false };
+            if (last <= after.uid)
+                return { ok: true, at: after, mails: [], renumbered: false, more: false };
+            const found = await client.search({ uid: `${after.uid + 1}:*` }, { uid: true });
+            const waiting = (Array.isArray(found) ? found : []).filter(uid => uid > after.uid).sort((a, b) => a - b);
+            const uids = waiting.slice(0, limit);
+            const mails = [];
+            if (uids.length > 0) {
+                for await (const message of client.fetch(uids.join(","), { uid: true, source: { start: 0, maxLength: SOURCE_BYTES } }, { uid: true })) {
+                    if (message.source !== undefined)
+                        mails.push(await readMail(message.uid, message.source));
+                }
+            }
+            mails.sort((a, b) => a.uid - b.uid);
+            return { ok: true, at: { validity, uid: uids.at(-1) ?? after.uid }, mails, renumbered: false, more: waiting.length > uids.length };
+        }
+        finally {
+            lock.release();
+        }
+    }
+    catch (error) {
+        return { ok: false, ...problemOf(error) };
+    }
+    finally {
+        await client.logout().catch(() => client.close());
+    }
+};

package/dist/maintenance.d.ts

@@ -0,0 +1,11 @@
+/** Serialized background maintenance. It schedules no agent work: callers
+ * retain dispatch, ownership and recovery policy. Slow passes never overlap. */
+export declare function startMaintenance(args: {
+    intervalMs: number;
+    run: () => Promise<void>;
+    shouldStop: () => boolean;
+    onError: (error: unknown) => void;
+}): {
+    runNow: () => Promise<void>;
+    stop: () => Promise<void>;
+};

package/dist/maintenance.js

@@ -0,0 +1,35 @@
+/** Serialized background maintenance. It schedules no agent work: callers
+ * retain dispatch, ownership and recovery policy. Slow passes never overlap. */
+export function startMaintenance(args) {
+    if (!Number.isSafeInteger(args.intervalMs) || args.intervalMs < 1 || args.intervalMs > 2_147_483_647) {
+        throw new Error("maintenance interval must be an integer from 1 to 2147483647 milliseconds");
+    }
+    let stopped = false;
+    let pending = null;
+    const runNow = () => {
+        if (stopped || args.shouldStop())
+            return Promise.resolve();
+        if (pending !== null)
+            return pending;
+        pending = Promise.resolve().then(async () => {
+            if (!stopped && !args.shouldStop())
+                await args.run();
+        }).catch(error => {
+            try {
+                args.onError(error);
+            }
+            catch { /* Reporting cannot create an unhandled timer rejection. */ }
+        }).finally(() => { pending = null; });
+        return pending;
+    };
+    const timer = setInterval(() => { void runNow(); }, args.intervalMs);
+    timer.unref?.();
+    return {
+        runNow,
+        stop: async () => {
+            stopped = true;
+            clearInterval(timer);
+            await pending;
+        },
+    };
+}

package/dist/mate-cli.d.ts

@@ -0,0 +1,52 @@
+import type { MateProposal, Store } from "./store.js";
+import type { SubscriptionMateRunner } from "./subscription-chat.js";
+export type MateCliSeams = {
+    fetcher?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    /** Lines the REPL reads instead of stdin (tests). */
+    lines?: AsyncIterable<string> | Iterable<string>;
+    clock?: () => Date;
+    /** Subscription harness seam; tests never consume a real membership turn. */
+    subscriptionRunner?: SubscriptionMateRunner;
+};
+export type MateCliInput = {
+    store: Store;
+    databaseFile: string;
+    write: (line: string) => void;
+    json: boolean;
+    credentials: {
+        name: string;
+        token: string;
+    };
+    /** The ceiling: explicit `--repo` paths, or the enrolled projects when none are named. */
+    repos: readonly string[];
+    say: string | undefined;
+    end: boolean;
+    follow?: boolean;
+    ceilingUsd: number | undefined;
+    seams?: MateCliSeams;
+    /** Where evidence lives — a scout's report reads from here. */
+    evidenceRoot?: string;
+};
+export type MateCliResult = {
+    code: number;
+    reason?: string;
+    message?: string;
+};
+export declare const MATE_CLI_EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+    readonly refused: 3;
+};
+/**
+ * What a terminal must show before an answer is confirmed (v3 review,
+ * finding 4): the question, every option with its consequence, which one
+ * the builder recommends, which one is proposed — the card's content.
+ */
+export declare function answerContextLines(store: Store, payload: Record<string, unknown>): string[];
+/** One line per proposal, numbered in thread order, for the operator to name. */
+export declare function proposalLines(proposals: readonly MateProposal[], repos: readonly string[], ordinal?: (proposal: MateProposal) => number): string[];
+/** The lines for one proposal, its answer context included when it is an answer. */
+export declare function proposalBlock(store: Store, proposal: MateProposal, repos: readonly string[], number: number): string[];
+export declare function runMateCli(input: MateCliInput): Promise<MateCliResult>;

package/dist/mate-cli.js

@@ -0,0 +1,345 @@
+import { configureLeadFollow, leadFollowStatus } from './lead-follow.js';
+/**
+ * `toolroll chat` (mate arc §6): the same thread the console shows,
+ * driven from a terminal. The password is typed once — it mints the mate
+ * session, the one ceremony a conversation gets — and every later turn
+ * debits that session without asking again. Confirming a card runs the
+ * same doors the console runs; password-class acts (approving a scope,
+ * cancelling) print where to do them instead of doing them here.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CHAT_KEY_ENV, credentialKeyOf, isDirectChatProvider, priceForConfig, subscriptionCredentialKey } from "./converse.js";
+import { verifyApproverByPassword } from "./principal.js";
+import { runMateTurn } from "./mate.js";
+import { confirmMateProposal, dismissMateProposal } from "./mate-doors.js";
+import { projectName } from "./project.js";
+import { CHAT_CONTROLS, chatControlHref, isChatControl } from "./chat-controls.js";
+import { CHAT_TASK_ACTIONS, isChatTaskAction } from "./chat-task-actions.js";
+export const MATE_CLI_EXIT = { ok: 0, failed: 1, usage: 2, refused: 3 };
+function money(microusd) {
+    return `$${(microusd / 1_000_000).toFixed(2)}`;
+}
+function keyFor(config, databaseFile, env) {
+    const fromEnv = env[CHAT_KEY_ENV[config.provider]];
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv;
+    try {
+        const read = readFileSync(join(dirname(databaseFile), `chat-key-${config.provider}`), "utf8").trim();
+        return read === "" ? null : read;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What a terminal must show before an answer is confirmed (v3 review,
+ * finding 4): the question, every option with its consequence, which one
+ * the builder recommends, which one is proposed — the card's content.
+ */
+export function answerContextLines(store, payload) {
+    const id = typeof payload["decision"] === "number" ? payload["decision"] : null;
+    const decision = id === null ? null : store.getDecision(id);
+    if (decision === null)
+        return ["     (the decision is gone)"];
+    const pick = typeof payload["option"] === "string" ? payload["option"] : "";
+    return [
+        `     ${decision.question}${decision.state !== "open" ? ` [${decision.state}]` : ""}`,
+        ...decision.options.map(one => `     ${one.id === pick ? "→" : " "} ${one.label}${one.reversible ? "" : " (irreversible)"}${one.id === decision.recommendation ? " — the builder recommends this" : ""}: ${one.consequence}`),
+    ];
+}
+/** One line per proposal, numbered in thread order, for the operator to name. */
+export function proposalLines(proposals, repos, ordinal = (_p) => 0) {
+    return proposals.map((one, index) => {
+        const number = ordinal(one) || index + 1;
+        const payload = one.payload;
+        const t = (key) => (typeof payload[key] === "string" ? payload[key] : "");
+        const repoLabel = (() => {
+            const id = t("repoId");
+            const path = /^r[0-9]+$/.test(id) ? repos[Number(id.slice(1)) - 1] : undefined;
+            return path === undefined ? id : `${id} ${projectName(path)}`;
+        })();
+        const what = one.kind === "task_action"
+            ? `${isChatTaskAction(payload["operation"]) ? CHAT_TASK_ACTIONS[payload["operation"]].label : "Unavailable"}: ${t("taskTitle") || t("task")}${t("dependencyTitle") ? ` · ${t("dependencyTitle")}` : ""}`
+            : one.kind === "review"
+                ? `${t("operation") === "revise" ? "request a revision" : "save feedback"} for ${t("taskTitle") || t("task")}: ${t("note")}${Array.isArray(payload["notes"]) && payload["notes"].length > 0 ? ` (saved notes: ${payload["notes"].join(", ")})` : ""}`
+                : one.kind === "control"
+                    ? (isChatControl(payload["control"]) ? `${CHAT_CONTROLS[payload["control"]].label}: ${chatControlHref(payload["control"], t("task"), payload["run"], payload["project"])} (open in the console)` : "control unavailable")
+                    : one.kind === "steer" ? `guide ${t("task")}'s next attempt: ${t("note")}`
+                        : one.kind === "agents" ? `change agents for ${t("task")}: ${t("role")} ${t("provider")} ${t("model")} ${t("risk")}`
+                            : one.kind === "repair" ? `${t("operation")} dependency ${t("blocker")} for ${t("task")}`
+                                :
+                                    one.kind === "task"
+                                        ? `file "${t("title")}" in ${repoLabel}${payload["report"] === true ? " (a scout task — it delivers a report, never a branch)" : ""}`
+                                        : one.kind === "next"
+                                            ? `move ${t("task")} to the front (was ${String(payload["position"] ?? "?")} of ${String(payload["of"] ?? "?")})`
+                                            : one.kind === "reserve"
+                                                ? `${payload["worker"] === null ? `release ${t("task")} to the shared queue` : `reserve ${t("task")} for ${t("worker")}`}`
+                                                : one.kind === "hold"
+                                                    ? `hold ${t("task")}: ${t("reason")}`
+                                                    : one.kind === "unhold"
+                                                        ? `release ${t("task")} from its hold`
+                                                        : one.kind === "answer"
+                                                            ? `answer decision #${String(payload["decision"])} on ${t("task")} with "${t("optionLabel")}"${payload["reversible"] === false ? " (irreversible — confirm N yes)" : ""}: ${t("rationale")}`
+                                                            : one.kind === "scope"
+                                                                ? `rewrite the scope of ${t("task")} (then approve it: toolroll task approve ${t("task")})`
+                                                                : `cancel ${t("task")}: ${t("reason")} (arm it yourself: toolroll task cancel ${t("task")})`;
+        const state = one.state === "pending" ? "" : ` [${one.state}${one.outcome !== null && typeof one.outcome.said === "string" ? `: ${one.outcome.said}` : ""}]`;
+        return `  ${number}. ${what}${state}`;
+    });
+}
+/** The lines for one proposal, its answer context included when it is an answer. */
+export function proposalBlock(store, proposal, repos, number) {
+    const [line] = proposalLines([proposal], repos, () => number);
+    if (proposal.kind === "review") {
+        const snapshot = proposal.payload["snapshot"];
+        const selected = Array.isArray(proposal.payload["notes"]) ? proposal.payload["notes"] : [];
+        const notes = snapshot?.notes.filter(one => selected.includes(one.id)) ?? [];
+        return [line, ...notes.map(one => `     ${one.path === null ? "" : `${one.path}${one.line === null ? "" : `:${one.line}`}: `}${one.note}`),
+            proposal.payload["operation"] === "revise" ? "     Creates a revision of the same task; approval is separate." : "     Saves feedback; no work starts."];
+    }
+    return proposal.kind === "answer" ? [line, ...answerContextLines(store, proposal.payload)] : [line];
+}
+async function* linesOf(seams) {
+    if (seams?.lines !== undefined) {
+        for await (const line of seams.lines)
+            yield line;
+        return;
+    }
+    const { createInterface } = await import("node:readline");
+    const reader = createInterface({ input: process.stdin, terminal: false });
+    try {
+        for await (const line of reader)
+            yield line;
+    }
+    finally {
+        reader.close();
+    }
+}
+export async function runMateCli(input) {
+    const { store, write, json } = input;
+    const seams = input.seams ?? {};
+    const clock = seams.clock ?? (() => new Date());
+    const env = seams.env ?? process.env;
+    const say = (line) => {
+        if (!json)
+            write(line);
+    };
+    const emit = (envelope) => {
+        if (json)
+            write(JSON.stringify({ command: "chat", ...envelope }));
+    };
+    const refuse = (reason, message, code = MATE_CLI_EXIT.refused) => {
+        if (json)
+            write(JSON.stringify({ ok: false, command: "chat", reason, message }));
+        else
+            write(message);
+        return { code, reason, message };
+    };
+    if (store.isDemo())
+        return refuse("demo", "this is a demo database — chat cannot contact an external model");
+    const config = store.getChatConfig();
+    if (config === null)
+        return refuse("unconfigured", "chat is not configured — choose a membership or direct API provider with toolroll config set chat");
+    const directProvider = isDirectChatProvider(config.provider) ? config.provider : null;
+    const subscriptionProvider = directProvider === null ? config.provider : null;
+    const direct = directProvider !== null;
+    if (direct && priceForConfig(config) === null)
+        return refuse("unpriced", `no pinned price for ${config.model} — re-save the chat configuration`);
+    const key = direct ? keyFor(config, input.databaseFile, env) : null;
+    if (direct && key === null)
+        return refuse("no-key", `no ${directProvider} key — export ${CHAT_KEY_ENV[directProvider]}, or paste one on the console's chat page`);
+    const repos = [...input.repos];
+    if (repos.length === 0)
+        return refuse("empty-ceiling", "the mate needs projects to see — name them with --repo, or enroll some in the console", MATE_CLI_EXIT.usage);
+    const verified = verifyApproverByPassword(store, input.credentials.name, input.credentials.token, repos);
+    if (!verified.ok)
+        return refuse("unauthenticated", "that is not an approver, or the password does not match");
+    const who = verified.who;
+    let now = clock();
+    if (input.end) {
+        const turns = store.failLiveMateTurnsFor(who.name, "ended", now);
+        const sessions = store.endMateSessionsFor(who.name, who.name, now);
+        const threads = store.closeMateThreadsFor(who.name, now);
+        emit({ ok: true, ended: { sessions, threads, turns } });
+        say(sessions === 0 ? "no mate session was live; the thread is gone" : "the session is over and the thread is forgotten");
+        return { code: MATE_CLI_EXIT.ok };
+    }
+    store.sweepStaleMateTurns(now);
+    let session = store.activeMateSession(who.name);
+    const credentialKey = direct ? credentialKeyOf(directProvider, key) : subscriptionCredentialKey(subscriptionProvider);
+    if (session !== null && session.credentialKey !== credentialKey) {
+        // A session minted under another provider key cannot be spent by this
+        // one (slice-2 review, finding 9): say so, never loop on `not-yours`.
+        return refuse("key-mismatch", "the live mate session was minted under a different provider key — use that key, or end the session with --end and mint a new one");
+    }
+    if (session !== null && session.ceilingDigest !== who.ceilingDigest) {
+        store.endMateSession(session.id, who.name, now);
+        store.closeMateThreadsFor(who.name, now);
+        say("the projects named differ from the live session's — that session ended; minting a new one");
+        session = null;
+    }
+    if (session === null) {
+        const ceilingUsd = direct ? (input.ceilingUsd ?? 5) : 0;
+        if (direct && (!Number.isFinite(ceilingUsd) || ceilingUsd <= 0 || ceilingUsd > 1_000))
+            return refuse("usage", "--ceiling-usd is a dollar amount between 0 and 1000", MATE_CLI_EXIT.usage);
+        const ceilingMicrousd = Math.round(ceilingUsd * 1_000_000);
+        const termsDigest = createHash("sha256").update(`${ceilingMicrousd}\n${who.ceilingDigest}`).digest("hex");
+        const id = store.mintMateSession({ approver: who.name, approverGeneration: who.generation, credentialKey, ceilingMicrousd, ceilingDigest: who.ceilingDigest, termsDigest }, now);
+        session = store.getMateSession(id);
+        if (session === null)
+            return refuse("failed", "the session could not be minted", MATE_CLI_EXIT.failed);
+        if (!direct && input.ceilingUsd !== undefined)
+            say("the supplied --ceiling-usd value is ignored for membership usage");
+        say(`mate conversation started: ${direct ? `up to ${money(ceilingMicrousd)}` : "subscription usage (no dollar ceiling)"} over ${repos.map((one, index) => `r${index + 1} ${projectName(one)}`).join(", ")} — live until you end it`);
+        if (direct)
+            say(`(the weekly chat ceiling, ${money(config.weeklyCeilingMicrousd)}, still binds above it)`);
+    }
+    else {
+        say(`mate conversation live: ${direct ? `${money(session.spentMicrousd)} of ${money(session.ceilingMicrousd)} spent` : "subscription usage (no dollar ceiling)"} — live until you end it`);
+    }
+    const thread = store.openMateThread(who.name, who.ceilingDigest, now).thread;
+    if (input.follow !== undefined) {
+        if (!configureLeadFollow(store, who, session, thread, input.follow, now))
+            return refuse("standing", "Conversation access changed.");
+        say(leadFollowStatus(store, who.name).detail);
+        emit({ ok: true, follow: leadFollowStatus(store, who.name) });
+    }
+    const pendingProposals = () => store.listMateProposals(thread.id, ["pending"]);
+    // Ordinals are assigned once per proposal and never reused within this
+    // run (slice-2 review, finding 4): `confirm 2` means the card printed as
+    // 2, whatever the console did to its neighbours meanwhile.
+    const ordinals = new Map();
+    const ordinalOf = (proposal) => {
+        const known = ordinals.get(proposal.id);
+        if (known !== undefined)
+            return known;
+        const next = ordinals.size + 1;
+        ordinals.set(proposal.id, next);
+        return next;
+    };
+    const byOrdinal = (ordinal) => {
+        for (const [id, n] of ordinals)
+            if (n === ordinal)
+                return store.getMateProposal(id);
+        return null;
+    };
+    const printProposals = () => {
+        const rows = pendingProposals();
+        if (rows.length === 0)
+            return;
+        say("proposals — `confirm N`, `dismiss N`, `open N`:");
+        for (const row of rows)
+            ordinalOf(row);
+        for (const row of rows)
+            for (const line of proposalBlock(store, row, repos, ordinalOf(row)))
+                say(line);
+    };
+    const turn = async (message) => {
+        const live = store.activeMateSession(who.name);
+        if (live === null) {
+            const outcome = { ok: false, refused: "session-ended", message: "this mate session has ended — run chat again to mint one" };
+            return outcome;
+        }
+        return runMateTurn({ store, who, session: live, thread, config, key, message, ...(seams.fetcher === undefined ? {} : { fetcher: seams.fetcher }), ...(seams.subscriptionRunner === undefined ? {} : { subscriptionRunner: seams.subscriptionRunner }), ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }), clock });
+    };
+    const report = (outcome) => {
+        if (outcome.ok && outcome.replayed) {
+            emit(outcome);
+            say(`Message already received as turn #${outcome.turn}.`);
+            return;
+        }
+        if (outcome.ok) {
+            emit({ ok: true, turn: outcome.turn, reply: outcome.reply, activity: outcome.activity, steps: outcome.steps, settledMicrousd: outcome.settledMicrousd, proposals: pendingProposals().map(one => ({ id: one.id, ordinal: ordinalOf(one), kind: one.kind, payload: one.payload })) });
+            say(`  ${outcome.activity}`);
+            say(outcome.reply);
+            printProposals();
+            return;
+        }
+        emit({ ok: false, ...("refused" in outcome ? { reason: outcome.refused } : { turn: outcome.turn, reason: outcome.failed, unknownSpend: outcome.unknownSpend }), message: outcome.message });
+        say(outcome.message);
+    };
+    if (input.say !== undefined) {
+        const outcome = await turn(input.say);
+        report(outcome);
+        return { code: outcome.ok ? MATE_CLI_EXIT.ok : MATE_CLI_EXIT.refused };
+    }
+    // The REPL. Text is a turn; a few words are acts on the cards.
+    say("say something, or: proposals · confirm N · dismiss N · open N · end · quit");
+    const openTask = (proposal) => {
+        if (proposal.kind === "control" && isChatControl(proposal.payload["control"])) {
+            say(`Open in the console: ${chatControlHref(proposal.payload["control"], String(proposal.payload["task"] ?? ""), proposal.payload["run"], proposal.payload["project"])}`);
+            return;
+        }
+        const taskId = typeof proposal.payload["task"] === "string" ? proposal.payload["task"] : null;
+        if (taskId === null) {
+            say("that proposal names no task yet");
+            return;
+        }
+        const task = store.getTask(taskId);
+        const scope = store.getScope(taskId);
+        say(task === null ? `no task ${taskId}` : `${taskId} · ${task.title} · ${task.state}${scope === null ? "" : `\n  goal: ${scope.goal}${scope.outOfScope === null ? "" : `\n  not: ${scope.outOfScope}`}${scope.touches.length === 0 ? "" : `\n  touches: ${scope.touches.join(", ")}`}`}`);
+    };
+    for await (const raw of linesOf(seams)) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        now = clock();
+        const act = /^(confirm|dismiss|open)\s+([0-9]{1,3})(\s+yes)?$/i.exec(line);
+        if (act !== null) {
+            for (const row of pendingProposals())
+                ordinalOf(row);
+            const proposal = byOrdinal(Number(act[2]));
+            if (proposal === null) {
+                say(`no proposal ${act[2]}`);
+                continue;
+            }
+            if (proposal.state !== "pending" && act[1].toLowerCase() !== "open") {
+                say(`proposal ${act[2]} is ${proposal.state}${proposal.outcome !== null && typeof proposal.outcome.said === "string" ? `: ${proposal.outcome.said}` : ""}`);
+                continue;
+            }
+            const verb = act[1].toLowerCase();
+            if (verb === "open") {
+                openTask(proposal);
+            }
+            else if (verb === "dismiss") {
+                const done = dismissMateProposal(store, who, proposal.id, now);
+                emit({ ok: done, act: "dismiss", proposal: proposal.id });
+                say(done ? `dismissed ${act[2]}` : "that proposal was already acted on");
+            }
+            else {
+                const outcome = confirmMateProposal(store, who, proposal.id, now, { confirm: act[3] !== undefined, via: "cli", ...(input.evidenceRoot === undefined ? {} : { evidenceRoot: input.evidenceRoot }) });
+                emit({ ok: outcome.ok, act: "confirm", proposal: proposal.id, ...(outcome.ok ? { said: outcome.said, taskId: outcome.taskId } : { reason: outcome.reason, said: outcome.said }) });
+                say(outcome.ok ? outcome.said : outcome.reason === "needs-confirm" ? `${outcome.said}: confirm ${act[2]} yes` : `refused: ${outcome.said}`);
+                if (outcome.ok && outcome.kind === "scope" && outcome.taskId !== null)
+                    say(`approve it with your password: toolroll task approve ${outcome.taskId}`);
+            }
+            continue;
+        }
+        const word = line.toLowerCase();
+        if (word === "proposals") {
+            if (pendingProposals().length === 0)
+                say("no proposals are pending");
+            else
+                printProposals();
+            continue;
+        }
+        if (word === "quit" || word === "exit")
+            break;
+        if (word === "end") {
+            store.failLiveMateTurnsFor(who.name, "ended", now);
+            store.endMateSessionsFor(who.name, who.name, now);
+            store.closeMateThreadsFor(who.name, now);
+            say("the session is over and the thread is forgotten");
+            emit({ ok: true, ended: true });
+            return { code: MATE_CLI_EXIT.ok };
+        }
+        if (word === "help" || word === "?") {
+            say("say something, or: proposals · confirm N · dismiss N · open N · end · quit");
+            continue;
+        }
+        report(await turn(line));
+    }
+    return { code: MATE_CLI_EXIT.ok };
+}

package/dist/mate-contract.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The contract the mate reads (mate arc §4): plain words, versioned. It
+ * tells the model what the plane is, that every act is a proposal the
+ * operator confirms, the honesty and copy rules, when to ask instead of
+ * propose, and the shape of a good recap. Paths, consequences, and
+ * recommendations never reach the model — the tools already hide them —
+ * so the contract need not forbid repeating what it cannot see.
+ */
+export declare const MATE_CONTRACT_VERSION = 43;
+export declare const MATE_CONTRACT: string;