@neta-art/cohub-cli 10.3.0 → 10.4.2

package/dist/commands/boards/authoring.js

@@ -1,6 +1,6 @@
 import { readBoardJsonObject } from "../../board-command-support.js";
 import { loadBoardDocument, resolveBundledFonts } from "../../board-export.js";
-import { boardPathTrack, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createNodeBoardRenderer, inspectBoardScene, measureBoardText, } from "../../board-kernel.js";
+import { boardPathTrack, boardSequencePatch, buildBoardScene, createBoardAnimationSampler, createNodeBoardRenderer, inspectBoardItems, } from "../../board-kernel.js";
 import { parseBoardTimes } from "../../board-time.js";
 import { handleHttp, json as outJson } from "../../output.js";
 import { resolveSpace } from "../../space.js";
@@ -9,9 +9,14 @@ export function registerBoardAuthoringCommands(boards) {
         .command("inspect <board>")
         .description("Measure items and report visible layout hints without changing the Board")
         .option("--animation <id>", "Animation to sample")
-        .option("--at <times>", "Time, comma-separated times, or start:end:step", "0")
+        .option("--at <times>", "Time, comma-separated times, or start:end:step (up to 100 samples)", "0")
         .option("--items <ids>", "Limit measurements to comma-separated item ids")
         .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Without --animation, inspects the static document, not playback.
+Bounds use world units with x/y at the top left; worldBounds includes rotation.
+Checks native layout only, not camera cropping or content drawn inside scripts.
+Example: cohub boards inspect lesson.board --animation lecture --at 0:20s:1s --json`)
         .action(async (target, options) => {
         try {
             const { document } = await loadBoardDocument(await resolveSpace(boards), target);
@@ -21,20 +26,13 @@ export function registerBoardAuthoringCommands(boards) {
             try {
                 const ids = options.items ? new Set(options.items.split(",")) : null;
                 outJson({
-                    samples: times.map((time) => {
-                        const scene = sampler?.at(time).scene ?? buildBoardScene(document);
-                        return {
-                            time,
-                            diagnostics: inspectBoardScene(scene),
-                            items: scene.items
-                                .filter((item) => !ids || ids.has(item.id))
-                                .map((item) => ({
-                                id: item.id,
-                                bounds: item.frame,
-                                ...(item.type === "text" ? { text: measureBoardText(item.props) } : {}),
-                            })),
-                        };
-                    }),
+                    mode: sampler ? "animation" : "static",
+                    animation: options.animation ?? null,
+                    coverage: "Native layout in world coordinates; excludes camera cropping and script-drawn content.",
+                    samples: times.map((time) => ({
+                        time,
+                        ...inspectBoardItems(sampler?.at(time).scene ?? buildBoardScene(document), ids ?? undefined),
+                    })),
                 });
             }
             finally {

package/dist/commands/boards.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { parseBoardJsonObject } from "../board-command-support.js";
 export declare const parseJsonObject: typeof parseBoardJsonObject;
+export declare function boardSchemaField(schema: Record<string, unknown> | undefined, path: string): unknown;
 export declare function parseRect(value: string, name?: string): {
     x: number;
     y: number;

package/dist/commands/boards.js

@@ -4,6 +4,7 @@ import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { BOARD_PRESET_NAMES, BOARD_SCHEMA_TARGETS, BOARD_SCRIPT_API, boardJsonSchema, boardPresetTracks, boardSchemaOverview, isBoardPresetName, listBoardPresets, } from "@neta-art/cohub/board";
 import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
+import { BOARD_EXPORT_IMAGE_MEMORY_MIB } from "../board-export-resources.js";
 import { formatBoardTime, parseBoardTime, parseBoardTimes } from "../board-time.js";
 import { createClient, createRealtimeClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
@@ -11,6 +12,16 @@ import { resolveSpace } from "../space.js";
 import { registerBoardExampleCommands } from "./boards/examples.js";
 import { registerBoardAuthoringCommands } from "./boards/authoring.js";
 export const parseJsonObject = parseBoardJsonObject;
+export function boardSchemaField(schema, path) {
+    let field = schema;
+    for (const part of path.split(".")) {
+        const properties = field?.properties;
+        if (!part || !properties || !Object.hasOwn(properties, part))
+            throw new Error(`Unknown schema field ${path}.`);
+        field = properties[part];
+    }
+    return field;
+}
 function withJson(command) {
     return command.option("--json", "Output as JSON");
 }
@@ -152,6 +163,7 @@ function registerExportCommand(boards) {
         .option("--format <format>", `Override the format (${BOARD_EXPORT_FORMATS.join(", ")}, ${BOARD_VIDEO_FORMATS.join(", ")})`)
         .option("--quality <q>", "JPEG/WebP quality from 0 to 1", "0.92")
         .option("--fps <rate>", "Video frame rate; defaults to the --at step")
+        .option("--image-memory <mib>", "Decoded image memory budget in MiB", String(BOARD_EXPORT_IMAGE_MEMORY_MIB))
         .option("--no-images", "Draw placeholders instead of downloading images")
         .option("--force", "Replace existing output files"))
         .addHelpText("after", `
@@ -180,6 +192,11 @@ Examples:
                 if (!jsonRequested(options) && (completed === total || completed % 30 === 0))
                     process.stderr.write(`Rendered ${completed}/${total} frames\n`);
             };
