heyspex 0.1.0 → 0.2.1

package/scripts/hs-auto.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * hs auto — resolve /hs-auto [filename] and print dispatch plan.
+ */
+import process from 'node:process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveHsAutoEntry } from './hs-auto-resolve.mjs';
+
+const HELP = `hs auto — autonomous COO dispatch resolver
+
+Usage:
+  hs auto [filename] [--json] [--dry-run]
+  hs auto --help
+
+Arguments:
+  filename   Optional. One of:
+               - vault spec id (HS-…-TASK-… / HS-…-EPIC-… / HS-…-DIAG-… / HS-…-RES-…)
+               - path to a spec .md under specs/
+               - path to a source file (matched via task target: frontmatter)
+             Diagnose + research specs enter the source_plan → epic → tasks → dispatch pipeline.
+             Omit to enter discovery mode (backlog-selector after pre-flight).
+
+Flags:
+  --json       Machine-readable JSON on stdout
+  --dry-run    Same as default (never dispatches — prints plan only)
+  --help, -h   Show this help
+`;
+
+export const EXIT = {
+  OK: 0,
+  USAGE: 1,
+  RESOLVE_FAILED: 2,
+};
+
+/** @param {string[]} argv tokens after "auto" */
+export function parseAutoArgs(argv) {
+  let filename;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--dry-run') continue;
+    if (a.startsWith('-')) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${a}` } };
+    }
+    if (!filename) {
+      filename = a;
+      continue;
+    }
+    return { error: { code: EXIT.USAGE, message: `unexpected argument: ${a}` } };
+  }
+  return { args: { filename, json } };
+}
+
+const PREFLIGHT = [
+  'node dev-factory/fleet/manager.mjs --status',
+  'node dev-factory/pipeline/backlog-selector.mjs --real',
+  'node dev-factory/router.mjs --self-test',
+  'node dev-factory/lib/coo-detect.mjs --self-test',
+];
+
+async function main() {
+  const parsed = parseAutoArgs(process.argv.slice(2));
+  if (parsed.help) {
+    process.stdout.write(`${HELP}\n`);
+    process.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process.stderr.write(`hs auto: ${parsed.error.message}\n`);
+    process.exit(parsed.error.code);
+  }
+
+  const vaultRoot = process.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process.stderr.write('hs auto: HS_VAULT_ROOT is not set (the dispatcher must pass it).\n');
+    process.exit(EXIT.USAGE);
+  }
+
+  const resolved = resolveHsAutoEntry(vaultRoot, parsed.args.filename);
+  const payload = {
+    ...resolved,
+    preflight: PREFLIGHT,
+    discover_command: 'node dev-factory/pipeline/backlog-selector.mjs --real',
+    overnight_command:
+      'node dev-factory/pipeline/run-overnight.mjs --concurrent --max-tasks 5 --max-concurrent 4',
+  };
+
+  if (parsed.args.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.exit(resolved.error ? EXIT.RESOLVE_FAILED : EXIT.OK);
+  }
+
+  if (resolved.error) {
+    process.stderr.write(`hs auto: ${resolved.error} — ${resolved.message}\n`);
+    process.exit(EXIT.RESOLVE_FAILED);
+  }
+
+  const lines = ['# /hs-auto plan', ''];
+  lines.push('## Pre-flight');
+  for (const cmd of PREFLIGHT) lines.push(`- \`${cmd}\``);
+  lines.push('');
+  if (resolved.mode === 'discover') {
+    lines.push('## Discovery (no filename)');
+    lines.push(`- \`${payload.discover_command}\``);
+  } else if (resolved.mode === 'source_plan') {
+    lines.push(`## Source plan — \`${resolved.spec_id}\` (${resolved.source_kind})`);
+    lines.push(resolved.message ?? 'File remediation epic + tasks, then re-resolve.');
+    if (resolved.re_resolve_command) lines.push(`- Re-resolve: \`${resolved.re_resolve_command}\``);
+  } else if (resolved.mode === 'breakdown') {
+    lines.push(`## Breakdown — \`${resolved.spec_id}\``);
+    lines.push(`- \`${resolved.breakdown_command}\``);
+  } else if (resolved.mode === 'dispatch') {
+    lines.push(`## Dispatch — \`${resolved.spec_id}\``);
+    lines.push(`- target: \`${resolved.target}\``);
+    lines.push(`- \`${resolved.dispatch_command}\``);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+  process.exit(EXIT.OK);
+}
+
+const invoked = process.argv[1]
+  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (invoked) {
+  main().catch((err) => {
+    process.stderr.write(`hs auto: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(EXIT.RESOLVE_FAILED);
+  });
+}

package/scripts/hs-capture-cli.mjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * hs capture — CLI capture into the HeySpex console drafts inbox.
+ *
+ * The CLI face of the multi-capture workflow (companion voice + browser are
+ * the other faces). Posts a heyspex.capture/0.1 envelope to the console's
+ * POST /api/drafts — the same wire shape the companion's
+ * DraftsSpexConsoleClient sends — so CLI captures land in the same inbox and
+ * can join the same visual capture groups.
+ *
+ * Usage:
+ *   hs capture "<text>" [--title <t>] [--add] [--json]
+ *   hs capture --clipboard [--title <t>] [--add] [--json]
+ *   hs capture --file <path> [--title <t>] [--add] [--json]
+ *
+ * --add chains this capture into the PREVIOUS CLI capture's group (within a
+ * 2-minute window) — the "add another?" gesture. Group state lives in
+ * .heyspex/cli-capture-group.json.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { randomUUID } from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from "./lib/console-url-resolver.mjs";
+import { heyspexHome } from "./lib/heyspex-home.mjs";
+import { stashCaptureArgs } from "../vendor/heyspex-mcp/capture-outbox.mjs";
+import { readBearerToken } from "../vendor/heyspex-mcp/credentials.mjs";
+
+/**
+ * The bearer for a paired cloud console (`/api/drafts`-adjacent surfaces need
+ * it; a local dev console ignores it) — the ONE shared reader
+ * (`vendor/heyspex-mcp/credentials.mjs`,
+ * [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]), with
+ * `HEYSPEX_HOME` honoured through `heyspexHome()`.
+ */
+function readCredentialsMcpToken() {
+  return readBearerToken({ homeDir: heyspexHome() });
+}
+
+const CHAIN_WINDOW_MS = 2 * 60 * 1000; // keep in sync with CaptureGroupTracker.ChainWindow
+
+function usage() {
+  process.stdout.write(
+    [
+      "hs capture — capture text/clipboard/file into the console drafts inbox",
+      "",
+      "Usage:",
+      '  hs capture "<text>" [--title <t>] [--add] [--json]',
+      "  hs capture --clipboard [--title <t>] [--add] [--json]",
+      "  hs capture --file <path> [--title <t>] [--add] [--json]",
+      "",
+      "  --add      Chain into the previous CLI capture's group (within 2 minutes)",
+      "  --title    Optional capture title",
+      "  --url      Base console URL (default: shared resolver — HEYSPEX_CONSOLE_URL, then paired console_url in ~/.heyspex/credentials.yaml, then the repo discovery file, then http://localhost:3000)",
+      "  --json     Machine-readable result",
+      "",
+    ].join("\n"),
+  );
+}
+
+function parseArgs(argv) {
+  const opts = {
+    text: null, clipboard: false, file: null,
+    title: null, add: false, json: false,
+    url: null, // resolved via the shared console-url resolver unless --url overrides
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true };
+    else if (a === "--clipboard") opts.clipboard = true;
+    else if (a === "--file") opts.file = argv[++i];
+    else if (a === "--title") opts.title = argv[++i];
+    else if (a === "--url") opts.url = argv[++i];
+    else if (a === "--add") opts.add = true;
+    else if (a === "--json") opts.json = true;
+    else if (!a.startsWith("--") && opts.text === null) opts.text = a;
+    else return { error: `unknown argument: ${a}` };
+  }
+  return { opts };
+}
+
+function readClipboard() {
+  if (process.platform !== "win32") {
+    throw new Error("--clipboard is only implemented on Windows for now");
+  }
+  return execFileSync(
+    "powershell.exe",
+    ["-NoProfile", "-Command", "Get-Clipboard -Raw"],
+    { encoding: "utf8", windowsHide: true },
+  );
+}
+
+/** Same semantics as the companion's CaptureGroupTracker: every capture gets
+ * a group id; --add joins the previous group (window permitting). */
+function nextGroup(vaultRoot, chain) {
+  const stateDir = path.join(vaultRoot, ".heyspex");
+  const stateFile = path.join(stateDir, "cli-capture-group.json");
+  let prev = null;
+  try {
+    prev = JSON.parse(readFileSync(stateFile, "utf8"));
+  } catch { /* first run / corrupt — start fresh */ }
+
+  const now = Date.now();
+  let group;
+  if (chain && prev?.groupId && now - (prev.at ?? 0) <= CHAIN_WINDOW_MS) {
+    group = { groupId: prev.groupId, seq: (prev.seq ?? 1) + 1, at: now };
+  } else {
+    group = { groupId: randomUUID().replaceAll("-", "").slice(0, 12), seq: 1, at: now };
+  }
+  try {
+    if (!existsSync(stateDir)) mkdirSync(stateDir, { recursive: true });
+    writeFileSync(stateFile, JSON.stringify(group));
+  } catch { /* stateless fallback — capture still goes through */ }
+  return group;
+}
+
+/** True when `url`'s hostname is a loopback address — localhost, 127.0.0.1,
+ * or [::1] (bracketed or not). Non-loopback hosts (a paired cloud console,
+ * a LAN address, etc.) never get the hosted-console retry: if a deliberately
+ * configured console is unreachable, that's a real outage to surface, not a
+ * dead local dev server to route around. */
+function isLoopback(url) {
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * POST a capture to `url`, with a local-dead-console fallback ladder:
+ *   1. POST to `url` (the resolved console — often the local dev server).
+ *   2. If that fails to CONNECT (not an HTTP error) and `url` is loopback,
+ *      retry once against `hostedUrl` with the identical body/headers/trace id.
+ *   3. If the hosted retry also fails to connect, stash the payload to the
+ *      vault's disk outbox via `stash` and report that instead of throwing.
+ *
+ * A non-loopback URL that fails to connect is never retried or stashed — the
+ * caller configured that console on purpose, so an outage there is reported
+ * as-is. An HTTP error response (4xx/5xx) from either console is likewise
+ * reported as-is, never retried or stashed — the console IS reachable.
+ *
+ * `fetchImpl` and `stash` are injectable so tests never open a real socket
+ * or touch the real outbox directory.
+ */
+export async function postCaptureWithFallback({
+  url,
+  payload,
+  token,
+  vaultRoot,
+  fetchImpl = fetch,
+  hostedUrl = DEFAULT_CONSOLE_URL,
+  stash = stashCaptureArgs,
+}) {
+  const traceId = payload.trace_id;
+  const body = JSON.stringify({ traceId, payload, errors: [] });
+  const headers = {
+    "content-type": "application/json",
+    "x-heyspex-trace-id": traceId,
+    ...(token ? { authorization: `Bearer ${token}` } : {}),
+  };
+
+  const post = (targetUrl) =>
+    fetchImpl(`${targetUrl.replace(/\/$/, "")}/api/drafts`, { method: "POST", headers, body });
+
+  let res;
+  let consoleUrl = url;
+  try {
+    res = await post(url);
+  } catch (err) {
+    if (!isLoopback(url)) {
+      return { kind: "connect-error", url, err };
+    }
+    try {
+      res = await post(hostedUrl);
+      consoleUrl = hostedUrl;
+    } catch (err2) {
+      const stashed = stash(vaultRoot, { user_quote: payload.article_text });
+      return {
+        kind: "stashed",
+        files: stashed.map((e) => e.path),
+        primaryErr: err,
+        hostedErr: err2,
+      };
+    }
+  }
+
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => "");
+    return { kind: "http-error", status: res.status, body: errBody, url: consoleUrl };
+  }
+
+  const result = await res.json().catch(() => ({}));
+  return { kind: "ok", consoleUrl, retried: consoleUrl !== url, result };
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) { usage(); return; }
+  if (parsed.error) {
+    process.stderr.write(`hs capture: ${parsed.error}\n`);
+    process.exit(2);
+  }
+  const opts = parsed.opts;
+
+  let content, contentSource;
+  if (opts.clipboard) {
+    content = readClipboard();
+    contentSource = "cli-clipboard";
+  } else if (opts.file) {
+    // hs.mjs runs this script with cwd=PKG_ROOT (the platform checkout) and
+    // forwards the caller's real invocation directory as HS_INVOKED_CWD —
+    // resolve the user-typed --file against THAT, not this process's own
+    // (wrong) cwd, so `hs capture --file <relative>` finds the file where
+    // the caller stood rather than reporting it missing at a platform path.
+    const invokedCwd = process.env.HS_INVOKED_CWD?.trim() || process.cwd();
+    const p = path.resolve(invokedCwd, opts.file);
+    if (!existsSync(p)) {
+      process.stderr.write(`hs capture: file not found: ${p}\n`);
+      process.exit(1);
+    }
+    content = readFileSync(p, "utf8");
+    contentSource = "cli-file";
+    opts.title ??= path.basename(p);
+  } else if (opts.text) {
+    content = opts.text;
+    contentSource = "cli";
+  } else {
+    usage();
+    process.exit(2);
+  }
+
+  if (!content || !content.trim()) {
+    process.stderr.write("hs capture: nothing to capture (empty content)\n");
+    process.exit(1);
+  }
+
+  const vaultRoot = process.env.HS_VAULT_ROOT ?? process.cwd();
+  opts.url ??= resolveConsoleUrl({ repoRoot: vaultRoot });
+  const group = nextGroup(vaultRoot, opts.add);
+  const traceId = `cli-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+
+  const payload = {
+    schema: "heyspex.capture/0.1",
+    trace_id: traceId,
+    tier: 3,
+    captured_at: new Date().toISOString(),
+    capture_channel: "cli",
+    source: contentSource,
+    content_source: contentSource,
+    title: opts.title,
+    article_text: content,
+    degraded: null,
+    errors: null,
+    capture_group_id: group.groupId,
+    capture_group_seq: group.seq,
+  };
+
+  const mcpToken = readCredentialsMcpToken();
+  const outcome = await postCaptureWithFallback({
+    url: opts.url,
+    payload,
+    token: mcpToken,
+    vaultRoot,
+  });
+
+  if (outcome.kind === "connect-error") {
+    process.stderr.write(
+      `hs capture: console unreachable at ${outcome.url} (${outcome.err.cause?.code ?? outcome.err.message})\n`,
+    );
+    process.exit(1);
+  }
+
+  if (outcome.kind === "http-error") {
+    process.stderr.write(
+      `hs capture: POST /api/drafts failed ${outcome.status}: ${outcome.body.slice(0, 300)}\n`,
+    );
+    process.exit(1);
+  }
+
+  if (outcome.kind === "stashed") {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        ok: true, stashed: true, traceId, files: outcome.files,
+      }, null, 2) + "\n");
+    } else {
+      process.stdout.write(
+        `hs capture: local and hosted consoles both unreachable — saved to disk outbox instead\n` +
+        outcome.files.map((f) => `  ${f}`).join("\n") + "\n",
+      );
+    }
+    return;
+  }
+
+  // outcome.kind === "ok"
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      ok: true, traceId, consoleUrl: outcome.consoleUrl,
+      group: group.groupId, seq: group.seq,
+      chars: content.length, response: outcome.result,
+    }, null, 2) + "\n");
+  } else {
+    const chained = group.seq > 1 ? ` (group ${group.groupId} · #${group.seq})` : "";
+    const via = outcome.retried
+      ? ` — local console unreachable, sent to ${outcome.consoleUrl} instead`
+      : "";
+    process.stdout.write(
+      `captured ${content.length} chars → drafts${chained}${via}\n` +
+      `  add another: hs capture --clipboard --add  (within 2 minutes)\n`,
+    );
+  }
+}
+
+// Guard so this module can be `import`ed (e.g. by hs-capture-cli.test.mjs)
+// without running main() — bin/hs.mjs spawns this file as a child process
+// with the file path as argv[1], so this only fires under that spawn.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((err) => {
+    process.stderr.write(`hs capture: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/scripts/hs-classifier.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * hs classifier stats — read-only view of HeySpex Intent Classifier decisions.
+ * Dispatched from bin/hs.mjs. Reads .heyspex/intent-classifier-history.jsonl (the
+ * append-only decision log the classifier hooks write) and prints counts per behavior
+ * and layer plus the most recent fires. Pure read; never writes, never networks.
+ *
+ * Usage:
+ *   hs classifier stats [--json] [--recent N]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const HELP = `hs classifier stats — HeySpex Intent Classifier decision stats (read-only)
+
+Usage:
+  hs classifier stats [--json] [--recent N]
+
+Reads .heyspex/intent-classifier-history.jsonl. Shows totals per behavior + layer
+(lexical vs semantic) + decision (fire / self_check_injected / below_threshold /
+error), and the N most recent fires (default 10). self_check_injected is the default
+semantic-layer signal: an OFFER count (how often the deterministic self-check block was
+injected), not an agent-fire count — the agent's own judgment decides whether to act.
+`;
+
+function historyPath() {
+  const root = process.env.HS_VAULT_ROOT || process.env.HEYSPEX_VAULT_ROOT || REPO_ROOT;
+  return path.join(root, '.heyspex', 'intent-classifier-history.jsonl');
+}
+
+function readRows() {
+  let raw;
+  try {
+    raw = fs.readFileSync(historyPath(), 'utf8');
+  } catch {
+    return [];
+  }
+  const rows = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const r = JSON.parse(t);
+      if (r && r.event_kind === 'intent_classifier.decision') rows.push(r);
+    } catch {
+      /* skip a corrupt line — never throw */
+    }
+  }
+  return rows;
+}
+
+function main(argv) {
+  const args = argv[0] === 'classifier' ? argv.slice(1) : argv.slice();
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  const verb = args.find((a) => !a.startsWith('--')) || 'stats';
+  if (verb !== 'stats') {
+    process.stderr.write(`hs classifier: unknown subcommand \`${verb}\` (expected: stats)\n${HELP}`);
+    process.exit(2);
+  }
+  const asJson = args.includes('--json');
+  const recentIdx = args.indexOf('--recent');
+  const recentN = recentIdx >= 0 && args[recentIdx + 1] ? Math.max(0, parseInt(args[recentIdx + 1], 10) || 0) : 10;
+
+  const rows = readRows();
+
+  // Aggregate: behavior(rule) → { fire, self_check_injected, below_threshold, error, lexical, semantic }.
+  // self_check_injected is the DEFAULT semantic-layer signal ([[HS-M4PN-TASK]]): the
+  // hook injected a deterministic self-check block and the agent (not a model) decided
+  // whether to act. There is no synchronous confidence/verdict, so this is an OFFER
+  // count (fire rate of the injection), not a fire count of a behavior. Actual fires by
+  // the agent are observable downstream (capture-history, settings-history, defer edits).
+  const byBehavior = {};
+  const layerTotals = { lexical: 0, semantic: 0 };
+  const decisionTotals = { fire: 0, self_check_injected: 0, below_threshold: 0, error: 0 };
+  for (const r of rows) {
+    const key = r.rule || 'unknown';
+    const b = (byBehavior[key] ??= { fire: 0, self_check_injected: 0, below_threshold: 0, error: 0, lexical: 0, semantic: 0 });
+    if (r.decision && b[r.decision] !== undefined) b[r.decision] += 1;
+    if (r.layer && b[r.layer] !== undefined) b[r.layer] += 1;
+    if (r.layer && layerTotals[r.layer] !== undefined) layerTotals[r.layer] += 1;
+    if (r.decision && decisionTotals[r.decision] !== undefined) decisionTotals[r.decision] += 1;
+  }
+
+  const recentFires = rows
+    .filter((r) => r.decision === 'fire')
+    .slice(-recentN)
+    .reverse()
+    .map((r) => ({ timestamp: r.timestamp, behavior: r.rule, layer: r.layer, confidence: r.confidence ?? null }));
+
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify(
+        { total: rows.length, layerTotals, decisionTotals, byBehavior, recentFires },
+        null,
+        2,
+      ) + '\n',
+    );
+    process.exit(0);
+  }
+
+  const out = [];
+  out.push(`HeySpex Intent Classifier — ${rows.length} decision(s) logged`);
+  out.push(`  layers:    lexical ${layerTotals.lexical} · semantic ${layerTotals.semantic}`);
+  out.push(`  decisions: fire ${decisionTotals.fire} · self_check_injected ${decisionTotals.self_check_injected} · below_threshold ${decisionTotals.below_threshold} · error ${decisionTotals.error}`);
+  out.push('');
+  out.push('  per behavior:');
+  const names = Object.keys(byBehavior).sort();
+  if (names.length === 0) {
+    out.push('    (no decisions logged yet)');
+  } else {
+    for (const name of names) {
+      const b = byBehavior[name];
+      out.push(`    ${name.padEnd(26)} fire ${b.fire} · self-check ${b.self_check_injected} · below ${b.below_threshold} · error ${b.error}  (lexical ${b.lexical} / semantic ${b.semantic})`);
+    }
+  }
+  if (recentFires.length) {
+    out.push('');
+    out.push(`  recent fires (last ${recentFires.length}):`);
+    for (const f of recentFires) {
+      const conf = f.confidence !== null ? ` conf=${f.confidence}` : '';
+      out.push(`    ${f.timestamp}  ${String(f.behavior).padEnd(26)} ${f.layer}${conf}`);
+    }
+  }
+  process.stdout.write(out.join('\n') + '\n');
+  process.exit(0);
+}
+
+main(process.argv.slice(2));

