@huseynsnmz/pi-board 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ conventional commits by `scripts/release_helper.mjs`. Entries are
 forward-only: they begin with the first release after this file landed —
 for earlier history, see the git log and the pull-request list.
 
+## [0.15.1] - 2026-11-04
+
+### Features
+
+- **keys**: `Ctrl+S` groups by directory, `Shift+Up` and `Shift+Down` reorder, `Ctrl+G` opens your editor
+- **state**: a session waiting on a permission prompt or other dialog shows as `Needs answer`
+
+## [0.15.0] - 2026-11-04
+
+### Features
+
+- **keys**: typing starts a task with no key first, and the keys follow Claude Code's agent view
+- **board**: `Left` twice puts the session you're in on the board, so you can come back to it
+- **config**: settings move to `~/.pi/agent/extensions/pi-board/config.json`
+- **model**: `/board-model` chooses the helper model, which is now off until you choose one
+- **ui**: drawn with frames and Pi's theme colors, to match pi-frame
+
 ## [0.14.0] - 2026-11-04
 
 First release of `@huseynsnmz/pi-board`, a fork of `@zhuxixi/pi-agent-board` 0.13.1.

package/README.md

@@ -79,28 +79,27 @@ rm ~/.pi/agent/extensions/agent-board
 
 ## Quick Start
 
-Open the board with `/agent-board` inside Pi, or press `Left` twice on an empty prompt, then:
+Open the board with `/agent-board` inside Pi, or press `Left` twice on an empty prompt. That also puts the session you're in on the board, and `Esc` or `Enter` on its row brings you back. Then:
 
-1. Press `i` to enter INSERT mode.
-2. Type a task.
-3. Press `Enter`. It starts right away in the current folder, with this session's model and thinking level.
+1. Type a task.
+2. Press `Enter`. It starts right away in the current folder, with this session's model and thinking level.
 
 To choose the folder, model or thinking level first, press `Ctrl+N` while typing. With an empty input, `Enter` attaches/resumes the selected session. The row starts in `Queued`, then moves through `Running` to a terminal state such as `Needs answer`, `Needs instructions`, `Done`, `Failed`, or `Stopped`.
 
 From the board:
 
 - Press `Space` to peek at the selected session's summary, blocker, and latest output.
