@buildaharness/aielia 0.3.3 → 0.3.5

package/dist/plan-question.d.ts

@@ -0,0 +1,60 @@
+import { PlanRecord, PlanTaskRecord } from './plan-store.js';
+/**
+ * How a message that only asks about the active plan (the classifier's `isPlanQuestion`) is handled:
+ * - `stuck` (default): answered from the plan's recorded state ONLY while the plan is stuck on a failed
+ *   task — exactly where re-driving the plan is known to go wrong. A healthy plan behaves as it always
+ *   has, so this default changes nothing for it.
+ * - `always`: any plan question is answered from the recorded state, healthy plan or not.
+ * - `off`: an active plan drives every non-trivial turn (the pre-routing behaviour).
+ * `AUDIT_PLAN_QUESTION_ROUTING`: `always`/`on`/`1`/`true` → always; `0`/`false`/`off`/`no`/`disabled` → off;
+ * empty or `stuck` → stuck. Read at exactly one site: assistant.ts, where the turn is routed.
+ */
+export type PlanQuestionRouting = 'off' | 'stuck' | 'always';
+export declare function planQuestionRoutingMode(env?: Record<string, string | undefined>): PlanQuestionRouting;
+/** A plan is stuck when a step failed and was not skipped: the harness cannot advance past it on its own. */
+export declare function isPlanStuck(plan: PlanRecord): boolean;
+export declare function shouldRoutePlanQuestion(input: {
+    mode: PlanQuestionRouting;
+    plan: PlanRecord | null;
+    isPlanQuestion: boolean | undefined;
+}): boolean;
+/**
+ * `AUDIT_STUCK_PLAN_RESUME` (default ON): a plan stuck on a failed step is resumed only by a message that says to carry it
+ * on (the classifier's `continuesPlan`). Any other message is answered on its own terms — the plan is not handed to the
+ * harness, so the failed step is not silently retried — and the reply ends by asking whether to retry it. `0`/`false`/
+ * `off`/`no`/`disabled` restores the old behaviour (any non-trivial message on a stuck plan retries the step).
+ */
+export declare function stuckPlanResumeEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * True when the turn should set the stuck plan aside: the plan is stuck, the message is not a question about it (that is
+ * routed separately) and the classifier said explicitly that it does not continue it. A missing `continuesPlan` is not
+ * "no" — it keeps today's behaviour.
+ */
+export declare function shouldSetAsideStuckPlan(input: {
+    enabled: boolean;
+    plan: PlanRecord | null;
+    isPlanQuestion: boolean | undefined;
+    continuesPlan: boolean | undefined;
+}): boolean;
+/** Prompt addendum for a turn that set a stuck plan aside: answer the message, then ask about the failed step. */
+export declare function renderStuckPlanNudge(plan: PlanRecord): string;
+/**
+ * The plan's tasks as the harness should see them for a turn that moves the plan forward. A step that
+ * failed is put back to pending so it gets another attempt (left as FAILED it would strand the run on
+ * every later turn), and its description carries why the last attempt was rejected so the retry can
+ * address that instead of repeating it. Only the harness's copy changes: the stored plan keeps its
+ * original description, and its status is rewritten from the run's outcome afterwards.
+ */
+export declare function planTasksForRun(tasks: PlanTaskRecord[]): PlanTaskRecord[];
+/**
+ * What to add to the reply of a turn that ran an approved plan and stopped because a step was not
+ * accepted as done. Without it the reply is just the last step that DID complete, and the user only finds
+ * out the plan stalled by asking. Empty when nothing was rejected this turn.
+ */
+export declare function renderPlanStopNote(plan: PlanRecord, taskNotes: Record<string, string> | undefined): string;
+/**
+ * The plan's real state, rendered for the prompt of a turn that only asks about it. Grounds the answer
+ * in what the task graph actually recorded (a task is "done" only if it completed; a failed one carries
+ * the reason it was not accepted) so the reply can't drift into describing the plan as it was drafted.
+ */
+export declare function renderPlanStateBlock(plan: PlanRecord): string;

