ideawave 0.0.103 → 0.0.105

package/README.md

@@ -1,41 +1,293 @@
-# IdeaWave CLI
+# IdeaWave TUI
 
-Run local coding agents from an IdeaWave board.
+The local IdeaWave host, built with OpenTUI Solid and Effect. The application
+provides runtime-validated compatibility contracts, scoped lifecycle, ACP client
+discovery and runs, browser-hosted MCP tools, searchable local activity, and
+privacy-safe traces, metrics, and approved operational logs inside the general
+host-status dashboard.
+
+## Requirements
+
+- Node.js 22 or newer for the published npx/bunx launcher and managed ACP
+  subprocesses.
+- macOS and Linux glibc/musl on x64 or arm64, or Windows on x64.
+- One supported ACP client for agent use: Claude Code, Codex, GitHub Copilot,
+  OpenCode, or a configured custom ACP command.
+
+Users do not install Bun. Each platform npm package contains a Bun-compiled
+IdeaWave host with OpenTUI and the Bun runtime embedded. Bun 1.4.0 remains a
+pinned build and contributor dependency for this monorepo. x64 release hosts
+use Bun's baseline target so older non-AVX2 CPUs do not fail at startup.
 
 ```bash
-npx --yes ideawave@latest
+bun install
+bun dev
 ```
 
