@songsid/agend 2.3.2-beta.9 → 2.3.3-beta.1

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

@@ -157,6 +157,10 @@ export interface ProjectStats {
 /** A card as the dashboard draws it: references by card number. */
 export interface CardView {
     id: string;
+    /** #2080: in review needing the person's confirmation, or blocked on a question theirs (waitsForPerson): Waiting for you. */
+    waitsForPerson: boolean;
+    /** #2080: the instance that confirms it in review (its dispatcher, else its assignee); null when the person does. */
+    confirmer: string | null;
     uuid: string;
     kind: CardKind;
     projectId: number | null;
@@ -218,13 +222,15 @@ export interface CardEvent {
 }
 /**
  * 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);
- * it went to the person for confirmation and the instance handed it out, so it tells them (to_confirm);
- * 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).
+ * started it, sent it back, answered its blocked question, or finished the last card it waited for; it is blocked and
+ * the instance handed it out (decide); it went to the person for confirmation and the instance handed it out, so it
+ * tells them (to_confirm); 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). #2801: only a change of status or assignee is news, and only to the one instance that acts on it
+ * next — a comment, and a confirmation (the work is finished), wake nobody; but for the answer to its blocked question
+ * that waits on the card while its assignee is busy with another (#2303), which it acts on next (answer_kept).
  */
-export type WakeReason = "assigned" | "start" | "sent_back" | "answered" | "comment" | "ready" | "decide" | "to_confirm" | "approved" | "wrap_up" | "cancelled";
+export type WakeReason = "assigned" | "start" | "sent_back" | "answered" | "answer_kept" | "ready" | "decide" | "to_confirm" | "confirm_own" | "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;
@@ -248,6 +254,8 @@ export interface BoardChange {
     projects: boolean;
     /** Whom to wake about what (the fleet's waker); a page is sent the rest. */
     wakes: Wake[];
+    /** #2801: the cards whose status or assignee this write changed (an older notice about them no longer stands). */
+    changed: string[];
 }
 export interface CardDetail {
     card: CardView;
@@ -371,6 +379,11 @@ export interface SearchHit {
 export declare const personConfirms: (card: Pick<Card, "dispatcher">) => boolean;
 /** Who that is, in words (an error, the card's text). */
 export declare function confirmerOf(card: Pick<Card, "dispatcher" | "assignee">): string;
+/**
+ * #2080: the instance that confirms a card in review (`confirms`' rule), or null when it is the person's — handed out by
+ * them, or by an instance deleted since (`gone`), or nobody's at all.
+ */
+export declare function confirmingInstance(card: Pick<Card, "dispatcher" | "assignee" | "createdBy">, gone?: GoneDispatcher): string | null;
 /** "m3", "M - 3" → "M-3"; null when it is not a card number. */
 export declare function cardCode(raw: string): string | null;
 /**
@@ -438,6 +451,8 @@ export declare class TaskBoard {
     private checkProjectName;
     /** A new main task's project: the one asked for (not archived), or none. */
     private projectForMain;
+    /** #2801: when the card's status or assignee last changed (ISO), or null — a notice older than that is stale. */
+    lastChangeAt(uuid: string): string | null;
     /** 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;
@@ -462,10 +477,11 @@ export declare class TaskBoard {
     /**
      * 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.
+     * units done), cards waiting for the person and blocked, and the last change. One pass over the table. #2080: waiting
+     * counts only the cards in review the person confirms (waitsForPerson, `gone` as for Needs you), never an agent's.
      */
-    projectStats(): Record<string, ProjectStats>;
-    view(card: Card, scope?: ReadScope): CardView;
+    projectStats(gone?: GoneDispatcher): Record<string, ProjectStats>;
+    view(card: Card, scope?: ReadScope, gone?: GoneDispatcher): CardView;
     /** ` AND <column> NOT IN (…)` for a scope's left-out authors, with its values (empty when none). */
     private notBy;
     /**
@@ -474,8 +490,13 @@ export declare class TaskBoard {
      * 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;
+    views(cards: Card[], scope?: ReadScope, gone?: GoneDispatcher): CardView[];
+    detail(ref: string, scope?: ReadScope, gone?: GoneDispatcher): CardDetail;
+    /**
+     * #2757 review: the instance dispatchers on the board that `gone` says are gone, as one string — what a cached read
+     * that names waitsForPerson / confirmer must also be keyed by (a dispatcher deleted changes them, the revision not).
+     */
+    goneDispatchers(gone?: GoneDispatcher): string;
     /** 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. */
@@ -615,6 +636,13 @@ export declare class TaskBoard {
         result?: string;
         priority?: CardPriority;
     }): Card;
+    /**
+     * #2080: review for an instance's own confirmation is done. An instance moving a card to review that it confirms itself
+     * (nobody else handed it out, or it handed it to itself) would wait for nobody but itself — and sat there unnoticed,
+     * in the person's Waiting for you too: it finishes instead (the checks for review are the ones for done). A person's
+     * move, and a card someone else confirms, stay as asked.
+     */
+    private ownReview;
     /**
      * 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).
@@ -688,12 +716,11 @@ export declare class TaskBoard {
     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.
+     * news only as a cancel; 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 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. null when nothing is left.
      */
     wakeHolds(wake: Wake): Wake | null;
     /**

package/dist/scheduler/task-board.js

@@ -120,6 +120,17 @@ export function confirmerOf(card) {
         return card.dispatcher.name;
     return card.assignee ?? "its assignee";
 }
+/**
+ * #2080: the instance that confirms a card in review (`confirms`' rule), or null when it is the person's — handed out by
+ * them, or by an instance deleted since (`gone`), or nobody's at all.
+ */
+export function confirmingInstance(card, gone) {
+    if (personConfirms(card) || orphaned(card, gone))
+        return null;
+    if (card.dispatcher?.kind === "instance")
+        return card.dispatcher.name;
+    return card.assignee ?? (card.createdBy || null);
+}
 function normalizeAssignee(raw) {
     const v = raw?.trim() ?? "";
     if (v === "" || v.toLowerCase() === "none")
@@ -436,6 +447,11 @@ export class TaskBoard {
         return project.id;
     }
     // ── Reading ─────────────────────────────────────────────
+    /** #2801: when the card's status or assignee last changed (ISO), or null — a notice older than that is stale. */
+    lastChangeAt(uuid) {
+        const r = this.db.prepare("SELECT MAX(at) AS at FROM task_events WHERE task_id = ? AND type IN ('created', 'moved', 'assigned')").get(uuid);
+        return r?.at ?? null;
+    }
     /** A card by number (M-3), uuid, or a unique uuid prefix of at least 8 hex digits. */
     findCard(ref) {
         const text = (ref ?? "").trim();
@@ -518,10 +534,11 @@ export class TaskBoard {
     /**
      * 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.
+     * units done), cards waiting for the person and blocked, and the last change. One pass over the table. #2080: waiting
+     * counts only the cards in review the person confirms (waitsForPerson, `gone` as for Needs you), never an agent's.
      */
-    projectStats() {
-        const rows = this.db.prepare("SELECT id, kind, status, project_id, parent_id, updated_at FROM tasks").all();
+    projectStats(gone) {
+        const rows = this.db.prepare("SELECT id, kind, status, project_id, parent_id, updated_at, needs_review, dispatcher, dispatcher_kind FROM tasks").all();
         const subs = new Map();
         for (const r of rows) {
             if (r.kind !== "sub" || !r.parent_id || r.status === "cancelled")
@@ -540,7 +557,8 @@ export class TaskBoard {
             const status = r.status;
             if (status === "cancelled")
                 continue;
-            if (status === "review")
+            if (status === "review" && waitsForPerson({ status, needsReview: Number(r.needs_review) === 1,
+                dispatcher: r.dispatcher ? { kind: r.dispatcher_kind === "person" ? "person" : "instance", name: r.dispatcher } : null }, gone))
                 st.waiting++;
             if (status === "blocked")
                 st.blocked++;
@@ -565,8 +583,8 @@ export class TaskBoard {
             st.percent = st.units.total ? Math.round((st.units.done / st.units.total) * 100) : 0;
         return out;
     }
-    view(card, scope = {}) {
-        return this.views([card], scope)[0];
+    view(card, scope = {}, gone) {
+        return this.views([card], scope, gone)[0];
     }
     /** ` AND <column> NOT IN (…)` for a scope's left-out authors, with its values (empty when none). */
     notBy(scope, column) {
@@ -579,7 +597,7 @@ export class TaskBoard {
      * 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, scope = {}) {
+    views(cards, scope = {}, gone) {
         if (!cards.length)
             return [];
         const all = new Map();
@@ -618,6 +636,8 @@ export class TaskBoard {
             const c = comments.get(card.uuid);
             return {
                 id: card.code,
+                waitsForPerson: waitsForPerson(card, gone),
+                confirmer: confirmingInstance(card, gone),
                 uuid: card.uuid,
                 kind: card.kind,
                 projectId: card.projectId,
@@ -653,18 +673,28 @@ export class TaskBoard {
             };
         });
     }
-    detail(ref, scope = {}) {
+    detail(ref, scope = {}, gone) {
         const card = this.getCard(ref);
         const parent = card.parent ? this.byUuid(card.parent) : undefined;
         return {
-            card: this.view(card, scope),
+            card: this.view(card, scope, gone),
             parent: parent ? { id: parent.code, title: parent.title, status: parent.status } : null,
-            children: this.views(this.children(card.uuid), scope),
+            children: this.views(this.children(card.uuid), scope, gone),
             comments: this.entries(card.uuid, ["comment", "reject", "approve"], 200),
             logs: this.entries(card.uuid, ["log"], 200),
             history: this.events(card.uuid, 200).filter((e) => e.type !== "reordered"),
         };
     }
+    /**
+     * #2757 review: the instance dispatchers on the board that `gone` says are gone, as one string — what a cached read
+     * that names waitsForPerson / confirmer must also be keyed by (a dispatcher deleted changes them, the revision not).
+     */
+    goneDispatchers(gone) {
+        if (!gone)
+            return "";
+        const rows = this.db.prepare("SELECT DISTINCT dispatcher FROM tasks WHERE dispatcher IS NOT NULL AND (dispatcher_kind IS NULL OR dispatcher_kind != 'person')").all();
+        return rows.map((r) => r.dispatcher).filter((n) => gone(n)).sort().join("\u0000");
+    }
     /** The latest `limit` entries of a card, oldest first. */
     entries(uuid, kinds, limit = 20) {
         const rows = this.db.prepare(`SELECT * FROM task_entries WHERE task_id = ? AND kind IN (${kinds.map(() => "?").join(", ")}) ORDER BY id DESC LIMIT ?`)
@@ -1236,7 +1266,8 @@ export class TaskBoard {
                 if (busy.length) {
                     const text = checkText("the comment", comment, CARD_LIMITS.comment);
                     this.entry(card, "comment", actor, text);
-                    this.event(actor, card, "commented", { text });
+                    // #2801 review: the one comment that is news — the answer its assignee waits for (`kept`).
+                    this.event(actor, card, "commented", { text, kept: true });
                     card.version++;
                     card.updatedAt = this.nowIso();
                     this.save(card);
@@ -1249,7 +1280,7 @@ export class TaskBoard {
                 this.checkDerivedMove(card, actor, to, reason, { comment });
             else
                 this.checkManualMove(card, actor, to, reason, { comment });
-            this.applyMove(card, actor, to, reason, comment);
+            this.applyMove(card, actor, this.ownReview(card, actor, to, reason), reason, comment);
             return { card, from, ...this.spoken() };
         });
     }
@@ -1429,6 +1460,8 @@ export class TaskBoard {
                         if (held && to !== card.status)
                             this.checkManualMove(card, actor, to, "");
                     }
+                    // #2757 review: a derived main task too; a card off the board (not held) keeps the tool's old, unchecked finish.
+                    to = this.ownReview(card, actor, to, "", held);
                 }
                 if (to !== card.status) {
                     this.applyMove(card, actor, to, "");
@@ -1447,6 +1480,21 @@ export class TaskBoard {
         });
     }
     // ── Rules ───────────────────────────────────────────────
+    /**
+     * #2080: review for an instance's own confirmation is done. An instance moving a card to review that it confirms itself
+     * (nobody else handed it out, or it handed it to itself) would wait for nobody but itself — and sat there unnoticed,
+     * in the person's Waiting for you too: it finishes instead (the checks for review are the ones for done). A person's
+     * move, and a card someone else confirms, stay as asked.
+     */
+    ownReview(card, actor, to, reason = "", check = true) {
+        if (to !== "review" || isPerson(actor) || card.status === "review" || !confirms(card, actor))
+            return to;
+        // #2757 review: finished as done is, whichever way it came (a derived main task's review checks less).
+        if (check)
+            this.checkFinish(card, true, reason);
+        this.say("own_review", [card.code], `${card.code} waits for nobody else's confirmation (you confirm it): done, not review`);
+        return "done";
+    }
     /**
      * 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).
@@ -1628,6 +1676,13 @@ export class TaskBoard {
             return;
         }
         if (ai) {
+            // #2080: a main task in review by itself (its sub tasks done) is finished by the instance that confirms it.
+            if (from === "review" && to === "done" && confirms(card, actor)) {
+                if (reason)
+                    this.entry(card, "approve", actor, reason);
+                this.checkFinish(card, ai, reason);
+                return;
+            }
             if (from === "claimed" && to === "review") {
                 if (!own)
                     throw notOwner();
@@ -1886,10 +1941,16 @@ export class TaskBoard {
             w.by[reason] = by.name;
             out.set(key, w);
         };
+        // The answer to a blocked question is the comment that came with it (#2801: a comment alone wakes nobody).
         const comments = new Map();
         for (const e of events)
             if (e.type === "commented")
                 comments.set(e.uuid, String(e.data.text ?? ""));
+        for (const e of events) {
+            const card = e.type === "commented" && e.data.kept === true ? this.byUuid(e.uuid) : undefined;
+            if (card)
+                add(card, card.assignee, "answer_kept", e.actor, String(e.data.text ?? ""));
+        }
         for (const e of events) {
             const card = this.byUuid(e.uuid);
             if (!card)
@@ -1905,8 +1966,6 @@ export class TaskBoard {
                 if (this.isOnBoard(card))
                     add(card, d.to ?? null, "assigned", e.actor);
             }
-            else if (e.type === "commented")
-                add(card, card.assignee, "comment", e.actor, d.text);
             else if (e.type === "moved") {
                 if (d.to === "done")
                     this.wakeReady(card, e.actor, add);
@@ -1919,10 +1978,16 @@ export class TaskBoard {
                 }
                 // An agent's card waits for its instance dispatcher to confirm it (#2434: its own to confirm, nobody to ask). A
                 // person's card has no instance dispatcher, so no notice: the person has it in Needs you.
-                if (d.to === "review" && !isPerson(e.actor) && requiresReview(card))
-                    add(card, dispatcherOf(), "to_confirm", e.actor);
+                const toConfirm = d.to === "review" && !isPerson(e.actor) && requiresReview(card) ? dispatcherOf() : null;
+                if (toConfirm)
+                    add(card, toConfirm, "to_confirm", e.actor);
+                // #2080: a card its own assignee confirms, in review by itself (its sub tasks done) or by someone else's move:
+                // nobody else will confirm it, so its assignee is told it is theirs.
+                if (d.to === "review" && card.assignee && confirmingInstance(card) === card.assignee)
+                    add(card, card.assignee, "confirm_own", e.actor);
                 if (d.auto) {
-                    if (d.to === "review" && card.kind === "main" && wrapUpGap(card))
+                    // #2801: one change, one instance — the dispatcher's confirmation already says what it lacks.
+                    if (d.to === "review" && card.kind === "main" && wrapUpGap(card) && !toConfirm)
                         add(card, card.assignee, "wrap_up", e.actor);
                     continue;
                 }
@@ -1932,10 +1997,6 @@ export class TaskBoard {
                     add(card, card.assignee, "answered", e.actor, comments.get(card.uuid));
                 else if (d.from === "review" && (d.to === "claimed" || d.to === "open"))
                     add(card, card.assignee, "sent_back", e.actor, d.reason);
-                else if (d.from === "review" && d.to === "done") {
-                    add(card, card.assignee, "approved", e.actor, d.reason);
-                    add(card, dispatcherOf(), "approved", e.actor, d.reason);
-                }
                 if (d.to === "blocked" && !isPerson(e.actor))
                     add(card, dispatcherOf(), "decide", e.actor, d.reason);
             }
@@ -1952,12 +2013,11 @@ export class TaskBoard {
     }
     /**
      * 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.
+     * news only as a cancel; 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 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. null when nothing is left.
      */
     wakeHolds(wake) {
         const card = this.byUuid(wake.uuid);
@@ -1967,8 +2027,6 @@ export class TaskBoard {
         const own = card.assignee === wake.instance;
         const waiting = this.unmetDeps(card).length > 0;
         let reasons = wake.reasons.filter((r) => {
-            if (r === "approved")
-                return card.status === "done" && (own || handedOut);
             if (r === "cancelled")
                 return card.status === "cancelled" && own;
             if (isFinished(card))
@@ -1980,25 +2038,25 @@ export class TaskBoard {
                 return handedOut && card.status === "review" && requiresReview(card);
             if (!own)
                 return false;
+            if (r === "confirm_own")
+                return card.status === "review" && confirmingInstance(card) === wake.instance;
             if (r === "wrap_up")
                 return card.status === "review" && wrapUpGap(card) !== null;
             if (r === "assigned")
                 return !waiting;
-            if (r === "comment")
-                return !waiting && this.newComments(card).length > 0;
             if (r === "ready")
                 return card.status === "open" && !waiting;
             if (r === "start" || r === "answered")
                 return card.status === "claimed";
+            if (r === "answer_kept")
+                return card.status === "blocked";
             if (r === "sent_back")
                 return card.status === "claimed" || card.status === "open";
             return true;
         });
-        // One piece of news says it all: the answer is the comment, a send-back outweighs the rest.
-        if (reasons.includes("answered"))
-            reasons = reasons.filter((r) => r !== "comment");
+        // One piece of news says it all: a send-back outweighs the rest.
         if (reasons.includes("sent_back"))
-            reasons = reasons.filter((r) => r !== "comment" && r !== "start");
+            reasons = reasons.filter((r) => r !== "start");
         if (reasons.includes("assigned"))
             reasons = reasons.filter((r) => r !== "start" && r !== "ready");
         if (reasons.includes("cancelled"))
@@ -2032,7 +2090,8 @@ export class TaskBoard {
             const touched = this.pending;
             const projects = this.projectsChanged;
             if (touched.length || projects) {
-                const change = { rev: this.revision(), ids: [...new Set(touched.map((e) => e.code))], actors: [...new Set(touched.map((e) => e.actor.name))], projects, wakes };
+                const changed = [...new Set(touched.filter((e) => e.type === "moved" || e.type === "assigned").map((e) => e.uuid))];
+                const change = { rev: this.revision(), ids: [...new Set(touched.map((e) => e.code))], actors: [...new Set(touched.map((e) => e.actor.name))], projects, wakes, changed };
                 for (const listener of this.listeners) {
                     try {
                         listener(change);