heyspex 0.1.0 → 0.2.1

package/spexharness/src/config-root.mjs

@@ -0,0 +1,54 @@
+// spexharness/src/config-root.mjs
+//
+// The ONE answer to "which directory holds `.heyspex/config.yaml`?" for every
+// hook-side reader: the plugin loader (scripts/claude-hooks/_guardrail-loader.mjs),
+// the harness's own leaf reader (./intent-directive.mjs) and the gate-rows
+// severity resolver (./gate-rows.mjs) all default to this.
+//
+// Per ADR-0009 §1 the workflow-settings file lives at the VAULT root — the
+// directory the active-vault resolver (vendor/heyspex-mcp/vault-resolve.mjs)
+// reports as `repoRootAbs`. Since the 2026-08-31 repo split that is a separate
+// checkout from this code repo, and every hook-side reader that still joined
+// `config.yaml` onto the CODE root (DEFAULT_REPO_ROOT / DEFAULT_APP_ROOT) was
+// silently reading a stale copy while the MCP, CLI and console read the vault —
+// [[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]].
+//
+// ONLY `config.yaml` moves. The guardrail registry (`.heyspex/guardrails.json`),
+// the terminology override, the event/history logs, the dev-server lock and the
+// fleet-queue lanes are code-repo artifacts and keep resolving from the code
+// root — the same CODE_ROOT vs vault-root split scripts/lib/resolve-validate-root.mjs
+// makes for the validators (memory lesson [[after-the-repo-split-every-live-specs]]).
+//
+// FAIL-SAFE: resolution is fs/env only (no network) and `getActiveConfig()`
+// memoizes it once per process; if it throws for any reason the code root is
+// returned so a hook never strands the agent. Deliberately NOT memoized a second
+// time here — tests call `resetActiveConfigCache()` between cases and expect the
+// next read to re-resolve.
+//
+// Layering: a harness module importing from vendor/heyspex-mcp, the same
+// direction ./intent-directive.mjs and ./gates/enforce-session-sequence.mjs
+// already take. Never imports from scripts/claude-hooks.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { getActiveConfig } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+
+/** spexharness/src/ → the code checkout is two levels up. */
+export const CODE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/**
+ * The directory `.heyspex/config.yaml` is read from when a caller passes no
+ * explicit root: the active vault's repo root, else (resolution threw) the code
+ * checkout. Explicit `repoRoot` arguments on the readers always win over this.
+ *
+ * @returns {string}
+ */
+export function defaultConfigRoot() {
+  try {
+    const root = getActiveConfig()?.repoRootAbs;
+    return typeof root === 'string' && root.trim() ? root : CODE_ROOT;
+  } catch {
+    return CODE_ROOT;
+  }
+}

package/spexharness/src/context-budget.mjs