-Then open [ideawave.app](https://ideawave.app), choose a board, and start an agent run.
+To create and smoke-test the installable release artifacts for the current
+platform:
 
-## Requirements
+```bash
+bun run release:pack --target current
+bun test tests/release-artifact.test.ts
+```
+
+The builder writes a launcher tarball plus the current platform's exact host
+tarball to `dist/standalone/tarballs/`. The release workflow builds all seven
+unsigned targets on one Blacksmith Linux producer. Automated release acceptance
+executes Linux glibc/musl packages (with ARM headless checks through QEMU); the
+separate manual, credential-free compatibility workflow executes macOS arm64,
+macOS x64 under Rosetta, and Windows x64. It does not sign, publish, or gate the
+Linux release. The artifact test installs the two current-platform tarballs
+into a clean consumer project; it does not depend on a global install or this
+checkout.
+
+The package publishes to npm as `ideawave`, so both `npx ideawave` and ordinary
+`bunx ideawave` open the same TUI. Its small Node launcher validates Node,
+detects OS/CPU/libc, resolves the exact-version native host package, and starts
+that executable. There is no postinstall, binary copy, fallback download, or
+IdeaWave-owned executable cache. The universal package intentionally retains
+only `playwright-core` as a JavaScript sidecar so browser installation can run
+under the validated launcher Node. `bunx --bun ideawave` is rejected because it
+overrides the Node shebang and would make managed ACP and Playwright subprocess
+selection ambiguous.
 
-- Node.js 18 or newer
-- Google Chrome for screenshot capture. Browser cards stay inside the app
-  iframe and use the CLI's local browser-kit proxy.
-- At least one supported agent runtime installed and signed in:
-  - Claude Code
-  - Codex CLI
-  - GitHub Copilot CLI
-  - OpenCode
+On a clean profile, the first interactive start asks which ACP clients to use.
+The selection is checked before it is saved, and the dashboard opens only when
+at least one selected client is ready. Existing configured profiles start
+directly. Use `--onboard` to choose again or `--skip-onboarding` for automation.
 
 ## Commands
 
+| Command | Behavior |
+| --- | --- |
+| `ideawave` | Run first-use setup when needed, then open the status workspace. |
+| `ideawave --onboard` | Re-run ACP client selection and verification. |
+| `ideawave --skip-onboarding` | Open without reading or changing onboarding state. |
+| `ideawave --dev` | Allow Railway PR preview origins on the browser bridge (development/preview mode). |
+| `ideawave doctor` | Run passive checks and print a report without initializing OpenTUI. |
+| `ideawave doctor --deep` | Also launch ready ACP clients briefly; processes may use network/authentication state. |
+| `ideawave doctor --json` | Print the versioned privacy-safe automation report. May be combined with `--deep`. |
+| `ideawave traces` | Validate trace-export configuration without starting the host, accessing the network, or displaying collector/header values. |
+| `ideawave traces --json` | Print the versioned privacy-safe trace configuration report. |
+| `ideawave --version` | Print the installed package version. `-v` and `ideawave version` are aliases. |
+| `ideawave --headless` | Run the same host services as the TUI without initializing OpenTUI. |
+| `ideawave capture install` | Install the managed Chromium headless shell used by iframe capture. On Linux musl, install system Chromium instead (`apk add chromium` on Alpine). |
+
+`doctor` exits with status `0` when all checks pass, `1` when warnings are
+present, and `2` when a check fails or the command cannot complete. Onboarding
+returns `3` when no selected client is usable and `64` for invalid arguments.
+Redirected output is plain text without ANSI control sequences.
+The JSON doctor schema is versioned with `schemaVersion: 1`; it omits persisted
+commands, arguments, environment values, paths, overrides, and runtime IDs.
+
+`traces` exits with status `0` when trace export is intentionally disabled or
+valid, `1` when export was requested but its configuration is incomplete or
+invalid, and `64` for invalid options. It reports the standard OpenTelemetry
+environment-variable name that won precedence, but never its endpoint or header
+value. The command validates configuration for a future host process; it does
+not contact a collector or inspect another running host.
+
+`--headless` initializes the shared `Application` layer, prints one JSON readiness
+line containing only loopback ports, and stays active until `SIGINT` or `SIGTERM`.
+Ordinary interactive startup requires terminal stdin and stdout; automation must
+choose `--headless`, `doctor`, or `traces` explicitly.
+
+## Status Controls
+
+| Key | Action |
+| --- | --- |
+| `1`, `a` | Select the Activity workspace tab. |
+| `2`, `v` | Select the Doctor workspace tab. |
+| `Tab` | Switch workspace tabs. |
+| `/`, `b` | Search activity or edit severity, category, time, service, session, and run filters. |
+| `p`, `f` | Pause/resume the view or follow the newest matching activity. |
+| `j`, `k`, `Up`, `Down` | Select an activity record. |
+| `Enter`, `y` | Inspect a selected record or copy its safe projection with OSC 52. |
+| `r` | Run fast passive diagnostics. |
+| `d` | Review side effects, then run a cancellable ACP launch check. |
+| `i` | Review side effects, then install missing managed Claude/Codex bridges. |
+| `e` | Review side effects, then install the managed capture engine. |
+| `s`, `g` | Show browser session or live agent detail. |
+| `o` | Show runtime configuration and per-signal telemetry detail. |
+| `x`, `c` | Cancel active deep checks or installation. |
+| `l` | Clear only the current local view; retained history and service state are unchanged. |
+| `?` | Show controls and safety details. |
+| `q` | Close an overlay, or quit from the dashboard. |
+| `Esc` | Close an overlay. |
+| `Ctrl+C` | Cancel active work, or quit when idle. |
+
+Passive doctor checks do not launch ACP processes, install packages, or access
+the network. Deep checks briefly launch ready ACP commands. Managed bridge
+installation uses npm to place each exact pin in IdeaWave's versioned cache,
+validates and warms the bundled runtime, and can access the network and package
+cache. Warm launches run the verified adapter directly with Node. Both
+operations are Effect-scoped and clean up staging work on cancellation.
+
+Playwright does not publish supported managed browser builds for Linux musl.
+On Alpine and other musl systems, IdeaWave uses a distribution-provided
+`chromium` executable (or `IDEAWAVE_CAPTURE_EXECUTABLE_PATH`) and does not
+download a glibc browser into the managed cache.
+
+The left status panel remains visible on both workspace tabs. Activity entries
+always show their producing service label. When readiness transitions to a state
+where no ACP client can be activated, Doctor is selected once so remediation is
+immediately visible; a later explicit tab choice is respected.
+
+## Telemetry
+
+Remote export stays disabled on an ordinary install and automatically uses
+continuous mode when an OTLP endpoint is configured. It uses vendor-neutral OTLP/HTTP JSON and
+never sends prompts, responses, tool arguments or results, credentials,
+environment values, paths, URLs, user/card/run identifiers, or raw errors.
+Browser session IDs are the only approved high-cardinality correlation field and
+are never used as metric dimensions. Remote logs use a finite event and message
+catalog; local Activity summaries and arbitrary producer messages cannot cross
+the export boundary.
+
+Trace and log queues are deliberately bounded and in-process. IdeaWave does not
+create a local trace file, persist telemetry between launches, or backfill the
+Activity ring. Use `ideawave traces` for a non-networking configuration check;
+use Activity or Doctor inside the running host for live queue/export state, and
+the configured collector for retained trace search. Signal-specific endpoint
+and header variables take precedence over their generic counterparts, matching
+the [OpenTelemetry OTLP exporter contract](https://opentelemetry.io/docs/specs/otel/protocol/exporter/).
+
+| Variable | Behavior |
+| --- | --- |
+| `IDEAWAVE_TELEMETRY_MODE=disabled` | Explicitly opt out of all remote telemetry. |
+| `IDEAWAVE_TELEMETRY_MODE=manual` | Keep a bounded local queue without exporting automatically. |
+| `IDEAWAVE_TELEMETRY_MODE=continuous` | Export the bounded queue automatically with retry. This is inferred when an OTLP endpoint is configured. |
+| `IDEAWAVE_TELEMETRY_LOGS=disabled` | Explicitly opt approved operational logs out while retaining traces and metrics. Logs are enabled by default. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Operator-owned collector or ingest-proxy base URL. `/v1/logs`, `/v1/traces`, and `/v1/metrics` are resolved automatically. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Optional comma-separated, percent-encoded `name=value` request headers. Values are never displayed or exported. |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Optional final OTLP/HTTP logs URL; overrides the generic endpoint for logs. |
+| `OTEL_EXPORTER_OTLP_LOGS_HEADERS` | Optional logs-only headers; overrides generic headers for logs. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Optional final OTLP/HTTP traces URL; overrides the generic endpoint for traces. |
+| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Optional traces-only headers; overrides generic headers for traces. |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Optional final OTLP/HTTP metrics URL; overrides the generic endpoint for metrics. |
+| `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | Optional metrics-only headers; overrides generic headers for metrics. |
+
+The Activity header and Doctor show per-signal configuration, queue depth,
+drops, retry state, last success, and safe last-failure codes. Each signal has
+reserved bounded capacity, so a log burst cannot consume trace or metric space.
+A failure on one signal does not erase another signal's success or break browser,
+ACP, MCP, Doctor, iframe proxy, capture, or local log behavior. Shutdown
+interrupts all in-flight HTTP requests within one total final-flush bound so an
+unavailable collector cannot hang terminal restoration.
+
+### Collector And Axiom Routing
+
+Production deployments should send all three signal paths to an operator-owned
+OpenTelemetry Collector or product-owned ingest proxy. The collector holds
+credentials and routes logs and traces to separate Axiom Events datasets and
+metrics to an Axiom Metrics dataset. A single generic product configuration is
+then sufficient:
+
 ```bash
-npx --yes ideawave@latest --dev
-npx ideawave --help
-npx ideawave --version
+IDEAWAVE_TELEMETRY_MODE=continuous
+IDEAWAVE_TELEMETRY_LOGS=enabled
+OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
 ```
 
-## Troubleshooting
+A direct Axiom setup is supported only for an explicit developer-owned local
+validation. It requires three dataset routes because Axiom signal datasets are
+not interchangeable. Header values use OTLP's comma-separated percent-encoded
+format and are never retained in application state:
+
+```bash
+IDEAWAVE_TELEMETRY_MODE=continuous
+IDEAWAVE_TELEMETRY_LOGS=enabled
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://api.axiom.co/v1/logs
+OTEL_EXPORTER_OTLP_LOGS_HEADERS='Authorization=Bearer%20LOCAL_TOKEN,X-Axiom-Dataset=ideawave-local-logs'
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.axiom.co/v1/traces
+OTEL_EXPORTER_OTLP_TRACES_HEADERS='Authorization=Bearer%20LOCAL_TOKEN,X-Axiom-Dataset=ideawave-local-traces'
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.axiom.co/v1/metrics
+OTEL_EXPORTER_OTLP_METRICS_HEADERS='Authorization=Bearer%20LOCAL_TOKEN,X-Axiom-Dataset=ideawave-local-metrics'
+```
+
+Do not commit credentials or ship a shared token. Export applies only to future
+approved records; retained local Activity history is never backfilled.
+
+## Compatibility
+
+Runtime configuration remains compatible with the existing CLI:
+
+- `IDEAWAVE_RUNTIME_CONFIG_PATH` overrides `runtimes.json`.
+- Linux defaults to `${XDG_CONFIG_HOME:-~/.config}/ideawave/runtimes.json`.
+- macOS defaults to `~/Library/Application Support/ideawave/runtimes.json`.
+- Windows defaults to `%APPDATA%\ideawave\runtimes.json`.
+- `IDEAWAVE_ACP_BRIDGE_CACHE_DIR` overrides managed bridge state.
+- Browser bridge candidates remain `127.0.0.1:43275-43277`.
+- The preferred MCP port remains `127.0.0.1:43274`; set
+  `IDEAWAVE_MCP_PORT` to another loopback port, or `0` for an OS-assigned port.
 
-If a runtime appears unavailable, confirm its command is on your `PATH` and that you are signed in to that tool.
+The application validates version-1 runtime files, relay messages, runtime RPC
+requests, agent run payloads, and MCP context with Effect Schema. Missing files
+decode to the legacy empty default. Invalid external data produces typed
+boundary/configuration failures.
 
-For supported runtimes, the CLI fetches small ACP bridge packages on first use. npm caches them, so later runs are fast. If npm's cache was cleared, keep the CLI running and retry after the bridge downloads again.
+## Rollout
+
+Release qualification, fallback, persistence, platform checks, and live browser
+plus telemetry correlation steps are defined in [the rollout runbook](docs/rollout.md).
+The legacy CLI must remain available until every gate in that runbook has recorded
+evidence for the release candidate.
+
+## Phase Decisions
+
+- The browser remains the authenticated board tool host. Browser session IDs
+  are correlation data, not authentication.
+- Effect is pinned to `4.0.0-beta.102`; v3 APIs are not used.
+- `@effect/platform-node-shared` is an exact direct dependency and a workspace
+  resolution. The platform-bun prerelease range otherwise lets package managers
+  install a newer Effect prerelease beside the pinned beta, which breaks
+  service-context identity at runtime.
+- Product telemetry uses only an explicit operational metadata allowlist.
+  Prompts, responses, tool data, credentials, environment values, paths, and
+  URLs are prohibited.
+- Direct Axiom credentials may be used only in explicit developer-owned local
+  experiments. The product path requires an ingest proxy or operator-owned
+  collector and warns when a direct credential is present.
+- Browser automation remains isolated behind the Phase 5 iframe proxy and
+  capture service boundaries.
+- First-run setup verifies an explicit user selection and writes it through the
+  version-1 runtime configuration contract. Running the passive `Doctor` service
+  itself is non-mutating.
+- The original branded sidebar and activity dashboard remains the primary TUI.
+  Doctor, sessions, runs, logs, and configuration extend that shell rather than
+  replace it with single-purpose primary screens.
+
+## Architecture
+
+- `src/domain/` contains compatibility schemas, typed errors, shared snapshots,
+  activity events, and telemetry policy.
+- `src/services/` contains Effect service contracts and Bun production layers.
+- `src/ui/` adapts the managed Effect runtime to Solid subscriptions and
+  commands.
+- Solid renders authoritative snapshots and a separate bounded activity stream;
+  it does not own discovery timers or infrastructure state.
+- `src/services/mock.ts` provides a deterministic mock `Application` layer for
+  presentation work.
+
+Interactive startup uses one `ManagedRuntime`, one OpenTUI renderer scope, and
+`BunRuntime.runMain` inside the compiled host. The public package launcher and
+managed ACP/Playwright children use Node. The top-level doctor command never
+imports the TUI module.
+OpenTUI signal handlers are disabled so Effect owns
+`SIGINT`/`SIGTERM`; renderer destruction restores the terminal and closes the
+runtime scope.
+
+## Verification
+
+```bash
+bun run check
+bun test
+bun run release:pack --target current
+bun run validate:pilotty # when pilotty is installed
+```
 
-The CLI advertises `browser-proxy-v6` and `browser-dom-snapshot-v1` so browser
-cards can share one local browser profile, route pages and subresources through
-the local browser-kit proxy, and publish a sanitized read-only fallback for
-collaborators. The normal command
-keeps screenshot capture available. `--dev` skips screenshot-engine setup and
-allows Railway PR previews for browser-card development.
+The suite covers compatibility fixtures, typed invalid boundaries, resolver
+precedence, passive/deep doctor behavior, interruption cleanup, cross-process
+bridge locks, first-run reselection, privacy redaction, scoped shutdown, and
+wide/narrow/tiny OpenTUI rendering.

package/bin/ideawave.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { accessSync, constants, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isPathInside, launcherRuntimeError } from "./launcher-core.mjs";
+import { detectLinuxLibc, resolveHostTarget } from "./platform.mjs";
+
+const require = createRequire(import.meta.url);
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function readManifest(filename, label) {
+  try {
+    const value = JSON.parse(readFileSync(filename, "utf8"));
+    if (!value || typeof value !== "object") throw new Error("not an object");
+    return value;
+  } catch (error) {
+    throw new Error(`${label} manifest is unreadable at ${filename}: ${String(error)}`);
+  }
+}
+
+function resolveDistribution() {
+  const manifest = readManifest(path.join(packageRoot, "package.json"), "IdeaWave launcher");
+  if (manifest.name !== "ideawave" || typeof manifest.version !== "string" || !manifest.version) {
+    throw new Error("IdeaWave launcher manifest has an invalid package name or version. Reinstall IdeaWave.");
+  }
+
+  const libc = process.platform === "linux" ? detectLinuxLibc() : null;
+  const target = resolveHostTarget({
+    platform: process.platform,
+    architecture: process.arch,
+    libc,
+  });
+  if (!target) {
+    const tuple =
+      process.platform === "linux"
+        ? `${process.platform}/${process.arch}/${libc ?? "unknown-libc"}`
+        : `${process.platform}/${process.arch}`;
+    throw new Error(
+      `IdeaWave does not have a native host for ${tuple}. Supported targets are macOS and Linux glibc/musl on x64 or arm64, and Windows on x64.`,
+    );
+  }
+
+  let hostManifestPath;
+  try {
+    hostManifestPath = require.resolve(`${target.packageName}/package.json`);
+  } catch {
+    throw new Error(
+      `IdeaWave's ${target.key} host package is missing (expected ${target.packageName}@${manifest.version}). ` +
+        `Reinstall with optional dependencies enabled, for example \`npm install ideawave@${manifest.version} --include=optional\`.`,
+    );
+  }
+  const hostManifest = readManifest(hostManifestPath, `IdeaWave ${target.key} host`);
+  if (hostManifest.name !== target.packageName) {
+    throw new Error(
+      `IdeaWave host package mismatch: expected ${target.packageName}, found ${hostManifest.name ?? "an unnamed package"}. Reinstall IdeaWave.`,
+    );
+  }
+  if (hostManifest.version !== manifest.version) {
+    throw new Error(
+      `IdeaWave host version mismatch: launcher ${manifest.version}, host ${hostManifest.version ?? "unknown"}. ` +
+        "Clear the package-runner cache and reinstall IdeaWave.",
+    );
+  }
+
+  const hostRoot = path.dirname(hostManifestPath);
+  const executable = path.resolve(hostRoot, ...target.executable.split("/"));
+  if (!isPathInside(hostRoot, executable)) {
+    throw new Error(`IdeaWave host package ${target.packageName} declared an unsafe executable path.`);
+  }
+  try {
+    accessSync(executable, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+  } catch {
+    throw new Error(`IdeaWave's native host is missing or not executable at ${executable}. Reinstall IdeaWave.`);
+  }
+
+  let playwrightManifestPath;
+  try {
+    playwrightManifestPath = require.resolve("playwright-core/package.json");
+  } catch {
+    throw new Error("IdeaWave's Playwright runtime sidecar is missing. Reinstall IdeaWave.");
+  }
+  const playwrightManifest = readManifest(playwrightManifestPath, "IdeaWave Playwright sidecar");
+  const expectedPlaywright = manifest.dependencies?.["playwright-core"];
+  if (typeof expectedPlaywright !== "string" || playwrightManifest.version !== expectedPlaywright) {
+    throw new Error(
+      `IdeaWave Playwright sidecar mismatch: expected ${expectedPlaywright ?? "an exact pinned version"}, ` +
+        `found ${playwrightManifest.version ?? "unknown"}. Reinstall IdeaWave.`,
+    );
+  }
+
+  return {
+    executable,
+    manifest,
+    playwrightRoot: path.dirname(playwrightManifestPath),
+    target,
+  };
+}
+
+const runtimeError = launcherRuntimeError();
+if (runtimeError) {
+  fail(runtimeError);
+} else {
+  try {
+    const distribution = resolveDistribution();
+    const child = spawn(distribution.executable, process.argv.slice(2), {
+      cwd: process.cwd(),
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        IDEAWAVE_DISTRIBUTION_MODE: "standalone",
+        IDEAWAVE_LAUNCHER_NODE_PATH: process.execPath,
+        IDEAWAVE_LAUNCHER_NODE_VERSION: process.version,
+        IDEAWAVE_PLAYWRIGHT_CORE_PATH: distribution.playwrightRoot,
+        IDEAWAVE_PRODUCT_VERSION: distribution.manifest.version,
+      },
+    });
+
+    const signalHandlers = new Map();
+    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+      if (process.platform === "win32" && signal === "SIGHUP") continue;
+      const handler = () => {
+        if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+      };
+      signalHandlers.set(signal, handler);
+      process.on(signal, handler);
+    }
+    const removeSignalHandlers = () => {
+      for (const [signal, handler] of signalHandlers) process.removeListener(signal, handler);
+      signalHandlers.clear();
+    };
+
+    child.once("error", (error) => {
+      removeSignalHandlers();
+      fail(`IdeaWave failed to start its ${distribution.target.key} host: ${String(error)}`);
+    });
+    child.once("exit", (code, signal) => {
+      removeSignalHandlers();
+      if (signal && process.platform !== "win32") {
+        process.kill(process.pid, signal);
+        return;
+      }
+      process.exitCode = code ?? (signal ? 1 : 0);
+    });
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}

