heyspex 0.1.0 → 0.2.1

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-branch.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * hs-source-branch.mjs — `hs source branch declare|show`, plus
+ * `resolvePushBranch` used by `hs source push` when no branch is typed
+ * ([[HS-G01N-CWPX-TASK-hs-source-declares-the-session-branch]], epic
+ * [[HS-B8CY-CWPX-EPIC-one-session-one-reviewable-change]]).
+ *
+ * The branch DECISION stays on the server: `GET /api/source/session-branch`
+ * runs the one shared resolver (`resolveSessionTargetBranch`,
+ * spex-console/src/lib/git-export/branch-resolver.ts) — the same function the
+ * cloud-write drain calls. This module never re-implements ref validation or
+ * the dated-branch rule; it only declares, asks, and falls back to the local
+ * HEAD when the console cannot be reached (and says so).
+ *
+ * The HTTP client is injectable (`fetchImpl`) so tests never touch a network;
+ * console URL + bearer reuse the same idiom as `hs-source-log.mjs`.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConsoleUrl } from './console-url-resolver.mjs';
+import { bearerHeaderFor } from './hs-source-log.mjs';
+import { hookVaultHeaders } from './hook-vault-header.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+const ENDPOINT = '/api/source/session-branch';
+
+/**
+ * Current checked-out branch, or null (detached HEAD / git unavailable).
+ * @param {{ cwd?: string, run?: (cmd: string, args: string[], opts: object) => { status: number|null, stdout?: string } }} [opts]
+ * @returns {string | null}
+ */
+export function currentGitBranch({ cwd = process.cwd(), run = spawnSync } = {}) {
+  try {
+    const r = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, encoding: 'utf8' });
+    const out = (r.stdout ?? '').toString().trim();
+    if (r.status !== 0 || !out || out === 'HEAD') return null;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+async function callConsole({ method, body, fetchImpl, consoleUrl, repoRoot }) {
+  const base = consoleUrl ?? resolveConsoleUrl({ repoRoot });
+  const headers = { ...bearerHeaderFor(base), ...hookVaultHeaders() };
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  const res = await fetchImpl(`${base}${ENDPOINT}`, {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, base };
+}
+
+/**
+ * Ask the console which branch this session's work should target.
+ * Never throws. `via: 'console'` carries the resolver's `source`
+ * ('session' | 'dated'); `via: 'git-head'` is the explicit offline fallback.
+ * @returns {Promise<{ branch: string, via: 'console'|'git-head', source?: string, note?: string } | { branch: null, via: 'none', note: string }>}
+ */
+export async function resolvePushBranch({
+  fetchImpl = fetch,
+  cwd = process.cwd(),
+  consoleUrl,
+  repoRoot,
+  run,
+} = {}) {
+  try {
+    const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+    const branch = r.ok ? r.json?.target?.branch : null;
+    if (typeof branch === 'string' && branch) {
+      return { branch, via: 'console', source: r.json.target.source };
+    }
+  } catch {
+    // fall through to the local fallback
+  }
+  const head = currentGitBranch({ cwd, run });
+  if (head) {
+    return {
+      branch: head,
+      via: 'git-head',
+      note: `console unreachable — pushing the checked-out branch \`${head}\` instead of the resolver's target`,
+    };
+  }
+  return { branch: null, via: 'none', note: 'console unreachable and no checked-out branch to fall back to' };
+}
+
+/**
+ * Spec commits the cloud drain made for this session, from the same console
+ * endpoint ([[HS-OAD2-CWPX-TASK-hs-source-status-names-the-spec-commits]]).
+ * Never throws. `known: false` means the console could not answer — callers
+ * must NOT present that as "no commits".
+ * @returns {Promise<{ known: true, commits: Array<{repo:string,branch:string,commitSha:string,settledAt:string,specIds:string[]}>, basis?: string } | { known: false }>}
+ */
+export async function fetchDrainCommits({ fetchImpl = fetch, consoleUrl, repoRoot } = {}) {
+  try {
+    const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+    if (!r.ok || !Array.isArray(r.json?.drainCommits)) return { known: false };
+    return { known: true, commits: r.json.drainCommits, basis: r.json.window?.basis };
+  } catch {
+    return { known: false };
+  }
+}
+
+/**
+ * Pure formatter for the `hs source status` section.
+ * @param {Awaited<ReturnType<typeof fetchDrainCommits>>} result
+ * @returns {string[]}
+ */
+export function formatDrainCommits(result) {
+  const head = 'Cloud spec commits (this session):';
+  if (!result.known) return [head, '  unknown (console unreachable)'];
+  if (result.commits.length === 0) return [head, '  No cloud spec commits for this session.'];
+  const lines = [head];
+  for (const c of result.commits) {
+    lines.push(`  ${c.branch} @ ${String(c.commitSha).slice(0, 7)}  ${c.specIds.join(', ')}`);
+  }
+  if (result.basis === 'last_12h') lines.push('  (no branch declared — showing the last 12 hours)');
+  return lines;
+}
+
+/**
+ * `hs source branch declare [<branch>]` / `hs source branch show`.
+ * @param {string[]} argv args after the `branch` verb
+ * @returns {Promise<number>} exit code
+ */
+export async function runBranchCommand(
+  argv,
+  { fetchImpl = fetch, cwd = process.cwd(), consoleUrl, repoRoot, run, out = console.log, err = console.error } = {},
+) {
+  const sub = argv[0] ?? 'show';
+
+  if (sub === 'show') {
+    try {
+      const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+      if (!r.ok || !r.json?.target) {
+        err(`hs source branch show: console answered ${r.status} — no target available.`);
+        return 1;
+      }
+      const t = r.json.target;
+      out(`target branch: ${t.branch} (${t.source === 'session' ? 'declared by this session' : 'dated fallback — no session branch declared'})`);
+      if (t.reason) out(`note: declared branch was refused — ${t.reason}`);
+      if (r.json.declaration) out(`declared ${r.json.declaration.declaredAt}, expires ${r.json.declaration.expiresAt}`);
+      return 0;
+    } catch (e) {
+      err(`hs source branch show: console unreachable (${e instanceof Error ? e.message : String(e)}).`);
+      return 1;
+    }
+  }
+
+  if (sub === 'declare') {
+    const branch = argv[1] ?? currentGitBranch({ cwd, run });
+    if (!branch) {
+      err('hs source branch declare: no branch given and no checked-out branch (detached HEAD?).');
+      return 1;
+    }
+    try {
+      const r = await callConsole({ method: 'POST', body: { branch }, fetchImpl, consoleUrl, repoRoot });
+      if (!r.ok) {
+        err(`hs source branch declare: refused — ${r.json?.reason ?? r.json?.error ?? `HTTP ${r.status}`}`);
+        return 1;
+      }
+      out(`declared session branch: ${r.json.declaration.branch} (expires ${r.json.declaration.expiresAt})`);
+      return 0;
+    } catch (e) {
+      err(`hs source branch declare: console unreachable (${e instanceof Error ? e.message : String(e)}).`);
+      return 1;
+    }
+  }
+
+  err(`hs source branch: unknown subcommand \`${sub}\` — expected declare|show.`);
+  return 2;
+}
+
+function invokedDirectly() {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  // argv: [node, script, "branch", ...args]
+  runBranchCommand(process.argv.slice(3)).then((code) => process.exit(code));
+}