heyspex 0.1.0 → 0.2.0

package/scripts/lib/standalone-doctor.mjs

@@ -17,14 +17,17 @@
  *
  * `RUNTIME_FILES` is the same set `scripts/lib/packed-runtime-imports.test.mjs`
  * proves ships in the published tarball (its two explicitly-diagnosed
- * dynamic-import targets, the `hs source` entrypoints it spawns, and the two
- * `dist/cli/*.mjs` bundle entries `hs init`/`hs install` dispatch to) — this
+ * dynamic-import targets, the `hs source` entrypoints it spawns, and the
+ * `dist/cli/*.mjs` bundle entries `hs init`/`hs install`/`hs dev` dispatch to) — this
  * is deliberately the SAME list, not a re-derivation, so the two checks can
  * never silently drift apart (one says "ships", the other says "present").
  */
-import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { TEMPLATE_CORE_DESTS, TEMPLATE_VERSION } from "./template-pin.mjs";
+
 /**
  * Runtime files a published install must have next to `bin/hs.mjs` — each
  * entry is a path-segment array (portable across `path.join`/posix).
@@ -39,6 +42,9 @@ export const RUNTIME_FILES = Object.freeze([
   ["scripts", "lib", "hs-source-secret-scan.mjs"],
   ["dist", "cli", "hs-init.mjs"],
   ["dist", "cli", "hs-install.mjs"],
+  // HS-2HII: the `hs dev` bundle — invariant 10's visibility verb for a mode
+  // override, so a package missing it is named on the first command.
+  ["dist", "cli", "hs-dev.mjs"],
 ]);
 
 /**
@@ -87,3 +93,534 @@ export function runtimeFilesCheckRow(pkgRoot, opts = {}) {
       "if it's still missing after a clean reinstall, the published package itself is broken.",
   };
 }
+
+// ---------------------------------------------------------------------------
+// `vault-config` — the vault's `.heyspex/config.yaml` exists
+// ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]] fix 5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Path segments of the HeySpex workflow-settings file, relative to the VAULT
+ * root (ADR-0009 §1: the vault root is its one and only home; it is
+ * git-tracked there). Kept as a segment array like {@link RUNTIME_FILES}.
+ */
+export const VAULT_CONFIG_REL = Object.freeze([".heyspex", "config.yaml"]);
+
+/**
+ * Does `<vaultRoot>/.heyspex/config.yaml` exist? Returns `{ ok, path }` where
+ * `path` is the POSIX-joined RELATIVE path (never absolute — same
+ * no-machine-path-leak rule as {@link checkRuntimeFiles}). `exists` is the
+ * same injectable seam. A null/empty `vaultRoot` (no vault resolved at all)
+ * reports `ok: false` with `resolved: false` so the row can say WHY.
+ */
+export function checkVaultConfig(vaultRoot, { exists = existsSync } = {}) {
+  const relPosix = VAULT_CONFIG_REL.join("/");
+  if (typeof vaultRoot !== "string" || vaultRoot.length === 0) {
+    return { ok: false, resolved: false, path: relPosix };
+  }
+  const abs = join(vaultRoot, ...VAULT_CONFIG_REL);
+  return { ok: exists(abs), resolved: true, path: relPosix };
+}
+
+/**
+ * Render {@link checkVaultConfig}'s result as one `hs doctor` check row —
+ * the same `id`/`status`/`detail`/optional `human` shape as
+ * {@link runtimeFilesCheckRow}. FAILS when the file is missing: with it
+ * absent every settings reader falls to its registry/documented default
+ * (MVP mode off, strict task grain — the HS-4C76 symptom), and until the
+ * fix the settings faces refused to write at all. Both remedies now seed
+ * the file from the shipped template: `hs init` (in the vault directory),
+ * or any `hs settings set` / `heyspex_settings_set` write.
+ */
+export function vaultConfigCheckRow(vaultRoot, opts = {}) {
+  const { ok, resolved, path: relPosix } = checkVaultConfig(vaultRoot, opts);
+  if (ok) {
+    return {
+      id: "vault-config",
+      status: "ok",
+      detail: `${relPosix} present at the vault root`,
+    };
+  }
+  if (!resolved) {
+    return {
+      id: "vault-config",
+      status: "fail",
+      detail: `${relPosix} not checked — no vault root resolved`,
+      human:
+        "No vault was found (no heyspex.yaml / specs/ up from the invoked directory, no registry " +
+        "pointer). Run `hs init` in the directory that should become the vault — it seeds " +
+        `${relPosix} from the shipped template too.`,
+    };
+  }
+  return {
+    id: "vault-config",
+    status: "fail",
+    detail: `${relPosix} missing at the vault root`,
+    human:
+      `The vault has no ${relPosix}, so every HeySpex settings reader (console, MCP, CLI, hooks) ` +
+      "falls back to defaults — MVP mode reads as OFF and close-out gates go strict. Run `hs init` " +
+      "in the vault directory to seed it from the shipped template (an existing file is never " +
+      "touched), or any `hs settings set <key> <value>` — the settings core now seeds the file on " +
+      "its first write instead of refusing. Then commit it with the vault (ADR-0009).",
+  };
+}
+
+/** Marker file that only the HeySpex platform vault has: it IS the template source. */
+const PLATFORM_VAULT_MARKER =
+  "specs/protocols/dev-factory-delegation-routing.md";
+
+/** `template_version:` from raw `heyspex.yaml` text, or null (mirrors `readTemplateVersion` in init-git-finalize.ts). */
+function readTemplatePin(yamlText) {
+  const m = /^template_version:\s*(.+?)\s*$/m.exec(yamlText ?? "");
+  if (!m) return null;
+  const v = m[1]
+    .replace(/^"(.*)"$/, "$1")
+    .replace(/^'(.*)'$/, "$1")
+    .trim();
+  return v.length > 0 ? v : null;
+}
+
+/**
+ * The `vault-template` doctor row: does a customer vault carry the current
+ * HeySpex template (HS-KH0Q)? Pure over injectable `exists` / `readFile`
+ * (default node:fs; `readFile` returns the text or null), same row shape as
+ * {@link vaultConfigCheckRow}.
+ *   - platform vault (marker protocol present) -> ok: it is the template source;
+ *   - any core dest missing -> fail, naming the files, repair `hs init --customer-vault .`;
+ *   - `heyspex.yaml` pins {@link TEMPLATE_VERSION} -> ok;
+ *   - pin older/newer/absent while the files exist -> warn.
+ */
+export function templateCheckRow(vaultRoot, opts = {}) {
+  const exists = opts.exists ?? existsSync;
+  const readFile =
+    opts.readFile ??
+    ((p) => {
+      try {
+        return readFileSync(p, "utf8");
+      } catch {
+        return null;
+      }
+    });
+  const id = "vault-template";
+  const repair = "hs init --customer-vault .";
+  if (typeof vaultRoot !== "string" || vaultRoot.length === 0) {
+    return {
+      id,
+      status: "fail",
+      detail: "template not checked — no vault root resolved",
+      human: `No vault was found. Run \`${repair}\` in the directory that should become the vault.`,
+    };
+  }
+  const at = (rel) => join(vaultRoot, ...rel.split("/"));
+  if (exists(at(PLATFORM_VAULT_MARKER))) {
+    return {
+      id,
+      status: "ok",
+      detail: "platform vault (the template source, not a customer vault)",
+    };
+  }
+  const missing = TEMPLATE_CORE_DESTS.filter((rel) => !exists(at(rel)));
+  if (missing.length > 0) {
+    return {
+      id,
+      status: "fail",
+      detail: `missing template file(s): ${missing.join(", ")}`,
+      human:
+        `The vault is missing ${missing.length} shipped template file(s): ${missing.join(", ")}. ` +
+        `Run \`${repair}\` in the vault directory — it adds only what is missing and never overwrites an existing file.`,
+    };
+  }
+  const pin = readTemplatePin(readFile(at("heyspex.yaml")));
+  if (pin === TEMPLATE_VERSION) {
+    return {
+      id,
+      status: "ok",
+      detail: `template v${TEMPLATE_VERSION} pinned; all ${TEMPLATE_CORE_DESTS.length} core files present`,
+    };
+  }
+  return {
+    id,
+    status: "warn",
+    detail: pin
+      ? `heyspex.yaml pins template v${pin}, current is v${TEMPLATE_VERSION}`
+      : `heyspex.yaml has no template_version pin (current is v${TEMPLATE_VERSION})`,
+    human: `Core template files are present but the pin is not current. Run \`${repair}\` to refresh the pin and add any newer shipped files.`,
+  };
+}
+
+/**
+ * The `hs doctor` repair for a pre-v2 `~/.heyspex/registry.json`: the argv
+ * `--fix` hands to Node from the repo root (`bin/hs.mjs vault migrate-registry`,
+ * [[HS-RXLG-WW9R-TASK-key-registry-json-per-account-schema-v2]] AC5).
+ */
+export const REGISTRY_SCHEMA_FIX = Object.freeze([
+  "bin/hs.mjs",
+  "vault",
+  "migrate-registry",
+]);
+
+/**
+ * Classify the raw text of `~/.heyspex/registry.json` (`null` = no file). Pure.
+ * Mirrors `registry-file.ts`'s `inspectVaultRegistry` + `hasLegacyAccountState`
+ * on the fields a doctor needs:
+ *   - `missing`    — nothing registered on this machine yet;
+ *   - `unreadable` — the file is not a JSON object (the loader reads it as
+ *                    empty, and the next write would start over);
+ *   - `v1`         — machine-global pointers, rows with no account;
+ *   - `legacy`     — v2, but some state is still keyed to `legacy` (migrated
+ *                    while signed out, or written before migration);
+ *   - `v2`         — per-account pointers, every row keyed.
+ */
+export function classifyRegistryFile(rawText) {
+  if (rawText === null || rawText === undefined) return { kind: "missing" };
+  let json;
+  try {
+    json = JSON.parse(rawText);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json))
+    return { kind: "unreadable" };
+  if (json.schema_version !== 2) return { kind: "v1" };
+  const LEGACY = "legacy";
+  const rows = [
+    ...(Array.isArray(json.workspaces) ? json.workspaces : []),
+    ...(Array.isArray(json.vaults) ? json.vaults : []),
+  ];
+  const accounts =
+    json.accounts && typeof json.accounts === "object" ? json.accounts : {};
+  const legacy =
+    Object.prototype.hasOwnProperty.call(accounts, LEGACY) ||
+    json.current_account_id === LEGACY ||
+    rows.some(
+      (r) => r && typeof r === "object" && (r.account_id ?? LEGACY) === LEGACY,
+    );
+  return { kind: legacy ? "legacy" : "v2" };
+}
+
+/**
+ * Render {@link classifyRegistryFile} as one `hs doctor` row (`registry-schema`).
+ * A v1 file (or v2 with `legacy` state) is a `warn` that carries
+ * {@link REGISTRY_SCHEMA_FIX}, so `hs doctor --fix` runs `hs vault
+ * migrate-registry`. It is a warn, not a fail: the loader still reads a v1
+ * file. An unreadable file is a warn with no fix — the migration refuses to
+ * overwrite it, so a human looks first.
+ */
+export function registrySchemaCheckRow(rawText) {
+  const { kind } = classifyRegistryFile(rawText);
+  const id = "registry-schema";
+  if (kind === "missing") {
+    return {
+      id,
+      status: "ok",
+      detail: "no ~/.heyspex/registry.json yet (nothing registered)",
+    };
+  }
+  if (kind === "v2") {
+    return {
+      id,
+      status: "ok",
+      detail: "schema v2 (active vault/workspace kept per account)",
+    };
+  }
+  if (kind === "unreadable") {
+    return {
+      id,
+      status: "warn",
+      detail: "~/.heyspex/registry.json is unreadable — it loads as empty",
+      human:
+        "The registry file is not valid JSON, so every reader treats it as empty and the next " +
+        "`hs connect` / `hs vault register` would start it over. Fix or move it aside by hand " +
+        "(`hs vault migrate-registry` will not overwrite it).",
+    };
+  }
+  const detail =
+    kind === "v1"
+      ? "schema v1 — one machine-global active vault for every account"
+      : "schema v2, but some rows are still keyed to `legacy` (no account)";
+  return {
+    id,
+    status: "warn",
+    detail: `${detail}; fix: \`hs vault migrate-registry\``,
+    fix: [...REGISTRY_SCHEMA_FIX],
+    human:
+      "Run `hs vault migrate-registry --dry-run` to see the plan, then `hs vault migrate-registry` " +
+      "(or `hs doctor --fix`) while signed in: it rewrites ~/.heyspex/registry.json as schema v2 " +
+      "and keys each row to the account PROVEN for it (its heyspex.yaml `account:`, or your cloud " +
+      "vault roster). Unproven rows stay `legacy` and keep resolving. A second run changes nothing.",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// `connection` — the local-vs-cloud view, folded from `hs connect --check
+// --json` ([[HS-W73V-WW9R-TASK-make-both-doctor-shapes-fail-on-cloud]],
+// invariant 8: proof from both sides)
+// ---------------------------------------------------------------------------
+//
+// ONE fold for both doctor shapes: the full doctor (`scripts/heyspex-doctor.mjs`,
+// source checkout) and the published-install doctor (`bin/hs.mjs`
+// `runStandaloneDoctor`) both feed the SAME report through
+// `foldConnectionReport`, so a broken setup reads the same on any machine.
+// Neither doctor keeps its own list of comparison rows: the report is computed
+// by `spex-console/src/lib/cli/connect-checks.ts` from the routing fact table
+// (`routing-facts.ts`), and a cloud-view row is recognised by the field it
+// carries (`agree`: only the seven local-vs-cloud rows have it), never by a
+// second copy of its id list.
+
+/** The connection section's summary row id; per-artifact rows are `connect-<id>`. */
+export const CONNECTION_ROW_ID = "connect";
+
+/**
+ * The connect-check report on a stream. `hs connect --check --json` prints its
+ * payload as ONE JSON line, but other output may precede or follow it (the
+ * identity note, a customer-kit line from the bundle), so every `{`-led line
+ * is tried and the LAST one with the report's shape wins; a pretty-printed
+ * whole-stream document is the fallback. Pure.
+ * @returns {{ ok: true, report: object } | { ok: false, error: string }}
+ */
+export function parseConnectCheckOutput(text) {
+  const isReport = (v) =>
+    v &&
+    typeof v === "object" &&
+    typeof v.connected === "boolean" &&
+    Array.isArray(v.checks);
+  const candidates = [];
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    if (!/^\s*\{/.test(line)) continue;
+    try {
+      candidates.push(JSON.parse(line));
+    } catch {
+      // not a one-line document
+    }
+  }
+  try {
+    candidates.push(JSON.parse(String(text ?? "")));
+  } catch {
+    // not one whole document either
+  }
+  const report = candidates.filter(isReport).pop();
+  if (report) return { ok: true, report };
+  if (candidates.length === 0) {
+    return { ok: false, error: "`hs connect --check --json` printed no JSON" };
+  }
+  return {
+    ok: false,
+    error: "`hs connect --check --json` returned an unexpected shape",
+  };
+}
+
+/** A local-vs-cloud row: the only rows of the report that carry `agree`. Pure. */
+export function isCloudViewRow(check) {
+  return (
+    Boolean(check) && typeof check === "object" && Object.hasOwn(check, "agree")
+  );
+}
+
+const sideText = (v) =>
+  v === null || v === undefined || v === "" ? "(unknown)" : String(v);
+
+/**
+ * One report row to one doctor row. The severity rule (HS-W73V AC1/AC2):
+ *   - local artifact rows keep the pre-W73V behaviour: `present` (and
+ *     `not_applicable`, which the report's own `connected` already accepts) is
+ *     ok, anything else a warn with no fix ("not connected" is a
+ *     recommendation, never a failure);
+ *   - a cloud-view row whose two sides DISAGREE (`agree: false`) is a `fail`
+ *     whose `human` is the row's own `repair` command, verbatim;
+ *   - a cloud-view row whose other side could not be read (`agree: null`,
+ *     not `not_applicable`) is a `warn` naming the cause: unknown is never
+ *     success, and never a failure on its own;
+ *   - agreeing and not-applicable cloud rows are ok.
+ * Cloud rows keep `local` / `cloud` / `agree` / `repair` / `fact` so the JSON
+ * shows both sides next to each other.
+ */
+function foldCheckRow(check, idPrefix) {
+  const base = {
+    id: `${idPrefix}-${check.id}`,
+    label: `Connect: ${check.label ?? check.id}`,
+    fix: null,
+  };
+  if (!isCloudViewRow(check)) {
+    return {
+      ...base,
+      // `not_applicable` counts as connected in the report itself (`connected`).
+      status:
+        check.status === "present" || check.status === "not_applicable"
+          ? "ok"
+          : "warn",
+      detail: check.detail
+        ? `${check.status} (${check.detail})`
+        : String(check.status),
+    };
+  }
+  const view = {
+    local: check.local ?? null,
+    cloud: check.cloud ?? null,
+    agree: check.agree ?? null,
+    repair: check.repair ?? null,
+    ...(check.fact ? { fact: check.fact } : {}),
+  };
+  const sides = `local: ${sideText(view.local)} | cloud: ${sideText(view.cloud)}`;
+  if (check.status === "not_applicable") {
+    return {
+      ...base,
+      ...view,
+      status: "ok",
+      detail: `not applicable — ${check.detail ?? "nothing to compare"}`,
+    };
+  }
+  if (view.agree === true) {
+    return { ...base, ...view, status: "ok", detail: `${sides} — agree` };
+  }
+  if (view.agree === false) {
+    return {
+      ...base,
+      ...view,
+      status: "fail",
+      detail: `${sides} — DISAGREE: ${check.detail ?? "the two sides differ"}`,
+      human:
+        view.repair ??
+        "Run `hs connect --check` to see the disagreement and its repair.",
+    };
+  }
+  return {
+    ...base,
+    ...view,
+    status: "warn",
+    detail: `local: ${sideText(view.local)} | cloud: unknown — ${check.detail ?? "the cloud side could not be read"}`,
+    ...(view.repair ? { human: view.repair } : {}),
+  };
+}
+
+/**
+ * Fold a `hs connect --check --json` result (`parseConnectCheckOutput`'s
+ * `{ ok, report }`, or `{ ok: false, error }` when it could not be run) into
+ * doctor rows: one summary row (`connect`) plus one row per report row
+ * (`connect-<id>`). The summary FAILS when any cloud row fails; otherwise it
+ * is a warn for an unconnected repo or an unknown cloud side, else ok. Rows
+ * never carry a `fix`: doctor never runs `hs connect` for you, `--fix`
+ * included. Pure.
+ *
+ * Returns `{ rows, json, ok }`: `json` is the raw report (doctor's
+ * `connection` key) plus `cloud_view` counts; `ok` is false iff a row failed.
+ */
+export function foldConnectionReport(
+  surface,
+  {
+    idPrefix = CONNECTION_ROW_ID,
+    label = "HeySpex connection (hs connect --check)",
+    connectCommand = "hs connect",
+    checkCommand = "hs connect --check",
+  } = {},
+) {
+  if (!surface?.ok) {
+    const error = surface?.error ?? "no report";
+    return {
+      rows: [
+        {
+          id: idPrefix,
+          label,
+          status: "warn",
+          detail: `connection state unknown — ${error}`,
+          human: `Run \`${checkCommand}\` directly to see the full report — this check never runs it for you.`,
+          fix: null,
+        },
+      ],
+      json: { checked: false, connected: null, error },
+      ok: true,
+    };
+  }
+  const report = surface.report;
+  const checks = Array.isArray(report.checks) ? report.checks : [];
+  const rows = checks.map((c) => foldCheckRow(c, idPrefix));
+  const cloudRows = rows.filter((_r, i) => isCloudViewRow(checks[i]));
+  const failed = cloudRows.filter((r) => r.status === "fail");
+  const unknown = cloudRows.filter((r) => r.status === "warn");
+  const agreed = cloudRows.filter((r) => r.status === "ok" && r.agree === true);
+  const localConnected = checks
+    .filter((c) => !isCloudViewRow(c))
+    .every((c) => c.status === "present" || c.status === "not_applicable");
+
+  let summary;
+  if (failed.length > 0) {
+    const repairs = [...new Set(failed.map((r) => r.repair).filter(Boolean))];
+    summary = {
+      status: "fail",
+      detail: `${failed.length} local-vs-cloud row(s) disagree: ${failed.map((r) => r.id.slice(idPrefix.length + 1)).join(", ")}`,
+      human: `Run the repair named on each failing row: ${repairs.join("; ")}`,
+    };
+  } else if (!localConnected) {
+    summary = {
+      status: "warn",
+      detail: `not connected to HeySpex — run \`${connectCommand}\``,
+      human: `Run \`${connectCommand}\` to wire this repo up to HeySpex — this check recommends it but never runs it for you.`,
+    };
+  } else if (unknown.length > 0) {
+    summary = {
+      status: "warn",
+      detail: `connected locally; the cloud side is unknown on ${unknown.length} row(s) — ${unknown[0].detail.replace(/^.*?cloud: unknown — /, "")}`,
+    };
+  } else {
+    summary = {
+      status: "ok",
+      detail: `connected — ${checks.length} row(s); local and cloud agree on ${agreed.length} row(s)`,
+    };
+  }
+  return {
+    rows: [{ id: idPrefix, label, fix: null, ...summary }, ...rows],
+    json: {
+      checked: true,
+      connected: report.connected,
+      repo_root: report.repo_root,
+      checks,
+      ...(report.satellite ? { satellite: report.satellite } : {}),
+      cloud_view: {
+        agree: agreed.length,
+        disagree: failed.length,
+        unknown: unknown.length,
+      },
+    },
+    ok: failed.length === 0,
+  };
+}
+
+/**
+ * Run the BUNDLED `dist/cli/hs-connect.mjs connect --check --json` of a
+ * published install (the package ships it; `scripts/heyspex-doctor.mjs` does
+ * not) and parse its report. The bundle's cloud view is GET-only by
+ * construction (`connect-checks.ts` `cloudGet`). `spawn` / `exists` are
+ * injectable for tests.
+ * @returns {{ ok: true, report: object } | { ok: false, error: string }}
+ */
+export function runBundledConnectCheck(
+  pkgRoot,
+  {
+    cwd,
+    env = process.env,
+    spawn = spawnSync,
+    timeoutMs = 60_000,
+    exists = existsSync,
+  } = {},
+) {
+  const script = join(pkgRoot, "dist", "cli", "hs-connect.mjs");
+  if (!exists(script)) {
+    return {
+      ok: false,
+      error: "dist/cli/hs-connect.mjs is missing from this install",
+    };
+  }
+  const r = spawn(process.execPath, [script, "connect", "--check", "--json"], {
+    cwd,
+    env,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (r.error) {
+    return {
+      ok: false,
+      error: `could not run \`hs connect --check --json\`: ${r.error.message}`,
+    };
+  }
+  return parseConnectCheckOutput(r.stdout);
+}

package/scripts/lib/subagent-git-lock.mjs

@@ -0,0 +1,109 @@
+// scripts/lib/subagent-git-lock.mjs
+//
+// The orchestrator (COO)'s hard lock around a delegated sub-agent's work
+// window (HS-H8KI-P3TJ, epic HS-GG01-P3TJ). While set, EVERY destructive git
+// command in the covered session is denied outright by
+// scripts/claude-hooks/git-stash-gate.mjs's runGitDestructiveGate — no intent
+// file can override it (deny beats ask beats allow; this task may only
+// ESCALATE toward deny, never soften toward allow — see
+// specs/memory/decisions/protected-shared-tree-actions-assisted.md).
+//
+// SPIKE VERDICT (HS-H8KI, static analysis, no harness spawn): Claude Code's
+// PreToolUse hook payload carries NO sub-agent identity distinguishing an
+// orchestrator's own tool calls from a spawned sub-agent's. The only identity
+// field present anywhere in this repo's hook payloads is `session_id`
+// (resolved by scripts/claude-hooks/claim-liveness-shared.mjs's
+// resolveSessionId) — and it is the SAME value for every tool call inside one
+// CLI session, orchestrator and any Task-tool-spawned sub-agent alike (they
+// share one process/session). Every hook in scripts/claude-hooks/ that reads
+// `transcript_path` (enforce-session-sequence.mjs, naughty-list-gate.mjs,
+// id-display-format-gate.mjs) uses it for OTHER purposes; none of them, and no
+// other file in this repo, reads an `agentId`/`isSidechain`/`sidechain` field —
+// because the standard PreToolUse schema does not carry one
+// (hook_event_name, session_id, transcript_path, cwd, tool_name, tool_input,
+// tool_response are the complete field set observed across every hook here).
+// Conclusion: per-agent locking is NOT possible from the hook payload alone.
+// This module therefore implements the SESSION-WIDE fallback the task
+// prescribes for that case — keyed by session id (so concurrent sessions on
+// different checkouts/agents never share lock state), but NOT distinguishing
+// the orchestrator's own tool calls from its delegated sub-agent's within that
+// one session. That is the correct scope for the orchestrator's own use: it
+// sets the lock immediately before spawning a sub-agent for destructive-git-
+// adjacent delegated work and clears it right after the sub-agent returns, so
+// the lock's live window IS the delegation window regardless of which of the
+// two (orchestrator or sub-agent) happens to issue the git command.
+//
+// A session id may be unresolvable (e.g. a bare script run outside any hook
+// context) — that case files under a fixed NO_SESSION_KEY so it still works
+// but is trivially inspectable in .heyspex/subagent-locks/ instead of being
+// silently lost.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const LOCK_DIR_NAME = 'subagent-locks';
+const NO_SESSION_KEY = '_no-session-id';
+
+/** Filesystem-safe key for a session id (or the fixed fallback key). Exported for tests. */
+export function lockKey(sessionId) {
+  const trimmed = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!trimmed) return NO_SESSION_KEY;
+  return trimmed.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+
+export function lockDir(root) {
+  return path.join(root, '.heyspex', LOCK_DIR_NAME);
+}
+
+export function lockPath(root, sessionId) {
+  return path.join(lockDir(root), `${lockKey(sessionId)}.json`);
+}
+
+/**
+ * Set the session-wide hard lock. Idempotent — calling it again while already
+ * set just overwrites the record (last setter wins; there is deliberately no
+ * "already locked" error since the orchestrator is the only writer of its own
+ * lock file).
+ *
+ * @returns {object} the record written
+ */
+export function setSubagentLock({ root, sessionId = null, reason = null, setBy = null, now = Date.now() }) {
+  const dir = lockDir(root);
+  fs.mkdirSync(dir, { recursive: true });
+  const record = {
+    sessionId: sessionId ?? null,
+    reason: reason ?? null,
+    setBy: setBy ?? null,
+    setAt: new Date(now).toISOString(),
+  };
+  const target = lockPath(root, sessionId);
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(record, null, 2));
+  fs.renameSync(tmp, target);
+  return record;
+}
+
+/** Clear the session-wide hard lock. Returns true if a lock file was actually removed. */
+export function clearSubagentLock({ root, sessionId = null }) {
+  try {
+    fs.rmSync(lockPath(root, sessionId), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the current lock record for `sessionId`, or null when unset/unreadable.
+ * Never throws — a corrupt lock file reads as "no lock" (fail toward allowing
+ * the gate to proceed to its next check, never toward a crash).
+ */
+export function checkSubagentLock({ root, sessionId = null }) {
+  try {
+    const raw = fs.readFileSync(lockPath(root, sessionId), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}