@wrongstack/tools 0.302.2 → 0.305.0

package/dist/session-kanban.d.ts

@@ -3,20 +3,58 @@ import { type PlanFile, type PlanItem, type TaskFile } from '@wrongstack/core/st
 import type { SerializedTaskGraph } from '@wrongstack/core/types';
 import { type TaskItem } from '@wrongstack/core/utils';
 import { type KanbanBoard, type KanbanColumn, type KanbanTask } from '@wrongstack/kanban';
-/** The canonical workflow shared by WebUI and TUI session boards. */
+/**
+ * The canonical workflow shared by WebUI and TUI session boards.
+ *
+ * Session boards now use the same 5 standard columns as every other board
+ * (backlog, todo, in-progress, review, done). Formerly this shipped a 4-column
+ * variant without a backlog; the column lock unified the layout. Existing
+ * 4-column session_mirror boards are migrated automatically on the next session
+ * touch: `ensureSessionKanbanBoard`'s `sameColumns` check detects the drift
+ * and `updateBoard` reconciles to DEFAULT_COLUMNS.
+ */
 export declare const SESSION_KANBAN_COLUMNS: KanbanColumn[];
 /** Create (or migrate) the single Kanban board owned by a session. */
 export declare function ensureSessionKanbanBoard(projectRoot: string | undefined, sessionId: string): Promise<KanbanBoard | null>;
+/**
+ * Remove an inactive session's observational mirror, including its cards.
+ * The durable source remains the session todo/task/plan files; retaining the
+ * mirror after detach only creates historical duplicate work in project views.
+ */
+export declare function cleanupSessionKanbanBoard(projectRoot: string | undefined, sessionId: string): Promise<string[]>;
 /** Remove a particular inactive session's system-owned board when it has no cards. */
 export declare function cleanupSessionKanbanBoardIfEmpty(projectRoot: string | undefined, sessionId: string): Promise<string[]>;
 /** Prune stale empty session boards while preserving manual and live boards. */
 export declare function cleanupEmptySessionKanbanBoards(projectRoot: string | undefined, activeSessionId?: string): Promise<string[]>;
+/**
+ * Consume the last unreported mirror failure for a session, if any.
+ *
+ * The mirror is asynchronous and fire-and-forget, so a rejected projection
+ * used to be observable only in stdout. The `todo` tool drains this on its
+ * next call and reports it as a warning, so a board that stopped tracking the
+ * session is surfaced where the divergence actually matters.
+ */
+export declare function takeSessionMirrorFailure(projectRoot: string | undefined, sessionId: string): string | undefined;
 export declare function todoListToSerializedGraph(todos: readonly TodoItem[], sessionId: string): SerializedTaskGraph;
 export declare function taskFileToSerializedGraph(tasks: readonly TaskItem[], sessionId: string): SerializedTaskGraph;
 export declare function planFileToSerializedGraph(items: readonly PlanItem[], sessionId: string): SerializedTaskGraph;
 export declare function projectSessionTodosToKanban(projectRoot: string | undefined, todos: readonly TodoItem[], sessionId: string): Promise<KanbanBoard | null>;
 export declare function projectSessionTasksToKanban(projectRoot: string | undefined, tasks: readonly TaskItem[], sessionId: string): Promise<KanbanBoard | null>;
 export declare function projectSessionPlanToKanban(projectRoot: string | undefined, items: readonly PlanItem[], sessionId: string): Promise<KanbanBoard | null>;
+/**
+ * The todo rows that still need the session mirror: those not already cards on
+ * the board this session is working on.
+ *
+ * The rule used to be all-or-nothing — the mirror was skipped only when EVERY
+ * row was bound. A single unbound row (a todo the model added to the chat list
+ * without also filing a card) sent the whole list to a separate session board,
+ * so work already tracked on the real board showed up a second time there, and
+ * one stray row was enough to leave a session board holding a single card.
+ *
+ * With no active board every row still needs mirroring, since there is no other
+ * place the work is being recorded.
+ */
+export declare function todosNeedingSessionMirror(todos: readonly TodoItem[], activeBoardId: string | undefined): readonly TodoItem[];
 export declare function mirrorSessionTodosToKanban(projectRoot: string | undefined, todos: readonly TodoItem[], sessionId: string): void;
 export declare function mirrorSessionTasksToKanban(projectRoot: string | undefined, tasks: readonly TaskItem[], sessionId: string): void;
 export declare function mirrorSessionPlanToKanban(projectRoot: string | undefined, items: readonly PlanItem[], sessionId: string): void;