package/bin/launcher-core.mjs

@@ -0,0 +1,35 @@
+import path from "node:path";
+
+export const MINIMUM_NODE_MAJOR = 22;
+
+export function parseNodeMajor(version) {
+  const match = /^v?(\d+)(?:\.|$)/.exec(String(version));
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * @param {{ nodeVersion?: string, bunVersion?: string | null, runtimeName?: string } | undefined} options
+ */
+export function launcherRuntimeError(options = {}) {
+  const {
+    nodeVersion = process.version,
+    bunVersion = process.versions?.bun,
+    runtimeName = process.release?.name,
+  } = options;
+  if (bunVersion) {
+    return "IdeaWave's launcher must run on Node.js, not Bun. Run `bunx ideawave` without `--bun`, or use `npx ideawave`.";
+  }
+  if (runtimeName !== "node") {
+    return `IdeaWave's launcher requires Node.js 22 or newer; detected ${runtimeName || "an unknown runtime"}.`;
+  }
+  const major = parseNodeMajor(nodeVersion);
+  if (major === null || major < MINIMUM_NODE_MAJOR) {
+    return `IdeaWave requires Node.js 22 or newer; this launcher is using ${nodeVersion || "an unknown version"}.`;
+  }
+  return null;
+}
+
+export function isPathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}