@@ -0,0 +1,141 @@
+// spexharness/src/context-budget.mjs
+//
+// The harness's single context-injection measurement path (HS-7UAQ, epic HS-1YDJ). Every
+// frontend that puts something into a seat's context window — a Claude Code hook shell run
+// through spexharness/src/adapters/claude-code.mjs, the plugin's own SessionStart pieces,
+// a headless seat's bootstrap (session-bootstrap.mjs), an overnight loop run — reports that
+// injection through {@link recordContextInjection}. Nothing else in the harness writes a
+// context-injection line into a session record; this is the one path every frontend goes
+// through, which is what makes the resulting inventory trustworthy across fronts.
+//
+// Sizing is NOT reimplemented here: measuring one piece delegates to
+// spexharness/src/token-inventory.mjs's `measurePiece` (itself built on
+// dev-factory/lib/context-budget.mjs's `estimateTokens`), so this module owns WHERE a
+// measurement is recorded, not HOW big a piece of text is. Recording delegates to
+// spexharness/src/session-record.mjs's `recordEvent`, so the injection lands as an ordinary
+// event on the session record (`point: 'context_injection'`) rather than a bespoke array —
+// a session record inspector that already walks `record.events` sees these for free.
+//
+// Pure: no I/O, no console. `record` is mutated in place (matching recordEvent's and
+// recordToolCall's own contract) and the measured piece is returned so a caller can log or
+// assert on it without re-reading the record.
+
+import { measurePiece } from './token-inventory.mjs';
+import { recordEvent } from './session-record.mjs';
+
+/** The session-record event point every context injection is recorded under. */
+export const CONTEXT_INJECTION_POINT = 'context_injection';
+
+/**
+ * @typedef {object} ContextInjectionMeasurement
+ * @property {string} source   who injected it — a hook id, a gate id, 'seat-context',
+ *   'wip', 'memories', 'procedures', etc. Required in spirit (falls back to 'unknown'
+ *   rather than throwing, matching the rest of the harness's fail-soft posture).
+ * @property {string} name     a human label for the piece; defaults to `source`.
+ * @property {number} tokens   the measured (or caller-supplied) token count.
+ * @property {number} chars    the measured byte/char length of the injected text.
+ * @property {boolean} estimated  true when `tokens` came from the chars/4 estimate
+ *   rather than a caller-supplied exact count.
+ */
+
+/**
+ * Measure and record ONE context injection into `record`. This is the single reporting
+ * path (AC2): a chat front, a plugin hook shell, and a headless seat all call this same
+ * function — none of them measures or records a piece any other way.
+ *
+ * @param {ReturnType<import('./session-record.mjs').createSessionRecord>} record
+ * @param {{ source?: string, name?: string, text?: string, tokens?: number, priority?: number, ts?: number }} [injection]
+ * @returns {ContextInjectionMeasurement} the measurement that was recorded.
+ */
+export function recordContextInjection(record, injection = {}) {
+  const { source, name, text, tokens, priority, ts } = injection;
+  const measured = measurePiece({ name: name ?? source, text, tokens, priority }, record?.events?.length ?? 0);
+  const decision = {
+    source: source ? String(source) : 'unknown',
+    name: measured.name,
+    tokens: measured.tokens,
+    chars: measured.chars,
+    estimated: measured.estimated,
+  };
+  recordEvent(record, { point: CONTEXT_INJECTION_POINT, ts }, decision);
+  return decision;
+}
+
+/**
+ * Every context-injection measurement recorded on `record` so far, in the order they were
+ * recorded. This is what "the session record shows bytes per injection with a source"
+ * (AC3) means in practice — a caller reads this instead of re-deriving it from raw events.
+ *
+ * @param {ReturnType<import('./session-record.mjs').createSessionRecord>|null} record
+ * @returns {ContextInjectionMeasurement[]}
+ */
+export function contextInjectionsOf(record) {
+  return (record?.events ?? [])
+    .filter((e) => e && e.point === CONTEXT_INJECTION_POINT)
+    .map((e) => e.decision)
+    .filter(Boolean);
+}
+
+/**
+ * Roll up every context injection recorded on `record`: total tokens/chars, and a
+ * per-source breakdown — the shape a `hs harness context` printer (or a test asserting a
+ * budget target) reads from.
+ *
+ * @param {ReturnType<import('./session-record.mjs').createSessionRecord>|null} record
+ * @returns {{
+ *   injections: ContextInjectionMeasurement[],
+ *   totalTokens: number,
+ *   totalChars: number,
+ *   bySource: Record<string, { tokens: number, chars: number, count: number }>,
+ * }}
+ */
+export function summarizeContextInjections(record) {
+  const injections = contextInjectionsOf(record);
+  const bySource = {};
+  let totalTokens = 0;
+  let totalChars = 0;
+  for (const injection of injections) {
+    totalTokens += injection.tokens || 0;
+    totalChars += injection.chars || 0;
+    const bucket = bySource[injection.source] ?? { tokens: 0, chars: 0, count: 0 };
+    bucket.tokens += injection.tokens || 0;
+    bucket.chars += injection.chars || 0;
+    bucket.count += 1;
+    bySource[injection.source] = bucket;
+  }
+  return { injections, totalTokens, totalChars, bySource };
+}
+
+/**
+ * Context-window-used percentage for a non-Claude-Code session (HS-CUWH, epic HS-8CMW) — the
+ * one figure the spexcode status line needs to show a real context number for a seat that
+ * isn't Claude Code (which reports its own). Deliberately NOT a second sizing path: the
+ * caller resolves `usedTokens` however it already knows tokens (a real usage count from a
+ * model response, or this module's own chars/4 `estimateTokens` from token-inventory.mjs when
+ * only characters are tracked — see spexharness/src/chat/chat-loop.mjs's `windowTokens` wiring
+ * for that fallback in practice) and `windowTokens` from the model's context window; this
+ * function only turns the two into a percentage.
+ *
+ * Returns the explicit marker `null` — never an invented number — when either input is
+ * missing, non-numeric, or non-positive, so a caller/renderer can print "unknown" instead of
+ * a misleading 0%.
+ *
+ * @param {{ usedTokens?: number, windowTokens?: number }} [args]
+ * @returns {number|null} an integer 0-100 (rounded, clamped at 100), or `null` when unknown.
+ */
+export function contextUsedPercent({ usedTokens, windowTokens } = {}) {
+  const used = Number(usedTokens);
+  const window = Number(windowTokens);
+  if (!Number.isFinite(used) || used <= 0) return null;
+  if (!Number.isFinite(window) || window <= 0) return null;
+  const pct = Math.round((used / window) * 100);
+  return Math.min(100, pct);
+}
+
+export default {
+  recordContextInjection,
+  contextInjectionsOf,
+  summarizeContextInjections,
+  contextUsedPercent,
+  CONTEXT_INJECTION_POINT,
+};