package/scripts/hs-companion.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * `hs companion ...` — the desktop companion's CLI face.
+ *
+ *   start|stop|status|build   tray-host lifecycle → companion/start.ps1 (PowerShell 7),
+ *                             which launches companion/src/HeySpex.Companion.Host directly
+ *                             (the versioned-folder indirection was retired 2026-08-12).
+ *   settings list|get|set     every Companion setting, via the console's
+ *                             GET/PUT /api/companion/settings ([[HS-UDH1]]); plus the
+ *                             short aliases (mute, volume, orb, wake, ...).
+ *
+ * Parsing, the key/alias tables, value coercion, and the request shape live in
+ * scripts/lib/hs-companion-settings.mjs so they are unit-testable without a
+ * process; this file only spawns, prints, and exits.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+  makeCompanionConsoleFetch,
+  parseCompanionArgs,
+  renderHelp,
+  runCompanionSettings,
+} from "./lib/hs-companion-settings.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const START_PS1 = path.join(PKG_ROOT, "companion", "start.ps1");
+
+function resolvePwsh() {
+  return process.env.HEYSPEX_COMPANION_POWERSHELL?.trim() || "pwsh";
+}
+
+function runHost(sub, rest) {
+  if (!existsSync(START_PS1)) {
+    process.stderr.write(`hs companion: start script not found at ${START_PS1}\n`);
+    process.exit(1);
+  }
+
+  const pwshArgs = ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", START_PS1, "-Action", sub];
+  if (sub === "start" && rest.includes("--build")) {
+    pwshArgs.push("-Build");
+  }
+
+  const child = spawn(resolvePwsh(), pwshArgs, { cwd: PKG_ROOT, stdio: "inherit" });
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 0));
+  child.on("error", (err) => {
+    process.stderr.write(
+      `hs companion: failed to run ${resolvePwsh()}: ${err.message}\n` +
+        "Install PowerShell 7 (pwsh) or set HEYSPEX_COMPANION_POWERSHELL to its path.\n",
+    );
+    process.exit(1);
+  });
+}
+
+async function main(argv) {
+  const parsed = parseCompanionArgs(argv);
+
+  if (parsed.error) {
+    process.stderr.write(`hs companion: ${parsed.error}\n\n${renderHelp("companion")}\n`);
+    process.exit(2);
+  }
+  if (parsed.kind === "help") {
+    process.stdout.write(`${renderHelp(parsed.topic)}\n`);
+    process.exit(0);
+  }
+  if (parsed.kind === "host") {
+    runHost(parsed.sub, parsed.rest);
+    return;
+  }
+
+  // settings — resolved console (or --url) + the shared bearer ladder.
+  const consoleFetch = makeCompanionConsoleFetch({ url: parsed.url, repoRoot: process.env.HS_VAULT_ROOT });
+  const result = await runCompanionSettings(parsed, { consoleFetch });
+  if (result.ok) {
+    process.stdout.write(`${result.stdout}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`hs companion: ${result.stderr}\n`);
+  process.exit(result.exitCode);
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  process.stderr.write(`hs companion: ${err.message}\n`);
+  process.exit(1);
+});