@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/ui/layout/header-hints.d.ts

@@ -1,25 +1,21 @@
 /**
- * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ * The right-hand hint budget for the header row
+ * (tui-shortcut-drawer-and-task-summary §4.2).
  *
  * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
  *
- * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
- * right side used to be one hand-computed width constant (`detailCells = indexHint
- * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
- * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
- * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
- * already set the precedent for the same problem: the chip has to participate in
- * one width budget rather than be appended and hoped for.
+ * THIS FILE USED TO BE A SIX-RUNG LADDER. `^L branch`, `^P prompts`, `^I Index`,
+ * `^K switch kit`, `^G more` and the expanded variants competed for a width
+ * budget, so what a user saw was not "my shortcuts" but "which clauses happen to
+ * fit at this width" - and on an 80-column terminal that was three of six. The
+ * requirement replaces the whole idea with ONE entry point (`ctrl+G more`) whose
+ * panel lists every shortcut, so the ladder is gone and what remains is a
+ * three-state single clause.
  *
- * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
- * first ladder rung whose `cells` fits. There is no second magic constant, and the
- * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
- * branch.
- *
- * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
- * the key symbol need at least 11 more to stay readable. It is lower than
- * `status-layout`'s 34 because the top-left half has a brand to lose while the
- * bottom-left half has a phase that must not disappear.
+ * WHY A PLANNER AND NOT A TERNARY IN THE JSX (R-0-4, unchanged): the header's
+ * right side was once one hand-computed width constant, and every later addition
+ * to it produced either a clipped hint or a pushed-out word mark with no test
+ * able to see it - the only thing lost is trailing characters.
  */
 /**
  * Bounds for the hint budget.
@@ -27,71 +23,68 @@
  * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
  * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
  * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
- * This module has exactly one consumer. If `ui/layout/` ever grows a real
- * `limits.ts`, these three constants should move there together; this comment is
- * that future migration's note.
  */
 export declare const HEADER_HINT_LIMITS: {
-    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    /**
+     * Cells the LEFT half of the header must keep.
+     *
+     * 24 = the 13-cell word mark plus at least 11 for `provider:model`, the
+     * directory and the key symbol. Lower than `status-layout`'s 34 because the top
+     * row has a brand to lose while the bottom row has a phase that must not
+     * disappear.
+     */
     readonly minLeftCells: 24;
-    /** Fixed spacing between two hint clauses. */
-    readonly gapCells: 2;
     /**
      * Blank cells between the header's left half and this hint column (defect 12).
      *
-     * A SEPARATE CONSTANT FROM `gapCells`. That one spaces two hint clauses INSIDE
-     * the right column (`buildPlan` below); this one separates the session
-     * description from that column. One constant carrying two meanings is how a
-     * later change to clause spacing silently re-lays-out the whole row.
+     * A SEPARATE CONCEPT FROM CLAUSE SPACING: this one separates the two HALVES of
+     * the row, and it is spent out of the same `columns` budget so the row still
+     * spans exactly the terminal width.
      */
     readonly separatorCells: 2;
 };
-export type HeaderHintId = 'branch' | 'prompts' | 'index' | 'kit' | 'detail';
-export interface HeaderHintClause {
-    id: HeaderHintId;
-    text: string;
-}
+/**
+ * What the right-hand column says. THREE STATES, NO LADDER.
+ *
+ * `none`      - no overlay: `^G more`, the only shortcut hint the header teaches.
+ * `shortcuts` - this panel is open: `^G close`, the key that closes it.
+ * `other`     - some other overlay owns the keyboard: `Esc close`, which is true
+ *               for every overlay and is the only key that works in all of them.
+ */
+export type HeaderPanelState = 'none' | 'shortcuts' | 'other';
 export interface HeaderHintPlan {
-    /** Clauses left to right (including the overlay's `Details on/off` replacement). */
-    clauses: HeaderHintClause[];
     /** The whole right-hand string, scroll chip included with its trailing spacing. */
     text: string;
-    /** Total cells of the right column; `Header` uses it to size the left one. */
+    /** Total cells of the right column; `Header` sizes the left one from it. */
     cells: number;
     /** Cells taken by the scroll chip (0 when there is none). */
     scrollCells: number;
-    /** True while an overlay owns the keyboard: only the detail word remains. */
-    detailsOnly: boolean;
 }
