heyspex 0.1.0 → 0.2.1

package/spexharness/src/seat-context.mjs

@@ -0,0 +1,122 @@
+// spexharness/src/seat-context.mjs
+//
+// The harness's seat-context loader: a seat's procedures, skills and memories, for any
+// front (a chat window, an overnight seat run, the Claude Code plugin shell) — not just
+// the Claude Code "SessionStart injection" text dev-factory/lib/seat-context.mjs produces.
+//
+// Built ON dev-factory/lib/seat-context.mjs (its buildSeatContext + repoRoot are the single
+// source of truth for the "DEV-FACTORY SEAT: <title> — <mandate>" line and for reading
+// dev-factory/seats.json — see that file's header for why three consumers already depend
+// on it staying byte-identical), NOT reimplemented here. This module wraps that seat line
+// in a front-agnostic, structured shape and layers on the vault-sourced context — the
+// procedures (specs/protocols/*.md), skills (.claude/skills/*), and memories
+// (specs/memory/**/*.md) a seat has available — none of which dev-factory/lib/seat-context.mjs
+// carries, since its only job is the Claude-Code-shaped injection string.
+//
+// Every listing here is best-effort: a missing directory (e.g. a stripped-down worktree
+// with no specs/ junction, or a front with no .claude/skills) yields an empty array, never
+// a throw — the same fail-soft posture buildSeatContext itself uses for a missing/corrupt
+// seats.json.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { buildSeatContext, repoRoot } from '../../dev-factory/lib/seat-context.mjs';
+
+export { repoRoot };
+
+/** List `.md` basenames (no extension) directly under `dir`, sorted. [] if `dir` doesn't exist. */
+function listMarkdownSlugs(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => f.slice(0, -3))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** List every `.md` slug under `dir`, one level of subdirectories deep (specs/memory/{lessons,decisions,...}/*.md). [] if `dir` doesn't exist. */
+function listMarkdownSlugsRecursiveOneLevel(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const slugs = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      slugs.push(...listMarkdownSlugs(full).map((slug) => `${entry.name}/${slug}`));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      slugs.push(entry.name.slice(0, -3));
+    }
+  }
+  return slugs.sort();
+}
+
+/** List skill directory/file names under a skills root (each entry is a skill id). [] if the root doesn't exist. */
+function listSkillIds(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory() || e.name.endsWith('.md'))
+    .map((e) => (e.isDirectory() ? e.name : e.name.slice(0, -3)))
+    .sort();
+}
+
+/**
+ * Load one seat's full context: the seat line (built on dev-factory/lib/seat-context.mjs),
+ * plus the procedures, skills and memories available to it — front-agnostic, so a chat
+ * front, a headless seat, or a Claude Code hook can all consume the same shape and format
+ * it however that front needs (text injection, a system-prompt block, a tool result…).
+ *
+ * @param {{ root?: string, seatId?: string|null, vaultRoot?: string|null }} [opts]
+ *   `root` — repo root (defaults to repoRoot()): where dev-factory/seats.json and
+ *   .claude/skills live. `vaultRoot` — the SPEC vault root, where specs/protocols and
+ *   specs/memory live; defaults to `root`, but the platform checkout and its vault are
+ *   separate directories for the owner (HS_VAULT_ROOT names the vault — see hs-chat.ts's
+ *   own REPO_ROOT note), so a front that knows its vault passes it here or every
+ *   vault-sourced piece silently reads as empty. `seatId` — when supplied and
+ *   dev-factory/seats.json has a matching seat, that seat's own record is returned under
+ *   `seat`; omit to get the same information buildSeatContext already exposes (the combined
+ *   `seatLine` for every active seat) without a single-seat lookup.
+ * @returns {{
+ *   seatLine: string|null,
+ *   seat: object|null,
+ *   procedures: string[],
+ *   skills: string[],
+ *   memories: string[],
+ * }}
+ */
+export function loadSeatContext({ root = repoRoot(), seatId = null, vaultRoot = null } = {}) {
+  const seatLine = buildSeatContext(root);
+  const specsRoot = typeof vaultRoot === 'string' && vaultRoot.length > 0 ? vaultRoot : root;
+
+  let seat = null;
+  if (seatId) {
+    try {
+      // Reuse the exact seats.json dev-factory/lib/seat-context.mjs already reads — no
+      // second parse-and-guess of the registry shape here.
+      const seatsPath = path.join(root, 'dev-factory', 'seats.json');
+      const registry = JSON.parse(readFileSync(seatsPath, 'utf8'));
+      const seats = Array.isArray(registry?.seats) ? registry.seats : [];
+      seat = seats.find((s) => s && s.id === seatId) ?? null;
+    } catch {
+      seat = null;
+    }
+  }
+
+  return {
+    seatLine,
+    seat,
+    procedures: listMarkdownSlugs(path.join(specsRoot, 'specs', 'protocols')),
+    skills: listSkillIds(path.join(root, '.claude', 'skills')),
+    memories: listMarkdownSlugsRecursiveOneLevel(path.join(specsRoot, 'specs', 'memory')),
+  };
+}