package/spexharness/src/dev-server-control.mjs

@@ -0,0 +1,389 @@
+// spexharness/src/dev-server-control.mjs
+//
+// The SHARED dev-server protection logic — moved here verbatim from
+// scripts/claude-hooks/dev-server-task-reminder.mjs (task HS-SJD3-D0UC,
+// protocol [[protected-shared-actions-gate]]) as wave 6 of [[HS-AZ61-NYPR]]
+// turned that hook into a thin shim over ./gates/dev-server-task-reminder.mjs.
+// There is exactly ONE copy of the start/stop classification, the worktree
+// bypass, the front read, and the fleet-queue claim wrapper in the tree: this
+// one. The gate imports it; the Claude Code shim reaches it through the gate;
+// scripts/claude-hooks/dev-server-task-reminder.smoke.mjs drives it directly.
+//
+// TIER 1 (hard gate): starting or stopping the shared spex-console dev server
+// is a PROTECTED action. In Assisted front it ALWAYS asks (approving IS the
+// permission). In Autonomous front it requires a fleet-queue claim on this
+// checkout's `dev-server-<checkout-key>` lane: a second agent's concurrent
+// attempt is rejected while the claim is held, and can retry after
+// release/TTL expiry. Worktree-isolated agents bypass entirely — each has its
+// own server/port ([[parallel-agent-isolation-guidance]]), so there is no
+// shared resource to gate.
+//
+// TIER 2 (soft reminder): a server-impacting command (migration, Neon branch
+// reset, dependency install, .next delete, a second `next dev`) gets a warning
+// naming the live port, and only when the ground-truth status core says a
+// server is actually up. It NEVER blocks.
+//
+// Pure-ish: the classification/reminder half is pure; the claim, audit, lock
+// and status halves do I/O and every path they touch is a parameter.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// 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 ([[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]]).
+import { hsCommand } from '../../scripts/lib/hs-command.mjs';
+import { enqueue, claim, complete, list } from '../../dev-factory/lib/fleet-queue.mjs';
+
+/** spexharness/src/ → repo root is two levels up. */
+const DEFAULT_REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** The `.heyspex/config.yaml` leaf that can revert tier 1 to legacy warn-only. */
+export const TOGGLE_KEY = 'agent_behaviors.dev_server_control.enabled';
+
+/** Env-first repo-root resolution, matching every pre-cutover hook's own helper. */
+export function repoRoot(env = process.env) {
+  const fromEnv = env.CLAUDE_PROJECT_DIR?.trim();
+  if (fromEnv) return fromEnv.replace(/[\\/]+$/, '');
+  return DEFAULT_REPO_ROOT;
+}
+
+// ── TIER 2 — warn-only server-impacting detection ───────────────────────────
+
+/** Shell-command patterns that can break / collide with a running dev server. */
+export const SERVER_IMPACTING_COMMAND_PATTERNS = [
+  /\bdb:(?:migrate|baseline|generate|push)\b/, // npm run db:* (Drizzle migrations)
+  /\bdrizzle-kit\b/,
+  /\bmigrate\.mjs\b/,
+  /\bnpm\s+run\s+dev\b/, // starting a second wrapped dev server
+  /\bnext\s+dev\b/, // starting a bare second dev server
+  /\b(?:npm|pnpm|yarn)\s+(?:i|install|ci|add)\b/, // dependency changes (need a restart)
+  // Deleting the .next build dir out from under a running server.
+  /\brm\s+-[a-zA-Z]*r[a-zA-Z]*f?[a-zA-Z]*\s+[^|;&\n]*\.next\b/,
+  /\bRemove-Item\b[^|;&\n]*\.next\b/i,
+];
+
+/**
+ * Neon MCP tools that mutate the schema / endpoint the running server is bound
+ * to. Matched on tool name.
+ */
+export const SERVER_IMPACTING_TOOL_NAMES = new Set([
+  'mcp__neon__prepare_database_migration',
+  'mcp__neon__complete_database_migration',
+  'mcp__neon__reset_from_parent',
+  'mcp__neon__delete_branch',
+  'mcp__Neon__prepare_database_migration',
+  'mcp__Neon__complete_database_migration',
+  'mcp__Neon__reset_from_parent',
+  'mcp__Neon__delete_branch',
+]);
+
+/** True when this tool call could break a running dev server. */
+export function isServerImpacting(toolName, toolInput) {
+  if (typeof toolName === 'string' && SERVER_IMPACTING_TOOL_NAMES.has(toolName)) return true;
+  if (toolName === 'Bash' || toolName === 'PowerShell') {
+    const command = toolInput?.command;
+    if (typeof command === 'string' && command.trim()) {
+      return SERVER_IMPACTING_COMMAND_PATTERNS.some((re) => re.test(command));
+    }
+  }
+  return false;
+}
+
+/** Build the soft-reminder text from a status verdict, or null if no server is live. */
+export function buildReminder(status) {
+  if (!status || !status.running) return null;
+  const live = (status.servers || []).filter((s) => s.probe === 'console');
+  const where = live.map((s) => `:${s.port}${s.pid ? ` (listener pid ${s.pid})` : ''}`).join(', ');
+  const launcherPid = status.lockfile?.present && status.lockfile?.pid ? status.lockfile.pid : null;
+  const stopHint = launcherPid
+    ? `Ctrl+C in its terminal, or stop the launcher process (pid ${launcherPid}), or run /kill-ports`
+    : 'Ctrl+C in its terminal, or run /kill-ports';
+  return (
+    `⚠ A spex-console dev server is RUNNING (${where}) and this command can break it. ` +
+    `Running a migration / schema change under a live server strands its in-memory ` +
+    `schema and forces a restart. Recommended: stop the server first (${stopHint}), run ` +
+    `the task, then restart with \`npm run dev\`. Re-check with \`${hsCommand('server status')}\` / ` +
+    `heyspex_dev_server_status. (Proceeding anyway is allowed — this is a reminder, not a block. ` +
+    `Mute: HEYSPEX_DEV_SERVER_REMINDER_OFF=1.)`
+  );
+}
+
+/**
+ * Ground-truth dev-server status. The answer comes from
+ * scripts/dev-server-status.mjs — the SAME core `heyspex_dev_server_status`
+ * itself calls (vendor/heyspex-mcp/dev-tools.mjs's `handleDevServerStatus` is a
+ * three-line wrapper over it), so an in-process tool-catalog call and this
+ * function cannot disagree.
+ *
+ * @param {string} root
+ * @returns {Promise<object>}
+ */
+export async function getStatus(root = repoRoot()) {
+  const coreUrl = pathToFileURL(path.join(root, 'scripts', 'dev-server-status.mjs')).href;
+  const mod = await import(coreUrl);
+  return mod.getDevServerStatus({ vaultRoot: root });
+}
+
+// ── TIER 1 — hard gate for dev-server START/STOP ────────────────────────────
+
+// Narrow start/stop detection — deliberately NOT the broad
+// SERVER_IMPACTING_COMMAND_PATTERNS set above (migration/install detection stays
+// warn-only, unchanged). Per protected-shared-actions-gate.md Gate 1.
+const START_PATTERNS = [/\bnpm\s+run\s+dev\b/, /\bnext\s+dev\b/];
+
+/**
+ * Generic process-kill commands (Stop-Process / taskkill / bare kill) are
+ * ambiguous on their own — an agent kills stray processes for all kinds of
+ * reasons. They only count as a server STOP when they target the recorded
+ * dev-server lock pid. `/kill-ports` is the one exception: it is the
+ * dev-server-aware skill/CLI, already scoped to the recorded lock port.
+ */
+export function extractKillTargetPid(command) {
+  let m = command.match(/Stop-Process\s+(?:-Id\s+)?(\d+)/i);
+  if (m) return Number(m[1]);
+  m = command.match(/taskkill\b[^\n]*?\/pid\s+(\d+)/i);
+  if (m) return Number(m[1]);
+  // `kill <pid>` / `kill -9 <pid>` — word-boundaried so it never matches
+  // "skill" or "killed" inside prose/paths.
+  m = command.match(/(?:^|[\s;&|(])kill\s+(?:-\d+\s+)?(\d+)\b/i);
+  if (m) return Number(m[1]);
+  return null;
+}
+
+/** The recorded dev-server launcher pid, or null when there is no lockfile. */
+export function readLockPid(repoRootPath) {
+  try {
+    const raw = JSON.parse(
+      fs.readFileSync(path.join(repoRootPath, '.heyspex', 'dev-server.lock.json'), 'utf8'),
+    );
+    return typeof raw?.pid === 'number' ? raw.pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify a tool call as a dev-server 'start', 'stop', or null. `lockPid` (the
+ * currently-recorded dev-server launcher pid, or null) scopes the generic kill
+ * commands to the actual server — a `kill <unrelated-pid>` never counts.
+ */
+export function classifyServerStartStop(toolName, toolInput, { lockPid = null } = {}) {
+  if (
+    toolName === 'Skill' &&
+    typeof toolInput?.skill === 'string' &&
+    /kill-ports/i.test(toolInput.skill)
+  ) {
+    return 'stop';
+  }
+  if (toolName !== 'Bash' && toolName !== 'PowerShell') return null;
+  const command = toolInput?.command;
+  if (typeof command !== 'string' || !command.trim()) return null;
+  if (START_PATTERNS.some((re) => re.test(command))) return 'start';
+  if (/kill-ports/i.test(command)) return 'stop';
+  const targetPid = extractKillTargetPid(command);
+  if (targetPid != null && lockPid != null && targetPid === lockPid) return 'stop';
+  return null;
+}
+
+/**
+ * Pure comparison: true when `gitDir` and `gitCommonDir` differ, i.e. this
+ * checkout is a linked git worktree, not the main checkout.
+ */
+export function isWorktreePaths(gitDir, gitCommonDir) {
+  if (!gitDir || !gitCommonDir) return false; // can't determine → not isolated (stay gated)
+  return path.resolve(gitDir) !== path.resolve(gitCommonDir);
+}
+
+/** Shell out to git to answer "is this cwd a linked worktree (not the main checkout)?" */
+export function detectWorktreeIsolation(cwd = process.cwd()) {
+  try {
+    const dir = spawnSync('git', ['rev-parse', '--git-dir'], { cwd, encoding: 'utf8', timeout: 3000 });
+    const common = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 3000,
+    });
+    if (dir.status !== 0 || common.status !== 0 || !dir.stdout?.trim() || !common.stdout?.trim()) {
+      return false;
+    }
+    return isWorktreePaths(
+      path.resolve(cwd, dir.stdout.trim()),
+      path.resolve(cwd, common.stdout.trim()),
+    );
+  } catch {
+    return false; // undetectable → stay gated (fail toward protection, not bypass)
+  }
+}
+
+/** The claim-bound session worktree's owner marker, written by
+ *  dev-factory/lib/worktree-allocator.mjs. The name is mirrored rather than
+ *  imported so this module stays loadable in a checkout with no dev-factory. */
+export const WORKTREE_OWNER_FILE = '.hsewt-owner.json';
+
+/** The env var a SPAWNED worktree session carries (set by the spawner). */
+export const WORKTREE_ENV = 'HEYSPEX_WORKTREE';
+
+/** The one stderr line a bypassed Gate 1 emits, so a bypass is never silent. */
+export const WORKTREE_BYPASS_LOG =
+  'protected-actions gate: worktree-isolated session, dev-server gate bypassed';
+
+/**
+ * Is this checkout a claim-bound SESSION worktree?
+ * ([[HS-QDQA]], epic [[HS-03DO]] — the bypass [[protected-shared-actions-gate]]
+ * Gate 1 documents ("A worktree-isolated agent bypasses entirely — its own
+ * server, its own port") but only ever implemented via git's own linked-worktree
+ * probe, which misses a spawned session whose shell never resolved git, and
+ * which cannot be exercised without a real worktree on disk.)
+ *
+ * Two independent signals, either sufficient on its own:
+ *   - `<cwd>/.hsewt-owner.json` with `kind: "session"` — the allocator's record;
+ *   - `HEYSPEX_WORKTREE=1` — the spawner's env stamp.
+ *
+ * A `kind: "build"` marker (dev-factory's per-candidate gate worktree) is NOT a
+ * session and gets no bypass. Undetectable → false, i.e. STAY GATED: this
+ * function may only ever say "yes, isolated", never guess one.
+ *
+ * SCOPE: Gate 1 (dev-server start/stop) ONLY. Every destructive GIT verb keeps
+ * its own, separate gating in ./gates/git-stash-gate.mjs — a worktree still
+ * shares the object store, the reflog and the branch namespace with the primary
+ * checkout, so `git stash` / `reset --hard` / `push --force` are exactly as
+ * dangerous there as anywhere else. Nothing here is wired into that gate.
+ *
+ * @param {{ cwd?: string, env?: Record<string, string|undefined>, fs?: object }} [input]
+ * @returns {boolean}
+ */
+export function isWorktreeIsolated({ cwd = process.cwd(), env = process.env, fs: fsImpl = fs } = {}) {
+  try {
+    const raw = fsImpl.readFileSync(path.join(String(cwd), WORKTREE_OWNER_FILE), 'utf8');
+    const marker = JSON.parse(raw);
+    if (marker && typeof marker === 'object' && marker.kind === 'session') return true;
+  } catch {
+    // No marker / unreadable / not JSON — fall through to the env signal.
+  }
+  return String(env?.[WORKTREE_ENV] ?? '') === '1';
+}
+
+/**
+ * Read the live front (`assisted` | `autonomous`) off
+ * dev-factory/state/coo-dispatcher-state.json — re-read fresh every call so a
+ * mid-session front flip takes effect on the very next gated action.
+ */
+export function readFront(repoRootPath) {
+  try {
+    const p = path.join(repoRootPath, 'dev-factory', 'state', 'coo-dispatcher-state.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return raw?.front === 'autonomous' ? 'autonomous' : 'assisted';
+  } catch {
+    return 'assisted';
+  }
+}
+
+/** Deterministic per-checkout fleet-queue lane name. */
+export function devServerLane(repoRootPath) {
+  const key = path.basename(repoRootPath).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+  return `dev-server-${key || 'checkout'}`;
+}
+
+/** Path of the standing "who holds the dev server" marker for a checkout. */
+export function activeClaimPath(repoRootPath) {
+  return path.join(repoRootPath, '.heyspex', 'dev-server-active-claim.json');
+}
+
+/**
+ * THIN wrapper over dev-factory/lib/fleet-queue.mjs (enqueue/claim/complete/list
+ * — unmodified) implementing the one exclusive "who currently owns the shared
+ * dev server" resource per lane. All I/O is parameterized.
+ */
+export function attemptDevServerClaim({ lane, action, claimant, queuePath, activePath, now = Date.now() }) {
+  let active = null;
+  try {
+    active = JSON.parse(fs.readFileSync(activePath, 'utf8'));
+  } catch {
+    active = null;
+  }
+  if (active && active.lane === lane && active.claimant !== claimant) {
+    const heldItems = list(lane, 'claimed', { queuePath, now });
+    const stillHeld = heldItems.some((i) => i.id === active.id);
+    if (stillHeld) {
+      return {
+        ok: false,
+        reason:
+          `dev-server resource "${lane}" is already claimed by ${active.claimant} (since ${active.claimedAt}) — ` +
+          `back off and retry after release or TTL expiry.`,
+      };
+    }
+  }
+
+  const enq = enqueue({ lane, payload: { action }, requestedBy: claimant, queuePath, now });
+  const res = claim(enq.id, claimant, { queuePath, now });
+  if (!res.ok) {
+    return { ok: false, reason: `dev-server resource "${lane}" claim rejected: ${res.reason}` };
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(activePath), { recursive: true });
+    fs.writeFileSync(
+      activePath,
+      JSON.stringify({ lane, id: enq.id, claimant, action, claimedAt: new Date(now).toISOString() }),
+    );
+  } catch {
+    /* best-effort marker write — the queue-level claim already holds regardless */
+  }
+
+  if (action === 'stop') {
+    complete(enq.id, { action }, { queuePath, now });
+    try {
+      fs.rmSync(activePath, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  return { ok: true, id: enq.id };
+}
+
+/** Append one row to `.heyspex/dev-server-history.jsonl`. Never throws. */
+export function auditHistory(repoRootPath, record) {
+  try {
+    const dir = path.join(repoRootPath, '.heyspex');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'dev-server-history.jsonl'),
+      JSON.stringify({ timestamp: new Date().toISOString(), ...record }) + '\n',
+    );
+  } catch {
+    /* observability must never break the gate */
+  }
+}
+
+/** The exact ask text the Assisted front shows. Pure; asserted by the goldens. */
+export function askReason(action) {
+  return (
+    `Starting or stopping the shared spex-console dev server (${action}) is a PROTECTED action ` +
+    `(protected-shared-actions-gate) — it always requires explicit permission in Assisted front. ` +
+    `Approving this prompt IS the permission.`
+  );
+}
+
+export default {
+  TOGGLE_KEY,
+  activeClaimPath,
+  askReason,
+  attemptDevServerClaim,
+  auditHistory,
+  buildReminder,
+  classifyServerStartStop,
+  detectWorktreeIsolation,
+  devServerLane,
+  extractKillTargetPid,
+  getStatus,
+  isServerImpacting,
+  isWorktreeIsolated,
+  isWorktreePaths,
+  readFront,
+  readLockPid,
+  repoRoot,
+};