+            const imageMemoryMiB = parseNumber(options.imageMemory ?? String(BOARD_EXPORT_IMAGE_MEMORY_MIB), "--image-memory", { min: 1, max: 65536, integer: true });
+            const onPlan = ({ width, height, frames }) => {
+                if (!jsonRequested(options))
+                    process.stderr.write(`Rendering ${width}x${height}, ${frames} frame(s)\n`);
+            };
             const pathVideoFormat = videoFormatFromPath(out);
             const requestedFormat = options.format?.toLowerCase();
             if (requestedFormat && ![...BOARD_EXPORT_FORMATS, ...BOARD_VIDEO_FORMATS].includes(requestedFormat))
@@ -204,6 +221,8 @@ Examples:
                     target,
                     camera,
                     onProgress: progress,
+                    onPlan,
+                    imageMemoryMiB,
                     signal: controller.signal,
                     force: options.force,
                     region: parseExportRegion(options),
@@ -238,6 +257,8 @@ Examples:
                 target,
                 camera,
                 onProgress: progress,
+                onPlan,
+                imageMemoryMiB,
                 signal: controller.signal,
                 onFrame: async (frame, index) => {
                     const path = sequence ? framePath(out, index) : out;
@@ -448,17 +469,22 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     });
     boards.command("schema [target]")
         .description("Print JSON Schema for a part of a Board")
+        .option("--field <path>", "Print one field, e.g. props.decoration or props.geometry")
         .addHelpText("after", `
 Without a target: units, item types, colors and every animatable property.
 With a target: its fields and what they mean; script also lists the module API.
 Targets: ${BOARD_SCHEMA_TARGETS.join(", ")}`)
