gentle-pi 4.2.0 → 4.4.0

package/lib/shell-sidebar-layout.ts

@@ -25,7 +25,7 @@ type LayoutRoot = Component & { [NODE]?: () => LayoutNode };
 type Host = TUI & { mode?: string; layoutRoot?: LayoutRoot };
 type SidebarCache = { revision: number };
 type RailHit = { key: string; component: Component; startY: number; height: number; width: number };
-type SectionCacheEntry = { component: Component; digest: string | undefined; revision: number; contentWidth: number; theme: ShellBarTheme; lines: string[] };
+type SectionCacheEntry = { component: Component; digest: string | undefined; revision: number; contentWidth: number; theme: ShellBarTheme; themeSignature: string; lines: string[] };
 type SidebarPresentation = { scrollTop: number; output: LayoutNode };
 type PreparedRail = {
 	revision: number;
@@ -35,6 +35,7 @@ type PreparedRail = {
 	cardStyle: CardStyle;
 	root: LayoutRoot;
 	theme: ShellBarTheme;
+	themeSignature: string;
 	parts: Array<[string, SidebarRail]>;
 	digests: Array<string | undefined>;
 	contentWidth: number;
@@ -74,6 +75,20 @@ function railDigest(rail: SidebarRail): string | undefined {
 	}
 }
 
+// Pi passes extensions one live theme proxy, so identity never changes on a
+// theme switch, and the switch only calls ui.invalidate(), which does not reach
+// the rail inside the layout tree. How the current theme paints a few roles is
+// what changes, so the memo keys on that: a digest-only section (Status,
+// Agents, Todos) would otherwise keep the previous theme's colors.
+const THEME_SIGNATURE_ROLES = ["accent", "border", "borderAccent", "muted", "dim", "text", "success", "warning", "error"];
+function themeSignature(theme: ShellBarTheme): string {
+	try {
+		return THEME_SIGNATURE_ROLES.map((role) => theme.fg(role, "·")).join("") + theme.bold("·");
+	} catch {
+		return "";
+	}
+}
+
 export const STATUS_OWNER = { HEADER: "header", BOTTOM: "bottom" } as const;
 export type StatusOwner = (typeof STATUS_OWNER)[keyof typeof STATUS_OWNER];
 export interface StatusOwnerInput {
@@ -217,9 +232,13 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 		}
 		const style = cardStyle();
 		const parts = [...state.parts.entries()];
+		// Digest closures read live session state, so they must be evaluated once
+		// per frame and stored for the next comparison (issue #1681): the sections
+		// loop below reuses this pass instead of calling each digest a second time.
 		const digests = parts.map(([, rail]) => railDigest(rail));
+		const signature = themeSignature(theme);
 		const unchanged = prepared?.revision === cache.revision &&
-			prepared.width === width && prepared.mode === host.mode && prepared.headerPlacement === headerPlacement() && prepared.cardStyle === style && prepared.root === root && prepared.theme === theme &&
+			prepared.width === width && prepared.mode === host.mode && prepared.headerPlacement === headerPlacement() && prepared.cardStyle === style && prepared.root === root && prepared.theme === theme && prepared.themeSignature === signature &&
 			prepared.parts.length === parts.length && prepared.parts.every(([key, part], index) => parts[index]?.[0] === key && parts[index]?.[1] === part) &&
 			prepared.digests.length === digests.length && prepared.digests.every((digest, index) => digest === digests[index]);
 		if (unchanged) {
@@ -228,6 +247,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 			return prepared.active;
 		}
 		try {
+			const digestByPart = new Map(parts.map(([key], index) => [key, digests[index]]));
 			// The header is a full-width sibling row, not a rail section: it reads
 			// the terminal width (minus the rail's right inset), never the
 			// 50-column rail's content width.
@@ -241,16 +261,16 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 					sectionCache.delete(key);
 					return { key, component, lines: [] as string[] };
 				}
-				const digest = railDigest(component);
+				const digest = digestByPart.get(key);
 				const existing = sectionCache.get(key);
-				const reusable = existing?.component === component && existing.contentWidth === contentWidth && existing.theme === theme &&
+				const reusable = existing?.component === component && existing.contentWidth === contentWidth && existing.theme === theme && existing.themeSignature === signature &&
 					(digest !== undefined ? existing.digest === digest : existing.digest === undefined && existing.revision === cache.revision);
 				const lines = reusable ? existing.lines : (() => {
 					const rendered = [...(component.render(contentWidth - RAIL_PADDING * 2) ?? [])];
 					while (rendered.length && rendered[rendered.length - 1]?.trim() === "") rendered.pop();
 					return rendered;
 				})();
-				sectionCache.set(key, { component, digest, revision: cache.revision, contentWidth, theme, lines });
+				sectionCache.set(key, { component, digest, revision: cache.revision, contentWidth, theme, themeSignature: signature, lines });
 				return { key, component, lines };
 			}).filter((section) => section.component !== undefined && section.lines.length > 0) as Array<{ key: string; component: Component; lines: string[] }>;
 			// The header carries the brand once it is active; the banner is the
