heyspex 0.1.0 → 0.2.0

package/scripts/hs-settings.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+/**
+ * hs settings — CLI face of the HeySpex settings capability.
+ * Dispatched from bin/hs.mjs. Delegates to the ONE settings core
+ * (vendor/heyspex-mcp/config-settings.mjs) per the three-faces principle
+ * ([[capability-three-faces-no-per-capability-slash]]).
+ *
+ * Usage:
+ *   hs settings list [prefix] [--json]
+ *   hs settings get <dotted.key> [--json]
+ *   hs settings set <dotted.key> <value> [--json] [--confirmed-by-user]
+ *
+ * WRITE-PERMISSION GUARDRAIL (agent-settings-protocol, owner directive
+ * 2026-07-11): settings writes require explicit user permission. A human typing
+ * `hs settings set` in their own terminal IS the permission. But when this CLI
+ * runs inside an agent harness (Claude Code sets CLAUDECODE=1 / CLAUDE_AGENT for
+ * its shell tool), the write is agent-initiated: it is refused unless
+ * `--confirmed-by-user` is passed, and that flag may ONLY be passed after the
+ * user explicitly approved the exact change in the conversation. This holds
+ * regardless of agent_behaviors.ask_forgiveness_not_permission — that switch
+ * governs behaviors, never its own controls. All writes are audited to
+ * .heyspex/settings-history.jsonl.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+import {
+  listConfigLeaves,
+  getEffectiveSetting,
+  setConfigLeaf,
+  validateSettingKey,
+} from '../vendor/heyspex-mcp/config-settings.mjs';
+import {
+  SETTINGS_REGISTRY,
+  getSettingEntry,
+  isKnownSetting,
+} from '../vendor/heyspex-mcp/settings-registry.mjs';
+import { getActiveConfig } from '../vendor/heyspex-mcp/vault-resolve.mjs';
+
+const HELP = `hs settings — read/change HeySpex workflow settings (.heyspex/config.yaml at the VAULT root)
+
+Usage:
+  hs settings list [prefix] [--json]        List all scalar settings (optionally under a dotted prefix)
+  hs settings get <dotted.key> [--json]     Read one setting (e.g. agent_behaviors.capture_on_idea.enabled)
+  hs settings set <dotted.key> <value>      Change one setting (value: string | number | true | false | null)
+       [--confirmed-by-user] [--json]
+
+The settings file lives at <vault root>/.heyspex/config.yaml (ADR-0009). If it is
+missing, \`hs settings set\` creates it from the shipped seed template first and
+then applies the change (reads never create it) — \`hs init\` seeds the same file.
+
+Write permission (agent-settings-protocol):
+  A human running \`hs settings set\` directly is inherently permissioned. Inside an
+  agent harness (CLAUDECODE / CLAUDE_AGENT env present) the write is refused unless
+  --confirmed-by-user is passed — and an agent may pass it ONLY after the user
+  explicitly approved the exact change. Writes are audited to
+  .heyspex/settings-history.jsonl. Agents should prefer the MCP tool
+  heyspex_settings_set (two-step confirm).
+`;
+
+/**
+ * The vault root this face reads/writes. `bin/hs.mjs` always forwards
+ * `HS_VAULT_ROOT`; the last fallback (this script run directly) asks the shared
+ * vault resolver — NEVER this code checkout. Since the 2026-08-31 repo split the
+ * vault is a sibling repo, so falling back to `scripts/..` silently read/wrote a
+ * `.heyspex/config.yaml` the console and MCP never look at
+ * ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]).
+ */
+function vaultRoot() {
+  return process.env.HS_VAULT_ROOT || process.env.HEYSPEX_VAULT_ROOT || getActiveConfig().repoRootAbs;
+}
+
+function isAgentHarness() {
+  return Boolean(
+    process.env.CLAUDECODE ||
+      process.env.CLAUDE_AGENT ||
+      process.env.CLAUDE_CODE_SESSION_ID ||
+      process.env.CURSOR_AGENT,
+  );
+}
+
+/**
+ * True when `root` is the HeySpex platform vault rather than a
+ * customer-provisioned one. `hs init --customer-vault` unconditionally stamps
+ * `template_version: <…>` into the scaffolded vault's `heyspex.yaml`
+ * (`spex-console/src/lib/cli/init-git-finalize.ts` `gitFinalizeHook` /
+ * `ensureTemplateVersionLine`) — the platform vault's own marker never
+ * carries that field. That stamp is the one on-disk, offline-readable signal
+ * that distinguishes the two without a network/account lookup (the MCP/CLI
+ * process is standalone, per `vendor/heyspex-mcp/vault-resolve.mjs`'s module
+ * doc). A vault with no `heyspex.yaml` at all (e.g. this code checkout run
+ * directly, with no vault marker) is treated as platform — it is not a
+ * customer scaffold. Registry-declared admin-only entries (e.g.
+ * `close_out.run_command_drift_doctor`) are hidden from `hs settings list`
+ * everywhere `template_version` is present ([[HS-5MNS-15XI-TASK]] AC4).
+ */
+export function isHeyspexPlatformVault(root) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path.join(root, 'heyspex.yaml'), 'utf8');
+  } catch {
+    return true; // no marker at all — not a customer scaffold
+  }
+  return !/^template_version:\s*\S+/m.test(raw);
+}
+
+/** How a value's `source` reads in a one-line human sentence. */
+function describeSource(source) {
+  if (source === 'file') return 'settings file';
+  if (source === 'registry_default') return 'shipped default';
+  return 'absent';
+}
+
+/**
+ * Build the `hs settings list` result: every registry entry this vault ships
+ * (admin-only entries dropped in a non-platform vault), each carrying its
+ * effective value/source plus its shipped default and description, followed
+ * by any keys the settings file has that the registry does not declare
+ * (marked `unrecognised: true`) — the freeform namespaces the registry has
+ * not been taught yet (`agent_behaviors.*`, `mvp_mode.*`, …) land here too,
+ * unchanged from their pre-registry values.
+ * ([[HS-5MNS-15XI-TASK-show-every-declared-setting-in-the]])
+ *
+ * @param {string} root
+ * @param {string} [prefix] - optional dotted-key prefix filter
+ * @returns {{ declared: object[], unrecognised: object[] }}
+ */
+export function buildListEntries(root, prefix, options = {}) {
+  const trimmedPrefix = (prefix ?? '').trim();
+  const matchesPrefix = (key) =>
+    !trimmedPrefix || key === trimmedPrefix || key.startsWith(trimmedPrefix + '.');
+  const platform = isHeyspexPlatformVault(root);
+
+  const declared = [];
+  for (const entry of SETTINGS_REGISTRY) {
+    if (entry.adminOnly && !platform) continue;
+    if (!matchesPrefix(entry.key)) continue;
+    const effective = getEffectiveSetting(root, entry.key, options);
+    declared.push({
+      key: entry.key,
+      value: effective.value,
+      source: effective.source,
+      default: entry.default,
+      type: entry.type,
+      description: entry.description,
+      cliFlag: entry.cliFlag,
+      adminOnly: entry.adminOnly,
+      enforced: entry.enforced,
+      ...(entry.type === 'enum' ? { values: entry.values } : {}),
+    });
+  }
+
+  const unrecognised = listConfigLeaves(root, options)
+    .filter((leaf) => !isKnownSetting(leaf.key))
+    .filter((leaf) => matchesPrefix(leaf.key))
+    .map((leaf) => ({ key: leaf.key, value: leaf.value, unrecognised: true }));
+
+  return { declared, unrecognised };
+}
+
+/**
+ * Build the `hs settings get <key>` result: the effective value (file value
+ * when present, else the registry's shipped default), which of the two it
+ * came from, and — for a name the registry does not declare AND that has no
+ * value in the file either — an explicit "not declared" report instead of a
+ * silent empty value. ([[HS-7W0S-15XI-TASK-return-the-effective-value-from-the]])
+ *
+ * @param {string} root
+ * @param {string} key
+ * @returns {object}
+ */
+export function resolveGet(root, key, options = {}) {
+  const effective = getEffectiveSetting(root, key, options);
+  if (effective.source === 'absent') {
+    return { ok: true, key, found: false, known: false, value: null, source: 'absent' };
+  }
+  const entry = getSettingEntry(key);
+  return {
+    ok: true,
+    key,
+    found: effective.found,
+    known: Boolean(entry),
+    value: effective.value,
+    source: effective.source,
+    ...(entry ? { default: entry.default, description: entry.description } : {}),
+  };
+}
+
+/** Render `resolveGet`'s result as the plain-text `hs settings get` body. */
+function renderGetText(result) {
+  if (result.source === 'absent') {
+    return `${result.key} is not set and is not declared in the settings registry (no shipped default to fall back to)\n`;
+  }
+  return `${result.key} = ${JSON.stringify(result.value)}  [${describeSource(result.source)}]\n`;
+}
+
+/** Render `buildListEntries`'s result as the plain-text `hs settings list` body. */
+function renderListText({ declared, unrecognised }) {
+  const lines = [];
+  for (const row of declared) {
+    lines.push(`${row.key} = ${JSON.stringify(row.value)}  [${describeSource(row.source)}]`);
+    lines.push(`  ${row.description}`);
+  }
+  if (unrecognised.length) {
+    if (declared.length) lines.push('');
+    lines.push('Unrecognised (not declared in the settings registry):');
+    for (const row of unrecognised) {
+      lines.push(`  ${row.key} = ${JSON.stringify(row.value)}`);
+    }
+  }
+  if (!declared.length && !unrecognised.length) return 'no settings found\n';
+  return lines.join('\n') + '\n';
+}
+
+function parseValueToken(token) {
+  if (token === undefined) return undefined;
+  if (token === 'null') return null;
+  if (token === 'true') return true;
+  if (token === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(token)) return Number(token);
+  return token;
+}
+
+function out(obj, asJson, plain) {
+  if (asJson) process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+  else process.stdout.write(plain);
+}
+
+function main(argv) {
+  // bin/hs.mjs forwards the full argv (leading `settings` token included).
+  const args = argv[0] === 'settings' ? argv.slice(1) : argv.slice();
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    process.stdout.write(HELP);
+    process.exit(args.length === 0 ? 2 : 0);
+  }
+  const asJson = args.includes('--json');
+  const confirmedByUser = args.includes('--confirmed-by-user');
+  const positional = args.filter((a) => !a.startsWith('--'));
+  const [verb, keyArg, ...valueTokens] = positional;
+  const root = vaultRoot();
+
+  if (verb === 'list') {
+    const prefix = keyArg?.trim() || '';
+    const { declared, unrecognised } = buildListEntries(root, prefix);
+    out(
+      { ok: true, count: declared.length + unrecognised.length, declared, unrecognised },
+      asJson,
+      renderListText({ declared, unrecognised }),
+    );
+    process.exit(0);
+  }
+
+  if (verb === 'get') {
+    const check = validateSettingKey(keyArg ?? '');
+    if (!check.ok) {
+      process.stderr.write(`hs settings get: ${check.reason}\n`);
+      process.exit(2);
+    }
+    const result = resolveGet(root, keyArg);
+    out(result, asJson, renderGetText(result));
+    process.exit(0);
+  }
+
+  if (verb === 'set') {
+    const check = validateSettingKey(keyArg ?? '');
+    if (!check.ok) {
+      process.stderr.write(`hs settings set: ${check.reason}\n`);
+      process.exit(2);
+    }
+    if (valueTokens.length === 0) {
+      process.stderr.write('hs settings set: missing <value> (string | number | true | false | null)\n');
+      process.exit(2);
+    }
+    const value = parseValueToken(valueTokens.join(' '));
+
+    if (isAgentHarness() && !confirmedByUser) {
+      const msg =
+        `hs settings set: REFUSED — this shell is running inside an agent harness, and settings writes ` +
+        `require explicit user permission (agent-settings-protocol; independent of ` +
+        `ask_forgiveness_not_permission). Show the user the exact change and, only after they approve, ` +
+        `re-run with --confirmed-by-user (or use the MCP tool heyspex_settings_set, which has a ` +
+        `built-in confirm step).\n`;
+      process.stderr.write(msg);
+      process.exit(3);
+    }
+
+    const actor = isAgentHarness() ? 'agent (CLI, user-confirmed)' : 'human (CLI)';
+    const result = setConfigLeaf(root, keyArg, value, { actor, face: 'cli' });
+    if (!result.ok) {
+      process.stderr.write(`hs settings set: ${result.error} — ${result.message}\n`);
+      process.exit(1);
+    }
+    // HS-4C76 fix 3: the core seeds a missing config.yaml from the template on
+    // the first write instead of refusing — say so, since the user may not have
+    // known the file was absent (it is git-tracked at the vault root).
+    if (result.seeded === true) {
+      process.stderr.write(
+        `hs settings set: note — ${path.join(root, '.heyspex', 'config.yaml')} did not exist and was created from ` +
+          `the seed template before applying this change. Commit it with the vault (ADR-0009).\n`,
+      );
+    }
+    // The CLI face shares the core with heyspex_settings_set, so it inherits the
+    // measured `audited` flag ([[HS-IOJW-5YDH-DIAG]] sweep). A settings write with
+    // no audit row is a partial, and must not print as a clean success.
+    if (result.audited !== true) {
+      process.stderr.write(
+        `hs settings set: WARNING — the value was applied to .heyspex/config.yaml but the audit append to ` +
+          `.heyspex/settings-history.jsonl FAILED. The change is live and UNAUDITED; check that file is writable.\n`,
+      );
+    }
+    out(
+      { ok: true, ...result },
+      asJson,
+      `${keyArg}: ${JSON.stringify(result.previous)} → ${JSON.stringify(result.value)}${result.created ? ' (created)' : ''}${result.seeded === true ? ' (config.yaml seeded from template)' : ''}${result.audited === true ? '' : ' (UNAUDITED — audit append failed)'}\n`,
+    );
+    process.exit(0);
+  }
+
+  process.stderr.write(`hs settings: unknown subcommand \`${verb ?? ''}\` (expected: list | get | set)\n${HELP}`);
+  process.exit(2);
+}
+
+// Only auto-run when executed directly (`node scripts/hs-settings.mjs …` or via
+// bin/hs.mjs's spawn) — not when a test imports this module for its exported
+// helpers (buildListEntries, isHeyspexPlatformVault, …).
+const isMain = (() => {
+  try {
+    return import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main(process.argv.slice(2));
+}

package/scripts/hs-view.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * hs view <surface> [spec-id] — open ONE console surface in a chromeless
+ * app-mode browser window (the "solo surface" console gauge).
+ *
+ * Per [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]]: launches
+ * Edge/Chrome with `--app=<url>` (NOT `--kiosk`, which forces fullscreen and
+ * ignores window sizing) pointed at the console's `/solo/<surface>` route.
+ * Probes ground-truth dev-server status first (same core as `hs server
+ * status`) so a down console yields a clear message, never a blank window.
+ *
+ * Open = run it; close = close the window; re-run = reopen (idempotent).
+ *
+ * Usage:
+ *   hs view pipeline                      # follow the focus pin
+ *   hs view pipeline HS-I87U-CAP          # fixed anchor spec
+ *   hs view docs HS-NP1Y                  # single-doc reader, live-refreshing
+ *   hs view pipeline --follow capture     # track the capture-on-deck pin
+ *   hs view pipeline --follow capture --url https://console.example.com
+ *   hs view pipeline --width 510 --height 900 --browser edge|chrome
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { getDevServerStatus } from './dev-server-status.mjs';
+import { resolveConsoleUrl, DEFAULT_CONSOLE_URL } from './lib/console-url-resolver.mjs';
+// The runnable form of a HeySpex command on THIS machine — `hs …` when the bin
+// is on PATH, else an absolute-path `node "<install>/bin/hs.mjs" …`. Never an
+// `npx` form: npx resolves from the READER's working directory, and outside a
+// checkout `npx hs` installs the unrelated public package hs@2.0.1
+// ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+import { hsCommand } from './lib/hs-command.mjs';
+import { collectOccupiedFamilyKeysFromVault, parseSpecId } from '../vendor/heyspex-mcp/spec-id-lib.mjs';
+
+function defaultVaultRoot() {
+  // This file lives at <vaultRoot>/scripts/, so one level up is the root.
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+/** Levenshtein edit distance — small local helper, no dependency pulled in for it. */
+function editDistance(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Nearest occupied family keys to a typo'd spec token — walks the vault
+ * (fresh every call, unlike `.heyspex/vault-index.json`) via the shared
+ * spec-id-lib helper, never re-implements the vault scan.
+ */
+function suggestFamilyKeys(rawSpec, vaultRoot, limit = 5) {
+  const parsed = parseSpecId(rawSpec);
+  const needle = (parsed?.familyKey ?? rawSpec.replace(/^HS-/i, '')).toUpperCase();
+  const occupied = [...collectOccupiedFamilyKeysFromVault(vaultRoot)];
+  return occupied
+    .map((key) => ({ key, dist: editDistance(needle, key) }))
+    .sort((x, y) => x.dist - y.dist || x.key.localeCompare(y.key))
+    .slice(0, limit)
+    .filter((c) => c.dist <= Math.max(2, Math.ceil(needle.length / 2)))
+    .map((c) => `HS-${c.key}`);
+}
+
+/**
+ * Resolve a spec id/token against the running console before opening a
+ * browser window (same resolution rules as `GET /api/specs/:id`, including
+ * its bare-family-token prefix fallback). Returns `{ ok: true }`,
+ * `{ ok: false, kind: 'ambiguous', candidates }`, or
+ * `{ ok: false, kind: 'not_found', suggestions }`.
+ */
+async function resolveSpec(base, rawSpec, vaultRoot) {
+  let res;
+  try {
+    res = await fetch(`${base}/api/specs/${encodeURIComponent(rawSpec)}`);
+  } catch (err) {
+    // Network hiccup against a console we already confirmed is up — don't
+    // block the window on it, just open unvalidated.
+    return { ok: true, skipped: true, reason: err?.message || String(err) };
+  }
+  if (res.ok) return { ok: true };
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    // non-JSON error body — fall through to generic not_found handling
+  }
+  if (res.status === 404 && body?.error === 'ambiguous_id' && Array.isArray(body.candidates)) {
+    return { ok: false, kind: 'ambiguous', candidates: body.candidates };
+  }
+  if (res.status !== 404) {
+    // Not a verdict on the spec — a hosted console answers an unauthenticated
+    // probe with a sign-in redirect or a 401/403. Open unvalidated rather than
+    // claiming the doc does not exist.
+    return { ok: true, skipped: true, reason: `HTTP ${res.status}` };
+  }
+  return { ok: false, kind: 'not_found', suggestions: suggestFamilyKeys(rawSpec, vaultRoot) };
+}
+
+/** Anchor sources the window can follow live. `pin` is the default behavior. */
+const FOLLOW_MODES = new Set(['pin', 'capture']);
+
+/** Opening width for a surface with nothing better to say. */
+export const DEFAULT_WINDOW_WIDTH = 510;
+
+/**
+ * Surfaces that want a different opening width than the default.
+ *
+ * `inspector` is one narrow pane meant to sit beside a terminal — at 510 it
+ * takes screen it does not need, and its one-pane layout is designed around
+ * 350 ([[HS-LO2G-AQVI-TASK-one-pane-inspector-window-doc-takes-the]]).
+ */
+export const SURFACE_WINDOW_WIDTH = {
+  inspector: 350,
+};
+
+/**
+ * Resolve the window width: an explicit `--width` always wins, otherwise the
+ * surface's own default, otherwise {@link DEFAULT_WINDOW_WIDTH}.
+ *
+ * `explicitWidth` is null/undefined when the flag was not passed. Deciding that
+ * by COMPARING against the fallback would silently drop `--width 510` on the
+ * inspector back to 350, so the caller tracks "was it passed" instead.
+ */
+export function resolveWindowWidth(surface, explicitWidth) {
+  if (typeof explicitWidth === 'number' && Number.isFinite(explicitWidth) && explicitWidth > 0) {
+    return explicitWidth;
+  }
+  return SURFACE_WINDOW_WIDTH[surface] ?? DEFAULT_WINDOW_WIDTH;
+}
+
+function parseArgs(argv) {
+  const args = {
+    surface: null,
+    spec: null,
+    // null until `--width` is seen; resolved per-surface once the surface is known.
+    width: null,
+    height: 900,
+    browser: 'edge',
+    follow: null,
+    url: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') return { help: true };
+    if (a === '--width') { args.width = Number(argv[++i]) || args.width; continue; }
+    if (a === '--height') { args.height = Number(argv[++i]) || args.height; continue; }
+    if (a === '--browser') { args.browser = String(argv[++i] || 'edge'); continue; }
+    if (a === '--url') {
+      const raw = String(argv[++i] || '').trim();
+      if (!/^https?:\/\/\S+$/.test(raw)) {
+        process.stderr.write(`hs view: --url expects an http(s) URL (got "${raw || '(nothing)'}")\n`);
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.url = raw.replace(/\/+$/, '');
+      continue;
+    }
+    if (a === '--follow') {
+      const mode = String(argv[++i] || '').trim().toLowerCase();
+      if (!FOLLOW_MODES.has(mode)) {
+        process.stderr.write(
+          `hs view: --follow expects ${[...FOLLOW_MODES].join(' or ')} (got "${mode || '(nothing)'}")\n`,
+        );
+        process.exitCode = 2;
+        return { help: true };
+      }
+      args.follow = mode;
+      continue;
+    }
+    if (a.startsWith('--')) {
+      process.stderr.write(`hs view: unknown flag ${a}\n`);
+      process.exitCode = 2;
+      return { help: true };
+    }
+    if (!args.surface) args.surface = a;
+    else if (!args.spec) args.spec = a;
+  }
+  return args;
+}
+
+function usage() {
+  process.stdout.write(
+    [
+      'hs view <surface> [spec-id] [--follow pin|capture] [--url https://…]',
+      '                                [--width N] [--height N] [--browser edge|chrome]',
+      '',
+      'Open one console surface in a chromeless app-mode browser window.',
+      'Surfaces: pipeline, docs, inspector, whats-next, captures, session-log, settings',
+      '  (registry: src/app/solo/[surface]/page.tsx).',
+      'Without a spec-id the pipeline and docs views follow the focus pin live.',
+      '--follow capture tracks the capture-on-deck pin instead, so the window',
+      '  re-anchors itself onto each new capture rather than opening another.',
+      '--url opens against a named console (a hosted one) instead of probing for',
+      '  a local dev server — the cloud-relay path the desktop companion uses.',
+      '',
+    ].join('\n'),
+  );
+}
+
+/**
+ * Only a localhost/loopback resolution still requires a running local dev
+ * server; anything else (a paired or `hs dev mode:cloud` hosted console) is
+ * opened directly. An unparseable URL is treated as local so it still goes
+ * through the dev-server probe instead of being launched blind.
+ */
+function isLocalConsoleUrl(url) {
+  try {
+    const host = new URL(url).hostname;
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
+  } catch {
+    return true;
+  }
+}
+
+function launchAppWindow(url, { width, height, browser }) {
+  const exe = browser === 'chrome' ? 'chrome' : 'msedge';
+  const flags = [`--app=${url}`, `--window-size=${width},${height}`];
+  let child;
+  if (process.platform === 'win32') {
+    // `start` resolves msedge/chrome via the App Paths registry; the empty ''
+    // is start's window-title slot, without it the exe would be eaten as title.
+    child = spawn('cmd.exe', ['/c', 'start', '', exe, ...flags], {
+      detached: true,
+      stdio: 'ignore',
+    });
+  } else if (process.platform === 'darwin') {
+    const app = browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
+    child = spawn('open', ['-na', app, '--args', ...flags], { detached: true, stdio: 'ignore' });
+  } else {
+    const bin = browser === 'chrome' ? 'google-chrome' : 'microsoft-edge';
+    child = spawn(bin, flags, { detached: true, stdio: 'ignore' });
+  }
+  child.unref();
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.surface) {
+    usage();
+    if (!args.help) process.exitCode = 2;
+    return;
+  }
+
+  // Now that the surface is known, settle the width: an explicit `--width`
+  // stands, otherwise the surface's own opening width.
+  args.width = resolveWindowWidth(args.surface, args.width);
+
+  // `--url` names the console explicitly — the cloud-relay path, where the
+  // companion opens a window against the hosted console it is paired with and
+  // there is no local dev server to probe. Without it, the machine's own
+  // console resolution decides: `hs dev mode:cloud` / `hs mcp pair` stamp a
+  // hosted URL into ~/.heyspex/credentials.yaml, and a non-local resolution
+  // needs no dev server either. Only a localhost resolution keeps the old
+  // behavior of requiring (and probing for) a running local console.
+  const vaultRoot = process.env.HS_VAULT_ROOT || defaultVaultRoot();
+  let base = args.url;
+  if (!base) {
+    const resolved = resolveConsoleUrl({ repoRoot: vaultRoot });
+    if (!isLocalConsoleUrl(resolved)) {
+      base = resolved.replace(/\/+$/, '');
+    } else {
+      const status = await getDevServerStatus({ vaultRoot: process.env.HS_VAULT_ROOT });
+      if (!status.running) {
+        process.stderr.write(
+          'hs view: this machine points at a local console but no spex-console dev server is running.\n' +
+            '  Start it first (npm run dev), then re-run this command.\n' +
+            `  (Meant the hosted console? Run \`${hsCommand('dev mode:cloud')}\`, or pass --url https://…)\n`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const consoleServer = (status.servers || []).find((s) => s.probe === 'console');
+      base = (consoleServer?.url || DEFAULT_CONSOLE_URL).replace(/\/+$/, '');
+    }
+  }
+
+  if (args.spec) {
+    const resolution = await resolveSpec(base, args.spec, vaultRoot);
+    if (!resolution.ok) {
+      if (resolution.kind === 'ambiguous') {
+        process.stderr.write(
+          `hs view: "${args.spec}" is ambiguous — it matches more than one spec:\n` +
+            resolution.candidates.map((c) => `  ${c}\n`).join('') +
+            'Pass the full basename to disambiguate.\n',
+        );
+      } else {
+        process.stderr.write(`hs view: no spec found for "${args.spec}".\n`);
+        if (resolution.suggestions.length) {
+          process.stderr.write(
+            'Did you mean:\n' + resolution.suggestions.map((s) => `  ${s}\n`).join(''),
+          );
+        }
+      }
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // A fixed `?spec=` wins over any follow mode (both here and in the route),
+  // so only send `follow` when there is no fixed anchor to override it.
+  const params = new URLSearchParams();
+  if (args.spec) params.set('spec', args.spec);
+  else if (args.follow) params.set('follow', args.follow);
+  const search = params.toString();
+  const query = search ? `?${search}` : '';
+  const url = `${base}/solo/${encodeURIComponent(args.surface)}${query}`;
+
+  launchAppWindow(url, args);
+  process.stdout.write(
+    `hs view: opened ${url} in an app-mode ${args.browser === 'chrome' ? 'Chrome' : 'Edge'} window ` +
+      `(${args.width}x${args.height}). Close the window to close; re-run to reopen.\n`,
+  );
+}
+
+// Run only as the CLI entry point. Without this guard, importing the module —
+// which is how `resolveWindowWidth` is tested — would spawn a browser window.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main().catch((err) => {
+    process.stderr.write(`hs view: ${err?.message || err}\n`);
+    process.exitCode = 1;
+  });
+}