-- In Peek, press `r` to reply without attaching.
-- Press `v` for a read-only transcript, or `e` for evidence and diagnostics.
-- Press `Enter`, `Right`, or `>` to attach to the real Pi session.
+- In Peek, type to reply without attaching.
+- Press `Ctrl+O` for a read-only transcript, or `Ctrl+E` for evidence and diagnostics.
+- Press `Enter`, `Left` or `Right` to attach to the real Pi session.
 - In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft), or `Ctrl+\` — the unconditional escape: it detaches regardless of editor state on any terminal that forwards the raw 0x1c byte (raw, kitty, and modifyOtherKeys keyboard modes all work). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. Automatic themes also resolve correctly in attach sessions: the child's background probe (OSC 11) and color-scheme change notifications are forwarded to your real terminal, replies flow back to the child when your terminal answers, and attach re-probes the background once when it settles so the theme is right from the first frame. Set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable this (default on); keyboard-protocol negotiation (kitty/DA) is not forwarded — it happens once at child spawn, before attach exists. `Ctrl+X` opens an in-place delete confirm: press `y` (or Enter) to archive the row and return to the board with the next row selected — any other key cancels and is passed through to the session. While attached, the child Pi's own `Ctrl+X` bindings (copy in `/tree` and fullscreen, clear-all in the models dialog) are captured by this gesture.
 
 ## Dashboard Workflow
 
-The dashboard has two input modes:
+The input is always ready:
 
-- **Normal mode** owns dashboard shortcuts such as navigation, peek, attach, and filtering.
-- **INSERT mode** owns text editing. Press `i` before typing or pasting a task; `/` is literal while editing a prompt.
+- With an empty input, keys drive the board. `/`, `!`, `?` and `Space` are shortcuts only here.
+- Once you've typed something, keys edit the task, and `/` is literal.
 
 When you press `Ctrl+N` while typing a task, the **Start session** dialog lets you review:
 
@@ -113,11 +112,11 @@ Launch preferences are persisted and reused for later sessions. **Start & attach
 
 Session actions are deliberately confirmation-aware:
 
-- `d` confirms moving an inactive session to **Done**. Manual completion is the default.
-- `h` toggles the on-hold state (manual verdict — automated writers are fenced).
-- Press `x`, then `y` to confirm deleting the selected row. `Ctrl+X` twice quickly still deletes without confirmation. Archiving removes the row from the board but preserves its underlying Pi session file.
-- `X` archives inactive rows in the selected state; live work is skipped.
-- `m` enters multi-select mode; see [Multi-select](#multi-select) for its keys.
+- `Ctrl+D` confirms moving an inactive session to **Done**. Manual completion is the default.
+- `Ctrl+B` toggles the on-hold state (manual verdict — automated writers are fenced).
+- `Ctrl+X` stops a session, and a second press within 2 seconds deletes its row. Deleting removes the row from the board but preserves its underlying Pi session file.
+- `Ctrl+K` archives inactive rows in the selected state; live work is skipped.
+- `Ctrl+A` enters multi-select mode; see [Multi-select](#multi-select) for its keys.
 
 ## Views and Actions
 
@@ -125,34 +124,46 @@ Shortcuts are scoped to the view where they are available:
 
 ### Main list
 
+Typing goes straight into the input, as in Claude Code's agent view, so there's no mode to enter first.
+
 | Key | Action |
 | --- | --- |
-| `Up` / `Down` / `j` / `k` | Move the selection. |
-| `i` | Enter INSERT mode for a new task. |
-| `Enter` | Start a draft right away, or attach/resume when the input is empty. |
-| `Right` / `>` / `l` | Attach to the selected session. |
-| `Space` | Open Peek. |
-| `v` | Open the read-only transcript. |
-| `e` | Open Evidence / Diagnostics. |
-| `/` | Enter filter mode. |
-| `Ctrl+N` | Enter INSERT mode with a pre-filled `hello` prompt. |
-| `Left` twice | From an empty Pi prompt, open the board. |
-| `Ctrl+R` | Rename the selected session. |
-| `Ctrl+T` | Pin or unpin the selected session. |
-| `Ctrl+S` | Stop the selected active session. |
-| `d` | Confirm marking the selected inactive session Done. |
-| `h` | Hold or unhold the selected inactive session. |
-| `x`, then `y` | Archive/delete the selected row (confirmation prompt). |
-| `Ctrl+X` twice quickly | Archive/delete the selected row without confirmation. |
-| `X` | Delete inactive rows in the selected state. |
-| `m` | Enter multi-select mode. |
-| `!` | Open node-pty diagnostics and fix steps. |
-| `?` | Open the help overlay. |
-| `Esc` | Clear a draft, or exit when the input is empty. |
+| Any text | Start writing a task. |
+| `Enter` | Start the task, or attach to the selected session when the input is empty. |
+| `Ctrl+Enter` | Start the task and attach to it. |
+| `Shift+Enter` / `Ctrl+J` | New line in the task. |
+| `Ctrl+N` | While typing, choose the folder, model and thinking level first. |
+| `Left` / `Right` | Attach to the selected session. |
+| `Left` twice | From an empty Pi prompt, put this session on the board and open it. |
+| `Up` / `Down` | Move between rows. |
+| `PgUp` / `PgDn` | Move by a screenful. |
+| `Home` / `End` | First or last row. |
+| `Alt+Up` / `Alt+Down` | Previous or next group. |
+| `Alt+1`..`Alt+9` | Attach to that row. |
+| `Space` | Open or close Peek. |
+| `/` / `Ctrl+F` | Filter the list. |
+| `Ctrl+S` | Group by state or by directory. |
+| `Shift+Up` / `Shift+Down` | Move the row up or down its group. |
+| `Ctrl+G` | Write the task in `$VISUAL` or `$EDITOR`. |
+| `Ctrl+T` | Pin or unpin. |
+| `Ctrl+R` | Rename. |
+| `Ctrl+X` | Stop the session; press again within 2 seconds to delete it. |
+| `Ctrl+D` | Confirm marking an inactive session Done. |
+| `Ctrl+B` | Hold or unhold an inactive session. |
+| `Ctrl+A` | Select several rows. |
+| `Ctrl+O` | Read-only transcript. |
+| `Ctrl+E` | Evidence / Diagnostics. |
+| `Ctrl+K` | Delete inactive rows in the selected state. |
+| `!` | node-pty diagnostics and fix steps. |
+| `?` | Help. |
+| `Esc` | Clear a draft, or leave the board. |
+| `Ctrl+C` | Clear a draft; press twice to leave. |
+
+On macOS, the `Alt` keys need your terminal to send Option as Alt.
 
 ### Multi-select
 
-Press `m` in the main list to act on several sessions at once.
+Press `Ctrl+A` in the main list to act on several sessions at once.
 
 | Key | Action |
 | --- | --- |
@@ -172,15 +183,15 @@ Peek shows the selected session's summary, blocker or question, latest output, a
 
 | Key | Action |
 | --- | --- |
-| `r` or `Enter` | Enter reply mode; type a follow-up and press `Enter` to send it without attaching. |
-| `a`, `Right`, `>`, or `l` | Attach to the session. |
-| `v` | Open the read-only transcript. |
-| `e` | Open Evidence / Diagnostics. |
-| `d` | Confirm marking the inactive session Done. |
-| `h` | Hold or unhold the session. |
+| Any text | Start a reply, and press `Enter` to send it without attaching. |
+| `Left` / `Right` | Attach to the session. |
+| `Up` / `Down` | Move to the previous or next session. |
+| `Ctrl+O` | Open the read-only transcript. |
+| `Ctrl+E` | Open Evidence / Diagnostics. |
+| `Ctrl+D` | Confirm marking the inactive session Done. |
+| `Ctrl+B` | Hold or unhold the session. |
 | `!` | Open node-pty diagnostics and fix steps. |
-| `Up` / `Down` / `j` / `k` | Move to the previous or next session. |
-| `Esc` | Return to the main list. |
+| `Space` / `Esc` | Return to the main list. |
 
 When a Pi question or questionnaire tool is pending, inline reply is rejected; attach to answer that interactive question in the real Pi session.
 
@@ -320,33 +331,47 @@ Other current limitations:
 
 ## Configuration
 
-Set these variables before starting Pi. Model-backed features fall back gracefully where noted, so disabling them does not prevent the core dashboard from working.
+Settings live in `~/.pi/agent/extensions/pi-board/config.json`. Everything is optional, and a missing or broken file means the defaults. Restart Pi after editing it.
 
-| Variable | Default / values | Purpose |
+```json
+{
+  "model": "provider/model-id",
+  "autoDone": false
+}
+```
+
+### Helper model
+
+Titles, row summaries and telling `Needs answer` from `Needs instructions` can use a model. **It's off by default**, so the board makes no model calls of its own and uses built-in rules instead.
+
+Run `/board-model` inside Pi to pick a model or turn it off. It's saved to the file above and applies to sessions started from then on. These calls run through Pi, so any model Pi can use works, and they send up to 6,000 characters of a session's latest reply to that model.
+
+### Other settings
+
+| Key | Default | Purpose |
 | --- | --- | --- |
-| `AGENT_BOARD_ROOT` | `~/.pi/agent/agent-board/` | Override the durable store location. |
-| `AGENT_BOARD_AUTO_STATE` | enabled; `off` disables | Enable automatic terminal-state refinement after a turn. |
-| `AGENT_BOARD_AUTO_STATE_MODEL` | `gpt-4o`; `off` uses heuristics | Model for classifying the terminal state of a finished turn. |
-| `AGENT_BOARD_AUTO_STATE_NO_DONE` | unset = manual Done; `0`, `false`, `off`, or `no` restores auto-Done | Keep completion manual by default, or restore automatic `Done` classification. |
-| `AGENT_BOARD_SUMMARY_MODEL` | `gpt-4o`; `off` disables | Generate short row summaries. Heuristic summaries remain available as a fallback. |
-| `AGENT_BOARD_TITLE_MODEL` | `openai-codex/gpt-5.5`; `off` disables | Generate a short session title after dispatch. The initial slug remains if generation fails. |
-| `AGENT_BOARD_TITLE_THINKING_LEVEL` | `low`; `off` omits the option | Thinking level used by title generation. |
-| `AGENT_BOARD_CODE_REFS` | enabled; `off` disables | Extract issue/PR badges from session evidence. |
-| `AGENT_BOARD_DISABLE_PTY` | unset; `1` disables | Disable PTY host and attach mode. |
-| `AGENT_BOARD_FORCE_PTY` | unset; `1` forces the PTY path | Force the PTY availability path when diagnosing or controlling fallback behavior. |
-| `AGENT_BOARD_ATTACH_MOUSE` | enabled; `0`, `off`, or `false` disables | Disable attach-view mouse handling and use terminal-native selection instead. |
-| `AGENT_BOARD_ENABLE_MOUSE_SCROLL` | enabled; `0` disables | Compatibility switch to disable attach-view mouse scrolling. |
-| `AGENT_BOARD_WHEEL_LINES` | `1`, clamped to `1..50` | Lines scrolled per mouse-wheel notch in the attach view (regular TUI mode; in fullscreen the TUI's own wheel accelerator decides the line count). |
-| `AGENT_BOARD_MAX_WARM_HOSTS` | `4`, clamped to `0..50` | Maximum number of idle PTY hosts retained for faster attach. |
-| `AGENT_BOARD_WARM_HOST_TTL_MS` | `600000` (10 minutes); `0` disables TTL eviction | How long an idle warm host may remain before it is evicted. |
-| `AGENT_BOARD_ATTACH_NATIVE_PASTE` | enabled; `0` disables | Disable X11 PRIMARY selection copy and middle-click paste integration. |
-| `AGENT_BOARD_FORWARD_OSC52` | enabled; `0` disables | Disable OSC 52 clipboard sequence forwarding from an attached session. |
-| `AGENT_BOARD_FORWARD_IMAGES` | enabled; `0` disables | Disable terminal image/file passthrough forwarding from an attached session. |
-| `AGENT_BOARD_IME_FIX` | enabled; `0` disables | Disable the attach-view IME cursor coalescer if your terminal has compatibility problems. |
-| `AGENT_BOARD_TERMINAL_SNAPSHOT` | enabled; `0` forces legacy | Force the pre-phase-4 attach path (screen.log replay + jiggle); escape hatch / rollback switch for the snapshot+subscribe attach protocol. |
-| `AGENT_BOARD_REPLY_GUARD` | enabled; `0`, `off`, or `false` disables | Discard terminal reply fragments (device attributes, kitty flags, cell size, DCS) that pi-tui delivers as input, and forward color replies whole. While a reply head is open, up to 64 bytes / 250ms of following input is absorbed. |
-
-`AGENT_BOARD_TERMINAL_SNAPSHOT=0` routes attach onto the legacy fallback family: the screen.log replay tail plus the shrink-and-hold jiggle redraw. These paths exist only for pre-protocol runners and as a rollback hatch — they are not part of the snapshot+subscribe protocol path (issue #91 phase 4). They will be retired once the installed runner fleet is on the snapshot protocol baseline (detectable on the wire via hello protocol fields).
+| `model` | off | Helper model, as `provider/id`. |
+| `groupBy` | `state` | `state` or `directory`. `Ctrl+S` changes it. |
+| `root` | `~/.pi/agent/agent-board/` | Where the board stores its state. |
+| `titleThinking` | `low` | Thinking level for titles. |
+| `autoDone` | `false` | Let the helper model mark sessions Done. |
+| `codeRefs` | `true` | Issue and pull request badges. |
+| `disablePty` | `false` | Turn off live terminal sessions and attach. |
+| `attachMouse` | `true` | Mouse handling in attached sessions. |
+| `mouseScroll` | `true` | Mouse wheel scrolling in attached sessions. |
+| `wheelLines` | `1` | Lines per wheel notch, from 1 to 50. |
+| `maxWarmHosts` | `4` | Idle sessions kept ready for fast attach, from 0 to 50. |
+| `warmHostTtlMs` | `600000` | How long an idle one is kept; `0` keeps it. |
+| `nativePaste` | `true` | X11 PRIMARY copy and middle-click paste. |
+| `forwardClipboard` | `true` | Forward OSC 52 clipboard writes from attached sessions. |
+| `forwardImages` | `true` | Forward terminal images from attached sessions. |
+| `imeFix` | `true` | IME cursor fix in attached sessions. |
+| `terminalSnapshot` | `true` | Newer attach path; `false` uses the older one. |
+| `replyGuard` | `true` | Discard stray terminal replies delivered as input. |
+
+An `AGENT_BOARD_*` environment variable that's already set overrides the file for that run.
+
+Setting `terminalSnapshot` to `false` routes attach onto the legacy fallback family: the screen.log replay tail plus the shrink-and-hold jiggle redraw. These paths exist only for pre-protocol runners and as a rollback hatch — they are not part of the snapshot+subscribe protocol path (issue #91 phase 4). They will be retired once the installed runner fleet is on the snapshot protocol baseline (detectable on the wire via hello protocol fields).
 
 Older `AGENT_VIEW_*` names are still read in selected compatibility paths. Prefer `AGENT_BOARD_*` for new setups. Internal child markers are managed by Agent Board and are not user settings.
 
@@ -413,23 +438,7 @@ npm run verify
 
 ## Publishing
 
-Releases run through `scripts/release.mjs` and are published by CI when a GitHub Release is created. The flow checks the parts that are easy to get wrong — the changelog range, tag ancestry against `main`, and drift from a late merge — instead of assuming them. See [docs/RELEASE.md](docs/RELEASE.md) for the full process, the one-time npm trusted-publisher setup, and failure recovery.
-
-```bash
-node scripts/release.mjs precheck          # gate: clean main, nothing in flight
-node scripts/release.mjs prepare minor     # changelog + verify + bump + tag + release branch
-node scripts/release.mjs open-pr 0.9.0     # push the branch and tag, open the release PR
-# merge the PR with a merge commit, then:
-node scripts/release.mjs finish 0.9.0      # GitHub Release → CI publishes to npm
-```
-
-After publishing, users install the scoped package with:
-
-```bash
-pi install npm:@huseynsnmz/pi-board
-```
-
-The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.json`.
+Published to npm by hand, with `npm publish --access public`. There's no publish workflow.
 
 ## Further Reading
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huseynsnmz/pi-board",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "A board for Pi's background sessions: start, watch, reply to and attach to them. A fork of @zhuxixi/pi-agent-board.",
   "type": "module",
   "main": "./index.ts",