@@ -276,7 +296,7 @@ export function installSidebar(tui: TUI, theme: ShellBarTheme, placement: () =>
 			// Height is owned by the native ScrollView, never by the transcript.
 			const active = railLines.length > 0 && railLines.every((line) => visibleWidth(line) <= contentWidth);
 			headerLines = headerActive && headerPlacement() === "top" ? preparedHeaderLines : [];
-			prepared = { revision: cache.revision, width, mode: host.mode, headerPlacement: headerPlacement(), cardStyle: style, root, theme, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
+			prepared = { revision: cache.revision, width, mode: host.mode, headerPlacement: headerPlacement(), cardStyle: style, root, theme, themeSignature: signature, parts, digests, contentWidth, active, lines: railLines, hits, headerLines, headerActive: headerLines.length > 0 };
 			state.active = active;
 			return active;
 		} catch {

package/lib/shell-todo.ts

@@ -90,6 +90,21 @@ export interface TodoRenderOptions {
 export const TODO_DETAILS_KEY = "gentleTodo";
 export const TODO_TOOL_NAME = "todo";
 export const TODO_GLYPH = "❀";
+/** Emitted on pi.events after each successful todo write; gentle-agents publishes it as session progress. */
+export const TODO_PROGRESS_EVENT = "gentle-pi:todo:progress";
+
+export interface TodoProgress {
+	sessionId: string;
+	done: number;
+	total: number;
+	/** Title of the first in-progress task, or null when none is in progress. */
+	current: string | null;
+}
+
+export function todoProgress(state: TodoState, sessionId: string): TodoProgress {
+	const current = state.tasks.find((task) => task.status === TODO_STATUS.IN_PROGRESS)?.title ?? null;
+	return { sessionId, done: countStatus(state, TODO_STATUS.DONE), total: state.tasks.length, current };
+}
 const STATUS_ALIASES: Record<string, TodoStatus> = {
 	completed: TODO_STATUS.DONE,
 	complete: TODO_STATUS.DONE,
@@ -261,13 +276,14 @@ export function replayTodo(entries: readonly unknown[]): TodoState {
 // gentle-shell#1367, #1662: the system prompt is a cached prefix for every
 // provider, so the block it carries is byte-stable for the whole session:
 // rules only, no task content and no counters. The current list travels as a
-// request-local message at the end of the conversation (todoStateMessage),
-// where a change costs only the tail of the request, never the prefix.
+// hidden transcript message appended when it changes (todoStateMessage,
+// gentle-shell#2195), so requests stay append-only and a change costs only
+// the tail of the conversation, never the prefix.
 const TODO_PROMPT_BLOCK = [
 	"## Todo list",
-	"Keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
+	"A small task (Task Size) uses no todo list: do it and report. For tracked or multi-step work, keep it current with the `todo` tool: mark a task in_progress before starting it, done right after finishing it, and rewrite the whole list with `write` whenever the plan changes. Update it before you end the turn.",
 	"A blocked task waits on something outside the list: do not work on it until its condition holds. When the plan changes, mark the tasks it made obsolete dropped instead of leaving them pending or marking them done.",
-	"While tasks stay open, the current list arrives as the last message of each request; it is not repeated here.",
+	"While tasks stay open, the current list arrives as a hidden conversation message whenever it changes; the latest one is current, and it is not repeated here.",
 ].join("\n");
 
 /** The byte-stable rules block appended to every system prompt. */
@@ -275,7 +291,10 @@ export function todoPromptBlock(): string {
 	return TODO_PROMPT_BLOCK;
 }
 
-/** The open-task snapshot delivered as a request-local message; undefined when nothing is open. */
+/** Persisted once an open list closes, so an earlier snapshot never reads as current work (#2195). */
+export const TODO_CLOSED_STATE = "Current todo list: no open tasks.";
+
+/** The open-task snapshot delivered as a hidden transcript message; undefined when nothing is open. */
 export function todoStateMessage(state: TodoState): string | undefined {
 	if (todoSummary(state).open === 0) return undefined;
 	const lines = state.tasks.map((task, index) => `${index + 1}. [${task.status}] ${task.title}${task.note ? ` — ${task.note}` : ""}`);

package/lib/shell-usage-view.ts

@@ -1,5 +1,6 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { renderUsagePanel, type ActiveProvider, type UsagePanelScope, type UsageSourceRegistry, type UsageStore, type UsageTheme } from "./shell-usage.ts";
+import type { GaugePaint } from "./shell-gauge.ts";
 import { paintHoverable } from "./shell-hover.ts";
 
 // Gentle Shell subscriptions overlay: a framed panel over the usage store.
@@ -16,6 +17,9 @@ export interface UsageViewDeps {
 	// provider the store holds; with it, exactly the targeted providers, in
 	// scope order, explaining the ones without data.
 	scope?(): UsagePanelScope | undefined;
+	// Optional: gauge-specific theme roles resolved from the installed theme
+	// source; without it the panel paints with the shared roles.
+	gauge?(): GaugePaint | undefined;
 	onRefresh(): Promise<void>;
 	onClose(): void;
 	requestRender(): void;
@@ -106,7 +110,7 @@ export class UsageView {
 		const inner = width - 2;
 		const title = this.refreshing ? REFRESHING : TITLE;
 		const top = theme.fg(FRAME_ROLE, "╭─ ") + theme.fg(TITLE_ROLE, title) + theme.fg(FRAME_ROLE, ` ${rule(inner - visibleWidth(title) - 3)}╮`);
-		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active(), this.deps.registry?.(), this.deps.scope?.()).map(
+		const body = renderUsagePanel(this.store.all(), theme, inner - 2, this.deps.now(), this.deps.active(), this.deps.registry?.(), this.deps.scope?.(), this.deps.gauge?.()).map(
 			(line) => `${theme.fg(FRAME_ROLE, "│")} ${fit(line, inner - 2)} ${theme.fg(FRAME_ROLE, "│")}`,
 		);
 		const hints = KEYS.map(([key, label]) => ({ key, label, text: `${key} ${label}`, action: (key === "r" ? "refresh" : "close") as HintAction }));

package/lib/shell-usage.ts

@@ -1,6 +1,6 @@
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { parseModelRef } from "./agents-config.ts";
-import { paintGauge } from "./shell-gauge.ts";
+import { paintGauge, type GaugePaint } from "./shell-gauge.ts";
 
 // Gentle Shell subscription usage: the rate-limit windows each connected
 // provider reports. Codex sends them as SSE headers and through its usage
@@ -514,16 +514,16 @@ export function accountIdFromToken(token: string): string | undefined {
 	}
 }
 
-function paintMeter(percent: number, cells: number, theme: UsageTheme): string {
-	return paintGauge(percent, theme, cells);
+function paintMeter(percent: number, cells: number, theme: UsageTheme, paint?: GaugePaint): string {
+	return paintGauge(percent, theme, cells, paint);
 }
 
-export function renderUsageBar(usage: ProviderUsage, theme: UsageTheme, activeModelId?: string): string | undefined {
+export function renderUsageBar(usage: ProviderUsage, theme: UsageTheme, activeModelId?: string, paint?: GaugePaint): string | undefined {
 	const main = selectUsageLimit(usage, activeModelId);
 	const [first, ...rest] = main?.windows ?? [];
 	if (!first) return undefined;
 	// An unlabeled window prints as the name, the meter and the percentage.
-	const head = [theme.fg(ROLE.LABEL, main.name), ...(first.label.length === 0 ? [] : [theme.fg(ROLE.LABEL, first.label)]), paintMeter(first.usedPercent, 8, theme), theme.fg(ROLE.PERCENT, `${Math.round(first.usedPercent)}%`)].join(" ");
+	const head = [theme.fg(ROLE.LABEL, main.name), ...(first.label.length === 0 ? [] : [theme.fg(ROLE.LABEL, first.label)]), paintMeter(first.usedPercent, 8, theme, paint), theme.fg(ROLE.PERCENT, `${Math.round(first.usedPercent)}%`)].join(" ");
 	const tail = rest.map((window) => `${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.LABEL, window.label)} ${theme.fg(ROLE.PERCENT, `${Math.round(window.usedPercent)}%`)}`);
 	return [head, ...tail].join(" ");
 }
@@ -574,7 +574,7 @@ export interface UsagePanelScope {
 // snapshot keeps that snapshot and says so beside it, and a provider recorded
 // under a previous profile's routing is never presented as current scope after
 // a profile switch.
-export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, width: number, now: number, active?: ActiveProvider, registry?: UsageSourceRegistry, scope?: UsagePanelScope): string[] {
+export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, width: number, now: number, active?: ActiveProvider, registry?: UsageSourceRegistry, scope?: UsagePanelScope, paint?: GaugePaint): string[] {
 	const activeUsage = active ? usages.find((usage) => usage.provider === active.provider) : undefined;
 	const byProvider = new Map(usages.map((usage) => [usage.provider, usage] as const));
 	const rows = scope
@@ -607,7 +607,7 @@ export function renderUsagePanel(usages: ProviderUsage[], theme: UsageTheme, wid
 			const percent = `${Math.round(row.window.usedPercent)}%`.padStart(4);
 			const reset = formatReset(row.window.resetAt, now);
 			const tail = reset.length > 0 ? ` ${theme.fg(ROLE.SEPARATOR, "·")} ${theme.fg(ROLE.RESET, reset)}` : "";
-			lines.push(`  ${theme.fg(ROLE.LABEL, row.name.padEnd(nameWidth))} ${paintMeter(row.window.usedPercent, PANEL_METER_CELLS, theme)} ${theme.fg(ROLE.PERCENT, percent)}${tail}`);
+			lines.push(`  ${theme.fg(ROLE.LABEL, row.name.padEnd(nameWidth))} ${paintMeter(row.window.usedPercent, PANEL_METER_CELLS, theme, paint)} ${theme.fg(ROLE.PERCENT, percent)}${tail}`);
 		}
 		// A failure after a good snapshot never hides either fact: the last good
 		// snapshot stays on its rows and the failed refresh says so beside it.

package/lib/verifier-admission.ts

@@ -0,0 +1,30 @@
+import { namesExistingFeatureDocumentTask } from "./bounded-writer-admission.ts";
+import { contextBackstopReached, type MeasuredContext } from "./context-backstop.ts";
+
+// odd/tasks/verifier-admission.md: the Verification rule reserves the independent verifier for a change that names a
+// Task Size high-risk item, yet a bench run still launched it on a small, not high-risk task. In the primary session a
+// verifier launch is admitted only when its task or context declares a named high-risk item, carries a task of an
+// existing feature document (the same lines writer admission accepts), or the parent's measured context reaches the
+// context backstop. The agent catalog has no generic verifier alias, so only `gentle-ai-verify` is gated.
+const VERIFIER_NAMES = ["gentle-ai-verify"];
+// A declaration that starts a line (optionally as a list item) or a sentence (after `.`, `!` or `?` and a space) with
+// `Risk:` whose first entry is `item N` with N in 1-6, for example `Risk: item 3 (shared parser)`, `- Risk: item 2,
+// item 3 (reason)` or `... on top of ebf3f35. Risk: item 1 (migration)`. `Risk: none` and a mention inside a
+// sentence ("Do not write Risk: item 3") do not start one.
+const HIGH_RISK_ITEM_LINE = /(?:^[ \t]*(?:[-*+][ \t]+)?|[.!?][ \t]+)Risk:[ \t]*item[ \t]+[1-6](?!\d)/m;
+export const VERIFIER_RISK_REJECTION =
+	"An independent verifier runs only for a change that declares a named high-risk item (`Risk: item N` from the Task Size list in the task). This change declares none: run its focused test and suite inline yourself now; do not retry the launch, and never add a Risk line or create a feature document only to get a verifier admitted.";
+
+export function rejectUnriskedVerifierLaunch(
+	input: unknown,
+	options: { root: string; contextUsage: MeasuredContext | undefined; env?: Readonly<Record<string, string | undefined>> },
+): { block: true; reason: string } | undefined {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+	const record = input as Record<string, unknown>;
+	if (typeof record.agent !== "string" || !VERIFIER_NAMES.includes(record.agent)) return undefined;
+	const values = [record.task, record.context];
+	if (values.some(value => typeof value === "string" && HIGH_RISK_ITEM_LINE.test(value))) return undefined;
+	if (namesExistingFeatureDocumentTask(values, options.root)) return undefined;
+	if (contextBackstopReached(options.contextUsage, options.env)) return undefined;
+	return { block: true, reason: VERIFIER_RISK_REJECTION };
+}

package/lib/vim-editor-adapter.ts

@@ -32,6 +32,8 @@ interface PrivateEditor {
   onChange?: (text: string) => void;
   pastes: Map<number, string>;
   pasteCounter: number;
+  /** Host-owned atomic spans (gentle-shell#2464 image chips) that NORMAL motions must not split. */
+  atomicSpans?(line: string): Array<{ start: number; end: number }>;
   undoStack: Stack;
   history: string[];
   historyIndex: number;
@@ -151,12 +153,13 @@ function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, righ
   return result;
 }
 
-function boundaries(line: string, pastes: Map<number, string>): number[] {
+function boundaries(line: string, editor: Pick<PrivateEditor, "pastes" | "atomicSpans">): number[] {
   const units = [...segmenter.segment(line)].map((part) => part.index);
-  for (const match of line.matchAll(marker)) {
-    if (!pastes.has(Number(match[1]))) continue;
-    const start = match.index;
-    const end = start + match[0].length;
+  const spans = [...line.matchAll(marker)]
+    .filter((match) => editor.pastes.has(Number(match[1])))
+    .map((match) => ({ start: match.index, end: match.index + match[0].length }));
+  if (typeof editor.atomicSpans === "function") spans.push(...editor.atomicSpans(line));
+  for (const { start, end } of spans) {
     for (let i = units.length - 1; i >= 0; i--) {
       if (units[i]! > start && units[i]! < end) units.splice(i, 1);
     }
@@ -177,7 +180,7 @@ function assertUniquePastes(editor: PrivateEditor): void {
 function assertPosition(editor: PrivateEditor, pos: Position): void {
   assertUniquePastes(editor);
   const line = editor.state.lines[pos.line];
-  if (line === undefined || !Number.isInteger(pos.col) || !boundaries(line, editor.pastes).includes(pos.col)) {
+  if (line === undefined || !Number.isInteger(pos.col) || !boundaries(line, editor).includes(pos.col)) {
     throw new Error("Cursor must be on a valid grapheme or paste boundary");
   }
 }
@@ -265,7 +268,7 @@ export function createVimEditorAdapter(value: unknown, version: string, editorCl
     },
     motionBoundaries(): number[][] {
       assertUniquePastes(editor);
-      return editor.state.lines.map((line) => boundaries(line, editor.pastes));
+      return editor.state.lines.map((line) => boundaries(line, editor));
     },
     move(pos: Position): void {
       assertPosition(editor, pos);
@@ -277,7 +280,7 @@ export function createVimEditorAdapter(value: unknown, version: string, editorCl
     moveByGraphemes(delta: number): void {
       if (!Number.isInteger(delta)) throw new Error("Invalid motion");
       const positions = editor.state.lines.flatMap((line, index) =>
-        boundaries(line, editor.pastes).map((col) => ({ line: index, col })));
+        boundaries(line, editor).map((col) => ({ line: index, col })));
       const current = editor.getCursor();
       const at = positions.findIndex((p) => p.line === current.line && p.col === current.col);
       if (at < 0) throw new Error("Invalid cursor boundary");

package/lib/voice-artifacts.ts

@@ -0,0 +1,188 @@
+// Pinned artifacts for the optional local voice dictation (S1-S3). Nothing here is
+// fetched or resolved at runtime: every version, size and digest below was read
+// from the public npm registry and Hugging Face metadata for the exact versions,
+// and the tarball layouts were inspected for the facts the comments state.
+// Installation lives in voice-install.ts; this module is data only.
+
+export type VoiceTarget = "darwin-x64" | "darwin-arm64" | "linux-x64" | "linux-arm64" | "win32-x64";
+
+export const VOICE_TARGETS: readonly VoiceTarget[] = ["darwin-x64", "darwin-arm64", "linux-x64", "linux-arm64", "win32-x64"];
+
+// A redirect hop is followed only when its URL is HTTPS on this origin and its
+// path starts with the prefix. Anything else ends the download.
+export interface VoiceRedirectRule {
+	origin: string;
+	pathPrefix: string;
+}
+
+export interface VoiceNpmPackage {
+	name: string;
+	version: string;
+	license: string;
+	tarball: string;
+	// The packed tarball size in bytes and its registry `dist.integrity`.
+	size: number;
+	integrity: string;
+	// Registry `dist.unpackedSize` and `dist.fileCount`: hard limits for extraction.
+	unpackedSize: number;
+	fileCount: number;
+	// Paths relative to the package root that must be present after extraction.
+	requiredFiles: string[];
+}
+
+export interface VoiceRuntimeManifest {
+	// The installed directory name; also part of the install marker.
+	id: string;
+	target: VoiceTarget;
+	packages: VoiceNpmPackage[];
+	redirects: VoiceRedirectRule[];
+}
+
+export interface VoiceModelFile {
+	name: string;
+	size: number;
+	sha256: string;
+}
+
+export interface VoiceModelManifest {
+	id: string;
+	revision: string;
+	// Files are fetched from `${baseUrl}/${name}`.
+	baseUrl: string;
+	files: VoiceModelFile[];
+	redirects: VoiceRedirectRule[];
+}
+
+const SHERPA_VERSION = "1.13.8";
+
+const npmTarball = (name: string, version: string) => `https://registry.npmjs.org/${name}/-/${name}-${version}.tgz`;
+
+// sherpa-onnx-node holds only JavaScript. Its addon-static-import.js loads
+// `../sherpa-onnx-<platform>-<arch>/sherpa-onnx.node` (Windows spelled `win`), so the
+// platform package must be installed as a sibling directory under node_modules.
+export const SHERPA_ONNX_NODE: VoiceNpmPackage = {
+	name: "sherpa-onnx-node",
+	version: SHERPA_VERSION,
+	license: "Apache-2.0",
+	tarball: npmTarball("sherpa-onnx-node", SHERPA_VERSION),
+	size: 11954,
+	integrity: "sha512-MsDMBdhLFTZ1GwvcGSSQhnS7g/EA8OMH6IYysCVUOM7j8Icty9KRc0E6YT1A5fWBsZwRfKOeh88QC95aRvS8ag==",
+	unpackedSize: 61221,
+	fileCount: 19,
+	requiredFiles: ["package.json", "sherpa-onnx.js", "addon.js", "addon-static-import.js", "non-streaming-asr.js"],
+};
+
+function sherpaPlatform(target: VoiceTarget, size: number, integrity: string, unpackedSize: number, fileCount: number): VoiceNpmPackage {
+	const name = `sherpa-onnx-${target.replace(/^win32-/, "win-")}`;
+	return {
+		name,
+		version: SHERPA_VERSION,
+		license: "Apache-2.0",
+		tarball: npmTarball(name, SHERPA_VERSION),
+		size,
+		integrity,
+		unpackedSize,
+		fileCount,
+		requiredFiles: ["package.json", "sherpa-onnx.node"],
+	};
+}
+
+// Each platform package bundles sherpa-onnx.node, the sherpa-onnx C/C++ API
+// libraries and onnxruntime, all built for the named architecture.
+export const SHERPA_ONNX_PLATFORM_PACKAGES: Readonly<Record<VoiceTarget, VoiceNpmPackage>> = {
+	"darwin-x64": sherpaPlatform("darwin-x64", 11191481, "sha512-7BLRpjM6w4f9W46/nmkmq8lEKUayhebvcpslCVQ+6QN2uReYlZEMDZlSpXMjme+hUFrPfRz8P3UNq8ep/4d19g==", 37678686, 7),
+	"darwin-arm64": sherpaPlatform("darwin-arm64", 10047754, "sha512-FPNgJMgnWVl/KhRTIhG3KL3A4Om63Rn4YKXc9/uHY7SzLcvqLJLc/h7UBWJwduXvv7K18t5NpxHR6XgXn4sjWw==", 34089738, 7),
+	"linux-x64": sherpaPlatform("linux-x64", 11089653, "sha512-6plnhjagsSeTntCgnlag86hWbs/uZE9Crms1LgOb68/1nKsIQjMd+WG519m+aPwT6TrsBOiEMzrx41t8sL5L5g==", 33381117, 7),
+	"linux-arm64": sherpaPlatform("linux-arm64", 13910679, "sha512-Tlg7a70b/Wge3OF8IgTHF9jhSVCsLyKQKhwc4BsJ5A+dL/SrFtGBjzuHp4XeLhiiOT7afCxX5PdSn/D4c8Lnuw==", 40306856, 7),
+	"win32-x64": sherpaPlatform("win32-x64", 8894875, "sha512-oZF1c9VPOKtMwn83Bboc5XSWL+76BRoyB3eUuVnCknBKxwSULZU2Foia9VHWzU+n4I12rPsP6z6H9Rp1hD9o8g==", 23453246, 8),
+};
+
+// node-cpal has no dependencies or install scripts and needs Node >= 22. Its
+// tarball ships every prebuilt binary; the default backend loads
+// bin/<platform>-<arch>/index.node through facade.js. The five binary headers were
+// inspected (not loaded) and each is built for its own architecture. Published
+// from saeta-eth/node-cpal tag v1.0.0, commit 20e2ac8d1922de7c4af50431e2ddc21a421cf764.
+// 0.1.1 is not used: its darwin-x64 and linux-arm64 binaries were built for the
+// other architecture.
+const NODE_CPAL_VERSION = "1.0.0";
+
+export const NODE_CPAL: VoiceNpmPackage = {
+	name: "node-cpal",
+	version: NODE_CPAL_VERSION,
+	license: "ISC",
+	tarball: npmTarball("node-cpal", NODE_CPAL_VERSION),
+	size: 7723259,
+	integrity: "sha512-d71jIzKDjw1HepqaJQMPd+/k3ZLqYZWhLAv6a8aafIGnYoA1QWlShA5iB5CgijIJtQxq9PdQAk99JQKspqlnTA==",
+	unpackedSize: 20363834,
+	fileCount: 40,
+	requiredFiles: ["package.json", "index.js", "facade.js", "cpal-values.js"],
+};
+
+// The oldest glibc the pinned Linux native binaries accept.
+export const VOICE_LINUX_MIN_GLIBC = "2.34";
+
+export function voiceRuntimeManifest(target: VoiceTarget): VoiceRuntimeManifest {
+	const packages = [
+		SHERPA_ONNX_NODE,
+		SHERPA_ONNX_PLATFORM_PACKAGES[target],
+		{ ...NODE_CPAL, requiredFiles: [...NODE_CPAL.requiredFiles, `bin/${target}/index.node`] },
+	];
+	// The id names both native versions, so a runtime installed with other pins
+	// lives in another directory and is never reported as this one.
+	// npm serves these tarballs directly; no redirect is expected or followed.
+	return { id: `sherpa-onnx-${SHERPA_VERSION}-node-cpal-${NODE_CPAL_VERSION}-${target}`, target, packages, redirects: [] };
+}
+
+const PARAKEET_REPO = "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8";
+const PARAKEET_REVISION = "2bda32ec70b097a55adaa07d9a7173915b43cc78";
+
+// The int8 sherpa-onnx export of NVIDIA Parakeet TDT 0.6B v3 at a fixed commit.
+// Observed redirects: tokens.txt answers 307 with a same-origin resolve-cache path,
+// the LFS/Xet files answer 302 to us.aws.cdn.hf.co/xet-bridge-us/. Other CDN
+// regions were not observed, so they are refused rather than guessed.
+export const PARAKEET_MODEL_MANIFEST: VoiceModelManifest = {
+	id: `parakeet-tdt-0.6b-v3-int8-${PARAKEET_REVISION.slice(0, 12)}`,
+	revision: PARAKEET_REVISION,
+	baseUrl: `https://huggingface.co/${PARAKEET_REPO}/resolve/${PARAKEET_REVISION}`,
+	files: [
+		{ name: "encoder.int8.onnx", size: 652184281, sha256: "acfc2b4456377e15d04f0243af540b7fe7c992f8d898d751cf134c3a55fd2247" },
+		{ name: "decoder.int8.onnx", size: 11845275, sha256: "179e50c43d1a9de79c8a24149a2f9bac6eb5981823f2a2ed88d655b24248db4e" },
+		{ name: "joiner.int8.onnx", size: 6355277, sha256: "3164c13fc2821009440d20fcb5fdc78bff28b4db2f8d0f0b329101719c0948b3" },
+		{ name: "tokens.txt", size: 93939, sha256: "d58544679ea4bc6ac563d1f545eb7d474bd6cfa467f0a6e2c1dc1c7d37e3c35d" },
+	],
+	redirects: [
+		{ origin: "https://huggingface.co", pathPrefix: `/api/resolve-cache/models/${PARAKEET_REPO}/${PARAKEET_REVISION}/` },
+		{ origin: "https://us.aws.cdn.hf.co", pathPrefix: "/xet-bridge-us/" },
+	],
+};
+
+export interface VoiceNotice {
+	component: string;
+	license: string;
+	source: string;
+	attribution?: string;
+	// What is known to be missing from the distributed artifact, stated plainly.
+	unresolved?: string;
+}
+
+export const VOICE_NOTICES: readonly VoiceNotice[] = [
+	{
+		component: "parakeet-tdt-0.6b-v3",
+		license: "CC-BY-4.0",
+		source: "https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3",
+		attribution: "Parakeet TDT 0.6B v3 by NVIDIA, licensed under CC-BY-4.0; int8 sherpa-onnx export by csukuangfj.",
+		unresolved: `The ${PARAKEET_REPO} export has no license file or model card license of its own; the license is taken from the upstream NVIDIA model.`,
+	},
+	{
+		component: "sherpa-onnx-node",
+		license: "Apache-2.0",
+		source: "https://github.com/k2-fsa/sherpa-onnx",
+		unresolved: "The sherpa-onnx npm tarballs ship no LICENSE or NOTICE file, and the platform packages bundle onnxruntime (MIT) without its license text.",
+	},
+	{
+		component: "node-cpal",
+		license: "ISC",
+		source: "https://github.com/saeta-eth/node-cpal",
+		unresolved: "The node-cpal@1.0.0 tarball ships no LICENSE or NOTICE file, and its prebuilt binaries link Rust crates whose notices are not included.",
+	},
+];