+/** The verbatim text of each state. Exported so a test can name it instead of guessing. */
+export declare const HEADER_HINTS: Readonly<Record<HeaderPanelState, string>>;
 /**
- * Plan the right-hand hints.
+ * Plan the right-hand hint.
  *
- * The inputs are the props `Header` receives plus the two switches that decide which
- * clauses exist at all - the call site does not change, only the arithmetic behind it
- * (spec 3.11 step 5).
+ * NO WIDTH BRANCHING: the clause is always rendered. When the row cannot hold it
+ * the LEFT half is what shrinks (to zero) and `overflow="hidden"` keeps that from
+ * spilling - the pre-feature behaviour, which is what makes the header safe at 20
+ * columns without a ladder. `headerHintFits` below exists only so the threshold
+ * is documented and testable, not so the renderer can branch on it.
  */
 export declare function planHeaderHints(input: {
     columns: number;
-    statusExpanded: boolean;
-    overlayOpen: boolean;
+    panel: HeaderPanelState;
     scrolledLines: number;
-    /**
-     * Whether the `^K switch kit` clause exists at all (default `true`).
-     *
-     * `App` ALWAYS PASSES TRUE, including for a user with no kits: the whole point
-     * of the requirement is discoverability of `ctrl+K`, and an empty library is
-     * exactly the state that needs it (the picker's own `No kits yet` row tells
-     * them where to create one). `false` exists for tests and for the future
-     * switch, and it degrades the six expanded rungs back into today's four.
-     */
-    kitHint?: boolean;
-    /**
-     * Whether the `^P prompts` clause exists at all (default `true`).
-     *
-     * `false` is the `prompts.hint` config key and the only reason the ladder is
-     * parameterised: a user who turned the header hint off must get exactly the row
-     * they had before this feature, which is what the unfiltered ladder below
-     * degenerates into.
-     */
-    promptsHint?: boolean;
 }): HeaderHintPlan;
+/**
+ * Whether the row can hold the hint column without squeezing the left half below
+ * `minLeftCells`.
+ *
+ * A FORMULA, NOT A TABLE OF MAGIC NUMBERS: `columns - minLeftCells -
+ * separatorCells >= scrollCells + bodyCells`. Substituting the three states gives
+ * 32 / 34 / 35 columns with no chip, plus up to 8 more for a saturated `^9999+ `.
+ * v1 claimed "any width >= 35", which forgot the chip entirely.
+ */
+export declare function headerHintFits(columns: number, panel: HeaderPanelState): boolean;
+/** The narrowest width at which each state fits with no scroll chip. */
+export declare function headerHintThreshold(panel: HeaderPanelState): number;

package/dist/ui/layout/header-hints.js

@@ -1,25 +1,21 @@
 /**
- * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ * The right-hand hint budget for the header row
+ * (tui-shortcut-drawer-and-task-summary §4.2).
  *
  * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
  *
- * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
- * right side used to be one hand-computed width constant (`detailCells = indexHint
- * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
- * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
- * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
- * already set the precedent for the same problem: the chip has to participate in
- * one width budget rather than be appended and hoped for.
+ * THIS FILE USED TO BE A SIX-RUNG LADDER. `^L branch`, `^P prompts`, `^I Index`,
+ * `^K switch kit`, `^G more` and the expanded variants competed for a width
+ * budget, so what a user saw was not "my shortcuts" but "which clauses happen to
+ * fit at this width" - and on an 80-column terminal that was three of six. The
+ * requirement replaces the whole idea with ONE entry point (`ctrl+G more`) whose
+ * panel lists every shortcut, so the ladder is gone and what remains is a
+ * three-state single clause.
  *
- * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
- * first ladder rung whose `cells` fits. There is no second magic constant, and the
- * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
- * branch.
- *
- * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
- * the key symbol need at least 11 more to stay readable. It is lower than
- * `status-layout`'s 34 because the top-left half has a brand to lose while the
- * bottom-left half has a phase that must not disappear.
+ * WHY A PLANNER AND NOT A TERNARY IN THE JSX (R-0-4, unchanged): the header's
+ * right side was once one hand-computed width constant, and every later addition
+ * to it produced either a clipped hint or a pushed-out word mark with no test
+ * able to see it - the only thing lost is trailing characters.
  */
 /**
  * Bounds for the hint budget.
@@ -27,183 +23,80 @@
  * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
  * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
  * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
- * This module has exactly one consumer. If `ui/layout/` ever grows a real
- * `limits.ts`, these three constants should move there together; this comment is
- * that future migration's note.
  */
 export const HEADER_HINT_LIMITS = {
-    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    /**
+     * Cells the LEFT half of the header must keep.
+     *
+     * 24 = the 13-cell word mark plus at least 11 for `provider:model`, the
+     * directory and the key symbol. Lower than `status-layout`'s 34 because the top
+     * row has a brand to lose while the bottom row has a phase that must not
+     * disappear.
+     */
     minLeftCells: 24,
-    /** Fixed spacing between two hint clauses. */
-    gapCells: 2,
     /**
      * Blank cells between the header's left half and this hint column (defect 12).
      *
-     * A SEPARATE CONSTANT FROM `gapCells`. That one spaces two hint clauses INSIDE
-     * the right column (`buildPlan` below); this one separates the session
-     * description from that column. One constant carrying two meanings is how a
-     * later change to clause spacing silently re-lays-out the whole row.
+     * A SEPARATE CONCEPT FROM CLAUSE SPACING: this one separates the two HALVES of
+     * the row, and it is spent out of the same `columns` budget so the row still
+     * spans exactly the terminal width.
      */
     separatorCells: 2,
 };
