tickmarkr 1.83.0 → 1.85.0

package/dist/tui/cockpit/components.js

@@ -18,9 +18,23 @@ import { formatKeybarEntries, keybarEntries, SETUP_KEY_BINDINGS, } from "./keys.
  */
 import { cellWidth as stringWidth, sliceCells } from "./width.js";
 const SPARKLINE_GLYPHS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+/**
+ * The hover highlight's non-colour half: one cell wide, drawn in the separator
+ * the row already spends, from the block family the cockpit already draws with.
+ * Colour is the other half and the louder one, but Chalk suppresses inverse and
+ * colour together at level 0, so a highlight made of ink alone does not exist
+ * under `NO_COLOR` or a colourless TTY. This is a character; it always does.
+ */
+export const HOVER_MARKER = "▌";
 const BAND_GAP_COLUMNS = 1;
 const PANEL_HORIZONTAL_CHROME = 4;
-const READABLE_PANEL_COLUMNS = 20;
+/**
+ * The columns below which a bordered panel no longer reads — the floor a band
+ * allocation defends, and the floor planFrame's session resize override clamps
+ * the body panel at: a drag surrenders an element whole or not at all, it
+ * never collapses one below what reads.
+ */
+export const READABLE_PANEL_COLUMNS = 20;
 export const PANEL_CHROME_ROWS = 3;
 export const BAND_CONTINUATION_PREFIX = "↳ ";
 const SETUP_KEYS = keybarEntries(SETUP_KEY_BINDINGS);
@@ -269,6 +283,8 @@ export function KeyRoster({ entries, width, }) {
 export function StatusStrip({ items, width, }) {
     return (_jsx(OneLineItems, { width: width, label: "cockpit status", children: items.map((item, index) => (_jsxs(Box, { flexShrink: 0, children: [index > 0 && _jsx(BodyText, { emphasis: "dim", children: " \u00B7 " }), _jsx(StateGlyph, { state: item.state }), _jsxs(BodyText, { children: [" ", item.text] })] }, `${item.state}:${item.text}`))) }));
 }
-export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", selection, }) {
-    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsx(BodyText, { children: " " }), index === selection && (_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " "] })), _jsx(BodyText, { children: row.text })] }, row.id))) }));
+export function JournalRowPanel({ rows, width, focused, title = "JOURNAL", selection, hover, }) {
+    return (_jsx(Panel, { title: title, focused: focused, width: width, children: rows.map((row, index) => (_jsxs(Box, { flexDirection: "row", flexWrap: "nowrap", height: 1, overflow: "hidden", children: [_jsx(BodyText, { emphasis: "dim", children: row.time }), _jsx(BodyText, { children: " " }), _jsx(StateGlyph, { state: row.state }), _jsx(BodyText, { emphasis: index === hover ? "strong" : "normal", children: index === hover ? HOVER_MARKER : " " }), index === selection && (_jsxs(BodyText, { emphasis: "strong", children: [GLYPHS.pointer, " "] })), index === hover
+                    ? (_jsx(Text, { inverse: true, color: `ansi256(${COCKPIT_DATA_RAMP[0].xterm})`, children: row.text }))
+                    : _jsx(BodyText, { children: row.text })] }, row.id))) }));
 }

package/dist/tui/cockpit/derive.d.ts

@@ -3,7 +3,14 @@ import type { RunViewId } from "./views.js";
 export declare const SPARKLINE_BUCKET_WINDOW = 12;
 export declare function selectSparklineBucketWidthMs(elapsedMs: number): number;
 type MetricSample = number | null;
