@neosh/api 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neosh/api",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "The neosh plugin API. Types are generated from the Rust side and drift-checked in CI.",
   "license": "MIT",
   "type": "module",

package/src/generated/ApiCall.ts

@@ -32,6 +32,7 @@ import type { ProjectKey } from "./ProjectKey";
 import type { ProviderEvent } from "./ProviderEvent";
 import type { QuotaSnapshot } from "./QuotaSnapshot";
 import type { Rect } from "./Rect";
+import type { ScrollAmount } from "./ScrollAmount";
 import type { SelectShape } from "./SelectShape";
 import type { SessionId } from "./SessionId";
 import type { StatusSegment } from "./StatusSegment";
@@ -113,6 +114,7 @@ export type ApiCall =
   | { "call": "win_set_cursor"; win: WindowId; row: number; col: number }
   | { "call": "win_get_viewport"; win: WindowId }
   | { "call": "win_scroll_to"; win: WindowId; top_line: number | null }
+  | { "call": "win_scroll"; win: WindowId; amount: ScrollAmount }
   | { "call": "win_list" }
   | {
     "call": "pane_split";
@@ -478,12 +480,37 @@ export type ApiCall =
   | { "call": "git_stage"; paths: Array<string> }
   | { "call": "git_unstage"; paths: Array<string> }
   | { "call": "git_commit"; message: string }
+  | {
+    "call": "git_fetch";
+    /**
+     * The repository to fetch in. The conversation's own when absent.
+     */
+    cwd?: string | null;
+  }
   | {
     "call": "git_pull";
     /**
      * The repository to pull in. The conversation's own when absent.
      */
     cwd?: string | null;
+    /**
+     * Replay this branch's own commits on top of what arrived, rather than merging.
+     *
+     * A flag rather than a call of its own because it is one argument to one command, and the
+     * caller that needs it is the one that has just been told the branch diverged — at which
+     * point "rebase or merge" is the question being answered, and two entry points for the two
+     * answers would be two things to keep in step for no gain.
+     *
+     * It rewrites local commits, which is why nothing sets it without asking first.
+     */
+    rebase: boolean;
+  }
+  | {
+    "call": "forge_pulls";
+    /**
+     * The repository to ask about. The conversation's own when absent.
+     */
+    cwd?: string | null;
   }
   | {
     "call": "git_add_worktree";
@@ -507,6 +534,32 @@ export type ApiCall =
      */
     cwd?: string | null;
   }
+  | {
+    "call": "git_clone";
+    /**
+     * Anything `git clone` takes: an `https://` or `git@` URL, or a local path.
+     */
+    url: string;
+    /**
+     * Where the working tree lands, in full. The caller resolved the root and the name, so
+     * that a picker can *show* the destination on the row before anything is written.
+     */
+    path: string;
+  }
+  | {
+    "call": "git_move_worktree";
+    path: string;
+    /**
+     * Where it lands, in full. The leaf must not exist; the parent is created.
+     */
+    dest: string;
+    /**
+     * The repository it belongs to. `git worktree move` runs from a checkout, and the
+     * conversation the caller is in may be standing in the one being moved — the same reason
+     * [`Self::GitRemoveWorktree`] takes one.
+     */
+    cwd?: string | null;
+  }
   | {
     "call": "gen_complete";
     prompt: string;
@@ -515,6 +568,30 @@ export type ApiCall =
      * Ask for JSON and parse it host-side, tolerating the code fences models wrap it in.
      */
     json: boolean;
+    /**
+     * The one key the answer is *about*, when the whole answer is one value.
+     *
+     * A prompt that says "return `{"branch": …}`" is answered with the object most of the
+     * time and with a bare `fix/composer-paste` the rest of it — the model did the work and
+     * skipped the envelope, and a caller that only accepts the envelope throws a correct
+     * answer away. Measured on this workspace's own history it was two runs in twenty-two:
+     * twice a branch was never named, silently, and both times the name was sitting in the
+     * reply.
+     *
+     * So: extraction first, exactly as before, and this is what a *bare* answer means. Named
+     * rather than inferred, because only the caller knows which key one value belongs under
+     * — and absent, nothing changes, which is what every existing caller wants.
+     *
+     * Only for a one-value answer. A commit message is a subject *and* a body, and guessing
+     * which half a bare paragraph is would be inventing the other one.
+     *
+     * And only for a value a *wrong* answer is recognisable in. A branch name is checkable
+     * and one `git branch -m` from being fixed; a thread title is any short line, which is
+     * also what a refusal and a driver's own error message look like — there the envelope is
+     * the only evidence the question was answered rather than commented on, and it is worth
+     * the one reply in ten that arrives without it.
+     */
+    field?: string | null;
     /**
      * Defaults to `gen.model` if set, else the session's own selection.
      */

package/src/generated/ApiOk.ts

@@ -25,6 +25,7 @@ import type { PermissionDecision } from "./PermissionDecision";
 import type { PermissionMode } from "./PermissionMode";
 import type { PluginInfo } from "./PluginInfo";
 import type { PointInfo } from "./PointInfo";
+import type { PullRequest } from "./PullRequest";
 import type { QuestionAnswer } from "./QuestionAnswer";
 import type { QuotaSample } from "./QuotaSample";
 import type { QuotaSnapshot } from "./QuotaSnapshot";
@@ -92,6 +93,7 @@ export type ApiOk =
   | { "ok": "status"; status: RepoStatus }
   | { "ok": "branches"; branches: Array<BranchInfo> }
   | { "ok": "worktrees"; worktrees: Array<WorktreeInfo> }
+  | { "ok": "pulls"; pulls: Array<PullRequest> }
   | { "ok": "commits"; commits: Array<CommitInfo> }
   | { "ok": "commit"; commit: CommitInfo }
   | { "ok": "text"; text: string }

package/src/generated/ChecksState.ts

@@ -0,0 +1,14 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * What the forge's checks say, folded to the one thing a row has room for.
+ *
+ * Folded here rather than on the wire as a list, because the question a project row answers is
+ * "is anything wrong" and the answer is one glyph. The counts travel beside it for whoever wants
+ * to say `✗2`; the full list of check names is a panel's job and a different call.
+ *
+ * `Pending` and `None` are deliberately different. Nothing has run yet is a state that resolves on
+ * its own in a few minutes; there are no checks configured at all is permanent, and drawing a
+ * spinner over it for ever is the failure this distinction avoids.
+ */
+export type ChecksState = "none" | "pending" | "passing" | "failing";

package/src/generated/FloatConfig.ts

@@ -23,6 +23,17 @@ export type FloatConfig = {
    */
   border_hl?: string | null;
   title?: string | null;
+  /**
+   * A strip on the bottom border: what the keys here do.
+   *
+   * On the border rather than in the buffer, because a key strip written as a row of content is
+   * one that scrolls away exactly when it is wanted, and is the first thing clipped on a terminal
+   * too short for the panel. Both of those happened: the picker's strip is the row that says how
+   * to get out, and on a sixteen-row screen it was the row that did not fit.
+   *
+   * Clipped to the border's width like the title, so it is for a legend and not for prose.
+   */
+  footer?: string | null;
   /**
    * Close automatically when focus moves elsewhere. The right default for pickers and hovers.
    */
@@ -60,4 +71,26 @@ export type FloatConfig = {
    * characters through to the composer would be typing into a field you cannot see.
    */
   modal: boolean;
+  /**
+   * This panel is a place you can move in when it does not fit.
+   *
+   * A float asks for a height and the frontend gives it what there is — so on a short terminal
+   * every row past the bottom edge is content that exists, is drawn nowhere, and has no key
+   * pointed at it. `height: Max { n: 30 }` on a twenty-row screen is not thirty rows of panel, it
+   * is ten rows of panel and twenty rows nobody can reach.
+   *
+   * Setting this adds one scope to the keymap chain while this float has focus —
+   * `BufKind { name: "neosh.scroll" }` — which is where the workspace binds the reader's motions:
+   * `j`/`k`, `<C-d>`/`<C-u>`, `<C-f>`/`<C-b>`, `gg`/`G`, the arrows and the paging keys. A scope
+   * rather than a capture, so all three of the usual rules hold: `^Z` lists the keys, `init.ts`
+   * moves them, and a panel that wants `j` for something of its own binds it on *its* kind, which
+   * is nearer and wins. It sits below the panel's own kind and above `Global`, so it is a default
+   * that never takes a key away from the thing it is scrolling.
+   *
+   * Off by default, and not for want of ambition: a picker whose filter takes printable
+   * characters through a capture would have `j` and `G` resolved out from under it by a scope, so
+   * typing a model's name would scroll instead of filtering. A panel that already moves in itself
+   * says so by staying quiet here.
+   */
+  scroll: boolean;
 };

package/src/generated/ModelInfo.ts

@@ -27,4 +27,20 @@ export type ModelInfo = {
    * numbers are already columns.
    */
   tagline?: string | null;
+  /**
+   * Why this one cannot be chosen here, in a sentence, or nothing when it can.
+   *
+   * A model a driver lists but will not run — the vendor CLI on this machine is too old for it,
+   * most often. Said rather than filtered out, for the reason a missing provider is listed
+   * rather than dropped: nothing there and not allowed are the same empty list, and only one of
+   * them is fixed by doing something. A model that silently vanishes from the picker is a
+   * question with nowhere to ask it — you go looking for the release notes, or for our bug
+   * tracker, and the answer was one `claude update` away the whole time.
+   *
+   * The sentence carries the fix, not just the diagnosis: "needs claude 2.1.251 — run `claude
+   * update`" is actionable and "unsupported model" is not. Anything reading a catalogue to
+   * *choose* — the startup default, `model.upgrade`, `model.line` — skips these; only a picker
+   * draws them, and draws them disabled.
+   */
+  unavailable?: string | null;
 };

package/src/generated/PluginEvent.ts

@@ -63,6 +63,7 @@ export type PluginEvent =
   | { "type": "composer_changed"; text: string }
   | { "type": "event"; name: string; data?: unknown; from: string }
   | { "type": "var_changed"; scope: VarScope; key: string; value?: unknown }
+  | { "type": "project_moved"; from: string; to: string }
   | { "type": "highlight_changed"; names: Array<string> }
   | { "type": "contributions_changed"; point: string }
   | { "type": "swarm_changed" }

package/src/generated/PullRequest.ts

@@ -0,0 +1,30 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { ChecksState } from "./ChecksState";
+import type { PullState } from "./PullState";
+
+/**
+ * One pull request, as much of it as a row can use.
+ *
+ * **Keyed by `branch`**, which is what makes one call answer for every worktree at once: a
+ * repository's pull requests come back together and each checkout finds its own by the branch it
+ * has out. Asking per branch would be one network round trip per row in the panel.
+ */
+export type PullRequest = {
+  number: number;
+  title: string;
+  /**
+   * For opening it. The forge's own URL, so nothing here has to know how to build one.
+   */
+  url: string;
+  /**
+   * The head branch. What a checkout matches itself against.
+   */
+  branch: string;
+  state: PullState;
+  checks: ChecksState;
+  /**
+   * How many checks have failed, for a row that wants to say `✗2` rather than `✗`.
+   */
+  checks_failed: number;
+  checks_total: number;
+};

package/src/generated/PullState.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Where a pull request has got to.
+ *
+ * Four states because that is what a person means by "what happened to it": one is a review you
+ * are waiting for, one is a review you have not asked for yet, one is done, and one is not going
+ * to happen. Draft is its own state rather than a flag on `Open` because on a row it is the whole
+ * difference between "somebody should look at this" and "I am still writing it".
+ */
+export type PullState = "open" | "draft" | "merged" | "closed";

package/src/generated/ScrollAmount.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How far to move a window's scroll. See [`crate::ApiCall::WinScroll`].
+ *
+ * Verbs rather than a row number, for the reason [`CursorMotion`] is: only the core knows how many
+ * buffer rows the frontend last drew, so "half a screen" is a question the caller cannot answer and
+ * a caller that tried would answer it with a height. Signed, so one variant covers both directions
+ * and a binding for `<C-d>` is the binding for `<C-u>` with the sign flipped.
+ */
+export type ScrollAmount =
+  | { "kind": "lines"; n: number }
+  | { "kind": "half"; n: number }
+  | { "kind": "page"; n: number }
+  | { "kind": "top" }
+  | { "kind": "bottom" };

package/src/index.ts

@@ -36,6 +36,7 @@ import type { CredentialSource } from "./generated/CredentialSource";
 import type { CursorMotion } from "./generated/CursorMotion";
 import type { CursorShape } from "./generated/CursorShape";
 import type { SelectShape } from "./generated/SelectShape";
+import type { ScrollAmount } from "./generated/ScrollAmount";
 import type { DiffTarget } from "./generated/DiffTarget";
 import type { Dock } from "./generated/Dock";
 import type { Gravity } from "./generated/Gravity";
@@ -136,6 +137,9 @@ import type { Viewport } from "./generated/Viewport";
 import type { WindowId } from "./generated/WindowId";
 import type { WindowInfo } from "./generated/WindowInfo";
 import type { WindowLayout } from "./generated/WindowLayout";
+import type { ChecksState } from "./generated/ChecksState";
+import type { PullRequest } from "./generated/PullRequest";
+import type { PullState } from "./generated/PullState";
 import type { WorktreeInfo } from "./generated/WorktreeInfo";
 
 export type {
@@ -153,12 +157,15 @@ export type {
   CostBasis, QuotaCredits, QuotaSample, QuotaSeverity, QuotaSnapshot, QuotaSource, QuotaWindow,
   InstallMethod, UpdateOutcome, UpdateStatus,
   UsageBucket, UsageHistory, UsageResolution, UsageScanSource,
-  Rect, RepoInfo, RepoStatus, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
+  Rect, RepoInfo, RepoStatus, ScrollAmount, SelectShape, SessionId, SessionInfo, StatusAlign, StatusSegment, StopReason,
   SurfaceCell, SurfaceId, TextEdit, ToolCall, ToolDef, ToolResult, TurnRequest, Usage,
   NodeCapabilities, NodeId, NodeInfo, ProjectKey, RemoteProject, StreamEvent,
   SwarmAgent, SwarmNode, SwarmStranger,
   VarScope, ViewId, ViewInfo, Viewport,
   WindowId, WindowInfo, WindowLayout,
+  ChecksState,
+  PullRequest,
+  PullState,
   WorktreeInfo,
 };
 
@@ -368,6 +375,16 @@ export interface FloatOptions {
   border?: FloatConfig["border"];
   borderHl?: string;
   title?: string;
+  /**
+   * A strip on the bottom border: what the keys here do.
+   *
+   * On the border rather than in the buffer, because a key strip written as a row of content is one
+   * that scrolls away exactly when it is wanted, and is the first thing clipped on a terminal too
+   * short for the panel. It costs no content row and cannot be scrolled off.
+   *
+   * Clipped to the border's width like the title, so it is for a legend and not for prose.
+   */
+  footer?: string;
   closeOnBlur?: boolean;
   focusable?: boolean;
   /**
@@ -384,6 +401,24 @@ export interface FloatOptions {
    * control sheet. Not for a hint or a hover card.
    */
   modal?: boolean;
+  /**
+   * This panel is a place you can move in when it does not fit.
+   *
+   * You ask for a height and get whatever there is: `{ kind: "max", n: 30 }` on a twenty-row
+   * terminal is ten rows of panel and twenty rows of content drawn nowhere, with no key pointed at
+   * them and nothing on screen to say they exist. Set this and the workspace's scroll keys resolve
+   * here — `j`/`k`, `^D`/`^U`, `^F`/`^B`, `gg`/`G`, the arrows and the paging keys — along with the
+   * mouse wheel, and a bar appears down the right border while anything is hidden.
+   *
+   * They are ordinary bindings on `{ kind: "buf_kind", name: "neosh.scroll" }`, so `^Z` lists them
+   * and `init.ts` moves them. That scope sits *below* your buffer's own kind, so a key you bind on
+   * your panel is still yours — and above `global`, so it works under `modal` too.
+   *
+   * For a panel of rows you read: a key sheet, a diff, a status, a help screen. **Not** for one with
+   * a cursor of its own — a picker, a list — which already scrolls to keep the cursor on screen and
+   * whose filter would lose `j` and `G` to this.
+   */
+  scroll?: boolean;
 }
 
 export interface Neosh {
@@ -415,6 +450,8 @@ export interface Neosh {
   readonly opt: OptionApi;
   readonly state: StateApi;
   readonly vars: VarApi;
+  /** The directories somebody works in. See {@link ProjectApi}. */
+  readonly project: ProjectApi;
   readonly ext: ExtensionApi;
   readonly event: EventApi;
   readonly swarm: SwarmApi;
@@ -689,6 +726,19 @@ export interface WindowApi {
    * its first row at `0`. Anything else shows the same thing either way.
    */
   scrollTo(win: WindowId, topLine: number | null): Promise<void>;
+  /**
+   * Move a window's scroll by a line, a half screen, a screen, or all the way to an end.
+   *
+   * What {@link scrollTo} cannot express, because the arithmetic is not yours to do: "half a screen"
+   * is counted in the buffer rows the frontend actually drew — which on a wrapping window is fewer
+   * than its height — and the floor is the last screenful rather than the last line, so the bottom
+   * is a full panel and not one row above an empty one. Both numbers are a frame old by the time
+   * {@link viewport} hands them to you; this reads them where they live.
+   *
+   * The keys bound on `neosh.scroll` run exactly this. Call it directly for a scroll a key did not
+   * ask for — following output, or a button on a panel of your own.
+   */
+  scroll(win: WindowId, amount: ScrollAmount): Promise<void>;
   /**
    * How big this window actually is, in cells.
    *
@@ -1152,12 +1202,52 @@ export interface GitApi {
   stage(paths?: string[]): Promise<void>;
   unstage(paths?: string[]): Promise<void>;
   commit(message: string): Promise<CommitInfo>;
+  /**
+   * `git fetch --prune`, answering with where the tree stands *after* it.
+   *
+   * **The one call that makes `ahead` and `behind` mean anything.** `status()` reads them off
+   * `git status --branch`, which compares HEAD with the remote-tracking ref sitting on this disk —
+   * so a panel drawing `↓0` from it is reporting the state of the world as of whenever this
+   * checkout last spoke to a remote. Call this first and the number is news; do not, and it is
+   * archaeology.
+   *
+   * It answers with the fresh {@link RepoStatus} rather than nothing, so "fetch and see where I am"
+   * is one round trip. Prunes, because a picker offering six branches that were deleted when their
+   * pull requests merged is worse than one that is a fetch behind.
+   *
+   * A write, and the reason is the network rather than the working tree, which does not move:
+   * this contacts a remote and writes refs. It fails rather than hangs when there are no
+   * credentials — stdin is closed and every askpass unset — which is what makes it safe to put on
+   * a timer. Expect it to reject routinely: no remote, no network, a key the host will not take.
+   */
+  fetch(opts?: { cwd?: string }): Promise<RepoStatus>;
+  /**
+   * Every pull request the forge knows about for this repository, open and closed.
+   *
+   * **One call answers for every checkout.** They come back keyed by
+   * {@link PullRequest.branch}, so a repository with six worktrees is one request and six lookups
+   * — which is the difference between a panel that costs a round trip every few minutes and one
+   * that costs six.
+   *
+   * Answered by `gh`, the CLI the user has already signed into, so tokens, enterprise hosts, SSO
+   * and rate limits are already handled and the answer is the one they get in their own terminal.
+   *
+   * **Rejects rather than answering empty** when it cannot know — no `gh`, not signed in, no
+   * remote on a forge. An empty list is the claim "this repository has no pull requests", and
+   * three of the four ways this fails would be making it falsely. Catch it, say it once, and do
+   * not say it again every tick.
+   */
+  pulls(opts?: { cwd?: string }): Promise<PullRequest[]>;
   /**
    * `git pull`, answering with git's own summary — "Already up to date.", the fast-forward range —
    * because those are different answers and a caller showing neither is a caller nobody trusts.
    * `cwd` picks the repository, as everywhere; absent means the conversation's own.
+   *
+   * `rebase` replays this branch's commits on top of what arrived instead of merging them. It is
+   * the answer to a diverged branch and it rewrites local commits, so ask before you set it — the
+   * caller this exists for is a panel that has just said "diverged" and offered the choice.
    */
-  pull(opts?: { cwd?: string }): Promise<string>;
+  pull(opts?: { cwd?: string; rebase?: boolean }): Promise<string>;
   addWorktree(
     path: string,
     branch: string,
@@ -1169,6 +1259,60 @@ export interface GitApi {
    * exactly that one.
    */
   removeWorktree(path: string, opts?: { force?: boolean; cwd?: string }): Promise<void>;
+  /**
+   * Move a worktree to `dest` — `git worktree move`, and everything that has to follow it.
+   *
+   * A worktree's path is an identity here, not a coordinate: it is the key of the project facts
+   * every list draws, of the conversations living in it, of the project vars holding a pin and a
+   * fold state, and of the working directory each vendor CLI was started in. This call moves all
+   * of them, which is why it is a call rather than a `git worktree move` you could have run
+   * yourself — the git part is the part that was never hard.
+   *
+   * `dest` is the full path it lands at. Its parent is created; the leaf must not exist.
+   *
+   * Refused while a turn is running anywhere in the tree, because a CLI holds its working
+   * directory from the moment it is spawned and would otherwise write the file it is editing into
+   * the place the tree used to be. Interrupt it and ask again.
+   *
+   * `cwd` names the repository, as everywhere.
+   */
+  moveWorktree(path: string, dest: string, opts?: { cwd?: string }): Promise<void>;
+  /**
+   * Clone `url` into `path`, resolving to the path once it is there.
+   *
+   * The one call here with no `cwd`: everything else asks a repository a question, and this one
+   * arrives before there is a repository to ask. `path` is absolute and its parent need not
+   * exist — cloning into a location you have just invented is the ordinary case.
+   *
+   * **It reports progress while it runs**, on the bus as {@link CLONE_EVENT}, so a caller that
+   * wants to draw a clone rather than block on one subscribes before awaiting this. Keyed by
+   * `path`, because a workspace may be cloning two things at once.
+   *
+   * Needs `vcs_write` in the manifest, like every other call here that changes a disk.
+   */
+  clone(url: string, path: string): Promise<string>;
+}
+
+/**
+ * What {@link GitApi.clone} says about itself while it runs, on {@link EventsApi.on}.
+ *
+ * `phase` is git's own word for what it is doing — `Receiving objects`, `Resolving deltas` — and
+ * `percent` is absent for the phases that have no total, which draw as a spinner rather than as a
+ * bar. `done` arrives exactly once per clone, on success and on failure alike, because a panel
+ * drawing itself from these has no other way to learn it may stop.
+ */
+export const CLONE_EVENT = "neosh.git.clone";
+
+/** One {@link CLONE_EVENT} payload. */
+export interface CloneProgress {
+  /** Which clone this is about. The key, since two may be running. */
+  path: string;
+  url: string;
+  phase: string;
+  percent?: number | null;
+  done?: boolean;
+  /** Present, with git's own last word in it, only when the clone failed. */
+  error?: string;
 }
 
 /**
@@ -1190,6 +1334,32 @@ export interface GenApi {
    * do not each reimplement that. Rejects if there is no JSON in the response at all.
    */
   json<T = unknown>(prompt: string, opts?: { system?: string; selection?: ModelSelection }): Promise<T>;
+  /**
+   * One value, asked for as JSON and accepted however it comes back.
+   *
+   * The shape almost every generating plugin actually wants: a branch name, a thread title, a PR
+   * subject — one string, asked for as `{"branch": …}` because that is how you pin a model down,
+   * and answered as a bare `fix/composer-paste` often enough to matter. Both are the same answer,
+   * and {@link GenApi.json} rejects the second one — which is a correct name thrown away, with
+   * nothing on screen to say so.
+   *
+   * So the key is passed down and a bare reply is read as its value. Everything
+   * {@link GenApi.json} tolerates is tolerated first and unchanged; this is only what happens when
+   * there is no JSON at all. Rejects on an empty answer, or on prose it will not guess at.
+   *
+   * For one value only. A commit message is a subject and a body, and there is no answering the
+   * question of which one a lone paragraph is — that stays {@link GenApi.json}.
+   *
+   * And only for a value you would know was wrong on sight. A branch name is that, and a wrong one
+   * is one rename away; a thread title is any short line, and so is a refusal or a driver's own
+   * error message — where nothing distinguishes an answer from a remark, the envelope is the
+   * evidence, and {@link GenApi.json} is the call.
+   */
+  field(
+    prompt: string,
+    key: string,
+    opts?: { system?: string; selection?: ModelSelection },
+  ): Promise<string>;
 }
 
 /**
@@ -1449,6 +1619,27 @@ export interface VarApi {
   ): Disposable;
 }
 
+/**
+ * The directories somebody works in, and the one thing that can happen to one.
+ *
+ * A project *is* its path everywhere else in this API — `projectScope` keys vars by it, a panel's
+ * list is a list of them, `SessionInfo.cwd` names one. Which is exactly why a path that changes
+ * needs saying out loud rather than inferring: from the outside, a worktree that moved and a
+ * project that was deleted while another was added are the same two facts in the same order.
+ */
+export interface ProjectApi {
+  /**
+   * A project's directory is now somewhere else — a worktree that was relocated.
+   *
+   * The host has already moved everything it owns by the time this arrives: the conversations, the
+   * project vars, the names and branches every list draws. What is left is whatever *you* keyed by
+   * the old path — a list of directories, a cache, a decoration target — and the point of getting
+   * both ends in one event is that you can re-key in place instead of dropping a row and gaining a
+   * stranger.
+   */
+  onMove(cb: (e: { from: string; to: string }) => void): Disposable;
+}
+
 /** Sugar for the two scopes anything with a panel spends its time in. */
 export function projectScope(cwd: string): VarScope {
   return { scope: "project", cwd };
@@ -1876,6 +2067,7 @@ interface Registered {
   composerListeners: Array<(e: { text: string }) => void>;
   activityListeners: Array<(e: { session: SessionId; turn: string; activity: Activity }) => void>;
   varListeners: Array<(e: { scope: VarScope; key: string; value: unknown }) => void>;
+  projectMovedListeners: Array<(e: { from: string; to: string }) => void>;
   swarmListeners: Array<() => void>;
   quotaListeners: Array<(snapshot: QuotaSnapshot) => void>;
   swarmStreamListeners: Array<
@@ -1922,6 +2114,7 @@ function reg(plugin: string): Registered {
       composerListeners: [],
       activityListeners: [],
       varListeners: [],
+      projectMovedListeners: [],
       swarmListeners: [],
       quotaListeners: [],
       swarmStreamListeners: [],
@@ -1973,9 +2166,11 @@ function floatConfig(o: FloatOptions = {}): FloatConfig {
     border: o.border ?? "rounded",
     border_hl: o.borderHl ?? null,
     title: o.title ?? null,
+    footer: o.footer ?? null,
     close_on_blur: o.closeOnBlur ?? false,
     focusable: o.focusable ?? true,
     modal: o.modal ?? false,
+    scroll: o.scroll ?? false,
   };
 }
 
@@ -2134,6 +2329,11 @@ function build(
         return listener(r.varListeners, cb);
       },
     },
+    project: {
+      onMove(cb) {
+        return listener(r.projectMovedListeners, cb);
+      },
+    },
     ext: {
       async contribute(point, id, item, opts) {
         await c({ call: "ext_contribute", point, id, item, priority: opts?.priority ?? 0 });
@@ -2499,6 +2699,9 @@ function build(
       async scrollTo(win, topLine) {
         await c({ call: "win_scroll_to", win, top_line: topLine });
       },
+      async scroll(win, amount) {
+        await c({ call: "win_scroll", win, amount });
+      },
       async viewport(win) {
         return expect(await c({ call: "win_get_viewport", win }), "viewport").viewport ?? null;
       },
@@ -2817,8 +3020,16 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async fetch(opts) {
+        const v = await c({ call: "git_fetch", cwd: opts?.cwd ?? null });
+        return expect(v, "status").status;
+      },
+      async pulls(opts) {
+        const v = await c({ call: "forge_pulls", cwd: opts?.cwd ?? null });
+        return expect(v, "pulls").pulls;
+      },
       async pull(opts) {
-        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null });
+        const v = await c({ call: "git_pull", cwd: opts?.cwd ?? null, rebase: opts?.rebase ?? false });
         return expect(v, "text").text;
       },
       async removeWorktree(path, opts) {
@@ -2829,6 +3040,13 @@ function build(
           cwd: opts?.cwd ?? null,
         });
       },
+      async moveWorktree(path, dest, opts) {
+        await c({ call: "git_move_worktree", path, dest, cwd: opts?.cwd ?? null });
+      },
+      async clone(url, path) {
+        const v = await c({ call: "git_clone", url, path });
+        return expect(v, "text").text;
+      },
     },
     gen: {
       async complete(prompt, opts) {
@@ -2851,6 +3069,23 @@ function build(
         });
         return expect(v, "json").value as never;
       },
+      async field(prompt, key, opts) {
+        const v = await c({
+          call: "gen_complete",
+          prompt,
+          system: opts?.system ?? null,
+          json: true,
+          field: key,
+          selection: opts?.selection ?? null,
+        });
+        const value = (expect(v, "json").value as Record<string, unknown>)?.[key];
+        // A key that came back as something other than a non-empty string is an answer to a
+        // different question, and the caller is about to name a branch after it.
+        if (typeof value !== "string" || value.trim() === "") {
+          throw new Error(`the model returned no ${key}`);
+        }
+        return value.trim();
+      },
     },
     view: {
       async list() {
@@ -3166,6 +3401,9 @@ async function dispatchEvent(
         for (const cb of r.varListeners)
           cb({ scope: ev.scope, key: ev.key, value: ev.value });
         break;
+      case "project_moved":
+        for (const cb of r.projectMovedListeners) cb({ from: ev.from, to: ev.to });
+        break;
       case "quota":
         for (const cb of [...r.quotaListeners]) cb(ev.snapshot);
         break;

package/src/ui.ts

@@ -513,7 +513,11 @@ export async function picker<T>(
   items: PickerItem<T>[],
   opts: PickerOptions<T> = {},
 ): Promise<T | null> {
-  const height = Math.max(1, opts.height ?? 12);
+  // What the list would like. What it *gets* is settled by `measure` below, once the frontend has
+  // said how much of the screen there was — a picker asking for twelve rows on a sixteen-row
+  // terminal is not a twelve-row picker, and every number this widget computes from `rows` was
+  // wrong by the difference until it asked.
+  let rows = Math.max(1, opts.height ?? 12);
   const width = Math.max(20, opts.width ?? 64);
   const filtering = opts.filter !== false;
 
@@ -530,13 +534,13 @@ export async function picker<T>(
     anchor: opts.anchor ?? { kind: "screen" },
     offset: opts.offset,
     width: { kind: "fixed", n: width },
-    // Exactly the rows that get drawn: the list, plus a filter line when there is one, a title
-    // when there is one, and the key strip unless it was waived.
-    height: {
-      kind: "fixed",
-      n: height + (filtering ? 1 : 0) + (opts.title ? 1 : 0) + (hints === "" ? 0 : 1),
-    },
+    // Exactly the rows that get drawn: the list, plus a filter line when there is one and a title
+    // when there is one. The key strip is not among them any more — it is on the bottom border,
+    // where it costs no row and cannot be the row that does not fit. It was a row, and on a
+    // sixteen-row terminal it was reliably the one clipped: the strip that says how to get out.
+    height: { kind: "fixed", n: rows + (filtering ? 1 : 0) + (opts.title ? 1 : 0) },
     border: "rounded",
+    footer: hints === "" ? undefined : ` ${hints} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -625,7 +629,7 @@ export async function picker<T>(
     if (closed) return;
     // Keep the cursor on screen without recentring on every keystroke.
     if (cursor < top) top = cursor;
-    if (cursor >= top + height) top = cursor - height + 1;
+    if (cursor >= top + rows) top = cursor - rows + 1;
 
     const lines: string[] = [];
     if (opts.title) lines.push(opts.title);
@@ -636,7 +640,7 @@ export async function picker<T>(
     // dock. Measuring against anything else puts the last visible character on both lines — the
     // continuation says `/ finds` under a row that already ended in `/`.
     const inner = Math.max(8, width);
-    let window = visible.slice(top, top + height);
+    let window = visible.slice(top, top + rows);
     // One gutter for the whole list, or none at all. Giving it only to the rows that asked for an
     // icon would step every other label one column left, which reads as a list that cannot decide
     // where its left margin is.
@@ -672,7 +676,7 @@ export async function picker<T>(
     // float's height: the window was sized for `height` lines and growing past it would push the
     // key strip off the bottom, which is the row that says how to get out.
     if (rest.length > 0) {
-      const room = Math.max(1, height - rest.length);
+      const room = Math.max(1, rows - rest.length);
       if (cursor < top) top = cursor;
       if (cursor >= top + room) top = cursor - room + 1;
       window = visible.slice(top, top + room);
@@ -691,23 +695,6 @@ export async function picker<T>(
       if (!isCursor) continue;
       for (const line of rest) lines.push(`    ${line}`);
     }
-    // Pushed onto the last row rather than floated: the float is sized for it, and a strip that
-    // moved up as the list shortened would be a strip you have to look for.
-    //
-    // The placeholder takes a row of the list's own space, so an empty list has used one of the
-    // `height` rows and not none. Counting it as none put the strip one row past the bottom of a
-    // float sized for exactly `height`, where it was silently clipped — leaving the empty state,
-    // the one state where you most want to be told what the keys do, as the only one with no keys
-    // on it.
-    // Lines, not rows: the row under the cursor is more than one of them when it has unfolded, and
-    // counting rows here would leave the strip that many lines low — off the bottom of a float
-    // sized for exactly `height`.
-    const listRows = Math.max(1, lines.length - firstListLine);
-    const hintLine = hints === "" ? -1 : lines.length + Math.max(0, height - listRows);
-    if (hintLine >= 0) {
-      while (lines.length < hintLine) lines.push("");
-      lines.push(` ${hints}`);
-    }
     // Marks are collected against their row and handed over with the text, in one call. Set one at
     // a time they were a sequence the frontend could draw the middle of: the moment the clear had
     // landed and the marks had not, every row drew unmarked — in `Normal`, which is near-white.
@@ -716,9 +703,6 @@ export async function picker<T>(
       drawn[line]?.marks!.push({ col, opts: o });
     };
 
-    if (hintLine >= 0) {
-      mark(hintLine, 0, { hlGroup: "Sidebar.Dim", endCol: byteLength(lines[hintLine] ?? "") });
-    }
     const listTop = (opts.title ? 1 : 0) + (filtering ? 1 : 0);
     for (let i = 0; i < window.length; i++) {
       const row = window[i]!;
@@ -869,10 +853,10 @@ export async function picker<T>(
           cursor = Math.max(0, cursor - 1);
           break;
         case "page_down":
-          cursor = Math.min(last(), cursor + height);
+          cursor = Math.min(last(), cursor + rows);
           break;
         case "page_up":
-          cursor = Math.max(0, cursor - height);
+          cursor = Math.max(0, cursor - rows);
           break;
         case "first":
           cursor = 0;
@@ -923,6 +907,33 @@ export async function picker<T>(
     }, { desc: "picker key" }),
   );
 
+  /**
+   * How many list rows there turned out to be room for.
+   *
+   * A float is *asked* for a height and given whatever the screen has, so `opts.height` is a wish
+   * and this is the answer. Everything above counts in `rows` — where the window starts, what a
+   * page step is, how far the cursor may go before the list scrolls — and while that number was the
+   * wish, a picker on a short terminal scrolled to keep the cursor on a row that was not drawn.
+   *
+   * Read once when the panel opens and again whenever the frontend says this window changed size,
+   * rather than on every keystroke: a round trip per character typed is latency on the one path in
+   * this widget that has to feel immediate.
+   */
+  async function measure(): Promise<void> {
+    if (closed) return;
+    const v = await neosh.win.viewport(win).catch(() => null);
+    if (!v) return;
+    const next = Math.max(1, v.height - (filtering ? 1 : 0) - (opts.title ? 1 : 0));
+    if (next === rows) return;
+    rows = next;
+    await render();
+  }
+  disposers.push(
+    neosh.event.on("neosh.viewport", (e) => {
+      if ((e as { win?: WindowId }).win === win) void measure();
+    }),
+  );
+
   await neosh.focus.push(win);
   disposers.push(await neosh.keymap.capture(win, command));
   // `<C-c>` is bound globally to `interrupt`, which would arm "press again to quit" while a picker
@@ -935,6 +946,7 @@ export async function picker<T>(
   if (typeof opts.query === "function") query = opts.query();
   await refetch();
   await render();
+  await measure();
   if (opts.onHighlight) {
     const row = visible[cursor];
     if (row) opts.onHighlight(row.item, row.index);
@@ -957,6 +969,145 @@ function dropSegment(text: string): string {
   return at < 0 ? "" : trimmed.slice(0, at + 1);
 }
 
+// ---------------------------------------------------------------------------
+// Reading something too long for the screen
+// ---------------------------------------------------------------------------
+
+export interface PagerOptions {
+  /** On the top border. */
+  title?: string;
+  /**
+   * On the bottom border, replacing the default legend.
+   *
+   * The default already names the scroll keys and the way out, read out of nothing — they are fixed
+   * defaults on `neosh.scroll` and `^Z` is where a rebinding shows up. Pass your own only to add a
+   * verb of your own to it.
+   */
+  footer?: string;
+  /** Columns of content. The border is drawn outside it. */
+  width?: number;
+  /**
+   * The most rows of content to ask for. Fewer if the content is shorter, fewer still if the screen
+   * is — which is the case this whole widget is about, and is why it is a ceiling and not a size.
+   */
+  height?: number;
+  /**
+   * The buffer kind, so a third party can bind keys in *this* panel and find it with `win.ofKind`.
+   *
+   * Defaults to {@link KIND_PAGER}, which every pager in the workspace shares. Pass your own when
+   * the panel is a thing in its own right — a diff, a status — and somebody might reasonably want
+   * keys on that and not on every pager there is.
+   */
+  kind?: string;
+  /** Marks to lay over the rows, in the same shape {@link Neosh.buf.render} takes. */
+  marks?: DrawnRow["marks"][];
+  z?: number;
+  /**
+   * Handed this panel's own close, as soon as it is on screen.
+   *
+   * For the caller that has to be able to put it away itself — a key that toggles, a panel that
+   * closes when the thing it is about goes. Without it the only way out is a key, and a `^Z` that
+   * opens a sheet and then opens a second one behind it is the bug this exists to prevent.
+   */
+  onOpen?: (close: () => Promise<void>) => void;
+}
+
+/** The kind a pager's buffer gets when the caller does not name one. */
+export const KIND_PAGER = "neosh.pager";
+
+/**
+ * Show rows you can read but not edit, in a float that scrolls when it does not fit.
+ *
+ * The shape almost every read-only panel in the workspace turned out to want, and the thing each of
+ * them was missing: a float is given whatever height the screen has, so a status of sixty changed
+ * files or a diff of four hundred lines was thirty rows on screen and the rest drawn nowhere, with
+ * no key pointed at it and nothing to say it was there. Every one of them had independently written
+ * "open a float, put lines in it" and independently stopped before the part where the terminal is
+ * short.
+ *
+ * What you get: the reader's motions (`j`/`k`, `^D`/`^U`, `^F`/`^B`, `gg`/`G`, arrows, paging keys)
+ * and the wheel, because the float sets `scroll` and those are ordinary bindings on
+ * `neosh.scroll` — so `^Z` lists them and `init.ts` moves them. A bar down the right border while
+ * anything is hidden. A legend on the bottom border, which cannot scroll away and is not the first
+ * row clipped. `<Esc>`, `q`, `<CR>` and `^C` close it.
+ *
+ * Resolves when it closes.
+ */
+export async function pager(
+  neosh: Neosh,
+  lines: string[],
+  opts: PagerOptions = {},
+): Promise<void> {
+  const buf = await neosh.buf.create({
+    name: `[${opts.title?.trim() || "pager"}]`,
+    scratch: true,
+    kind: opts.kind ?? KIND_PAGER,
+  });
+  const ns = await neosh.ns.create("neosh.ui.pager");
+  await neosh.buf.render(
+    buf,
+    ns,
+    0,
+    -1,
+    lines.map((text, i) => ({ text, marks: opts.marks?.[i] ?? [] })),
+  );
+
+  const win = await neosh.float.open(buf, {
+    anchor: { kind: "screen" },
+    width: opts.width === undefined ? { kind: "auto" } : { kind: "fixed", n: opts.width },
+    // A ceiling, never a size. `fixed` here would ask for rows the screen does not have and get
+    // clipped to them anyway — the difference being that `max` also shrinks to fit content that is
+    // shorter, so a two-line status is a two-line panel rather than a mostly empty box.
+    height: { kind: "max", n: opts.height ?? 30 },
+    border: "rounded",
+    title: opts.title,
+    footer: opts.footer ?? " j k move   ^D ^U half   gg G ends   esc close ",
+    focusable: true,
+    closeOnBlur: true,
+    scroll: true,
+    z: opts.z ?? 200,
+  });
+  await neosh.focus.push(win);
+
+  let settle: () => void = () => {};
+  const done = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
+
+  const command = `neosh.ui.pager.key.${++pickerSeq}`;
+  const disposers: Disposable[] = [];
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    for (const d of disposers) d.dispose();
+    await neosh.focus.pop().catch(() => {});
+    await neosh.win.close(win).catch(() => {});
+    settle();
+  };
+
+  disposers.push(
+    await neosh.cmd.register(command, (_args, key) => {
+      // Only what nothing else claimed reaches here, and the scroll keys are claimed — they resolve
+      // at `neosh.scroll`, which is nearer than this capture is late. So what is left is dismissal.
+      // Which is *named*: a panel you scroll is a panel you spend time in, and "any key closes it"
+      // turns a mistyped letter into losing your place.
+      if (!key || closesPager(key)) void close();
+    }, { desc: "close this panel" }),
+  );
+  disposers.push(await neosh.keymap.capture(win, command));
+  opts.onOpen?.(close);
+  return done;
+}
+
+/** `<Esc>`, `q`, `<CR>` and `^C` — the four keys every panel in this workspace closes on. */
+function closesPager(key: KeyContext): boolean {
+  const { code, mods } = key.key;
+  if (code.kind === "esc" || code.kind === "enter") return true;
+  if (code.kind !== "char") return false;
+  return mods.ctrl ? code.c.toLowerCase() === "c" : code.c.toLowerCase() === "q";
+}
+
 // ---------------------------------------------------------------------------
 // Derived widgets
 // ---------------------------------------------------------------------------
@@ -1013,6 +1164,18 @@ export async function confirm(
     `y ${yes.toLowerCase()}   n ${no.toLowerCase()}   ↵ choose   esc cancel`,
     width - 2,
   );
+  /**
+   * How many of the detail lines there is room for.
+   *
+   * Settled once the frontend has said how tall this dialog turned out to be — a dialog is asked
+   * for a height and given what the screen has, and the rows it loses are the ones at the bottom.
+   * Which for a question with the answers under the detail meant the answers, so a long `detail` on
+   * a short terminal was a dialog you could not see either option in.
+   *
+   * The detail is what gives way, because the detail is the part you can do without: the question
+   * and the two answers are the dialog. What went is said rather than silently dropped.
+   */
+  let room = detail.length;
 
   // On the answer that changes nothing, when the other one cannot be taken back.
   let cursor = opts.dangerous ? 1 : 0;
@@ -1025,14 +1188,17 @@ export async function confirm(
 
   /** Where each part of the dialog starts, so the marks do not have to count rows twice. */
   const detailAt = asked.length + 1;
-  const answersAt = detailAt + (detail.length === 0 ? 0 : detail.length + 1);
-  const stripAt = answersAt + answers.length + 1;
+  /** Every row but the detail: the question, the blanks around it, and the two answers. */
+  const fixedRows = asked.length + 1 + answers.length;
 
   const win = await neosh.float.open(buf, {
     anchor: { kind: "screen" },
     width: { kind: "fixed", n: width },
-    height: { kind: "fixed", n: stripAt + 1 },
+    height: { kind: "fixed", n: fixedRows + (detail.length === 0 ? 0 : detail.length + 1) },
     border: "rounded",
+    // The key strip, on the edge. It was the last row of the buffer, which made it both the row a
+    // long `detail` pushed off the bottom and a row of height every dialog had to pay for.
+    footer: ` ${strip} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -1048,15 +1214,20 @@ export async function confirm(
   });
 
   const render = async () => {
+    const shownDetail = room >= detail.length
+      ? detail
+      : // One row of the budget goes to saying what is not being shown, so a dialog that has had to
+        // cut something never looks like a dialog that had nothing more to say.
+        [...detail.slice(0, Math.max(0, room - 1)), `… and ${detail.length - Math.max(0, room - 1)} more lines`];
+    const detailRows = shownDetail.length;
+    const answersAt = detailAt + (detailRows === 0 ? 0 : detailRows + 1);
     const lines: string[] = asked.map((l) => ` ${l}`);
     lines.push("");
-    if (detail.length > 0) {
-      lines.push(...detail.map((l) => ` ${l}`));
+    if (detailRows > 0) {
+      lines.push(...shownDetail.map((l) => ` ${l}`));
       lines.push("");
     }
     answers.forEach((a, i) => lines.push(`${i === cursor ? `${CURSOR_MARKER}` : BLANK_MARKER}${a}`));
-    lines.push("");
-    lines.push(` ${strip}`);
     // Text and marks together, in one call: this is redrawn on every keystroke, and a repaint the
     // frontend can draw the middle of is one that flashes — unmarked rows draw in `Normal`. It also
     // takes care of the older half of the same bug, that a mark whose line was replaced under it
@@ -1069,7 +1240,7 @@ export async function confirm(
     for (let i = 0; i < asked.length; i++) {
       mark(i, 0, { hlGroup: "Title", endCol: byteLength(lines[i] ?? "") });
     }
-    for (let i = 0; i < detail.length; i++) {
+    for (let i = 0; i < detailRows; i++) {
       mark(detailAt + i, 0, {
         hlGroup: "Comment",
         endCol: byteLength(lines[detailAt + i] ?? ""),
@@ -1090,7 +1261,6 @@ export async function confirm(
         });
       }
     }
-    mark(stripAt, 0, { hlGroup: "Sidebar.Dim", endCol: byteLength(lines[stripAt] ?? "") });
     await neosh.buf.render(buf, ns, 0, -1, drawn);
     // The caret marks the answer, since there is nothing here to type into.
     await neosh.win.setCursor(win, answersAt + cursor, 0);
@@ -1161,6 +1331,23 @@ export async function confirm(
   disposers.push(await neosh.keymap.capture(win, command));
   await bindWidgetKeys(neosh, win, command, keys);
   await render();
+  // And then how much of it there was room for. Asked after the first draw, because a window the
+  // frontend has never laid out has no answer to give.
+  const measure = async () => {
+    if (closed) return;
+    const v = await neosh.win.viewport(win).catch(() => null);
+    if (!v) return;
+    const next = Math.max(0, v.height - fixedRows - 1);
+    if (next === room) return;
+    room = next;
+    await render();
+  };
+  disposers.push(
+    neosh.event.on("neosh.viewport", (e) => {
+      if ((e as { win?: WindowId }).win === win) void measure();
+    }),
+  );
+  await measure();
   return done;
 }
 
@@ -1401,6 +1588,9 @@ export async function prompt(
     width: { kind: "fixed", n: width },
     height: { kind: "fixed", n: 2 },
     border: "rounded",
+    // A field with no legend on it is a field you guess at. On the border, so it costs neither of
+    // the two rows this has.
+    footer: " ↵ accept   ^W a word   ^U all   esc cancel ",
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -2224,9 +2414,11 @@ export async function railPicker<G, T>(
   const win = await neosh.float.open(buf, {
     anchor: { kind: "screen" },
     width: { kind: "fixed", n: total },
-    // title, filter, rule, body, rule, hints
-    height: { kind: "fixed", n: height + 5 },
+    // title, filter, rule, body, rule. The key strip is not among them: it is on the bottom border,
+    // where it costs no row of body and cannot be the row a short terminal clips.
+    height: { kind: "fixed", n: height + 4 },
     border: "rounded",
+    footer: ` ${opts.hints ?? "↵ use   ⇥ panes   ^N/^P move   esc close"} `,
     focusable: true,
     closeOnBlur: true,
     // Modal: nothing global resolves while this is up. Shadowing the keys a widget wants — which
@@ -2336,8 +2528,21 @@ export async function railPicker<G, T>(
     all = got;
     rebuild();
     cursor = Math.max(0, Math.min(opts.itemAt?.(all) ?? 0, Math.max(0, rows.length - 1)));
-    // Land on something selectable rather than on a section header.
-    if (rows[cursor]?.kind !== "item") cursor = rows.findIndex((r) => r.kind === "item");
+    // Land on something you can actually press `↵` on: not a section header, and not a row the
+    // caller disabled. `movePane` has always stepped over disabled rows, so the only way to be
+    // standing on one was to open here — and the first row of a list is where a picker opens by
+    // default. A pane whose top row is "this needs a newer CLI" then greeted every `↵` with
+    // nothing happening, which reads as the picker being broken rather than the row being refused.
+    const landable = (at: number) => {
+      const row = rows[at];
+      return row?.kind === "item" && !row.item.disabled;
+    };
+    if (!landable(cursor)) {
+      const next = rows.findIndex((_, at) => landable(at));
+      // Every row refused is still a list worth opening — you came to read why. Falling back to
+      // the first item rather than to nothing keeps the detail line of *something* on screen.
+      cursor = next >= 0 ? next : rows.findIndex((r) => r.kind === "item");
+    }
     if (cursor < 0) cursor = 0;
     paneTop = 0;
   };
@@ -2415,7 +2620,11 @@ export async function railPicker<G, T>(
       ? takeWords(detail, Math.max(0, room))
       : [clipToWidth(detail, Math.max(0, room)), ""];
     const label = padToWidth(labelHead, labelWidth);
-    const badgeCell = badgeWidth === 0 ? "" : padToWidth(clipToWidth(badge, badgeWidth), badgeWidth);
+    // One column narrower than the cell it sits in, so there is always a space before the detail.
+    // Clipped to the full width, a badge that happens to fill it runs straight into the sentence
+    // after it and the two read as one word.
+    const badgeCell =
+      badgeWidth === 0 ? "" : padToWidth(clipToWidth(badge, badgeWidth - 1), badgeWidth);
     const text = `${head}${label}${badgeCell}${detailHead}`;
 
     const labelAt = byteLength(head);
@@ -2543,12 +2752,6 @@ export async function railPicker<G, T>(
       line: lines.length - 1,
       mark: { from: 0, to: byteLength(lines[lines.length - 1]!), hl: "Separator" },
     });
-    const hints = opts.hints ?? "↵ use   ⇥ panes   ^N/^P move   esc close";
-    lines.push(` ${hints}`);
-    marks.push({
-      line: lines.length - 1,
-      mark: { from: 0, to: byteLength(lines[lines.length - 1]!), hl: "Sidebar.Dim" },
-    });
 
     // The marks were already collected against their rows; they now travel with them. One call
     // rather than one per mark, so there is no frame in which the text has arrived and the colour
@@ -2766,7 +2969,16 @@ export interface ActionItem {
   /** For the hint strip and `^Z`. */
   label: string;
   command: string;
-  /** Which rows it applies to — a row kind the panel names, `custom` for contributed rows, or `any`. */
+  /**
+   * Which rows it applies to — a row kind the panel names, `custom` for contributed rows, or `any`.
+   *
+   * `custom:<section id>` narrows it to the rows of **one** section: `custom:git` is a verb about
+   * the git block and nothing else. Bare `custom` means every contributed row in the panel, which
+   * is right for a verb about contributions in general and wrong for the usual case — two plugins
+   * each with a block in the column and each wanting `<Tab>` on their own rows were, without this,
+   * one key that one of them won and the other silently lost. A panel binds the key once and sends
+   * it to whichever action matches the row the cursor is actually on.
+   */
   on?: string;
 }
 
@@ -3012,7 +3224,16 @@ export function placeSections<S extends string>(
  */
 export function sectionRows<T>(
   c: Contribution & { item: SectionItem },
-  opts: { width: number; custom: (command: string, args: string[]) => T },
+  opts: {
+    width: number;
+    /**
+     * What a landable contributed row *is*, in the panel's own vocabulary.
+     *
+     * The section's id comes third so a panel can tell one contributor's rows from another's —
+     * which is what {@link ActionItem.on}'s `custom:<id>` form is matched against.
+     */
+    custom: (command: string, args: string[], section: string) => T;
+  },
 ): ListRow<T>[] {
   const rows: ListRow<T>[] = [];
   const contributed = Array.isArray(c.item?.rows) ? c.item.rows : [];
@@ -3052,7 +3273,7 @@ export function sectionRows<T>(
       spans: spans.length > 0 ? spans : undefined,
       right: typeof r.right?.text === "string" ? { text: `${r.right.text} `, hl: r.right.hl } : undefined,
       inert: typeof r.command !== "string",
-      value: typeof r.command === "string" ? opts.custom(r.command, args) : undefined,
+      value: typeof r.command === "string" ? opts.custom(r.command, args, c.id) : undefined,
     });
   }
   return rows;