-/** The verbatim clause text (spec 3.8, appendix A). */
-const BRANCH_CLAUSE = { collapsed: '^L branch', expanded: '^L new branch' };
-const INDEX_CLAUSE = { collapsed: '^I Index', expanded: '^I build index' };
-/**
- * THE KIT CLAUSE HAS NO COLLAPSED FORM (agent-model-kits D-11).
- *
- * The requirement says the `ctrl+k` hint appears AFTER `ctrl+G`; the collapsed
- * row is the narrowest budget in the header, and `^K` is a low-frequency action.
- * Spending 13 columns of the everyday row on it would push `provider:model`
- * leftward on every launch for a key pressed twice a session.
- */
-const KIT_CLAUSE = { expanded: '^K switch kit' };
-/**
- * THE PROMPT LIBRARY KEY HAS EXACTLY ONE FORM, AND IT IS THE SHORT ONE
- * (quick-prompt-library D-15).
- *
- * `^P` is a REQUIREMENT (the user must be able to see that `ctrl+P` exists), and
- * the collapsed row is where that requirement is met. The expanded row's job is to
- * reveal MORE keys than the collapsed one, so inserting a 17-cell
- * `^P prompt library` before `^I` there would trade `^I` and `^K` away on an
- * 80-column terminal - a user who pressed `^G` asking for more would be shown less.
- *
- * The second thing this constant's position encodes is an explicit REVISION of the
- * `RV-P1-2` ordering constraint for the COLLAPSED ladder: `^P` sits before `^I`
- * there, so `^I Index` now appears from 66 columns instead of 54. That is a
- * deliberate, documented loss: `^I` is a once-per-project action and `^P` is the
- * entry point this feature is about. The expanded ladder keeps its full existing
- * order, so `RV-P1-2` still holds there and `^I` never disappears from a row where
- * it used to fit.
- */
-const PROMPTS_CLAUSE = '^P prompts';
-const DETAIL_CLAUSE = { collapsed: '^G more', expanded: '^G less' };
-/** L3 gives the key name and nothing else: discoverability at the last width. */
-const BRANCH_KEY_ONLY = '^L';
-/** Overlay wording, kept exactly as `Header.tsx` had it. */
-const DETAILS_ON = 'Details on';
-const DETAILS_OFF = 'Details off';
+/** The verbatim text of each state. Exported so a test can name it instead of guessing. */
+export const HEADER_HINTS = {
+    none: '^G more',
+    shortcuts: '^G close',
+    other: 'Esc close',
+};
 /** Above this, the chip stops counting and saturates (`^9999+`), as it always has. */
 const SCROLL_CHIP_MAX = 9999;
 /**
- * Plan the right-hand hints.
+ * Plan the right-hand hint.
  *
- * The inputs are the props `Header` receives plus the two switches that decide which
- * clauses exist at all - the call site does not change, only the arithmetic behind it
- * (spec 3.11 step 5).
+ * NO WIDTH BRANCHING: the clause is always rendered. When the row cannot hold it
+ * the LEFT half is what shrinks (to zero) and `overflow="hidden"` keeps that from
+ * spilling - the pre-feature behaviour, which is what makes the header safe at 20
+ * columns without a ladder. `headerHintFits` below exists only so the threshold
+ * is documented and testable, not so the renderer can branch on it.
  */
 export function planHeaderHints(input) {
-    // NORMALISED HERE, NOT TRUSTED (R-14). `Header` defaults to 80, but a test or a
-    // future caller may pass anything; `budget.ts::dimension()` already set the rule
-    // (non-finite or < 1 falls back, everything else floors) and this follows it.
     const columns = normalizeDimension(input.columns, 80);
     const scrolledLines = Math.max(0, Math.floor(normalizeDimension(input.scrolledLines, 0)));
-    const scrollCells = scrollChip(scrolledLines, input.overlayOpen);
-    if (input.overlayOpen) {
-        // THE OVERLAY OWNS THE KEYBOARD, so every key hint disappears (D-14's sibling
-        // rule, unchanged from the old JSX). The scroll chip stays: it is a position
-        // indicator, not an affordance.
-        const detail = input.statusExpanded ? DETAILS_ON : DETAILS_OFF;
-        return buildPlan([{ id: 'detail', text: detail }], scrollCells, true);
-    }
-    const ladder = ladderFor(input.statusExpanded, input.kitHint !== false, input.promptsHint !== false);
-    // THE SEPARATOR IS SPENT OUT OF THE SAME ROW (defect 12): left half + gap + this
-    // column have to add up to `columns`, so the gap comes off the budget instead of
-    // being assumed free.
-    const budget = columns - HEADER_HINT_LIMITS.minLeftCells
-        - HEADER_HINT_LIMITS.separatorCells;
-    for (const rung of ladder) {
-        const plan = buildPlan(rung, scrollCells, false);
-        if (plan.cells <= budget)
-            return plan;
-    }
-    // L4 IS UNCONDITIONAL: `^G` is the only entry in this table that may never be
-    // dropped - it is how a user who hid the status detail fields gets them back.
-    // A header narrower than the last rung still renders; the LEFT column is what
-    // shrinks (to zero), and `overflow="hidden"` keeps that from overflowing.
-    return buildPlan(ladder[ladder.length - 1] ?? [], scrollCells, false);
+    const overlayOpen = input.panel !== 'none';
+    const chip = scrollChip(scrolledLines, overlayOpen);
+    const body = HEADER_HINTS[input.panel] ?? HEADER_HINTS.none;
+    const text = chip.length > 0 ? `${chip}${body}` : body;
+    return { text, cells: text.length, scrollCells: chip.length };
 }
 /**
- * The rungs, widest first. Built per call because the widths are text-derived.
+ * Whether the row can hold the hint column without squeezing the left half below
+ * `minLeftCells`.
  *
- * THE EXPANDED ORDER `branch -> index -> kit -> detail` IS A REGRESSION
- * CONSTRAINT, NOT A PREFERENCE (RV-P1-2). With `kit` AFTER `index`, rungs E2,
- * E4, E5 and E6 are exactly today's four expanded rungs, so every existing
- * width assertion for 48-78 columns keeps its old answer and `^I` never
- * disappears from a row where it used to fit. Putting `^K` first would have cost
- * `^I` everything from 64 to 78 columns - a permanent loss, paid for a
- * low-frequency key.
+ * A FORMULA, NOT A TABLE OF MAGIC NUMBERS: `columns - minLeftCells -
+ * separatorCells >= scrollCells + bodyCells`. Substituting the three states gives
+ * 32 / 34 / 35 columns with no chip, plus up to 8 more for a saturated `^9999+ `.
+ * v1 claimed "any width >= 35", which forgot the chip entirely.
  */
