heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/search-specs.mjs

@@ -0,0 +1,280 @@
+/**
+ * search-specs.mjs — `heyspex_search_specs`, the vault's text search for agents
+ * ([[HS-YFLS]] fix 2).
+ *
+ * THE DEFECT THIS CLOSES
+ * ----------------------
+ * The bug-filing protocol tells an agent to "search specs/diagnoses/ before
+ * filing" — and no MCP tool searched specs by text. In PROD mode the vault is
+ * CLOUD-primary and the local mirror is incomplete (537 files on disk against
+ * 559 in the system of record), so a `grep` over the checkout is not a search
+ * of the vault: it answers "not on this disk", which is not the same claim.
+ * `heyspex_resolve_focus_intent` is the nearest thing and it is built for a
+ * different job — given the AC2 symptom sentence it returns 20 specs matched on
+ * a broad `security` tag and neither of the two that actually describe it.
+ *
+ * WHAT THIS IS
+ * ------------
+ * A duplicate check. It reads the CLOUD vault through `GET /api/search` — the
+ * system of record, never local disk — asks a handful of bounded angles
+ * ({@link ./symptom-query.mjs}, see that module for why one query cannot work),
+ * merges the windows, and returns enough per row to JUDGE a duplicate without a
+ * second call: id, name, type, status, a marked-up snippet, and which angles
+ * matched.
+ *
+ * A NEGATIVE MUST MEAN "NOT THERE", NEVER "COULD NOT LOOK" ([[HS-YFLS]] AC3)
+ * -------------------------------------------------------------------------
+ * Every way of not finding something is reported as a DIFFERENT thing:
+ *
+ *   result: "no_match"  — the corpus WAS searched and holds nothing. `searched`
+ *                         is true and `queries_tried` lists exactly what was
+ *                         asked. This is the only shape an agent may act on by
+ *                         filing a new spec.
+ *   result: "no_query"  — nothing searchable was extracted from the input.
+ *   isError envelopes   — CONSOLE_UNREACHABLE / CONSOLE_NOT_SIGNED_IN /
+ *                         VAULT_SCOPE_UNRESOLVED (a transient 503, retry) /
+ *                         VAULT_SCOPE_UNAUTHORIZED (the caller's vault could
+ *                         not be resolved, so the endpoint returned an empty
+ *                         page that means nothing about the corpus) /
+ *                         SEARCH_FAILED / SEARCH_RESPONSE_UNRECOGNIZED.
+ *
+ * An angle that fails fails the WHOLE call. A partial answer is indistinguishable
+ * from a complete one at the call site, and a silently partial duplicate check is
+ * exactly how the duplicate gets filed.
+ */
+
+import { consoleFetch as defaultConsoleFetch, controlOk } from './console-transport.mjs';
+import { buildSymptomQueries } from './symptom-query.mjs';
+
+/** Rows requested per angle. Bounded: this tool never walks the vault. */
+const ANGLE_LIMIT = 20;
+
+/** Default / maximum rows returned to the agent. */
+const DEFAULT_TOP_K = 10;
+const MAX_TOP_K = 30;
+
+/** Snippets are for judging a duplicate, not for reading the spec. */
+const MAX_SNIPPET_CHARS = 320;
+
+function errorResult(payload) {
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+
+/**
+ * Classify a non-OK `/api/search` response. Each code sends the agent somewhere
+ * different, which is the entire point of not collapsing them into "no results".
+ */
+function searchFailure(res, query) {
+  const status = res?.status ?? 0;
+  const code =
+    status === 0
+      ? 'CONSOLE_UNREACHABLE'
+      : status === 401
+        ? 'CONSOLE_NOT_SIGNED_IN'
+        : status === 503
+          ? 'VAULT_SCOPE_UNRESOLVED'
+          : 'SEARCH_FAILED';
+  const message =
+    code === 'CONSOLE_UNREACHABLE'
+      ? 'The console did not answer, so the vault was NOT searched. Check heyspex_dev_server_status (or console reachability in cloud mode) — do NOT read this as "no matching spec".'
+      : code === 'CONSOLE_NOT_SIGNED_IN'
+        ? 'The console refused this caller (401), so the vault was NOT searched. Re-pair the MCP bearer — do NOT read this as "no matching spec".'
+        : code === 'VAULT_SCOPE_UNRESOLVED'
+          ? 'This console instance has not resolved its active vault yet (transient). Retry shortly — the vault was NOT searched.'
+          : `GET /api/search returned ${status}, so the vault was NOT searched.`;
+  return errorResult({
+    error: code,
+    message,
+    searched: false,
+    status,
+    url: res?.url ?? null,
+    attempted_query: query ?? null,
+    console_response: res?.body ?? null,
+  });
+}
+
+/** `<mark>`s are kept — they show WHERE the match landed — but the row is capped. */
+function normalizeSnippet(value) {
+  if (typeof value !== 'string') return '';
+  const flat = value.replace(/\s+/g, ' ').trim();
+  return flat.length > MAX_SNIPPET_CHARS ? `${flat.slice(0, MAX_SNIPPET_CHARS)}…` : flat;
+}
+
+function normalizeRow(row) {
+  const id = typeof row?.id === 'string' ? row.id : null;
+  if (!id) return null;
+  const rank = Number(row?.rank);
+  return {
+    id,
+    name: String(row?.name ?? id),
+    type: String(row?.type ?? 'unknown'),
+    status: String(row?.status ?? 'unknown').toLowerCase(),
+    rank: Number.isFinite(rank) && rank > 0 ? rank : 0,
+    snippet: normalizeSnippet(row?.snippet),
+  };
+}
+
+/**
+ * One bounded page for one angle. Returns `{ rows, mode }` on success, or a
+ * ready-to-return error envelope under `{ failure }` — never an empty page
+ * standing in for a failure.
+ */
+async function fetchAngle(fetchImpl, { q, limit, type, status }) {
+  const params = new URLSearchParams();
+  params.set('q', q);
+  params.set('limit', String(limit));
+  params.set('scope', 'body');
+  if (type) params.set('type', type);
+  if (status) params.set('status', status);
+
+  let res;
+  try {
+    res = await fetchImpl(`/api/search?${params.toString()}`);
+  } catch (err) {
+    return {
+      failure: errorResult({
+        error: 'CONSOLE_UNREACHABLE',
+        message: `The console search endpoint threw (${err?.message ?? err}), so the vault was NOT searched. Do NOT read this as "no matching spec".`,
+        searched: false,
+        attempted_query: q,
+      }),
+    };
+  }
+  if (!res || !res.ok) return { failure: searchFailure(res, q) };
+
+  const body = res.body && typeof res.body === 'object' ? res.body : {};
+  // The route answers a caller whose vault scope it could not authorize with a
+  // 200 and an EMPTY page carrying `vaultScope.authorized: false`. That page is
+  // a permission verdict, not a statement about the corpus — the one shape that
+  // would otherwise read as a clean "no duplicate exists".
+  if (body.vaultScope && body.vaultScope.authorized === false) {
+    return {
+      failure: errorResult({
+        error: 'VAULT_SCOPE_UNAUTHORIZED',
+        message: `The console could not resolve a vault for this caller (${body.vaultScope.reason ?? 'unknown'}), so the empty page it returned says nothing about the vault. Do NOT read this as "no matching spec".`,
+        searched: false,
+        reason: body.vaultScope.reason ?? null,
+        attempted_query: q,
+      }),
+    };
+  }
+  const rows = Array.isArray(body.rows) ? body.rows : Array.isArray(body.results) ? body.results : null;
+  // `mode` ("fts" | "bm25" | "trgm" | "memory") is the endpoint's proof that it
+  // actually ran a query. Its absence alongside no rows is an unrecognized
+  // shape, and an unrecognized shape is never a negative result.
+  if (rows === null || typeof body.mode !== 'string') {
+    return {
+      failure: errorResult({
+        error: 'SEARCH_RESPONSE_UNRECOGNIZED',
+        message: 'GET /api/search answered 200 with a body this tool cannot read as a search result (no `rows`/`mode`), so the vault was NOT searched.',
+        searched: false,
+        attempted_query: q,
+        console_response: body,
+      }),
+    };
+  }
+  return { rows: rows.map(normalizeRow).filter(Boolean), mode: body.mode };
+}
+
+/**
+ * `heyspex_search_specs` — find specs in the CLOUD vault by symptom text.
+ *
+ * args: { query, top_k?, type?, status? }
+ * deps: { fetchImpl } (tests inject; production uses the shared consoleFetch)
+ */
+export async function handleSearchSpecs(args = {}, { fetchImpl = defaultConsoleFetch } = {}) {
+  const query = typeof args.query === 'string' ? args.query.trim() : '';
+  if (!query) {
+    return errorResult({
+      error: 'SEARCH_QUERY_REQUIRED',
+      message: '`query` is required — pass the symptom sentence (or the concept) you would otherwise grep for.',
+      searched: false,
+    });
+  }
+  const topKRaw = Number(args.top_k);
+  const topK = Number.isFinite(topKRaw) && topKRaw > 0 ? Math.min(MAX_TOP_K, Math.trunc(topKRaw)) : DEFAULT_TOP_K;
+  const type = typeof args.type === 'string' && args.type.trim() ? args.type.trim() : undefined;
+  const status = typeof args.status === 'string' && args.status.trim() ? args.status.trim() : undefined;
+
+  const { terms, queries } = buildSymptomQueries(query);
+  if (queries.length === 0) {
+    return controlOk({
+      query,
+      terms,
+      queries_tried: [],
+      searched: false,
+      result: 'no_query',
+      match_count: 0,
+      matches: [],
+      message: 'No searchable term survived normalization (the input was punctuation or stopwords only) — the vault was NOT searched. Rephrase with the concrete nouns from the symptom.',
+    });
+  }
+
+  /** id → merged candidate. */
+  const byId = new Map();
+  const queriesTried = [];
+  let mode = null;
+
+  for (const angle of queries) {
+    // eslint-disable-next-line no-await-in-loop -- a handful of bounded angles, deliberately sequential so a failure stops the walk.
+    const page = await fetchAngle(fetchImpl, { q: angle.q, limit: ANGLE_LIMIT, type, status });
+    if (page.failure) return page.failure;
+    mode = mode ?? page.mode;
+    queriesTried.push({ label: angle.label, q: angle.q, hits: page.rows.length, mode: page.mode });
+    page.rows.forEach((row, position) => {
+      const existing = byId.get(row.id);
+      if (!existing) {
+        byId.set(row.id, { ...row, matched_by: [angle.label], best_position: position });
+        return;
+      }
+      // Keep the strongest evidence each angle produced for this spec.
+      existing.rank = Math.max(existing.rank, row.rank);
+      existing.best_position = Math.min(existing.best_position, position);
+      if (!existing.snippet && row.snippet) existing.snippet = row.snippet;
+      if (!existing.matched_by.includes(angle.label)) existing.matched_by.push(angle.label);
+    });
+  }
+
+  // Agreement across angles first (a spec the quoted concept AND the loose term
+  // window both surfaced is the likeliest duplicate), then the endpoint's own
+  // `ts_rank_cd`, then the order it handed rows back — which is the only signal
+  // left on the disk read tier, where every rank is 0.
+  const matches = [...byId.values()]
+    .sort(
+      (a, b) =>
+        b.matched_by.length - a.matched_by.length ||
+        b.rank - a.rank ||
+        a.best_position - b.best_position ||
+        a.id.localeCompare(b.id),
+    )
+    .slice(0, topK)
+    .map(({ best_position: _position, ...row }) => row);
+
+  if (matches.length === 0) {
+    return controlOk({
+      query,
+      terms,
+      queries_tried: queriesTried,
+      searched: true,
+      corpus: 'cloud-vault (GET /api/search — the system of record, not local disk)',
+      result: 'no_match',
+      match_count: 0,
+      matches: [],
+      mode,
+      message: `Searched the vault on ${queriesTried.length} angle(s) and found NOTHING. This is an explicit negative: the corpus was read and holds no spec matching these terms — it is safe to file.`,
+    });
+  }
+
+  return controlOk({
+    query,
+    terms,
+    queries_tried: queriesTried,
+    searched: true,
+    corpus: 'cloud-vault (GET /api/search — the system of record, not local disk)',
+    result: 'match',
+    match_count: matches.length,
+    mode,
+    matches,
+    message: 'Read each match before filing: a spec that already describes this symptom must be commented on or reopened, not duplicated.',
+  });
+}

package/vendor/heyspex-mcp/seat-block-ledger.mjs

@@ -0,0 +1,113 @@
+// vendor/heyspex-mcp/seat-block-ledger.mjs
+//
+// Per-session "has the DEV-FACTORY SEAT banner already gone out this session"
+// decision for the two vendor surfaces that used to each keep their OWN flag:
+//   - tool-dispatch.mjs handleInitialize()      → surface 'mcp_instructions'
+//   - cli.mjs maybePrependSeatBanner()          → surface 'preflight' (when the
+//     first tool called is heyspex_preflight) or 'tool_result' otherwise
+//
+// Before this module, `initialize` always appended the banner to `instructions`
+// AND, independently, the first tools/call response ALSO got the banner
+// prepended (a separate `seatBannerSeenSessions` Set tracked only THAT surface) —
+// so a caller could see "DEV-FACTORY SEAT: ..." twice in one session. That is
+// exactly the bug spexharness/src/bootstrap-injection.mjs's engine contract
+// exists to close for every surface (its own header calls out wiring
+// vendor/heyspex-mcp as the deferred follow-up — HS-8U8X).
+//
+// spexharness/ is dev-only tooling: it is deliberately NOT part of the published
+// `heyspex` npm package (see dev-factory-bridge.mjs for the identical open-core
+// concern with dev-factory/spexcrawl/). scripts/verify-mcp-package.mjs's
+// `closure` check fails the build if the server's STATIC import graph reaches a
+// file the package doesn't ship, so the engine contract is reached the same way
+// spexcrawl is: a memoized `await import()`, never a static import. A
+// published install (no spexharness/ tree on disk) gets the fallback ledger
+// below instead — same "at most one surface, across the whole session" contract,
+// just without a shared spexharness bootstrap ledger to defer to.
+
+/** @type {Promise<typeof import('../../spexharness/src/bootstrap-injection.mjs')>|undefined} */
+let enginePromise;
+
+function loadEngine() {
+  if (!enginePromise) {
+    enginePromise = import('../../spexharness/src/bootstrap-injection.mjs').catch(() => null);
+  }
+  return enginePromise;
+}
+
+/**
+ * Local, dependency-free ledger with the exact `shouldIncludeSeatBlock` /
+ * `markSeatBlockSent` shape bootstrap-injection.mjs's `withSeatBlockLedger`
+ * exposes — used when the engine module is not reachable (a published install,
+ * or any import failure). "No bootstrap yet" degrades to "emit once, guarded",
+ * never to "emit unguarded".
+ */
+function createFallbackLedger() {
+  const sent = new Set();
+  return {
+    shouldIncludeSeatBlock(surface) {
+      if (sent.has(surface)) return false;
+      return sent.size === 0;
+    },
+    markSeatBlockSent(surface) {
+      sent.add(surface);
+    },
+  };
+}
+
+function fallbackSeatBlockForSurface(ledger, surface, seatLine) {
+  if (!ledger.shouldIncludeSeatBlock(surface)) return null;
+  ledger.markSeatBlockSent(surface);
+  return seatLine ?? null;
+}
+
+/** One ledger controller per session id — two sessions sharing this process (e.g. two
+ *  fleet workers spawned back-to-back) never see each other's sends. */
+const controllersBySession = new Map();
+
+async function getSeatBlockController(sessionId) {
+  const key = sessionId || 'local';
+  const existing = controllersBySession.get(key);
+  if (existing) return existing;
+
+  const engine = await loadEngine();
+  const ledger = engine?.withSeatBlockLedger ? engine.withSeatBlockLedger({}) : createFallbackLedger();
+  const forSurface = engine?.seatBlockForSurface
+    ? (surface, seatLine) => engine.seatBlockForSurface(ledger, surface, seatLine)
+    : (surface, seatLine) => fallbackSeatBlockForSurface(ledger, surface, seatLine);
+
+  const controller = { forSurface };
+  controllersBySession.set(key, controller);
+  return controller;
+}
+
+/**
+ * Decide whether `surface` should emit the seat banner for `sessionId` this
+ * session — sourced from the engine contract's per-session ledger when
+ * spexharness/ is reachable (memoized per session id), else a local fallback
+ * with identical "exactly once, across every surface" semantics. Returns the
+ * banner text when `surface` is cleared to send it, else `null`. Never throws;
+ * a falsy `seatLine` (not enabled / unknown caller) short-circuits to `null`
+ * WITHOUT touching the ledger, so an ineligible caller never "uses up" the
+ * session's one send.
+ *
+ * @param {string|null|undefined} sessionId
+ * @param {string} surface one of bootstrap-injection.mjs's SEAT_BLOCK_SURFACES
+ *   ('mcp_instructions', 'preflight', 'tool_result', 'bootstrap').
+ * @param {string|null|undefined} seatLine
+ * @returns {Promise<string|null>}
+ */
+export async function seatBlockForSessionSurface(sessionId, surface, seatLine) {
+  if (!seatLine) return null;
+  try {
+    const controller = await getSeatBlockController(sessionId);
+    return controller.forSurface(surface, seatLine);
+  } catch {
+    return null;
+  }
+}
+
+/** Test-only: forget every per-session ledger and the memoized engine probe. */
+export function resetSeatBlockLedgerForTests() {
+  controllersBySession.clear();
+  enginePromise = undefined;
+}

package/vendor/heyspex-mcp/seat-identity.mjs

@@ -19,7 +19,7 @@
 
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { PACKAGE_ROOT } from "./package-root.mjs";
 
 /**
  * Read and parse <vaultRoot>/dev-factory/seats.json.
@@ -169,11 +169,7 @@ function selfTest() {
   };
 
   // Repo root is two dirs up from this file (vendor/heyspex-mcp/ → repo root).
-  const repoRoot = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    "..",
-    "..",
-  );
+  const repoRoot = PACKAGE_ROOT;
 
   // 1. Real registry smoke-read.
   const real = readSeatsRegistry(repoRoot);

package/vendor/heyspex-mcp/session-owner.mjs

@@ -0,0 +1,109 @@
+// session-owner.mjs — the ONE place the MCP server learns which account owns
+// the documents it files ([[HS-WE87-WW9R-TASK-thread-the-gated-caller-through-every]],
+// epic [[HS-P1AW-WW9R-EPIC-identity-threading-and-the-end-of-the]] — invariant 1).
+//
+// Until this module the three frontmatter writers (`capture-focus.mjs`,
+// `research-focus.mjs`, `defer-spec.mjs`) each stamped the HeySpex owner's
+// handle as a literal — on a customer machine that put the platform owner's
+// name on the customer's own documents. They now ask here, and when nothing
+// resolves the `owner:` key is OMITTED rather than guessed.
+//
+// Resolution order (no network — this runs inside synchronous writers and
+// under `node --test`):
+//   1. `HS_ACCOUNT_ID` env — the same override the CLI's account reader honours.
+//   2. the credentials store's current account (`credentials.mjs`
+//      `readCurrentAccountId`, [[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]]):
+//      `current_account_id` of `~/.heyspex/credentials.yaml`, set by `hs login` /
+//      `hs mcp pair` from the account GET /api/mcp/session confirmed for the
+//      stored bearer and moved by `hs login --switch-account` / `hs logout`.
+//      An existing single-account (v1) file has no such key: its account is
+//      the `~/.heyspex/config.yaml` `account_id:` the earlier `hs login` wrote
+//      ([[HS-630L-WW9R-TASK-one-strict-cli-account-reader-hs-login]]) — read
+//      for that case only, never written any more (one account-id store).
+//   3. null — the writer omits `owner:`.
+//
+// This is ALSO the CLI's account reader: `resolveConfiguredAccountId` in
+// spex-console/src/lib/cli/vault-workspace-shared.ts and `readConfiguredAccountId`
+// in spex-console/src/lib/cli/install-identity.ts both delegate to
+// `resolveSessionOwnerUncached`, so one precedence serves `hs vault`, `hs connect`,
+// `hs install` and every MCP frontmatter writer. Its bearer twin is
+// `./credentials.mjs` (HS-HL0D).
+//
+// Cached per process once resolved from the real environment (the MCP server
+// is spawned once per session; pairing changes restart it). Callers inject
+// `env` / `homeDir` / `readFile` for tests, which bypasses the cache.
+
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { readCurrentAccountId } from './credentials.mjs';
+
+const ACCOUNT_ID_LINE_RE = /^account_id:\s*["']?([^"'\r\n#]+)/m;
+
+/**
+ * Read the paired account id from `~/.heyspex/config.yaml`, or null.
+ * @param {{ homeDir?: string, readFile?: (p: string) => string }} [opts]
+ */
+export function readConfigAccountId({ homeDir = heyspexHome(), readFile } = {}) {
+  const read = readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const raw = read(join(homeDir, '.heyspex', 'config.yaml'));
+    const match = String(raw ?? '').match(ACCOUNT_ID_LINE_RE);
+    const value = match?.[1]?.trim() ?? '';
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the session owner without caching — the pure core.
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
+ * @returns {string | null}
+ */
+export function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
+  const fromEnv = typeof env?.HS_ACCOUNT_ID === 'string' ? env.HS_ACCOUNT_ID.trim() : '';
+  if (fromEnv) return fromEnv;
+  return readCurrentAccountId({ homeDir, readFile });
+}
+
+let cached = null;
+let cacheFilled = false;
+
+/**
+ * The account every MCP-authored document is stamped with, or null when the
+ * machine has no resolvable account (the writers then OMIT `owner:`).
+ *
+ * The real-environment answer is memoised per process; any injected option
+ * bypasses the cache so tests stay hermetic.
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
+ * @returns {string | null}
+ */
+export function resolveSessionOwner(opts) {
+  if (opts && Object.keys(opts).length > 0) return resolveSessionOwnerUncached(opts);
+  if (!cacheFilled) {
+    cached = resolveSessionOwnerUncached();
+    cacheFilled = true;
+  }
+  return cached;
+}
+
+/** Test seam: forget the per-process answer. */
+export function __resetSessionOwnerCacheForTests() {
+  cached = null;
+  cacheFilled = false;
+}
+
+/**
+ * The `owner:` frontmatter entry for an object-shaped frontmatter — `{ owner }`
+ * when an account resolved, `{}` when none did (the key is omitted, never
+ * guessed). `explicit` (an `args.owner` the caller supplied) wins.
+ * @param {{ explicit?: unknown, resolve?: () => string | null }} [opts]
+ */
+export function ownerFrontmatterEntry({ explicit, resolve = resolveSessionOwner } = {}) {
+  const chosen =
+    typeof explicit === 'string' && explicit.trim() ? explicit.trim() : (resolve() ?? null);
+  return chosen ? { owner: chosen } : {};
+}

package/vendor/heyspex-mcp/session-tools.mjs

@@ -0,0 +1,162 @@
+// Session hand-off and agent identity tools: heyspex_handoff_record, handoff_load,
+// import_agent. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { consoleFetch } from './console-transport.mjs';
+import { consoleErrorCode, consoleErrorMessage } from './console-fetch.mjs';
+import { detectAgentIdentity } from './mcp-config.mjs';
+import { resolveReadTier } from './read-path.mjs';
+import { deferControlWrite } from './write-outbox.mjs';
+
+/**
+ * Import a community agent role via console `POST /api/agents/import` — the MCP
+ * face of agent import ([[HS-TASK-Z666]]). Same core as `hs agent import`; no
+ * field-mapping logic duplicated in JS.
+ */
+export async function handleImportAgent(args = {}) {
+  if (!args.collection || typeof args.collection !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'collection is required' }) }],
+    };
+  }
+  if (!args.role || typeof args.role !== 'string') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_ARGS', message: 'role is required' }) }],
+    };
+  }
+  const body = {
+    collection: args.collection,
+    role: args.role,
+    ...(args.dry_run === true || args.dry_run === 'true' ? { dry_run: true } : {}),
+  };
+  const result = await consoleFetch('/api/agents/import', { method: 'POST', body });
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'IMPORT_AGENT_FAILED'),
+      message: consoleErrorMessage(result, `POST /api/agents/import returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: body,
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  const responseBody = result.body ?? {};
+  const payload = {
+    spec_id: responseBody.spec_id ?? null,
+    path: responseBody.path ?? null,
+    warnings: Array.isArray(responseBody.warnings) ? responseBody.warnings : [],
+    ...(responseBody.dry_run ? { dry_run: true } : {}),
+    console_response: responseBody,
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+/**
+ * Upsert the current resume context for this agent/lane into the Neon control
+ * plane — [[HS-EPIC-NCPS]] handoff_context / [[HS-EPIC-CLMW]] `hs handoff record`.
+ *
+ * Self-purging overwrite-in-place (PUT /api/control/handoff-context). The lane
+ * defaults to this agent's session id so each session is its own lane. Coordi-
+ * nation only — the endpoint rejects durable-knowledge fields.
+ */
+export async function handleHandoffRecord(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const laneKey =
+    typeof args.lane === 'string' && args.lane.trim()
+      ? args.lane.trim()
+      : identity.sessionId;
+  const body = {
+    lane_key: laneKey,
+    agent: identity.agent,
+    ...(typeof args.spec_id === 'string' ? { spec_id: args.spec_id } : {}),
+    ...(typeof args.phase === 'string' ? { phase: args.phase } : {}),
+    ...(typeof args.estimated_time === 'string' ? { estimated_time: args.estimated_time } : {}),
+    ...(Array.isArray(args.blockers) ? { blockers: args.blockers.map(String) } : {}),
+    ...(Array.isArray(args.links) ? { links: args.links.map(String) } : {}),
+  };
+  const result = await consoleFetch('/api/control/handoff-context', {
+    method: 'PUT',
+    body,
+  });
+  if (!result.ok) {
+    const deferred = await deferControlWrite(result, {
+      route: '/api/control/handoff-context',
+      method: 'PUT',
+      request_body: body,
+      acting_agent: identity.agent,
+      session_id: identity.sessionId,
+    }, { isCloud: async () => (await resolveReadTier()) === 'neon' });
+    if (deferred) return deferred;
+    const payload = {
+      error: consoleErrorCode(result, 'HANDOFF_RECORD_FAILED'),
+      message: consoleErrorMessage(result, `Handoff-context endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: { lane: laneKey },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ lane: laneKey, console_response: result.body }, null, 2),
+    }],
+  };
+}
+
+/**
+ * Read the current resume context for a lane from the Neon control plane —
+ * [[HS-EPIC-NCPS]] handoff_context / [[HS-EPIC-CLMW]] `hs handoff load`.
+ *
+ * Defaults to this agent's own lane (its session); `all: true` lists every
+ * active lane (parallel-agent off-on-deck). Self-purging — no per-session
+ * history; expired rows read as absent.
+ */
+export async function handleHandoffLoad(args = {}) {
+  const identity = detectAgentIdentity(args.agent, args.session_id);
+  const wantAll = args.all === true;
+  const laneKey =
+    typeof args.lane === 'string' && args.lane.trim()
+      ? args.lane.trim()
+      : identity.sessionId;
+  const path = wantAll
+    ? '/api/control/handoff-context'
+    : `/api/control/handoff-context?lane=${encodeURIComponent(laneKey)}`;
+  const result = await consoleFetch(path);
+  if (!result.ok) {
+    const payload = {
+      error: consoleErrorCode(result, 'HANDOFF_LOAD_FAILED'),
+      message: consoleErrorMessage(result, `Handoff-context endpoint returned ${result.status}`),
+      status: result.status,
+      url: result.url,
+      console_response: result.body,
+      attempted: wantAll ? { all: true } : { lane: laneKey },
+    };
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(
+        wantAll ? result.body : { lane: laneKey, ...result.body },
+        null,
+        2,
+      ),
+    }],
+  };
+}