@xmoon76/dsh-pi-tui 0.4.9 → 0.5.1

package/dist/terminal-progress-source-BfiTKDT-.mjs

@@ -0,0 +1,2349 @@
+import { ft as isFooterLayout, pt as parseFooterLayout } from "./extensions-1WYBUQ8I.mjs";
+import { accessSync, constants, readdirSync, statSync } from "node:fs";
+import { delimiter, join, posix, win32 } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+//#region src/runtime/process/errors.ts
+/**
+* Shared, TOTAL error-observation helpers for every async boundary in the
+* TUI: the owned/detached entries (`tasks.ts`), the lifecycle roots
+* (startup, exit, flush), the per-task callbacks and the diagnostics
+* formatter. One implementation, one behavior — no drift between modules.
+*
+* CONTRACT (deliberately scoped, honestly worded): the SYNC boundary is
+* total — observing any legal JavaScript value (a Proxy with a throwing
+* `getPrototypeOf` trap, a throwing `message` getter, a throwing
+* `toString`/`Symbol.toPrimitive`) can never make THIS code throw or
+* reject; every observation is protected and every fallback is a fixed
+* constant that never touches the value again. What is NOT guaranteed: an
+* observer (getter/trap/coercion) that, WHILE being observed, spawns its
+* OWN detached async work (e.g. `void Promise.reject(...)` inside
+* `toString`) — that rejection belongs to the observer, not to this
+* boundary, and no synchronous try/catch can intercept it. Callers must
+* not describe this module as a strict "any legal value, zero side
+* effects" guarantee.
+* @module @xmoon76/dsh-pi-tui/runtime/process/errors
+*/
+/**
+* Describe an arbitrary thrown value as a string WITHOUT ever throwing:
+* `instanceof`, property reads and coercion are all inside the protection,
+* the fallbacks are FIXED constants that never touch the value again, and
+* a hostile Proxy/getter/`Symbol.toPrimitive` yields a stable placeholder
+* instead of escaping. (Best-effort beyond the sync boundary — see the
+* module contract.)
+*/
+function safeErrorMessage(value) {
+	try {
+		if (value instanceof Error) try {
+			const message = value.message;
+			return typeof message === "string" ? message : "<error with non-string message>";
+		} catch {
+			return "<error with unreadable message>";
+		}
+		return String(value);
+	} catch {
+		return "<unprintable error>";
+	}
+}
+/** Describe an arbitrary thrown value using its normal `String` form without
+* allowing hostile coercion to escape the async boundary. */
+function safeErrorString(value) {
+	try {
+		return String(value);
+	} catch {
+		return "<unprintable error>";
+	}
+}
+//#endregion
+//#region src/runtime/process/tasks.ts
+/**
+* Whether an error represents an abort/cancel rather than a real failure.
+* TOTAL over the whole `unknown` domain: every probe (prototype-chain
+* walk, `name`/`code` getters) is inside the protection, and a hostile
+* value that throws while being observed simply classifies as NOT a
+* cancellation — recognizing a cancellation must never mint a new primary
+* error.
+*/
+function isCancellation(error) {
+	try {
+		if (!(error instanceof Error)) return false;
+		return error.name === "AbortError" || error.code === "ABORT_ERR";
+	} catch {
+		return false;
+	}
+}
+/** Build a cancellation-shaped error the classifier recognizes (a plain
+* `new Error('...')` would route through the failure path). */
+function cancellationError(message) {
+	const error = new Error(message);
+	error.name = "AbortError";
+	error.code = "ABORT_ERR";
+	return error;
+}
+/** Read the live session id for diagnostics WITHOUT ever throwing: a
+* throwing `sessionId()` callback degrades to `undefined` (diagnostics
+* must not crash classification or the final sink). */
+function safeSessionId(options) {
+	try {
+		return options.sessionId?.();
+	} catch {
+		return;
+	}
+}
+/**
+* Invoke the task factory SYNCHRONOUSLY (an ownership action inside the
+* factory — a stop, a latch, a spawn — must take effect before the helper
+* returns, so two calls in one input batch cannot both start), and convert
+* a synchronous throw into a rejected promise so it classifies exactly like
+* a rejection.
+*/
+function invokeTask(task) {
+	try {
+		return Promise.resolve(task());
+	} catch (error) {
+		return Promise.reject(error);
+	}
+}
+/**
+* Observe the settlement of an ALREADY-OWNED promise without taking ownership.
+* The callback runs on fulfilment or rejection and its own result is dropped,
+* so bookkeeping (for example removing a promise from a teardown-drained set)
+* never adds a second, unhandled rejection branch next to the real owner's
+* failure handling. Never use this to START work — that is `runDetached` /
+* `runOwned`.
+* @param promise - the promise whose failure semantics already have an owner.
+* @param onSettled - runs once, on either settlement.
+*/
+function observeSettled(promise, onSettled) {
+	promise.then(onSettled, onSettled);
+}
+/**
+* Attach rejection handling to a fire-and-forget task. The factory is
+* invoked synchronously (a synchronous throw is a rejection like any
+* other); every rejection is caught and classified:
+* - cancellation → debug diagnostics only (never a user error);
+* - recoverable (per the options hook) → notify + warn;
+* - anything else → warn.
+* The log line carries the task label and the live session id — never the
+* task payload (no API keys, prompt bodies, or shell output). A throwing
+* notify/diag/sessionId path cannot escape: it lands in the handler-failure
+* sink, which is itself total over the `unknown` domain.
+*/
+function runDetached(label, task, options) {
+	invokeTask(task).catch((error) => {
+		if (isCancellation(error)) {
+			options.diag.debug(label, {
+				session: safeSessionId(options),
+				cancelled: true
+			});
+			return;
+		}
+		const message = safeErrorMessage(error);
+		options.diag.warn(label, {
+			session: safeSessionId(options),
+			error: message
+		});
+		if (options.recoverable?.(error) === true) options.notify?.(`${label}: ${message}`);
+	}).catch(handlerFailure(label, options));
+}
+/**
+* The owned-workflow counterpart of {@link runDetached}: a fire-and-forget
+* task whose RESULT drives user-visible state (a settled card, a restored
+* draft, a queue mutation, a notification). The factory starts
+* SYNCHRONOUSLY; the TASK phase (factory throw / task rejection) classifies
+* with the error shape plus the task-local predicate; the onResult phase is
+* classified as a PRIMARY failure — ERROR + onError, never a cancellation,
+* regardless of error shape or task-local state; a terminal side-effect
+* handler's (onCancel/onError/classifier) own sync/async throw is wrapped
+* in a {@link HandlerFailure} and lands in the `${label} handler failed`
+* sink exactly once, without mutating the thrown value. Never a bare
+* `void somePromise()`: every owned flow goes through this entry
+* (AGENTS.md).
+*/
+function runOwned(label, task, options) {
+	invokeTask(task).then((result) => options.onResult?.(result), (error) => {
+		return classify(label, options, error, true);
+	}).catch((error) => {
+		if (isHandlerFailure(error)) throw error;
+		return classify(label, options, error, false);
+	}).catch(handlerFailure(label, options));
+}
+/**
+* Classify one failure and record the classification diagnostics, then run
+* the matching per-task callback. `allowCancellation` gates ALL cancellation
+* classification: the task phase may treat an AbortError or a task-local
+* state as a cancellation; the onResult phase may not (a result-consumer
+* failure is a failure). A terminal side-effect handler's own sync/async
+* failure is wrapped in {@link HandlerFailure} and propagated to the
+* handler-failure sink — never re-classified, never repeated, never
+* escaped. All diagnostics go through the never-throw helpers, so a
+* hostile thrown value or a throwing sessionId/diag can never mint a new
+* primary error.
+*/
+function classify(label, options, error, allowCancellation) {
+	if (allowCancellation && (isCancellation(error) || taskLocalCancellation(options, error))) {
+		options.diag.debug(label, {
+			session: safeSessionId(options),
+			cancelled: true
+		});
+		if (options.onCancel !== void 0) return guardHandler(() => options.onCancel(error));
+		return;
+	}
+	options.diag.error(label, {
+		session: safeSessionId(options),
+		error: safeErrorMessage(error)
+	});
+	if (options.onError !== void 0) return guardHandler(() => options.onError(error));
+}
+/** The task-local predicate (cancellation classification is already gated
+* by the caller). A throwing predicate is wrapped as a handler failure — it
+* never re-routes the original error into the wrong classification and is
+* never itself re-classified. */
+function taskLocalCancellation(options, error) {
+	if (options.isCancellation === void 0) return false;
+	try {
+		return options.isCancellation(error) === true;
+	} catch (classifierError) {
+		throw new HandlerFailure(classifierError);
+	}
+}
+/**
+* Immutable wrapper for a terminal side-effect handler's own failure. The
+* thrown value is NEVER mutated (a primitive, null, or a frozen/non-
+* extensible error must survive intact); the wrapper carries the original
+* cause to the handler-failure sink, and the middle classification catch
+* recognizes it and forwards it unchanged — so `onError`/`onCancel` run
+* exactly once even when they throw.
+*/
+var HandlerFailure = class {
+	cause;
+	constructor(cause) {
+		this.cause = cause;
+		handlerFailures.add(this);
+	}
+};
+/** Identity registry for the internal wrappers: `WeakSet.has` compares by
+* identity and never walks the argument's prototype chain, so a hostile
+* thrown value (a Proxy with a throwing `getPrototypeOf` trap) can be
+* tested safely — `instanceof HandlerFailure` on an untrusted value could
+* itself throw. */
+const handlerFailures = /* @__PURE__ */ new WeakSet();
+/** Whether a value is one of OUR wrapper instances (identity only; total
+* over the whole `unknown` domain). */
+function isHandlerFailure(value) {
+	return typeof value === "object" && value !== null && handlerFailures.has(value);
+}
+/** Run a per-task terminal callback; a sync or async failure is wrapped in
+* {@link HandlerFailure} so the chain forwards it to the handler-failure
+* sink instead of re-classifying it (and never repeats the callback). */
+function guardHandler(invoke) {
+	try {
+		const outcome = invoke();
+		if (outcome !== void 0) return outcome.catch((error) => {
+			throw new HandlerFailure(error);
+		});
+		return;
+	} catch (error) {
+		throw new HandlerFailure(error);
+	}
+}
+/**
+* The final sink of both helpers: a terminal side-effect handler
+* (onResult's own invocation aside — see {@link runOwned}), a task-local
+* classifier, or the diagnostics channel itself threw. The ENTIRE body is
+* protected — wrapper unwrapping, error description, the session read and
+* the diag call all live inside the try, and the fallback is a fixed
+* constant that never touches the hostile value again — so the sink is a
+* total function over the `unknown` domain: it can NEVER reject, and there
+* is no lower sink to leak into.
+*/
+function handlerFailure(label, options) {
+	return (error) => {
+		try {
+			const cause = isHandlerFailure(error) ? error.cause : error;
+			options.diag.error(`${label} handler failed`, {
+				session: safeSessionId(options),
+				error: safeErrorMessage(cause)
+			});
+		} catch {}
+	};
+}
+//#endregion
+//#region src/runtime/session-reader-port.ts
+/** The official context-pressure occupancy numerator shared by both
+* backends: `projectedTokens ?? pressureTokens` over the raw projection
+* value (an absent/foreign-shaped field is not coerced; a projection with
+* neither field reads unmeasured). */
+function contextPressureOccupancy(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const pressure = value;
+	if (typeof pressure.projectedTokens === "number") return pressure.projectedTokens;
+	if (typeof pressure.pressureTokens === "number") return pressure.pressureTokens;
+}
+//#endregion
+//#region src/domain/footer/command-config.ts
+/** The timeout ceiling. */
+const MAX_COMMAND_TIMEOUT_MS = 1e3;
+/** The minimum refresh interval (plan §17.7). */
+const MIN_COMMAND_REFRESH_MS = 1e3;
+//#endregion
+//#region src/domain/footer/command-trust.ts
+/**
+* The footer command TRUST GATE (plan §17.4): a repository/project config
+* must NEVER silently trigger arbitrary shell execution. The command is
+* read ONLY from the settings descriptor's USER layer (the stored
+* document's user section) — never from the merged/resolved value, which
+* a project layer could influence. When the user layer cannot prove the
+* command, command mode is disabled and the native layout applies.
+* @module @xmoon76/dsh-pi-tui/domain/footer/command-trust
+*/
+/** Validate the persisted footerCommand value (bounds per plan §17.3). */
+function parseFooterCommandConfig(input) {
+	if (typeof input !== "object" || input === null) return void 0;
+	const raw = input;
+	if (raw.schemaVersion !== 1) return void 0;
+	if (typeof raw.command !== "string" || raw.command.trim() === "") return void 0;
+	if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(raw.command)) return void 0;
+	const timeoutMs = raw.timeoutMs === void 0 ? 300 : typeof raw.timeoutMs === "number" && Number.isFinite(raw.timeoutMs) ? Math.min(Math.max(1, raw.timeoutMs), MAX_COMMAND_TIMEOUT_MS) : 300;
+	const refreshIntervalMs = raw.refreshIntervalMs === void 0 ? MIN_COMMAND_REFRESH_MS : typeof raw.refreshIntervalMs === "number" && Number.isFinite(raw.refreshIntervalMs) ? Math.max(MIN_COMMAND_REFRESH_MS, raw.refreshIntervalMs) : MIN_COMMAND_REFRESH_MS;
+	const maxRows = raw.maxRows === void 0 ? 1 : typeof raw.maxRows === "number" && Number.isFinite(raw.maxRows) ? Math.min(Math.max(1, Math.floor(raw.maxRows)), 2) : 1;
+	return {
+		command: raw.command,
+		timeoutMs,
+		refreshIntervalMs,
+		maxRows
+	};
+}
+/**
+* Resolve the TRUSTED command config: the footerCommand value must be
+* present in the USER layer of the tui-app settings descriptor. A
+* merged/project-supplied value is refused (undefined = command mode
+* disabled, native fallback, diagnostic warning).
+* @param descriptors - the settings provider's describe() output.
+* @param namespace - the tui-app settings/profile Config namespace value.
+* @returns the validated config, or undefined when untrusted/invalid.
+*/
+function resolveTrustedFooterCommand(descriptors, namespace) {
+	if (descriptors === void 0) return void 0;
+	const descriptor = descriptors.find((entry) => entry.ns === namespace);
+	if (descriptor === void 0) return void 0;
+	const user = descriptor.user;
+	if (typeof user !== "object" || user === null) return void 0;
+	const raw = user.footerCommand;
+	return parseFooterCommandConfig(raw);
+}
+/**
+* Resolve the USER layer's declared footer mode. Command mode must be
+* user-layer-owned as well: a project can flip the MERGED `footer:
+* command`, but the gate never lets a project config silently trigger the
+* user's command — the user layer must declare the command mode too.
+* @returns the user layer's footer value, or undefined when absent.
+*/
+function resolveUserLayerFooterMode(descriptors, namespace) {
+	if (descriptors === void 0) return void 0;
+	const descriptor = descriptors.find((entry) => entry.ns === namespace);
+	if (descriptor === void 0) return void 0;
+	const user = descriptor.user;
+	if (typeof user !== "object" || user === null) return void 0;
+	const mode = user.footer;
+	return typeof mode === "string" ? mode : void 0;
+}
+/**
+* Resolve the USER layer's declared custom layout (PR D activation trust):
+* the layout whose refs MAY authorize custom command items — but only
+* while the USER layer itself declares footer: custom (see
+* resolveUserCommandItemActivationIds). A project can supply a MERGED
+* `footerLayout` for rendering, but it can never activate a dormant USER
+* command — the same principle as the command-mode gate above: the user
+* layer must own the layout that decides what executes.
+* @returns the validated USER-layer layout, or undefined when absent or
+* invalid (an invalid user layout authorizes nothing — fail-safe).
+*/
+function resolveUserLayerFooterLayout(descriptors, namespace) {
+	if (descriptors === void 0) return void 0;
+	const descriptor = descriptors.find((entry) => entry.ns === namespace);
+	if (descriptor === void 0) return void 0;
+	const user = descriptor.user;
+	if (typeof user !== "object" || user === null) return void 0;
+	const layout = user.footerLayout;
+	const parsed = parseFooterLayout(layout);
+	return isFooterLayout(parsed) ? parsed : void 0;
+}
+/**
+* Resolve the USER layer's declared footerFallbackMode (the native mode
+* the user's own command-mode fallback restores).
+*/
+function resolveUserLayerFooterFallbackMode(descriptors, namespace) {
+	if (descriptors === void 0) return void 0;
+	const descriptor = descriptors.find((entry) => entry.ns === namespace);
+	if (descriptor === void 0) return void 0;
+	const user = descriptor.user;
+	if (typeof user !== "object" || user === null) return void 0;
+	const mode = user.footerFallbackMode;
+	return typeof mode === "string" ? mode : void 0;
+}
+/** The shared empty authorization set. */
+const EMPTY_IDS = /* @__PURE__ */ new Set();
+/** Every item id a layout references (the authorization projection). */
+function layoutRefIds(layout) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const row of layout.rows) {
+		for (const ref of row.left) ids.add(ref.id);
+		for (const ref of row.right) ids.add(ref.id);
+	}
+	return ids;
+}
+/**
+* The ids the USER layer AUTHORIZES for custom command item execution
+* (PR D activation trust, mode-gated): the USER custom layout's refs, but
+* ONLY while the USER layer itself declares `footer: custom`. A stale
+* leftover layout under `footer: default/compact` (the /settings switch
+* deliberately keeps the old layout) authorizes NOTHING — a project
+* flipping the MERGED mode to custom can never resurrect a dormant USER
+* command. `footer: command` authorizes nothing while the whole-footer
+* command surface runs (the caller suspends per-item runners); the native
+* fallback case uses resolveUserCommandItemFallbackActivationIds.
+*/
+function resolveUserCommandItemActivationIds(descriptors, namespace) {
+	if (resolveUserLayerFooterMode(descriptors, namespace) !== "custom") return EMPTY_IDS;
+	const layout = resolveUserLayerFooterLayout(descriptors, namespace);
+	return layout === void 0 ? EMPTY_IDS : layoutRefIds(layout);
+}
+/**
+* The ids authorized for the native FALLBACK surface (a merged
+* `footer: command` the USER layer does not own). The FULL semantic is
+* encoded HERE so no caller can forget the outer mode gate:
+*
+*   USER footer === 'command'
+*     && USER footerFallbackMode === 'custom'
+*     && valid USER footerLayout
+*   → the layout's refs
+*   otherwise → empty
+*
+* A USER who never opted into command mode (footer: default/compact)
+* authorizes NOTHING even with stale fallback metadata; a PROJECT
+* forcing the merged command mode can never turn it into execution
+* authorization.
+*/
+function resolveUserCommandItemFallbackActivationIds(descriptors, namespace) {
+	if (resolveUserLayerFooterMode(descriptors, namespace) !== "command") return EMPTY_IDS;
+	if (resolveUserLayerFooterFallbackMode(descriptors, namespace) !== "custom") return EMPTY_IDS;
+	const layout = resolveUserLayerFooterLayout(descriptors, namespace);
+	return layout === void 0 ? EMPTY_IDS : layoutRefIds(layout);
+}
+//#endregion
+//#region src/domain/footer/custom-items.ts
+/**
+* User-owned custom footer item definitions (PR C + PR D), neutral half
+* (TS5 §13.3): the persisted raw settings shapes, their validation and
+* normalization, and the config-effective values. Custom definitions are
+* persisted separately from FooterLayoutV1: the layout stores only the
+* canonical `user:*` reference, while this module owns what that item IS.
+* The presentation compilation (FooterItemDefinition / runtime catalog) lives
+* in `tui/footer/custom-item-catalog.ts`.
+* @module @xmoon76/dsh-pi-tui/domain/footer/custom-items
+*/
+/** The namespace reserved for user-created definitions. */
+const CUSTOM_FOOTER_ITEM_PREFIX = "user:";
+/** The default refresh interval for a custom command item (PR D §5.2):
+* several command items can coexist, so the default must not spawn one
+* process per item per second (the whole-footer M5 default is 1s). */
+const DEFAULT_CUSTOM_COMMAND_REFRESH_MS = 5e3;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/u;
+const TONES = /* @__PURE__ */ new Set([
+	"primary",
+	"accent",
+	"text",
+	"textStrong",
+	"textDim",
+	"textMuted",
+	"border",
+	"success",
+	"warning",
+	"error",
+	"roleUser",
+	"shellMode"
+]);
+/** The EXACT key set a v1 text definition may carry. A known-kind object
+* with any OTHER key is forward-compatible raw data (plan §12.1 — an
+* "unknown field object" keeps its raw slot): a future client's field must
+* never be silently normalized away by an unrelated save. */
+const TEXT_ITEM_KEYS = /* @__PURE__ */ new Set([
+	"schemaVersion",
+	"id",
+	"kind",
+	"text",
+	"tone"
+]);
+/** The EXACT key set a v1 command definition may carry (same rule). */
+const COMMAND_ITEM_KEYS = /* @__PURE__ */ new Set([
+	"schemaVersion",
+	"id",
+	"kind",
+	"command",
+	"refreshIntervalMs",
+	"timeoutMs",
+	"tone"
+]);
+/** Whether the raw object carries a key outside the allowed v1 set. */
+function hasUnknownKeys(raw, allowed) {
+	for (const key of Object.keys(raw)) if (!allowed.has(key)) return true;
+	return false;
+}
+/** The validated runner config for one command definition (maxRows is
+* always 1 — a custom command item is exactly one line; the composer owns
+* width/truncation). The custom-item DEFAULT refresh is 5s (several items
+* can coexist — the whole-footer 1s default would spawn a process per
+* item per second), so an ABSENT refreshIntervalMs is projected to the
+* custom default BEFORE the shared parser runs: an absent default and an
+* explicit 5s must produce the SAME cadence. The parser already validated
+* the definition, so this is defensive. This is the ONE projection both
+* the runtime and the effective-value helpers consume, so the UI, the
+* dirty comparator and the real execution can never drift apart. */
+function customCommandConfigOf(item) {
+	return parseFooterCommandConfig({
+		schemaVersion: 1,
+		command: item.command,
+		timeoutMs: item.timeoutMs,
+		refreshIntervalMs: item.refreshIntervalMs ?? 5e3,
+		maxRows: 1
+	});
+}
+/** The effective refresh interval of a command definition (absent = the
+* 5s default). Dirty comparison and the runtime use the EFFECTIVE value so
+* an absent default and an explicit default are the same fact. The value
+* is the SAME normalized value the runner executes (the shared parser
+* clamps refresh to >= 1s): a hand-edited out-of-range raw value is
+* preserved in storage for forward compatibility, but the UI and the
+* dirty comparator never lie about the real cadence. */
+function effectiveCustomCommandRefreshMs(item) {
+	return customCommandConfigOf(item)?.refreshIntervalMs ?? 5e3;
+}
+/** The effective timeout of a command definition (absent = the whole-footer
+* 300ms default; the shared parser clamps to 1..1000ms — the UI reports
+* the same value the runner enforces). */
+function effectiveCustomCommandTimeoutMs(item) {
+	return customCommandConfigOf(item)?.timeoutMs ?? 300;
+}
+function codePointLength(text) {
+	return [...text].length;
+}
+/** Normalize the name typed by the user and return undefined for a name that
+* cannot form a stable user namespace id. Colons are reserved so a user name
+* cannot impersonate another canonical namespace such as `ext:*`. */
+function normalizeCustomItemName(input) {
+	const name = input.trim();
+	if (name === "" || CONTROL_CHARS.test(name)) return void 0;
+	if (name.includes(":")) return void 0;
+	if (codePointLength(name) > 64) return void 0;
+	return name;
+}
+/** Convert a user-facing name to the deterministic persisted id. */
+function customItemId(name) {
+	const normalized = normalizeCustomItemName(name);
+	return normalized === void 0 ? void 0 : `${CUSTOM_FOOTER_ITEM_PREFIX}${normalized}`;
+}
+/** Return the user-facing part of a canonical id. */
+function customItemName(id) {
+	return id.startsWith("user:") ? id.slice(5) : id;
+}
+function isTone(value) {
+	return value === "auto" || typeof value === "string" && TONES.has(value);
+}
+/** Parse one persisted definition. Invalid definitions are rejected at this
+* boundary; callers can keep the rest of the collection. */
+function parseFooterCustomItem(input) {
+	try {
+		if (typeof input !== "object" || input === null || Array.isArray(input)) return void 0;
+		const raw = input;
+		if (raw.schemaVersion !== 1) return void 0;
+		if (typeof raw.id !== "string" || customItemId(customItemName(raw.id)) !== raw.id) return void 0;
+		if (raw.tone !== void 0 && !isTone(raw.tone)) return void 0;
+		const tone = raw.tone === void 0 ? void 0 : raw.tone;
+		if (raw.kind === "text") {
+			if (hasUnknownKeys(raw, TEXT_ITEM_KEYS)) return void 0;
+			if (typeof raw.text !== "string" || raw.text.trim() === "" || CONTROL_CHARS.test(raw.text)) return void 0;
+			if (codePointLength(raw.text) > 256) return void 0;
+			return {
+				schemaVersion: 1,
+				id: raw.id,
+				kind: "text",
+				text: raw.text,
+				...tone === void 0 ? {} : { tone }
+			};
+		}
+		if (raw.kind === "command") {
+			if (hasUnknownKeys(raw, COMMAND_ITEM_KEYS)) return void 0;
+			const refresh = typeof raw.refreshIntervalMs === "number" && Number.isFinite(raw.refreshIntervalMs) ? raw.refreshIntervalMs : void 0;
+			const timeout = typeof raw.timeoutMs === "number" && Number.isFinite(raw.timeoutMs) ? raw.timeoutMs : void 0;
+			const config = parseFooterCommandConfig({
+				schemaVersion: 1,
+				command: raw.command,
+				timeoutMs: timeout,
+				refreshIntervalMs: refresh,
+				maxRows: 1
+			});
+			if (config === void 0) return void 0;
+			const command = config.command;
+			return {
+				schemaVersion: 1,
+				id: raw.id,
+				kind: "command",
+				command,
+				...refresh === void 0 ? {} : { refreshIntervalMs: refresh },
+				...timeout === void 0 ? {} : { timeoutMs: timeout },
+				...tone === void 0 ? {} : { tone }
+			};
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+/** Parse the collection without letting one malformed or duplicate entry
+* break startup. The first definition for an id wins deterministically. A
+* hostile collection-level proxy/iterator fails closed as one invalid
+* collection instead of escaping into startup or reload. */
+function parseFooterCustomItems(input) {
+	try {
+		if (input === void 0) return {
+			items: [],
+			invalidCount: 0
+		};
+		if (!Array.isArray(input)) return {
+			items: [],
+			invalidCount: 1
+		};
+		const items = [];
+		const ids = /* @__PURE__ */ new Set();
+		let invalidCount = 0;
+		for (const candidate of input) {
+			const item = parseFooterCustomItem(candidate);
+			if (item === void 0 || ids.has(item.id)) {
+				invalidCount += 1;
+				continue;
+			}
+			ids.add(item.id);
+			items.push(item);
+		}
+		return {
+			items,
+			invalidCount
+		};
+	} catch {
+		return {
+			items: [],
+			invalidCount: 1
+		};
+	}
+}
+/** Every item id a layout references (the authorization / active-set
+* projection). An absent layout activates nothing. */
+function activeFooterItemIds(layout) {
+	const ids = /* @__PURE__ */ new Set();
+	if (layout === void 0) return ids;
+	for (const row of layout.rows) {
+		for (const ref of row.left) ids.add(ref.id);
+		for (const ref of row.right) ids.add(ref.id);
+	}
+	return ids;
+}
+/** The EXECUTABLE command item ids (PR D activation trust, final formula):
+*
+*   executable = USER trusted definitions ∩ USER-authorized ids ∩
+*                currently rendered layout ids
+*
+* The trusted definitions come from the USER-layer semantic read; the
+* authorized ids come from the ConfigPort's mode-gated projection (a stale
+* leftover USER layout under footer: default/compact authorizes nothing); the
+* rendered layout is what the composer actually shows — a command hidden by
+* the merged layout must not keep running in the background. A /footer save is
+* the special case where the just-committed validated layout is both
+* authorized and rendered. */
+function executableCommandItemIds(trustedCommands, authorizedIds, renderedLayout) {
+	const trustedIds = new Set(trustedCommands.map((item) => item.id));
+	const renderedIds = activeFooterItemIds(renderedLayout);
+	const executable = /* @__PURE__ */ new Set();
+	for (const id of renderedIds) if (trustedIds.has(id) && authorizedIds.has(id)) executable.add(id);
+	return executable;
+}
+/** Escape regex metacharacters for a finder's regex pattern: the completion
+* term is a LITERAL substring (the scoring model's input), so a filename
+* containing `[`, `+`, `.` etc. must match as literal text, never as a regex.
+* Both locality adapters pass the escaped term. */
+function escapeFinderRegex(term) {
+	return term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Normalize one finder's stdout into detached records: NUL records when the
+* finder honoured `--print0` (so legal filenames containing newlines survive),
+* the newline fallback for a fake/older finder (preserving meaningful leading
+* and trailing spaces in a filename), the `./` prefix strip, the directory
+* hint and the `.git` exclusion. PURE — operates solely on detached strings.
+*/
+function normalizeFinderRecords(stdout) {
+	const records = stdout.includes("\0") ? stdout.split("\0").filter((record) => record !== "") : (() => {
+		const lines = stdout.split(/\r?\n/);
+		if (lines.at(-1) === "") lines.pop();
+		return lines.filter((line) => line !== "");
+	})();
+	const out = [];
+	for (const line of records) {
+		const relative = line.startsWith("./") ? line.slice(2) : line;
+		if (relative === ".git" || relative.startsWith(".git/") || relative.includes("/.git/")) continue;
+		out.push({
+			path: relative.endsWith("/") ? relative.slice(0, -1) : relative,
+			directoryHint: relative.endsWith("/")
+		});
+	}
+	return out;
+}
+/**
+* The bounded recursive scan of one directory's SUBTREE: the root's direct
+* children are always complete (a root-level `src/` must be found), deeper
+* entries are capped at {@link MAX_FALLBACK_SCAN}. Paths are relative to
+* `baseDir` (`sub/deep.ts`); `.git` is skipped (kimi parity); a symlinked
+* directory is NEVER descended — at the search root and below it alike
+* (cycle safety), so a link to a parent directory or to the workspace's
+* outside cannot widen the scan or consume the traversal budget.
+*
+* ASYNC: the fuzzy fallback runs on the EDITOR path, so a synchronous
+* whole-tree traversal would block the editor's event loop per keystroke. The
+* scan yields to the event loop between directory levels and checks the
+* AbortSignal inside the loop — the editor stays responsive and a cancelled
+* request stops the traversal promptly.
+*/
+async function scanSubtree(baseDir, driver, signal) {
+	const candidates = [];
+	const firstEntries = await driver.listDirectory(baseDir, "", signal);
+	if (signal.aborted || firstEntries === null) return [];
+	const stack = [];
+	for (const entry of firstEntries) {
+		if (entry.name === ".git") continue;
+		candidates.push({
+			path: entry.name,
+			kind: entry.kind
+		});
+		if (entry.descendable) stack.push(entry.name);
+	}
+	let scanned = 0;
+	while (stack.length > 0 && scanned < 2e3) {
+		if (signal.aborted) break;
+		const relativeDir = stack.pop() ?? "";
+		const entries = await driver.listDirectory(baseDir, relativeDir, signal);
+		if (entries === null) continue;
+		for (const entry of entries) {
+			if (signal.aborted || scanned >= 2e3) break;
+			if (entry.name === ".git") continue;
+			const path = `${relativeDir}/${entry.name}`;
+			scanned += 1;
+			candidates.push({
+				path,
+				kind: entry.kind
+			});
+			if (entry.kind === "directory" && entry.descendable) stack.push(path);
+		}
+		if (stack.length > 0) await new Promise((resolve) => setImmediate(resolve));
+	}
+	return signal.aborted ? [] : candidates;
+}
+/** Map one driver listing into path candidates, dropping `.git` (a `@` or
+* `/image` listing never presents VCS internals). PURE. */
+function listingCandidates(entries) {
+	return entries.filter((entry) => entry.name !== ".git").map((entry) => ({
+		path: entry.name,
+		kind: entry.kind
+	}));
+}
+/**
+* Answer one resolved query with discovery facts: a scoped LISTING (empty
+* term) reads the target directory's direct children; a scoped or whole-tree
+* FUZZY query uses the locality finder when available and the bounded subtree
+* scan otherwise. Paths are relative to the QUERY's search base.
+* @param query - the resolved path query (searchBase already absolute).
+* @param driver - the locality's discovery boundary.
+* @param signal - the editor's request abort.
+*/
+async function discoverForQuery(query, driver, signal) {
+	if (query.explicitScope && query.searchTerm === "") {
+		if (signal.aborted) return [];
+		const direct = await driver.listDirectory(query.searchBase, "", signal);
+		if (signal.aborted || direct === null) return [];
+		return listingCandidates(direct);
+	}
+	if (!query.winAbsolute && !query.raw.includes("\\")) {
+		const found = await driver.find(query.searchBase, query.searchTerm, signal);
+		if (signal.aborted) return [];
+		if (found !== null) {
+			const seen = new Set(found.map((candidate) => candidate.path));
+			const lowerTerm = query.searchTerm.toLowerCase();
+			const direct = await driver.listDirectory(query.searchBase, "", signal);
+			if (signal.aborted) return [];
+			const merged = (direct === null ? [] : listingCandidates(direct)).filter((candidate) => lowerTerm === "" || candidate.path.toLowerCase().includes(lowerTerm)).filter((candidate) => !seen.has(candidate.path));
+			return [...found, ...merged];
+		}
+	}
+	return scanSubtree(query.searchBase, driver, signal);
+}
+//#endregion
+//#region src/domain/file-completion/query.ts
+/**
+* The neutral path query resolver (TS8-A, split out of the historical
+* `src/file-completion/query.ts`): PURE — turns a raw token into the search
+* directory, the basename term, the display prefix and whether the token
+* names an EXPLICIT scope. No filesystem access, and no environment
+* discovery: the facts this algebra needs arrive from the LOCALITY owner as
+* an explicit {@link PathQueryEnvironment}, never from `homedir()` /
+* `process.platform` inside the domain layer.
+*
+* A scoped token (`src/fo`, `../foo`, `../../foo`, `~/foo`, `/tmp/foo`,
+* a drive-qualified path, or an UNC path) searches ONLY its resolved
+* directory — never a whole-tree scan filtered by string. An unscoped token
+* (`foo`, `nested`, `config`) is a whole-tree fuzzy query with an EMPTY
+* display base.
+* @module @xmoon76/dsh-pi-tui/domain/file-completion/query
+*/
+/**
+* The HOST filesystem's path algebra, selected from the EXPLICIT
+* `windowsHost` fact. Every host-native path this module computes (a joined
+* scope, an expanded `~`) goes through this api, so the domain never infers
+* the running machine from the ambient `node:path` default export: a caller
+* that injects a foreign host's facts gets that host's algebra.
+*/
+function hostPathApi(windowsHost) {
+	return windowsHost ? win32 : posix;
+}
+/**
+* Return the final path component without depending on the host OS dialect.
+* Completion can present a Windows path while the client process is running
+* on POSIX (and vice versa), so `node:path.basename` is not sufficient here.
+*/
+function basenameOfPath(path) {
+	const separator = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+	return path.slice(separator + 1);
+}
+/**
+* Expand a leading `~` in one token against the locality's home directory
+* (other tokens unchanged). PURE — both the home directory AND the host
+* platform are explicit facts: the joined result is a path on the HOST
+* filesystem, so it uses that host's algebra.
+* @param token - the raw token.
+* @param homeDir - the locality owner's home directory fact.
+* @param windowsHost - whether the filesystem host is Windows.
+*/
+function expandHomeToken(token, homeDir, windowsHost) {
+	if (token === "~") return homeDir;
+	if (token.startsWith("~/") || token.startsWith("~\\")) return hostPathApi(windowsHost).join(homeDir, token.slice(2).replace(/\\/g, "/"));
+	return token;
+}
+/**
+* Choose the separator immediately before the basename. This preserves a
+* mixed Windows token's actual dialect (forward-slash drive paths stay
+* forward-slashed, while backslash drive paths stay backslashed) instead of
+* normalizing it to the host platform's preferred separator.
+*/
+function separatorOfRaw(raw, windowsDialect) {
+	const slash = raw.lastIndexOf("/");
+	const backslash = raw.lastIndexOf("\\");
+	if (slash === -1 && backslash === -1) return windowsDialect ? "\\" : "/";
+	return backslash > slash ? "\\" : "/";
+}
+/** Whether the token is a leading-home form, including `~\\foo`. */
+function isHomeToken$1(raw) {
+	return raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\");
+}
+/** Whether one raw token is genuinely Windows-dialect. */
+function isWindowsDialect(raw, winAbsolute) {
+	return winAbsolute || raw.includes("\\");
+}
+/** Whether an absolute path uses the Windows drive/UNC grammar. */
+function isWindowsAbsolute(raw) {
+	return !raw.startsWith("/") && win32.isAbsolute(raw);
+}
+/** Join a relative scope while keeping POSIX fixtures usable for a
+* Windows-looking token. The result is a path on the HOST filesystem, so the
+* joiner comes from the EXPLICIT host fact (never `process.platform`); the
+* TOKEN's own dialect only decides whether backslashes are the user's
+* separators or ordinary characters.
+*
+* A `windowsDialect` token on a POSIX host has backslashes in the USER'S
+* dialect, not as filesystem separators, so they are normalized; an
+* unmistakable drive/UNC `cwd` selects the win32 joiner even on a POSIX host
+* (that cwd string is itself a Windows path). */
+function joinRelativeScope(cwd, rawPath, windowsDialect, windowsHost) {
+	const api = hostPathApi(windowsHost);
+	if (!windowsDialect) return api.join(cwd, rawPath);
+	const windowsCwd = /^[A-Za-z]:[\\/]/.test(cwd) || cwd.startsWith("\\\\");
+	if (windowsHost || windowsCwd) return win32.join(cwd, rawPath);
+	return api.join(cwd, rawPath.replace(/\\/g, "/"));
+}
+/** Whether the raw token names a directory that should be LISTED
+* (`searchTerm === ''`). `.`/`..` root forms list their own relative
+* directory; `./`/`../`/`~`/`/` list the scope root. */
+function isBareScopeForm(raw) {
+	return raw === "" || raw === "." || raw === ".." || raw === "./" || raw === "../" || raw === "~" || raw === "~/" || raw === "~\\" || raw === "/" || raw === ".\\" || raw === "..\\";
+}
+/**
+* Resolve ONE raw completion token into the pure path query.
+* @param raw - the token as typed (quotes stripped; leading separator
+*   whitespace stripped by the caller).
+* @param cwd - the completion base (the Client cwd for local completion, the
+*   Direct workspace cwd for the WORKSPACE compatibility scanner; relative
+*   forms resolve against it).
+* @param environment - the locality owner's explicit environment facts.
+*/
+function resolvePathQuery(raw, cwd, environment) {
+	const expanded = expandHomeToken(raw, environment.homeDir, environment.windowsHost);
+	const posixAbsolute = raw.startsWith("/");
+	const winAbsolute = isWindowsAbsolute(raw);
+	const windowsDialect = isWindowsDialect(raw, winAbsolute);
+	const absolute = isHomeToken$1(raw) || posixAbsolute || winAbsolute;
+	const tokenWindows = windowsDialect || environment.windowsHost;
+	const pathDirname = tokenWindows ? win32.dirname : posix.dirname;
+	const pathBasename = tokenWindows ? win32.basename : posix.basename;
+	const separator = separatorOfRaw(raw, windowsDialect);
+	if (isBareScopeForm(raw)) return {
+		raw,
+		searchBase: raw === "." || raw === ".." || raw === "./" || raw === "../" || raw === ".\\" || raw === "..\\" ? joinRelativeScope(cwd, raw, windowsDialect, environment.windowsHost) : absolute ? expanded : joinRelativeScope(cwd, expanded, windowsDialect, environment.windowsHost),
+		searchTerm: "",
+		displayBase: raw === "" ? "" : raw === "~" ? `~${separator}` : raw.endsWith("/") || raw.endsWith("\\") ? raw : `${raw}${separator}`,
+		explicitScope: true,
+		winAbsolute
+	};
+	if (raw.endsWith("/") || raw.endsWith("\\")) return {
+		raw,
+		searchBase: absolute ? expanded : joinRelativeScope(cwd, expanded, windowsDialect, environment.windowsHost),
+		searchTerm: "",
+		displayBase: raw,
+		explicitScope: true,
+		winAbsolute
+	};
+	const lastSlash = Math.max(raw.lastIndexOf("/"), raw.lastIndexOf("\\"));
+	const hasSeparator = lastSlash >= 0;
+	const displayBase = hasSeparator ? raw.slice(0, lastSlash + 1) : "";
+	const rawDir = hasSeparator ? raw.slice(0, lastSlash) : "";
+	const searchTerm = pathBasename(expanded);
+	const explicitScope = hasSeparator || absolute;
+	const searchBaseForScope = isHomeToken$1(raw) ? expandHomeToken(rawDir, environment.homeDir, environment.windowsHost) : absolute ? pathDirname(expanded) : joinRelativeScope(cwd, rawDir, windowsDialect, environment.windowsHost);
+	return {
+		raw,
+		searchBase: explicitScope ? searchBaseForScope : cwd,
+		searchTerm,
+		displayBase,
+		explicitScope,
+		winAbsolute
+	};
+}
+/**
+* Reattach the query's display base onto one discovered candidate path.
+* Discovery returns paths RELATIVE to the query's search base; the candidate
+* the user accepts must read in the USER'S dialect (`../sibling-file.ts`,
+* `~/pics/a.png`, `src/deep.ts`, `/tmp/x`). The SOURCE calls this before its
+* candidates cross the port contract (the port's paths are user-facing).
+* PURE.
+*/
+function reattachDisplayBase(candidate, query) {
+	if (query.displayBase === "") return candidate;
+	return {
+		...candidate,
+		path: `${query.displayBase}${candidate.path}`
+	};
+}
+/** Score one candidate against the query term (lowercased). */
+function scorePathCandidate(candidate, lowerQuery) {
+	if (lowerQuery === "") {
+		const depthPenalty = candidate.path.split(/[\\/]/).length - 1;
+		return (candidate.kind === "directory" ? 120 : 100) - depthPenalty;
+	}
+	const lowerPath = candidate.path.toLowerCase();
+	const lowerBase = basenameOfPath(candidate.path).toLowerCase();
+	let score = 0;
+	if (lowerBase === lowerQuery) score = 100;
+	else if (lowerBase.startsWith(lowerQuery)) score = 80;
+	else if (lowerBase.includes(lowerQuery)) score = 50;
+	else if (lowerPath.includes(lowerQuery)) score = 30;
+	if (candidate.kind === "directory" && score > 0) score += 10;
+	return score;
+}
+/** Deterministic order: score desc, directories (kind) first, path asc. */
+function compareScoredPaths(left, right) {
+	if (left.score !== right.score) return right.score - left.score;
+	if (left.candidate.kind !== right.candidate.kind) return left.candidate.kind === "directory" ? -1 : 1;
+	return left.candidate.path.localeCompare(right.candidate.path);
+}
+/**
+* Rank, filter and bound one discovery set (the local scoring model — the
+* SOURCE's own order for its Client-fs / Direct-workspace-compat consumers,
+* NOT the live Session `@` mention path, whose ranking is the official Host
+* authority's). PURE: path candidates in, ranked path candidates out — no UI
+* DTOs, so a semantic adapter can own its ranking end-to-end.
+*/
+function rankPathCandidates(candidates, term) {
+	const lowerQuery = term.toLowerCase();
+	return candidates.map((candidate) => ({
+		candidate,
+		score: scorePathCandidate(candidate, lowerQuery)
+	})).filter((entry) => entry.score > 0).sort(compareScoredPaths).slice(0, 50).map((entry) => entry.candidate);
+}
+//#endregion
+//#region src/runtime/read-error.ts
+/**
+* A typed semantic READ failure: the read was superseded by a connection or
+* surface change, so its result must not be presented as the current Host
+* state. Remote adapters throw this instead of a generic Error so a consumer
+* can stay UI-silent (v2 §0.2.3/§0.3.1) rather than surfacing a stale failure.
+* Host-free; no I/O.
+* @module @xmoon76/dsh-pi-tui/read-error
+*/
+/** The read no longer owns the surface (generation change or superseded epoch). */
+var SupersededReadError = class extends Error {
+	reason;
+	constructor(reason) {
+		super(reason);
+		this.name = "SupersededReadError";
+		this.reason = reason;
+	}
+};
+//#endregion
+//#region src/domain/catalog/provider.ts
+/**
+* Read a value at a dotted path inside a plain object (the web schema-form
+* `getPath` semantics, structural here so /login needs no schema package).
+* @param value - the object to walk.
+* @param path - path segments; the empty path returns `value` itself.
+* @returns the value at the path, or undefined when any segment is missing.
+*/
+function getPath(value, path) {
+	let current = value;
+	for (const key of path) {
+		if (Array.isArray(current)) {
+			current = current[Number(key)];
+			continue;
+		}
+		if (typeof current !== "object" || current === null) return void 0;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* Derive the conventional credential reference for a provider route: the web
+* Models page never asks for an environment-variable name, so a typed key
+* stores under this derived reference and the profile records it as
+* `apiKeyEnv`. Kept byte-identical to the web's `deriveKeyRef`.
+* @param provider - provider route id (e.g. `anthropic`, `minimax-cn`).
+* @returns the derived reference name (e.g. `MINIMAX_CN_API_KEY`).
+*/
+function deriveKeyRef(provider) {
+	return `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
+}
+/**
+* A route id usable as a settings key AND as the stem of a credential name.
+* The web create card's pattern: the leading letter is the second half of
+* that — `deriveKeyRef` uppercases the id and replaces every non-alphanumeric
+* run with `_`, and a credential reference is a POSIX shell identifier, which
+* cannot start with a digit. A digit-leading id passes every check this card
+* makes and then fails at the credential seam with a raw regular expression
+* the user cannot act on.
+*/
+const ROUTE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** The wire protocols a hand-declared route may name. Mirrors the pi-ai
+* adapter's `supportedProtocols()`; keep in step with
+* `@deepseek-ai/dsh-llm-pi-ai`'s `PROTOCOLS` table (the drift gate is the
+* adapter's own — a protocol it stops serving must be removed here too). */
+const PROTOCOL_CHOICES = [
+	"openai-completions",
+	"openai-responses",
+	"anthropic-messages"
+];
+/**
+* Merge the configurable-provider directory with the existing settings
+* section into the /login option list.
+*
+* @param entries - the llm directory entries (or undefined when the llm
+*   service is absent — degrades to the official target only).
+* @param readSection - read one settings namespace's resolved section (the
+*   settings service's `get`); absent namespaces read as undefined.
+* @returns the merged options, deepseek official first, deduped by ref.
+*/
+function providerOptionsFor(entries, readSection) {
+	const options = [];
+	const seen = /* @__PURE__ */ new Set();
+	const push = (option) => {
+		if (seen.has(option.ref)) return;
+		seen.add(option.ref);
+		options.push(option);
+	};
+	push({
+		label: "deepseek official",
+		ref: "DEEPSEEK_API_KEY",
+		route: "deepseek-official",
+		configured: true,
+		declared: false,
+		namesCredential: true,
+		group: "configured",
+		settingsNs: "",
+		settingsPath: []
+	});
+	if (entries === void 0) return options;
+	for (const entry of entries) {
+		if (entry.provider.length === 0 || entry.settingsNs.length === 0) continue;
+		const section = readSection(entry.settingsNs);
+		const profile = entry.settingsPath.length === 0 ? section : getPath(section, entry.settingsPath);
+		const configured = profile !== void 0;
+		const namedRef = configured && typeof profile === "object" && profile !== null && typeof profile.apiKeyEnv === "string" ? profile.apiKeyEnv : void 0;
+		const namesCredential = namedRef !== void 0 && namedRef !== "";
+		const ref = namesCredential ? namedRef : deriveKeyRef(entry.provider);
+		push({
+			label: entry.displayName,
+			ref,
+			route: entry.provider,
+			configured,
+			declared: entry.declared === true,
+			namesCredential,
+			group: configured ? "configured" : entry.declared === true ? "custom" : "available",
+			settingsNs: entry.settingsNs,
+			settingsPath: [...entry.settingsPath]
+		});
+	}
+	return options;
+}
+/** The credential-target options for /login and /logout: the deepseek
+* official ref always first, then every llm-pi-ai provider route's
+* apiKeyEnv (deduped by ref). `providers` is the llm-pi-ai settings
+* section's `providers` dict, or undefined when the adapter or the settings
+* service is absent — which degrades /login to the official target only.
+* Kept as the settings-only fallback when the llm directory is absent. */
+function credentialOptionsFor(providers) {
+	const options = [{
+		label: "deepseek official",
+		ref: "DEEPSEEK_API_KEY"
+	}];
+	if (providers === void 0) return options;
+	const seen = new Set(options.map((option) => option.ref));
+	for (const [route, profile] of Object.entries(providers)) {
+		const ref = profile?.apiKeyEnv;
+		if (ref === void 0 || ref === "" || seen.has(ref)) continue;
+		seen.add(ref);
+		options.push({
+			label: route,
+			ref
+		});
+	}
+	return options;
+}
+/** Resolve a /login or /logout argument to a credential ref. A
+* case-insensitive llm-pi-ai route name wins, then a literal env-var-looking
+* name (any casing, uppercased like the old behavior — `/login my_key` sets
+* `MY_KEY`); anything else is unknown and returns undefined so the caller
+* can list the valid options. */
+function resolveCredentialArg(arg, options) {
+	const trimmed = arg.trim();
+	if (trimmed === "") return void 0;
+	const needle = trimmed.toLowerCase();
+	const route = options.find((option) => option.label.toLowerCase() === needle || option.label.split(" ")[0].toLowerCase() === needle);
+	if (route !== void 0) return route.ref;
+	if (/^[a-zA-Z][a-zA-Z0-9_]*$/.test(trimmed)) return trimmed.toUpperCase();
+}
+//#endregion
+//#region src/runtime/session-lifecycle-port.ts
+/** A lifecycle outcome that must ABORT the caller's transition, carrying the
+*  two independent axes so a Remote caller never has to parse a string. */
+var LifecycleError = class extends Error {
+	settlement;
+	ownership;
+	publishedSessionId;
+	/** CORRELATION ONLY for an indeterminate create — never publication proof. */
+	requestedSessionId;
+	constructor(settlement, ownership, message, publishedSessionId, requestedSessionId) {
+		super(message);
+		this.name = "LifecycleError";
+		this.settlement = settlement;
+		this.ownership = ownership;
+		this.publishedSessionId = publishedSessionId;
+		this.requestedSessionId = requestedSessionId;
+	}
+};
+/** Unwrap a CREATE result for the runner's transition: a `created` result that
+*  still owns the surface yields the handle; everything else aborts with a
+*  machine-readable `LifecycleError` (a superseded create is NOT committed to
+*  the local surface, though its identity stays available). */
+function requireCreated(result) {
+	const { ownership, outcome } = result;
+	switch (outcome.kind) {
+		case "created":
+			if (ownership === "superseded") throw new LifecycleError("superseded", ownership, `Session "${outcome.handle.session.id}" was created, but the local surface was superseded — do not retry creation`, outcome.handle.session.id);
+			return outcome.handle;
+		case "published-with-error": throw new LifecycleError(outcome.kind, ownership, `Session "${outcome.sessionId}" was published, but workspace attach/reconcile failed: ${outcome.error.message} (${outcome.error.code}) — do not retry creation`, outcome.sessionId);
+		case "indeterminate": throw new LifecycleError(outcome.kind, ownership, `the create is indeterminate — do not retry: ${outcome.error.message} (${outcome.error.code})`, void 0, outcome.requestedSessionId);
+		case "rejected": throw new LifecycleError(outcome.kind, ownership, `${outcome.error.message} (${outcome.error.code})`, void 0);
+		case "cancelled": throw new LifecycleError("cancelled", ownership, "the Session creation was cancelled before dispatch", void 0);
+	}
+}
+/** Unwrap an OPEN result for the runner's transition. */
+function requireOpened(result) {
+	const { ownership, outcome } = result;
+	switch (outcome.kind) {
+		case "opened":
+			if (ownership === "superseded") throw new LifecycleError("superseded", ownership, "the Session was opened but the local surface was superseded", outcome.handle.session.id);
+			return outcome.handle;
+		case "unavailable": throw new LifecycleError("unavailable", ownership, outcome.message, void 0);
+		case "cancelled": throw new LifecycleError("cancelled", ownership, "the Session open was cancelled before selection", void 0);
+	}
+}
+/** Extract the Direct ownership handle (the real AgentHandle with
+* `dispose()`) from a lifecycle result. Accepts both the converged
+* SessionHandle and a legacy AgentHandle so transition code cannot lose the
+* ownership capability. Remote handles lack `direct` and yield undefined. */
+function ownerHandleOf(next) {
+	const handle = next;
+	if (handle.direct?.ownerHandle !== void 0) return handle.direct.ownerHandle;
+	if (typeof handle.dispose === "function") return handle;
+}
+/** Extract the live in-process agent from a lifecycle result (the Direct
+* SessionHandle via `direct.agent`, or a legacy AgentHandle's `agent`).
+* Remote handles yield undefined. */
+function directAgentOf(next) {
+	const handle = next;
+	return handle.direct?.agent ?? handle.agent;
+}
+/** Extract the Remote Client generation owner from a lifecycle result. A
+* Direct handle yields undefined. A composing Remote caller must release it
+* exactly once on retirement — including when a superseded transition discards
+* the handle. The Remote session-owner provider (`app/remote/session-owners.ts`)
+* consumes it as the sole ownership mapping source; the Direct runner never
+* interprets it. */
+function clientOwnerOf(next) {
+	return next.client;
+}
+//#endregion
+//#region src/runtime/capability.ts
+/** The capabilities the experimental Remote backend serves: exactly the
+* ports its M3-3B assembly provides. A capability is added HERE only when its
+* Remote port genuinely serves the semantic contract (no misleading empty
+* defaults), so the set is deliberately explicit rather than derived. */
+const REMOTE_IMPLEMENTED_CAPABILITIES = [
+	"session-read",
+	"session-write",
+	"session-lifecycle",
+	"subagent",
+	"interaction",
+	"catalog",
+	"config",
+	"host-file",
+	"session-archive",
+	"host-command",
+	"plugin-manager",
+	"job-observation"
+];
+/** The capabilities the Direct backend ACTUALLY serves today: one port per
+* entry, nothing more — never advertise what is not served. */
+const DIRECT_IMPLEMENTED_CAPABILITIES = [
+	"session-read",
+	"session-write",
+	"session-lifecycle",
+	"subagent",
+	"interaction",
+	"catalog",
+	"config",
+	"host-file",
+	"session-archive",
+	"host-command",
+	"plugin-manager",
+	"job-observation"
+];
+//#endregion
+//#region src/runtime/write-outcome.ts
+/**
+* Pinned Gateway infrastructure codes raised strictly BEFORE the addressed
+* business method is invoked (descriptor/argument/receiver/endpoint resolution
+* and context/lookup provider resolution — all inside `prepareInvocation` and
+* boundary decoding): such a failure proves the operation did not commit. The
+* only Gateway code raised AFTER invocation is `gateway/result-invalid`, so it
+* is deliberately absent.
+*/
+const GATEWAY_PRE_INVOCATION_CODES = /* @__PURE__ */ new Set([
+	"gateway/ambiguous-endpoint",
+	"gateway/arguments-invalid",
+	"gateway/binding-invalid",
+	"gateway/context-failed",
+	"gateway/context-not-found",
+	"gateway/context-unavailable",
+	"gateway/definition-unavailable",
+	"gateway/input-invalid",
+	"gateway/invocation-unavailable",
+	"gateway/lookup-failed",
+	"gateway/lookup-not-found",
+	"gateway/lookup-unavailable",
+	"gateway/method-unavailable",
+	"gateway/provider-mismatch",
+	"gateway/service-unavailable",
+	"gateway/signature-invalid"
+]);
+/**
+* Whether a failure code PROVES the addressed operation was refused: domain
+* codes, `gateway/bad-request`, and the pinned pre-invocation Gateway
+* infrastructure codes qualify. `gateway/cancelled`, `gateway/internal`,
+* `gateway/result-invalid`, an unknown `gateway/*` code, or a code-less failure
+* do NOT (the commit state stays unproven).
+*
+* SCOPE: this predicate expresses ONLY the D2.2-verified write vocabulary plus
+* the pinned Gateway pre-invocation codes. It is NOT a general
+* idempotency/commit judgement: a domain code does not universally prove that
+* no mutation happened (e.g. `session/workspace-attach-failed` can follow a
+* successful Session create/fork). Later operation families (D2.3/D2.4) must
+* use their own operation-specific settlement table rather than extending this
+* helper.
+*/
+function isRemoteBusinessRefusalCode(code) {
+	if (code === void 0) return false;
+	if (code === "gateway/bad-request") return true;
+	if (code.startsWith("gateway/")) return GATEWAY_PRE_INVOCATION_CODES.has(code);
+	return true;
+}
+//#endregion
+//#region src/runtime/subagent-outcome.ts
+/**
+* Backend-neutral outcome/error classification for one subagent viewer prompt
+* (TS8-F4): the stable refusal taxonomy shared by the Direct and Remote
+* adapters. Pure and never throwing — it reads structural `code` values only,
+* so the subagent package stays resolvable from the dsh installation and is
+* never imported here.
+* @module @xmoon76/dsh-pi-tui/runtime/subagent-outcome
+*/
+/**
+* Settle a failed viewer prompt. A caller cancellation and every PROVEN refusal
+* code are rejected (a domain `subagent/*` admission refusal, `gateway/bad-request`,
+* or a pre-invocation Gateway infrastructure code); only a carrier/internal/
+* post-invocation failure (`gateway/internal`, `gateway/result-invalid`, an
+* unknown `gateway/*` code) or a code-less throw settles `indeterminate`.
+*/
+function classifySubagentPromptSettlement(error) {
+	const reason = classifySubagentPromptError(error);
+	if (reason.kind !== "error") return {
+		kind: "rejected",
+		reason
+	};
+	if (isRemoteBusinessRefusalCode(remoteErrorCode(error))) return {
+		kind: "rejected",
+		reason
+	};
+	return {
+		kind: "indeterminate",
+		message: reason.message
+	};
+}
+/**
+* Classify an official prompt failure into the stable reason set. The Direct
+* adapter reads the official RemoteError vocabulary structurally (the `code`
+* string; the subagent package stays resolvable from the dsh installation,
+* never an import here).
+*/
+function classifySubagentPromptError(error) {
+	if (isAbortError(error)) return { kind: "cancelled" };
+	const code = remoteErrorCode(error);
+	if (code === "gateway/cancelled") return { kind: "cancelled" };
+	if (code === "subagent/parent-unavailable") return { kind: "parent-unavailable" };
+	if (code === "subagent/not-resumable" || code === "subagent/not-found" || code === "subagent/catalog-diagnostic") return { kind: "stale-child" };
+	if (code === "subagent/unauthorized") return { kind: "unauthorized" };
+	if (code === "subagent/delivery-unavailable" || code === "subagent/projections-unavailable") return { kind: "unavailable" };
+	return {
+		kind: "error",
+		message: safeSubagentErrorMessage(error)
+	};
+}
+/** The stable failure code of a structural official failure, if any. */
+function remoteErrorCode(error) {
+	if (typeof error !== "object" || error === null) return void 0;
+	const code = error.code;
+	return typeof code === "string" && code !== "" ? code : void 0;
+}
+function isAbortError(error) {
+	return typeof error === "object" && error !== null && error.name === "AbortError";
+}
+/** One-line safe error text (never throws on hostile values). Shared with the
+* Direct adapter's pre-dispatch catch so both settle the same wording. */
+function safeSubagentErrorMessage(error) {
+	if (error === void 0 || error === null) return "unknown error";
+	if (typeof error === "string") return error;
+	if (error instanceof Error) {
+		const message = error.message;
+		return message === "" ? error.name : message;
+	}
+	if (typeof error === "object") {
+		const message = error.message;
+		if (typeof message === "string" && message !== "") return message;
+	}
+	try {
+		return String(error);
+	} catch {
+		return "unknown error";
+	}
+}
+//#endregion
+//#region src/runtime/presentation-read-port.ts
+/** Detach the official `turnOutline` wire view into the picker DTO — only
+*  well-formed entries cross (shared by the Direct projection read and the
+*  Remote binding projection read); a foreign-shaped value reads unknown. */
+function detachedTurnOutline(value) {
+	if (!Array.isArray(value)) return void 0;
+	const entries = [];
+	for (const entry of value) {
+		if (typeof entry !== "object" || entry === null) return void 0;
+		const record = entry;
+		if (typeof record.turn !== "number" || typeof record.seq !== "number") return void 0;
+		if (typeof record.prompt !== "string" || typeof record.response !== "string") return void 0;
+		entries.push({
+			turn: record.turn,
+			seq: record.seq,
+			prompt: record.prompt,
+			response: record.response
+		});
+	}
+	return Object.freeze(entries);
+}
+//#endregion
+//#region src/runtime/session-status-projection.ts
+/**
+* Detach the official projection values into the status DTO. Fields are
+* only present when their official projection value is well-formed; nothing
+* is coerced, defaulted or copied from another subject.
+*/
+function detachedSessionStatus(sessionId, values, cwd) {
+	const record = { sessionId };
+	if (typeof cwd === "string" && cwd !== "") record.cwd = cwd;
+	const model = modelSelectionFact(values.modelSelection);
+	if (model !== void 0) record.model = model;
+	if (typeof values.agentPreset === "string" && values.agentPreset !== "") record.preset = values.agentPreset;
+	if (typeof values.title === "string" && values.title !== "") record.title = values.title;
+	const permissionValue = values.permissions;
+	if (typeof permissionValue === "object" && permissionValue !== null) {
+		const current = permissionValue.currentValue;
+		if (typeof current === "string" && current !== "") record.permission = current;
+	}
+	if ("goal" in values) {
+		const goal = goalFact(values.goal);
+		if (goal !== void 0) record.goal = goal;
+	}
+	const pressure = numericRecord(values.contextPressure);
+	const breakdownValue = values.contextBreakdown;
+	const breakdown = typeof breakdownValue === "object" && breakdownValue !== null ? numericRecord(breakdownValue) : void 0;
+	const hasBreakdown = breakdown !== void 0 && typeof breakdown.systemTokens === "number" && typeof breakdown.toolsTokens === "number" && typeof breakdown.messageTokens === "number";
+	if (pressure !== void 0 && Object.keys(pressure).length > 0 || hasBreakdown) record.context = {
+		...pressure ?? {},
+		...hasBreakdown ? { breakdown: {
+			systemTokens: breakdown.systemTokens,
+			toolsTokens: breakdown.toolsTokens,
+			messageTokens: breakdown.messageTokens
+		} } : {}
+	};
+	const todos = detachedTodos(values.todos);
+	if (todos !== void 0) record.todos = todos;
+	const usageValue = numericRecord(values.tokenUsage);
+	if (usageValue !== void 0 && typeof usageValue.uncachedInputTokens === "number" && typeof usageValue.outputTokens === "number" && typeof usageValue.cacheReadTokens === "number" && typeof usageValue.cacheWriteTokens === "number") record.usage = {
+		uncachedInputTokens: usageValue.uncachedInputTokens,
+		outputTokens: usageValue.outputTokens,
+		cacheReadTokens: usageValue.cacheReadTokens,
+		cacheWriteTokens: usageValue.cacheWriteTokens
+	};
+	return record;
+}
+/** Narrow the official `goal` projection view: `null` (no goal) is a LEGAL
+*  value and stays distinct from `undefined` (unavailable); the current goal
+*  is read from `goal.{objective,phase}` with the phase vocabulary validated. */
+function goalFact(value) {
+	if (value === null) return null;
+	if (typeof value !== "object") return void 0;
+	const current = value.goal;
+	if (typeof current !== "object" || current === null) return void 0;
+	const goal = current;
+	if (typeof goal.objective !== "string" || goal.objective === "") return void 0;
+	if (goal.phase !== "active" && goal.phase !== "paused" && goal.phase !== "blocked" && goal.phase !== "complete") return;
+	return {
+		objective: goal.objective,
+		phase: goal.phase
+	};
+}
+/** Narrow an unknown projection value to its numeric fields (no coercion). */
+function numericRecord(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const source = value;
+	const out = {};
+	for (const [key, entry] of Object.entries(source)) if (typeof entry === "number") out[key] = entry;
+	return out;
+}
+/** The effective selection off the official `modelSelection` fold:
+* `next ?? lastUsed`, validated to the normalized shape. */
+function modelSelectionFact(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const fold = value;
+	for (const candidate of [fold.next, fold.lastUsed]) {
+		if (typeof candidate !== "object" || candidate === null) continue;
+		const selection = candidate;
+		if (typeof selection.provider !== "string" || selection.provider === "") continue;
+		if (typeof selection.model !== "string" || selection.model === "") continue;
+		return {
+			provider: selection.provider,
+			model: selection.model,
+			...typeof selection.reasoningEffort === "string" && selection.reasoningEffort !== "" ? { reasoningEffort: selection.reasoningEffort } : {}
+		};
+	}
+}
+/** Detach the official `todos` whole-list snapshot. The projection's
+* LEGAL `null` (no `todo/write` yet) stays `null`; only `undefined` (the
+* projection value was absent — capability unavailable) reads absent. */
+function detachedTodos(value) {
+	if (value === null) return null;
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) return void 0;
+	const todos = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) return void 0;
+		const todo = item;
+		if (typeof todo.content !== "string") return void 0;
+		if (todo.status !== "pending" && todo.status !== "in_progress" && todo.status !== "completed") return void 0;
+		todos.push({
+			content: todo.content,
+			status: todo.status
+		});
+	}
+	return Object.freeze(todos);
+}
+//#endregion
+//#region src/runtime/interaction-port.ts
+/** The official Host code for a late answer whose reply is already queued. */
+const QUESTION_REPLY_QUEUED = "REPLY_QUEUED";
+/** The official Host code for a late answer that does not name each question. */
+const QUESTION_BAD_ANSWER = "BAD_ANSWER";
+/**
+* One rejected late answer with the Host's stable code (`REPLY_QUEUED`,
+* `BAD_ANSWER`, `CALLER_NOT_LIVE`, or a transport/gateway code). Both
+* adapters throw THIS shape so a consumer can offer truthful recovery
+* without switching on a backend.
+*/
+var QuestionAnswerError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "QuestionAnswerError";
+		this.code = code;
+	}
+};
+/** Wrap an unknown failure from the late-answer path in the port vocabulary. */
+function questionAnswerError(error) {
+	if (error instanceof QuestionAnswerError) return error;
+	return new QuestionAnswerError(typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : "question/answer-failed", typeof error === "object" && error !== null && typeof error.message === "string" ? error.message : String(error), { cause: error });
+}
+//#endregion
+//#region src/runtime/direct/file-completion/host-discovery.ts
+/**
+* The Direct Host discovery implementation (TS8-A, renamed by TS8-HF1): the
+* DIRECT process's filesystem behind the neutral {@link LocalDiscoveryDriver}
+* contract. It has two legitimate consumers:
+*
+* ```text
+* 1. the sessionless `HostFileScope { kind: 'workspace', cwd }` compatibility
+*    path of `DirectHostFilePort` (the cold surface with no official carrier);
+* 2. the explicit-path `@` navigation route of the Session scope
+*    (`runtime/direct/host-file-augmentation-direct.ts`), where the user
+*    explicitly typed the scope (`@src/`, `@../`, `@/abs`, `@~/`).
+* ```
+*
+* A BARE Session `@` query (`@foo`) never runs through this adapter — that
+* path is the OFFICIAL Host authority's (`ctx.fileReferences.list` through the
+* port), whose candidates arrive already filtered, ranked and bounded.
+*
+* It owns the Direct Host process's own PATH/PATHEXT finder detection, its
+* `node:fs` facts and its fd/fdfind process. The small syscall-level
+* duplication against `client/file-completion/local-discovery.ts` is
+* deliberate: the two adapters read DIFFERENT machines under Remote, and one
+* concrete source owner for both localities is exactly what TS8-A removes.
+* @module @xmoon76/dsh-pi-tui/runtime/direct/file-completion/host-discovery
+*/
+/**
+* The Direct Host process's explicit path-query environment facts. Under
+* Remote these are the HOST machine's facts, never the Client's; today Direct
+* runs in-process, so the numbers coincide — that coincidence is deliberately
+* not encoded in the domain contract.
+*/
+function hostPathQueryEnvironment() {
+	return {
+		homeDir: homedir(),
+		windowsHost: process.platform === "win32"
+	};
+}
+/**
+* Locate an executable file-finder on the Direct Host process's PATH: `fd`
+* preferred, `fdfind` second. See the Client adapter for the probe contract.
+*/
+function resolveFdPath() {
+	const pathEntries = process.env.PATH?.split(delimiter) ?? [];
+	const suffixes = (process.env.PATHEXT || (process.platform === "win32" ? ".COM;.EXE;.BAT;.CMD" : "")).split(";").map((suffix) => suffix.trim()).filter((suffix) => suffix !== "").flatMap((suffix) => suffix.toLowerCase() === suffix ? [suffix] : [suffix, suffix.toLowerCase()]);
+	for (const name of ["fd", "fdfind"]) for (const entry of pathEntries) {
+		const dir = entry === "" ? "." : entry;
+		for (const suffix of ["", ...suffixes]) {
+			const candidate = join(dir, `${name}${suffix}`);
+			try {
+				if (statSync(candidate).isFile() && accessSync(candidate, constants.X_OK) === void 0) return candidate;
+			} catch {}
+		}
+	}
+	return null;
+}
+/** Join a Host path WITHOUT collapsing a `..` segment. The Host's filesystem
+* backend anchors a POSIX path containing a `..` segment with its physical
+* spelling (the kernel resolves an intermediate symlink before the parent step),
+* so a search base that deliberately keeps that traversal may not be lexically
+* re-normalized on the way to a syscall. For every base the neutral resolver
+* already normalized (no `..` left) this is identical to `path.join`. */
+function hostJoin(baseDir, relative) {
+	if (relative === "") return baseDir;
+	return baseDir.endsWith("/") ? `${baseDir}${relative}` : `${baseDir}/${relative}`;
+}
+/** Whether one Dirent is a directory (symlinks followed; a broken link is a
+* file candidate — the fork's rule). */
+function entryIsDirectory(baseDir, name, entry) {
+	if (entry.isDirectory()) return true;
+	if (entry.isSymbolicLink()) try {
+		return statSync(hostJoin(baseDir, name)).isDirectory();
+	} catch {
+		return false;
+	}
+	return false;
+}
+/** Run the Direct Host finder for one scoped query. Returns NULL on finder
+* FAILURE (the neutral policy then runs the bounded fallback), `[]` on a
+* genuine no-match or an abort. */
+function runHostFinder(fdPath, baseDir, term, signal) {
+	const args = [
+		"--base-directory",
+		baseDir,
+		"--max-results",
+		String(100),
+		"-i",
+		"--full-path",
+		"--print0",
+		"--type",
+		"f",
+		"--type",
+		"d",
+		"--type",
+		"l",
+		"--hidden",
+		"--exclude",
+		".git",
+		"--exclude",
+		".git/*",
+		"--exclude",
+		".git/**"
+	];
+	if (term !== "") args.push(escapeFinderRegex(term));
+	return new Promise((resolve) => {
+		if (signal.aborted) {
+			resolve([]);
+			return;
+		}
+		let child;
+		try {
+			child = spawn(fdPath, args, { stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			] });
+		} catch {
+			resolve(null);
+			return;
+		}
+		let stdout = "";
+		let settled = false;
+		const settle = (results) => {
+			if (settled) return;
+			settled = true;
+			signal.removeEventListener("abort", onAbort);
+			resolve(results);
+		};
+		const onAbort = () => {
+			if (child.exitCode === null) child.kill("SIGKILL");
+			settle([]);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		child.stdout.setEncoding("utf-8");
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.on("error", () => settle(null));
+		child.on("close", (code) => {
+			if (signal.aborted) {
+				settle([]);
+				return;
+			}
+			if (code !== 0) {
+				settle(null);
+				return;
+			}
+			const results = [];
+			for (const record of normalizeFinderRecords(stdout)) {
+				let isDirectory = record.directoryHint;
+				if (!isDirectory) try {
+					isDirectory = statSync(hostJoin(baseDir, record.path)).isDirectory();
+				} catch {
+					isDirectory = false;
+				}
+				results.push({
+					path: record.path,
+					kind: isDirectory ? "directory" : "file"
+				});
+			}
+			settle(results);
+		});
+	});
+}
+/**
+* The Direct Host discovery driver: the Direct Host process's OWN filesystem,
+* with a Host PATH finder when present.
+*
+* `fdPath` is a test/API pin: `undefined` probes the Host PATH, `null` FORCES
+* the bounded fallback (no finder), a string pins one finder.
+*/
+var DirectHostDiscoveryDriver = class {
+	fdPathValue;
+	constructor(fdPath = void 0) {
+		this.fdPathValue = fdPath === void 0 ? resolveFdPath() : fdPath;
+	}
+	/** The pinned/detected Host finder (null = bounded-fallback only). */
+	get fdPath() {
+		return this.fdPathValue;
+	}
+	async listDirectory(baseDir, relativeDir, signal) {
+		if (signal.aborted) return null;
+		let entries;
+		try {
+			entries = readdirSync(hostJoin(baseDir, relativeDir), { withFileTypes: true });
+		} catch {
+			return null;
+		}
+		if (signal.aborted) return null;
+		const dir = hostJoin(baseDir, relativeDir);
+		return entries.map((entry) => ({
+			name: entry.name,
+			kind: entryIsDirectory(dir, entry.name, entry) ? "directory" : "file",
+			descendable: entry.isDirectory() && !entry.isSymbolicLink()
+		}));
+	}
+	async find(baseDir, term, signal) {
+		if (this.fdPathValue === null) return null;
+		return runHostFinder(this.fdPathValue, baseDir, term, signal);
+	}
+};
+//#endregion
+//#region src/runtime/direct/host-file-augmentation-direct.ts
+/**
+* The session `@`-reference Host router (TS8-HF1): ONE Host-side authority
+* that answers a completion query with the routing boundary
+*
+* ```text
+* bare workspace fuzzy search          -> official ctx.fileReferences.list
+*   @foo @readme @src @.env               (workspace index, cache, exclusions,
+*                                         scoring, maxResults stay authoritative)
+*
+* explicit path navigation             -> dsh-pi-tui Host scoped discovery
+*   @src/ @src/uti @./ @../shared/foo      (the exact scope the user typed:
+*   @../../foo @/tmp/foo @~/Down           recursive fuzzy inside it, explicit
+*   Windows drive @C:/work/foo and UNC     parent/absolute/native paths)
+* ```
+*
+* The decision is the TOKEN's explicit path navigation, never the resolved
+* search base's workspace containment (the superseded v1 rule): a user-typed
+* separator, a root form (`.`/`..`/`~`) or a Windows absolute path is what
+* selects the scoped route, so `@dist/` and `@link/foo` address their
+* explicitly named scope even when the official provider would exclude or not
+* traverse it.
+*
+* POSIX BOUNDARY: on a POSIX Host a backslash is an ordinary FILENAME character,
+* but the reused TS8-A path resolver selects its Windows dialect from the token
+* alone and normalizes the separators (a pinned cross-dialect contract of the
+* Client-local completion — `test/domain-file-completion.test.ts`). The
+* augmentation therefore does NOT CLAIM an ambiguous POSIX token that contains a
+* backslash: such a token is left to the official provider rather than searched
+* in a scope we cannot represent verbatim. This is a deliberate fail-closed
+* narrowing, not a claim that the token is a bare fuzzy query; delete the guard
+* once the shared resolver distinguishes host dialect, token dialect and literal
+* backslashes.
+*
+* PARENT-TRAVERSAL SPELLING: a relative scope is searched with the SAME spelling
+* the Host's local filesystem backend gives the accepted value. On a POSIX Host a
+* path containing a `..` segment is anchored with its PHYSICAL spelling by
+* `dsh-fs-local` (kernel resolves an intermediate symlink before the parent step);
+* the scoped search therefore keeps the raw `<cwd>/<displayBase>` concatenation for
+* those queries instead of the lexically joined directory, so completion and the
+* model's read can never land in two different physical directories. Windows, the
+* absolute forms (already verbatim) and the home shorthand (absolute normalized
+* value) keep the shared resolver's spelling.
+*
+* The official provider is called ONLY on the bare route; an authoritative
+* official `[]` stays empty and never falls back to the scanner. The scoped
+* route never calls the official provider and needs no capability from it.
+*
+* Home shorthand (`@~`, `@~/Down`) is dsh-pi-tui INPUT syntax: discovery runs
+* against the Host HOME, but every returned candidate is materialized as an
+* ABSOLUTE Host path — DSH path resolution performs no shell-style `~`
+* expansion, so a literal `~/...` completion value would be unusable. Ranking
+* always scores the SCOPE-RELATIVE candidate, never the materialized absolute
+* path (the home prefix itself must not satisfy the path-substring tier).
+*
+* This authority receives HOST facts only (the live Agent, the Host discovery
+* driver, the Host path environment); it never reads the Client cwd, home or
+* platform.
+*
+* TODO(upstream-file-reference-explicit-scope): Delete the pi-tui
+* explicit-scope augmentation when the minimum supported DSH fileReferences
+* provider supports equivalent explicit scoped recursive search,
+* parent/absolute Host path navigation, explicit excluded/symlink scope
+* access, and a Host-home-safe completion representation.
+*
+* @module @xmoon76/dsh-pi-tui/runtime/direct/host-file-augmentation-direct
+*/
+/** Whether the token names an EXPLICIT path scope (the frozen classifier,
+* decided from the raw token and the HOST platform — never from filesystem
+* existence, official result count, or workspace containment).
+*
+* A POSIX host has ONE separator: any `/` is an explicit scope, and the root
+* forms are explicit. A token that also contains a backslash is deliberately NOT
+* claimed (see the module comment): the reused resolver cannot represent its
+* literal POSIX scope, so the official provider keeps it.
+*
+* A Windows host treats `\` as a separator as well and accepts any
+* win32-absolute form (drive/UNC) even before its first separator is visible. */
+function isExplicitPathNavigation(raw, environment) {
+	if (raw === "") return false;
+	if (environment.windowsHost) return raw === "." || raw === ".." || raw === "~" || raw.includes("/") || raw.includes("\\") || win32.isAbsolute(raw);
+	if (raw.includes("\\")) return false;
+	return raw === "." || raw === ".." || raw === "~" || raw.includes("/");
+}
+/** Whether the token is a leading-home form (`~`, `~/x`, `~\x`). */
+function isHomeToken(raw) {
+	return raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\");
+}
+/** Materialize one candidate discovered under a HOME scope as an ABSOLUTE Host
+* path (the `~` shorthand must never reach the prompt as literal text). */
+function materializeHostPath(candidate, searchBase, windowsHost) {
+	return {
+		path: (windowsHost ? win32 : posix).join(searchBase, candidate.path),
+		kind: candidate.kind
+	};
+}
+/** One `..` path SEGMENT — the exact shape the Host filesystem backend keys its
+* physical-spelling rule on (`dsh-fs-local`'s `localDisplayPath`). */
+const PARENT_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/u;
+/**
+* The directory one explicit scope searches.
+*
+* The Host's local filesystem backend anchors a POSIX path that contains a `..`
+* SEGMENT with its PHYSICAL spelling (the raw `<anchor>/<path>`, deliberately
+* unnormalized), so the kernel resolves an intermediate symlink BEFORE the parent
+* step; every other spelling goes through a lexical `resolve(anchor, path)`, and
+* Windows always resolves lexically. Two consequences drive this function:
+*
+* 1. The anchor is `<hostCwd>` for a relative scope and the value itself for an
+*    absolute one, and the rule tests the WHOLE anchored spelling — so a `..`
+*    carried by the SESSION CWD flips it just like one in the typed scope. The
+*    consumer applies that rule to the value we hand it (`displayBase + name`), so
+*    the search must use the same spelling; otherwise the completion could offer a
+*    path the model's read resolves into a DIFFERENT physical directory.
+* 2. A home shorthand emits an ABSOLUTE value through `path.join`, which normalizes
+*    lexically. Its scope must be normalized the same way: the bare `~`/`~/` root
+*    form is the one form whose search base is the raw `homedir()` string, so a
+*    `..`-bearing HOME would otherwise be searched physically while the value we
+*    emit names the lexical directory.
+*
+* Absolute forms already spell their traversal verbatim. This is one segment test
+* plus one concatenation (plus one lexical normalize for the home root form) — the
+* consumer's own rule applied to the value we are about to hand it, not a second
+* path parser.
+*/
+function scopeSearchBase(resolved, raw, hostCwd, environment) {
+	const api = environment.windowsHost ? win32 : posix;
+	if (isHomeToken(raw)) return api.normalize(resolved.searchBase);
+	if (environment.windowsHost) return resolved.searchBase;
+	if (raw.startsWith("/") || resolved.winAbsolute) return resolved.searchBase;
+	const physicalScope = `${hostCwd}/${resolved.displayBase}`;
+	return PARENT_SEGMENT.test(physicalScope) ? physicalScope : resolved.searchBase;
+}
+/**
+* Answer one session `@` completion query over the Host facts.
+*
+* Cancellation (the caller's `signal`) outranks every route: an aborted
+* request rejects at entry — before the route/capability decision — and again
+* after each await, so a cancelled scope never serves a late result and never
+* reports `unavailable`.
+*
+* @param agent - the live Agent the session scope resolved to.
+* @param query - the official query form (path text following `@`).
+* @param signal - caller cancellation.
+* @param deps - the Host facts this router answers with.
+*/
+async function listPiTuiHostFileReferences(agent, query, signal, deps) {
+	signal.throwIfAborted();
+	if (!isExplicitPathNavigation(query, deps.environment)) {
+		const official = deps.official;
+		if (official === void 0) return {
+			kind: "unavailable",
+			reason: "the official Host file-reference service is not mounted"
+		};
+		const candidates = await official.list(agent, query, signal);
+		signal.throwIfAborted();
+		return {
+			kind: "ok",
+			items: candidates.map((candidate) => ({
+				path: candidate.path,
+				kind: candidate.kind
+			}))
+		};
+	}
+	const workspaceCwd = agent.session.header.cwd ?? process.cwd();
+	const resolved = resolvePathQuery(query, workspaceCwd, deps.environment);
+	const searchBase = scopeSearchBase(resolved, query, workspaceCwd, deps.environment);
+	const discovered = await discoverForQuery(searchBase === resolved.searchBase ? resolved : {
+		...resolved,
+		searchBase
+	}, deps.driver, signal);
+	signal.throwIfAborted();
+	const homeToken = isHomeToken(query);
+	return {
+		kind: "ok",
+		items: rankPathCandidates(homeToken ? discovered : discovered.map((candidate) => reattachDisplayBase(candidate, resolved)), resolved.searchTerm).map((candidate) => homeToken ? materializeHostPath(candidate, resolved.searchBase, deps.environment.windowsHost) : {
+			path: candidate.path,
+			kind: candidate.kind
+		})
+	};
+}
+//#endregion
+//#region src/runtime/plugin-manager-mapping.ts
+/** Generate one install request id (the branded shape is a plain string). */
+function pluginInstallRequestId(value) {
+	return value;
+}
+/** Resolve one official localized text to the English fallback. */
+function localizedText(value) {
+	if (value === void 0) return void 0;
+	return typeof value === "string" ? value : value.en;
+}
+function detachIncompatible(entry) {
+	return Object.freeze({
+		name: entry.name,
+		version: entry.version,
+		runtimeVersion: entry.runtimeVersion,
+		peers: Object.freeze({ ...entry.peers })
+	});
+}
+function detachError(error) {
+	if (error === void 0) return void 0;
+	return Object.freeze({
+		code: error.code,
+		...error.diagnostic === void 0 ? {} : { diagnostic: error.diagnostic },
+		...error.incompatible === void 0 ? {} : { incompatible: Object.freeze(error.incompatible.map(detachIncompatible)) }
+	});
+}
+function pickMeta(meta) {
+	const title = localizedText(meta.title);
+	const description = localizedText(meta.description);
+	return {
+		...title === void 0 ? {} : { title },
+		...description === void 0 ? {} : { description }
+	};
+}
+function detachBundle(bundle) {
+	const rows = bundle.rows.map((row) => Object.freeze({
+		rowId: row.rowId,
+		moduleName: row.moduleName,
+		...row.meta === void 0 ? {} : pickMeta(row.meta),
+		...row.entryId === void 0 ? {} : { entryId: String(row.entryId) }
+	}));
+	return Object.freeze({
+		name: bundle.name,
+		...bundle.version === void 0 ? {} : { version: bundle.version },
+		...bundle.meta === void 0 ? {} : pickMeta(bundle.meta),
+		...bundle.description === void 0 ? {} : { description: bundle.description },
+		enabled: bundle.enabled,
+		installed: bundle.installed,
+		optional: bundle.optional,
+		removable: bundle.removable,
+		...bundle.readOnlyReason === void 0 ? {} : { readOnlyReason: bundle.readOnlyReason },
+		...bundle.error === void 0 ? {} : { error: detachError(bundle.error) },
+		rows: Object.freeze(rows),
+		overrides: Object.freeze([...bundle.overrides])
+	});
+}
+function detachPlugin(entry) {
+	const addressable = "patchId" in entry;
+	return Object.freeze({
+		entryId: String(entry.entryId),
+		moduleName: entry.moduleName,
+		...entry.meta === void 0 ? {} : pickMeta(entry.meta),
+		enabled: entry.enabled,
+		fiberPhase: entry.fiberPhase,
+		...addressable ? { patchId: entry.patchId } : { readOnlyReason: entry.readOnlyReason }
+	});
+}
+function detachRegistries(registries) {
+	return Object.freeze({
+		registry: registries.registry,
+		fallbackRegistries: Object.freeze([...registries.fallbackRegistries]),
+		resolved: registries.resolved
+	});
+}
+function detachExemptions(value) {
+	return Object.freeze(Object.entries(value.exemptions).map(([packageVersion, runtimeVersions]) => Object.freeze({
+		packageVersion,
+		runtimeVersions: Object.freeze([...runtimeVersions])
+	})));
+}
+/** Map one complete snapshot read onto the detached surface facts. */
+function detachPluginManagerSnapshot(input) {
+	return Object.freeze({
+		bundles: Object.freeze(input.bundles.map(detachBundle)),
+		plugins: Object.freeze(input.plugins.map(detachPlugin)),
+		registries: detachRegistries(input.registries),
+		exemptions: detachExemptions(input.exemptions),
+		exemptionWarnings: Object.freeze([...input.exemptions.warnings])
+	});
+}
+/** Map one persisted change and its observed application outcome. */
+function detachChange(result) {
+	return Object.freeze({
+		changed: result.changed,
+		application: result.application,
+		stage: result.stage,
+		target: result.target,
+		...result.error === void 0 ? {} : { error: detachError(result.error) },
+		...result.warnings === void 0 ? {} : { warnings: Object.freeze([...result.warnings]) },
+		...result.bundle === void 0 ? {} : { bundle: result.bundle }
+	});
+}
+/** Map what a spec names before installation. */
+function detachInspection(inspection) {
+	if (inspection.status === "accepted") return Object.freeze({
+		status: "accepted",
+		kind: inspection.kind,
+		...inspection.name === void 0 ? {} : { name: inspection.name },
+		...inspection.version === void 0 ? {} : { version: inspection.version },
+		...inspection.description === void 0 ? {} : { description: inspection.description },
+		bundle: inspection.bundle,
+		registry: inspection.registry,
+		...inspection.host === void 0 ? {} : { host: inspection.host }
+	});
+	return Object.freeze({
+		status: "refused",
+		problem: inspection.problem,
+		reason: inspection.reason,
+		...inspection.registries === void 0 ? {} : { registries: Object.freeze([...inspection.registries]) }
+	});
+}
+/** Map one official install-phase announcement. */
+function detachPhase(progress) {
+	return Object.freeze({
+		requestId: String(progress.requestId),
+		phase: progress.phase,
+		...progress.attempt === void 0 ? {} : { attempt: Object.freeze({
+			registry: progress.attempt.registry,
+			index: progress.attempt.index,
+			total: progress.attempt.total
+		}) }
+	});
+}
+/** Map one pnpm output chunk. */
+function detachLog(chunk) {
+	return Object.freeze({
+		...chunk.requestId === void 0 ? {} : { requestId: String(chunk.requestId) },
+		jobId: chunk.jobId,
+		stream: chunk.stream,
+		text: chunk.text
+	});
+}
+//#endregion
+//#region src/domain/terminal-progress/interval.ts
+/**
+* Classify one official `turn/end.reason.kind` (plan §5.2). `completed` is the
+* DSH turn result (not a claim about every business step); `error` and
+* `max-tokens` (a resource ceiling, not success) are `error`; a cancelled /
+* blocked / non-live closer is honestly `idle`. An UNKNOWN upstream kind is
+* NOT guessed — the caller records it and the interval stays `idle`.
+*
+* @param kind - the durable `turn/end` reason kind.
+* @returns the proven outcome, or `undefined` for an unknown kind.
+*/
+function classifyTerminalTurnEnd(kind) {
+	switch (kind) {
+		case "completed": return "done";
+		case "error": return "error";
+		case "max-tokens": return "error";
+		case "aborted":
+		case "blocked":
+		case "interrupted":
+		case "forked": return "idle";
+		default: return;
+	}
+}
+/**
+* Create one independent fold instance.
+* @param onUnknownReason - reports an unknown `turn/end.reason.kind` (the
+* Host/Direct owner injects its diagnostics channel here); the interval stays
+* `idle` instead of guessing.
+*/
+function createTerminalProgressInterval(onUnknownReason) {
+	let active = false;
+	/** The turn opened by the newest live `turn/start` of THIS interval. */
+	let openTurn;
+	/** The classified outcome of the newest turn whose `turn/end` matched the
+	*  open turn — reset whenever a newer turn opens. */
+	let lastClosed;
+	/** The currently committed outcome of the interval (`idle` while running
+	*  without a proven result). */
+	let outcome = "idle";
+	const state = () => ({
+		active,
+		outcome
+	});
+	return {
+		status(running) {
+			if (running) {
+				if (active) return void 0;
+				active = true;
+				openTurn = void 0;
+				lastClosed = void 0;
+				outcome = "idle";
+				return state();
+			}
+			if (!active) return void 0;
+			outcome = openTurn === void 0 ? lastClosed ?? "idle" : "idle";
+			active = false;
+			openTurn = void 0;
+			lastClosed = void 0;
+			return state();
+		},
+		turnStart(turn) {
+			if (!active) return;
+			openTurn = turn;
+			lastClosed = void 0;
+		},
+		turnEnd(turn, reasonKind) {
+			if (!active) return;
+			if (openTurn !== turn) return;
+			openTurn = void 0;
+			const classified = classifyTerminalTurnEnd(reasonKind);
+			if (classified === void 0) {
+				onUnknownReason?.(reasonKind);
+				lastClosed = "idle";
+				return;
+			}
+			lastClosed = classified;
+		},
+		retire() {
+			openTurn = void 0;
+			lastClosed = void 0;
+			if (!active && outcome === "idle") return void 0;
+			active = false;
+			return state();
+		},
+		apply(fact) {
+			active = fact.active;
+			outcome = fact.outcome;
+			openTurn = void 0;
+			lastClosed = void 0;
+			return state();
+		},
+		reset() {
+			active = false;
+			openTurn = void 0;
+			lastClosed = void 0;
+			outcome = "idle";
+			return state();
+		},
+		snapshot() {
+			return state();
+		}
+	};
+}
+//#endregion
+//#region src/runtime/remote/pi-tui-terminal-progress-contract.ts
+/** The wire namespace (and Host Cordis service key) of the private stream. */
+const PI_TUI_TERMINAL_PROGRESS_NAMESPACE = "piTuiTerminalProgress";
+/** The private method's stable endpoint identity. */
+const PI_TUI_TERMINAL_PROGRESS_WATCH_ENDPOINT = "@xmoon76/dsh-pi-tui#piTuiTerminalProgress/watch";
+/** One strict JSON codec that validates a wire string. */
+function stringCodec(typeSymbol) {
+	return {
+		mode: "strict",
+		typeSymbol,
+		create: () => ({ parse: (value) => {
+			if (typeof value !== "string") throw new TypeError(`${typeSymbol}: the wire value must be a string`);
+			return value;
+		} })
+	};
+}
+/**
+* Validate and detach one `PiTuiTerminalProgressFrame`. This is the ONE
+* structural validator of the frame shape: the descriptor's `result` codec
+* uses it, and the R2 Client source must call it on every downlink item because
+* the framework does not (see the module JSDoc).
+*/
+function parsePiTuiTerminalProgressFrame(value) {
+	if (typeof value !== "object" || value === null) throw new TypeError("piTuiTerminalProgress/watch: the frame must be an object");
+	const frame = value;
+	if (frame.kind !== "snapshot" && frame.kind !== "update") throw new TypeError("piTuiTerminalProgress/watch: the frame kind must be snapshot or update");
+	if (typeof frame.sessionId !== "string") throw new TypeError("piTuiTerminalProgress/watch: the frame needs a string sessionId");
+	if (typeof frame.hostEpoch !== "string") throw new TypeError("piTuiTerminalProgress/watch: the frame needs a string hostEpoch");
+	if (typeof frame.agentEpoch !== "number") throw new TypeError("piTuiTerminalProgress/watch: the frame needs a numeric agentEpoch");
+	if (typeof frame.revision !== "number") throw new TypeError("piTuiTerminalProgress/watch: the frame needs a numeric revision");
+	if (typeof frame.running !== "boolean") throw new TypeError("piTuiTerminalProgress/watch: the frame needs a boolean running");
+	if (frame.outcome !== "idle" && frame.outcome !== "done" && frame.outcome !== "error") throw new TypeError("piTuiTerminalProgress/watch: the frame outcome must be idle, done or error");
+	return {
+		kind: frame.kind,
+		sessionId: frame.sessionId,
+		hostEpoch: frame.hostEpoch,
+		agentEpoch: frame.agentEpoch,
+		revision: frame.revision,
+		running: frame.running,
+		outcome: frame.outcome
+	};
+}
+const PI_TUI_TERMINAL_PROGRESS_FRAME_CODEC = {
+	mode: "strict",
+	typeSymbol: "@xmoon76/dsh-pi-tui#piTuiTerminalProgress/watch:frame",
+	create: () => ({ parse: parsePiTuiTerminalProgressFrame }),
+	decode: parsePiTuiTerminalProgressFrame
+};
+/**
+* The ONE shared invocation descriptor both contributions derive from. The
+* Host registers this exact object; the Client mounts this exact object.
+*/
+const PI_TUI_TERMINAL_PROGRESS_WATCH = {
+	id: PI_TUI_TERMINAL_PROGRESS_WATCH_ENDPOINT,
+	service: PI_TUI_TERMINAL_PROGRESS_NAMESPACE,
+	namespace: PI_TUI_TERMINAL_PROGRESS_NAMESPACE,
+	method: "watch",
+	mode: "stream",
+	invocation: { kind: "direct" },
+	parameters: [{
+		name: "sessionId",
+		wire: "sessionId",
+		source: "json",
+		codec: stringCodec("@xmoon76/dsh-pi-tui#piTuiTerminalProgress/watch:sessionId")
+	}],
+	cancellation: { parameter: "signal" },
+	result: PI_TUI_TERMINAL_PROGRESS_FRAME_CODEC
+};
+//#endregion
+//#region src/app/remote/terminal-progress-source.ts
+/** Consecutive frame-less watch endings tolerated before failing closed. */
+const EMPTY_WATCH_REOPEN_LIMIT = 3;
+/**
+* Consume the ONE Remote progress watch of one session for as long as the caller
+* stays current, re-establishing it whenever the Host retires it.
+*
+* @param source - the Remote progress source.
+* @param sessionId - the main session this authority belongs to.
+* @param signal - the caller's lifetime; aborting it stops the consumption at
+* the next fact and before any re-open.
+* @param consumer - the currentness fence and the fact sink.
+* @throws when the Host keeps ending the watch without ever delivering a frame.
+*/
+async function consumeRemoteTerminalProgress(source, sessionId, signal, consumer) {
+	let emptyReopens = 0;
+	for (;;) {
+		let frames = 0;
+		try {
+			for await (const fact of source.open(sessionId, signal)) {
+				if (signal.aborted || !consumer.isCurrent()) return;
+				frames += 1;
+				consumer.onFact(fact);
+			}
+		} catch (error) {
+			if (signal.aborted) return;
+			throw error;
+		}
+		if (signal.aborted || !consumer.isCurrent()) return;
+		if (frames === 0) {
+			emptyReopens += 1;
+			if (emptyReopens > EMPTY_WATCH_REOPEN_LIMIT) throw new Error(`the Remote terminal-progress watch of ${sessionId} ended without a frame ${String(emptyReopens)} times`);
+		} else emptyReopens = 0;
+	}
+}
+/**
+* Assemble the source over the ONE Remote Client graph. It constructs no
+* Client and owns no subscription of its own; the provenance of an accepted
+* frame lives only for the watch that observed it (see {@link createRemoteTerminalProgressSource}).
+*/
+function createRemoteTerminalProgressSource(deps) {
+	/**
+	* Judge one frame against the provenance of THIS watch.
+	*
+	* @param previous - the last frame accepted by this watch, or `undefined`
+	* before its opening baseline. It deliberately never crosses watches: a
+	* settled `done`/`error` belongs to the interval ONE watch observed, so a new
+	* watch (a reconnect, a re-adopted session, a re-retained binding, another TUI
+	* owner) opens on the Host's current `running` truth and `idle` — the plan's
+	* "a new binding default to idle" — instead of inheriting a result it cannot
+	* prove.
+	* @param opened - whether this watch already delivered its opening baseline.
+	* @returns the fact to publish, or `undefined` for a frame that must be dropped.
+	* @throws when the stream cannot be interpreted at all.
+	*/
+	const acceptFrame = (frame, sessionId, opened, previous) => {
+		if (!opened) {
+			if (frame.kind !== "snapshot") throw new Error(`the Remote terminal-progress stream of ${sessionId} did not open with a snapshot`);
+			return {
+				kind: "snapshot",
+				restart: true,
+				running: frame.running,
+				outcome: "idle"
+			};
+		}
+		if (previous !== void 0 && frame.revision < previous.revision) throw new Error(`the Remote terminal-progress stream of ${sessionId} moved its revision backwards`);
+		if (frame.kind === "snapshot") return {
+			kind: "snapshot",
+			restart: true,
+			running: frame.running,
+			outcome: "idle"
+		};
+		if (previous === void 0) return void 0;
+		if (frame.hostEpoch !== previous.hostEpoch) return;
+		if (frame.agentEpoch < previous.agentEpoch) return void 0;
+		if (frame.revision <= previous.revision) return void 0;
+		return {
+			kind: "update",
+			restart: frame.agentEpoch > previous.agentEpoch,
+			running: frame.running,
+			outcome: frame.outcome
+		};
+	};
+	return { async *open(sessionId, signal) {
+		const capturedGeneration = deps.generation.getSnapshot();
+		const capturedBinding = deps.binding(sessionId);
+		if (capturedGeneration === void 0 || capturedBinding === void 0) throw new Error(`the Remote terminal-progress watch of ${sessionId} has no retained Session binding`);
+		const handle = deps.remote.piTuiTerminalProgress.watch(sessionId, signal);
+		try {
+			let opened = false;
+			/** This watch's own provenance: it dies with the watch. */
+			let accepted;
+			for await (const item of handle) {
+				if (signal.aborted) return;
+				if (!Object.is(capturedGeneration, deps.generation.getSnapshot()) || deps.binding(sessionId) !== capturedBinding) throw new Error(`the Remote terminal-progress watch of ${sessionId} lost its transport identity`);
+				const frame = parsePiTuiTerminalProgressFrame(item);
+				if (frame.sessionId !== sessionId) throw new Error(`the Remote terminal-progress stream of ${sessionId} delivered a frame of ${frame.sessionId}`);
+				const fact = acceptFrame(frame, sessionId, opened, accepted);
+				if (fact === void 0) continue;
+				opened = true;
+				accepted = {
+					hostEpoch: frame.hostEpoch,
+					agentEpoch: frame.agentEpoch,
+					revision: frame.revision
+				};
+				yield fact;
+			}
+		} finally {
+			handle.dispose();
+		}
+	} };
+}
+//#endregion
+export { effectiveCustomCommandRefreshMs as $, directAgentOf as A, SupersededReadError as B, safeSubagentErrorMessage as C, REMOTE_IMPLEMENTED_CAPABILITIES as D, DIRECT_IMPLEMENTED_CAPABILITIES as E, ROUTE_PATTERN as F, discoverForQuery as G, reattachDisplayBase as H, credentialOptionsFor as I, DEFAULT_CUSTOM_COMMAND_REFRESH_MS as J, escapeFinderRegex as K, deriveKeyRef as L, requireCreated as M, requireOpened as N, LifecycleError as O, PROTOCOL_CHOICES as P, customItemName as Q, providerOptionsFor as R, classifySubagentPromptSettlement as S, isRemoteBusinessRefusalCode as T, resolvePathQuery as U, rankPathCandidates as V, separatorOfRaw as W, customCommandConfigOf as X, activeFooterItemIds as Y, customItemId as Z, QUESTION_REPLY_QUEUED as _, safeErrorString as _t, createTerminalProgressInterval as a, resolveTrustedFooterCommand as at, detachedSessionStatus as b, detachLog as c, resolveUserLayerFooterMode as ct, pluginInstallRequestId as d, cancellationError as dt, effectiveCustomCommandTimeoutMs as et, listPiTuiHostFileReferences as f, isCancellation as ft, QUESTION_BAD_ANSWER as g, safeErrorMessage as gt, resolveFdPath as h, runOwned as ht, PI_TUI_TERMINAL_PROGRESS_WATCH as i, parseFooterCommandConfig as it, ownerHandleOf as j, clientOwnerOf as k, detachPhase as l, MAX_COMMAND_TIMEOUT_MS as lt, hostPathQueryEnvironment as m, runDetached as mt, createRemoteTerminalProgressSource as n, parseFooterCustomItem as nt, detachChange as o, resolveUserCommandItemActivationIds as ot, DirectHostDiscoveryDriver as p, observeSettled as pt, normalizeFinderRecords as q, PI_TUI_TERMINAL_PROGRESS_NAMESPACE as r, parseFooterCustomItems as rt, detachInspection as s, resolveUserCommandItemFallbackActivationIds as st, consumeRemoteTerminalProgress as t, executableCommandItemIds as tt, detachPluginManagerSnapshot as u, contextPressureOccupancy as ut, QuestionAnswerError as v, GATEWAY_PRE_INVOCATION_CODES as w, detachedTurnOutline as x, questionAnswerError as y, resolveCredentialArg as z };