package/dist/plan-service.d.ts

@@ -33,7 +33,7 @@ export declare class PlanService {
     updatePlanFromRun(plan: PlanRecord, taskGraphTasks: {
         id: string;
         status: TaskStatus;
-    }[]): PlanRecord;
+    }[], taskNotes?: Record<string, string>): PlanRecord;
     planCompletionPct(plan: PlanRecord): number;
     computePlanPosition(plan: PlanRecord, taskGraphTasks: {
         id: string;
@@ -44,7 +44,7 @@ export declare class PlanService {
     saveAndSummarize(sessionId: string, plan: PlanRecord, taskGraphTasks: {
         id: string;
         status: TaskStatus;
-    }[]): Promise<{
+    }[], taskNotes?: Record<string, string>): Promise<{
         plan: PlanRecord;
         completionPct: number;
         planStatus: {
@@ -55,6 +55,10 @@ export declare class PlanService {
                 id: string;
                 description: string;
                 status: string;
+                note?: string;
+                dependsOn?: string[];
+                cancelled?: boolean;
+                riskLevel?: 'LOW' | 'MEDIUM' | 'HIGH';
             }[];
         };
     }>;

package/dist/plan-step-prompt.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `AUDIT_PLAN_STEP_PROMPT` gate. Default **ON**: while an approved plan runs, the model is told which
+ * step it is carrying out. A falsy value (`0` / `false` / `off` / `no` / `disabled`) restores the
+ * previous behaviour, where every step was run by re-sending the user's message alone. Read at exactly
+ * one site: assistant.ts, where the proposer is wired.
+ */
+export declare function planStepPromptEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * The instruction that makes one step of a plan a distinct piece of work. Without it the harness ran
+ * every step through the same proposer with only the user's message ("run the plan"), so each step
+ * produced the same answer and none of them did its own step. `description` may already carry the
+ * reason a previous attempt was rejected (plan-question.ts's planTasksForRun), which is what lets a
+ * retry address it.
+ */
+export declare function buildStepInstruction(description: string): string;

package/dist/plan-store.d.ts

@@ -23,6 +23,12 @@ export interface PlanTaskRecord {
      * claiming the user's own work actually got done.
      */
     cancelled?: boolean;
+    /**
+     * Why the last attempt at this task did not count as done — set when the semantic task-completion
+     * check judged its output did not do the task (task-completion-check.ts), so a later turn can say
+     * why the plan is stuck. Cleared once the task completes. Absent otherwise.
+     */
+    statusNote?: string;
 }
 /**
  * Superset of the old 3-value `status`: 'drafting' and 'awaiting_approval' are new (plan mode's
@@ -202,7 +208,7 @@ export declare function editPlanTask(memory: MemoryAdapter, sessionId: string, p
 export declare function updatePlanFromRun(plan: PlanRecord, taskGraphTasks: {
     id: string;
     status: TaskStatus;
-}[]): PlanRecord;
+}[], taskNotes?: Record<string, string>): PlanRecord;
 /** Cancelled tasks are excluded from both sides of the ratio — they're neither remaining work nor
  * something the user actually did, so counting them as "complete" would overstate real progress.
  * A plan with no tasks at all is 0% (unchanged); a plan whose remaining tasks were all cancelled

package/dist/plan-viz/normalize.d.ts

@@ -0,0 +1,14 @@
+import { VizNode } from './types.js';
+export interface NormalizedNodes {
+    nodes: VizNode[];
+    /** What was repaired, one human-readable line each (duplicate ids, unknown/self dependencies, broken cycles). */
+    warnings: string[];
+}
+/**
+ * Makes any node list safe for the layout and rasterizer: drops duplicate ids (first wins), unknown and
+ * self dependencies, duplicate dependencies, and breaks cycles by removing the edge that closes one
+ * (depth-first in input order, so the result is deterministic). Never throws and never mutates its input.
+ * Behaviour is specified by `normalizePlan` in testkit/generators.ts and differential-tested against it.
+ * The depth-first walk is iterative so a very deep chain cannot overflow the stack.
+ */
+export declare function normalizePlanNodes(input: readonly VizNode[]): NormalizedNodes;

package/dist/plan-viz/plan-detail-lines.d.ts

@@ -0,0 +1,3 @@
+import { VizNode } from './types.js';
+/** The detail drawer's text for one node: full (unshortened) label, status, dependencies and dependents. Pure. */
+export declare function planDetailLines(nodes: readonly VizNode[], id: string | undefined, width: number): string[];

package/dist/plan-viz/plan-layout.d.ts

@@ -0,0 +1,48 @@
+import { VizNode } from './types.js';
+/** Above this many nodes the picture is not useful in a terminal; callers fall back to the checklist. */
+export declare const MAX_PLAN_NODES = 150;
+/** Dense plans (hundreds of dependencies) turn into a wall of lines; same checklist fallback as the node cap. */
+export declare const MAX_PLAN_EDGES = 600;
+export declare const BOX_HEIGHT = 3;
+/** A box (real) or a one-column waypoint of an edge that skips ranks (virtual). */
+export interface LayoutItem {
+    uid: number;
+    rank: number;
+    x: number;
+    w: number;
+    virtual: boolean;
+    /** Real items only. */
+    node?: VizNode;
+    /** Visible label text of a real item (sanitized and shortened). */
+    label?: string;
+    /** Virtual items: the chain they belong to, so adjacent-rank waypoints of one edge may share a column. */
+    chain?: number;
+}
+export interface EdgeChain {
+    from: string;
+    to: string;
+    /** Source box, waypoints in rank order, target box. */
+    items: LayoutItem[];
+}
+export interface PlanLayout {
+    ok: true;
+    nodes: VizNode[];
+    ranks: LayoutItem[][];
+    chains: EdgeChain[];
+    byId: Map<string, LayoutItem>;
+    width: number;
+    warnings: string[];
+}
+export type LayoutFailure = {
+    ok: false;
+    reason: 'empty' | 'too_large' | 'cannot_draw';
+    message: string;
+};
+export declare const LABEL_FLOOR = 8;
+/**
+ * Layered layout in character units. dagre decides the ranks and the left-to-right order (dummy nodes
+ * included); positions are then legalized per rank so boxes never touch and waypoints keep clear of boxes.
+ * Deterministic: nodes and edges are inserted in task order and nothing in the input depends on status, so
+ * a status change never moves a box.
+ */
+export declare function layoutPlan(input: readonly VizNode[], labelMax: number): PlanLayout | LayoutFailure;

package/dist/plan-viz/plan-nav.d.ts

@@ -0,0 +1,29 @@
+import { Box, VizNode } from './types.js';
+/**
+ * Keyboard navigation over the plan graph (section 5.4). Same behaviour as `referenceNavigator` in
+ * testkit/nav-oracles.ts (copied: production code does not import the kit); a differential test keeps them equal.
+ * Pure: no I/O. Read-only: it only moves a selection.
+ */
+export type NavKey = 'up' | 'down' | 'left' | 'right' | 'tab' | 'shiftTab';
+export interface NavModel {
+    ids: string[];
+    taskOrder: string[];
+    /** Box centre x and top y; rank is decided by y (equal y = same rank). */
+    x: Record<string, number>;
+    y: Record<string, number>;
+    deps: Record<string, string[]>;
+    dependents: Record<string, string[]>;
+}
+export interface NavState {
+    cur: string;
+    lastKey?: NavKey;
+    /** For a repeated vertical key: the node the cycling started from. */
+    lastFrom?: string;
+    k: number;
+}
+export interface Navigator {
+    start(model: NavModel, id: string): NavState;
+    press(model: NavModel, state: NavState, key: NavKey): NavState;
+}
+export declare function navModelFrom(nodes: readonly VizNode[], boxes: readonly Box[]): NavModel;
+export declare const planNavigator: Navigator;

package/dist/plan-viz/plan-raster.d.ts

@@ -0,0 +1,36 @@
+import { LayoutFailure } from './plan-layout.js';
+import { RenderResult, VizNode, VizStatus } from './types.js';
+export interface PlanRenderOptions {
+    /** Terminal width in cells; labels shrink (down to a floor) until the picture fits. Omit for the natural size. */
+    maxCols?: number;
+    ascii?: boolean;
+    color?: boolean;
+    selectedId?: string;
+}
+/** What a successful render returns beyond what the grid oracles need. */
+export interface PlanRender extends RenderResult {
+    ok: true;
+    width: number;
+    height: number;
+    /** False when even the shortest labels do not fit `maxCols`; the caller pans a viewport over the full grid. */
+    fits: boolean;
+    /** The label text each box shows (after sanitizing and shortening). */
+    labels: Record<string, string>;
+    /** Cells (row, column) every edge is drawn through, keyed `${from}>${to}`. */
+    routes: Record<string, Array<[number, number]>>;
+    /** One entry per terminal cell (a double-width character is followed by WIDE_TAIL) and its SGR parameters ('' = none). */
+    cells: string[][];
+    styles: string[][];
+    warnings: string[];
+}
+export type PlanRenderFailure = LayoutFailure;
+export declare const GLYPHS: Record<VizStatus, string>;
+export declare const ASCII_GLYPHS: Record<VizStatus, string>;
+/** Joins cells into text lines, emitting SGR sequences only where the style changes. Trailing blanks are dropped. */
+export declare function toLines(cells: readonly string[][], styles: readonly string[][], rows?: [number, number], cols?: [number, number]): string[];
+/**
+ * Lays out and draws a plan. Labels shrink (down to a floor) until the picture fits `maxCols`; when it still
+ * does not, the full-size grid is returned with `fits: false` so the caller can pan over it. Never throws:
+ * a plan that cannot be drawn comes back as `{ ok: false, reason, message }` and the caller shows the checklist.
+ */
+export declare function renderPlan(nodes: readonly VizNode[], opts?: PlanRenderOptions): PlanRender | PlanRenderFailure;

package/dist/plan-viz/plan-routes.d.ts

@@ -0,0 +1,6 @@
+import { PlanRender } from './plan-raster.js';
+import { Edge } from './types.js';
+/** The edges that touch a node: its incoming (dependencies) and outgoing (dependents) ones. */
+export declare function incidentEdges(edges: readonly Edge[], id: string): Edge[];
+/** Every cell the incident edges of `id` are drawn through, as `"row,col"` keys (exact: the rasterizer reports its own routes). */
+export declare function highlightCells(render: Pick<PlanRender, 'edges' | 'routes'>, id: string): Set<string>;

package/dist/plan-viz/plan-snapshot.d.ts

@@ -0,0 +1,73 @@
+import { TaskStatus } from '@buildaharness/harness';
+import { PlanRecord } from '../plan-store.js';
+import { GoalGraphRecord } from '../goal-graph-store.js';
+import { VizNode } from './types.js';
+/** One node of the snapshot the web viewer consumes (cuddlytoddly's node shape; absent metadata means "nothing to show"). */
+export interface SnapshotNode {
+    id: string;
+    node_type: 'goal' | 'task';
+    status: string;
+    origin: 'system';
+    dependencies: string[];
+    children: string[];
+    result: string | null;
+    metadata: {
+        description: string;
+        expanded?: boolean;
+        required_input: string[];
+        output: string[];
+        execution_steps: string[];
+        reflection_notes: string[];
+        verification_failure?: string;
+    };
+}
+export interface PlanSnapshot {
+    type: 'snapshot';
+    nodes: Record<string, SnapshotNode>;
+    status: {
+        total: number;
+        by_status: Record<string, number>;
+        running_nodes: string[];
+        node_activities: Record<string, string>;
+    };
+    structure_version: number;
+    paused: boolean;
+    activity: string | null;
+    activity_started_ms: number | null;
+    status_events: never[];
+    tokens: {
+        prompt: number;
+        completion: number;
+        total: number;
+        calls: number;
+    };
+}
+export interface PlanSnapshotResult {
+    /** What the web viewer consumes. */
+    snapshot: PlanSnapshot;
+    /** The normalized nodes the CLI renderer consumes (goal nodes included, ids namespaced exactly as in the snapshot). */
+    nodes: VizNode[];
+    /** Repairs `normalizePlanNodes` made to malformed input (empty for a well-formed plan). */
+    warnings: string[];
+}
+export interface PlanSnapshotOptions {
+    /** The node the harness is currently executing — becomes `activity: "Executing: <currentNode>"`. Defaults to the first running task. */
+    currentNode?: string;
+    tokens?: {
+        prompt: number;
+        completion: number;
+        total: number;
+        calls: number;
+    };
+}
+/**
+ * Turns a plan (or every goal thread) into the node snapshot both surfaces draw. Pure and total: malformed
+ * input is repaired by `normalizePlanNodes`, never thrown on. `live` overlays per-task statuses from a
+ * running turn; un-namespaced ids apply to the active thread (or the only plan), namespaced ids anywhere.
+ * Statuses: PENDING with every dependency done is `ready`; BLOCKED -> awaiting_input; HUMAN_REQUIRED ->
+ * awaiting_user; a cancelled task is `done` in the snapshot (with a ⊘ description) and `cancelled` for the CLI.
+ */
+export declare function planToSnapshot(source: PlanRecord | GoalGraphRecord, live?: readonly {
+    id: string;
+    status: TaskStatus;
+}[], opts?: PlanSnapshotOptions): PlanSnapshotResult;

package/dist/plan-viz/plan-viewport.d.ts

@@ -0,0 +1,29 @@
+import { Box } from './types.js';
+export interface Viewport {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Keeps the selected box fully visible when it fits, never leaves the diagram and never exceeds the terminal.
+ * Scrolls the minimum amount from the previous viewport so the picture does not jump while navigating.
+ * Same behaviour as `followSelection` in testkit/nav-oracles.ts (copied: production code does not import the kit).
+ */
+export declare function followSelection(prev: Viewport, box: Box, grid: {
+    width: number;
+    height: number;
+}, term: {
+    cols: number;
+    rows: number;
+}): Viewport;
+/** Which edges of the diagram lie beyond the viewport, for scroll indicators. */
+export declare function scrollIndicators(v: Viewport, grid: {
+    width: number;
+    height: number;
+}): {
+    up: boolean;
+    down: boolean;
+    left: boolean;
+    right: boolean;
+};

package/dist/plan-viz/plan-width.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Terminal cell widths for the plan renderer. Same tables as testkit/display-width.ts (copied, not imported: production code must not depend on the test kit);
+ * the oracles cross-check it against that independent copy. Covers the ranges that matter for plan labels, not all of Unicode.
+ */
+export declare function cellWidth(ch: string): 0 | 1 | 2;
+export declare function displayWidth(s: string): number;
+/** Marks the second cell of a double-width character in a cell grid. */
+export declare const WIDE_TAIL = "\0";
+/** Expands a line into one entry per terminal cell (a wide character becomes [char, WIDE_TAIL]). */
+export declare function toCells(line: string): string[];
+export declare function toGrid(lines: readonly string[]): string[][];
+/** One printable line: control, escape and bidi characters are removed, whitespace runs collapse, ends are trimmed. */
+export declare function sanitizeLabel(raw: string): string;
+/** Cuts `s` to at most `max` cells, ending with an ellipsis when something was removed. Never splits a wide character. */
+export declare function fitLabel(s: string, max: number): string;

package/dist/plan-viz/testkit/display-width.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An intentionally simple, independent terminal cell-width function for the oracles. The production
+ * renderer may use a library; checking it against this separate implementation catches width bugs in
+ * either (CJK, emoji, combining marks). Covers the ranges that matter for plan labels, not all of Unicode.
+ */
+export declare function cellWidth(ch: string): 0 | 1 | 2;
+export declare function displayWidth(s: string): number;
+/** Marks the second cell of a double-width character in a cell grid. */
+export declare const WIDE_TAIL = "\0";
+/** Expands a line into one entry per terminal cell (a wide character becomes [char, WIDE_TAIL]). */
+export declare function toCells(line: string): string[];
+export declare function toGrid(lines: readonly string[]): string[][];

package/dist/plan-viz/testkit/generators.d.ts

@@ -0,0 +1,61 @@
+import { Box, Edge, VizNode, VizStatus } from './types.js';
+/** Small deterministic PRNG (mulberry32): the same seed always yields the same plans, so failures reproduce. */
+export declare function rng(seed: number): () => number;
+export declare function edgesOf(nodes: readonly VizNode[]): Edge[];
+export declare function dependentsOf(nodes: readonly VizNode[]): Record<string, string[]>;
+export declare function isAcyclic(nodes: readonly VizNode[]): boolean;
+/** Weakly connected: ignoring edge direction, every node can reach every other. */
+export declare function isConnected(nodes: readonly VizNode[]): boolean;
+/** Longest-path rank from the roots (roots are rank 0). Assumes an acyclic, normalized plan. */
+export declare function ranksOf(nodes: readonly VizNode[]): Record<string, number>;
+/** Adds a goal node that depends on every sink — exactly what the production adapter does, so the result is connected. */
+export declare function withGoal(nodes: readonly VizNode[], goalId?: string, label?: string): VizNode[];
+export declare function withStatus(nodes: readonly VizNode[], id: string, status: VizStatus): VizNode[];
+export interface Normalized {
+    nodes: VizNode[];
+    warnings: string[];
+}
+/**
+ * Executable specification of input sanitising: drops duplicate ids (first wins), unknown and self
+ * dependencies, and breaks cycles by removing the edge that closes one (deterministically, in input order).
+ * The production adapter/layout must satisfy `checkNormalized` on every input, malformed ones included.
+ */
+export declare function normalizePlan(input: readonly VizNode[]): Normalized;
+export declare function checkNormalized(nodes: readonly VizNode[]): string[];
+/**
+ * A trivial deterministic layout (longest-path ranks, input order within a rank). It is *not* the
+ * production layout; it exists so navigation and viewport oracles can be tested before that layout
+ * exists, and as a cross-check afterwards. Box height is 3, label width is the display width.
+ */
+export declare function toyLayout(plan: readonly VizNode[], gapX?: number, gapY?: number): {
+    boxes: Box[];
+    edges: Edge[];
+    width: number;
+    height: number;
+};
+/** The 9-task plan used throughout the verification work, every interesting status included, goal depending on the terminals. */
+export declare const NINE_TASK_PLAN: VizNode[];
+/** Hand-shaped plans, each chosen to stress one thing. Every one is normalized; `connected` says whether it is weakly connected. */
+export declare const NAMED_PLANS: Record<string, {
+    nodes: VizNode[];
+    connected: boolean;
+}>;
+/**
+ * The seven real plan templates shipped with aielia, converted to nodes with a goal node added
+ * (what a user of the product actually gets). Statuses are assigned by progress so each one exercises
+ * done / running / pending.
+ */
+export declare function templatePlans(): Record<string, VizNode[]>;
+export interface RandomPlanOptions {
+    minNodes?: number;
+    maxNodes?: number;
+    /** Probability that a node depends on any given earlier node (default depends on size). */
+    density?: number;
+    /** Add a goal depending on every sink (connected, like the adapter's output). Default true. */
+    goal?: boolean;
+    /** Mix in CJK and very long labels. Default false. */
+    unicodeLabels?: boolean;
+}
+export declare function randomPlan(seed: number, opts?: RandomPlanOptions): VizNode[];
+/** Malformed inputs the production code must survive (it receives LLM-drafted and hand-edited plans). */
+export declare const MALFORMED_PLANS: Record<string, VizNode[]>;

package/dist/plan-viz/testkit/grid-oracles.d.ts

@@ -0,0 +1,38 @@
+import { Box, Edge, RenderResult, VizNode } from './types.js';
+export interface OracleOptions {
+    /** The diagram uses the ASCII glyph set (`| - + v`). `+` is ambiguous, so edge checks become connectivity-only. */
+    ascii?: boolean;
+    /** Require reached = expected exactly (default true; forced off for ASCII). */
+    exact?: boolean;
+    /** Treat `┼` as a junction (turns allowed). Default false: a crossing is straight-through only. */
+    crossingIsJunction?: boolean;
+}
+/** Exactness: from every node, following drawn lines reaches precisely the nodes that depend on it. */
+export declare function checkEdges(lines: readonly string[], boxes: readonly Box[], edges: readonly Edge[], opts?: OracleOptions): string[];
+/** Line glyphs outside every box that no edge traversal passes through: leftovers such as the prototype's stray segments. */
+export declare function checkNoStrays(lines: readonly string[], boxes: readonly Box[], opts?: OracleOptions): string[];
+/** Every arrowhead must sit directly above the top border of some box. */
+export declare function checkArrowsPointAtBoxes(lines: readonly string[], boxes: readonly Box[], opts?: OracleOptions): string[];
+/** No two boxes overlap, and boxes in the same rows keep at least `minGap` empty columns between them. */
+export declare function checkNoOverlap(boxes: readonly Box[], minGap?: number): string[];
+/** Edge direction: a dependent is drawn strictly below the node it depends on. */
+export declare function checkRanksDownward(boxes: readonly Box[], edges: readonly Edge[]): string[];
+/** Borders are intact and nothing but label text sits inside a box. */
+export declare function checkBoxesDrawn(lines: readonly string[], boxes: readonly Box[], opts?: OracleOptions): string[];
+/** Each node's label text (already truncated by the renderer, if it truncates) appears inside its own box. */
+export declare function checkLabelsVisible(lines: readonly string[], boxes: readonly Box[], expected: Readonly<Record<string, string>>): string[];
+/** No output line is wider than the terminal, measured in cells (CJK and emoji count as two). */
+export declare function checkWidth(lines: readonly string[], maxCols: number): string[];
+/** Output must be plain printable text: no stray control characters or newlines inside a line. */
+export declare function checkPrintable(lines: readonly string[]): string[];
+export interface RenderCheckInput {
+    render: RenderResult;
+    nodes: readonly VizNode[];
+    /** Terminal width the render was asked for; width is only checked when given. */
+    maxCols?: number;
+    /** Expected visible label text per node id (after any truncation); omit to skip. */
+    labels?: Readonly<Record<string, string>>;
+    opts?: OracleOptions;
+}
+/** Runs every grid oracle and returns all violations (empty = the diagram is correct). */
+export declare function checkRender({ render, maxCols, labels, opts }: RenderCheckInput): string[];

package/dist/plan-viz/testkit/nav-oracles.d.ts

@@ -0,0 +1,79 @@
+import { Box, Edge, VizNode } from './types.js';
+/**
+ * The navigation specification and its oracles. `referenceNavigator` is the *executable specification*
+ * of the pane's keys (section 5.4 of the plan); the production navigator must behave identically on the
+ * property suite below. It was derived from the V10 simulation, where the obvious rule ("go to the
+ * nearest connected node") stranded nodes in about 1.1–1.5% of plans and the final rule reached every
+ * node in 3,000 of 3,000.
+ *
+ * Rules:
+ *  - ↑ / ↓ follow edges to the nearest (by horizontal position) dependency / dependent. Pressing the SAME
+ *    key again cycles through the other candidates of the node the sequence started from.
+ *  - ← / → move to the neighbour in the same rank (by horizontal position), wrapping around.
+ *  - Tab / Shift+Tab step through all nodes in task order, wrapping — a guaranteed way to reach any node.
+ *  - A key with nothing to move to leaves the selection unchanged.
+ */
+export type NavKey = 'up' | 'down' | 'left' | 'right' | 'tab' | 'shiftTab';
+export interface NavModel {
+    ids: string[];
+    /** Task order, used by Tab (usually the plan's own order). */
+    taskOrder: string[];
+    /** Box centre x and top y; rank is decided by y (equal y = same rank). */
+    x: Record<string, number>;
+    y: Record<string, number>;
+    deps: Record<string, string[]>;
+    dependents: Record<string, string[]>;
+}
+export interface NavState {
+    cur: string;
+    lastKey?: NavKey;
+    /** For a repeated vertical key: the node the cycling started from. */
+    lastFrom?: string;
+    /** How many times the same vertical key has been repeated. */
+    k: number;
+}
+export interface Navigator {
+    start(model: NavModel, id: string): NavState;
+    press(model: NavModel, state: NavState, key: NavKey): NavState;
+}
+export declare function navModelFrom(nodes: readonly VizNode[], boxes: readonly Box[]): NavModel;
+export declare const referenceNavigator: Navigator;
+/** Every node reachable from `startId` using only the four arrow keys (explores real key state, with repeats). */
+export declare function reachableByArrows(nav: Navigator, m: NavModel, startId: string): Set<string>;
+/** Arrow-only reachability: every node of a connected plan is reachable from the start node. */
+export declare function checkReachability(nav: Navigator, m: NavModel, startId?: string): string[];
+/** Tab visits every node once in task order and returns to the start; Shift+Tab is its exact inverse. */
+export declare function checkTabCycle(nav: Navigator, m: NavModel): string[];
+/** A vertical key with no candidate leaves the selection (and state) untouched. */
+export declare function checkBoundaries(nav: Navigator, m: NavModel): string[];
+/** ← and → stay in the rank, wrap, and are inverses of each other. */
+export declare function checkHorizontal(nav: Navigator, m: NavModel): string[];
+/** Repeating ↓ (↑) visits each dependent (dependency) exactly once, then wraps. */
+export declare function checkRepeatCycles(nav: Navigator, m: NavModel): string[];
+/** The highlighted edges for a selection are exactly the edges touching that node. */
+export declare function checkHighlightIncident(m: NavModel, edges: readonly Edge[], highlight: (id: string) => readonly Edge[]): string[];
+export interface Viewport {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Executable specification for panning: keep the selected box fully visible when it fits, never leave
+ * the diagram, and never exceed the terminal. Scrolls the minimum amount from the previous viewport so the
+ * picture does not jump while navigating.
+ */
+export declare function followSelection(prev: Viewport, box: Box, grid: {
+    width: number;
+    height: number;
+}, term: {
+    cols: number;
+    rows: number;
+}): Viewport;
+export declare function checkViewport(v: Viewport, box: Box, grid: {
+    width: number;
+    height: number;
+}, term: {
+    cols: number;
+    rows: number;
+}): string[];

package/dist/plan-viz/testkit/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the plan-visualization test kit. The kit contains fixtures, seeded generators and
+ * *oracles* (independent correctness checkers) that the layout, rasterizer, navigation and pane tests all
+ * use, so every layer is held to the same definition of "correct". Nothing here is production code and
+ * nothing here is exported from the package index.
+ */
+export { VIZ_STATUSES } from '../types.js';
+export type { VizStatus, VizNode, Box, Edge, RenderResult } from '../types.js';

package/dist/plan-viz/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Production types for the plan visualization: the status vocabulary the renderers receive, the node
+ * shape the layout consumes, and what a rasterizer returns. The test kit re-exports these so there is
+ * one definition.
+ */
+/** The status vocabulary the renderer receives (the adapter maps aielia TaskStatus onto it). */
+export type VizStatus = 'pending' | 'ready' | 'running' | 'done' | 'failed' | 'awaiting_user' | 'awaiting_input' | 'cancelled';
+export declare const VIZ_STATUSES: readonly VizStatus[];
+export interface VizNode {
+    id: string;
+    label: string;
+    status: VizStatus;
+    /** Ids this node depends on (they are drawn above it). */
+    deps: string[];
+}
+/** A node rectangle on the character grid, in cells (a double-width character occupies two cells). */
+export interface Box {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** `from` is the dependency (drawn above), `to` the dependent (drawn below). */
+export interface Edge {
+    from: string;
+    to: string;
+}
+/** What a rasterizer must return for the oracles to be able to check it. */
+export interface RenderResult {
+    lines: string[];
+    boxes: Box[];
+    edges: Edge[];
+}