@junghanacs/entwurf 0.32.0 → 0.34.0

package/docs/setup-clean-host.md

@@ -28,8 +28,8 @@ evidence split, and its three states must not collapse into "macOS is supported"
 | npm/pnpm | npm is bundled with Node; pnpm is required for source setup | package or source installation |
 | Python 3 | required by `setup`/`install` (project-path normalization + settings writers); `--help`/`check-bridge` stay Python-free | pi/Claude/agy/Copilot/Codex wiring writers |
 | entwurf | global/project-local `@junghanacs/entwurf`, or a source checkout | operator command and garden capability |
-| pi | optional-by-presence, `>=1.0.4 <1.1` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
-| Native durable (`pi-durable`) | supplied by the Entwurf package (#130): a pinned upstream v1.0.4 app carrier plus the exact 1.0.4 pi SDK set as production dependencies — setup PASS when they verify, a named FAIL otherwise (never SKIP) | the `entwurf pi-durable` contact; native birth/LIVE on this supply surface is a separate release proof (§2b) |
+| pi | optional-by-presence, `>=1.1.0 <1.2` — absent is an explicit setup SKIP, below-floor is a named FAIL | ACP provider, control sockets |
+| Native durable (`pi-durable`) | supplied by the Entwurf package (#130): a pinned upstream v1.1.0 app carrier plus the exact 1.1.0 pi SDK set as production dependencies — setup PASS when they verify, a named FAIL otherwise (never SKIP) | the `entwurf pi-durable` contact; native birth/LIVE on this supply surface is a separate release proof (§2b) |
 | Claude Code | optional, **`>=2.1.217`** — the exec-form hook floor | Claude ACP auth/runtime and mailbox-backed native citizen |
 | GitHub Copilot CLI | optional-by-presence, operator-installed and authenticated — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/receiver/footer) | self-fetch citizen and visible fresh |
 | OMP (`omp`) | optional-by-presence, operator-installed — absent is an explicit setup SKIP; detected composes all four units (birth/MCP/`tools.xdev` setting/receiver) | self-fetch citizen and visible fresh (accepted on one host — see §4b) |
@@ -191,7 +191,7 @@ on Darwin; that is wiring, not a rail receipt. If `pi` is on PATH,
 Install the exact release floor, then wire the project:
 
 ```bash
-npm install -g @earendil-works/pi-coding-agent@1.0.4
+npm install -g @earendil-works/pi-coding-agent@1.1.0
 pi --version
 
 cd ~/entwurf-smoke
@@ -199,7 +199,7 @@ entwurf install .
 pi -e "$(npm root -g)/@junghanacs/entwurf" --list-models entwurf
 ```
 
-The supported range is `>=1.0.4 <1.1`. It is a hard minimum: installing this
+The supported range is `>=1.1.0 <1.2`. It is a hard minimum: installing this
 release onto a 0.83.x pi host upgrades the runtime rather than keeping the older
 minor. A host using only the external MCP bridge can skip pi until it needs a
 control socket; no delivery rail launches a pi process.
@@ -295,22 +295,22 @@ by `entwurf pi` or by registering ordinary Pi's adapter.
 What the Entwurf package supplies:
 
 1. **The pi SDK set** — `@earendil-works/{pi-coding-agent, pi-ai, pi-tui, pi-agent-core,
-   pi-durable, chord, pi-mcp, pi-codemode, pi-telemetry}` at exactly `1.0.4`, plus
+   pi-durable, chord, pi-mcp, pi-codemode, pi-telemetry}` at exactly `1.1.0`, plus
    `proper-lockfile`, as Entwurf's own production dependencies (declared once in
    `pi/pi-durable/overlay/upstream-pin.json` `sdk`). Model data rides the published
    `pi-ai`; there is no catalog copy.
 2. **The native app/TUI carrier** — upstream does not publish the experimental durable
    app (`pi-coding-agent` excludes `dist/experimental`; `pi-durable` on npm is the
-   library). Entwurf ships the six pinned app files from upstream tag `v1.0.4`
-   (`7c10bd4337495ee613f2224843ecdf349b80d1df`), its narrow runtime-contact overlay
+   library). Entwurf ships the six pinned app files from upstream tag `v1.1.0`
+   (`abe508e1b89912adde45528136c3221eb69acdd7`), its narrow runtime-contact overlay
    applied to `runtime.ts`, type-stripped and relocated, in `pi/pi-durable/carrier/`
    with upstream's MIT license. Each file's source blob and emitted digest are in the pin.
    The carrier reaches pi-coding-agent's internals only through its resolver
    (`pi/pi-durable/carrier-resolver.mjs`), which maps them to the published package's
    own `dist/` as installed — never through a source checkout.
 
-The upstream [library guide](https://github.com/earendil-works/pi/blob/v1.0.4/packages/durable/README.md)
-and [experimental app guide](https://github.com/earendil-works/pi/blob/v1.0.4/packages/coding-agent/src/experimental/durable/README.md)
+The upstream [library guide](https://github.com/earendil-works/pi/blob/v1.1.0/packages/durable/README.md)
+and [experimental app guide](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/src/experimental/durable/README.md)
 describe what the carrier is. Running the bare upstream app does not attach Entwurf's
 garden contact. Entwurf does not rebuild the controller/model/auth/storage system or
 proxy a subscription; native execution, models, auth, queues, SQLite and recovery stay
@@ -327,7 +327,7 @@ and from every package copy it reaches, at any depth, to its own `@earendil-work
 lands on a package of the declared name at exactly the pinned version (`pi-durable-sdk-mismatch`). The members declare one another with caret
 ranges, so semver satisfaction is not the contract; the bytes an import binds are. Sharing
 one copy with an aligned host install of the same version is an ordinary layout. A mixed
