@camstack/addon-terminal 0.1.12 → 0.1.15

package/dist/addon.mjs

@@ -1,6 +1,8 @@
 import { createRequire } from "node:module";
+import { execFile } from "node:child_process";
 import { accessSync, chmodSync, constants, existsSync, statSync } from "node:fs";
-import { delimiter, dirname, join } from "node:path";
+import path, { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import sharp from "sharp";
 import { createServer } from "node:http";
 //#region \0rolldown/runtime.js
@@ -18406,24 +18408,28 @@ var snapshotCapability = {
 		*
 		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
 		* the wrapper happens to hold and never captures. Under D93 the client
-		* versions its image URL on that answer, and an image REQUEST is what enrols
-		* a camera in the keep-warm loop. Both of those are satisfiable by the
-		* client's own image cache — `expo-image` is URL-keyed and never revalidates
-		* — so a URL painted in a previous session comes off disk with no network,
-		* no enrolment, and nothing warming. Measured on the live hub: reopening
-		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
-		* HTTP requests, and the fleet only recovered because a later poll happened
-		* to observe a different identity.
+		* versions its image URL on that answer, and an image REQUEST was the only
+		* demand signal. Both of those are satisfiable by the client's own image
+		* cache — `expo-image` is URL-keyed and never revalidates — so a URL painted
+		* in a previous session comes off disk with no network, no demand, and no
+		* capture. Measured on the live hub: reopening after two minutes idle
+		* painted 15 of 16 tiles at **168 s old** with zero HTTP requests, and the
+		* fleet only recovered because a later poll happened to observe a different
+		* identity.
 		*
 		* ## The two properties that fix it
 		*
 		* **It is an RPC, so no client cache can answer it.** The demand signal
-		* always reaches the wrapper. This method therefore MAY create keep-warm
-		* subscriptions, where `getSnapshotOverview` must never (D93) — the
-		* distinction is not "one is newer" but that the overview poll is app-wide
-		* (a creating overview would warm every camera on the install) while this is
-		* called by a rendered surface naming the tiles it is actually painting, at
-		* the width it is painting them.
+		* always reaches the wrapper. This method therefore CAPTURES, where
+		* `getSnapshotOverview` must never (D93) — the distinction is not "one is
+		* newer" but that the overview poll is app-wide (a capturing overview would
+		* dial every camera on the install) while this is called by a rendered
+		* surface naming the tiles it is actually painting, at the width it is
+		* painting them.
+		*
+		* Since 2026-08-11 this is the ONLY thing that refreshes a snapshot: the
+		* server-side keep-warm loop was removed (operator directive — on-demand,
+		* always), so a camera nobody is looking at costs nothing at all.
 		*
 		* **It waits, briefly and boundedly, for the capture it triggered.** The
 		* returned `capturedAt` is the frame the link will serve, not the frame the
@@ -27392,9 +27398,10 @@ var DeclaredDevices = class {
 		}
 		const integrationId = spec.integrationId ?? await this.ensureIntegration(spec.integrationName);
 		const index = await this.readIndex();
+		const live = await this.readLiveByStableId();
 		const outcomes = [];
 		for (const declaration of spec.devices) {
-			const outcome = await this.applyDeclaration(declaration, integrationId, index);
+			const outcome = await this.applyDeclaration(declaration, integrationId, index, live);
 			if (outcome !== null) outcomes.push(outcome);
 		}
 		return {
@@ -27440,6 +27447,26 @@ var DeclaredDevices = class {
 		return new Map(rows.map((row) => [row.stableId, row]));
 	}
 	/**
+	* Devices this kernel already has CONSTRUCTED, by stableId.
+	*
+	* Distinct from {@link readIndex}, and the distinction is the bug: the index
+	* is persisted rows, this is live objects. A row without an object must be
+	* adopted; an object must be left exactly as it is.
+	*
+	* Failure is non-fatal and deliberately so — an empty map degrades to the
+	* previous behaviour (attempt the adopt) rather than skipping a device that
+	* genuinely needs bringing up.
+	*/
+	async readLiveByStableId() {
+		try {
+			const devices = await this.ports.devices.getAll();
+			return new Map(devices.map((device) => [device.stableId, device]));
+		} catch (err) {
+			this.ports.logger.warn("could not read live devices — falling back to adopt-by-row", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	/**
 	* One declaration: adopt what exists, create what does not.
 	*
 	* The create branch is the destructive one — it seeds `initialMeta`, and
@@ -27448,8 +27475,15 @@ var DeclaredDevices = class {
 	* the declared name over the operator's rename. D49: that branch needs a
 	* second read to agree.
 	*/
-	async applyDeclaration(declaration, integrationId, index) {
+	async applyDeclaration(declaration, integrationId, index, live) {
 		try {
+			const alreadyLive = live.get(declaration.stableId);
+			if (alreadyLive !== void 0) return {
+				stableId: declaration.stableId,
+				deviceId: alreadyLive.id,
+				device: alreadyLive,
+				created: false
+			};
 			let existing = index.get(declaration.stableId);
 			if (existing === void 0) {
 				existing = (await this.readIndex()).get(declaration.stableId);
@@ -33323,6 +33357,46 @@ DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 //#endregion
+//#region src/curses-shim.ts
+/**
+* macOS repair for the managed Python's curses.
+*
+* The python-build-standalone distribution the dependency resolver installs on
+* macOS links ncurses statically with the terminfo database compiled OUT
+* (`--disable-database`) and an ABI mismatch that misparses every numeric
+* capability of its five built-in fallback terminals (`colors=-1`,
+* `cols=524368`). `has_colors()` is therefore False under every TERM value and
+* `init_pair` is hard-blocked, so glances takes its B&W branch and paints the
+* whole screen with SGR conceal/reverse/alt-charset — the "text missing,
+* light bars instead" terminal camera frames. No environment variable can fix
+* it: the code that would read TERMINFO/TERMINFO_DIRS was never compiled in.
+*
+* The repair ships prebuilt `_curses` / `_curses_panel` extension modules
+* linked against the system `/usr/lib/libncurses.5.4.dylib` (universal2) and
+* puts their directory on PYTHONPATH at PTY spawn — PYTHONPATH precedes
+* lib-dynload on sys.path, so the working modules shadow the broken ones with
+* no change to the managed distribution. The filename is ABI-locked to
+* cpython-312: a managed-python bump to 3.13 makes the shim silently inert
+* (python ignores a mismatched ABI tag), which is why the addon probes
+* `tigetnum("colors")` at startup and logs loudly when colours are missing.
+*/
+/** `<addonRoot>/assets/curses-shim/py312`, valid from both src/ and dist/. */
+function cursesShimDir() {
+	return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "assets", "curses-shim", "py312");
+}
+function cursesShimDirExists(shimDir) {
+	return existsSync(shimDir);
+}
+/**
+* The env to merge into the glances profile, or undefined when the shim does
+* not apply (non-macOS, or the assets were not shipped).
+*/
+function resolveGlancesCursesShimEnv(options) {
+	if (options.platform !== "darwin" || !options.shimDirExists) return void 0;
+	const existing = options.existingPythonPath?.trim();
+	return { PYTHONPATH: existing ? `${options.shimDir}:${existing}` : options.shimDir };
+}
+//#endregion
 //#region src/pty.ts
 /**
 * Minimal pty abstraction. The manager depends on this interface, never on
@@ -33453,14 +33527,253 @@ function buildTerminalInstanceCameraDeclarations(instances) {
 function needsTerminalCameraConfigMigration(persistedConfig, declaration) {
 	return persistedConfig.instanceId !== declaration.config.instanceId || persistedConfig.nodeId !== declaration.config.nodeId || persistedConfig.profileId !== declaration.config.profileId || persistedConfig.profileLabel !== declaration.config.profileLabel;
 }
+//#endregion
+//#region src/terminal-cell-runs.ts
+var TERMINAL_DEFAULT_FG = "#d7dce2";
+var TERMINAL_DEFAULT_BG = "#0b0d10";
+/**
+* The 16 ANSI colours, in a dark-theme variant chosen to sit with the existing
+* frame (`#0b0d10` ground, `#d7dce2` text) rather than the raw xterm defaults,
+* whose pure `#0000ff` blue and `#008000` green are close to unreadable on a
+* near-black background at 13px. Index 7 IS the default foreground, so plain
+* `CSI 37m` text renders identically to unstyled text.
+*/
+var TERMINAL_ANSI_PALETTE = [
+	"#282c34",
+	"#e06c75",
+	"#98c379",
+	"#e5c07b",
+	"#61afef",
+	"#c678dd",
+	"#56b6c2",
+	TERMINAL_DEFAULT_FG,
+	"#5c6370",
+	"#ef596f",
+	"#89ca78",
+	"#f0c674",
+	"#6cb6ff",
+	"#d55fde",
+	"#2bbac5",
+	"#ffffff"
+];
+/** The six levels of the xterm 6×6×6 colour cube (indices 16-231). */
+var TERMINAL_CUBE_LEVELS = [
+	0,
+	95,
+	135,
+	175,
+	215,
+	255
+];
+var TERMINAL_CUBE_FIRST = 16;
+var TERMINAL_GRAYSCALE_FIRST = 232;
+var TERMINAL_GRAYSCALE_BASE = 8;
+var TERMINAL_GRAYSCALE_STEP = 10;
+/** SGR 2 keeps the foreground legible; it must not become the background. */
+var TERMINAL_DIM_WEIGHT = .6;
+function channel(value) {
+	return Math.max(0, Math.min(255, Math.round(value))).toString(16).padStart(2, "0");
+}
+function hex(red, green, blue) {
+	return `#${channel(red)}${channel(green)}${channel(blue)}`;
+}
+function parseHex(color) {
+	return [
+		Number.parseInt(color.slice(1, 3), 16),
+		Number.parseInt(color.slice(3, 5), 16),
+		Number.parseInt(color.slice(5, 7), 16)
+	];
+}
+/** Resolve an xterm palette index (0-255) to a hex colour. */
+function terminalPaletteColor(index) {
+	const ansi = TERMINAL_ANSI_PALETTE[index];
+	if (ansi !== void 0) return ansi;
+	if (index >= TERMINAL_GRAYSCALE_FIRST) {
+		const level = TERMINAL_GRAYSCALE_BASE + (index - TERMINAL_GRAYSCALE_FIRST) * TERMINAL_GRAYSCALE_STEP;
+		return hex(level, level, level);
+	}
+	if (index >= TERMINAL_CUBE_FIRST) {
+		const offset = index - TERMINAL_CUBE_FIRST;
+		return hex(TERMINAL_CUBE_LEVELS[Math.floor(offset / 36) % 6] ?? 0, TERMINAL_CUBE_LEVELS[Math.floor(offset / 6) % 6] ?? 0, TERMINAL_CUBE_LEVELS[offset % 6] ?? 0);
+	}
+	return TERMINAL_DEFAULT_FG;
+}
+/** Resolve a 0xRRGGBB truecolor value to a hex colour. */
+function terminalRgbColor(value) {
+	return hex(value >> 16 & 255, value >> 8 & 255, value & 255);
+}
+function blend(color, toward, weight) {
+	const [red, green, blue] = parseHex(color);
+	const [targetRed, targetGreen, targetBlue] = parseHex(toward);
+	return hex(red * weight + targetRed * (1 - weight), green * weight + targetGreen * (1 - weight), blue * weight + targetBlue * (1 - weight));
+}
+function resolveForeground(cell) {
+	if (cell.isFgRGB()) return terminalRgbColor(cell.getFgColor());
+	if (cell.isFgPalette()) return terminalPaletteColor(cell.getFgColor());
+	return TERMINAL_DEFAULT_FG;
+}
+function resolveBackground(cell) {
+	if (cell.isBgRGB()) return terminalRgbColor(cell.getBgColor());
+	if (cell.isBgPalette()) return terminalPaletteColor(cell.getBgColor());
+	return TERMINAL_DEFAULT_BG;
+}
+/**
+* Resolve one cell's attributes into concrete colours.
+*
+* Inverse is applied by SWAPPING the already-resolved pair, so inverse over two
+* defaults is still a visible swap rather than a no-op — that is how a selected
+* or highlighted row in Glances reads. Invisible is then conceal-by-equality
+* (foreground painted in its own background): the cell keeps its columns, which
+* a dropped cell would not, and dropping it would shift the whole rest of the
+* row left.
+*/
+function resolveCellStyle(cell) {
+	const inverse = cell.isInverse() !== 0;
+	const plainFg = resolveForeground(cell);
+	const plainBg = resolveBackground(cell);
+	const background = inverse ? plainFg : plainBg;
+	let foreground = inverse ? plainBg : plainFg;
+	if (cell.isDim() !== 0) foreground = blend(foreground, background, TERMINAL_DIM_WEIGHT);
+	if (cell.isInvisible() !== 0) foreground = background;
+	return {
+		fg: foreground === "#d7dce2" ? null : foreground,
+		bg: background === "#0b0d10" ? null : background,
+		bold: cell.isBold() !== 0
+	};
+}
+function sameStyle(left, right) {
+	return left.fg === right.fg && left.bg === right.bg && left.bold === right.bold;
+}
+/**
+* Merge adjacent same-style cells into runs, then drop the trailing run of
+* default-styled whitespace so a row costs what it draws — the same trim
+* `translateToString(true)` performs. Whitespace carrying a BACKGROUND is kept:
+* a green bar of spaces out to the right margin is a pixel Glances drew.
+*/
+function buildCellRuns(cells) {
+	const runs = [];
+	let text = "";
+	let style = null;
+	for (const cell of cells) {
+		if (style !== null && sameStyle(style, cell.style)) {
+			text += cell.text;
+			continue;
+		}
+		if (style !== null) runs.push({
+			text,
+			...style
+		});
+		text = cell.text;
+		style = cell.style;
+	}
+	if (style !== null) runs.push({
+		text,
+		...style
+	});
+	while (runs.length > 0) {
+		const last = runs[runs.length - 1];
+		if (last === void 0 || last.bg !== null) break;
+		const trimmed = last.text.replace(/\s+$/u, "");
+		if (trimmed === last.text) break;
+		if (trimmed === "") {
+			runs.pop();
+			continue;
+		}
+		runs[runs.length - 1] = {
+			...last,
+			text: trimmed
+		};
+		break;
+	}
+	return runs;
+}
+/**
+* Monospace families to try, in order — NOT one family and a generic.
+*
+* A terminal screen is mostly box-drawing and block characters, and a font
+* without them renders the frame as noise rather than as missing detail.
+* `DejaVu Sans Mono` covers them and ships in the hub image; macOS has neither
+* DejaVu nor fontconfig, so the Mac agent fell through to a generic whose
+* coverage is not, and its Glances camera came out unreadable while the hub's
+* was pixel-perfect (measured 2026-08-11, same Glances, two nodes).
+*
+* `Menlo` is the fix rather than a guess: it is macOS's default terminal face,
+* present on every install, and derived from DejaVu Sans Mono — the same glyph
+* coverage by ancestry. Monaco and Courier New follow as older fallbacks; the
+* generic stays last so a host with none of them still draws something.
+*/
+var TERMINAL_FONT_STACK = "DejaVu Sans Mono,Menlo,Monaco,Courier New,monospace";
+var TERMINAL_FONT_SIZE = 13;
+var TERMINAL_TEXT_MARGIN_X = 8;
+var TERMINAL_ROW_HEIGHT = 15;
+var TERMINAL_BASELINE_Y = 18;
+/**
+* Distance from a row's baseline up to the top of its cell box. Chosen so
+* consecutive rows tile exactly: row N's box runs from `baseline - this` for
+* `TERMINAL_ROW_HEIGHT`, and row N+1's box starts where it ends. A background
+* bar that stopped short would draw as stripes across a `CSI 42m` panel.
+*/
+var TERMINAL_CELL_ASCENT = 11.5;
+var TERMINAL_CELL_WIDTH = TERMINAL_FONT_SIZE * (1233 / 2048);
+/** Two decimals is under a tenth of a pixel and keeps the SVG small. */
+function coordinate(value) {
+	return String(Number(value.toFixed(2)));
+}
 function escapeXml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 }
-/** Render already-interpreted terminal rows into a compact MJPEG frame. */
-async function renderTerminalJpeg(lines) {
-	const renderedLines = lines.slice(0, 40).map((line, index) => `<text x="8" y="${String(18 + index * 15)}">${escapeXml(line.slice(0, 120))}</text>`).join("");
-	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${String(960)}" height="${String(640)}"><rect width="100%" height="100%" fill="#0b0d10"/><g fill="#d7dce2" font-family="DejaVu Sans Mono,monospace" font-size="13">${renderedLines}</g></svg>`;
-	return sharp(Buffer.from(svg)).jpeg({
+/**
+* Render already-interpreted terminal rows into a compact MJPEG frame.
+*
+* `xml:space="preserve"` is load-bearing, not tidiness. SVG `<text>` collapses
+* runs of whitespace by default, and a terminal's entire column alignment IS
+* runs of whitespace — Glances pads every field with spaces. Without it the
+* frame drew each line at roughly half its true width, crammed into the
+* top-left of a mostly-black image, while the SAME session over `attach`
+* looked perfect — which is exactly how the operator reported it. Measured in
+* the hub's own rasterizer 2026-08-11: `AAA<10 spaces>BBB<3>CCC` drew 92 px
+* collapsed against 178 px preserved.
+*
+* Every run is anchored at its OWN column (`x = margin + startCol * cellW`),
+* never appended to the one before it, so the background rects and the glyphs
+* are placed off the same grid and cannot drift apart. `textLength` is emitted
+* with it because it is the correct declaration and renderers that honour it
+* get an exact grid — but it is not what makes this work: librsvg, which sharp
+* uses, ignores it outright (measured 2026-08-12, a 120-glyph run pinned to
+* 600 px still drew its natural 937 px). The anchoring is the guarantee.
+*/
+function renderTerminalSvg(rows) {
+	const backgrounds = [];
+	const texts = [];
+	rows.slice(0, 40).forEach((row, index) => {
+		const baseline = TERMINAL_BASELINE_Y + index * TERMINAL_ROW_HEIGHT;
+		const top = baseline - TERMINAL_CELL_ASCENT;
+		let column = 0;
+		for (const run of row) {
+			if (column >= 120) break;
+			const clipped = clipRun(run, 120 - column);
+			const columns = [...clipped].length;
+			if (columns === 0) continue;
+			const x = TERMINAL_TEXT_MARGIN_X + column * TERMINAL_CELL_WIDTH;
+			const width = columns * TERMINAL_CELL_WIDTH;
+			if (run.bg !== null) backgrounds.push(`<rect x="${coordinate(x)}" y="${coordinate(top)}" width="${coordinate(width)}" height="${String(TERMINAL_ROW_HEIGHT)}" fill="${run.bg}"/>`);
+			if (clipped.trim() !== "") {
+				const fill = run.fg === null ? "" : ` fill="${run.fg}"`;
+				const weight = run.bold ? " font-weight=\"bold\"" : "";
+				texts.push(`<text xml:space="preserve" x="${coordinate(x)}" y="${coordinate(baseline)}" textLength="${coordinate(width)}" lengthAdjust="spacingAndGlyphs"${fill}${weight}>${escapeXml(clipped)}</text>`);
+			}
+			column += columns;
+		}
+	});
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="${String(960)}" height="${String(640)}"><rect width="100%" height="100%" fill="${TERMINAL_DEFAULT_BG}"/>${backgrounds.join("")}<g fill="${TERMINAL_DEFAULT_FG}" font-family="${TERMINAL_FONT_STACK}" font-size="${String(TERMINAL_FONT_SIZE)}">${texts.join("")}</g></svg>`;
+}
+/** Cut a run to the columns still left in the row, by code point not unit. */
+function clipRun(run, remaining) {
+	const points = [...run.text];
+	return points.length <= remaining ? run.text : points.slice(0, remaining).join("");
+}
+async function renderTerminalJpeg(rows) {
+	return sharp(Buffer.from(renderTerminalSvg(rows))).jpeg({
 		quality: 82,
 		chromaSubsampling: "4:2:0"
 	}).toBuffer();
@@ -38366,6 +38679,40 @@ function createXtermScreen(cols, rows) {
 			for (let row = 0; row < term.rows; row += 1) lines.push(buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? "");
 			return lines;
 		},
+		/**
+		* The colour-bearing read. `translateToString` — the only cell read this
+		* screen used to offer — keeps characters and discards every attribute,
+		* which is why the terminal camera rendered a fully-coloured Glances in
+		* grey. Walking cells is the only way to get the attributes back.
+		*
+		* A zero-width cell is the tail half of a wide glyph (CJK, some emoji);
+		* its characters already came back with the leading cell, so skipping it
+		* keeps the text right. `getNullCell()` is reused across the whole screen
+		* because `getCell` allocates otherwise — 4800 objects per frame.
+		*/
+		styledLines: () => {
+			const buffer = term.buffer.active;
+			const scratch = buffer.getNullCell();
+			const styled = [];
+			for (let row = 0; row < term.rows; row += 1) {
+				const line = buffer.getLine(buffer.viewportY + row);
+				if (!line) {
+					styled.push([]);
+					continue;
+				}
+				const cells = [];
+				for (let column = 0; column < line.length; column += 1) {
+					const cell = line.getCell(column, scratch);
+					if (!cell || cell.getWidth() === 0) continue;
+					cells.push({
+						text: cell.getChars() || " ",
+						style: resolveCellStyle(cell)
+					});
+				}
+				styled.push(buildCellRuns(cells));
+			}
+			return styled;
+		},
 		dispose: () => {
 			term.dispose();
 		}
@@ -38376,6 +38723,9 @@ function createXtermScreen(cols, rows) {
 var MJPEG_BOUNDARY = "camstack-terminal-frame";
 var SESSION_IDLE_MS = 3e4;
 var SNAPSHOT_STARTUP_WAIT_MS = 1500;
+var SNAPSHOT_SETTLE_QUIET_MS = 300;
+var SNAPSHOT_SETTLE_BUDGET_MS = 3e3;
+var SNAPSHOT_SETTLE_MAX_PULLS = 20;
 var CLOSE_RETRY_BASE_MS = 50;
 var CLOSE_RETRY_MAX_MS = 1e3;
 var CLOSE_ATTEMPTS_PER_PASS = 3;
@@ -38500,20 +38850,36 @@ var TerminalCameraRelay = class {
 			if (state.openPromise === opening) state.openPromise = null;
 		}
 	}
+	/** Replay one output batch into the relay screen; true = the session exited. */
+	applyBatch(state, batch) {
+		if (batch.reset) {
+			state.screen.dispose();
+			state.screen = createXtermScreen(120, 40);
+			if (batch.snapshot) state.screen.write(batch.snapshot);
+		}
+		let exited = false;
+		for (const event of batch.events) if (event.kind === "data") state.screen.write(event.data);
+		else {
+			state.sessionId = null;
+			exited = true;
+		}
+		state.cursor = exited ? 0 : batch.cursor;
+		return exited;
+	}
 	async nextFrame(state, forceRender = false, waitForInitialOutput = false) {
 		if (state.framePromise) {
 			await state.framePromise;
 			return forceRender ? this.nextFrame(state, true, waitForInitialOutput) : state.jpeg ?? this.nextFrame(state, false, waitForInitialOutput);
 		}
 		const render = async () => {
-			const openingSession = state.sessionId === null;
+			const initialPull = state.sessionId === null && waitForInitialOutput;
 			const sessionId = await this.ensureSession(state);
 			let batch;
 			try {
 				batch = await this.api.pullOutput(state.nodeId, {
 					sessionId,
 					afterSeq: state.cursor,
-					...openingSession && waitForInitialOutput ? {
+					...initialPull ? {
 						waitMs: SNAPSHOT_STARTUP_WAIT_MS,
 						waitForOutput: true
 					} : {}
@@ -38535,21 +38901,29 @@ var TerminalCameraRelay = class {
 				state.cursor = 0;
 				throw error;
 			}
-			if (batch.reset) {
-				state.screen.dispose();
-				state.screen = createXtermScreen(120, 40);
-				if (batch.snapshot) state.screen.write(batch.snapshot);
-			}
-			let exited = false;
-			for (const event of batch.events) if (event.kind === "data") state.screen.write(event.data);
-			else {
-				state.sessionId = null;
-				exited = true;
+			let exited = this.applyBatch(state, batch);
+			if (initialPull && !exited) {
+				const deadline = Date.now() + SNAPSHOT_SETTLE_BUDGET_MS;
+				for (let pulls = 0; pulls < SNAPSHOT_SETTLE_MAX_PULLS && Date.now() < deadline; pulls += 1) {
+					let settle;
+					try {
+						settle = await this.api.pullOutput(state.nodeId, {
+							sessionId,
+							afterSeq: state.cursor,
+							waitMs: SNAPSHOT_SETTLE_QUIET_MS,
+							waitForOutput: true
+						});
+					} catch {
+						break;
+					}
+					const active = settle.reset || settle.events.some((event) => event.kind === "data");
+					exited = this.applyBatch(state, settle);
+					if (exited || !active) break;
+				}
 			}
-			state.cursor = exited ? 0 : batch.cursor;
 			await state.screen.flush();
 			if (forceRender || state.jpeg === null || state.renderedCursor !== state.cursor) {
-				state.jpeg = await renderTerminalJpeg(state.screen.lines());
+				state.jpeg = await renderTerminalJpeg(state.screen.styledLines());
 				state.renderedCursor = state.cursor;
 			}
 			return state.jpeg;
@@ -38998,7 +39372,8 @@ function buildProfiles(options) {
 				"-m",
 				"glances",
 				...options.glancesArgs ?? []
-			]
+			],
+			...options.glancesEnv && Object.keys(options.glancesEnv).length > 0 ? { env: options.glancesEnv } : {}
 		});
 	}
 	if (options.allowShell) profiles.push({
@@ -39083,6 +39458,7 @@ var TerminalSessionManager = class {
 			glancesPath: opts.glancesPath,
 			glancesArgs: opts.glancesArgs,
 			glancesPythonPath: opts.glancesPythonPath,
+			glancesEnv: opts.glancesEnv,
 			allowShell: opts.allowShell,
 			shellPath: opts.shellPath,
 			customProfiles: opts.customProfiles,
@@ -39380,6 +39756,18 @@ var TerminalSessionManager = class {
 };
 //#endregion
 //#region src/addon.ts
+/**
+* Terminal addon — hosts interactive pty sessions running an allowlisted
+* profile (`monitor` → `btm`), streamed to the Admin UI over the data plane.
+*
+* Phase 1 of docs/design/2026-07-26-terminal-session-design.md: a real TTY good
+* enough to run a full-screen program. Phase 2 (streaming a session as a camera)
+* is a separate device-provider concern and does not change this addon's cap.
+*
+* Its own package (not a builtin) because it carries a native dependency
+* (`node-pty`) and should update via `camstack deploy` independently of the
+* framework, exactly like the node-av decoder addon.
+*/
 var DEFAULTS = {
 	btmPath: "",
 	btmEnabled: true,
@@ -39412,12 +39800,21 @@ var TerminalAddon = class extends BaseAddon {
 	instanceMutationQueue = new TerminalInstanceMutationQueue();
 	terminalReconcileCoordinator = new TerminalInstanceReconcileCoordinator(this.instanceMutationQueue);
 	glancesPythonPath = "";
+	glancesEnv;
 	constructor() {
 		super({ ...DEFAULTS });
 	}
 	async onInitialize() {
 		await warmNodePty();
 		this.glancesPythonPath = await this.ctx.deps.ensurePython() ?? "";
+		const shimDir = cursesShimDir();
+		this.glancesEnv = resolveGlancesCursesShimEnv({
+			platform: process.platform,
+			shimDir,
+			shimDirExists: cursesShimDirExists(shimDir),
+			existingPythonPath: process.env["PYTHONPATH"]
+		});
+		this.probeGlancesCursesColours();
 		const manager = new TerminalSessionManager({
 			spawn: createNodePtySpawner(),
 			screenFactory: createXtermScreen,
@@ -39433,6 +39830,7 @@ var TerminalAddon = class extends BaseAddon {
 			glancesPath: this.config.glancesPath,
 			glancesArgs: this.config.glancesArgs,
 			glancesPythonPath: this.glancesPythonPath,
+			glancesEnv: this.glancesEnv,
 			allowShell: this.config.allowShell,
 			shellPath: this.config.shellPath,
 			maxSessions: this.config.maxSessions,
@@ -39478,6 +39876,39 @@ var TerminalAddon = class extends BaseAddon {
 			provider: manager
 		}];
 	}
+	/**
+	* Fire-and-forget canary: the managed python must see a colour-capable
+	* curses, or glances paints its B&W theme (SGR conceal/reverse) and the
+	* terminal camera frames lose their text. The shim filename is ABI-locked
+	* (cpython-312), so a managed-python bump silently disables it — this probe
+	* is what makes that failure loud instead of a garbled camera.
+	*/
+	probeGlancesCursesColours() {
+		if (!this.glancesPythonPath) return;
+		const probeEnv = {
+			...process.env,
+			...this.glancesEnv,
+			TERM: "xterm-256color"
+		};
+		execFile(this.glancesPythonPath, ["-c", "import curses\ncurses.setupterm('xterm-256color')\nprint(curses.tigetnum('colors'))"], {
+			env: probeEnv,
+			timeout: 1e4
+		}, (error, stdout) => {
+			const colours = error ? NaN : Number.parseInt(stdout.trim(), 10);
+			if (!Number.isFinite(colours) || colours <= 0) {
+				this.ctx.logger.warn("glances curses reports no colours — terminal camera frames will render the B&W theme", { meta: {
+					colours: Number.isFinite(colours) ? colours : null,
+					shimApplied: this.glancesEnv !== void 0,
+					error: error ? error instanceof Error ? error.message : String(error) : void 0
+				} });
+				return;
+			}
+			this.ctx.logger.debug("glances curses colours available", { meta: {
+				colours,
+				shimApplied: this.glancesEnv !== void 0
+			} });
+		});
+	}
 	async onConfigChanged() {
 		this.replaceTerminalCameraTombstones(this.config.terminalCameraTombstones);
 		this.manager?.reconfigureProfiles({
@@ -39491,6 +39922,7 @@ var TerminalAddon = class extends BaseAddon {
 			glancesPath: this.config.glancesPath,
 			glancesArgs: this.config.glancesArgs,
 			glancesPythonPath: this.glancesPythonPath,
+			glancesEnv: this.glancesEnv,
 			allowShell: this.config.allowShell,
 			shellPath: this.config.shellPath,
 			maxSessions: this.config.maxSessions,
@@ -39586,12 +40018,46 @@ var TerminalAddon = class extends BaseAddon {
 					this.migratedTerminalCameraConfigIds.add(outcome.device.id);
 				}
 			}
+			if (outcome.created) await this.silenceAnalysisFor(outcome.device.id);
 			const nodeId = outcome.device.config.get("nodeId");
 			const profileId = outcome.device.config.get("profileId");
 			const profileAvailable = this.cameraProfilesByNode.get(nodeId)?.some((profile) => profile.profileId === profileId) ?? false;
 			outcome.device.setNodeOnline((onlineByNode.get(nodeId) ?? false) && profileAvailable);
 		}
 	}
+	/**
+	* A Terminal camera is a rendered screen. Object detection on it finds
+	* nothing, forever, at full cost.
+	*
+	* Measured on the hub 2026-08-11, for ONE terminal camera: 19 frames per 10 s
+	* through the detection pipeline at ~61 ms of inference each, plus 115
+	* capture-scheduler requests a minute — against `detections=0`. Multiply by
+	* one terminal per node and it is a standing tax on a hub that was already
+	* shedding 86 % of its capture queue.
+	*
+	* Written through `setCameraSwitch`, which is the authority that already owns
+	* this function — [D62] forbids a second store that disagrees with it. And
+	* written ONLY on creation: an operator who deliberately turns detection back
+	* on for a terminal must win, and a reconcile that re-asserted every pass
+	* would silently overrule them once a minute.
+	*/
+	async silenceAnalysisFor(deviceId) {
+		for (const switchId of ["object-detection", "audio-analysis"]) try {
+			await this.ctx.api.pipelineOrchestrator.setCameraSwitch.mutate({
+				deviceId,
+				switchId,
+				enabled: false
+			});
+		} catch (err) {
+			this.ctx.logger.warn("could not switch off analysis for a Terminal camera", {
+				tags: { deviceId },
+				meta: {
+					switchId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+	}
 	terminalInstanceControl() {
 		return {
 			listInstances: async () => this.terminalInstances().map((instance) => this.instanceInfo(instance)),
@@ -39903,4 +40369,4 @@ var TerminalAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { TerminalAddon, createXtermScreen as a, createTerminalDataPlaneHandler as i, buildProfiles as n, createNodePtySpawner as o, findProfile as r, warmNodePty as s, TerminalSessionManager as t };
+export { TerminalAddon, createXtermScreen as a, buildCellRuns as c, terminalRgbColor as d, createNodePtySpawner as f, createTerminalDataPlaneHandler as i, resolveCellStyle as l, buildProfiles as n, TERMINAL_DEFAULT_BG as o, warmNodePty as p, findProfile as r, TERMINAL_DEFAULT_FG as s, TerminalSessionManager as t, terminalPaletteColor as u };