-        .action((target) => {
+        .action((target, options) => {
         try {
+            if (options.field && !target)
+                throw new Error("--field needs a schema target, e.g. schema frame --field props.decoration.");
             if (!target)
                 return outJson({ ...boardSchemaOverview(), presets: listBoardPresets() });
             const schema = boardJsonSchema(target);
             if (!schema)
                 throw new Error(`Unknown target ${target}; expected ${BOARD_SCHEMA_TARGETS.join(", ")}.`);
+            if (options.field)
+                return outJson(boardSchemaField(schema.schema, options.field));
             outJson(target === "script" ? { ...schema, api: BOARD_SCRIPT_API } : schema);
         }
         catch (cause) {

package/dist/commands/generations.js

@@ -1,7 +1,7 @@
 import { openAsBlob } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
-import { GenerationPolicyError, assertGenerationRequestAllowedByPolicy, parseGenerationPolicyFromEnv, } from "@neta-art/cohub";
+import { GenerationPolicyError, assertGenerationRequestAllowedByPolicy, mimeTypeForPath, parseGenerationPolicyFromEnv, } from "@neta-art/cohub";
 import { probeMediaInfo } from "@neta-art/cohub/media";
 import { createClient } from "../client.js";
 import { resolveSpace } from "../space.js";
@@ -14,19 +14,6 @@ const rolesByMediaType = {
     audio: new Set(["reference_audio"]),
 };
 const mediaRoles = new Set([...frameMediaRoles, ...referenceMediaRoles]);
-const mimeByExt = {
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".webp": "image/webp",
-    ".gif": "image/gif",
-    ".mp4": "video/mp4",
-    ".webm": "video/webm",
-    ".mov": "video/quicktime",
-    ".mp3": "audio/mpeg",
-    ".wav": "audio/wav",
-    ".ogg": "audio/ogg",
-};
 function parseValue(value) {
     const trimmed = value.trim();
     if (trimmed === "true")
@@ -84,8 +71,8 @@ async function mediaContent({ type, value, role }, upload) {
     const block = (source) => ({ type, source, ...(role ? { meta: { role } } : {}) });
     if (/^https?:\/\//.test(value))
         return block({ type: "url", url: value });
-    const mediaType = mimeByExt[extname(value).toLowerCase()];
-    if (mediaType && upload) {
+    const mediaType = mimeTypeForPath(value);
+    if (mediaType && /^(image|video|audio)\//.test(mediaType) && upload) {
         try {
             return block({ type: "url", url: await upload(value, mediaType) });
         }
@@ -189,11 +176,13 @@ function slugOutputLabel(block) {
     return slugify(metaRole(block) ?? block.type);
 }
 const PROBE_TIMEOUT_MS = 3_000;
-/** Size, duration, and frames of URL outputs, probed in parallel; best effort. */
+/** Size, duration, and frames of image, video, and audio URL outputs, probed in parallel; best effort. */
 async function probeOutputs(output) {
     const signal = AbortSignal.timeout(PROBE_TIMEOUT_MS);
     const probed = await Promise.all(output.map(async (block, index) => {
-        if (block.type === "text" || block.source.type !== "url")
+        if (block.type !== "image" && block.type !== "video" && block.type !== "audio")
+            return null;
+        if (block.source.type !== "url")
             return null;
         const info = await probeMediaInfo(block.source.url, { type: block.type, signal });
         return Object.keys(info).length > 0 ? { index, ...info } : null;

package/dist/commands/public.d.ts

@@ -1,4 +1,4 @@
-import type { CohubHttpClient } from "@neta-art/cohub";
+import { type CohubHttpClient } from "@neta-art/cohub";
 import type { Command } from "commander";
 type LocalPublicFile = {
     id: string;

package/dist/commands/public.js

@@ -1,45 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { lstat, readdir } from "node:fs/promises";
-import { basename, extname, relative, resolve } from "node:path";
+import { basename, relative, resolve } from "node:path";
+import { isTextMime, mimeTypeForPath, } from "@neta-art/cohub";
 import { createClient } from "../client.js";
 import { HttpPutError, putLocalFile } from "../http-put.js";
 import { error, handleHttp, json as outJson, jsonRequested } from "../output.js";
 import { resolveSpace } from "../space.js";
 const UPLOAD_CONCURRENCY = 4;
-const MIME_TYPES = {
-    ".aac": "audio/aac",
-    ".avi": "video/x-msvideo",
-    ".avif": "image/avif",
-    ".css": "text/css; charset=utf-8",
-    ".csv": "text/csv; charset=utf-8",
-    ".gif": "image/gif",
-    ".htm": "text/html; charset=utf-8",
-    ".html": "text/html; charset=utf-8",
-    ".ico": "image/x-icon",
-    ".jpeg": "image/jpeg",
-    ".jpg": "image/jpeg",
-    ".js": "text/javascript; charset=utf-8",
-    ".json": "application/json; charset=utf-8",
-    ".m4a": "audio/mp4",
-    ".md": "text/markdown; charset=utf-8",
-    ".mov": "video/quicktime",
-    ".mp3": "audio/mpeg",
-    ".mp4": "video/mp4",
-    ".ogg": "audio/ogg",
-    ".ogv": "video/ogg",
-    ".pdf": "application/pdf",
-    ".png": "image/png",
-    ".svg": "image/svg+xml",
-    ".txt": "text/plain; charset=utf-8",
-    ".wasm": "application/wasm",
-    ".wav": "audio/wav",
-    ".webm": "video/webm",
-    ".webp": "image/webp",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-    ".xml": "application/xml; charset=utf-8",
-    ".zip": "application/zip",
-};
 function hasControlCharacters(value) {
     return [...value].some((char) => {
         const code = char.charCodeAt(0);
@@ -65,8 +32,11 @@ function normalizePublicPath(input) {
     }
     return parts.join("/");
 }
-function mimeTypeForPath(path) {
-    return MIME_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+function contentTypeForPath(path) {
+    const mimeType = mimeTypeForPath(path);
+    if (!mimeType)
+        return "application/octet-stream";
+    return isTextMime(mimeType) ? `${mimeType}; charset=utf-8` : mimeType;
 }
 async function walkDirectory(root, directory, destination) {
     const names = await readdir(directory);
@@ -90,7 +60,7 @@ async function walkDirectory(root, directory, destination) {
             localPath,
             publicPath,
             size: info.size,
-            mimeType: mimeTypeForPath(localPath),
+            mimeType: contentTypeForPath(localPath),
         });
     }
     return files;
@@ -114,7 +84,7 @@ export async function collectPublicUpload(source, destination) {
                     localPath,
                     publicPath,
                     size: info.size,
-                    mimeType: mimeTypeForPath(localPath),
+                    mimeType: contentTypeForPath(localPath),
                 }],
         };
     }

package/dist/commands/rooms-rtc-binary.js

@@ -7,7 +7,7 @@ import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 // Pin a global release tag after its helper artifacts are published.
-export const RTC_HELPER_VERSION = "v2.67.0";
+export const RTC_HELPER_VERSION = "v2.68.0";
 const MAX_BINARY_BYTES = 128 * 1024 * 1024;
 async function digest(path) {
     const hash = createHash("sha256");

package/dist/commands/sandboxd-binary.d.ts

@@ -1,9 +1,9 @@
-export declare const SANDBOXD_VERSION = "v2.67.0";
+export declare const SANDBOXD_VERSION = "v2.68.0";
 export declare class SandboxdDownloadError extends Error {
     name: string;
 }
-export declare function validSandboxdArchiveEntries(entries: string[]): boolean;
-export declare function validateSandboxdArchive(archivePath: string): Promise<string[]>;
+export declare function validSandboxdArchiveEntries(entries: string[], goos: string): boolean;
+export declare function validateSandboxdArchive(archivePath: string, goos: string): Promise<string[]>;
 export type EnsureSandboxdOptions = {
     version?: string;
     onStatus?: (message: string) => void;

package/dist/commands/sandboxd-binary.js

@@ -7,8 +7,9 @@ import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 // Pin only after all platform artifacts are published to the public CDN.
-export const SANDBOXD_VERSION = "v2.67.0";
+export const SANDBOXD_VERSION = "v2.68.0";
 const BINARY_NAME = "cohub-sandboxd";
+const binaryName = (goos) => goos === "windows" ? `${BINARY_NAME}.exe` : BINARY_NAME;
 // Public CDN prefix hosting the release archives (the repo is private, so the
 // GitHub Release assets are not publicly downloadable). Overridable for staging
 // or self-hosting.
@@ -16,7 +17,7 @@ const cdnBaseUrl = () => (process.env.COHUB_SANDBOXD_CDN_BASE_URL?.trim() || "ht
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 const LOCK_STALE_MS = 5 * 60 * 1000;
 // Map Node's platform/arch to the Go GOOS/GOARCH used in release asset names.
-const GOOS_BY_PLATFORM = { darwin: "darwin", linux: "linux" };
+const GOOS_BY_PLATFORM = { darwin: "darwin", linux: "linux", win32: "windows" };
 const GOARCH_BY_ARCH = { x64: "amd64", arm64: "arm64" };
 export class SandboxdDownloadError extends Error {
     name = "SandboxdDownloadError";
@@ -30,7 +31,7 @@ const resolveTarget = () => {
     return { goos, goarch };
 };
 const cacheDir = (version) => join(homedir(), ".cache", "cohub", "sandboxd", version);
-const cachedBinaryPath = (version) => join(cacheDir(version), BINARY_NAME);
+const cachedBinaryPath = (version, target) => join(cacheDir(version), binaryName(target.goos));
 const archiveName = (version, target) => `${BINARY_NAME}_${version}_${target.goos}_${target.goarch}.tar.gz`;
 const isExecutableFile = async (path) => {
     const info = await lstat(path).catch(() => null);
@@ -85,14 +86,23 @@ const fetchText = (url, accept) => withTimeout(`Download of ${url}`, async (sign
     return (await response.text()).trim();
 });
 // Every published release ships the binary alongside its LICENSE and NOTICE.
-const EXPECTED_ARCHIVE_ENTRIES = [BINARY_NAME, "LICENSE", "NOTICE"];
-export function validSandboxdArchiveEntries(entries) {
-    return (entries.length === EXPECTED_ARCHIVE_ENTRIES.length &&
-        EXPECTED_ARCHIVE_ENTRIES.every((entry) => entries.includes(entry)));
+export function validSandboxdArchiveEntries(entries, goos) {
+    const expected = [binaryName(goos), "LICENSE", "NOTICE"];
+    return (entries.length === expected.length &&
+        expected.every((entry) => entries.includes(entry)));
 }
+// Git for Windows puts GNU tar on PATH, which treats `C:\...` as a remote host.
+// Use the system bsdtar (Windows 10+) instead.
+const tarCommand = () => {
+    if (process.platform !== "win32")
+        return "tar";
+    if (!process.env.SystemRoot)
+        throw new SandboxdDownloadError("SystemRoot is not set; cannot locate tar.exe");
+    return join(process.env.SystemRoot, "System32", "tar.exe");
+};
 // Reject unexpected paths before extracting the checksum-verified release.
 const listTarGz = (archivePath, verbose = false) => new Promise((res, rej) => {
-    const child = spawn("tar", [verbose ? "-tvzf" : "-tzf", archivePath], { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(tarCommand(), [verbose ? "-tvzf" : "-tzf", archivePath], { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (chunk) => {
@@ -106,9 +116,9 @@ const listTarGz = (archivePath, verbose = false) => new Promise((res, rej) => {
         ? res(stdout.split("\n").map((line) => line.trim()).filter(Boolean))
         : rej(new SandboxdDownloadError(`tar listing failed: ${stderr.trim() || `exit ${code}`}`)));
 });
-export async function validateSandboxdArchive(archivePath) {
+export async function validateSandboxdArchive(archivePath, goos) {
     const entries = await listTarGz(archivePath);
-    if (!validSandboxdArchiveEntries(entries)) {
+    if (!validSandboxdArchiveEntries(entries, goos)) {
         throw new SandboxdDownloadError(`Unexpected sandbox archive contents: ${entries.join(", ") || "(empty)"}`);
     }
     const details = await listTarGz(archivePath, true);
@@ -120,7 +130,7 @@ export async function validateSandboxdArchive(archivePath) {
 // Extract the verified `.tar.gz` using the system tar (universally present on
 // macOS and Linux), keeping the CLI free of native archive dependencies.
 const extractTarGz = (archivePath, cwd) => new Promise((res, rej) => {
-    const child = spawn("tar", ["-xzf", archivePath, "-C", cwd], { stdio: ["ignore", "ignore", "pipe"] });
+    const child = spawn(tarCommand(), ["-xzf", archivePath, "-C", cwd], { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     child.stderr.on("data", (chunk) => {
         stderr += chunk.toString();
@@ -175,19 +185,19 @@ const downloadAndVerify = async (version, target) => {
         if (actual !== expected) {
             throw new SandboxdDownloadError(`Checksum mismatch for ${name} (expected ${expected}, got ${actual})`);
         }
-        const entries = await validateSandboxdArchive(archivePath);
+        const entries = await validateSandboxdArchive(archivePath, target.goos);
         await extractTarGz(archivePath, tempDir);
         for (const entry of entries) {
             if (!(await isSafeArchiveFile(join(tempDir, entry)))) {
                 throw new SandboxdDownloadError(`Unsafe sandbox archive entry: ${entry}`);
             }
         }
-        const extractedBinary = join(tempDir, BINARY_NAME);
+        const extractedBinary = join(tempDir, binaryName(target.goos));
         if (!(await isSafeArchiveFile(extractedBinary))) {
-            throw new SandboxdDownloadError(`Archive ${name} did not contain ${BINARY_NAME}`);
+            throw new SandboxdDownloadError(`Archive ${name} did not contain ${binaryName(target.goos)}`);
         }
         // Atomically move into the version cache (fall back to copy across devices).
-        const dest = cachedBinaryPath(version);
+        const dest = cachedBinaryPath(version, target);
         await mkdir(dirname(dest), { recursive: true });
         await rename(extractedBinary, dest).catch(async (err) => {
             if (err.code !== "EXDEV")
@@ -212,10 +222,10 @@ export const ensureSandboxdBinary = async (options = {}) => {
         return override;
     }
     const version = options.version?.trim() || SANDBOXD_VERSION;
-    const cached = cachedBinaryPath(version);
+    const target = resolveTarget();
+    const cached = cachedBinaryPath(version, target);
     if (await isExecutableFile(cached))
         return cached;
-    const target = resolveTarget();
     return withLock(version, async () => {
         // Re-check inside the lock: another process may have finished downloading.
         if (await isExecutableFile(cached))

package/dist/runtime/harness.d.ts

@@ -5,6 +5,11 @@ export type HarnessOptions = {
     codex?: string;
 };
 export declare function harnessExecutableCandidates(binary: string, cwd: string, path: string, platform?: NodeJS.Platform, pathExt?: string | undefined): string[];
+/**
+ * Windows npm/pnpm installs expose harnesses as .cmd shims, which cannot be spawned
+ * without a shell. Run an .exe directly, or the shim's Node entry with this Node.
+ */
+export declare function harnessCommand(binary: string, args: string[], cwd: string): [string, string[]];
 /** Discover installed executables only; authentication/capability errors stay explicit. */
 export declare function installedHarnesses(cwd: string, options: HarnessOptions, path?: string): Promise<("pi" | "codex")[]>;
 /** Aborted streams leave tool calls with an empty id or name. */

package/dist/runtime/harness.js

@@ -1,5 +1,5 @@
 import { access, stat } from "node:fs/promises";
-import { constants } from "node:fs";
+import { constants, readFileSync, statSync } from "node:fs";
 import { delimiter, join, resolve, win32 } from "node:path";
 import { JsonRpcProcess, record } from "./json-rpc.js";
 import { codexModelCatalog, piModelCatalog } from "./model-catalog.js";
@@ -7,14 +7,40 @@ import { downloadPublicImage } from "../safe-remote-image.js";
 export function harnessExecutableCandidates(binary, cwd, path, platform = process.platform, pathExt = process.env.PATHEXT) {
     const windows = platform === "win32";
     const paths = windows ? win32 : { delimiter, join, resolve };
+    // Windows runs only PATHEXT names; npm/pnpm also write an extensionless sh script beside the .cmd shim.
     const extensions = windows && !win32.extname(binary)
-        ? ["", ...(pathExt || ".COM;.EXE;.BAT;.CMD").split(";").filter((ext) => /^\.[a-z0-9]+$/i.test(ext))]
+        ? (pathExt || ".COM;.EXE;.BAT;.CMD").split(";").filter((ext) => /^\.[a-z0-9]+$/i.test(ext))
         : [""];
     const roots = binary.includes("/") || binary.includes("\\")
         ? [paths.resolve(cwd, binary)]
         : path.split(paths.delimiter).map((directory) => directory.replace(/^"(.*)"$/, "$1")).filter(Boolean).map((directory) => paths.resolve(cwd, directory, binary));
     return roots.flatMap((root) => extensions.map((ext) => `${root}${ext}`));
 }
+/**
+ * Windows npm/pnpm installs expose harnesses as .cmd shims, which cannot be spawned
+ * without a shell. Run an .exe directly, or the shim's Node entry with this Node.
+ */
+export function harnessCommand(binary, args, cwd) {
+    if (process.platform !== "win32")
+        return [binary, args];
+    const path = harnessExecutableCandidates(binary, cwd, process.env.PATH ?? "").find((candidate) => statSync(candidate, { throwIfNoEntry: false })?.isFile());
+    if (!path)
+        throw new Error(`${binary} was not found on PATH`);
+    const extension = win32.extname(path).toLowerCase();
+    if (extension === ".exe" || extension === ".com")
+        return [path, args];
+    if ([".js", ".mjs", ".cjs"].includes(extension))
+        return [process.execPath, [path, ...args]];
+    if (extension === ".cmd") {
+        // npm (cmd-shim): SET "_prog=node" … "%dp0%\entry" %*; pnpm (@zkochan/cmd-shim): node  "%~dp0\entry" %*
+        const shim = readFileSync(path, "utf8");
+        const runsNode = /SET "_prog=node"/i.test(shim) || /^\s*node\s+"%~dp0\\/im.test(shim);
+        const entry = runsNode ? /"%~?dp0%?\\([^"]+)"\s+%\*/i.exec(shim)?.[1] : undefined;
+        if (entry)
+            return [process.execPath, [win32.join(win32.dirname(path), entry), ...args]];
+    }
+    throw new Error(`Cannot run ${path} without a shell; pass --pi/--codex with an .exe or Node script`);
+}
 /** Discover installed executables only; authentication/capability errors stay explicit. */
 export async function installedHarnesses(cwd, options, path = process.env.PATH ?? "") {
     const names = options.pi || options.codex ? ["pi", "codex"].filter((name) => options[name]) : ["pi", "codex"];
@@ -64,7 +90,7 @@ async function initializeCodex(rpc) {
 export async function discoverHarnesses(harnesses, options, cwd) {
     const models = [];
     await Promise.all(harnesses.map(async (harness) => {
-        const rpc = new JsonRpcProcess(options[harness] || harness, harness === "pi" ? ["--mode", "rpc", "--no-session"] : ["app-server", "--listen", "stdio://"], cwd, harness);
+        const rpc = new JsonRpcProcess(...harnessCommand(options[harness] || harness, harness === "pi" ? ["--mode", "rpc", "--no-session"] : ["app-server", "--listen", "stdio://"], cwd), cwd, harness);
         try {
             if (harness === "pi") {
                 const result = await rpc.request("get_available_models");

package/dist/runtime/json-rpc.js

@@ -67,7 +67,7 @@ export class JsonRpcProcess {
     closing = null;
     constructor(binary, args, cwd, mode, context = {}) {
         this.mode = mode;
-        this.child = spawn(binary, args, { cwd, env: { ...harnessEnvironment(), ...context }, stdio: "pipe", detached: process.platform !== "win32" });
+        this.child = spawn(binary, args, { cwd, env: { ...harnessEnvironment(), ...context }, stdio: "pipe", detached: process.platform !== "win32", windowsHide: true });
         this.closed = new Promise((resolve) => this.child.once("close", () => resolve()));
         const decoder = new JsonLineDecoder((value) => this.receive(value));
         this.child.stdout.on("data", (chunk) => { try {

package/dist/runtime/launch.js

@@ -1,7 +1,8 @@
-import { fork } from "node:child_process";
+import { execFile, fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { stat } from "node:fs/promises";
-import { basename, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
+import { promisify } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { isLocalHarness } from "@neta-art/cohub";
 import { discoverHarnesses, installedHarnesses } from "./harness.js";
@@ -23,11 +24,11 @@ export function parseRuntimeHarnesses(values) {
 export function parseRuntimeDisplay(value, platform = process.platform, env = process.env) {
     if (value === false)
         return undefined;
-    if (value === undefined && platform !== "darwin" && (platform !== "linux" || !env.DISPLAY))
+    if (value === undefined && platform !== "darwin" && platform !== "win32" && (platform !== "linux" || !env.DISPLAY))
         return undefined;
     const spec = value === undefined || value === true ? "auto" : value.trim();
-    if (!/^(auto|macos|x11(:[\w.:-]+)?|xvfb(:\d{3,4}x\d{3,4})?)$/.test(spec)) {
-        throw new Error("Display must be auto, macos, x11[:display] or xvfb[:WIDTHxHEIGHT]");
+    if (!/^(auto|macos|windows|x11(:[\w.:-]+)?|xvfb(:\d{3,4}x\d{3,4})?)$/.test(spec)) {
+        throw new Error("Display must be auto, macos, windows, x11[:display] or xvfb[:WIDTHxHEIGHT]");
     }
     if (platform === "linux" && spec === "auto" && !env.DISPLAY) {
         throw new Error(env.WAYLAND_DISPLAY
@@ -52,7 +53,9 @@ export async function startBackgroundRuntime(config) {
     return new Promise((resolve, reject) => {
         // Keep the same Node executable and loader (also works from source in tests).
         const workerUrl = new URL(import.meta.url.endsWith(".ts") ? "./worker.ts" : "./worker.js", import.meta.url);
-        const child = fork(workerUrl, [], { detached: true, stdio: ["ignore", "ignore", "ignore", "ipc"] });
+        // fork forwards spawn options; windowsHide keeps a detached Windows worker from opening a console.
+        const forkOptions = { detached: true, stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true };
+        const child = fork(workerUrl, [], forkOptions);
         const diagnosticConsole = createDiagnosticConsole(config.verbose);
         let last = null;
         let settled = false;
@@ -89,7 +92,19 @@ export async function startBackgroundRuntime(config) {
         child.send(config);
     });
 }
+/** Collaborators execute as this OS user; an elevated Windows token would grant them administrator rights. */
+async function assertNotElevatedOnWindows() {
+    if (process.platform !== "win32")
+        return;
+    if (!process.env.SystemRoot)
+        throw new Error("SystemRoot is not set; cannot check terminal elevation");
+    const { stdout } = await promisify(execFile)(join(process.env.SystemRoot, "System32", "whoami.exe"), ["/groups"], { encoding: "utf8", windowsHide: true });
+    // High (S-1-16-12288) and System (S-1-16-16384) integrity labels mark an elevated token.
+    if (/\bS-1-16-(?:12288|16384)\b/.test(stdout))
+        throw new Error("Run cohub runtime up from a non-elevated terminal");
+}
 export async function runtimeUp(program, dir, options) {
+    await assertNotElevatedOnWindows();
     const requestedRoot = resolve(dir ?? process.cwd());
     if (!(await stat(requestedRoot)).isDirectory())
         throw new Error("Workspace is not a directory");

package/dist/runtime/native/attach.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { serializeDiagnosticError } from "../diagnostics.js";
-import { CODEX_SHARED_MIN_VERSION, supportsSharedServer } from "./codex-link.js";
+import { CODEX_SHARED_MIN_VERSION, sharedServerAvailable, supportsSharedServer } from "./codex-link.js";
 import { PI_MIN_VERSION } from "./pi-link.js";
 import { atLeast, formatVersion, harnessVersion } from "./version.js";
 import { readNativeConfig, runtimeStateRoot, writeNativeConfig } from "./config.js";
@@ -43,7 +43,10 @@ export async function ensureNativeSync(input, log = (line) => process.stderr.wri
     let codexShared = previous?.codexShared ?? false;
     if (input.harnesses.includes("codex") && !codexShared) {
         const version = await harnessVersion(input.executables?.codex || "codex");
-        if (!supportsSharedServer(version)) {
+        if (!sharedServerAvailable) {
+            log("Shared Codex sessions are unavailable on Windows; terminal Codex chats sync read-only\n");
+        }
+        else if (!supportsSharedServer(version)) {
             log(`Codex ${formatVersion(version)} predates the shared app-server (${CODEX_SHARED_MIN_VERSION.join(".")}+); terminal Codex chats sync read-only\n`);
         }
         else {

package/dist/runtime/native/codex-link.d.ts

@@ -18,6 +18,8 @@ export interface CodexChannel {
     readonly shared: boolean;
     readonly closed: boolean;
 }
+/** Codex's shared server listens on an AF_UNIX socket, which Node cannot reach on Windows. */
+export declare const sharedServerAvailable: boolean;
 export declare const supportsSharedServer: (version: Version | null) => boolean;
 /** A private app-server over stdio, used when no shared one is available; it lives for one Turn. */
 export declare function openPrivateServer(rpc: JsonRpcProcess): Promise<CodexChannel>;

package/dist/runtime/native/codex-link.js

@@ -15,7 +15,9 @@ const DAEMON_START_TIMEOUT_MS = 30_000;
 const codexHome = () => process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
 /** The socket every Codex client on this machine discovers; a terminal `codex` attaches to it. */
 const codexControlSocket = () => join(codexHome(), "app-server-control", "app-server-control.sock");
-export const supportsSharedServer = (version) => atLeast(version, CODEX_SHARED_MIN_VERSION);
+/** Codex's shared server listens on an AF_UNIX socket, which Node cannot reach on Windows. */
+export const sharedServerAvailable = process.platform !== "win32";
+export const supportsSharedServer = (version) => sharedServerAvailable && atLeast(version, CODEX_SHARED_MIN_VERSION);
 /** Start the shared app-server when none is running. */
 async function ensureSharedServer(binary, cwd) {
     if (existsSync(codexControlSocket()) && await probe())

package/dist/runtime/native/execution.js

@@ -1,4 +1,4 @@
-import { imageForPi } from "../harness.js";
+import { harnessCommand, imageForPi } from "../harness.js";
 import { JsonRpcProcess, record, RpcProcessClosedError } from "../json-rpc.js";
 import { describeError } from "../../network-error.js";
 import { ProcessCleanupUncertainError } from "../process-group.js";
@@ -55,7 +55,7 @@ async function runPi(executor, turn, context) {
     let begun = false;
     try {
         if (!link) {
-            host = new JsonRpcProcess(executor.executables.pi || "pi", ["--mode", "rpc", "--session", session.path, "-e", executor.piExtension], executor.cwd, "pi", turnEnvironment(input));
+            host = new JsonRpcProcess(...harnessCommand(executor.executables.pi || "pi", ["--mode", "rpc", "--session", session.path, "-e", executor.piExtension], executor.cwd), executor.cwd, "pi", turnEnvironment(input));
             watchHost(host, executor.diagnostics, context);
             const rpc = host;
             // Nobody is at this Pi's terminal to answer an extension's question.
@@ -209,7 +209,7 @@ async function runCodex(executor, turn, context) {
     let begun = false;
     try {
         if (!channel) {
-            host = new JsonRpcProcess(executor.executables.codex || "codex", ["app-server", "--listen", "stdio://"], executor.cwd, "codex", turnEnvironment(input));
+            host = new JsonRpcProcess(...harnessCommand(executor.executables.codex || "codex", ["app-server", "--listen", "stdio://"], executor.cwd), executor.cwd, "codex", turnEnvironment(input));
             watchHost(host, executor.diagnostics, context);
             channel = await openPrivateServer(host);
         }