-tree (for example an override that binds pi-durable's `pi-ai` one patch behind) still
+tree (for example an override that binds pi-durable's `pi-ai` to an older published version) still
 *imports* — which is why the edge check exists — and is refused by name.
 
 - `entwurf setup` reports a `pi-durable` row from that check and writes no durable wiring:
@@ -358,12 +358,33 @@ tree (for example an override that binds pi-durable's `pi-ai` one patch behind)
   (`native-module-path-*`), a module that throws (`native-module-import-failed`), a function or
   nameless default (`native-module-export-invalid`), an extension named like one the app installs
   itself (`entwurf`, `coding-tools`, `pi-prompt`, `subagent`) or a tool named like one of Entwurf's
-  contact tools (`native-module-name-reserved`; any other duplicate is the native registry's to
-  judge), and a module whose initialization changes
+  contact tools (`native-module-name-reserved`; within one module, any other duplicate is the native
+  registry's to judge), and a module whose initialization changes
   `PI_SESSION_ID`, `PI_CODING_AGENT_DIR`, `HOME` or any `ENTWURF_*` (`native-module-env-identity-changed`)
   or the process directory (`native-module-cwd-changed`). Your module is trusted code; those
-  checks catch mistakes, they do not sandbox it. Nothing else names a module — no directory,
-  setting or profile — and a sibling opened by `entwurf_fresh_call` starts without one.
+  checks catch mistakes, they do not sandbox it. Nothing else names a module — no default
+  directory, setting or profile — and a sibling opened by `entwurf_fresh_call` starts without one.
+
+- **A module directory instead (#134, after 0.33.0).** `--native-module-dir
+  <absolute directory>` replaces `--native-module` (naming both is `native-module-ingress-exclusive`).
+  Entwurf reads that one directory once, at its top level: every `*.extension.mjs` that is not a
+  dotfile is a module; helpers such as `env.mjs` or `index.mjs`, other suffixes, subdirectories and
+  directory links are never opened. The modules initialize one by one in byte-wise name order
+  (`00-env.extension.mjs` before `10-tools.extension.mjs`), each under the same checks as above,
+  and install in that order after the contact. Also refused by name: a directory without a module
+  (`native-module-dir-empty`), a matching entry that is not a regular file
+  (`native-module-path-invalid`), two names for one file (`native-module-dir-duplicate-target`), and
+  a module repeating an earlier module's extension or tool name (`native-module-name-duplicate` —
+  the native registry would replace that extension or keep both tools). A refusal at a later module
+  leaves the earlier ones already evaluated; nothing is rolled back.
+
+- **Background-task badge (#134, after 0.33.0).** While a native background task is live, the durable
+  TUI shows `⏳ n tasks` as the first line under the transcript, whatever kind of task it is, with
+  the ones not running named (`aborting`, `completing`, `waiting`, `pending`). It never shrinks: a
+  short terminal loses the editor and footer before it, a one-row terminal shows only the badge, and
+  a narrow one shortens it down to `*`. `/tasks` only shows or hides the task panel; the badge stays.
+  With no background task the screen is unchanged. A task that has already finished leaves the
+  count — its outcome is reported by the task's own extension.
 
 - **Known warning.** Ordinary Pi may print `Host-provided extension packages must be declared in
   peerDependencies with a "*" range, not dependencies: @earendil-works/…` for Entwurf's
@@ -372,7 +393,7 @@ tree (for example an override that binds pi-durable's `pi-ai` one patch behind)
   manifest field; it is a known constraint of supplying both from one package, accepted for 0.32,
   not a claim that every load path is harmless.
 
-The ordinary Pi CLI on PATH is a separate subject (§2, range `>=1.0.4 <1.1`): a host Pi is
+The ordinary Pi CLI on PATH is a separate subject (§2, range `>=1.1.0 <1.2`): a host Pi is
 not needed to run pi-durable, and a host inside the range need not be the same copy as the
 carrier's. Native Pi owns credentials, model settings and durable SQLite sessions; keep them
 in place rather than copying credentials or migrating ordinary Pi transcripts. Native
@@ -562,7 +583,7 @@ as a note rather than a fault.
 
 **entwurf sets no OMP version floor in code, and will not grow one on schedule.** Detection is
 presence-only (`command -v "${OMP_BIN:-omp}"`); there is no `entwurf.ompFloor`, no coherence
-gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.0.4 <1.1`) and Claude Code
+gate, and no exact pin — unlike Node (`engines.node`), pi (`>=1.1.0 <1.2`) and Claude Code
 (`entwurf.claudeCodeFloor`), each of which has an enforcement point. That asymmetry is a
 decision, not an omission. A floor is the answer to a vendor that fails SILENTLY — Claude Code
 earned one because an older binary validates the exec manifest, drops `args` at runtime, and

package/mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js

@@ -16,7 +16,7 @@
  * The bootstrap that composes the two lives with the overlay (`pi/pi-durable/bootstrap.mjs`), not
  * here: this module never imports or initializes the durable app runtime and carries no path into
  * a vendor checkout. That is this module's import boundary, not the package's dependency list: the
- * package does declare the exact `@earendil-works/pi-durable` (1.0.4) for its carrier (#130).
+ * package does declare the exact `@earendil-works/pi-durable` (per the pin's SDK set) for its carrier (#130).
  *
  * WHY BIRTH IS AFTER OPEN, BEHIND A GATE. `[read @cd32f77]` The native session id is chosen
  * inside `openDurable` (`runtime.ts:125`, `sessions.ts:18-55`), and `openDurable` calls

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.32.0",
+	"version": "0.34.0",
 	"description": "Garden-citizen dispatch substrate and meta-bridge for pi, Claude Code, Copilot CLI, OMP, Antigravity, and Codex CLI; Claude and Snowflake Cortex Code ACP backends.",
 	"license": "MIT",
 	"author": {
@@ -93,15 +93,15 @@
 		"@agentclientprotocol/claude-agent-acp": "0.85.1",
 		"@agentclientprotocol/sdk": "1.6.0",
 		"@anthropic-ai/sdk": "0.100.1",
-		"@earendil-works/chord": "1.0.4",
-		"@earendil-works/pi-agent-core": "1.0.4",
-		"@earendil-works/pi-ai": "1.0.4",
-		"@earendil-works/pi-codemode": "1.0.4",
-		"@earendil-works/pi-coding-agent": "1.0.4",
-		"@earendil-works/pi-durable": "1.0.4",
-		"@earendil-works/pi-mcp": "1.0.4",
-		"@earendil-works/pi-telemetry": "1.0.4",
-		"@earendil-works/pi-tui": "1.0.4",
+		"@earendil-works/chord": "1.1.0",
+		"@earendil-works/pi-agent-core": "1.1.0",
+		"@earendil-works/pi-ai": "1.1.0",
+		"@earendil-works/pi-codemode": "1.1.0",
+		"@earendil-works/pi-coding-agent": "1.1.0",
+		"@earendil-works/pi-durable": "1.1.0",
+		"@earendil-works/pi-mcp": "1.1.0",
+		"@earendil-works/pi-telemetry": "1.1.0",
+		"@earendil-works/pi-tui": "1.1.0",
 		"@modelcontextprotocol/sdk": "^1.12.1",
 		"proper-lockfile": "4.1.2",
 		"smol-toml": "^1.8.0",

package/pi/pi-durable/bootstrap.mjs

@@ -50,18 +50,27 @@
 // its initialization, and its default export is a native durable Extension, handed to `openDurable`
 // by reference after the contact. Initialization runs before the TUI or the runtime is imported —
 // the runtime creates the provider runtime before it installs any extension (carrier/runtime.js
-// 140-146), so an extension object cannot carry an environment phase. Entwurf checks only what the
+// 142-148), so an extension object cannot carry an environment phase. Entwurf checks only what the
 // ingress needs: a default export object with a name, no extension name the app installs itself (a
 // same-name install REPLACES), and no tool name of the contact. Every other field is the native
 // registry's to validate. The module is trusted operator code: the identity carriers and the
 // process directory are compared across its initialization and a change is refused by name — a
-// mistake guard, not a sandbox, and nothing is rolled back. Nothing is discovered: no directory,
-// setting, environment variable or profile names a module.
+// mistake guard, not a sandbox, and nothing is rolled back. Nothing is discovered: no ambient or
+// default directory, setting, environment variable or profile names a module.
+//
+// `--native-module-dir <absolute directory>` (#134) is the paired form, exclusive with the file
+// ingress: the operator-named directory is read ONCE, top level only, and a name is a module exactly
+// when it matches `*.extension.mjs` and does not start with a dot. Every other name (helpers, tests,
+// subdirectories, directory symlinks) is ignored unopened; a matching name must resolve to a regular
+// file. The modules initialize one by one in byte-wise name order, each under the same guards; two
+// modules naming one extension or one tool are refused by name, because the native registry would
+// REPLACE the first extension or keep both tools. A refusal at module k leaves modules before it
+// evaluated: nothing is rolled back. No watch, no recursion, nothing persisted.
 //
 // Without that resolver the carrier's first pi-coding-agent internal import fails by name (an
 // unsupported entwurf-pi-dist: URL scheme), and that failure is the honest one.
-import { realpathSync, statSync } from "node:fs";
-import { isAbsolute } from "node:path";
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { decodeOmpBootstrapPayload } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-omp.js";
 import {
@@ -83,7 +92,14 @@ export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
 
 /** Flags that take a value. Anything else but `--continue`/`-c` is an unknown argument — a bridge
  * entry included: the launch argv cannot point the contact at another bridge. */
-const VALUE_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap", "--native-module"];
+const VALUE_FLAGS = [
+	"--provider",
+	"--model",
+	"--width",
+	"--entwurf-bootstrap",
+	"--native-module",
+	"--native-module-dir",
+];
 /** Flags only a NEW session can honour. */
 const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
 
@@ -93,6 +109,8 @@ const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstr
  * carrier/subagent.js:25). The native registry REPLACES an installed extension of the same name.
  */
 const RESERVED_EXTENSION_NAMES = [PI_DURABLE_EXTENSION_NAME, "coding-tools", "pi-prompt", "subagent"];
+/** A directory entry that is an operator module: `*.extension.mjs`, not a dotfile. */
+const MODULE_ENTRY = /^[^.].*\.extension\.mjs$/;
 /** The identity carriers a module's initialization must leave as it found them, every ENTWURF_* included. */
 const IDENTITY_KEYS = ["PI_SESSION_ID", "PI_CODING_AGENT_DIR", "HOME"];
 
@@ -131,6 +149,51 @@ function nativeModuleFile(value) {
 	return file;
 }
 
+/**
+ * The operator's module directory: absolute, resolving to a directory, read once at the top level. The
+ * matching entries in byte-wise name order, each resolved to a regular file and none twice. Decided
+ * before anything loads.
+ */
+function nativeModuleDirFiles(named) {
+	if (!isAbsolute(named))
+		throw refuse("native-module-path-not-absolute", `--native-module-dir takes an absolute path, got ${named}`);
+	let dir;
+	try {
+		dir = realpathSync(named);
+	} catch (error) {
+		throw Object.assign(refuse("native-module-path-invalid", `${named} does not resolve`), { cause: error });
+	}
+	if (!statSync(dir).isDirectory()) throw refuse("native-module-path-invalid", `${named} is not a directory`);
+	const names = readdirSync(dir)
+		.filter((name) => MODULE_ENTRY.test(name))
+		.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+	if (names.length === 0) {
+		throw refuse("native-module-dir-empty", `${named} holds no *.extension.mjs module at its top level`);
+	}
+	const seen = new Map();
+	return names.map((name) => {
+		let file;
+		try {
+			file = realpathSync(join(dir, name));
+		} catch (error) {
+			throw Object.assign(refuse("native-module-path-invalid", `${name} in ${named} does not resolve`), {
+				cause: error,
+			});
+		}
+		if (!statSync(file).isFile()) {
+			throw refuse(
+				"native-module-path-invalid",
+				`${name} in ${named} matches *.extension.mjs but is not a regular file`,
+			);
+		}
+		if (seen.has(file)) {
+			throw refuse("native-module-dir-duplicate-target", `${seen.get(file)} and ${name} in ${named} are the same file`);
+		}
+		seen.set(file, name);
+		return file;
+	});
+}
+
 /** The module's default export, checked only for what the ingress needs and returned BY REFERENCE. */
 function nativeExtensionOf(extension, file) {
 	if (typeof extension === "function") {
@@ -187,6 +250,31 @@ async function loadNativeModule(file) {
 	return nativeExtensionOf(namespace.default, file);
 }
 
+/**
+ * Initialize the operator's modules in order. A later module that names an extension or a tool an
+ * earlier one already did is refused by name: the native registry would replace that extension, or keep
+ * both tools, without a word.
+ */
+async function loadNativeModules(files) {
+	const extensions = [];
+	const owners = new Map();
+	for (const file of files) {
+		const extension = await loadNativeModule(file);
+		const names = [
+			`extension ${extension.name}`,
+			...(Array.isArray(extension.tools) ? extension.tools : []).map((tool) => `tool ${tool?.name}`),
+		];
+		for (const name of names) {
+			if (owners.has(name)) {
+				throw refuse("native-module-name-duplicate", `${file} and ${owners.get(name)} both name ${name}`);
+			}
+		}
+		for (const name of names) owners.set(name, file);
+		extensions.push(extension);
+	}
+	return extensions;
+}
+
 /**
  * Open the durable app with the contact installed, then birth the citizen and arm its doorbell on
  * the root conversation, then admit the first input (when given) to the root once. On any failure
@@ -198,8 +286,8 @@ async function loadNativeModule(file) {
  * roots; tests also pass a connector). `open` replaces the runtime's `openDurable` for tests.
  * `bridgeEntry` defaults to this package's own compiled bridge; only a programmatic caller (the
  * checkout-only gates, which drive a private bundle) passes another one — never the launch argv.
- * `extensions` are the operator's native extensions (`--native-module`), installed after the
- * contact, by reference.
+ * `extensions` are the operator's native extensions (`--native-module` or `--native-module-dir`),
+ * installed after the contact, by reference.
  *
  * @param {{
  *   bridgeEntry?: string,
@@ -320,7 +408,19 @@ function parseArgs(argv) {
 		);
 	}
 	const moduleArg = values.get("--native-module");
-	const nativeModule = moduleArg === undefined ? {} : { nativeModule: nativeModuleFile(moduleArg) };
+	const dirArg = values.get("--native-module-dir");
+	if (moduleArg !== undefined && dirArg !== undefined) {
+		throw refuse(
+			"native-module-ingress-exclusive",
+			"--native-module and --native-module-dir are two forms of one ingress; name the file or the directory",
+		);
+	}
+	const nativeModule =
+		moduleArg !== undefined
+			? { nativeModules: [nativeModuleFile(moduleArg)] }
+			: dirArg !== undefined
+				? { nativeModules: nativeModuleDirFiles(dirArg) }
+				: {};
 	if (continueSession) return { continueSession, ...nativeModule };
 	const provider = values.get("--provider");
 	if (provider === undefined) {
@@ -368,10 +468,10 @@ function parseArgs(argv) {
  */
 export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry } = {}) {
 	// Every argument refusal is decided here, before any module, the TUI or the app loads.
-	const { nativeModule, ...args } = parseArgs(argv);
+	const { nativeModules = [], ...args } = parseArgs(argv);
 	// The caller's directory, fixed before any operator code runs and handed to the app explicitly.
 	const cwd = process.cwd();
-	const extensions = nativeModule === undefined ? [] : [await loadNativeModule(nativeModule)];
+	const extensions = await loadNativeModules(nativeModules);
 	// Loaded before anything opens, as upstream main.ts imports it statically: a TUI that cannot
 	// load opens no session, mints no citizen and leaves nothing to clean up.
 	const { runDurableTui } = await loadTui();

package/pi/pi-durable/carrier/runtime.js

@@ -58,8 +58,10 @@ const context = BACKGROUND_CONTEXT;
 	                                                       
 	                                         
 	                                    
-	                                                        
+	                                                                                                  
 	                           
+	                                                                 
+	                             
  
 
                                     
@@ -213,6 +215,7 @@ export async function openDurable(options                     = {})
 			conversations: summaries,
 			models: models(),
 			notices: [],
+			tasksPanel: true,
 		};
 		const listeners = new Set            ();
 		let notifying = false;
@@ -330,17 +333,8 @@ export async function openDurable(options                     = {})
 					const thinking                     = agentOf(state.conversation).thinkingLevel ?? "off";
 					await current.configure({ model: ref, thinkingLevel: clampThinkingLevel(model, thinking) }, context);
 				}),
-			toggleTasks: () =>
-				command(async () => {
-					if (tasks !== undefined) {
-						closeTasks();
-						update({ tasks: undefined });
-						return;
-					}
-					const graph = await opened.taskGraph(context);
-					tasks = graph;
-					unsubscribeTasks = graph.subscribe((value) => update({ tasks: value }));
-				}),
+			// Only the panel: the graph stays observed, so live background work is never out of view.
+			toggleTasks: () => command(async () => update({ tasksPanel: !state.tasksPanel })),
 			switchConversation: (id) =>
 				command(async () => {
 					const next = await opened.conversation(id, context);
@@ -360,8 +354,11 @@ export async function openDurable(options                     = {})
 			notice("warning", `Saved model is unavailable: ${saved.provider}/${saved.modelId}`);
 		}
 		if (initial?.fallbackMessage !== undefined) notice("info", initial.fallbackMessage);
-		// The task panel starts open; /tasks hides it.
-		await controller.toggleTasks();
+		// The task graph is observed until close; its panel starts open and /tasks hides it.
+		const graph = await opened.taskGraph(context);
+		tasks = graph;
+		update({ tasks: graph.value });
+		unsubscribeTasks = graph.subscribe((value) => update({ tasks: value }));
 		// Recovered work from an interrupted turn continues now.
 		harness.resume();
 

package/pi/pi-durable/carrier/tui.js

@@ -23,12 +23,14 @@ import {
 	SelectList,
 	                     
 	Spacer,
+	                
 	setCapabilityOverrides,
 	setKeybindings,
 	Text,
 	TruncatedText,
 	TuiAltScreen,
 	VStack,
+	visibleWidth,
 } from "@earendil-works/pi-tui";
 import { getAgentDir } from "entwurf-pi-dist:config.js";
 import { KeybindingsManager } from "entwurf-pi-dist:core/keybindings.js";
@@ -150,10 +152,75 @@ class CompactionComponent extends Box {
 	                      
  
 
+/**
+ * The live background-task badge: the dock's first row, never shrunk, so live background work stays on
+ * screen however small the terminal gets. It counts the graph's background tasks whatever their kind and
+ * names the ones that are not running; with none it renders nothing and the dock is upstream's.
+ */
+export class TaskBadge                      {
+	#count = 0;
+	#detail = "";
+
+	get count()         {
+		return this.#count;
+	}
+
+	set(graph                       )       {
+		const nodes = Object.values(graph?.tasks ?? {}).filter((node) => node.background);
+		const tally = (state        , match                                  )           => {
+			const n = nodes.filter(match).length;
+			return n === 0 ? [] : [`${n} ${state}`];
+		};
+		this.#count = nodes.length;
+		this.#detail = [
+			...tally("aborting", (node) => node.abortRequested),
+			...tally("completing", (node) => !node.abortRequested && node.state.status === "completing"),
+			...tally("waiting", (node) => !node.abortRequested && node.state.status === "waiting"),
+			...tally("pending", (node) => !node.abortRequested && node.state.status === "pending"),
+		].join(", ");
+	}
+
+	/** The widest form that fits, padded when there is room; narrower terminals drop detail, then words. */
+	render(width        )           {
+		const n = this.#count;
+		if (n === 0) return [];
+		const tasks = `⏳ ${n} ${n === 1 ? "task" : "tasks"}`;
+		const detailed = this.#detail ? [`${tasks} (${this.#detail})`] : [];
+		const forms = [...detailed, tasks, `⏳ ${n}`, `⏳${n}`, `*${n}`, "*+", "*"];
+		for (const form of forms) {
+			if (visibleWidth(form) < width) return [theme.fg("accent", ` ${form}`)];
+			if (visibleWidth(form) === width) return [theme.fg("accent", form)];
+		}
+		return [theme.fg("accent", "*")];
+	}
+
+	invalidate()       {}
+}
+
+/**
+ * The screen: the transcript above the dock. The badge is the dock's first row and never shrinks, so the
+ * renderer, which clips from the bottom, drops the editor and the footer before it; a one-row terminal
+ * with live background work shows the badge instead of the transcript.
+ */
+export function durableLayout(transcript           , badge           , dock                       )         {
+	return new VStack([
+		{
+			component: transcript,
+			basis: 0,
+			grow: 1,
+			shrink: 1,
+			minSize: 1,
+			visible: (viewport) => badge.count === 0 || viewport.height > 1,
+		},
+		{ component: new VStack([{ component: badge, shrink: 0 }, ...dock]), basis: "auto", grow: 0, shrink: 1, minSize: 1 },
+	]);
+}
+
 class DurableTui {
 	static          #renderers                                = createAllToolRenderers();
 	         #ui              ;
 	         #chat = new Container();
+	         #taskBadge = new TaskBadge();
 	         #tasks = new Container();
 	         #queue = new Container();
 	         #notices = new Container();
@@ -216,15 +283,9 @@ class DurableTui {
 		content.addChild(new Spacer(1));
 		const transcript = new ScrollView(content, { follow: "end", primary: true, overscroll: "chain" });
 		this.#transcript = transcript;
-		const dock = new VStack([
-			{ component: this.#tasks, shrink: 1, minSize: 0 },
-			{ component: this.#queue, shrink: 1, minSize: 0 },
-			{ component: this.#notices, shrink: 1, minSize: 0 },
-			{ component: this.#editorContainer, shrink: 1, minSize: 3 },
-			{ component: this.#footer, shrink: 1, minSize: 0 },
-		]);
 		for (const component of [
 			this.#chat,
+			this.#taskBadge,
 			this.#tasks,
 			this.#queue,
 			this.#notices,
@@ -234,9 +295,12 @@ class DurableTui {
 			this.#ui.addChild(component);
 		}
 		this.#ui.setLayoutRoot(
-			new VStack([
-				{ component: transcript, basis: 0, grow: 1, shrink: 1, minSize: 1 },
-				{ component: dock, basis: "auto", grow: 0, shrink: 1, minSize: 1 },
+			durableLayout(transcript, this.#taskBadge, [
+				{ component: this.#tasks, shrink: 1, minSize: 0 },
+				{ component: this.#queue, shrink: 1, minSize: 0 },
+				{ component: this.#notices, shrink: 1, minSize: 0 },
+				{ component: this.#editorContainer, shrink: 1, minSize: 3 },
+				{ component: this.#footer, shrink: 1, minSize: 0 },
 			]),
 		);
 		this.#ui.setFocus(this.#editor);
@@ -299,7 +363,8 @@ class DurableTui {
 				);
 			}
 		}
-		this.#syncTasks(view.tasks);
+		this.#taskBadge.set(view.tasks);
+		this.#syncTasks(view.tasksPanel ? view.tasks : undefined);
 		this.#syncQueue((view.conversation.docs["pi.inbox"] ?? { items: [] })              );
 		this.#syncNotices(view);
 		this.#editor.borderColor = theme.getThinkingBorderColor(agentOf(view.conversation).thinkingLevel ?? "off");