package/bin/platform.mjs

@@ -0,0 +1,100 @@
+const host = (key, options) => Object.freeze({ key, ...options });
+
+const HOSTS = Object.freeze({
+  "darwin-arm64": host("darwin-arm64", {
+    packageName: "ideawave-host-darwin-arm64",
+    bunTarget: "bun-darwin-arm64",
+    os: "darwin",
+    cpu: "arm64",
+    executable: "bin/ideawave-host",
+  }),
+  "darwin-x64": host("darwin-x64", {
+    packageName: "ideawave-host-darwin-x64",
+    bunTarget: "bun-darwin-x64-baseline",
+    os: "darwin",
+    cpu: "x64",
+    executable: "bin/ideawave-host",
+  }),
+  "linux-arm64-glibc": host("linux-arm64-glibc", {
+    packageName: "ideawave-host-linux-arm64",
+    bunTarget: "bun-linux-arm64",
+    os: "linux",
+    cpu: "arm64",
+    libc: "glibc",
+    executable: "bin/ideawave-host",
+  }),
+  "linux-arm64-musl": host("linux-arm64-musl", {
+    packageName: "ideawave-host-linux-arm64-musl",
+    bunTarget: "bun-linux-arm64-musl",
+    os: "linux",
+    cpu: "arm64",
+    libc: "musl",
+    executable: "bin/ideawave-host",
+  }),
+  "linux-x64-glibc": host("linux-x64-glibc", {
+    packageName: "ideawave-host-linux-x64",
+    bunTarget: "bun-linux-x64-baseline",
+    os: "linux",
+    cpu: "x64",
+    libc: "glibc",
+    executable: "bin/ideawave-host",
+  }),
+  "linux-x64-musl": host("linux-x64-musl", {
+    packageName: "ideawave-host-linux-x64-musl",
+    bunTarget: "bun-linux-x64-baseline-musl",
+    os: "linux",
+    cpu: "x64",
+    libc: "musl",
+    executable: "bin/ideawave-host",
+  }),
+  "win32-x64": host("win32-x64", {
+    packageName: "ideawave-host-windows",
+    bunTarget: "bun-windows-x64-baseline",
+    os: "win32",
+    cpu: "x64",
+    executable: "bin/ideawave-host.exe",
+  }),
+});
+
+export const SUPPORTED_HOSTS = HOSTS;
+
+/**
+ * @param {{
+ *   platform?: string,
+ *   report?: { header?: Record<string, unknown> } | null,
+ * } | undefined} options
+ */
+export function detectLinuxLibc(options = {}) {
+  const { platform = process.platform, report = undefined } = options;
+  if (platform !== "linux") return null;
+
+  let runtimeReport = report;
+  if (runtimeReport === undefined) {
+    try {
+      runtimeReport = process.report?.getReport();
+    } catch {
+      return null;
+    }
+  }
+  if (!runtimeReport || typeof runtimeReport !== "object") return null;
+
+  const header = runtimeReport.header;
+  if (!header || typeof header !== "object") return null;
+  if (typeof header.glibcVersionRuntime === "string" && header.glibcVersionRuntime) {
+    return "glibc";
+  }
+
+  // Node's Linux diagnostic report exposes glibcVersionRuntime only on glibc.
+  // A real Linux report with no such field is therefore a musl runtime. An
+  // absent/malformed report remains unknown instead of silently choosing musl.
+  return typeof header.nodejsVersion === "string" || typeof header.nodeVersion === "string" ? "musl" : null;
+}
+
+export function resolveHostTarget({
+  platform = process.platform,
+  architecture = process.arch,
+  libc = platform === "linux" ? detectLinuxLibc({ platform }) : null,
+} = {}) {
+  const key = platform === "linux" ? `${platform}-${architecture}-${libc ?? "unknown"}` : `${platform}-${architecture}`;
+  return HOSTS[key] ?? null;
+}