package/runner/title-runner.mjs

@@ -25,7 +25,7 @@ function main() {
 async function maybeGenerateTitle(config) {
 	const configured = process.env.AGENT_BOARD_TITLE_MODEL ?? process.env.AGENT_VIEW_TITLE_MODEL;
 	if (configured === "off") return;
-	const model = config.model ?? configured ?? DEFAULT_TITLE_MODEL;
+	const model = configured ?? config.model ?? DEFAULT_TITLE_MODEL;
 	const thinking = process.env.AGENT_BOARD_TITLE_THINKING_LEVEL ?? process.env.AGENT_VIEW_TITLE_THINKING_LEVEL ?? DEFAULT_TITLE_THINKING_LEVEL;
 	const prompt = titlePrompt(config.prompt);
 	const args = [...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model];

package/src/commands/agent-board.ts

@@ -73,7 +73,7 @@ export function registerAgentBoardCommand(pi: ExtensionAPI, opts: AgentBoardComm
 }
 
 export async function openDashboard(
-	ctx: Pick<ExtensionCommandContext, "ui" | "cwd" | "modelRegistry" | "model">,
+	ctx: Pick<ExtensionCommandContext, "ui" | "cwd" | "modelRegistry" | "model" | "sessionManager">,
 	service: ReturnType<typeof createService>,
 	options: {
 		initialSelectedId?: string | null;
@@ -104,6 +104,7 @@ export async function openDashboard(
 					service,
 					root: service.getRoot(),
 					defaultCwd: ctx.cwd,
+					currentSessionFile: ctx.sessionManager?.getSessionFile?.() ?? null,
 					initialSelectedId: options.initialSelectedId,
 					initialNotice: options.initialNotice,
 					availableModels,
@@ -159,6 +160,8 @@ export async function dashboardAttachLoop(
 		});
 		pendingNotice = undefined;
 		if (result.action !== "attach") return;
+		// That session is the one on screen behind the board: going back to it is just closing.
+		if (result.viewId === currentId) return;
 		selectedId = result.viewId;
 		const outcome = await attach(ctx, service, root, result.viewId, result.stopFirst);
 		if (outcome.afterDelete) {

package/src/commands/bg.ts

@@ -3,6 +3,8 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { createService } from "../runtime/service.mjs";
 import { dashboardAttachLoop } from "./agent-board.js";
 
+const NEW_SESSION = "new session";
+
 export interface BgCommandOptions {
 	root: string;
 	runnerScript: string;
@@ -28,10 +30,6 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 		return;
 	}
 	const sessionFile = ctx.sessionManager.getSessionFile();
-	if (!sessionFile) {
-		ctx.ui.notify("No current session file is available to background.", "warning");
-		return;
-	}
 	const service = createService({
 		root: opts.root,
 		runnerScript: opts.runnerScript,
@@ -50,6 +48,11 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 			}
 		},
 	});
+	// A session that isn't saved anywhere has nothing to come back to, but the board still opens.
+	if (!sessionFile) {
+		await dashboardAttachLoop(ctx, service, opts.root, null, opts.getThinkingLevel);
+		return;
+	}
 	const model = modelRef(ctx.model as any);
 	// adoptSession is async (routes through the view-state coordinator, issue #91).
 	const adopted = await service.adoptSession({
@@ -57,7 +60,8 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 		cwd: ctx.cwd,
 		model,
 		thinkingLevel: opts.getThinkingLevel(),
-		name: "background-session",
+		// A row that exists keeps its name, which may be one you gave it.
+		name: hasOwnName(service, sessionFile) ? undefined : sessionName(ctx),
 	});
 	if (!adopted.ok || !adopted.viewId) {
 		ctx.ui.notify(adopted.error ?? "Could not background current session.", "warning");
@@ -72,6 +76,25 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 	await dashboardAttachLoop(ctx, service, opts.root, adopted.viewId, opts.getThinkingLevel);
 }
 
+function hasOwnName(service: ReturnType<typeof createService>, sessionFile: string): boolean {
+	const row = service.rows().find((candidate) => candidate.meta.sessionFile === sessionFile);
+	return row !== undefined && row.meta.name !== NEW_SESSION;
+}
+
+/** Its name if it has one, then what you first asked. A session with neither is new. */
+function sessionName(ctx: ExtensionCommandContext): string {
+	const named = ctx.sessionManager.getSessionName?.();
+	if (named) return named;
+	for (const entry of ctx.sessionManager.getEntries() as any[]) {
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const content = entry.message.content;
+		const text = typeof content === "string" ? content : (content ?? []).map((part: any) => part.text ?? "").join(" ");
+		const line = String(text).trim().split("\n")[0];
+		if (line) return line.slice(0, 48);
+	}
+	return NEW_SESSION;
+}
+
 function modelRef(model: any): string | null {
 	if (!model || typeof model !== "object") return null;
 	if (typeof model.provider === "string" && typeof model.id === "string") return `${model.provider}/${model.id}`;

package/src/commands/board-model.ts

@@ -0,0 +1,21 @@
+/** `/board-model`: which model writes the board's titles, summaries and states. */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { readConfig, setHelperModel } from "../core/config.mjs";
+
+const OFF = "Off: use built-in rules, no model calls";
+
+export function registerBoardModelCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("board-model", {
+		description: "Choose the model for the board's titles, summaries and states, or turn it off",
+		handler: async (_args, ctx: ExtensionCommandContext) => {
+			if (!ctx.hasUI) return;
+			const refs = ctx.modelRegistry.getAvailable().map((model) => `${model.provider}/${model.id}`);
+			const current = readConfig().model;
+			const choice = await ctx.ui.select(`Board helper model (now: ${current ?? "off"})`, [OFF, ...refs]);
+			if (choice === undefined) return;
+			const model = choice === OFF ? null : choice;
+			setHelperModel(model);
+			ctx.ui.notify(model ? `The board's helper calls now use ${model}.` : "The board's helper model calls are off.", "info");
+		},
+	});
+}

package/src/core/config.mjs

@@ -0,0 +1,77 @@
+/**
+ * The board's settings, from `~/.pi/agent/extensions/pi-board/config.json`.
+ *
+ * The runners are separate processes that read `AGENT_BOARD_*` from their environment, so a
+ * setting reaches them by being put there before anything starts. A variable that's already set
+ * wins, which keeps one run's override and the tests working.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Which model each kind of helper call uses when the config has none of its own. */
+const MODEL_VARS = ["AGENT_BOARD_AUTO_STATE_MODEL", "AGENT_BOARD_SUMMARY_MODEL", "AGENT_BOARD_TITLE_MODEL"];
+
+const off = (value) => (value ? "1" : "0");
+const SETTINGS = {
+	root: ["AGENT_BOARD_ROOT", String],
+	titleThinking: ["AGENT_BOARD_TITLE_THINKING_LEVEL", String],
+	autoDone: ["AGENT_BOARD_AUTO_STATE_NO_DONE", (value) => (value ? "0" : "1")],
+	codeRefs: ["AGENT_BOARD_CODE_REFS", (value) => (value ? "1" : "off")],
+	disablePty: ["AGENT_BOARD_DISABLE_PTY", (value) => (value ? "1" : "")],
+	attachMouse: ["AGENT_BOARD_ATTACH_MOUSE", off],
+	mouseScroll: ["AGENT_BOARD_ENABLE_MOUSE_SCROLL", off],
+	wheelLines: ["AGENT_BOARD_WHEEL_LINES", String],
+	maxWarmHosts: ["AGENT_BOARD_MAX_WARM_HOSTS", String],
+	warmHostTtlMs: ["AGENT_BOARD_WARM_HOST_TTL_MS", String],
+	nativePaste: ["AGENT_BOARD_ATTACH_NATIVE_PASTE", off],
+	forwardClipboard: ["AGENT_BOARD_FORWARD_OSC52", off],
+	forwardImages: ["AGENT_BOARD_FORWARD_IMAGES", off],
+	imeFix: ["AGENT_BOARD_IME_FIX", off],
+	terminalSnapshot: ["AGENT_BOARD_TERMINAL_SNAPSHOT", off],
+	replyGuard: ["AGENT_BOARD_REPLY_GUARD", off],
+};
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function configPath(env = process.env) {
+	const agentDir = env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+	return path.join(agentDir, "extensions", "pi-board", "config.json");
+}
+
+/** A missing or broken file is the defaults: the board must still open. */
+export function readConfig(file = configPath()) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+export function writeConfig(changes, file = configPath()) {
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify({ ...readConfig(file), ...changes }, null, 2)}\n`);
+}
+
+/** Helper model calls cost money and send text to a provider, so they're off until one is chosen. */
+export function configEnv(config) {
+	const vars = {};
+	for (const [key, [name, convert]] of Object.entries(SETTINGS)) {
+		if (config[key] !== undefined && config[key] !== null) vars[name] = convert(config[key]);
+	}
+	const models = typeof config.model === "string" && config.model ? config.model : "off";
+	for (const name of MODEL_VARS) vars[name] = models;
+	return vars;
+}
+
+export function applyConfig(env = process.env, config = readConfig(configPath(env))) {
+	for (const [name, value] of Object.entries(configEnv(config))) {
+		if (env[name] === undefined) env[name] = value;
+	}
+}
+
+/** Takes effect for sessions started from now on. */
+export function setHelperModel(model, env = process.env, file = configPath(env)) {
+	writeConfig({ model }, file);
+	for (const name of MODEL_VARS) env[name] = model ?? "off";
+}

package/src/core/load-config.mjs

@@ -0,0 +1,4 @@
+/** Imported first, because some modules read their settings as they load. */
+import { applyConfig } from "./config.mjs";
+
+applyConfig();

package/src/core/rows.mjs

@@ -154,6 +154,7 @@ export function rowView(row, now) {
 		folderName,
 		folderPath,
 		pinned: Boolean(row.meta.pinned),
+		order: row.meta.order ?? row.meta.createdAt ?? 0,
 		state,
 		alive: Boolean(row.alive),
 		hostAlive: Boolean(row.hostAlive),
@@ -257,6 +258,24 @@ export function groupRowsByFolder(rows, now) {
 	return groups;
 }
 
+/**
+ * The other way to see the list: one group per directory, whatever state its rows are in.
+ * @param {Row[]} rows
+ * @param {number} now
+ * @returns {Array<{ key: string, name: string, path: string, rows: RowView[] }>}
+ */
+export function groupRowsByDirectory(rows, now) {
+	const byFolder = new Map();
+	for (const view of rows.map((r) => rowView(r, now))) {
+		const existing = byFolder.get(view.folderKey);
+		if (existing) existing.rows.push(view);
+		else byFolder.set(view.folderKey, { key: view.folderKey, name: view.folderName, path: view.folderPath, rows: [view] });
+	}
+	const folders = [...byFolder.values()];
+	for (const folder of folders) folder.rows = sortRowViews(folder.rows);
+	return folders.sort((a, b) => Math.min(...a.rows.map((r) => r.createdAt)) - Math.min(...b.rows.map((r) => r.createdAt)) || a.name.localeCompare(b.name));
+}
+
 /**
  * Issue #147: the row the board should select after `id` is removed — the
  * next visible row in dashboard order, else the previous one, else null
@@ -286,6 +305,7 @@ function sortRowViews(views) {
 	return views.sort(
 		(a, b) =>
 			Number(b.pinned) - Number(a.pinned) ||
+			a.order - b.order ||
 			a.createdAt - b.createdAt ||
 			a.id.localeCompare(b.id),
 	);

package/src/index.ts

@@ -5,6 +5,7 @@
  * launch background workers and the detached runner, and keeps a small footer status with
  * the count of sessions needing attention. See docs/EXPLORATION.md for the design.
  */
+import "./core/load-config.mjs";
 import { fileURLToPath } from "node:url";
 import { createConnection } from "node:net";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -15,8 +16,10 @@ import { createService, envInt } from "./runtime/service.mjs";
 import { attachWarmHostSweeper } from "./core/warm-host-sweeper.mjs";
 import { openDashboard, registerAgentBoardCommand } from "./commands/agent-board.js";
 import { registerBgCommand } from "./commands/bg.js";
+import { registerBoardModelCommand } from "./commands/board-model.ts";
 import { announceBoardClosedOn } from "./ui/chrome.ts";
 import { watchDoubleLeft } from "./ui/double-left.ts";
+import { watchWaiting } from "./ui/waiting.ts";
 
 const RUNNER_SCRIPT = fileURLToPath(new URL("../runner/job-runner.mjs", import.meta.url));
 const PTY_RUNNER_SCRIPT = fileURLToPath(new URL("../runner/pty-runner.mjs", import.meta.url));
@@ -40,6 +43,7 @@ let hostedSessionEpoch = 0;
 export default function piAgentBoard(pi: ExtensionAPI): void {
 	announceBoardClosedOn(pi.events);
 	let stopDoubleLeft: (() => void) | null = null;
+	let stopWaiting: (() => void) | null = null;
 	const root = defaultRoot();
 	const { piCommand, piArgsPrefix } = resolvePiInvocation();
 
@@ -85,6 +89,7 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 
 	registerAgentBoardCommand(pi, commandOpts);
 	registerBgCommand(pi, commandOpts);
+	registerBoardModelCommand(pi);
 	pi.registerFlag("agent-board", {
 		description: "Open the agent-board dashboard on startup",
 		type: "boolean",
@@ -198,6 +203,10 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 			stopDoubleLeft?.();
 			stopDoubleLeft = watchDoubleLeft(ctx);
 		}
+		if (ctx.mode === "tui") {
+			stopWaiting?.();
+			stopWaiting = watchWaiting(ctx, (waiting) => syncForeground({ type: "agent_board_waiting", waiting }, ctx));
+		}
 		if (isHostedChild && !hostedEditorReporter && typeof ctx.ui?.getEditorText === "function" && hostedViewId) {
 			const { createEditorStateReporter } = await import("./core/editor-state-reporter.mjs");
 			hostedEditorReporter = createEditorStateReporter({

package/src/runtime/service.mjs

@@ -1377,7 +1377,8 @@ export function createService(opts) {
 		const pty = ptySupport();
 		if (!pty.ok) return { ok: false, error: "PTY unavailable", fallbackReason: nodePtyFallbackMessage(pty) };
 		if (isAgentBusy(row)) return { ok: false, error: "A non-live background run is active for this session" };
-		if (!existsSync(row.meta.sessionFile)) return { ok: false, error: "Session file isn't ready yet" };
+		// A missing file is a session that was put on the board before its first message. Pi starts
+		// it at that path, as it would have.
 
 		const lock = tryAcquireLockImpl(root, viewId, "host-start", { identity: serviceIdentity() });
 		if (!lock.acquired) {
@@ -1809,6 +1810,16 @@ export function createService(opts) {
 			appendDiagnostic(root, row.meta.id, { source: "evidence", level: "warn", code: "evidence_reduce_failed", message: "Could not reduce hosted evidence", details: { error: err instanceof Error ? err.message : String(err) } });
 		}
 
+		if (event.type === "agent_board_waiting") {
+			status.semanticState = event.waiting ? "needs_input" : "working";
+			status.processState = "alive";
+			status.question = event.waiting ? "Waiting on a prompt. Attach to answer it." : null;
+			status.summary = event.waiting ? "Waiting on a prompt" : "Running…";
+			status.lastActivityAt = now;
+			void writeForegroundState(row, status);
+			return true;
+		}
+
 		if (event.type === "input" || event.type === "before_agent_start" || event.type === "agent_start") {
 			status.semanticState = "working";
 			status.processState = "alive";
@@ -2293,6 +2304,22 @@ export function createService(opts) {
 			return { ok: true };
 		},
 
+		/**
+		 * Gives these rows this order, numbered from the lowest they had: rows created in the same
+		 * millisecond have no order between them to swap.
+		 * @param {string[]} viewIds
+		 */
+		setRowOrder(viewIds) {
+			const metas = viewIds.map((id) => loadRow(root, id)?.meta);
+			if (metas.some((meta) => !meta)) return { ok: false, error: "Unknown session" };
+			const base = Math.min(...metas.map((meta) => meta.order ?? meta.createdAt ?? 0));
+			metas.forEach((meta, index) => {
+				meta.order = base + index;
+				writeMeta(root, meta);
+			});
+			return { ok: true };
+		},
+
 		/** @param {string} viewId @param {string} name */
 		rename(viewId, name) {
 			const clean = String(name || "").trim();