@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.21

package/dist/scheduler/task-board.d.ts

@@ -0,0 +1,650 @@
+/**
+ * The task board: projects → main tasks (M-n) → sub tasks (S-n) on the fleet's `tasks` table, and the rules every
+ * write goes through — who may move what, the reasons a move needs, dependencies, the person's confirmation gate and
+ * optimistic versions — plus the comments, progress log and history each card keeps. Design:
+ * docs/design/task-board.md (ported from taskhall, 任務會所).
+ *
+ * Storage is additive: new columns on `tasks` (nullable or with defaults) and new tables. A release without the board
+ * still reads and writes the same rows — it ignores the new columns — and the startup backfill gives anything it
+ * created a card number, a kind and a place in the order again (see migrate()).
+ *
+ * Who acts is an {@link Actor}: the signed-in person on the dashboard, an instance through its tools, or the board
+ * itself (derived moves). Only a person confirms or rejects work waiting for review, clears "needs review", moves a
+ * card to another project, or reopens a finished card; an instance moves its own cards along.
+ */
+import type Database from "better-sqlite3";
+export declare const CARD_STATUSES: readonly ["open", "claimed", "blocked", "review", "done", "cancelled"];
+export type CardStatus = (typeof CARD_STATUSES)[number];
+/** Statuses still on the board (not finished). */
+export declare const LIVE_CARD_STATUSES: CardStatus[];
+export declare const CARD_PRIORITIES: readonly ["low", "normal", "high", "urgent"];
+export type CardPriority = (typeof CARD_PRIORITIES)[number];
+export declare const CARD_SIZES: readonly ["S", "M", "L"];
+export type CardSize = (typeof CARD_SIZES)[number];
+export type CardKind = "main" | "sub";
+/** `script`: a dashboard request on the header token (the CLI, a script) — held to the rules an instance is held to. */
+export interface Actor {
+    kind: "person" | "instance" | "script" | "system";
+    name: string;
+}
+export declare const SYSTEM_ACTOR: Actor;
+/** Field limits in characters (code points). Small on purpose: an agent reads the whole card. */
+export declare const CARD_LIMITS: {
+    readonly title: 100;
+    readonly goal: 300;
+    readonly scope: 600;
+    readonly acceptanceItems: 10;
+    readonly acceptanceText: 150;
+    readonly context: 1000;
+    readonly state: 500;
+    readonly stateLines: 5;
+    readonly blockedReason: 400;
+    readonly result: 1000;
+    readonly reason: 400;
+    readonly log: 300;
+    readonly comment: 4000;
+    readonly projectName: 60;
+    readonly projectDescription: 300;
+    readonly assignee: 128;
+};
+/**
+ * A refusal. `code` is its kind (and the HTTP status the dashboard gets); `key` and `args`, when set, name the same
+ * sentence for the dashboard to say in its own language (tasks.err.<key> with {0}, {1}… = args). Refusals only an
+ * instance can meet keep English only: they reach the instance, which reads the message.
+ */
+export declare class TaskBoardError extends Error {
+    readonly code: "not_found" | "invalid" | "too_long" | "forbidden" | "conflict" | "blocked_by_deps" | "needs_review" | "one_at_a_time";
+    readonly key?: string | undefined;
+    readonly args: Array<string | number>;
+    constructor(code: "not_found" | "invalid" | "too_long" | "forbidden" | "conflict" | "blocked_by_deps" | "needs_review" | "one_at_a_time", message: string, key?: string | undefined, args?: Array<string | number>);
+}
+/** A note after a write: English for the agents, a key and its values for the dashboard (tasks.note.<key>). */
+export interface Note {
+    text: string;
+    key: string;
+    args: Array<string | number>;
+}
+export interface Project {
+    id: number;
+    name: string;
+    description: string;
+    archived: boolean;
+    sort: number;
+    createdAt: string;
+}
+export interface AcceptanceItem {
+    text: string;
+    done: boolean;
+}
+/**
+ * Who handed a card out: the person who opened it on the dashboard, or the instance that opened it for another one (a
+ * coordinator such as a lead). A blocked card's question goes to an instance dispatcher first (step 2's wakes); it may
+ * answer it on the card and edit the card. Sub tasks take their main task's.
+ */
+export interface Dispatcher {
+    kind: "person" | "instance";
+    name: string;
+}
+/** What a write sets a dispatcher to: an instance by name, the person writing ({ kind: "person" }), or nobody. */
+export type DispatcherInput = {
+    kind: "instance";
+    name: string;
+} | {
+    kind: "person";
+} | null;
+/** A row as the rules see it: `uuid` is the key, `code` (M-3, S-34) the number people and agents use. */
+export interface Card {
+    uuid: string;
+    code: string;
+    kind: CardKind;
+    projectId: number | null;
+    /** Sub tasks: the main task's uuid. */
+    parent: string | null;
+    title: string;
+    status: CardStatus;
+    assignee: string | null;
+    dispatcher: Dispatcher | null;
+    priority: CardPriority;
+    size: CardSize | null;
+    needsReview: boolean;
+    /** uuids of the cards to finish first (what the fleet's `task` tool has always stored). */
+    deps: string[];
+    goal: string;
+    scope: string;
+    acceptance: AcceptanceItem[];
+    context: string;
+    state: string;
+    blockedReason: string;
+    result: string;
+    sort: number;
+    createdBy: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    submittedAt: string | null;
+    doneAt: string | null;
+    /** Highest entry id the assignee has acted after; later comments by others are new to it. */
+    seenEntryId: number;
+}
+export interface Progress {
+    total: number;
+    open: number;
+    claimed: number;
+    blocked: number;
+    review: number;
+    done: number;
+}
+/** A project's numbers on Home and in its header (projectStats). */
+export interface ProjectStats {
+    mains: number;
+    units: Progress;
+    percent: number;
+    waiting: number;
+    blocked: number;
+    lastActivity: string | null;
+}
+/** A card as the dashboard draws it: references by card number. */
+export interface CardView {
+    id: string;
+    uuid: string;
+    kind: CardKind;
+    projectId: number | null;
+    parentId: string | null;
+    title: string;
+    status: CardStatus;
+    assignee: string | null;
+    dispatcher: Dispatcher | null;
+    priority: CardPriority;
+    size: CardSize | null;
+    needsReview: boolean;
+    dependsOn: string[];
+    goal: string;
+    scope: string;
+    acceptance: AcceptanceItem[];
+    context: string;
+    state: string;
+    blockedReason: string;
+    result: string;
+    sort: number;
+    createdBy: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    submittedAt: string | null;
+    doneAt: string | null;
+    /** A main task's sub-task progress (total 0 when it has none); null for a sub task. */
+    progress: Progress | null;
+    unmetDeps: string[];
+    commentCount: number;
+    /** Comments by others its assignee has not acted on yet. */
+    newCommentCount: number;
+    lastComment: {
+        author: string;
+        authorKind: Actor["kind"];
+        at: string;
+    } | null;
+}
+export type EntryKind = "log" | "comment" | "reject" | "approve";
+export interface Entry {
+    id: number;
+    cardId: string;
+    kind: EntryKind;
+    author: string;
+    authorKind: Actor["kind"];
+    text: string;
+    at: string;
+}
+export type CardEventType = "created" | "updated" | "moved" | "assigned" | "commented" | "logged" | "reordered";
+export interface CardEvent {
+    id: number;
+    at: string;
+    actor: string;
+    actorKind: Actor["kind"];
+    cardId: string;
+    type: CardEventType;
+    data: Record<string, unknown>;
+}
+/**
+ * Why an instance hears about one of its cards (step 2's wakes, task-board-waker.ts): someone else assigned it,
+ * started it, sent it back, answered its blocked question, commented, or finished the last card it waited for; the
+ * person confirmed it (its assignee and its dispatcher hear); it is blocked and the instance handed it out (decide);
+ * a main task went to the person by itself before its owner wrapped it up (wrap_up); or someone else cancelled it — a
+ * main task's cancel takes its unfinished sub tasks down with it, and their assignees hear (cancelled).
+ */
+export type WakeReason = "assigned" | "start" | "sent_back" | "answered" | "comment" | "ready" | "decide" | "approved" | "wrap_up" | "cancelled";
+/** One card's news for one instance from one committed write. Never sent to a page (it carries titles and text). */
+export interface Wake {
+    instance: string;
+    uuid: string;
+    code: string;
+    title: string;
+    /** The main task's number, for a sub task. */
+    parent: string | null;
+    reasons: WakeReason[];
+    /** Who did each (the last one, when several did the same). */
+    by: Partial<Record<WakeReason, string>>;
+    /** The words that came with a reason: a send-back's, an answer's, a comment's, a question's, a confirmation note. */
+    texts: Partial<Record<WakeReason, string>>;
+}
+/** What one committed write changed, for live views: the card numbers touched (none for a project change). */
+export interface BoardChange {
+    /** The board's revision after this write (revision()). */
+    rev: number;
+    ids: string[];
+    actors: string[];
+    projects: boolean;
+    /** Whom to wake about what (the fleet's waker); a page is sent the rest. */
+    wakes: Wake[];
+}
+export interface CardDetail {
+    card: CardView;
+    parent: {
+        id: string;
+        title: string;
+        status: CardStatus;
+    } | null;
+    children: CardView[];
+    comments: Entry[];
+    logs: Entry[];
+    history: CardEvent[];
+}
+export interface NewCard {
+    /** Defaults to "sub" when a parent is given, else "main". */
+    kind?: CardKind;
+    /** Main tasks: a project id or name; none puts the card under "No project". */
+    project?: string | number | null;
+    /** Sub tasks: the main task's number, or "#n" for the n-th card of the same batch. */
+    parent?: string | null;
+    title: string;
+    goal?: string;
+    scope?: string;
+    acceptance?: string[];
+    context?: string;
+    size?: CardSize | null;
+    priority?: CardPriority;
+    /** Card numbers, or "#n" for the n-th card of the same batch. */
+    dependsOn?: string[];
+    assignee?: string | null;
+    /**
+     * Who handed it out. By default: the main task's for a sub task; else the person opening it on the dashboard, or the
+     * instance opening it for another one.
+     */
+    dispatcher?: DispatcherInput;
+    /** Defaults to true for a main task and false for a sub task. */
+    needsReview?: boolean;
+}
+export interface CardPatch {
+    version?: number;
+    title?: string;
+    goal?: string;
+    scope?: string;
+    context?: string;
+    state?: string;
+    result?: string;
+    blockedReason?: string;
+    size?: CardSize | null;
+    priority?: CardPriority;
+    assignee?: string | null;
+    dispatcher?: DispatcherInput;
+    needsReview?: boolean;
+    dependsOn?: string[];
+    acceptance?: string[];
+    addAcceptance?: string[];
+    check?: number[];
+    uncheck?: number[];
+    /** Main tasks only, a person only: move to another project (null: no project); sub tasks follow. */
+    projectId?: number | null;
+    log?: string;
+    comment?: string;
+}
+export interface MoveOptions {
+    reason?: string;
+    result?: string;
+    comment?: string;
+    version?: number;
+}
+export interface MutationResult {
+    card: Card;
+    /** English, for the agents. */
+    notes: string[];
+    /** The same notes for the dashboard to say in its own language. */
+    said: Note[];
+}
+export interface MyWork {
+    /** Cards it works on itself: sub tasks, and main tasks without sub tasks. */
+    doing: Card[];
+    blocked: Card[];
+    review: Card[];
+    ready: Card[];
+    /** Cards it could take but for their dependencies, with the card numbers they wait for. */
+    waiting: Array<{
+        card: Card;
+        waitsFor: string[];
+    }>;
+    newComments: Array<{
+        card: Card;
+        entries: Entry[];
+    }>;
+    sentBack: Array<{
+        card: Card;
+        entry: Entry;
+    }>;
+    /** Main tasks it coordinates (they have sub tasks). */
+    mains: Array<{
+        card: Card;
+        progress: Progress;
+    }>;
+}
+/**
+ * What a read leaves out: the comments, logs and send-backs of these authors (instances kept out of sight, over the
+ * public link — #2304 review). Their entries are not counted, named as a card's last comment, or found by search.
+ */
+export interface ReadScope {
+    leaveOutAuthors?: readonly string[];
+}
+export interface SearchHit {
+    card: Card;
+    /** Where the phrase was found, when not in the title. */
+    match: {
+        field: string;
+        text: string;
+    } | null;
+}
+/** "m3", "M - 3" → "M-3"; null when it is not a card number. */
+export declare function cardCode(raw: string): string | null;
+/** A card waits for the person's confirmation when it is finished. */
+export declare function requiresReview(card: Pick<Card, "needsReview">): boolean;
+/**
+ * What a finished card still lacks for the person's confirmation: unchecked acceptance items, no result. A main task
+ * goes to review by itself when its last sub task is done (often a reviewer's), before its owner wrapped it up.
+ */
+export declare function wrapUpGap(card: Pick<Card, "acceptance" | "result">): {
+    unchecked: number;
+    noResult: boolean;
+} | null;
+export declare class TaskBoard {
+    private readonly db;
+    private readonly now;
+    private listeners;
+    private cardLimit;
+    private pending;
+    private projectsChanged;
+    private notes;
+    /** The notes of the last write, until a caller of the `task` tool's old actions takes them (takeNotes). */
+    private lastNotes;
+    private codes;
+    constructor(db: Database.Database, now?: () => Date);
+    /** Called with what each committed write changed. Returns an unsubscribe function. */
+    onChange(listener: (change: BoardChange) => void): () => void;
+    /**
+     * Adds the board's columns and tables if missing, then backfills rows that have no card number yet (every task from
+     * before the board, and any a release without the board created since), drops comments and history whose task is
+     * gone, and lets main tasks catch up with their sub tasks. Safe to run on every open.
+     */
+    migrate(): void;
+    /**
+     * Main tasks whose sub tasks moved while nothing derived them (under a release without the board). Read first; the
+     * write lock only when one is out of step.
+     */
+    reconcile(): void;
+    /** The board's revision: it moves with every committed change, so a page reads the board again only when it moved. */
+    revision(): number;
+    listProjects(includeArchived?: boolean): Project[];
+    /** By id, or by name (case-insensitive). */
+    getProject(ref: string | number): Project;
+    createProject(actor: Actor, input: {
+        name: string;
+        description?: string;
+    }): Project;
+    updateProject(actor: Actor, id: number, patch: {
+        name?: string;
+        description?: string;
+        archived?: boolean;
+    }): Project;
+    private checkProjectName;
+    /** A new main task's project: the one asked for (not archived), or none. */
+    private projectForMain;
+    /** A card by number (M-3), uuid, or a unique uuid prefix of at least 8 hex digits. */
+    findCard(ref: string): Card | undefined;
+    getCard(ref: string): Card;
+    private byUuid;
+    /** A uuid's card number, for views and messages ("?" for one that is gone). */
+    codeOf(uuid: string): string;
+    children(uuid: string): Card[];
+    /** Sub tasks that still count (not cancelled). A main task with none is worked on directly. */
+    activeSubs(uuid: string): Card[];
+    progress(card: Card): Progress;
+    /**
+     * Dependencies that are not done (a cancelled one still holds its dependents, as the fleet's `task` tool always
+     * had it). A sub task also waits for its main task's. A dependency that no longer exists does not hold anything.
+     */
+    unmetDeps(card: Card): Card[];
+    /**
+     * What the board shows: live cards, and finished ones from the last `days` — done or cancelled main tasks, done sub
+     * tasks — or every done main task with `allDone` (the Done column's "All"). Older finished work stays in the
+     * database and in the projects' numbers (projectStats), not in every board read.
+     */
+    boardCards(days?: number, allDone?: boolean): Card[];
+    /**
+     * Each project's numbers (by id; "none" for No project) over all its cards, finished ones included: main tasks,
+     * work units (a main task's sub tasks, or one unit for a main task without them; a done main task counts all its
+     * units done), cards waiting for the person and blocked, and the last change. One pass over the table.
+     */
+    projectStats(): Record<string, ProjectStats>;
+    view(card: Card, scope?: ReadScope): CardView;
+    /** ` AND <column> NOT IN (…)` for a scope's left-out authors, with its values (empty when none). */
+    private notBy;
+    /**
+     * Many cards as the dashboard draws them, from one read of what they need — every task's number, status,
+     * dependencies and parent, sub-task counts, comment counts, the last comment and the unseen ones — instead of a few
+     * queries per card: a board read stays a handful of statements however many cards it has (it runs on the fleet's
+     * event loop). Same answers as progress(), unmetDeps() and newComments() card by card.
+     */
+    views(cards: Card[], scope?: ReadScope): CardView[];
+    detail(ref: string, scope?: ReadScope): CardDetail;
+    /** The latest `limit` entries of a card, oldest first. */
+    entries(uuid: string, kinds: EntryKind[], limit?: number): Entry[];
+    /** Comments and rejections by others that the assignee has not acted on yet. */
+    newComments(card: Card): Entry[];
+    events(uuid: string, limit?: number): CardEvent[];
+    private toEntry;
+    /**
+     * Cards matching a phrase in their number, title, text fields, checklist or comments; live cards first, newest
+     * first. `match` says where it matched when it is not the title.
+     */
+    search(query: string, limit?: number, scope?: ReadScope): SearchHit[];
+    private matchOf;
+    /**
+     * Cards by project (an id or name; null: No project), main task (its sub tasks), assignee and status (live ones by
+     * default), main tasks first, then by status and priority; at most `limit` (default 50), with how many matched.
+     */
+    listCards(filter: {
+        project?: string | number | null;
+        parent?: string;
+        assignee?: string;
+        status?: CardStatus[];
+        limit?: number;
+    }): {
+        cards: Card[];
+        total: number;
+    };
+    /** On the board's terms: in a project, a sub task, one with sub tasks, or one that waits for the person. */
+    isOnBoard(card: Card): boolean;
+    /**
+     * An instance's work, for `task mine`: what it is doing, what is blocked or waits for the person, what it can start
+     * (its own open cards, and the unassigned sub tasks of main tasks it coordinates, dependencies done) and what waits
+     * on dependencies; comments it has not seen and work sent back; the main tasks it coordinates and how far along.
+     */
+    myWork(name: string): MyWork;
+    createCards(actor: Actor, input: {
+        project?: string | number | null;
+        parent?: string | null;
+        cards: NewCard[];
+    }): {
+        cards: Card[];
+        notes: string[];
+        said: Note[];
+    };
+    updateCard(actor: Actor, ref: string, patch: CardPatch): MutationResult;
+    moveCard(actor: Actor, ref: string, to: CardStatus, options?: MoveOptions): MutationResult & {
+        from: CardStatus;
+    };
+    /**
+     * Place a card between two neighbours of its column (`after` comes right before it, `before` right after it).
+     * Order is presentation only, so the version does not change.
+     */
+    reorder(actor: Actor, ref: string, after: string | null, before: string | null): Card;
+    /**
+     * A task as the `task` tool has always opened it: a main task under no project, assigned only when asked, with no
+     * review gate unless a person later sets one. Dependencies are stored as given (ids are not checked).
+     */
+    legacyCreate(actor: Actor, params: {
+        title: string;
+        description?: string;
+        priority?: CardPriority;
+        assignee?: string;
+        depends_on?: string[];
+    }): Card;
+    /**
+     * Whether the board's rules hold for the `task` tool on this card: it is in a project, is a sub task, has sub tasks,
+     * or waits for the person. The tool's own tasks outside all of that keep the tool's old leniency (anyone may move
+     * them), and a person is never held to an instance's rules.
+     */
+    private heldToBoardRules;
+    /**
+     * `task claim`: an open task, every dependency done (a missing one counts as done). On the board, an instance claims
+     * as it would there: an unassigned card or its own, its main task's dependencies done too.
+     */
+    legacyClaim(actor: Actor, uuid: string, assignee: string): Card;
+    /**
+     * `task done`: from open or claimed. A card that needs the person's confirmation goes to review instead, so no
+     * instance can finish one alone. On the board, an instance finishes as it would there: its own card, with a result
+     * (an open one is claimed first, under the same rules).
+     */
+    legacyComplete(actor: Actor, uuid: string, result?: string): Card;
+    /**
+     * `task update`: status, assignee, result, priority. The review gate holds for everyone but a person: "done" on a
+     * card that needs confirmation becomes "review", and only a person takes a card out of review to done. On the
+     * board, an instance is held to the board's rules for each change (its own cards; moves as on the board).
+     */
+    legacyUpdate(actor: Actor, uuid: string, params: {
+        status?: CardStatus;
+        assignee?: string;
+        result?: string;
+        priority?: CardPriority;
+    }): Card;
+    /**
+     * Cards moved by hand: sub tasks, and main tasks that have no sub tasks. `comment` is the move's own comment (a
+     * dispatcher's answer); `finishing`: a claim on the way to done (the `task` tool's done of an open card).
+     */
+    private checkManualMove;
+    /**
+     * A main task with sub tasks follows them. By hand: block and unblock it, resubmit it after a rejection (its owner),
+     * and for a person approve, reject, reopen, cancel and restore it.
+     */
+    private checkDerivedMove;
+    /** What leaving "in progress" as finished (review or done) needs. */
+    private checkFinish;
+    private canEdit;
+    /** Its dispatcher answering a blocked card says what was decided: the assignee reads it. */
+    private checkAnswer;
+    /**
+     * An instance works on one card of the board at a time — or as many as its `board_cards_at_once` allows: starting
+     * another (claiming, resuming a blocked one, taking one back from review) at its limit is refused. Blocked cards,
+     * main tasks that follow their sub tasks and cards it opened for itself do not count; the `task` tool's own tasks and
+     * cards it opened for itself are not limited, nor is a person.
+     */
+    private checkOneAtATime;
+    /** The cards that keep `name` from starting `card` now: those it has in progress, once they reach its limit. */
+    private busyWith;
+    /** The fleet's `board_cards_at_once` for an instance: a whole number of at least 1, else 1. */
+    private limitOf;
+    /** For `mine`: the cards that count toward an instance's limit, when there are more than it allows (a person moved them). */
+    overLimit(name: string): {
+        count: number;
+        limit: number;
+    } | null;
+    /** How many handed-out cards each instance may have in progress (the fleet reads its config; default 1). */
+    setCardLimit(limit: (name: string) => number): void;
+    /** The board cards an instance works on itself right now (main tasks that follow their sub tasks aside). */
+    inProgress(name: string): Card[];
+    private personOnly;
+    /** Status bookkeeping shared by every move, then what the move sets off. */
+    private applyMove;
+    /**
+     * A main task with sub tasks follows them: open until something starts, in progress while they run, and when they
+     * are all done, review (or done, for one that skips the person's confirmation). Only a person moves it from review
+     * to done. A blocked or cancelled main task is left alone, and so is one without sub tasks (it is moved by hand).
+     */
+    /** What a main task's sub tasks make its status (its own, when it is blocked, cancelled or has none). */
+    private derivedStatus;
+    private deriveMain;
+    /** Cancelling a main task cancels its unfinished sub tasks (the event remembers where each was). */
+    private cancelSubs;
+    /** Restoring a main task brings back the sub tasks its cancellation took down, where they were. */
+    private restoreSubs;
+    /** `card` is done: the open cards that waited for it and wait for nothing else now can start. */
+    private noteUnblocked;
+    /** Every card's place again 1, 2, 3… in the same order (reorder() calls it when two neighbours touch). */
+    private renumber;
+    /** Several of the board's writes as one: all of them or none (the `task` tool's update with fields and a status). */
+    atomically<T>(fn: () => T): T;
+    /** This write's notes so far, both ways. */
+    private spoken;
+    /** A note of this write: English for agents, its key and values for the dashboard. */
+    private say;
+    /** The last write's notes (English), once: the `task` tool's old actions return them with their answer. */
+    takeNotes(): string[];
+    /**
+     * Whom this write wakes, read from its events once it is all written (still inside it): an instance hears only about
+     * what someone else did to a card that is its own — or that it handed out (a blocked question, a confirmation). The
+     * board's own catch-up wakes nobody, except that a card finishing — by hand or by itself — readies the cards that
+     * waited only for it. wakeHolds() then drops what no longer stands.
+     */
+    private settleWakes;
+    /** A finished card readies the open cards that waited only for it (a sub task also waits for its main task's). */
+    private wakeReady;
+    /**
+     * What of a wake still stands now (at the end of its write, and again when the fleet sends it): a finished card is
+     * news only as a confirmation; a card that is no longer the instance's is not; a question only while the card is
+     * blocked and the instance still handed it out; a wrap-up only while it waits unfinished; and an assignment or a
+     * comment only once the card can start (its "ready" wakes it then). What asks the instance to act holds only while
+     * it still can (#2303 review): "ready" while the card is open with nothing left to wait for, "start" and "answered"
+     * while it is in progress, "sent back" while it is back with the instance; a comment only while its assignee has not
+     * read it (its own write since showed it, as the `task` tool's answer). null when nothing is left.
+     */
+    wakeHolds(wake: Wake): Wake | null;
+    /**
+     * One write, all or nothing (BEGIN IMMEDIATE: the CLI and the fleet share this file). Listeners hear about it after
+     * it commits; a nested call joins the outer write.
+     */
+    private tx;
+    private nowIso;
+    private nextCode;
+    private nextSort;
+    /** A card number, uuid, or "#n" for the n-th card of the same batch → that card's uuid. */
+    private resolveRef;
+    /** A sub task's parent: a main task that is not cancelled. */
+    private resolveParent;
+    /** Valid, unique dependency uuids. Cycles are checked once the change is written (assertNoCycle). */
+    private checkDeps;
+    /** What a card waits on: its dependencies; a sub task also its main task's; a main task its sub tasks. */
+    private waitsOn;
+    /** Refuse a dependency loop reachable from `start`, counting the implicit main/sub waits. */
+    private assertNoCycle;
+    private checkVersion;
+    private assign;
+    /**
+     * Any write by the assignee counts as having seen the comments so far, so the unseen ones go in its reply first;
+     * otherwise a comment posted mid-task would be acknowledged without being read.
+     */
+    private surfaceComments;
+    private markSeen;
+    private entry;
+    private event;
+    private insert;
+    /** Empty text is stored as NULL in the columns the `task` tool has always had (description, result, depends_on). */
+    private save;
+}