heyspex 0.1.0 → 0.2.0

package/scripts/lib/hs-companion-settings.mjs

@@ -0,0 +1,472 @@
+/**
+ * hs companion settings — the CLI face of every Companion setting
+ * ([[HS-UDH1]] "every Companion setting and every console surface has three
+ * faces": settings screen, CLI, MCP).
+ *
+ * Talks to the SAME console endpoint the Settings > Companion screen uses
+ * (`GET`/`PUT /api/companion/settings`, see
+ * spex-console/src/app/api/companion/settings/route.ts) and sends the same
+ * partial-patch body the screen's `persist()` sends. Nothing here touches
+ * companion-settings.json directly — the console owns the file, its cache,
+ * and the normalisation.
+ *
+ * Transport: the shared vendor `makeConsoleFetch` (timeouts, loopback-host
+ * variants, dev-restart backoff, sign-in classification) bound to the ONE
+ * console-url resolver. Bearer ladder: `COMPANION_UI_TOKEN` env (the local
+ * route's optional loopback token) → the vendor `getAuthHeader` ladder
+ * (`HEYSPEX_MCP_TOKEN` env → `~/.heyspex/credentials.yaml` `mcp_token`).
+ *
+ * The console's store SILENTLY falls back to the previous value on a bad
+ * enum/type (sanitize() in companion-settings-store.ts — the route only
+ * 400s on a non-object body), so the CLI validates against the key table
+ * below BEFORE sending and then compares the echoed value with what it
+ * asked for; a console-side normalisation is reported, never hidden.
+ *
+ * Pure module: every function here is I/O-free except through the injected
+ * `consoleFetch`, so scripts/lib/hs-companion-settings.test.mjs can drive
+ * the whole thing with a fake. scripts/hs-companion.mjs is the process face.
+ */
+import process from "node:process";
+
+import { getAuthHeader, makeConsoleFetch } from "../../vendor/heyspex-mcp/console-fetch.mjs";
+import { resolveConsoleUrl } from "./console-url-resolver.mjs";
+
+export const SETTINGS_PATH = "/api/companion/settings";
+
+/** `spexCrawl.userAgentPreset` ids — mirrors SPEXCRAWL_UA_PRESETS in
+ * spex-console/src/lib/spexcrawl-user-agents.ts, plus the "custom" escape. */
+const SPEXCRAWL_UA_IDS = [
+  "googlebot-desktop", "googlebot-smartphone", "googlebot-image", "googlebot-news",
+  "bingbot", "bingbot-mobile", "duckduckbot", "yandexbot", "baiduspider",
+  "chrome-desktop", "chrome-android", "safari-macos", "safari-ios",
+  "firefox-desktop", "edge-desktop", "spexcrawl", "custom",
+];
+
+/**
+ * One row per settable leaf. Mirrors `CompanionSettings` +
+ * `DEFAULT_COMPANION_SETTINGS` in spex-console/src/lib/companion-settings-defaults.ts
+ * and the accept-rules in companion-settings-store.ts `sanitize()`. Nested
+ * objects are flattened to dotted keys; `set` re-nests them into the partial
+ * patch the store merges over the current value.
+ *
+ *   type      enum | boolean | integer | number | string | list
+ *   values    enum — accepted case-insensitively, sent in canonical case
+ *   min/max   integer / number range (inclusive)
+ *   nullable  `null` / `none` clears the value
+ *   readOnly  companion-owned telemetry; listed, never settable
+ */
+export const COMPANION_SETTING_KEYS = [
+  { key: "speechEngine", type: "enum", values: ["localParakeet", "localWhisper", "http", "pulse"] },
+  { key: "whisperModel", type: "enum", values: ["tiny.en", "base.en", "small.en"] },
+  { key: "micDevice", type: "string", note: "display label; selection is by micDeviceId" },
+  { key: "micDeviceId", type: "string", note: "capture device id (`list --json` shows devices)" },
+  { key: "pttHotkey", type: "string", note: "chord, e.g. Alt+Space" },
+  { key: "wakeWordEnabled", type: "boolean" },
+  { key: "activationMode", type: "enum", values: ["auto", "desktop", "vr"] },
+  { key: "vrPttHotkey", type: "string", note: "chord, or Mouse 4 / Mouse 5" },
+  { key: "vrWakeWordEnabled", type: "boolean" },
+  { key: "wakeWordThreshold", type: "number", min: 0, max: 1, note: "peak level treated as speech" },
+  { key: "confirmBeforeCapture", type: "boolean" },
+  { key: "orbVisibility", type: "enum", values: ["always", "while-listening", "hidden"] },
+  { key: "orbSize", type: "enum", values: ["small", "medium", "large"] },
+  { key: "theme", type: "enum", values: ["dark", "light", "system"] },
+  { key: "voiceProfile.present", type: "boolean", readOnly: true },
+  { key: "voiceProfile.lastCalibratedAt", type: "string", nullable: true, readOnly: true },
+  { key: "soundCuesEnabled", type: "boolean" },
+  { key: "soundCuesVolume", type: "integer", min: 0, max: 100 },
+  { key: "orbPositionX", type: "number", nullable: true, note: "screen x; null = no default" },
+  { key: "orbPositionY", type: "number", nullable: true, note: "screen y; null = no default" },
+  { key: "orbPositionLocked", type: "boolean" },
+  { key: "captureAutoLaunch.enabled", type: "boolean" },
+  { key: "captureAutoLaunch.defaultAgent", type: "string", nullable: true, note: "model-registry entry id" },
+  { key: "captureAutoLaunch.fallbackAgents", type: "list", note: "comma-separated entry ids" },
+  { key: "spexCrawl.userAgentPreset", type: "enum", values: SPEXCRAWL_UA_IDS },
+  { key: "spexCrawl.customUserAgent", type: "string", note: "used only when userAgentPreset=custom" },
+  { key: "spexCrawl.respectRobotsTxt", type: "boolean" },
+  { key: "spexCrawl.searxngBaseUrl", type: "string", nullable: true, note: "http(s) base URL of a SearXNG instance" },
+];
+
+/**
+ * Short verbs — each is `settings set <key> <value>` under the hood. A row
+ * with `value` takes no argument (`mute`); a row with `arg` takes one, and
+ * called WITHOUT it reads the key instead (`hs companion volume` prints the
+ * volume). Adding an alias is one line here; help and dispatch derive from
+ * this table.
+ */
+export const COMPANION_ALIASES = {
+  mute:       { key: "soundCuesEnabled", value: "false", help: "Silence feedback cues" },
+  unmute:     { key: "soundCuesEnabled", value: "true", help: "Feedback cues back on" },
+  volume:     { key: "soundCuesVolume", arg: "<0-100>", help: "Feedback-cue loudness" },
+  orb:        { key: "orbVisibility", arg: "always|while-listening|hidden", help: "Idle orb visibility" },
+  wake:       { key: "wakeWordEnabled", arg: "on|off", help: "Wake-word listening" },
+  activation: { key: "activationMode", arg: "auto|desktop|vr", help: "Activation profile (desktop / VR goggle)" },
+  hotkey:     { key: "pttHotkey", arg: "<chord>", help: "Push-to-talk chord, e.g. Alt+Space" },
+};
+
+export const HOST_COMMANDS = ["start", "stop", "status", "build"];
+
+const TRUE_WORDS = new Set(["true", "on", "yes", "1", "enabled"]);
+const FALSE_WORDS = new Set(["false", "off", "no", "0", "disabled"]);
+const NULL_WORDS = new Set(["null", "none"]);
+
+/** Find a key-table row by exact or case-insensitive name. */
+export function findSettingKey(name) {
+  if (typeof name !== "string" || !name) return null;
+  const exact = COMPANION_SETTING_KEYS.find((k) => k.key === name);
+  if (exact) return exact;
+  const lower = name.toLowerCase();
+  return COMPANION_SETTING_KEYS.find((k) => k.key.toLowerCase() === lower) ?? null;
+}
+
+/** Human form of a row's constraint, for `list`/`get` and help. */
+export function describeConstraint(entry) {
+  if (!entry) return "";
+  const parts = [];
+  if (entry.type === "enum") parts.push(entry.values.join("|"));
+  else if (entry.type === "boolean") parts.push("true|false");
+  else if (entry.type === "integer" || entry.type === "number") {
+    parts.push(
+      entry.min != null && entry.max != null
+        ? `${entry.min}-${entry.max}`
+        : entry.type,
+    );
+  } else parts.push(entry.type);
+  if (entry.nullable) parts.push("or null");
+  if (entry.readOnly) parts.push("(read-only)");
+  if (entry.note) parts.push(`— ${entry.note}`);
+  return parts.join(" ");
+}
+
+/**
+ * Parse the string a user typed into the JSON value the route expects.
+ * Returns `{ ok: true, value }` or `{ ok: false, error }` — the error is the
+ * message the CLI prints (and the reason the request is never sent).
+ */
+export function coerceValue(entry, raw) {
+  const text = String(raw ?? "").trim();
+  const lower = text.toLowerCase();
+  const { key } = entry;
+
+  if (entry.nullable && NULL_WORDS.has(lower)) return { ok: true, value: null };
+
+  switch (entry.type) {
+    case "boolean": {
+      if (TRUE_WORDS.has(lower)) return { ok: true, value: true };
+      if (FALSE_WORDS.has(lower)) return { ok: true, value: false };
+      return { ok: false, error: `${key} expects true|false (also on|off, yes|no); got "${text}"` };
+    }
+    case "enum": {
+      const match = entry.values.find((v) => v.toLowerCase() === lower);
+      if (match) return { ok: true, value: match };
+      return { ok: false, error: `${key} expects one of ${entry.values.join("|")}; got "${text}"` };
+    }
+    case "integer":
+    case "number": {
+      const n = Number(text);
+      if (text === "" || !Number.isFinite(n)) {
+        return { ok: false, error: `${key} expects a ${entry.type}; got "${text}"` };
+      }
+      if (entry.type === "integer" && !Number.isInteger(n)) {
+        return { ok: false, error: `${key} expects a whole number; got "${text}"` };
+      }
+      if ((entry.min != null && n < entry.min) || (entry.max != null && n > entry.max)) {
+        return { ok: false, error: `${key} must be between ${entry.min} and ${entry.max}; got ${text}` };
+      }
+      return { ok: true, value: n };
+    }
+    case "list": {
+      const items = text.split(",").map((s) => s.trim()).filter(Boolean);
+      return { ok: true, value: items };
+    }
+    case "string":
+    default:
+      return { ok: true, value: text };
+  }
+}
+
+/** `"captureAutoLaunch.enabled", true` → `{ captureAutoLaunch: { enabled: true } }`. */
+export function buildPatch(key, value) {
+  const parts = key.split(".");
+  const patch = {};
+  let cursor = patch;
+  for (let i = 0; i < parts.length - 1; i++) {
+    cursor[parts[i]] = {};
+    cursor = cursor[parts[i]];
+  }
+  cursor[parts[parts.length - 1]] = value;
+  return patch;
+}
+
+/** Read a dotted key out of the settings object; `undefined` when absent. */
+export function getPath(obj, key) {
+  let cur = obj;
+  for (const part of key.split(".")) {
+    if (cur == null || typeof cur !== "object") return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+/** Flatten nested settings objects to dotted keys (arrays stay values). */
+export function flattenSettings(settings, prefix = "") {
+  const out = {};
+  for (const [k, v] of Object.entries(settings ?? {})) {
+    const full = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === "object" && !Array.isArray(v)) Object.assign(out, flattenSettings(v, full));
+    else out[full] = v;
+  }
+  return out;
+}
+
+/**
+ * Parse everything after `hs companion`. Returns one of:
+ *   { kind: "help", topic: "companion"|"settings" }
+ *   { kind: "host", sub, rest }                      — start|stop|status|build
+ *   { kind: "settings", action: "list", json, url }
+ *   { kind: "settings", action: "get", key, json, url }
+ *   { kind: "settings", action: "set", key, value, json, url }
+ *   { error }
+ */
+export function parseCompanionArgs(argv) {
+  const [head, ...tail] = argv;
+  if (head === undefined) return { kind: "host", sub: "start", rest: [] };
+  if (head === "--help" || head === "-h" || head === "help") return { kind: "help", topic: "companion" };
+  if (HOST_COMMANDS.includes(head)) return { kind: "host", sub: head, rest: tail };
+
+  const flags = { json: false, url: null, help: false };
+  const positional = [];
+  for (let i = 0; i < tail.length; i++) {
+    const a = tail[i];
+    if (a === "--json") flags.json = true;
+    else if (a === "--url") flags.url = tail[++i] ?? null;
+    else if (a.startsWith("--url=")) flags.url = a.slice("--url=".length);
+    else if (a === "--help" || a === "-h" || a === "help") flags.help = true;
+    else if (a.startsWith("--")) return { error: `unknown flag ${a}` };
+    else positional.push(a);
+  }
+
+  if (head === "settings") {
+    if (flags.help) return { kind: "help", topic: "settings" };
+    const [action = "list", ...args] = positional;
+    if (action === "list") return { kind: "settings", action: "list", json: flags.json, url: flags.url };
+    if (action === "get") {
+      if (!args[0]) return { error: "settings get needs a key (hs companion settings get <key>)" };
+      return { kind: "settings", action: "get", key: args[0], json: flags.json, url: flags.url };
+    }
+    if (action === "set") {
+      // `set key value` and `set key=value` both read naturally.
+      let [key, value] = args;
+      if (key && value === undefined && key.includes("=")) {
+        const eq = key.indexOf("=");
+        value = key.slice(eq + 1);
+        key = key.slice(0, eq);
+      }
+      if (!key || value === undefined) {
+        return { error: "settings set needs a key and a value (hs companion settings set <key> <value>)" };
+      }
+      return { kind: "settings", action: "set", key, value, json: flags.json, url: flags.url };
+    }
+    return { error: `unknown settings subcommand \`${action}\` (list|get|set)` };
+  }
+
+  const alias = COMPANION_ALIASES[head];
+  if (alias) {
+    if (flags.help) return { kind: "help", topic: "settings" };
+    const value = alias.value ?? positional[0];
+    if (value === undefined) {
+      return { kind: "settings", action: "get", key: alias.key, json: flags.json, url: flags.url, alias: head };
+    }
+    return { kind: "settings", action: "set", key: alias.key, value, json: flags.json, url: flags.url, alias: head };
+  }
+
+  return { error: `unknown subcommand \`${head}\`` };
+}
+
+/** Bearer for the settings route: loopback UI token first, then the shared MCP ladder. */
+export function companionAuthHeader({ env = process.env, homeDir } = {}) {
+  const uiToken = env.COMPANION_UI_TOKEN?.trim();
+  if (uiToken) return { Authorization: `Bearer ${uiToken}` };
+  return getAuthHeader(homeDir ? { env, homeDir } : { env });
+}
+
+/**
+ * The console fetch this command uses: vendor transport + shared URL
+ * resolver + the bearer ladder above. `url` (from `--url`) short-circuits
+ * the resolver; `fetchImpl` is for tests.
+ */
+export function makeCompanionConsoleFetch({ url = null, env = process.env, fetchImpl, repoRoot } = {}) {
+  const getConsoleUrl = () =>
+    (url ?? resolveConsoleUrl({ repoRoot: repoRoot ?? env.HS_VAULT_ROOT ?? process.cwd(), env }))
+      .replace(/\/+$/, "");
+  return makeConsoleFetch({
+    getConsoleUrl,
+    ...(fetchImpl ? { fetchImpl } : {}),
+    getAuthHeader: () => companionAuthHeader({ env }),
+  }).consoleFetch;
+}
+
+/** One-line failure text for a non-ok transport result; route errors verbatim. */
+export function describeFailure(result, verb = "GET") {
+  if (!result || result.status === 0) {
+    const detail = result?.error ? ` (${result.error})` : "";
+    return result?.authMessage ?? `console unreachable at ${result?.url ?? "?"}${detail}`;
+  }
+  const body = result.body;
+  const msg =
+    (body && typeof body === "object" && (body.message ?? body.error ?? body.raw)) ??
+    (typeof body === "string" ? body : JSON.stringify(body));
+  return `${verb} ${SETTINGS_PATH} failed ${result.status}: ${msg}`;
+}
+
+function formatValue(v) {
+  if (v === undefined) return "(not reported by this console)";
+  if (v === null) return "null";
+  if (Array.isArray(v)) return v.length ? v.join(",") : "(empty)";
+  if (typeof v === "string") return v === "" ? '""' : v;
+  return String(v);
+}
+
+function pad(s, n) {
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+/** Rows for `list`: the key table ∪ whatever the console reported. */
+export function listRows(settings) {
+  const flat = flattenSettings(settings);
+  const rows = COMPANION_SETTING_KEYS.map((entry) => ({
+    key: entry.key,
+    value: flat[entry.key],
+    constraint: describeConstraint(entry),
+    entry,
+  }));
+  const known = new Set(COMPANION_SETTING_KEYS.map((k) => k.key));
+  for (const [key, value] of Object.entries(flat)) {
+    if (!known.has(key)) rows.push({ key, value, constraint: "(not in the CLI key table)", entry: null });
+  }
+  return rows;
+}
+
+export function renderList(rows, { consoleUrl, connected }) {
+  const width = Math.max(...rows.map((r) => r.key.length)) + 2;
+  const valueWidth = Math.max(...rows.map((r) => formatValue(r.value).length)) + 2;
+  const lines = [
+    `companion settings @ ${consoleUrl} (companion ${connected ? "connected" : "not connected"})`,
+    "",
+    ...rows.map((r) => `${pad(r.key, width)}${pad(formatValue(r.value), valueWidth)}${r.constraint}`),
+    "",
+    "set:  hs companion settings set <key> <value>    shortcuts: hs companion --help",
+  ];
+  return lines.join("\n");
+}
+
+function constraintJson(entry) {
+  if (!entry) return null;
+  const c = { type: entry.type };
+  if (entry.values) c.values = entry.values;
+  if (entry.min != null) c.min = entry.min;
+  if (entry.max != null) c.max = entry.max;
+  if (entry.nullable) c.nullable = true;
+  if (entry.readOnly) c.readOnly = true;
+  if (entry.note) c.note = entry.note;
+  return c;
+}
+
+/**
+ * Execute a parsed `settings` command against `consoleFetch` (vendor shape:
+ * `consoleFetch(path, { method, body })` → `{ ok, status, body, url }`).
+ * Returns `{ ok: true, stdout, exitCode: 0 }` or `{ ok: false, stderr, exitCode }`
+ * — the process face prints; nothing here writes to stdio.
+ */
+export async function runCompanionSettings(cmd, { consoleFetch }) {
+  const fail = (stderr, exitCode = 1) => ({ ok: false, stderr, exitCode });
+  const emit = (stdout, json) => ({ ok: true, stdout: cmd.json ? JSON.stringify(json, null, 2) : stdout, exitCode: 0 });
+
+  if (cmd.action === "list") {
+    const res = await consoleFetch(SETTINGS_PATH);
+    if (!res.ok) return fail(describeFailure(res, "GET"));
+    const consoleUrl = res.url.replace(SETTINGS_PATH, "");
+    const rows = listRows(res.body?.settings ?? {});
+    const json = {
+      consoleUrl,
+      connected: res.body?.connected ?? false,
+      settings: Object.fromEntries(rows.map((r) => [r.key, r.value ?? null])),
+      constraints: Object.fromEntries(rows.filter((r) => r.entry).map((r) => [r.key, constraintJson(r.entry)])),
+      devices: res.body?.devices ?? [],
+      activation: res.body?.activation ?? null,
+    };
+    return emit(renderList(rows, json), json);
+  }
+
+  // get / set both need the key resolved.
+  const entry = findSettingKey(cmd.key);
+  if (cmd.action === "set") {
+    if (!entry) return fail(`unknown setting \`${cmd.key}\`\nkeys: ${COMPANION_SETTING_KEYS.filter((k) => !k.readOnly).map((k) => k.key).join(", ")}`, 2);
+    if (entry.readOnly) return fail(`${entry.key} is companion-owned (read-only)`, 2);
+    const coerced = coerceValue(entry, cmd.value);
+    if (!coerced.ok) return fail(coerced.error, 2);
+
+    const res = await consoleFetch(SETTINGS_PATH, { method: "PUT", body: buildPatch(entry.key, coerced.value) });
+    if (!res.ok) return fail(describeFailure(res, "PUT"));
+    const actual = getPath(res.body?.settings ?? {}, entry.key);
+    const same = JSON.stringify(actual) === JSON.stringify(coerced.value);
+    const json = { key: entry.key, value: actual ?? null, requested: coerced.value, normalized: !same };
+    if (!same) {
+      return fail(
+        `${entry.key} = ${formatValue(actual)} — the console kept/normalised the value instead of ${formatValue(coerced.value)}` +
+          (actual === undefined ? " (this console does not report that key; is it running the latest build?)" : ""),
+      );
+    }
+    return emit(`${entry.key} = ${formatValue(actual)}`, json);
+  }
+
+  // get
+  const res = await consoleFetch(SETTINGS_PATH);
+  if (!res.ok) return fail(describeFailure(res, "GET"));
+  const key = entry?.key ?? cmd.key;
+  const value = getPath(res.body?.settings ?? {}, key);
+  if (!entry && value === undefined) {
+    return fail(`unknown setting \`${cmd.key}\`\nkeys: ${COMPANION_SETTING_KEYS.map((k) => k.key).join(", ")}`, 2);
+  }
+  const json = { key, value: value ?? null, constraint: constraintJson(entry) };
+  const constraint = entry ? `   ${describeConstraint(entry)}` : "";
+  return emit(`${key} = ${formatValue(value)}${constraint}`, json);
+}
+
+/** Help text derived from the two tables so it cannot drift from them. */
+export function renderHelp(topic = "companion") {
+  const settingsLines = [
+    "Settings (console-backed; --json on list/get for agents):",
+    "  hs companion settings [list] [--json]           Every key: current value + allowed values",
+    "  hs companion settings get <key> [--json]        One key",
+    "  hs companion settings set <key> <value>         Change one key (enums case-insensitive; booleans on|off|true|false; null clears)",
+    "  hs companion settings --help                    Key table",
+    "",
+    "Shortcuts (each is `settings set` under the hood; omit the value to read it):",
+    ...Object.entries(COMPANION_ALIASES).map(([name, a]) => {
+      const usage = `hs companion ${name}${a.arg ? ` ${a.arg}` : ""}`;
+      return `  ${pad(usage, 50)}${a.help} (${a.key})`;
+    }),
+    "",
+    "  --url <console>   Override the resolved console URL for this call",
+  ];
+  if (topic === "settings") {
+    const width = Math.max(...COMPANION_SETTING_KEYS.map((k) => k.key.length)) + 2;
+    return [
+      ...settingsLines,
+      "",
+      "Keys:",
+      ...COMPANION_SETTING_KEYS.map((k) => `  ${pad(k.key, width)}${describeConstraint(k)}`),
+    ].join("\n");
+  }
+  return [
+    "Usage:",
+    "  hs companion start [--build]   Start the tray app (build first if missing)",
+    "  hs companion stop              Quit the tray app",
+    "  hs companion status            Is it running?",
+    "  hs companion build             dotnet build Debug",
+    "",
+    ...settingsLines,
+    "",
+    "Shortcut: npm run companion",
+  ].join("\n");
+}

package/scripts/lib/hs-source-commit.mjs

@@ -13,8 +13,9 @@
  * the colocated test for the enforcement proof.
  */
 import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
   getTreeStatus,
@@ -22,10 +23,40 @@ import {
   computeDirtyFingerprint,
   REPO_ROOT,
 } from './hs-source-preflight.mjs';
-import { createSessionBranch } from './session-branch.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const OWNER_COMMIT_SCRIPT = path.join(REPO_ROOT, 'scripts', 'owner-commit.mjs');
+const SESSION_BRANCH_MODULE = path.join(__dirname, 'session-branch.mjs');
+
+/**
+ * `--session` (HS-6N2Z) statically imported `./session-branch.mjs`, which is
+ * a dev-only module — never in the package's `files` (RUNTIME_FILES /
+ * `package.json`) — so a static import crashed EVERY `hs source commit`
+ * invocation with a raw `ERR_MODULE_NOT_FOUND` on a published npm install,
+ * not just ones that pass `--session`. Guarded, on-demand load instead: only
+ * attempted when `--session` is actually given (see `invokedDirectly()`
+ * below), so the no-flag path never even tries to resolve it, and a
+ * resolution failure prints a clear refusal instead of a stack trace. Mirrors
+ * the shape of `hs doctor`'s own published-install guard in `bin/hs.mjs`
+ * (`existsSync(script)` before ever importing/spawning it).
+ *
+ * @returns {Promise<import('./session-branch.mjs').createSessionBranch | null>}
+ */
+export async function loadCreateSessionBranch() {
+  if (!existsSync(SESSION_BRANCH_MODULE)) return null;
+  try {
+    const mod = await import(pathToFileURL(SESSION_BRANCH_MODULE).href);
+    return mod.createSessionBranch ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export const SESSION_BRANCH_UNAVAILABLE_MESSAGE =
+  'hs source commit --session: refusing — scripts/lib/session-branch.mjs is not available on ' +
+  'this install. It ships only inside a full source checkout of the HeySpex repo, not a ' +
+  'published npm install, so `--session` is unavailable here. Run `hs source commit` without ' +
+  '`--session`, or use a source checkout.';
 
 /**
  * Default subprocess runner — injectable so tests can spy without ever
@@ -150,15 +181,24 @@ export function commitFromPlan({
  * no-flag path completely unchanged: `createSessionBranch` is never called,
  * so there is no branch-creation/selection side effect at all (AC2).
  *
+ * `createSessionBranchFn` has NO default here (unlike before this task) —
+ * see `invokedDirectly()` below for why: the direct-invocation entry point is
+ * the only caller that ever needed the real `session-branch.mjs`, and it now
+ * resolves it itself via the guarded `loadCreateSessionBranch()` above,
+ * on-demand, only when `--session` is actually in argv. A caller (test or
+ * otherwise) that reaches this function with `--session` set but no
+ * `createSessionBranchFn` gets the same graceful refusal a missing-module
+ * install would produce, never a crash.
+ *
  * @param {string[]} argv (verb-stripped: just the flags/args after `commit`)
  * @param {{
  *   cwd?: string,
  *   run?: (cmd: string, args: string[], opts?: object) => { status: number, stdout?: string, stderr?: string },
- *   createSessionBranchFn?: typeof createSessionBranch,
+ *   createSessionBranchFn?: (opts: object) => { ok: boolean, code?: string, message?: string, branch?: string, reused?: boolean },
  * }} [opts]
  * @returns {number} process exit code
  */
-export function runCommitCommand(argv, { cwd = process.cwd(), run, createSessionBranchFn = createSessionBranch } = {}) {
+export function runCommitCommand(argv, { cwd = process.cwd(), run, createSessionBranchFn } = {}) {
   let message = '';
   let sessionId;
   for (let i = 0; i < argv.length; i++) {
@@ -172,6 +212,10 @@ export function runCommitCommand(argv, { cwd = process.cwd(), run, createSession
   }
 
   if (sessionId !== undefined) {
+    if (typeof createSessionBranchFn !== 'function') {
+      console.error(SESSION_BRANCH_UNAVAILABLE_MESSAGE);
+      return 1;
+    }
     const branchResult = createSessionBranchFn({ sessionId, cwd, run });
     if (!branchResult.ok) {
       console.error(branchResult.message);
@@ -203,5 +247,15 @@ function invokedDirectly() {
 
 if (invokedDirectly()) {
   // argv: [node, script, "commit", ...flags] — drop the leading verb token.
-  process.exit(runCommitCommand(process.argv.slice(3)));
+  const argv = process.argv.slice(3);
+  // Only ever attempt to resolve the dev-only session-branch.mjs when
+  // `--session` is actually requested — the no-flag path (the overwhelming
+  // majority of invocations, including every published-install one) never
+  // touches it, exactly as before this task.
+  const needsSessionBranch = argv.includes('--session');
+  (needsSessionBranch ? loadCreateSessionBranch() : Promise.resolve(undefined)).then(
+    (createSessionBranchFn) => {
+      process.exit(runCommitCommand(argv, { createSessionBranchFn: createSessionBranchFn ?? undefined }));
+    },
+  );
 }