-export type RunStatus = "done" | "failed" | "interrupted" | "running";
+/**
+ * What the run is, in one word. `parked` is first-class beside the rest because
+ * a run holding an unresolved `human` task owes the operator a verb — it is not
+ * done, and calling it done is the render OBS-252 caught. The task-level word
+ * for the same fact stays `human` (TaskState): that is the event the journal
+ * writes, and `parked` is what the fold of it means for the run.
+ */
+export type RunStatus = "done" | "failed" | "interrupted" | "parked" | "running";
 export type RunCockpitData = {
     readonly binaryVersion: string;
     readonly runId: string;
@@ -80,12 +87,30 @@ export type TaskRow = {
     readonly attempts?: number;
     readonly actor?: string;
     readonly lastEventTime?: string;
+    /** Complete UTC instant paired with `lastEventTime`; additive for existing consumers. */
+    readonly lastEventTimestamp?: string;
     readonly title?: string;
+    /**
+     * The park the task is standing in right now, as the daemon recorded it
+     * (`task-human` data.kind). A resolved park has no kind at all: the badge
+     * retires with the state it belonged to, so a merged task never wears the
+     * `gate-fail` it was released from an hour earlier (OBS-256).
+     */
+    readonly parkKind?: string;
+    /**
+     * Recorded merged, and only then. A task the journal carried to `done` has
+     * finished its work; a task the journal recorded a `merge` for has landed.
+     * The two are different rows, so a consumer drawing a check-mark has the fact
+     * that earns one rather than having to read `done` as if it were the same.
+     */
+    readonly merged?: true;
 };
 /** One recorded gate result. `details` is the record's own text, verbatim. */
 export type GateRow = {
     readonly id: string;
     readonly time: string;
+    /** Complete UTC instant paired with `time`; additive for existing consumers. */
+    readonly timestamp?: string;
     readonly state: ComponentState;
     readonly gate?: string;
     readonly taskId?: string;
@@ -99,8 +124,10 @@ export type FleetRow = {
     readonly model: string;
     readonly dispatches?: number;
     readonly lastEventTime?: string;
+    /** Complete UTC instant paired with `lastEventTime`; additive for existing consumers. */
+    readonly lastEventTimestamp?: string;
 };
-export type TaskState = "done" | "failed" | "human" | "pending" | "running" | "interrupted";
+export type TaskState = "completed" | "done" | "failed" | "human" | "pending" | "running" | "interrupted";
 /**
  * The source identities the named view's rows carry, in draw order. Selection
  * is repaired against these, so it follows a row across a refresh instead of

package/dist/tui/cockpit/derive.js

@@ -116,6 +116,75 @@ function daemonPid(events) {
     }
     return undefined;
 }
+/**
+ * The state an event writes onto the task it names — the whole list of them, so
+ * "did anything move this task" is asked in one place. `task-dispatch` and
+ * `merge` carry more than a state and are folded by hand below; they are named
+ * here because they move one all the same.
+ *
+ * A Map, because an event name is whatever the journal wrote: an object's own
+ * lookup answers `constructor` and `toString` with something inherited and
+ * truthy, so a line naming one would masquerade as a state transition — writing
+ * a function where a TaskState belongs and releasing a park the run declared.
+ * A Map answers only for the keys stated here.
+ */
+const TASK_STATE_BY_EVENT = new Map([
+    ["task-dispatch", "running"],
+    ["merge", "done"],
+    ["task-done", "done"],
+    ["task-failed", "failed"],
+    ["task-human", "human"],
+    ["task-approved", "pending"],
+]);
+/** Only task identities the summary actually records can enter its fold. */
+function summaryTaskIds(value) {
+    return Array.isArray(value)
+        ? value.filter((id) => typeof id === "string")
+        : [];
+}
+/**
+ * The parks the latest `run-end` says the daemon stopped holding, that nothing
+ * since resolved. The summary is the daemon's own closing statement, so a run
+ * whose end names a task in `human` owes the operator a verb whether or not a
+ * `task-human` line happens to precede it — that dependence is what let a run
+ * end read `done` over a parked task (OBS-252).
+ *
+ * "Since" is measured from the summary forward, and only forward. The summary
+ * describes the moment the daemon exited, so a state written *before* it —
+ * the dispatch it parked, the completion of a round it then held for review —
+ * is history the summary already accounts for and cannot answer it. Weighing
+ * the whole-journal fold against it let a line above the summary retire a park
+ * the summary itself declares: `run-start · task-dispatch T1 · run-end
+ * human:[T1]` read `interrupted`, and the same journal with a `task-done T1`
+ * read `done` — OBS-252 again, one line lower.
+ *
+ * So a name is resolved only when a later event moved that task: approved,
+ * redispatched, finished, landed. Nothing later — including a task the record
+ * never mentions at all — leaves the park standing, because an uncorroborated
+ * park is still the run's own claim that it is waiting and withholding `done`
+ * on a claim the surface cannot check is the fail-closed reading. It stays a
+ * reading of the run and of the tasks it names: a summary is a journal event,
+ * so its explicit task outcomes are facts the board must count and draw even
+ * when the more detailed task event is absent.
+ */
+function unresolvedSummaryParks(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.event !== "run-end")
+            continue;
+        const parked = Array.isArray(event.data.human) ? event.data.human : [];
+        const released = new Map();
+        for (const later of events.slice(index + 1)) {
+            if (later.taskId === undefined)
+                continue;
+            if (!TASK_STATE_BY_EVENT.has(later.event))
+                continue;
+            released.set(later.taskId, later.event !== "task-human");
+        }
+        return parked.filter((id) => typeof id === "string" && released.get(id) !== true);
+    }
+    return [];
+}
 function deriveTasks(events, interrupted) {
     const tasks = new Map();
     const task = (taskId, index, ts) => {
@@ -126,6 +195,8 @@ function deriveTasks(events, interrupted) {
             id: taskId,
             dispatches: [],
             state: undefined,
+            parkKind: undefined,
+            merged: false,
             lastIndex: index,
             lastTs: ts,
             phase: "pending",
@@ -134,6 +205,30 @@ function deriveTasks(events, interrupted) {
         return created;
     };
     for (const [index, event] of events.entries()) {
+        if (event.event === "run-end") {
+            // The closing summary is a recorded fold, not commentary. Apply all
+            // task outcomes it owns before later resume events get their ordinary
+            // chance to supersede them. Failure comes last so a malformed overlap
+            // fails closed instead of repainting a failed task done.
+            const summaries = [
+                [event.data.done, "done"],
+                [event.data.human, "human"],
+                [event.data.failed, "failed"],
+            ];
+            for (const [ids, state] of summaries) {
+                for (const taskId of summaryTaskIds(ids)) {
+                    const fact = task(taskId, index, event.ts);
+                    fact.state = state;
+                    // A summary does not invent a park kind; it preserves one only when
+                    // it confirms that the same park still stands.
+                    if (state !== "human")
+                        fact.parkKind = undefined;
+                    fact.lastIndex = index;
+                    fact.lastTs = event.ts;
+                }
+            }
+            continue;
+        }
         if (!event.taskId)
             continue;
         if (event.event === "task-dispatch") {
@@ -148,11 +243,25 @@ function deriveTasks(events, interrupted) {
                 assignment: assignmentFrom(event.data.assignment),
             });
             fact.state = "running";
+            fact.parkKind = undefined;
             fact.phase = "worker";
             fact.lastIndex = index;
             fact.lastTs = event.ts;
             continue;
         }
+        if (event.event === "merge") {
+            const fact = task(event.taskId, index, event.ts);
+            fact.merged = true;
+            // A merge is a landing, and it is a state the journal recorded: the task
+            // is done, and whatever park it was released from is retired by the merge
+            // itself rather than by whichever event happened to precede it. Nothing
+            // here depends on a `task-done` line arriving first (OBS-256).
+            fact.state = "done";
+            fact.parkKind = undefined;
+            fact.lastIndex = index;
+            fact.lastTs = event.ts;
+            continue;
+        }
         if (event.event === "phase-start") {
             const fact = task(event.taskId, index, event.ts);
             fact.phase = typeof event.data.phase === "string" ? event.data.phase : fact.phase;
@@ -160,15 +269,19 @@ function deriveTasks(events, interrupted) {
             fact.lastTs = event.ts;
             continue;
         }
-        const state = {
-            "task-done": "done",
-            "task-failed": "failed",
-            "task-human": "human",
-            "task-approved": "pending",
-        }[event.event];
+        // `task-dispatch` and `merge` returned above; the rest write their state and
+        // nothing else. One list, read from one place, so a new state-writing event
+        // cannot move the fold without also moving what resolves a park.
+        const state = TASK_STATE_BY_EVENT.get(event.event);
         if (state) {
             const fact = task(event.taskId, index, event.ts);
             fact.state = state;
+            // The park kind travels with the park: `task-human` records it, and the
+            // next recorded state — approved, done, failed — retires it with the park
+            // it named. A resolved state must not leave its badge behind (OBS-256).
+            fact.parkKind = state === "human" && typeof event.data.kind === "string"
+                ? event.data.kind
+                : undefined;
             fact.lastIndex = index;
             fact.lastTs = event.ts;
         }
@@ -250,14 +363,42 @@ function recordsFailure(event) {
         || event.data.pass === false
         || event.data.ok === false
         || (typeof event.data.exitCode === "number" && event.data.exitCode !== 0)
-        || (event.event === "run-end" && event.data.tipVerify === "failed");
+        || (event.event === "run-end"
+            && (event.data.tipVerify === "failed"
+                || summaryTaskIds(event.data.failed).length > 0));
 }
+/**
+ * The outcome an event records as a success. `merge` is here and `task-done` is
+ * not: a merge records the landing, and a completion records only that the
+ * worker stopped working — the gates that judge it and the merge that lands it
+ * come after. A `run-end` counts only when its tip verification reads passed:
+ * an absent verdict is nothing verified, and a check-mark on nothing verified
+ * is the run claiming a pass tickmarkr never corroborated — the same
+ * fail-closed reading the status strip already draws (OBS-244), now on the row.
+ */
 function recordsSuccess(event) {
-    return event.event === "task-done"
-        || event.event === "merge"
+    return event.event === "merge"
         || event.data.pass === true
         || event.data.ok === true
-        || (event.event === "run-end" && event.data.tipVerify !== "failed");
+        || (event.event === "run-end" && event.data.tipVerify === "passed");
+}
+/** The newest run-end speaks for the run; spotlight is context, not outcome. */
+function runPresentation(runStatus, spotlight) {
+    switch (runStatus) {
+        case "failed":
+            return { state: "fail", word: "failed" };
+        case "parked":
+            return { state: "warn", word: "parked" };
+        case "interrupted":
+            return { state: "warn", word: "interrupted" };
+        case "running":
+            return { state: "neutral", word: "running" };
+        case "done":
+            // A task named beside the run still earns a check only from its merge.
+            return spotlight === undefined || spotlight.merged
+                ? { state: "pass", word: "pass" }
+                : { state: "neutral", word: "done" };
+    }
 }
 /**
  * A row depicts the event it names: the event's own recorded outcome decides
@@ -268,11 +409,25 @@ function recordsSuccess(event) {
  * Every state carries its word, so meaning never rides on hue alone.
  */
 function eventPresentation(event, task) {
-    if (event.event === "escalation" || event.event === "task-human") {
+    if (event.event === "escalation")
         return { state: "warn", word: "warn" };
-    }
+    // A park is a state, not a severity: the row says what the engagement is
+    // waiting for, which is the operator.
+    if (event.event === "task-human")
+        return { state: "warn", word: "parked" };
     if (recordsFailure(event))
         return { state: "fail", word: "fail" };
+    if (event.event === "run-end"
+        && summaryTaskIds(event.data.human).length > 0) {
+        return { state: "warn", word: "parked" };
+    }
+    // Work finished is not work landed. `task-done` records the first, so its row
+    // says `done` and carries no check: the check-mark belongs to the `merge` that
+    // records the landing, and until the journal writes one there is nothing to
+    // put it on (OBS-256). This is the same reading `taskPresentation` gives the
+    // task itself, stated here for the event because a row depicts its own event.
+    if (event.event === "task-done")
+        return { state: "neutral", word: "done" };
     if (recordsSuccess(event))
         return { state: "pass", word: "pass" };
     if (task?.state === "interrupted") {
@@ -282,19 +437,29 @@ function eventPresentation(event, task) {
 }
 function historyRow(event, tasks, spotlight, newest, runStatus) {
     const task = event.taskId === undefined ? undefined : tasks.get(event.taskId);
-    const { state, word } = eventPresentation(event, task);
+    // Spotlight is context only for the taskless closing summary. A task-owned
+    // newest event keeps its own identity and outcome: T2's dispatch or failure
+    // cannot become a pass for merged T1 merely because T1 wins the spotlight.
+    const summary = newest && event.event === "run-end"
+        ? runPresentation(runStatus, spotlight)
+        : undefined;
+    const { state, word } = summary ?? eventPresentation(event, task);
+    const displayedTask = newest
+        ? event.taskId === undefined ? spotlight : task
+        : task;
     // The spotlight entry must keep the task, its attempt and its acting adapter
     // inside the narrowest band's width budget — that budget cannot pay for the
     // separators and the event name, so the state word and the run's status
     // (what the newest event recorded) ride after the adapter instead.
-    const text = newest && spotlight !== undefined
-        ? `${spotlight.id} attempt ${taskAttempt(spotlight)} ${taskActor(spotlight)} ${word}${word === runStatus ? "" : ` ${runStatus}`}`
+    const text = newest && displayedTask !== undefined
+        ? `${displayedTask.id} attempt ${taskAttempt(displayedTask)} ${taskActor(displayedTask)} ${word}${word === runStatus ? "" : ` ${runStatus}`}`
         : task !== undefined
             ? `${task.id} ${word} · ${event.event}`
             : `${word} · ${event.event}`;
     return {
         id: `event:${event.line}`,
         time: eventTime(event.ts),
+        timestamp: event.ts,
         state,
         text,
     };
@@ -332,14 +497,28 @@ function taskRows(events, tasks, graph) {
         // zero when a run resumes, so a task dispatched 0,1,0 was tried three times
         // and reporting its last label would say one.
         const attempts = fact?.dispatches.length ?? 0;
+        // `task-done` records completion; only `merge` records landing. The fixed
+        // Tasks-view consumer maps `done` to a check, so the derived row must keep
+        // an unmerged completion in the neutral `completed` state and reserve
+        // `done` for a fact whose merge the journal actually carries.
+        const state = fact?.state === "done" && fact.merged !== true
+            ? "completed"
+            : fact?.state;
         return {
             id: `task:${id}`,
             taskId: id,
-            ...(fact?.state === undefined ? {} : { state: fact.state }),
+            ...(state === undefined ? {} : { state }),
             ...(attempts === 0 ? {} : { attempts }),
             ...(assignment === undefined ? {} : { actor: channelKey(assignment) }),
             ...(lastTs === undefined ? {} : { lastEventTime: eventTime(lastTs) }),
+            ...(lastTs === undefined ? {} : { lastEventTimestamp: lastTs }),
             ...(title === undefined ? {} : { title }),
+            // Only while the park stands: the fold cleared it the moment the journal
+            // recorded what the park resolved to.
+            ...(fact?.parkKind === undefined ? {} : { parkKind: fact.parkKind }),
+            // Landing is its own fact. `done` is work finished; only a recorded merge
+            // is work landed, and only that earns a check-mark.
+            ...(fact?.merged === true ? { merged: true } : {}),
         };
     });
 }
@@ -356,6 +535,7 @@ function gateRows(events) {
         return [{
                 id: `gate:${event.line}`,
                 time: eventTime(event.ts),
+                timestamp: event.ts,
                 state: pass === true ? "pass" : pass === false ? "fail" : "neutral",
                 ...(typeof event.data.gate === "string" ? { gate: event.data.gate } : {}),
                 ...(event.taskId === undefined ? {} : { taskId: event.taskId }),
@@ -421,6 +601,7 @@ function fleetRows(events) {
         model: channel.model,
         ...(channel.dispatches === 0 ? {} : { dispatches: channel.dispatches }),
         lastEventTime: eventTime(channel.lastTs),
+        lastEventTimestamp: channel.lastTs,
     }));
 }
 /**
@@ -535,15 +716,30 @@ export function deriveRunCockpitData(source, binaryVersion, options = {}) {
     const tipPassed = tipVerificationPassed(events);
     const spotlight = spotlightTask(tasks);
     const samples = bucketedMetricSamples(events);
+    // A task the journal carried somewhere other than done — approved and awaiting
+    // the resume that redispatches it, most of all. `done` is a claim about all of
+    // them, so one outstanding task retires it.
+    const outstanding = taskFacts.some((task) => task.state !== undefined && task.state !== "done");
+    // Parked outranks every reading but failure: a run holding an unresolved
+    // `human` task owes the operator a verb, and the daemon's exit after a park is
+    // the park's own consequence — not an interruption, and never done. A run that
+    // also failed a task owes a fix first, so failure still leads (OBS-252).
+    //
+    // The word is owed on two readings, not one: the parks the fold holds, and
+    // the parks the latest run-end names and nothing since resolved. The second
+    // is what keeps the reading off the luck of a `task-human` line preceding the
+    // run-end — the run's own closing statement is enough.
     const runStatus = failed > 0
         ? "failed"
-        : lifecycle === "superseded" || hasInterruptedTask
-            ? "interrupted"
-            : lifecycle === "completed"
-                ? "done"
-                : interrupted
-                    ? "interrupted"
-                    : "running";
+        : human > 0 || unresolvedSummaryParks(events).length > 0
+            ? "parked"
+            : lifecycle === "superseded" || hasInterruptedTask
+                ? "interrupted"
+                : lifecycle === "completed"
+                    ? outstanding ? "interrupted" : "done"
+                    : interrupted
+                        ? "interrupted"
+                        : "running";
     return {
         binaryVersion,
         runId: source.fileName.replace(/(?:\.interrupted)?\.journal\.jsonl$/, ""),

package/dist/tui/cockpit/layout.d.ts

@@ -87,11 +87,40 @@ export interface FrameState {
     detail?: boolean;
     /** Header caption, pre-measured in terminal cells by the caller. */
     captionCells?: number;
+    /**
+     * The session's panel resize override: the rail columns the operator dragged
+     * the boundary to. An INPUT to the plan, never a bypass of it — the plan
+     * recomputes from the measured size plus this override and the renderer
+     * draws the recomputed plan unmodified. It lives only in the running
+     * process: nothing writes it anywhere, and a relaunch plans the default
+     * layout. The plan clamps it at both panels' readable floors — see
+     * `planRailColumns`.
+     */
+    railColumns?: number;
 }
 export declare const FRAME_WIDTH_FLOOR = 40;
 export declare const FRAME_HEIGHT_FLOOR = 14;
 export declare const SIDEBAR_COLUMN_FLOOR = 64;
 export declare const RAIL_COLUMNS = 15;
+/**
+ * The narrowest rail that still reads: the selection marker, one space and the
+ * longest view name, whole — the name measured in display cells by the width
+ * authority, never String length, so a name that ever gains a wide glyph moves
+ * the floor with it. A drag never takes the rail below it — below the floor
+ * the element stands at the floor, surrendered whole per the contract, never
+ * collapsed.
+ */
+export declare const RAIL_READABLE_FLOOR_COLUMNS: number;
+/**
+ * The rail width the plan draws for a session resize override, clamped at both
+ * panels' readable floors: the rail never narrows past its own floor, and
+ * never widens past what leaves the body its readable floor
+ * (`READABLE_PANEL_COLUMNS`). The clamp is the plan's — the override is a
+ * request, the floors are the contract, and an element is surrendered whole or
+ * not at all, never collapsed by a drag. No override is the contract's
+ * constant rail.
+ */
+export declare function planRailColumns(columns: number, override?: number): number;
 export declare const STANDARD_TAIL_HEIGHT = 16;
 export declare const FULL_TAIL_HEIGHT = 24;
 export declare const TAIL_STANDARD_ROWS = 1;
@@ -127,7 +156,24 @@ export interface FrameFit {
  * ordering decision — not a comment about one.
  */
 export declare const FRAME_SURRENDER_FIT: Readonly<Record<SurrenderedRegionId, (fit: FrameFit) => boolean>>;
-export type FrameRegionId = "header" | "rule" | "strip" | "rail" | "body" | "rule2" | "tail" | "status" | "keybar" | "caption";
+export type FrameRegionId = "header" | "rule" | "strip" | "rail" | "body" | "items" | "rule2" | "tail" | "status" | "keybar" | "caption";
+/**
+ * Border plus horizontal padding the drawn panel charges around its body —
+ * half of it on each side. The plan owns this because the plan owns the item
+ * rows: the paint draws its list into the region planned below, and nothing
+ * downstream subtracts chrome of its own to find it again.
+ */
+export declare const RUN_PANEL_HORIZONTAL_CHROME = 4;
+/**
+ * Row bands drawn INSIDE another band rather than beside it, mapped to the band
+ * that hosts them. A nested band refines its host's rows, so the band walk skips
+ * it when tiling the height and asserts containment instead. It is no less a
+ * member of `rowSpans` for that: the oracle pins its span against the planned
+ * region, and demands the paint register a node at exactly that rectangle —
+ * which is precisely what a parallel field beside the plan could never be held
+ * to.
+ */
+export declare const FRAME_NESTED_ROW_BANDS: Readonly<Partial<Record<FrameRegionId, FrameRegionId>>>;
 /** The vitals elements in block order, top first; a short rail surrenders from the top, so the meter is the last to go. */
 export declare const SIDEBAR_VITALS_ORDER: readonly ["tasks", "gates", "meter"];
 export type SidebarVitalsElement = (typeof SIDEBAR_VITALS_ORDER)[number];
@@ -139,6 +185,13 @@ export declare const SIDEBAR_VITALS_COMPACT_ELEMENT_ROWS = 1;
 export interface SidebarPlan {
     /** Rows the menu block occupies at the rail's top: the five views, plus the label row when it fits. */
     menuRows: number;
+    /**
+     * The frame row each view's name is drawn on. The plan does the menu's
+     * arithmetic once, here, where the label row is decided — so a rail hit is a
+     * lookup in the plan's own rows rather than a second reconstruction of the
+     * menu's shape from `menuRows`.
+     */
+    viewRows: Readonly<Record<FrameView, number>>;
     /**
      * Blank rows between the last menu row and the first vitals row. Never zero
      * while any vitals element draws — a short rail surrenders whole vitals
@@ -157,8 +210,14 @@ export interface SidebarPlan {
  * one gap row is the vitals budget, spent on the full two-row block when it
  * fits whole, else on the one-row elements, surrendered from the top of the
  * block with the meter surrendered last. An element draws whole or not at all.
+ * `railRow` is the frame row the rail band starts at, so the view rows the plan
+ * reports are frame rows a reported cell is compared against directly. It is
+ * required for that reason: a default here would answer rail-relative rows in a
+ * field documented as frame rows — the same defaulted-measurement defect the key
+ * delivery carried, and this one would land in the rows a rail hit resolves
+ * through.
  */
-export declare function planSidebar(railRows: number): SidebarPlan;
+export declare function planSidebar(railRows: number, railRow: number): SidebarPlan;
 export interface FrameRegion {
     id: FrameRegionId;
     row: number;
@@ -182,8 +241,11 @@ export interface PlannedFrame {
     content: FrameBandContent;
     regions: readonly FrameRegion[];
     /**
-     * Row bands, top to bottom; their spans tile the height exactly. A band
-     * map: the nested caption sub-region is deliberately excluded.
+     * Row bands, top to bottom. `items` is nested inside the body band and so
+     * refines it rather than tiling beside it (see FRAME_NESTED_ROW_BANDS); the
+     * remaining spans tile the height exactly. The caption is excluded: it adds
+     * no row extent of its own, being the header's own row refined on the column
+     * axis, and the column map already carries no row.
      */
     rowSpans: Readonly<Record<string, number>>;
     /**
@@ -217,7 +279,9 @@ export type FramePlan = PlannedFrame | PlainFallbackPlan;
  * height exactly — header, rule, the view strip (40–63 columns), the body
  * band, a second rule, the journal tail surrendered whole by height tier,
  * status, keybar — and, at ≥64 columns, column bands that tile the width
- * exactly: the constant 15-column rail beside the body. The body is the sole
+ * exactly: the rail beside the body, at the constant 15 columns or at the
+ * session's dragged override clamped to both panels' readable floors
+ * (`planRailColumns`). The body is the sole
  * flexible element on both axes. The view and state decide what the flexible
  * bands draw (the Journal view is the full-height tail; SETUP turns the tail
  * into PENDING WRITES; an open detail owns the body) without moving any
@@ -231,7 +295,12 @@ export type FramePlan = PlannedFrame | PlainFallbackPlan;
  * of the block, the meter last, rather than closing the gap. rowSpans and
  * columnSpans are band maps: they deliberately exclude the nested caption,
  * and column bands are reported for the body band only, so each map's spans
- * sum to the full height and width respectively.
+ * sum to the full height and width respectively. The body band's item rows are
+ * a band of the plan in their own right — a region in `regions` and a span in
+ * `rowSpans`, nested inside the body band rather than tiling beside it — so the
+ * region the paint draws its list into and the region a pointer resolves a row
+ * through are the one thing the oracle pins, and neither subtracts the drawn
+ * panel's chrome for itself.
  */
 export declare function planFrame(size: MeasuredSize, view?: FrameView, state?: FrameState): FramePlan;
 export declare function resolveCockpitLayout(columns: number, rows: number): CockpitLayout;