@aragon-agent/cli 0.6.38 → 0.6.40

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;

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

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+import { cellWidth, fitCells } from './cells.js';
+import { TASK_SUMMARY_LIMITS } from '../../fast/limits.js';
+export const HEADER_LEFT_LIMITS = {
+    /** The `AragonAgent` word mark, the same 13 `header-hints.ts` documents. */
+    brandCells: 13,
+    /** Blank cells between two left clauses. */
+    gapCells: 2,
+    /** The has-key symbol (1 cell) plus its gap, always reserved. */
+    keyCells: 3,
+    /** Below this the model clause is dropped rather than rendered as `a...`. */
+    modelMinCells: 8,
+    /** Below this the cwd clause is dropped. */
+    cwdMinCells: 8,
+    /** Below this the summary is dropped instead of rendered as `...`. */
+    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.
+     */
+    summaryGapCells: 4,
+};
+/** `provider:model`, the clause `Header` prints after the word mark. */
+export function modelClause(provider, model) {
+    return `${provider}:${model}`;
+}
+/** The directory name, falling back to the whole path for a bare root. */
+export function cwdClause(cwd, basename) {
+    return basename(cwd) || cwd;
+}
+/**
+ * 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 function planHeaderLeft(input) {
+    const leftCells = Number.isFinite(input.leftCells) ? Math.max(0, Math.floor(input.leftCells)) : 0;
+    const empty = {
+        text: { model: '', cwd: '', summary: '' },
+        cells: { model: 0, cwd: 0, summary: 0 },
+        summaryReason: input.summaryEnabled ? 'empty' : 'disabled',
+    };
+    const gap = HEADER_LEFT_LIMITS.gapCells;
+    // Everything the planner never touches, taken off the top so no later step can
+    // borrow from it.
+    // `keyCells` already contains the gap before the symbol, so this is the whole fixed
+    // cost and every clause below pays its own gap.
+    const budget = leftCells - HEADER_LEFT_LIMITS.brandCells - HEADER_LEFT_LIMITS.keyCells;
+    if (budget <= 0) {
+        return {
+            ...empty,
+            summaryReason: input.summaryEnabled
+                ? (input.summary === null ? 'empty' : 'narrow')
+                : 'disabled',
+        };
+    }
+    const model = modelClause(input.provider, input.model);
+    const summaryText = input.summary?.text ?? '';
+    const wantsSummary = input.summaryEnabled && input.summary !== null;
+    /** Desired width and the floor this clause may be cut to. */
+    const clause = (text, floor) => ({
+        want: cellWidth(text),
+        floor: Math.min(cellWidth(text), floor),
+    });
+    const modelWanted = clause(model, HEADER_LEFT_LIMITS.modelMinCells);
+    const cwdWanted = clause(input.cwd, HEADER_LEFT_LIMITS.cwdMinCells);
+    const summaryWanted = {
+        want: Math.min(cellWidth(summaryText), TASK_SUMMARY_LIMITS.maxCells),
+        // A label is never shown below its minimum: a three-cell label is a fragment,
+        // not a label, and the cell is dropped instead.
+        floor: HEADER_LEFT_LIMITS.summaryMinCells,
+    };
+    const sets = [
+        ['model', 'cwd', ...(wantsSummary ? ['summary'] : [])],
+        ['model', 'cwd'],
+        ['model'],
+        [],
+    ];
+    const wanted = { model: modelWanted, cwd: cwdWanted, summary: summaryWanted };
+    for (const set of sets) {
+        const assigned = fitClauses(set, wanted, budget, gap);
+        if (assigned === null)
+            continue;
+        const modelCells = assigned.model ?? 0;
+        const cwdCells = assigned.cwd ?? 0;
+        const summaryCells = assigned.summary ?? 0;
+        let summaryReason = 'empty';
+        if (!input.summaryEnabled)
+            summaryReason = 'disabled';
+        else if (input.summary === null)
+            summaryReason = 'empty';
+        else if (summaryCells === 0)
+            summaryReason = 'narrow';
+        else
+            summaryReason = 'ok';
+        return {
+            text: {
+                model: modelCells > 0 ? fitCells(model, modelCells, input.ellipsis) : '',
+                cwd: cwdCells > 0 ? fitCells(input.cwd, cwdCells, input.ellipsis) : '',
+                summary: summaryCells > 0 ? fitCells(summaryText, summaryCells, input.ellipsis) : '',
+            },
+            cells: { model: modelCells, cwd: cwdCells, summary: summaryCells },
+            summaryReason,
+        };
+    }
+    return empty;
+}
+/**
+ * Fit one presence set into `budget`, cutting from the LAST clause inward.
+ *
+ * Returns `null` when the set cannot fit even at every clause's floor, which is the
+ * signal to try the next (smaller) set. `null` rather than a partial result because
+ * "the summary was dropped" and "the summary does not fit" must be the same fact to
+ * the caller, and only the set composition may express it.
+ */
+function fitClauses(set, wanted, budget, gap) {
+    const widths = { model: 0, cwd: 0, summary: 0 };
+    let cost = 0;
+    for (const key of set) {
+        widths[key] = wanted[key].want;
+        // EVERY CLAUSE PAYS ITS OWN SEPARATOR, including the first: the row renders
+        // `word mark, gap, clause, gap, clause, gap, key`, so a one-clause plan still
+        // spends a gap on each side of that clause.
+        cost += (key === 'summary' ? HEADER_LEFT_LIMITS.summaryGapCells : gap)
+            + wanted[key].want;
+    }
+    let excess = cost - budget;
+    for (let index = set.length - 1; index >= 0 && excess > 0; index -= 1) {
+        const key = set[index];
+        const room = widths[key] - wanted[key].floor;
+        if (room <= 0)
+            continue;
+        const cut = Math.min(room, excess);
+        widths[key] -= cut;
+        excess -= cut;
+    }
+    return excess > 0 ? null : widths;
+}
+/**
+ * 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 function planHeaderLeftCells(plan) {
+    const { gapCells, brandCells, keyCells, summaryGapCells } = HEADER_LEFT_LIMITS;
+    // The word mark and the key symbol are always drawn; every clause pays its own gap.
+    // The gap before the key is INSIDE `keyCells`, so it is counted once here and never
+    // again after a clause - the double count that made a one-clause plan read two cells
+    // wider than it renders.
+    let cells = brandCells + keyCells;
+    if (plan.cells.model > 0)
+        cells += gapCells + plan.cells.model;
+    if (plan.cells.cwd > 0)
+        cells += gapCells + plan.cells.cwd;
+    // The summary's separator carries the dot, so it is wider than the general gap.
+    if (plan.cells.summary > 0)
+        cells += summaryGapCells + plan.cells.summary;
+    return cells;
+}
+/**
+ * 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 const HEADER_LEFT_BASELINE = HEADER_LEFT_LIMITS.brandCells
+    + HEADER_LEFT_LIMITS.keyCells;