-function ladderFor(statusExpanded, kitHint, promptsHint) {
-    const branch = {
-        id: 'branch',
-        text: statusExpanded ? BRANCH_CLAUSE.expanded : BRANCH_CLAUSE.collapsed,
-    };
-    const index = {
-        id: 'index',
-        text: statusExpanded ? INDEX_CLAUSE.expanded : INDEX_CLAUSE.collapsed,
-    };
-    const detail = {
-        id: 'detail',
-        text: statusExpanded ? DETAIL_CLAUSE.expanded : DETAIL_CLAUSE.collapsed,
-    };
-    const branchKey = { id: 'branch', text: BRANCH_KEY_ONLY };
-    const prompts = { id: 'prompts', text: PROMPTS_CLAUSE };
-    const kit = { id: 'kit', text: KIT_CLAUSE.expanded };
-    // THE LADDERS ARE WRITTEN WITH EVERY CLAUSE IN PLACE AND THEN FILTERED, rather
-    // than branched per width. Two independently written tables drift: the day one of
-    // them gains a rung, the `prompts.hint=false` / `kitHint=false` degradations stop
-    // being "the same row minus that clause" and nothing would notice. Filtering a
-    // single table makes that property structural.
-    const keep = (clause) => (promptsHint || clause.id !== 'prompts') && (kitHint || clause.id !== 'kit');
-    // COLLAPSED (six rungs). `^P prompts` sits between the branch and the index, and
-    // the third rung is where `^L` loses its label in favour of `^P` - see the note
-    // on `PROMPTS_CLAUSE` above for the revision of `RV-P1-2` this encodes.
-    const collapsed = [
-        [branch, prompts, index, detail],
-        [branch, prompts, detail],
-        [branchKey, prompts, detail],
-        [branch, detail],
-        [branchKey, detail],
-        [detail],
-    ];
-    // EXPANDED (seven rungs). `^P` appears in the WIDEST rung only, and AFTER `^K`,
-    // so E2..E7 - the rungs that decide what a 34..90 column terminal shows - are
-    // byte-identical to the pre-feature answers.
-    const expanded = [
-        [branch, index, kit, prompts, detail],
-        [branch, index, kit, detail],
-        [branch, index, detail],
-        [branch, kit, detail],
-        [branch, detail],
-        [branchKey, detail],
-        [detail],
-    ];
-    return (statusExpanded ? expanded : collapsed).map((rung) => rung.filter(keep));
+export function headerHintFits(columns, panel) {
+    const cols = normalizeDimension(columns, 80);
+    const plan = planHeaderHints({ columns: cols, panel, scrolledLines: 0 });
+    return cols - HEADER_HINT_LIMITS.minLeftCells - HEADER_HINT_LIMITS.separatorCells
+        >= plan.cells;
 }
-/**
- * Compose the final string. The chip carries its OWN trailing spacing and is the
- * only source of it (R-8): one space while an overlay is open, two otherwise -
- * copied byte for byte from the expression the header already used.
- */
-function buildPlan(clauses, scrollChipText, detailsOnly) {
-    const body = clauses.map((clause) => clause.text).join(' '.repeat(HEADER_HINT_LIMITS.gapCells));
-    const text = scrollChipText.length > 0 ? `${scrollChipText}${body}` : body;
-    return {
-        clauses,
-        text,
-        cells: text.length,
-        scrollCells: scrollChipText.length,
-        detailsOnly,
-    };
+/** The narrowest width at which each state fits with no scroll chip. */
+export function headerHintThreshold(panel) {
+    return HEADER_HINTS[panel].length
+        + HEADER_HINT_LIMITS.minLeftCells
+        + HEADER_HINT_LIMITS.separatorCells;
 }
 /**
  * `^<n>` plus its trailing spacing, or `''`.
  *
  * THE SPACING IS PART OF THE CHIP, not something `Header` adds afterwards: with two
  * sources of spacing a reviewer has to read two files to answer "how wide is the
- * chip", and the overlay's single-space case lived in the JSX as a ternary nobody
- * would think to check.
+ * chip". One space while an overlay is open, two otherwise - copied byte for byte
+ * from the expression the header already used.
  */
 function scrollChip(scrolledLines, overlayOpen) {
     if (scrolledLines <= 0)

package/dist/ui/layout/header-left.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The header's LEFT half budget (tui-shortcut-drawer-and-task-summary §4.3).
+ *
+ * ASCII ONLY: `src/ui/**` is inside the glyph scanner's scope.
+ *
+ * WHY A PLANNER (the same argument `header-hints.ts` makes one file over): the
+ * left half used to be a `<Text wrap="truncate">` over four clauses with no
+ * clause-level arithmetic anywhere, so the only thing that ever decided what got
+ * cut was the terminal. Adding a fifth clause - the task summary - to that shape
+ * produces a header where the summary silently eats the directory name on an
+ * 80-column terminal and NO ASSERTION WOULD SEE IT, because losing trailing
+ * characters is invisible to a snapshot test.
+ *
+ * THE PRIORITY ORDER IS THE DESIGN: brand, then `provider:model`, then cwd, then
+ * the summary, with the key symbol reserved up front. The summary is the only
+ * clause that is allowed to disappear entirely - it is the newest and the least
+ * load-bearing (D-2) - and it is dropped rather than rendered as `...`, because a
+ * cell holding three dots spends eight columns to say nothing.
+ */
+export declare const HEADER_LEFT_LIMITS: {
+    /** The `AragonAgent` word mark, the same 13 `header-hints.ts` documents. */
+    readonly brandCells: 13;
+    /** Blank cells between two left clauses. */
+    readonly gapCells: 2;
+    /** The has-key symbol (1 cell) plus its gap, always reserved. */
+    readonly keyCells: 3;
+    /** Below this the model clause is dropped rather than rendered as `a...`. */
+    readonly modelMinCells: 8;
+    /** Below this the cwd clause is dropped. */
+    readonly cwdMinCells: 8;
+    /** Below this the summary is dropped instead of rendered as `...`. */
+    readonly summaryMinCells: 8;
+    /**
+     * The separator that belongs to the SUMMARY rather than to the general gap:
+     * two spaces, the mid dot and one space. It is reserved together with the label
+     * so a summary can never be drawn without its dot, or the dot without it.
+     */
+    readonly summaryGapCells: 4;
+};
+export interface HeaderLeftPlan {
+    text: {
+        model: string;
+        cwd: string;
+        summary: string;
+    };
+    cells: {
+        model: number;
+        cwd: number;
+        summary: number;
+    };
+    /**
+     * Why the summary cell is empty. `pending` is not a reason: a pending summary
+     * draws nothing at all, so the plan is indistinguishable from `empty` - which
+     * is exactly what removed the v1 layout jitter on the first submit.
+     */
+    summaryReason: 'ok' | 'empty' | 'narrow' | 'disabled';
+}
+export interface HeaderLeftInput {
+    /** Cells the header gives the left half (`columns - hintCells - separatorCells`). */
+    leftCells: number;
+    provider: string;
+    model: string;
+    cwd: string;
+    hasKey: boolean;
+    /** `null` while pending, empty or disabled - the planner never sees a placeholder. */
+    summary: {
+        text: string;
+        tone: 'model' | 'fallback';
+    } | null;
+    summaryEnabled: boolean;
+    ellipsis: string;
+}
+/** `provider:model`, the clause `Header` prints after the word mark. */
+export declare function modelClause(provider: string, model: string): string;
+/** The directory name, falling back to the whole path for a bare root. */
+export declare function cwdClause(cwd: string, basename: (path: string) => string): string;
+/**
+ * Allocate the left half.
+ *
+ * THE ORDER OF THE FOUR STEPS IS THE PRIORITY (D-2):
+ *  1. reserve the word mark, its gap and the key symbol - they are never cut;
+ *  2. `provider:model`, down to `modelMinCells`, then dropped;
+ *  3. cwd, down to `cwdMinCells`, then dropped;
+ *  4. the summary, capped at `TASK_SUMMARY_LIMITS.maxCells`, dropped below
+ *     `summaryMinCells` and reported as `narrow`.
+ *
+ * THE LADDER IS EXPLICIT RATHER THAN GREEDY, and that is a correction to v2's
+ * algorithm, which funded the summary out of the reserved budget and could therefore
+ * show a label on a row where the model name had already been dropped. Four
+ * presence sets are tried from most to least complete; within a set the LAST clause
+ * gives way first, each only down to its own minimum. The first set that fits wins.
+ *
+ * Every returned text already MEASURES its reported width, so `Header` renders
+ * cells rather than hoping for them.
+ */
+export declare function planHeaderLeft(input: HeaderLeftInput): HeaderLeftPlan;
+/**
+ * Cells the plan actually spends, for the row invariant:
+ * `brand + gap + model + gap + cwd + gap + summary + key <= leftCells`.
+ *
+ * Exported so `header-left.test.ts` can assert the inequality against the SAME
+ * arithmetic the renderer uses instead of re-deriving it in the test (which is how
+ * the two drift apart).
+ */
+export declare function planHeaderLeftCells(plan: HeaderLeftPlan): number;
+/**
+ * The fixed cells a plan needs before any clause can appear: the word mark plus the
+ * key symbol and its gap.
+ *
+ * Below this the row does not "spend too much", it simply cannot show a clause - the
+ * renderer truncates the overflow and `Header`'s own `wrap="truncate"` keeps that from
+ * spilling. Stating it as a constant keeps the invariant in the tests honest:
+ * `planHeaderLeftCells(plan) <= max(leftCells, HEADER_LEFT_BASELINE)`.
+ */
+export declare const HEADER_LEFT_BASELINE: number;