package/package.json

@@ -1,44 +1,49 @@
 {
   "name": "ideawave",
-  "version": "0.0.103",
-  "description": "IdeaWave CLI",
+  "version": "0.0.105",
+  "description": "IdeaWave local agent host and terminal UI",
   "type": "module",
+  "license": "UNLICENSED",
   "bin": {
-    "ideawave": "dist/index.mjs"
+    "ideawave": "bin/ideawave.mjs"
   },
   "files": [
-    "dist/index.mjs",
+    "bin",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "homepage": "https://ideawave.app",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/LoopedIn-ai/ideawave-app.git",
-    "directory": "apps/web/npm/ideawave"
+    "directory": "apps/tui"
   },
   "bugs": {
     "url": "https://github.com/LoopedIn-ai/ideawave-app/issues"
   },
   "keywords": [
     "ideawave",
-    "cli",
+    "tui",
     "agent",
     "whiteboard",
-    "mcp"
+    "mcp",
+    "acp"
   ],
-  "license": "UNLICENSED",
   "dependencies": {
-    "@agentclientprotocol/sdk": "^1.3.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "css-tree": "^3.2.1",
-    "playwright-core": "1.60.0",
-    "ws": "^8.21.0",
-    "zod": "^4.3.6"
+    "playwright-core": "1.62.1"
   },
-  "publishConfig": {
-    "access": "public"
+  "optionalDependencies": {
+    "ideawave-host-darwin-arm64": "0.0.105",
+    "ideawave-host-darwin-x64": "0.0.105",
+    "ideawave-host-linux-arm64": "0.0.105",
+    "ideawave-host-linux-arm64-musl": "0.0.105",
+    "ideawave-host-linux-x64": "0.0.105",
+    "ideawave-host-linux-x64-musl": "0.0.105",
+    "ideawave-host-windows": "0.0.105"
   }
 }