package/spexharness/src/session-bootstrap.mjs

@@ -0,0 +1,512 @@
+// spexharness/src/session-bootstrap.mjs
+//
+// The harness's ONE session bootstrap: the single in-process path that loads everything a
+// seat needs to start — the seat context, the WIP block, the memories and the preflight
+// procedures — exactly once per session, and hands them back as one structured block.
+//
+// Why this module exists (epic HS-Y646, task HS-QEXH): today the seat block arrives three
+// ways (the Claude Code SessionStart hook, spexharness/src/callers/headless.mjs, and each
+// front's own ad-hoc read), so a DeepSeek seat and a local-model seat neither start the
+// same way nor start once. This module is the one path: a front — `hs chat`, an overnight
+// headless seat, a DeepSeek seat entry point, a 64k local-model seat entry point — calls
+// startSession()/bootstrapSession() and gets the same six pieces in the same shape. No
+// front loads a piece itself, and nothing here reloads a piece a second time.
+//
+// Loading is NOT reinvented here. The seat context comes from
+// spexharness/src/seat-context.mjs's loadSeatContext (itself built directly on
+// dev-factory/lib/seat-context.mjs's buildSeatContext/repoRoot — see that module's header
+// for why that stays the single source of truth), and the three vault-sourced pieces are
+// derived from THAT already-loaded context rather than re-walking specs/ per piece. That is
+// the whole point of the "exactly once" criterion: one seats.json parse, one specs/ walk.
+//
+// Every loader is injectable (`loaders`), which is how a front that has a live lane swaps
+// the fail-soft on-disk defaults for the real thing — most importantly the WIP block, whose
+// system of record is the Neon lane, not a file. The defaults keep an offline/stripped-down
+// worktree (no specs/ junction, no lane file) starting successfully with empty pieces rather
+// than throwing, the same fail-soft posture loadSeatContext and decide.mjs already take.
+//
+// I/O: only the default loaders touch disk (via loadSeatContext and best-effort reads).
+// Injecting all six loaders makes this module pure.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { loadSeatContext, repoRoot } from './seat-context.mjs';
+import { loadDoctrine, renderDoctrineBlock, DOCTRINE_MAX_TOKENS, defaultDoctrinePath } from './doctrine/inject.mjs';
+import { defaultProfilePath, defaultProfileStatePath, loadProfileState, renderProfileDigest, PROFILE_MAX_TOKENS } from './profile/learn.mjs';
+import { estimateTokens } from './token-inventory.mjs';
+
+export { repoRoot };
+
+/** The intent a seat preflights for when neither the caller nor the seat row names one. */
+export const DEFAULT_INTENT = 'execute_spec';
+
+/** The six pieces a session bootstrap loads, in load order. Used for the load-count ledger.
+ *  HS-X3S1 (DR3) added `doctrine`: the SpexCode Doctrine block (../doctrine/inject.mjs), so
+ *  every seat's bootstrap — not just the chat front's system message — carries it. HS-3H6E
+ *  (P4) added `profile`, LAST: the SpexCode Profile block (../profile/learn.mjs), layered
+ *  AFTER `doctrine` — enforced SpexDoctrine, then learned SpexCode Doctrine, then
+ *  per-developer SpexCode Profile, per the three-layers decision memory. */
+export const BOOTSTRAP_PIECES = Object.freeze(['seatContext', 'wip', 'memories', 'procedures', 'doctrine', 'profile']);
+
+/**
+ * Preflight intent → the protocol slugs that intent binds, mirroring the intents
+ * `heyspex_preflight` accepts. Only slugs that actually exist under specs/protocols for the
+ * given root are returned (a stripped-down worktree yields fewer, never a throw), and an
+ * unknown intent yields none rather than guessing.
+ * @type {Readonly<Record<string, ReadonlyArray<string>>>}
+ */
+export const DEFAULT_INTENT_PROCEDURES = Object.freeze({
+  execute_spec: Object.freeze(['pre-execution-alignment-gate', 'session-close-protocol']),
+  claim_spec: Object.freeze(['pre-execution-alignment-gate']),
+  file_milestone: Object.freeze(['plan-ingest-agent-workflow', 'roadmap-protocol', 'spec-summary-authoring']),
+  file_epic: Object.freeze(['plan-ingest-agent-workflow', 'roadmap-protocol', 'spec-summary-authoring']),
+  file_task: Object.freeze(['spec-summary-authoring', 'checks-manifest-authoring']),
+  memory_creation: Object.freeze(['memory-protocol']),
+  close_session: Object.freeze(['session-close-protocol']),
+  destructive_action: Object.freeze(['destructive-action-checklist']),
+  protocol_edit: Object.freeze(['rule-placement-protocol']),
+  server_impacting_action: Object.freeze(['dev-server-lifecycle-and-db-safety']),
+  restructure_content: Object.freeze(['internal-linking-protocol']),
+});
+
+/** Read a JSON file, or return null for missing/unreadable/corrupt — never throws. */
+function readJsonSoft(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull `tags:` out of a markdown file's YAML frontmatter — both the block form
+ * (`tags:\n  - ui\n  - console`) and the inline form (`tags: [ui, console]`).
+ * Best-effort and allocation-light: this runs once per memory file at session start, so it
+ * stays a frontmatter scan rather than a YAML parse. Unreadable file → [].
+ *
+ * @param {string} filePath
+ * @returns {string[]}
+ */
+function readFrontmatterTags(filePath) {
+  let text;
+  try {
+    text = readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+  if (!text.startsWith('---')) return [];
+  const end = text.indexOf('\n---', 3);
+  const frontmatter = end === -1 ? text : text.slice(0, end);
+  const lines = frontmatter.split('\n');
+  const tags = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = /^tags:\s*(.*)$/.exec(lines[i]);
+    if (!match) continue;
+    const inline = match[1].trim();
+    if (inline.startsWith('[')) {
+      for (const raw of inline.replace(/^\[|\]$/g, '').split(',')) {
+        const tag = raw.trim().replace(/^['"]|['"]$/g, '');
+        if (tag) tags.push(tag);
+      }
+    } else if (inline) {
+      tags.push(inline.replace(/^['"]|['"]$/g, ''));
+    }
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const item = /^\s*-\s*(.+?)\s*$/.exec(lines[j]);
+      if (!item) break;
+      tags.push(item[1].replace(/^['"]|['"]$/g, ''));
+    }
+    break;
+  }
+  return tags;
+}
+
+/**
+ * The tags a seat recalls memories by: the seat row's own `tags` when it has them, else the
+ * identity it does have (its id and group) — so a seat with no curated tag list still
+ * recalls something targeted instead of everything.
+ *
+ * @param {object|null} seat a dev-factory/seats.json seat record.
+ * @returns {string[]}
+ */
+export function seatMemoryTags(seat) {
+  if (Array.isArray(seat?.tags) && seat.tags.length > 0) {
+    return seat.tags.filter((t) => typeof t === 'string' && t.length > 0);
+  }
+  return [seat?.id, seat?.group].filter((t) => typeof t === 'string' && t.length > 0);
+}
+
+/** The intent a session preflights for: the caller's, else the seat row's, else the default. */
+function resolveIntent(explicitIntent, seat) {
+  return explicitIntent ?? seat?.defaultIntent ?? DEFAULT_INTENT;
+}
+
+/* ------------------------------------------------------------------ default loaders --- */
+
+/**
+ * Default seat-context loader: spexharness/src/seat-context.mjs's loadSeatContext, which is
+ * itself the shared dev-factory builder. Not reimplemented, and called exactly once.
+ */
+function defaultSeatContextLoader({ root, seatId, vaultRoot }) {
+  return loadSeatContext({ root, seatId, vaultRoot });
+}
+
+/**
+ * Default WIP-block loader. The system of record for a WIP block is the Neon lane, which a
+ * front with a live connection injects as `loaders.wip`; this default is the offline
+ * fallback — a best-effort read of a JSON lane file, keyed by seat when the file is a map of
+ * seats. Missing/corrupt/absent seat → null, never a throw, so a seat with no prior WIP
+ * starts clean instead of failing to start.
+ */
+function defaultWipLoader({ root, seatId, wipLanePath }) {
+  const lanePath = wipLanePath ?? path.join(root, '.heyspex', 'session-wip.json');
+  const lane = readJsonSoft(lanePath);
+  if (!lane || typeof lane !== 'object') return null;
+  if (seatId && Object.prototype.hasOwnProperty.call(lane, seatId)) return lane[seatId] ?? null;
+  if (Object.prototype.hasOwnProperty.call(lane, 'wip')) return lane.wip ?? null;
+  return lane;
+}
+
+/**
+ * Default memories loader — derived from the ALREADY-LOADED seat context, so this does not
+ * re-walk specs/memory. Returns `{ slug, tags }` for each memory whose frontmatter tags
+ * intersect the seat's tags; a seat that resolves no tags (no seat row at all) recalls the
+ * full list unfiltered, matching loadSeatContext's own untargeted view.
+ *
+ * A seat whose tags match NO memory at all (the common shape today: seats.json rows carry
+ * no `tags`, so the fallback identity tags — the seat id and group — match nothing in a
+ * vault whose memories are tagged by domain) also falls back to the full list rather than
+ * reporting an empty recall: the memories exist and are the seat's to read, the seat merely
+ * has no curated subset yet. `targeted: false` on each entry says which case produced it.
+ */
+function defaultMemoriesLoader({ root, vaultRoot, seatContext }) {
+  const slugs = Array.isArray(seatContext?.memories) ? seatContext.memories : [];
+  const wanted = seatMemoryTags(seatContext?.seat);
+  const specsRoot = typeof vaultRoot === 'string' && vaultRoot.length > 0 ? vaultRoot : root;
+  const memoryRoot = path.join(specsRoot, 'specs', 'memory');
+  const all = slugs.map((slug) => ({ slug, tags: readFrontmatterTags(path.join(memoryRoot, `${slug}.md`)) }));
+  if (wanted.length === 0) return all;
+  const wantedSet = new Set(wanted);
+  const targeted = all.filter((m) => m.tags.some((tag) => wantedSet.has(tag)));
+  if (targeted.length > 0) return targeted.map((m) => ({ ...m, targeted: true }));
+  return all.map((m) => ({ ...m, targeted: false }));
+}
+
+/**
+ * Default preflight-procedure loader — also derived from the already-loaded seat context.
+ * Returns the slugs {@link DEFAULT_INTENT_PROCEDURES} binds to the session's intent, kept
+ * only when specs/protocols actually carries them. Unknown intent → [].
+ */
+function defaultProceduresLoader({ intent, seatContext, intentProcedures }) {
+  const table = intentProcedures ?? DEFAULT_INTENT_PROCEDURES;
+  const wanted = table[intent] ?? [];
+  const available = new Set(Array.isArray(seatContext?.procedures) ? seatContext.procedures : []);
+  return wanted.filter((slug) => available.has(slug));
+}
+
+/**
+ * Default Doctrine loader (HS-X3S1, DR3): reads `<root>/spexharness/doctrine/
+ * SPEXCODE-DOCTRINE.json` (../doctrine/inject.mjs's `loadDoctrine`, cached, tolerant of
+ * absence) and renders it within its own documented budget (`renderDoctrineBlock`,
+ * DOCTRINE_MAX_TOKENS) — never the full unbounded document. A repo with no Doctrine yet
+ * still starts: the render degrades to the absence notice rather than throwing.
+ */
+function defaultDoctrineLoader({ root }) {
+  const doctrine = loadDoctrine({ path: defaultDoctrinePath(root) });
+  return renderDoctrineBlock(doctrine, { maxTokens: DOCTRINE_MAX_TOKENS });
+}
+
+/**
+ * The profile is "ready" to condition a turn only once BOTH are true: the rendered file
+ * exists on disk, AND P2's incremental-state mark (`.heyspex/profile-state.json`'s
+ * `lastLearnedAt`, ../profile/learn.mjs's `loadProfileState`) says a learning pass actually
+ * completed. `buildProfile` (learn.mjs) and `accept` (proposals.mjs, P6) both write the
+ * profile file BEFORE saving state, so checking only file-existence would read a mid-write
+ * (or stale, pre-first-run) file as done; requiring the state mark too closes that race.
+ *
+ * Exported (P8, HS-NRCK — plugin parity): the Claude Code plugin's own injection hook
+ * (scripts/claude-hooks/inject-vault-context.mjs, via its gate
+ * spexharness/src/gates/inject-vault-context.mjs) is a thin shell over THIS function and
+ * {@link defaultProfileLoader} below — it never re-implements the readiness check or the
+ * rendering, so a plugin session and a SpexCode seat's own bootstrap see byte-identical
+ * profile content.
+ *
+ * @param {{ root: string }} args
+ * @returns {boolean}
+ */
+export function isProfileReady({ root }) {
+  if (!existsSync(defaultProfilePath(root))) return false;
+  const state = loadProfileState(defaultProfileStatePath(root));
+  return typeof state.lastLearnedAt === 'string' && state.lastLearnedAt.length > 0;
+}
+
+/**
+ * Render the profile file's markdown into the same shape {@link defaultDoctrineLoader}
+ * renders Doctrine into — `{ text, tokens, chars, learnedAt }` — measured through
+ * ../token-inventory.mjs's `estimateTokens` (the same chars/4 estimate every other piece's
+ * size comes from), so a caller that records this block through
+ * ../context-budget.mjs's `recordContextInjection` (P2's `registerProfileContextUsage`
+ * call shape) gets a real token count, not a guess.
+ *
+ * @param {string} markdown
+ * @param {{ learnedAt?: string|null, maxTokens?: number }} [opts] - `maxTokens` defaults to
+ *   ../profile/learn.mjs's {@link PROFILE_MAX_TOKENS}, mirroring how the doctrine loader
+ *   above passes DOCTRINE_MAX_TOKENS to `renderDoctrineBlock`.
+ * @returns {{ text: string, tokens: number, chars: number, learnedAt: string|null, truncated: boolean }}
+ */
+export function renderProfileBlock(markdown, { learnedAt = null, maxTokens = PROFILE_MAX_TOKENS } = {}) {
+  const full = String(markdown ?? '').replace(/\n+$/, '');
+  const budget = Number.isFinite(maxTokens) && maxTokens > 0 ? maxTokens : Infinity;
+
+  // Tail cut on WHOLE lines, the same convention renderDoctrineBlock uses: the first line
+  // that would overflow, and every line after it, are dropped together, so the block never
+  // ends mid-citation and a cheap later line never jumps the queue past a dropped one.
+  //
+  // This is the load-bearing containment: it bounds what reaches a seat's context REGARDLESS
+  // of what is on disk. The profile file on this machine had grown to 4.2MB (~1.06M tokens)
+  // and was injected whole, on EVERY user prompt, which is what pushed a 1M-window model
+  // past its limit before the developer's own message was even appended.
+  const lines = full.split('\n');
+  const kept = [];
+  let usedTokens = 0;
+  let truncated = false;
+  for (const line of lines) {
+    const lineTokens = estimateTokens(`${line}\n`);
+    if (usedTokens + lineTokens > budget) {
+      truncated = true;
+      break;
+    }
+    usedTokens += lineTokens;
+    kept.push(line);
+  }
+  if (truncated) kept.push('', `_(profile truncated to its ${budget}-token injection budget)_`);
+
+  const text = kept.join('\n').replace(/\n+$/, '');
+  return { text, tokens: estimateTokens(text), chars: text.length, learnedAt, truncated };
+}
+
+/**
+ * Default Profile loader (HS-3H6E, P4 — Conditioning, epic HS-HEBV scope item 4): once
+ * {@link isProfileReady} is true, reads `.heyspex/spexcode-profile.md`
+ * (../profile/learn.mjs's `defaultProfilePath`) — written only by `buildProfile`
+ * (learn.mjs, direct fold) or `accept` (proposals.mjs, P6's curated accept/decline gate),
+ * so every line already on disk is an accepted, non-pending entry — and renders it.
+ *
+ * Returns `null`, never a placeholder block, until the learner has completed for this
+ * machine: a turn whose bootstrap resolves before then must carry NO profile section at
+ * all (absent, not an empty one) — unlike {@link defaultDoctrineLoader}, which always
+ * renders something (an absence notice) because Doctrine is expected to exist from the
+ * start of a vault's life, while a fresh machine's Profile legitimately has not learned
+ * anything yet.
+ */
+export function defaultProfileLoader({ root }) {
+  if (!isProfileReady({ root })) return null;
+  let markdown;
+  try {
+    markdown = readFileSync(defaultProfilePath(root), 'utf8');
+  } catch {
+    return null;
+  }
+  if (!markdown || !markdown.trim()) return null;
+  const state = loadProfileState(defaultProfileStatePath(root));
+
+  // Prefer the structured digest (../profile/learn.mjs's `renderProfileDigest`): it budgets
+  // FAIRLY across sections, so "Recurring corrections" and "Tools approved or refused" still
+  // reach the seat instead of being starved by a long first section. The markdown file itself
+  // stays the complete browsable record and is deliberately NOT what gets injected.
+  //
+  // The markdown path below remains as the fallback for a state file that is missing or
+  // carries no sections (an older build, a hand-written profile) — and `renderProfileBlock`
+  // clamps that path too, so neither route can put an unbounded file into a context window.
+  const hasSections = Object.values(state?.sections ?? {}).some((s) => Array.isArray(s) && s.length > 0);
+  if (hasSections) {
+    const digest = renderProfileDigest(state.sections, { maxTokens: PROFILE_MAX_TOKENS, estimate: estimateTokens });
+    // On this path the digest is the authority on the budget — it already selected entries to
+    // fit. The outer clamp stays on as a BACKSTOP (a bug in the digest still cannot put an
+    // unbounded block into context) but is given headroom so it does not fight the digest's
+    // own accounting: the two round differently (the clamp sums a ceil per line, the digest
+    // sums a ceil per entry), and a clamp set to the same number trims the digest's closing
+    // footer every time purely on rounding drift.
+    return renderProfileBlock(digest.text, { learnedAt: state.lastLearnedAt, maxTokens: PROFILE_MAX_TOKENS * 2 });
+  }
+  return renderProfileBlock(markdown, { learnedAt: state.lastLearnedAt });
+}
+
+const DEFAULT_LOADERS = Object.freeze({
+  seatContext: defaultSeatContextLoader,
+  wip: defaultWipLoader,
+  memories: defaultMemoriesLoader,
+  procedures: defaultProceduresLoader,
+  doctrine: defaultDoctrineLoader,
+  profile: defaultProfileLoader,
+});
+
+/* ---------------------------------------------------------------------- the bootstrap --- */
+
+/**
+ * @typedef {object} SessionBootstrapBlock
+ * @property {string} sessionId          this session's id (generated when the caller has none).
+ * @property {string|null} seatId        the seat this session runs as.
+ * @property {string|null} front         the entry point that started it ('deepseek', 'local-model', 'chat', …) — recorded, never branched on.
+ * @property {string} intent             the preflight intent the procedures were loaded for.
+ * @property {string} startedAt          ISO timestamp of the bootstrap.
+ * @property {object} seatContext        loadSeatContext()'s result: seatLine, seat, procedures, skills, memories.
+ * @property {unknown} wip               the WIP block for this seat (null when there is none).
+ * @property {Array<{slug: string, tags: string[]}>} memories  memories recalled by seat tag.
+ * @property {string[]} procedures       preflight procedure slugs bound to `intent`.
+ * @property {{ text: string, tokens: number, chars: number, principleCount: number,
+ *   includedCount: number, learnedAt: string|null, truncated: boolean }} doctrine
+ *   the rendered SpexCode Doctrine block (HS-X3S1/DR3, ../doctrine/inject.mjs's
+ *   `renderDoctrineBlock`); absence renders as a notice, never a throw.
+ * @property {{ text: string, tokens: number, chars: number, learnedAt: string|null }|null} profile
+ *   the rendered SpexCode Profile block (HS-3H6E/P4, ../profile/learn.mjs), injected AFTER
+ *   `doctrine` — enforced SpexDoctrine, then learned SpexCode Doctrine, then per-developer
+ *   SpexCode Profile. `null` — ABSENT, not an empty placeholder — until the learner has
+ *   completed for this machine; a turn whose bootstrap resolves before then never carries a
+ *   profile section at all.
+ * @property {Readonly<Record<string, number>>} loadCounts  how many times each piece was loaded — 1 each, per HS-QEXH AC1.
+ * @property {Array<{piece: string, error: string}>} errors  loaders that failed (the piece degrades to empty; a session still starts).
+ */
+
+/**
+ * Create a session bootstrap handle. The handle memoizes: `load()` runs the six loaders on
+ * the first call and returns the SAME block (and the same load counts) on every later call,
+ * which is what makes "exactly once per session" true even when several parts of a front ask
+ * for the session block independently.
+ *
+ * @param {{
+ *   root?: string,
+ *   vaultRoot?: string|null,
+ *   seatId?: string|null,
+ *   sessionId?: string|null,
+ *   front?: string|null,
+ *   intent?: string|null,
+ *   wipLanePath?: string|null,
+ *   intentProcedures?: Record<string, ReadonlyArray<string>>|null,
+ *   loaders?: Partial<{ seatContext: Function, wip: Function, memories: Function, procedures: Function, doctrine: Function, profile: Function }>,
+ * }} [options]
+ *   `vaultRoot` — the SPEC vault root (specs/protocols, specs/memory) when it is not the
+ *   repo root; forwarded to every loader and to loadSeatContext. Omitted → `root`.
+ * @returns {{
+ *   sessionId: string,
+ *   seatId: string|null,
+ *   front: string|null,
+ *   load: () => Promise<SessionBootstrapBlock>,
+ *   loaded: () => SessionBootstrapBlock|null,
+ *   loadCounts: () => Readonly<Record<string, number>>,
+ * }}
+ */
+export function createSessionBootstrap(options = {}) {
+  const {
+    root = repoRoot(),
+    vaultRoot = null,
+    seatId = null,
+    sessionId = null,
+    front = null,
+    intent = null,
+    wipLanePath = null,
+    intentProcedures = null,
+    loaders = {},
+  } = options;
+
+  const resolvedSessionId = sessionId ?? randomUUID();
+  const loaderSet = { ...DEFAULT_LOADERS, ...loaders };
+  const counts = Object.fromEntries(BOOTSTRAP_PIECES.map((piece) => [piece, 0]));
+  const errors = [];
+
+  /** @type {SessionBootstrapBlock|null} */
+  let block = null;
+  /** @type {Promise<SessionBootstrapBlock>|null} */
+  let inFlight = null;
+
+  /** Run one loader, counting the call and folding a throw into a recorded error + fallback. */
+  async function runLoader(piece, args, fallback) {
+    counts[piece] += 1;
+    try {
+      return await loaderSet[piece](args);
+    } catch (err) {
+      errors.push({ piece, error: err instanceof Error ? err.message : String(err) });
+      return fallback;
+    }
+  }
+
+  async function loadOnce() {
+    const base = { root, vaultRoot, seatId, sessionId: resolvedSessionId, front, wipLanePath, intentProcedures };
+
+    // Seat context first and once — the other three are derived from it rather than
+    // re-reading seats.json / specs/ per piece. This is the "arrives three ways" fix.
+    const seatContext = (await runLoader('seatContext', base, null)) ?? {
+      seatLine: null,
+      seat: null,
+      procedures: [],
+      skills: [],
+      memories: [],
+    };
+    const resolvedIntent = resolveIntent(intent, seatContext.seat);
+    const withContext = { ...base, seatContext, intent: resolvedIntent };
+
+    const [wip, memories, procedures, doctrine, profile] = await Promise.all([
+      runLoader('wip', withContext, null),
+      runLoader('memories', withContext, []),
+      runLoader('procedures', withContext, []),
+      // A failed doctrine loader degrades to the SAME absence-notice shape a missing file
+      // renders to (renderDoctrineBlock(null)) — never `null` itself, so every consumer can
+      // read `block.doctrine.text` unconditionally, exactly like the other three pieces.
+      runLoader('doctrine', withContext, renderDoctrineBlock(null)),
+      // A failed (or not-yet-ready) profile loader degrades to `null` — ABSENCE, not a
+      // placeholder block, matching {@link defaultProfileLoader}'s own not-ready return.
+      runLoader('profile', withContext, null),
+    ]);
+
+    block = Object.freeze({
+      sessionId: resolvedSessionId,
+      seatId,
+      front,
+      intent: resolvedIntent,
+      startedAt: new Date().toISOString(),
+      seatContext,
+      wip: wip ?? null,
+      memories: memories ?? [],
+      procedures: procedures ?? [],
+      doctrine: doctrine ?? renderDoctrineBlock(null),
+      profile: profile ?? null,
+      loadCounts: Object.freeze({ ...counts }),
+      errors: Object.freeze(errors.slice()),
+    });
+    return block;
+  }
+
+  return {
+    sessionId: resolvedSessionId,
+    seatId,
+    front,
+    /** Load (or return the already-loaded) session block. Concurrent callers share one load. */
+    load() {
+      if (!inFlight) inFlight = loadOnce();
+      return inFlight;
+    },
+    /** The block if it has already loaded, else null — for a front that must not trigger a load. */
+    loaded() {
+      return block;
+    },
+    /** Live per-piece load-count ledger — every entry is 1 once a session has started. */
+    loadCounts() {
+      return Object.freeze({ ...counts });
+    },
+  };
+}
+
+/**
+ * One-shot form: bootstrap a session and return its block. This is what a seat entry point
+ * calls — a DeepSeek seat, a 64k local-model seat, `hs chat`, or a headless overnight run all
+ * call this same function with a different `front`/`seatId` and nothing else different.
+ *
+ * @param {Parameters<typeof createSessionBootstrap>[0]} [options]
+ * @returns {Promise<SessionBootstrapBlock>}
+ */
+export function bootstrapSession(options = {}) {
+  return createSessionBootstrap(options).load();
+}
+
+export default { createSessionBootstrap, bootstrapSession };