@@ -27,6 +65,38 @@ export declare function mirrorSessionPlanToKanban(projectRoot: string | undefine
  */
 export declare function attachSessionKanbanMirror(context: Context): () => void;
 /** Fully hydrate a session board before a host announces the session as ready. */
+/**
+ * Re-bind the card this session was working, after a restart or `--resume`.
+ *
+ * The binding produced by `start_task` lives in `ctx.meta.kanban`, which is
+ * conversation state — nothing restores it. So a resumed session came back
+ * with `currentKanbanTaskId` undefined while its card still sat in Running on
+ * the board: file events lost their task attribution, and under
+ * `tools.kanbanGovernance` the run was un-bound until the model happened to
+ * call `start_task` again.
+ *
+ * Board presence is the durable anchor. It is keyed `<sessionId>:<agentId>`,
+ * carries the `taskId`, and is stored on the board record itself, so it
+ * survives the restart even though its derived `active` flag does not (the TTL
+ * is two minutes). Matching it against the cards that are actually still
+ * running gives an unambiguous answer without guessing from free-text agent
+ * ids.
+ *
+ * Deliberately conservative — it prefers to do nothing over binding the wrong
+ * card:
+ * - never overrides a binding this process already has;
+ * - only considers cards whose assignment is still `running`;
+ * - skips an expired lease, because `recover_stale` may have reassigned that
+ *   card to another worker;
+ * - picks the most recently seen entry when a session touched several.
+ *
+ * Session mirrors and archived boards are excluded by the snapshot's default
+ * board-kind filter, which is correct: `start_task` never targets them.
+ */
+export declare function rebindSessionKanbanTask(context: Context): Promise<{
+    boardId: string;
+    taskId: string;
+} | null>;
 export declare function hydrateSessionKanban(context: Context): Promise<KanbanBoard | null>;
 export interface SessionKanbanSourceUpdate {
     source: 'todo' | 'task' | 'plan' | null;
@@ -34,6 +104,27 @@ export interface SessionKanbanSourceUpdate {
     tasks?: TaskFile | undefined;
     plan?: PlanFile | undefined;
 }
+/**
+ * Human-readable titles of the unfinished dependencies blocking a card.
+ *
+ * The board recomputes readiness on every mutation; this only carries the
+ * result to the todo surface. Titles rather than ids, because the row is read
+ * by a model and a human, neither of whom can resolve a raw card id.
+ */
+export declare function blockingTitles(board: KanbanBoard, task: KanbanTask): string[];
+/**
+ * Order cards the way they must actually be worked: dependencies first, then
+ * priority, then the board's own column/manual order.
+ *
+ * The managed projection previously sorted by `createdAt` — the moment a card
+ * happened to be created — which is unrelated to execution order, so the list
+ * the model reads top-to-bottom was not a plan. A dependency-respecting
+ * (Kahn) order makes the visible sequence the executable sequence; ties fall
+ * back to the deterministic board order so the list never reshuffles on its
+ * own. Any card left over by a dependency cycle is appended rather than
+ * dropped — the board rejects cycles, but a projection must never lose work.
+ */
+export declare function orderTasksForTodos(board: KanbanBoard, tasks: readonly KanbanTask[]): KanbanTask[];
 /**
  * Replace the tactical todo list from the current cards on a session-owned board.
  *
@@ -43,6 +134,8 @@ export interface SessionKanbanSourceUpdate {
  * todo list that happened to exist when the run started.
  */
 export declare function applySessionKanbanBoardToTodos(context: Context, board: KanbanBoard): TodoItem[];
+/** Project a durable managed board into the session's compact todo surface. */
+export declare function applyManagedKanbanBoardToTodos(context: Context, board: KanbanBoard): TodoItem[];
 /** Reflect a TUI/WebUI Kanban card edit back to its originating work list. */
 export declare function applySessionKanbanTaskToSource(context: Context, task: KanbanTask, options?: {
     remove?: boolean | undefined;