heyspex 0.1.0

package/dist/cli/hs-connect.mjs

@@ -0,0 +1,3436 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-connect.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync6, writeFileSync as writeFileSync2 } from "node:fs";
+import path4 from "node:path";
+import process2 from "node:process";
+
+// spex-console/src/lib/cli/connect.ts
+import { readdirSync } from "node:fs";
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// spex-console/src/lib/vault-registry/types.ts
+var VAULT_REGISTRY_SCHEMA_VERSION = 1;
+function emptyVaultRegistry() {
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    workspaces: [],
+    vaults: [],
+    active_workspace_id: null,
+    active_vault_id: null
+  };
+}
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+function vaultRegistryDir(opts = {}) {
+  return opts.registryDir ?? join(homedir(), ".heyspex");
+}
+function vaultRegistryFilePath(opts = {}) {
+  return join(vaultRegistryDir(opts), "registry.json");
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function normalizeWorkspace(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.created_at)) return null;
+  const record = {
+    id: o.id,
+    display_name: o.display_name,
+    created_at: o.created_at,
+    archived: o.archived === true
+  };
+  if (isNonEmptyString(o.github_org)) record.github_org = o.github_org;
+  return record;
+}
+function normalizeVault(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.workspace_id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.repo_root_abs)) return null;
+  if (typeof o.schema_version !== "number") return null;
+  if (!isNonEmptyString(o.registered_at)) return null;
+  const record = {
+    id: o.id,
+    workspace_id: o.workspace_id,
+    display_name: o.display_name,
+    repo_root_abs: o.repo_root_abs,
+    schema_version: o.schema_version,
+    registered_at: o.registered_at,
+    archived: o.archived === true
+  };
+  if (isNonEmptyString(o.github_remote)) record.github_remote = o.github_remote;
+  return record;
+}
+function parseVaultRegistryFile(json) {
+  const fallback = emptyVaultRegistry();
+  if (!json || typeof json !== "object") return fallback;
+  const o = json;
+  const workspacesRaw = Array.isArray(o.workspaces) ? o.workspaces : [];
+  const workspaces2 = workspacesRaw.map(normalizeWorkspace).filter((w) => w !== null);
+  const vaultsRaw = Array.isArray(o.vaults) ? o.vaults : [];
+  const vaults2 = vaultsRaw.map(normalizeVault).filter((v) => v !== null);
+  const active_workspace_id = isNonEmptyString(o.active_workspace_id) ? o.active_workspace_id : null;
+  const active_vault_id = isNonEmptyString(o.active_vault_id) ? o.active_vault_id : null;
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    workspaces: workspaces2,
+    vaults: vaults2,
+    active_workspace_id,
+    active_vault_id
+  };
+}
+function loadVaultRegistry(opts = {}) {
+  const filePath = vaultRegistryFilePath(opts);
+  if (!existsSync(filePath)) return emptyVaultRegistry();
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    return parseVaultRegistryFile(JSON.parse(raw));
+  } catch {
+    return emptyVaultRegistry();
+  }
+}
+function writeVaultRegistry(registry, opts = {}) {
+  const filePath = vaultRegistryFilePath(opts);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync(tmpPath, `${JSON.stringify(registry, null, 2)}
+`, "utf8");
+  renameSync(tmpPath, filePath);
+}
+function isValidId(id) {
+  if (!isNonEmptyString(id)) return false;
+  if (id.includes("/") || id.includes("\\")) return false;
+  if (id === "." || id === "..") return false;
+  return true;
+}
+function registerWorkspace(record, opts = {}) {
+  if (!isValidId(record.id)) {
+    throw new Error(`registerWorkspace: invalid workspace id "${record.id}"`);
+  }
+  const registry = loadVaultRegistry(opts);
+  const idx = registry.workspaces.findIndex((w) => w.id === record.id);
+  if (idx >= 0) {
+    registry.workspaces[idx] = { ...record };
+  } else {
+    registry.workspaces.push({ ...record });
+  }
+  writeVaultRegistry(registry, opts);
+  return registry;
+}
+function registerVault(record, opts = {}) {
+  if (!isValidId(record.id)) {
+    throw new Error(`registerVault: invalid vault id "${record.id}"`);
+  }
+  if (!isValidId(record.workspace_id)) {
+    throw new Error(`registerVault: invalid workspace_id "${record.workspace_id}"`);
+  }
+  if (!isNonEmptyString(record.repo_root_abs)) {
+    throw new Error("registerVault: repo_root_abs is required");
+  }
+  const registry = loadVaultRegistry(opts);
+  const isSameVault = (v) => v.id === record.id || v.repo_root_abs === record.repo_root_abs;
+  const idx = registry.vaults.findIndex(isSameVault);
+  if (idx >= 0) {
+    registry.vaults[idx] = { ...record };
+    registry.vaults = registry.vaults.filter((v, i) => i === idx || !isSameVault(v));
+  } else {
+    registry.vaults.push({ ...record });
+  }
+  writeVaultRegistry(registry, opts);
+  return registry;
+}
+
+// spex-console/src/lib/cli/vault-workspace-shared.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import os from "node:os";
+import path2 from "node:path";
+
+// dist/cli/._sql-orm-inert.cli-shim.mjs
+var inert = new Proxy(function inert2() {
+  return inert2;
+}, {
+  get(_target, prop) {
+    if (prop === "then" || prop === Symbol.toPrimitive || prop === Symbol.iterator) return void 0;
+    return inert;
+  },
+  apply() {
+    return inert;
+  },
+  construct() {
+    return inert;
+  }
+});
+var sql = inert;
+var eq = inert;
+var bigint = inert;
+var bigserial = inert;
+var boolean = inert;
+var foreignKey = inert;
+var index = inert;
+var integer = inert;
+var jsonb = inert;
+var pgEnum = inert;
+var pgTable = inert;
+var primaryKey = inert;
+var text = inert;
+var timestamp = inert;
+var uniqueIndex = inert;
+
+// dist/cli/._postgres-client.cli-shim.mjs
+function isPostgresConfigured() {
+  return false;
+}
+function getPostgresDb() {
+  throw new Error(
+    "getPostgresDb() is unavailable in a published install -- this build ships no direct database connection."
+  );
+}
+
+// spex-console/src/lib/db/schema/interfaces.ts
+var SINGLE_USER_ID = "pwher";
+var DEFAULT_VAULT_ID = "default";
+
+// spex-console/src/lib/db/schema/postgres.ts
+var edgeTypeEnum = pgEnum("edge_type", [
+  "blocks",
+  "related",
+  "parent_child",
+  "discovered_from"
+]);
+var validationSeverityEnum = pgEnum("validation_severity", ["error", "warning"]);
+var outboxOpEnum = pgEnum("outbox_op", ["upsert", "delete"]);
+var specs = pgTable(
+  "specs",
+  {
+    id: text("id").notNull(),
+    name: text("name").notNull(),
+    type: text("type").notNull(),
+    status: text("status").notNull(),
+    priority: integer("priority"),
+    owner: text("owner"),
+    created: text("created").notNull(),
+    // ISO date YYYY-MM-DD
+    updated: text("updated").notNull(),
+    // ISO date YYYY-MM-DD
+    relPath: text("rel_path").notNull(),
+    // Vault-relative POSIX path
+    bodyHash: text("body_hash").notNull(),
+    // SHA-256 of full file (frontmatter + body) for change detection
+    // Canonical authored body — re-added in 0020 ([[HS-TASK-UGUD]]); reverses the 0005 drop.
+    // Nullable until the write path ([[HS-TASK-X724]]) always populates it; UGUD backfills
+    // existing rows from the disk vault. NO read-path change yet (reads stay on disk until 4PH9).
+    bodyText: text("body_text"),
+    indexedAt: timestamp("indexed_at", { withTimezone: true }).notNull(),
+    // NOTE: `body_text` + `body_tsvector` were dropped in migration 0005
+    // ([[HS-EPIC-NLOC]]); the `embedding vector(1536)` column was dropped in
+    // 0004 (HS-EPIC-VSTR). HeySpex retrieval is lexical-only and LOCAL — no read
+    // tier in Neon — per [[retrieval-substrate-lexical-not-embeddings-gate-b-no]].
+    // WRT3 §Schema — single-user sentinel today; future multi-user routing.
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Index-isolation scope ([[HS-Z2KC-TASK]]): every index-table row is scoped
+    // by vault so >1 vault can share one Neon database without colliding on the
+    // specs PK or the (rel_path, user_id) unique index. DEFAULT keeps the ALTER
+    // safe on populated tables and single-vault installs under one bucket.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    // WRT3 §Soft-delete — null = active. No hard-delete API is exposed.
+    deletedAt: timestamp("deleted_at", { withTimezone: true }),
+    // Explicit family key (Naming V3 step 1, [[HS-8O69-EPIC-LKF9-relational-family-graph-authoring]]):
+    // nullable until the backfill script runs; the indexer writes the frontmatter
+    // `family:` field when present, else derives it via `familyOf` (parse
+    // fallback from `id`/basename). Nothing should string-parse family from `id`
+    // once this column is populated — see `dev-factory/handoffs/NAMING-V3-MIGRATION-BRIEF.md`.
+    family: text("family")
+  },
+  (table) => [
+    // Composite PK (vault_id, id): the same HS-XXXX id may exist once PER VAULT.
+    primaryKey({ columns: [table.vaultId, table.id] }),
+    // SpexConsole main list views filter by type + status
+    index("specs_type_status_idx").on(table.type, table.status),
+    // Family-graph lookups (Naming V3 step 1) — group specs by family key.
+    index("specs_family_idx").on(table.family),
+    // Per-user + per-vault lookups + filtering out soft-deleted rows in the hot path
+    index("specs_user_active_idx").on(table.userId, table.vaultId).where(sql`${table.deletedAt} IS NULL`),
+    // One-file-one-row guarantee: at most one ACTIVE row per (rel_path, user,
+    // vault). Without this two rows could share a rel_path under different id
+    // forms (bare vs full-slug) and render as a duplicate-key error. Partial
+    // (deleted_at IS NULL) so soft-deleted orphans don't block re-indexing. The
+    // upsert path soft-deletes any conflicting row first. Scoped by vault so the
+    // same rel_path can be indexed independently under two vaults.
+    uniqueIndex("specs_relpath_user_uq").on(table.relPath, table.userId, table.vaultId).where(sql`${table.deletedAt} IS NULL`)
+  ]
+);
+var tags = pgTable(
+  "tags",
+  {
+    specId: text("spec_id").notNull(),
+    tag: text("tag").notNull(),
+    inFrontmatter: boolean("in_frontmatter").notNull(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    primaryKey({ columns: [table.vaultId, table.specId, table.tag] }),
+    foreignKey({
+      columns: [table.vaultId, table.specId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade")
+  ]
+);
+var edges = pgTable(
+  "edges",
+  {
+    fromId: text("from_id").notNull(),
+    toId: text("to_id").notNull(),
+    edgeType: edgeTypeEnum("edge_type").notNull().$type(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    primaryKey({ columns: [table.vaultId, table.fromId, table.toId, table.edgeType] }),
+    foreignKey({
+      columns: [table.vaultId, table.fromId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade"),
+    foreignKey({
+      columns: [table.vaultId, table.toId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade"),
+    // Forward dependency lookups (what does this spec block?)
+    index("edges_from_type_idx").on(table.fromId, table.edgeType),
+    // Reverse dependency lookups (what blocks this spec?)
+    index("edges_to_type_idx").on(table.toId, table.edgeType)
+  ]
+);
+var wikilinks = pgTable(
+  "wikilinks",
+  {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    fromId: text("from_id").notNull(),
+    targetBasename: text("target_basename").notNull(),
+    resolvedId: text("resolved_id"),
+    inFrontmatter: boolean("in_frontmatter").notNull(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    // Surrogate PK `id` stays; the composite FKs scope both link ends to the
+    // owning vault's specs. resolvedId is nullable, so its composite FK is only
+    // enforced when BOTH columns are non-null (MATCH SIMPLE — Postgres default),
+    // which lets an unresolved forward reference keep resolvedId NULL.
+    foreignKey({
+      columns: [table.vaultId, table.fromId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade"),
+    // CAUTION (migration 0049): in the live DB this constraint carries a PG-15+
+    // column list — ON DELETE SET NULL ("resolved_id") — because a plain
+    // composite SET NULL nulls vault_id too (NOT NULL → 23502 on any delete of
+    // a spec with inbound resolved links). Drizzle cannot express the column
+    // list, so this declaration is the closest approximation: do NOT let a
+    // future drizzle-kit generate "correct" the constraint back to plain
+    // SET NULL — that reintroduces the delete-blocking bug.
+    foreignKey({
+      columns: [table.vaultId, table.resolvedId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("set null"),
+    // Backlink queries: find all specs linking to a target
+    index("wikilinks_target_idx").on(table.targetBasename)
+  ]
+);
+var aliases = pgTable(
+  "aliases",
+  {
+    specId: text("spec_id").notNull(),
+    alias: text("alias").notNull(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    primaryKey({ columns: [table.vaultId, table.specId, table.alias] }),
+    foreignKey({
+      columns: [table.vaultId, table.specId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade")
+  ]
+);
+var validationIssues = pgTable(
+  "validation_issues",
+  {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    specId: text("spec_id").notNull(),
+    severity: validationSeverityEnum("severity").notNull().$type(),
+    code: text("code").notNull(),
+    // e.g. "unresolved_wikilink", "missing_frontmatter"
+    message: text("message").notNull(),
+    detectedAt: timestamp("detected_at", { withTimezone: true }).notNull(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    // Surrogate PK `id` stays; the composite FK scopes issues to the owning
+    // vault's specs.
+    foreignKey({
+      columns: [table.vaultId, table.specId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade"),
+    // Query issues by spec
+    index("validation_issues_spec_idx").on(table.specId),
+    // Query issues by severity (e.g., show all errors)
+    index("validation_issues_severity_idx").on(table.severity)
+  ]
+);
+var indexMeta = pgTable(
+  "index_meta",
+  {
+    key: text("key").notNull(),
+    // e.g. "schema_version", "last_indexed_commit"
+    value: text("value").notNull(),
+    // Scope indexer state (last_indexed_commit, schema_version, last_rebuild_at,
+    // and the progress_relay:<userId> KV) per vault so two vaults keep
+    // independent commit pointers. Composite PK (vault_id, key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.key] })]
+);
+var frontmatterFields = pgTable(
+  "frontmatter_fields",
+  {
+    specId: text("spec_id").notNull(),
+    field: text("field").notNull(),
+    value: jsonb("value"),
+    // JSON value for flexible storage
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID)
+  },
+  (table) => [
+    primaryKey({ columns: [table.vaultId, table.specId, table.field] }),
+    foreignKey({
+      columns: [table.vaultId, table.specId],
+      foreignColumns: [specs.vaultId, specs.id]
+    }).onDelete("cascade")
+  ]
+);
+var eventOutbox = pgTable(
+  "event_outbox",
+  {
+    seq: bigserial("seq", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull(),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: `seq` (bigserial) stays the PK; consumers that need to filter
+    // by owning vault (e.g. a per-vault snapshot job) can now do so — the
+    // global PartyKit / snapshot drains stay unfiltered by design (they drain
+    // every vault's outbox).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    specId: text("spec_id").notNull(),
+    op: outboxOpEnum("op").notNull().$type(),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    publishedAt: timestamp("published_at", { withTimezone: true }),
+    snapshottedAt: timestamp("snapshotted_at", { withTimezone: true })
+  },
+  (table) => [
+    // PartyKit fan-out drain — unpublished rows in monotonic order
+    index("event_outbox_unpublished_idx").on(table.seq).where(sql`${table.publishedAt} IS NULL`),
+    // Snapshot-to-git drain — unsnapshotted rows in monotonic order
+    index("event_outbox_unsnapshotted_idx").on(table.seq).where(sql`${table.snapshottedAt} IS NULL`),
+    // Per-vault-per-user catch-up (`WHERE vault_id = ? AND user_id = ? AND seq > ?`)
+    index("event_outbox_user_seq_idx").on(table.vaultId, table.userId, table.seq)
+  ]
+);
+var captureSessions = pgTable(
+  "capture_sessions",
+  {
+    id: text("id").primaryKey(),
+    // HS-CAP-XXXX, minted by the writer
+    ownerUserId: text("owner_user_id").notNull(),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] of [[HS-TNTI-EPIC-saas-multi-tenant-isolation]]).
+    // Mirrors `specs.vault_id` EXACTLY (text, NOT NULL, DEFAULT 'default', no FK
+    // — `vaults` rows can be provisioned in Neon after an index row exists, so a
+    // hard FK would break the boot order; the id is the isolation key, not an
+    // entity reference). The PK stays the globally-minted `id` (capture ids are
+    // random tokens, not per-vault sequences); `vault_id` is the READ/WRITE
+    // filter so one user's two vaults never see each other's captures.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    openedBy: text("opened_by").$type().notNull(),
+    openedBySession: text("opened_by_session").notNull(),
+    mode: text("mode").$type().notNull().default("attended"),
+    status: text("status").$type().notNull().default("pending"),
+    specPath: text("spec_path"),
+    contentBuffer: jsonb("content_buffer").notNull().default(sql`'{}'::jsonb`),
+    attachedAgents: jsonb("attached_agents").notNull().default(sql`'[]'::jsonb`),
+    captureChannel: text("capture_channel"),
+    traceId: text("trace_id"),
+    sourceUrl: text("source_url"),
+    /**
+     * Provenance columns for a capture created from the Agent Mirror canvas
+     * ([[HS-1ROV-EPIC-session-mirror-platform-claude-code]] §Stage 6a). Both
+     * nullable — every pre-existing writer (modal/agent/companion) leaves
+     * them unset. No FK (session/launch rows can expire or predate this
+     * column); `agent_session_id` is `agent_sessions.session_id`,
+     * `launch_id` is `launch_intents.id` by convention only.
+     */
+    agentSessionId: text("agent_session_id"),
+    launchId: text("launch_id"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    lastActivityAt: timestamp("last_activity_at", { withTimezone: true }).notNull().default(sql`now()`),
+    materializedAt: timestamp("materialized_at", { withTimezone: true }),
+    abandonedAt: timestamp("abandoned_at", { withTimezone: true })
+  },
+  (table) => [
+    // Per-vault + per-user lookup of in-flight captures (e.g. `/hs-capture` attach)
+    index("capture_sessions_pending_by_user").on(table.vaultId, table.ownerUserId, table.status).where(sql`${table.status} = 'pending'`),
+    // Companion `heyspex.capture/0.1` trace correlation
+    index("capture_sessions_companion_by_trace").on(table.traceId).where(sql`${table.traceId} IS NOT NULL`)
+  ]
+);
+var handoffContext = pgTable(
+  "handoff_context",
+  {
+    laneKey: text("lane_key").notNull(),
+    // agent/lane identifier — upsert key
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Part of the widened upsert key below: two vaults must keep independent
+    // CURRENT rows for the same (user, lane_key), not fight over one row.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    agentId: text("agent_id").notNull(),
+    specId: text("spec_id"),
+    // current spec; plain text, no FK (id-form may be bare vs full-slug)
+    phase: text("phase"),
+    blockers: jsonb("blockers").notNull().default(sql`'[]'::jsonb`),
+    estimatedTime: text("estimated_time"),
+    links: jsonb("links").notNull().default(sql`'[]'::jsonb`),
+    schemaVersion: integer("schema_version").notNull().default(1),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`),
+    // TTL — server-set on every upsert; reads filter `expires_at > now()`.
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+  },
+  (table) => [
+    // Self-purge upsert key: one CURRENT row per (vault, user, lane). Widened
+    // ([[HS-ZP5H-TASK]] GAP 2) from (user, lane) — two vaults sharing the
+    // owner's user_id must not fight over one lane row.
+    uniqueIndex("handoff_context_user_lane_uq").on(table.vaultId, table.userId, table.laneKey),
+    // List-active-lanes read path (parallel-agent off-on-deck — PA7H).
+    index("handoff_context_user_expiry_idx").on(table.vaultId, table.userId, table.expiresAt)
+  ]
+);
+var claimEventKindEnum = pgEnum("claim_event_kind", [
+  "acquired",
+  "released",
+  "expired",
+  "stolen",
+  "status_updated",
+  // Sequencer decision log ([[HS-DO05-4U1E-EPIC-session-sequencer-in-the-console]]
+  // AC4): appended in the same transaction as the sequence assignment so the
+  // replay epic can reconstruct the order from events alone.
+  "sequence_assigned"
+]);
+var activeClaimStatusEnum = pgEnum("active_claim_status", [
+  "working",
+  "pending",
+  "blocked"
+]);
+var pendingReasonEnum = pgEnum("pending_reason", [
+  "question",
+  "permission",
+  "planning",
+  "response"
+]);
+var focusEventKindEnum = pgEnum("focus_event_kind", ["set", "cleared"]);
+var specEventKindEnum = pgEnum("spec_event_kind", [
+  "status_change",
+  "wikilink_added",
+  "wikilink_removed",
+  "review_requested",
+  "review_resolved",
+  "priority_change",
+  "parent_change",
+  "claim_acquired",
+  "claim_released"
+]);
+var focusPin = pgTable(
+  "focus_pin",
+  {
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`. The
+    // singleton is per (vault, user), not per user: one user with two vaults
+    // pins independently in each.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    specId: text("spec_id").notNull(),
+    pinnedBy: text("pinned_by").notNull(),
+    // agent identifier
+    pinnedAt: timestamp("pinned_at", { withTimezone: true }).notNull().default(sql`now()`),
+    // Silent fuse — null means no expiry; reads treat `expires_at <= now()` as cleared.
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    // Cross-milestone "do the prerequisite first, then come back" return target
+    // ([[HS-EPIC-QQBD]]): when the spec named by `return_on_close_of` closes, the
+    // status route re-pins `return_to_spec_id` and clears both. Both null = an
+    // ordinary pin with no auto-return. Nullable + additive (no data backfill).
+    returnToSpecId: text("return_to_spec_id"),
+    returnOnCloseOf: text("return_on_close_of"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var captureFocusPin = pgTable(
+  "capture_focus_pin",
+  {
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    specId: text("spec_id").notNull(),
+    pinnedBy: text("pinned_by").notNull(),
+    pinnedAt: timestamp("pinned_at", { withTimezone: true }).notNull().default(sql`now()`),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    // Kept structurally identical to {@link focusPin} (pins.ts casts one table to
+    // the other); the capture flow never populates these return-target columns.
+    returnToSpecId: text("return_to_spec_id"),
+    returnOnCloseOf: text("return_on_close_of"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var captureFocusSelection = pgTable(
+  "capture_focus_selection",
+  {
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // The resolved spec path of the current capture on deck (layer-2 core).
+    specPath: text("spec_path"),
+    // Capture kind — "idea" today; text, validated app-side, kept open.
+    kind: text("kind"),
+    // Free-form note for why this capture is pinned (e.g. "Pinned from console").
+    reason: text("reason"),
+    // The agent display name currently claiming the capture (doc-claim-badge).
+    claimedBy: text("claimed_by"),
+    // The claiming agent's session id (claim refresh surface).
+    claimSession: text("claim_session"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var focusSelection = pgTable(
+  "focus_selection",
+  {
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // The resolved spec path of the current focus (layer-2 core; scheduler tier #2).
+    specPath: text("spec_path"),
+    // Grain: "milestone" | "epic" | "task" (FocusKind). Text, not an enum — the
+    // vocabulary is validated app-side and kept open for forward grains.
+    kind: text("kind"),
+    // Provenance: "human" | "algorithm" | "human_switched_from_blocker" (FocusProvenance).
+    pickedBy: text("picked_by"),
+    pickedAt: timestamp("picked_at", { withTimezone: true }),
+    // The FocusReason object (trigger / formula / score / runners_up[]) as JSONB.
+    pickedReason: jsonb("picked_reason"),
+    // The blocked epic switched away from (only when picked_by = human_switched_from_blocker).
+    blockerOrigin: text("blocker_origin"),
+    // Free-form note when a human overrides the algorithm pick (Why-Now panel).
+    overrideReason: text("override_reason"),
+    // Legacy FocusState fields kept for backcompat with pre-Phase-3 writers.
+    reason: text("reason"),
+    expires: timestamp("expires", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var focusSkips = pgTable(
+  "focus_skips",
+  {
+    // Insertion-order key — reads order by this so the skip set keeps file order.
+    id: bigserial("id", { mode: "number" }).notNull().unique(),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    specId: text("spec_id").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // PK widened to (vault_id, user_id, spec_id): the same HS-XXXX id exists once
+    // PER VAULT, so a skip in vault A must not collide with (or hide) the same id
+    // in vault B. Strict superset of the old (user_id, spec_id) key — existing
+    // rows stay unique under it.
+    primaryKey({ columns: [table.vaultId, table.userId, table.specId] }),
+    // "this vault+user's skips in insertion order" — the list query.
+    index("focus_skips_user_order_idx").on(table.vaultId, table.userId, table.id)
+  ]
+);
+var activeClaims = pgTable(
+  "active_claims",
+  {
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`. Part
+    // of the PK, so the atomic-acquire UNIQUE is per (vault, user, spec): vault A
+    // holding HS-XXXX no longer blocks vault B from claiming ITS OWN HS-XXXX.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    specId: text("spec_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    sessionId: text("session_id").notNull(),
+    claimedAt: timestamp("claimed_at", { withTimezone: true }).notNull().default(sql`now()`),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    // Live agent-lifecycle signals — mirror the file-side `ActiveClaim` shape from
+    // [[HS-TASK-0LU3]] so the On-Deck v2 surface can distinguish Working / Pending /
+    // Stale / Blocked when claims migrate off `.heyspex/active-claims.json` ([[HS-TASK-ACLM]]).
+    // `effectiveStatus` + `staleAt` stay derived at read time (not persisted).
+    status: activeClaimStatusEnum("status").notNull().default("working"),
+    lastActivityAt: timestamp("last_activity_at", { withTimezone: true }).notNull().default(sql`now()`),
+    /** Fast-death heartbeat ([[HS-TASK-A3FE]]); distinct from minutes-scale `expires_at` lease. */
+    heartbeatAt: timestamp("heartbeat_at", { withTimezone: true }),
+    pendingReason: pendingReasonEnum("pending_reason"),
+    pendingExcerpt: text("pending_excerpt"),
+    errorMessage: text("error_message"),
+    // Live agent work-stage ([[HS-EPIC-... What's Next Phase 2]]): the
+    // present-progressive verb the agent reports as it works (one of WORK_STAGES,
+    // e.g. "Drafting") and the 0-based acceptance-criterion index it is currently
+    // on. Both nullable — a claim need not report progress. Plain text/integer (not
+    // a pg enum) so the verb vocabulary can evolve without an enum migration; the
+    // closed list is enforced in code (src/lib/work-stages.ts) at the write route.
+    currentStage: text("current_stage"),
+    acProgress: integer("ac_progress"),
+    // Durable agent identity↔session binding ([[HS-EPIC-96YK]] AC#2): the
+    // identity `name` slug this claim is operating as (e.g. "code-reviewer"),
+    // so the Agents surface binds presence to the named identity instead of the
+    // best-effort agent-string match. Nullable — a claim need not declare one.
+    agentProfile: text("agent_profile"),
+    // Close-out verification gate ([[HS-EPIC-P2TR]]). `close_permitted` blocks the
+    // `in_review` flip until an independent verifier (or the deterministic manifest
+    // runner) grants it via the verification API — the implementer's self-reported
+    // `ac_progress` is demoted to a display-only claim. `close_granted_by` records
+    // the granting authority (agent id or "human"); `verification_ac_state` holds
+    // the per-criterion `AcCriterionState[]` provenance array.
+    closePermitted: boolean("close_permitted").notNull().default(false),
+    closeGrantedAt: timestamp("close_granted_at", { withTimezone: true }),
+    closeGrantedBy: text("close_granted_by"),
+    verificationAcState: jsonb("verification_ac_state").$type().notNull().default(sql`'[]'::jsonb`),
+    // Session-sequencer global order ([[HS-DO05-4U1E-EPIC-session-sequencer-in-the-console]] AC1):
+    // database-minted, strictly increasing across the table — therefore strictly
+    // increasing within every vault (gaps allowed; ordering is the contract).
+    sequence: bigserial("sequence", { mode: "number" }).notNull().unique(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId, table.specId] })]
+);
+var claimWaiters = pgTable(
+  "claim_waiters",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    specId: text("spec_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    sessionId: text("session_id").notNull(),
+    // Shared global order: DEFAULT nextval on the claims sequence, not a
+    // per-table bigserial (which would mint a second, unrelated counter).
+    sequence: bigint("sequence", { mode: "number" }).notNull().default(sql`nextval('active_claims_sequence_seq')`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // "who is queued behind this spec, in order" — the grant + position query.
+    index("claim_waiters_spec_seq_idx").on(
+      table.vaultId,
+      table.userId,
+      table.specId,
+      table.sequence
+    )
+  ]
+);
+var claimEvents = pgTable(
+  "claim_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: the `id` PK is untouched (append-only log, no upsert key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    eventKind: claimEventKindEnum("event_kind").notNull(),
+    specId: text("spec_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    timestamp: timestamp("timestamp", { withTimezone: true }).notNull().default(sql`now()`),
+    metadata: jsonb("metadata").notNull().default(sql`'{}'::jsonb`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // "events for this spec, newest first" — the common query (NCPS §indexes).
+    index("claim_events_spec_ts_idx").on(
+      table.vaultId,
+      table.userId,
+      table.specId,
+      table.timestamp.desc()
+    )
+  ]
+);
+var focusEvents = pgTable(
+  "focus_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: the `id` PK is untouched (append-only log, no upsert key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    eventKind: focusEventKindEnum("event_kind").notNull(),
+    specId: text("spec_id"),
+    // null for `cleared`
+    actor: text("actor").notNull(),
+    timestamp: timestamp("timestamp", { withTimezone: true }).notNull().default(sql`now()`),
+    metadata: jsonb("metadata").notNull().default(sql`'{}'::jsonb`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    index("focus_events_spec_ts_idx").on(
+      table.vaultId,
+      table.userId,
+      table.specId,
+      table.timestamp.desc()
+    )
+  ]
+);
+var focusAreas = pgTable(
+  "focus_areas",
+  {
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`. The
+    // band is per (vault, user): a tag band set in vault A must not lift specs
+    // in vault B.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    version: integer("version").notNull().default(1),
+    rationale: text("rationale"),
+    // The tag set the focus-band pipeline stage matches against (jsonb string[]).
+    tags: jsonb("tags").notNull().default(sql`'[]'::jsonb`),
+    updatedBy: text("updated_by"),
+    // agent · session that last wrote the band
+    // Reserved fuse — null means no expiry. A2 writes it; enforcement is deferred.
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var focusAreasEvents = pgTable(
+  "focus_areas_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: the `id` PK is untouched (append-only log, no upsert key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    eventKind: focusEventKindEnum("event_kind").notNull(),
+    actor: text("actor").notNull(),
+    timestamp: timestamp("timestamp", { withTimezone: true }).notNull().default(sql`now()`),
+    metadata: jsonb("metadata").notNull().default(sql`'{}'::jsonb`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    index("focus_areas_events_ts_idx").on(table.vaultId, table.userId, table.timestamp.desc())
+  ]
+);
+var specEvents = pgTable(
+  "spec_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: the `id` PK is untouched (append-only log, no upsert key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    eventKind: specEventKindEnum("event_kind").notNull(),
+    specId: text("spec_id").notNull(),
+    actor: text("actor").notNull(),
+    timestamp: timestamp("timestamp", { withTimezone: true }).notNull().default(sql`now()`),
+    metadata: jsonb("metadata").notNull().default(sql`'{}'::jsonb`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // High-traffic "events for spec X" query (<50ms target — NCPS AC #5).
+    index("spec_events_spec_ts_idx").on(
+      table.vaultId,
+      table.userId,
+      table.specId,
+      table.timestamp.desc()
+    ),
+    // `?kind=` filtered query.
+    index("spec_events_spec_kind_ts_idx").on(
+      table.vaultId,
+      table.userId,
+      table.specId,
+      table.eventKind,
+      table.timestamp.desc()
+    )
+  ]
+);
+var rateLimitBuckets = pgTable(
+  "rate_limit_buckets",
+  {
+    userId: text("user_id").notNull(),
+    bucket: text("bucket").notNull(),
+    windowStart: timestamp("window_start", { withTimezone: true }).notNull(),
+    count: integer("count").notNull().default(0),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    primaryKey({ columns: [table.userId, table.bucket, table.windowStart] }),
+    // Background reaper / dashboards: enumerate stale rows by `window_start`
+    // older than the longest live window. The hot path uses the composite PK.
+    index("rate_limit_buckets_window_idx").on(table.windowStart)
+  ]
+);
+var userVaults = pgTable("user_vaults", {
+  userId: text("user_id").primaryKey(),
+  vaultRepo: text("vault_repo").notNull(),
+  /** GitHub App installation id — set by `/api/github/callback` before a vault is linked. */
+  installationId: integer("installation_id"),
+  vaultLocalPath: text("vault_local_path"),
+  repoName: text("repo_name"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+});
+var milestoneSnapshots = pgTable(
+  "milestone_snapshots",
+  {
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`. Part
+    // of the PK: two vaults each hold their own frozen rank for the same
+    // milestone id.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    milestoneId: text("milestone_id").notNull(),
+    snapshotVersion: integer("snapshot_version").notNull().default(1),
+    snapshotAt: timestamp("snapshot_at", { withTimezone: true }).notNull().defaultNow(),
+    schedulerInputDigest: text("scheduler_input_digest"),
+    epicOrder: jsonb("epic_order").$type().notNull(),
+    appendedAfterSnapshot: jsonb("appended_after_snapshot").$type().notNull().default(sql`'{"epics":[],"tasks_by_epic":{}}'::jsonb`),
+    dormantAt: timestamp("dormant_at", { withTimezone: true })
+  },
+  (table) => [
+    primaryKey({ columns: [table.vaultId, table.userId, table.milestoneId] }),
+    // "active snapshot for vault+user" hot lookup — only non-dormant rows.
+    index("ms_user_active_idx").on(table.vaultId, table.userId).where(sql`${table.dormantAt} IS NULL`)
+  ]
+);
+var modelRegistryEntries = pgTable(
+  "model_registry_entries",
+  {
+    id: text("id").notNull(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    model: text("model").notNull(),
+    agent: text("agent").notNull(),
+    shell: text("shell").notNull(),
+    enabled: boolean("enabled").notNull().default(true),
+    isDefault: boolean("is_default").notNull().default(false),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    primaryKey({ columns: [table.userId, table.id] }),
+    index("model_registry_entries_user_default_idx").on(table.userId, table.isDefault)
+  ]
+);
+var launchIntentStatusEnum = pgEnum("launch_intent_status", [
+  "pending",
+  // emitted by the browser, not yet claimed by a companion
+  "claimed",
+  // a companion poller took it (claim-on-read) and is spawning
+  "done",
+  // the companion ACKed after spawning the local agent
+  "failed"
+  // the companion claimed it but the local spawn threw (see last_error)
+]);
+var launchIntents = pgTable(
+  "launch_intents",
+  {
+    id: text("id").primaryKey(),
+    // uuid, client-opaque intent id
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: `id` (a caller-minted uuid) stays the PK; `vault_id` is the
+    // READ/WRITE filter so the SAME owner's two vaults never drain each
+    // other's spawn/mint/mirror-send intents.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    // The `/hs-next <id>` target spec (idempotency key for the optimistic
+    // "Launching…" face); null for a bare `/hs-next` launch.
+    specId: text("spec_id"),
+    prompt: text("prompt").notNull(),
+    // the `/hs-next …` prompt to seed the agent
+    registryEntryId: text("registry_entry_id"),
+    agent: text("agent"),
+    /** When false, companion uses `cmd /c` on Windows so the tab closes when the agent exits. */
+    keepTerminalOpen: boolean("keep_terminal_open").notNull().default(true),
+    // Resolved launch target ([[HS-EPIC-JLTL]] model+effort assignment). Nullable
+    // and additive: an old companion simply ignores them and spawns with CLI
+    // defaults — exactly the pre-column behavior.
+    model: text("model"),
+    reasoningEffort: text("reasoning_effort"),
+    // Companion-reported spawn failure detail (status `failed`) — the write-back
+    // channel that lets the cloud UI stop toasting optimistic success.
+    lastError: text("last_error"),
+    status: launchIntentStatusEnum("status").notNull().default("pending"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    // Set when a companion claims the intent (pending → claimed).
+    claimedAt: timestamp("claimed_at", { withTimezone: true }),
+    // TTL fuse — server-set on emit; the drain filters `expires_at > now()` and
+    // emit reaps already-expired rows so a dead browser tab can't strand work.
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+  },
+  (table) => [
+    // Drain query: "oldest pending (non-expired) intents for this vault+user".
+    index("launch_intents_user_status_idx").on(
+      table.vaultId,
+      table.userId,
+      table.status,
+      table.createdAt
+    )
+  ]
+);
+var companionRelayPresence = pgTable(
+  "companion_relay_presence",
+  {
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    lastSeenAt: timestamp("last_seen_at", { withTimezone: true }).notNull()
+  },
+  (table) => [primaryKey({ columns: [table.userId, table.vaultId] })]
+);
+var companionSettingsStore = pgTable(
+  "companion_settings",
+  {
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    settings: jsonb("settings").notNull(),
+    telemetry: jsonb("telemetry"),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.userId, table.vaultId] })]
+);
+var wipLedger = pgTable(
+  "wip_ledger",
+  {
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    /** Epic/spec id the hand-off belongs to (short id, e.g. "HS-COYG"). */
+    specId: text("spec_id").notNull(),
+    /** The full WipEntry blob — see `WipEntry` in `src/lib/wip-state.ts`. */
+    payload: jsonb("payload").notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.specId] })]
+);
+var gatherResults = pgTable(
+  "gather_results",
+  {
+    jobId: text("job_id").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    /** Per-page result entries — `[{ url, state: "cleaned"|"blocked"|"failed", ... }]`. */
+    pages: jsonb("pages").notNull(),
+    /**
+     * A research job's engine-level search account — `{ query,
+     * enginesAttempted, enginesAnswered, resultsFound, resultsGathered,
+     * summary, engines: [{ engine, answered, results, reason?, httpStatus? }] }`.
+     * Null for plain gather/crawl jobs (nothing was searched) and for uploads
+     * from Companions built before the report existed. This is what lets a
+     * zero-page search result say WHY it is empty
+     * ([[HS-RIZN-DIL5-DIAG-spexcrawl-search-returns-zero-pages-on]]).
+     */
+    search: jsonb("search"),
+    createdAt: timestamp("created_at", { withTimezone: true }).default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.jobId, table.idempotencyKey] })]
+);
+var agentSessions = pgTable(
+  "agent_sessions",
+  {
+    sessionId: text("session_id").primaryKey(),
+    // FK-by-convention to launch_intents.id — no hard FK, intents expire/sweep
+    // while the session row (and its usage history) must outlive them.
+    launchId: text("launch_id"),
+    ownerUserId: text("owner_user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]]) — mirrors `specs.vault_id`. The
+    // PK stays the vendor-minted `session_id` (a globally-unique uuid, not a
+    // per-vault sequence); `vault_id` is the READ/WRITE filter.
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    vendor: text("vendor").notNull(),
+    // "claude-code" now; enum grows later (read-only viewer vendors)
+    machine: text("machine"),
+    cwd: text("cwd"),
+    transcriptPath: text("transcript_path"),
+    // Session-chain lineage after /clear, /branch, /rewind, --fork-session.
+    parentSessionId: text("parent_session_id"),
+    status: text("status").notNull().default("live"),
+    // live | ended | stale
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().default(sql`now()`),
+    endedAt: timestamp("ended_at", { withTimezone: true }),
+    lastEventAt: timestamp("last_event_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // Launch drill-down: "sessions bound to this launch".
+    index("agent_sessions_launch_idx").on(table.launchId),
+    // "Live sessions on this machine" attach flow, scoped per vault.
+    index("agent_sessions_owner_status_idx").on(table.vaultId, table.ownerUserId, table.status)
+  ]
+);
+var usageEvents = pgTable(
+  "usage_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    sessionId: text("session_id").notNull(),
+    launchId: text("launch_id"),
+    requestId: text("request_id").notNull(),
+    model: text("model").notNull(),
+    lane: text("lane").notNull(),
+    // subscription | api | bundled_local
+    inputTokens: integer("input_tokens").notNull(),
+    outputTokens: integer("output_tokens").notNull(),
+    cacheReadTokens: integer("cache_read_tokens").notNull(),
+    cacheCreationTokens: integer("cache_creation_tokens").notNull(),
+    cacheCreation5m: integer("cache_creation_5m"),
+    cacheCreation1h: integer("cache_creation_1h"),
+    isSidechain: boolean("is_sidechain").notNull().default(false),
+    at: timestamp("at", { withTimezone: true }).notNull()
+  },
+  (table) => [
+    // Keep-last dedupe key — the ingest route upserts on this so a re-POST of
+    // the same request_id overwrites rather than duplicates.
+    uniqueIndex("usage_events_session_request_idx").on(table.sessionId, table.requestId),
+    // Launch drill-down: "usage rows for this launch, in order".
+    index("usage_events_launch_at_idx").on(table.launchId, table.at)
+  ]
+);
+var streamEvents = pgTable(
+  "stream_events",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    streamId: text("stream_id").notNull(),
+    // "mirror_session" now; "build" | "api" | "council" join later (HS-31Z5).
+    streamKind: text("stream_kind").notNull(),
+    // Producer-assigned dedupe key — stable across retries/transport hot-swaps.
+    eventUuid: text("event_uuid").notNull(),
+    eventType: text("event_type").notNull(),
+    // e.g. "turn" | "status"
+    payload: jsonb("payload").notNull(),
+    at: timestamp("at", { withTimezone: true }).notNull(),
+    // Short-retention TTL fuse — default now()+6h at insert; swept by cron.
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+  },
+  (table) => [
+    // Producer dedupe — replays/hot-swaps land exactly once per (stream, uuid).
+    uniqueIndex("stream_events_stream_uuid_idx").on(table.streamId, table.eventUuid),
+    // Snapshot-on-connect: "rows for this stream, in order, after a cursor".
+    index("stream_events_stream_id_idx").on(table.streamId, table.id)
+  ]
+);
+var jobStreams = pgTable(
+  "job_streams",
+  {
+    jobId: text("job_id").primaryKey(),
+    kind: text("kind").notNull(),
+    // build | api | council
+    // FK-by-convention to launch_intents.id — no hard FK, same reasoning as
+    // agent_sessions.launch_id (intents expire/sweep, the job row must outlive them).
+    launchId: text("launch_id"),
+    provider: text("provider"),
+    // e.g. "deepseek" — the tile's `source`
+    model: text("model"),
+    seat: text("seat"),
+    // routing-table seat name (dev-factory/routing-table.json)
+    machine: text("machine"),
+    status: text("status").notNull().default("queued"),
+    // queued | running | done | failed
+    startedAt: timestamp("started_at", { withTimezone: true }).notNull().default(sql`now()`),
+    endedAt: timestamp("ended_at", { withTimezone: true }),
+    lastEventAt: timestamp("last_event_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // "Live-ish jobs" read for the unioned stream list.
+    index("job_streams_status_idx").on(table.status),
+    // Launch drill-down: "job streams bound to this launch".
+    index("job_streams_launch_idx").on(table.launchId)
+  ]
+);
+var resolutionStatusEnum = pgEnum("resolution_status", [
+  "open",
+  "resolved",
+  "dismissed",
+  "deferred"
+]);
+var resolutionFocusPin = pgTable(
+  "resolution_focus_pin",
+  {
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    itemKey: text("item_key").notNull(),
+    pinnedBy: text("pinned_by").notNull(),
+    pinnedAt: timestamp("pinned_at", { withTimezone: true }).notNull().default(sql`now()`),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.userId] })]
+);
+var resolutionLedger = pgTable(
+  "resolution_ledger",
+  {
+    id: bigserial("id", { mode: "number" }).primaryKey(),
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    // Tenant-isolation scope ([[HS-ZP5H-TASK]] GAP 2) — mirrors `specs.vault_id`.
+    // Additive: the `id` PK is untouched (append-only log, no upsert key).
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    itemKey: text("item_key").notNull(),
+    status: resolutionStatusEnum("status").$type().notNull(),
+    reason: text("reason"),
+    deferUntil: timestamp("defer_until", { withTimezone: true }),
+    at: timestamp("at", { withTimezone: true }).notNull().default(sql`now()`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // Fold-on-read hot path: newest status row per (vault, user, item_key).
+    index("resolution_ledger_user_item_at_idx").on(
+      table.vaultId,
+      table.userId,
+      table.itemKey,
+      table.at.desc()
+    )
+  ]
+);
+var workspaces = pgTable("workspaces", {
+  id: text("id").primaryKey(),
+  accountId: text("account_id").notNull(),
+  displayName: text("display_name").notNull(),
+  githubOrg: text("github_org"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+  /**
+   * Reversible soft-remove flag (Close-is-not-Destroy,
+   * [[HS-NBV9-EKLJ-TASK-archive-restore-and-the-close-is-not]]) — distinct
+   * from `DELETE /api/workspaces/:id` unregister, which drops the row
+   * entirely. An archived workspace stays in Neon/registry.json but is
+   * excluded from the default active list.
+   */
+  archived: boolean("archived").notNull().default(false)
+});
+var vaults = pgTable("vaults", {
+  id: text("id").primaryKey(),
+  workspaceId: text("workspace_id").notNull().references(() => workspaces.id, { onDelete: "cascade" }),
+  accountId: text("account_id").notNull(),
+  displayName: text("display_name").notNull(),
+  repoRootAbs: text("repo_root_abs"),
+  githubRemote: text("github_remote"),
+  schemaVersion: integer("schema_version").notNull().default(1),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`),
+  /** Vault equivalent of `workspaces.archived` — see that column's doc comment. */
+  archived: boolean("archived").notNull().default(false)
+});
+var accountSettings = pgTable("account_settings", {
+  accountId: text("account_id").primaryKey(),
+  activeWorkspaceId: text("active_workspace_id").references(() => workspaces.id, {
+    onDelete: "set null"
+  }),
+  activeVaultId: text("active_vault_id").references(() => vaults.id, { onDelete: "set null" }),
+  // Admin dev/prod mode control (epic HS-Q6M2): the CLOUD rung of the dev-mode
+  // resolution order (env → ~/.heyspex/dev-mode.json → THIS → default prod).
+  // Shape: { mode: "prod"|"dev", reliance: "local"|"cloud", updated_at, source }.
+  // Readers/writers MUST tolerate the column being absent (migration 0050 may
+  // not have run yet on a given database) — catch 42703 and treat as unset.
+  devMode: jsonb("dev_mode"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+});
+var vaultGrants = pgTable(
+  "vault_grants",
+  {
+    vaultId: text("vault_id").notNull().references(() => vaults.id, { onDelete: "cascade" }),
+    accountId: text("account_id").notNull(),
+    access: text("access").notNull().default("read"),
+    grantedBy: text("granted_by").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.vaultId, table.accountId] })]
+);
+var githubInstallations = pgTable(
+  "github_installations",
+  {
+    accountId: text("account_id").notNull(),
+    githubAccountLogin: text("github_account_login").notNull(),
+    installationId: integer("installation_id").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.accountId, table.githubAccountLogin] })]
+);
+var fleetMachines = pgTable(
+  "fleet_machines",
+  {
+    machineKey: text("machine_key").primaryKey(),
+    label: text("label"),
+    gpu: text("gpu"),
+    vramMb: integer("vram_mb"),
+    ramMb: integer("ram_mb"),
+    architecture: text("architecture"),
+    // cuda | rocm | cpu
+    os: text("os"),
+    companionVersion: text("companion_version"),
+    /**
+     * Owning account, stamped from the redeemed join code's issuer at
+     * `POST /api/fleet/join` ([[HS-DOD0-DIAG-fleet-tables-have-no-account-linkage]]).
+     * Nullable: bearer-only `POST /api/fleet/register` registrations and
+     * pre-migration machines have no attributable account ("unattributed" is the
+     * honest state, not a fabricated owner default). The upsert COALESCEs so a
+     * bearer re-register never overwrites a set account_id with null. Prerequisite
+     * for per-account fleet isolation ([[HS-TNTI-EPIC-saas-multi-tenant-isolation]]).
+     */
+    accountId: text("account_id"),
+    /**
+     * Task kinds this machine is willing to run ([[HS-60Z1-EPIC]]). NULL = any kind
+     * (the pre-existing behavior, preserved for machines registered before this
+     * column existed). Eligibility used to be model-only, so a build box could claim
+     * a `research` task it had no way to execute — `claimNextTask` now also filters
+     * on this list when it is set.
+     */
+    eligibleKinds: text("eligible_kinds").array(),
+    lastSeenAt: timestamp("last_seen_at", { withTimezone: true }),
+    registeredAt: timestamp("registered_at", { withTimezone: true }).default(sql`now()`)
+  },
+  (table) => [index("fleet_machines_account_idx").on(table.accountId)]
+);
+var fleetTasks = pgTable(
+  "fleet_tasks",
+  {
+    taskId: text("task_id").primaryKey(),
+    kind: text("kind").notNull(),
+    // build | breakdown | research | ...
+    modelId: text("model_id"),
+    spec: jsonb("spec").notNull(),
+    target: text("target"),
+    budgetMaxSeconds: integer("budget_max_seconds"),
+    status: text("status").notNull().default("queued"),
+    // queued|claimed|running|done|failed|cancelled
+    claimedBy: text("claimed_by").references(() => fleetMachines.machineKey),
+    claimedAt: timestamp("claimed_at", { withTimezone: true }),
+    lastProgressAt: timestamp("last_progress_at", { withTimezone: true }),
+    /**
+     * The fleet-queue lane ([[HS-60Z1-EPIC]]) — a free-form name for a gated resource
+     * whose work waits its turn (`research-firecrawl`, `build-gpu0`, …). Deliberately
+     * NOT folded into `kind`: `kind` is an existing taxonomy (build|breakdown|research)
+     * that the companion's model-eligibility matching already consumes, and overloading
+     * it would change what shipped callers claim. NULL = a plain dispatch task with no
+     * lane, i.e. every task written before this column existed.
+     */
+    lane: text("lane"),
+    /** Who asked for this work (agent id / session). First-class so the queue can be filtered by requester. */
+    requestedBy: text("requested_by"),
+    /**
+     * Stale-claim provenance. The stall sweep resets `claimed_by` to NULL so a healthy
+     * machine can re-claim; without these two columns the identity of the machine that
+     * dropped the task is erased, and "who had it before it went stale" is unanswerable.
+     * The sweep copies claimed_by/claimed_at here before nulling them, so a reclaim is
+     * visible (`reclaimed: true`) rather than silent.
+     */
+    lastClaimant: text("last_claimant"),
+    lastClaimedAt: timestamp("last_claimed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).default(sql`now()`)
+  },
+  (table) => [
+    index("fleet_tasks_status_created_idx").on(table.status, table.createdAt),
+    // Lane-scoped peek / rank / list — the fleet-queue read path ([[HS-60Z1-EPIC]]).
+    index("fleet_tasks_lane_status_created_idx").on(table.lane, table.status, table.createdAt)
+  ]
+);
+var fleetResults = pgTable(
+  "fleet_results",
+  {
+    taskId: text("task_id").references(() => fleetTasks.taskId),
+    idempotencyKey: text("idempotency_key").notNull(),
+    machineKey: text("machine_key").references(() => fleetMachines.machineKey),
+    status: text("status").notNull(),
+    // done | failed
+    reason: text("reason"),
+    result: jsonb("result"),
+    artifacts: jsonb("artifacts"),
+    commitSha: text("commit_sha"),
+    reportedAt: timestamp("reported_at", { withTimezone: true }).default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.taskId, table.idempotencyKey] })]
+);
+var userApiKeys = pgTable(
+  "user_api_keys",
+  {
+    userId: text("user_id").notNull().default(SINGLE_USER_ID),
+    /** Provider id — validated app-side against `API_KEY_PROVIDERS`. */
+    provider: text("provider").notNull(),
+    // Envelope-encryption fields (all base64). See lib/keys/crypto.ts.
+    ciphertext: text("ciphertext").notNull(),
+    iv: text("iv").notNull(),
+    authTag: text("auth_tag").notNull(),
+    wrappedDek: text("wrapped_dek").notNull(),
+    wrapIv: text("wrap_iv").notNull(),
+    wrapAuthTag: text("wrap_auth_tag").notNull(),
+    /** Which KEK version wrapped the data key (rotation selector). */
+    keyVersion: integer("key_version").notNull().default(1),
+    /** Trailing 4 chars of the plaintext — masked-display projection only. */
+    last4: text("last4").notNull(),
+    /** Best-effort verify-on-save result: unverified | valid | invalid. */
+    verificationStatus: text("verification_status").notNull().default("unverified"),
+    verifiedAt: timestamp("verified_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [primaryKey({ columns: [table.userId, table.provider] })]
+);
+var apiKeys = pgTable(
+  "api_keys",
+  {
+    id: text("id").primaryKey(),
+    // opaque key id (uuid), minted at creation — never the raw key
+    keyHash: text("key_hash").notNull(),
+    // SHA-256 hex digest of the raw key; the raw key itself is never stored
+    keyPrefix: text("key_prefix").notNull(),
+    // short non-secret prefix for masked display + lookup
+    scopes: text("scopes").array().notNull(),
+    accountId: text("account_id").notNull().default(SINGLE_USER_ID),
+    status: text("status").notNull().default("active"),
+    // active | expiring | revoked
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true })
+  },
+  (table) => [
+    // Presented-key lookup path: verifyApiKey resolves by prefix, then
+    // compares the hash. One key can never collide with another's prefix.
+    uniqueIndex("api_keys_prefix_uq").on(table.keyPrefix),
+    // Per-account listing + the max-active-keys-per-account enforcement scan.
+    index("api_keys_account_status_idx").on(table.accountId, table.status)
+  ]
+);
+var mcpSessions = pgTable(
+  "mcp_sessions",
+  {
+    id: text("id").primaryKey(),
+    // first 12 hex chars of the token hash — list/revoke/audit reference
+    tokenHash: text("token_hash").notNull(),
+    // SHA-256 hex digest of the raw `hsmcp_...` token
+    userId: text("user_id").notNull(),
+    // Clerk userId (or SINGLE_USER_ID) the token authenticates as
+    label: text("label"),
+    // optional human label ("laptop MCP", "CI runner", …)
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true })
+  },
+  (table) => [
+    // Presented-token lookup: verify hashes the FULL presented token and scans
+    // for a match — this index is for per-account listing, not the verify path
+    // (the verify path has no indexable prefix to look up by; the sessions
+    // table is expected to stay small — one row per paired machine/agent).
+    index("mcp_sessions_user_idx").on(table.userId)
+  ]
+);
+var pairingCodes = pgTable(
+  "pairing_codes",
+  {
+    id: text("id").primaryKey(),
+    // first 8 hex chars of the code hash — audit/revoke reference
+    hash: text("hash").notNull(),
+    // SHA-256 hex digest of the plaintext code
+    userId: text("user_id").notNull(),
+    // Clerk userId (or SINGLE_USER_ID) that minted the code
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    usedAt: timestamp("used_at", { withTimezone: true }),
+    usedBy: text("used_by"),
+    // machineKey that redeemed the code, if supplied
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    note: text("note")
+    // display/audit hint only ("mcp", …) — no effect on redemption
+  },
+  (table) => [index("pairing_codes_user_idx").on(table.userId)]
+);
+var companionSessions = pgTable(
+  "companion_sessions",
+  {
+    id: text("id").primaryKey(),
+    // first 12 hex chars of the token hash — list/revoke/audit reference
+    tokenHash: text("token_hash").notNull(),
+    // SHA-256 hex digest of the raw `hscmp_...` token
+    userId: text("user_id").notNull(),
+    machineKey: text("machine_key"),
+    // machineKey presented at pairing, if any
+    label: text("label"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`),
+    lastSeenAt: timestamp("last_seen_at", { withTimezone: true }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true })
+  },
+  (table) => [index("companion_sessions_user_idx").on(table.userId)]
+);
+var inviteRequests = pgTable(
+  "invite_requests",
+  {
+    id: text("id").primaryKey(),
+    // uuid minted by the webhook receiver
+    email: text("email").notNull(),
+    name: text("name"),
+    /** Plan the requester expects to need: free | pro | team. A planning signal, not a commitment. */
+    tier: text("tier").notNull().default("free"),
+    /** Optional free-text context: what they are building / how they use agents. */
+    building: text("building"),
+    status: text("status").notNull().default("new"),
+    // new | invited | declined
+    /** Clerk invitation id, set when an approval actually issues one. */
+    clerkInvitationId: text("clerk_invitation_id"),
+    /** Account id of the admin who approved/declined — audit trail for the decision. */
+    reviewedBy: text("reviewed_by"),
+    reviewedAt: timestamp("reviewed_at", { withTimezone: true }),
+    /** Intake metadata forwarded from the Worker, for spam triage. */
+    sourceIp: text("source_ip"),
+    userAgent: text("user_agent"),
+    /**
+     * Double opt-in completion. Rows only reach this table AFTER the requester
+     * clicked the confirmation link, so in practice this is always set — it is
+     * stored anyway because "when did they verify?" is part of the consent
+     * evidence, and a future intake path might relax that ordering.
+     */
+    confirmedAt: timestamp("confirmed_at", { withTimezone: true }),
+    /**
+     * The OPTIONAL marketing opt-in — deliberately distinct from the required
+     * privacy agreement, which is a condition of using the form and therefore
+     * not evidence of marketing consent. Only this flag may be used to justify
+     * sending marketing email.
+     */
+    marketingConsent: boolean("marketing_consent").notNull().default(false),
+    /**
+     * Version tag of the exact on-page wording the requester agreed to
+     * (`CONSENT_TEXT_VERSION` in heyspex-com/src/lib/consent-text.ts). Without
+     * this, editing the copy would silently rewrite what every historical row
+     * appears to have consented to.
+     */
+    consentTextVersion: text("consent_text_version"),
+    /** When the marketing site recorded it (NOT when the webhook landed). */
+    requestedAt: timestamp("requested_at", { withTimezone: true }).notNull().default(sql`now()`),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // The upsert key — one row per requester, re-submits update in place.
+    uniqueIndex("invite_requests_email_uq").on(table.email),
+    // The admin surface's default read: pending first, newest first.
+    index("invite_requests_status_requested_idx").on(table.status, table.requestedAt)
+  ]
+);
+var notifications = pgTable(
+  "notifications",
+  {
+    id: text("id").primaryKey(),
+    // uuid
+    /** Recipient. Every read path filters on this — notifications are never global. */
+    accountId: text("account_id").notNull().default(SINGLE_USER_ID),
+    /** Event type, e.g. `invite_request`. Open vocabulary by design (see above). */
+    kind: text("kind").notNull(),
+    title: text("title").notNull(),
+    /** One-line supporting detail shown under the title in the dropdown. */
+    body: text("body"),
+    /** Where clicking the notification should take the user (in-app path). */
+    href: text("href"),
+    /**
+     * Kind-specific structured data (e.g. `{ inviteRequestId, email, tier }`).
+     * Keeps the table stable as new kinds arrive.
+     */
+    payload: jsonb("payload"),
+    /**
+     * Idempotency key for the producing event (e.g. `invite_request:<email>`).
+     * A webhook retry must surface ONE bell item, not one per delivery attempt.
+     */
+    dedupeKey: text("dedupe_key"),
+    readAt: timestamp("read_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // The bell's two queries: unread count, and the recent list — both scoped
+    // to the recipient and ordered newest-first.
+    index("notifications_account_created_idx").on(table.accountId, table.createdAt),
+    // Retry-safe producers: one row per (recipient, event).
+    uniqueIndex("notifications_account_dedupe_uq").on(table.accountId, table.dedupeKey)
+  ]
+);
+var webhookIngestions = pgTable(
+  "webhook_ingestions",
+  {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    repo: text("repo").notNull(),
+    // `owner/repo`, from `repository.full_name`
+    branch: text("branch").notNull(),
+    // from `ref`, `refs/heads/` stripped
+    commitSha: text("commit_sha").notNull(),
+    message: text("message").notNull(),
+    authorName: text("author_name").notNull(),
+    authorEmail: text("author_email").notNull(),
+    path: text("path").notNull(),
+    // changed file's repo-relative path
+    ingestedAt: timestamp("ingested_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // A retried/duplicate delivery for the same (repo, commit, path) must not
+    // record twice — GitHub does redeliver on timeout/5xx.
+    uniqueIndex("webhook_ingestions_repo_commit_path_uq").on(
+      table.repo,
+      table.commitSha,
+      table.path
+    )
+  ]
+);
+var specSettlements = pgTable(
+  "spec_settlements",
+  {
+    id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+    specId: text("spec_id").notNull(),
+    vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+    repo: text("repo").notNull(),
+    // `owner/name`
+    branch: text("branch").notNull(),
+    commitSha: text("commit_sha").notNull(),
+    settledAt: timestamp("settled_at", { withTimezone: true }).notNull().default(sql`now()`)
+  },
+  (table) => [
+    // "latest settlement for this spec" — the read path's only query.
+    index("spec_settlements_spec_settled_idx").on(table.specId, table.settledAt.desc())
+  ]
+);
+
+// spex-console/src/lib/vault-registry/neon-probe.ts
+var NEON_PROBE_TIMEOUT_MS = 1500;
+var SUSPENSION_ELAPSED_FACTOR = 3;
+var SUSPENSION_MIN_OVERSHOOT_MS = 5e3;
+var MAX_SUSPENSION_RETRIES = 2;
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new NeonProbeTimeoutError(label, ms)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    );
+  });
+}
+var NeonProbeTimeoutError = class _NeonProbeTimeoutError extends Error {
+  timeoutMs;
+  constructor(label, timeoutMs) {
+    super(`${label} timed out after ${timeoutMs}ms`);
+    this.name = "NeonProbeTimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, _NeonProbeTimeoutError.prototype);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function emitProbeFailure(options, failure) {
+  try {
+    options?.onFailure?.(failure);
+  } catch {
+  }
+}
+async function runNeonReachabilityProbe(attempt, options = {}, label = "Neon reachability probe") {
+  const timeoutMs = options.timeoutMs ?? NEON_PROBE_TIMEOUT_MS;
+  const backoffMs = options.backoffMs ?? [];
+  const deadlineMs = options.deadlineMs ?? Number.POSITIVE_INFINITY;
+  const attempts = backoffMs.length + 1;
+  let startedAt = Date.now();
+  let suspensions = 0;
+  for (let i = 0; i < attempts; i++) {
+    const attemptStartedAt = Date.now();
+    try {
+      await withTimeout(Promise.resolve().then(attempt), timeoutMs, label);
+      return true;
+    } catch (err) {
+      const elapsedMs = Date.now() - attemptStartedAt;
+      const suspended = elapsedMs >= timeoutMs * SUSPENSION_ELAPSED_FACTOR && elapsedMs - timeoutMs >= SUSPENSION_MIN_OVERSHOOT_MS;
+      if (suspended && suspensions < MAX_SUSPENSION_RETRIES) {
+        suspensions += 1;
+        emitProbeFailure(options, {
+          reason: "suspended",
+          attempt: i + 1,
+          attempts,
+          timeoutMs,
+          elapsedMs,
+          willRetry: true,
+          error: err
+        });
+        startedAt = Date.now();
+        i -= 1;
+        continue;
+      }
+      const isLast = i === attempts - 1;
+      const pastDeadline = Date.now() - startedAt >= deadlineMs;
+      const willRetry = !isLast && !pastDeadline;
+      emitProbeFailure(options, {
+        reason: err instanceof NeonProbeTimeoutError ? "timeout" : "error",
+        attempt: i + 1,
+        attempts,
+        timeoutMs,
+        elapsedMs,
+        willRetry,
+        error: err
+      });
+      if (!willRetry) return false;
+      await sleep(backoffMs[i]);
+    }
+  }
+  return false;
+}
+
+// spex-console/src/lib/vault-registry/repo-identity.ts
+import path from "node:path";
+function normalizeRepoRoot(p) {
+  let resolved = path.resolve(p);
+  while (resolved.length > 1 && (resolved.endsWith("/") || resolved.endsWith("\\"))) {
+    resolved = resolved.slice(0, -1);
+  }
+  return resolved.toLowerCase();
+}
+function repoRootCandidates(p) {
+  const norm = normalizeRepoRoot(p);
+  const candidates = [norm];
+  if (path.basename(norm) === "specs") {
+    const parent = path.dirname(norm);
+    if (parent !== norm) candidates.push(parent);
+  }
+  return candidates;
+}
+function repoRootsEquivalent(a, b) {
+  if (!a || !b) return false;
+  const aCands = repoRootCandidates(a);
+  const bCands = new Set(repoRootCandidates(b));
+  return aCands.some((c) => bCands.has(c));
+}
+function normalizeGithubRemote(remote) {
+  let r = remote.trim().toLowerCase();
+  r = r.replace(/\.git$/, "");
+  const hosted = r.match(/github\.com[/:]([^/\s]+\/[^/\s]+)$/);
+  if (hosted) return hosted[1];
+  return r.replace(/^\/+|\/+$/g, "");
+}
+function githubRemotesEquivalent(a, b) {
+  if (!a || !b) return false;
+  return normalizeGithubRemote(a) === normalizeGithubRemote(b);
+}
+function matchesRepoIdentity(row2, probe) {
+  return repoRootsEquivalent(row2.repoRootAbs, probe.repoRootAbs) || githubRemotesEquivalent(row2.githubRemote, probe.githubRemote);
+}
+
+// spex-console/src/lib/cli/vault-workspace-shared.ts
+var DEFAULT_ACCOUNT_ID = SINGLE_USER_ID;
+function resolveCliAccountId(opts = {}) {
+  const env = opts.env ?? process.env;
+  const fromEnv = env.HS_ACCOUNT_ID?.trim();
+  if (fromEnv) return fromEnv;
+  try {
+    const homeDir = opts.homeDir ?? os.homedir();
+    const readFile2 = opts.readFile ?? ((p) => readFileSync2(p, "utf-8"));
+    const config = readFile2(path2.join(homeDir, ".heyspex", "config.yaml"));
+    const match = config.match(/^account_id:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    if (value && value.length > 0) return value;
+  } catch {
+  }
+  return DEFAULT_ACCOUNT_ID;
+}
+async function cloudHttpRequest(http, method, path5, body) {
+  try {
+    const res = await http.fetchImpl(`${http.consoleUrl}${path5}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...http.token ? { authorization: `Bearer ${http.token}` } : {}
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    let json = null;
+    try {
+      json = await res.json();
+    } catch {
+    }
+    return { ok: res.ok, status: res.status, json };
+  } catch {
+    return { ok: false, status: 0, json: null };
+  }
+}
+function shouldUseCloudHttp(deps) {
+  return deps.db === void 0 && deps.http !== void 0 && !isPostgresConfigured();
+}
+async function upsertWorkspaceHttp(record, http) {
+  const res = await cloudHttpRequest(http, "POST", "/api/workspaces", {
+    id: record.id,
+    display_name: record.displayName,
+    ...record.githubOrg ? { github_org: record.githubOrg } : {}
+  });
+  return res.status === 201 || res.status === 409;
+}
+async function insertWorkspaceStrictHttp(record, http) {
+  const res = await cloudHttpRequest(http, "POST", "/api/workspaces", {
+    id: record.id,
+    display_name: record.displayName,
+    ...record.githubOrg ? { github_org: record.githubOrg } : {}
+  });
+  if (res.status === 201) return "inserted";
+  if (res.status === 409) return "conflict";
+  return "unreachable";
+}
+async function upsertVaultHttp(record, http) {
+  const res = await cloudHttpRequest(http, "POST", "/api/vaults", {
+    id: record.id,
+    workspace_id: record.workspaceId,
+    display_name: record.displayName,
+    repo_root_abs: record.repoRootAbs,
+    schema_version: record.schemaVersion,
+    ...record.githubRemote ? { github_remote: record.githubRemote } : {}
+  });
+  return res.ok;
+}
+async function findVaultByRepoIdentityHttp(probe, http) {
+  if (!probe.githubRemote) return null;
+  const qs = new URLSearchParams({ remote: probe.githubRemote });
+  const res = await cloudHttpRequest(http, "GET", `/api/vaults?${qs.toString()}`);
+  if (!res.ok) return null;
+  const body = res.json;
+  const row2 = body?.vaults?.[0];
+  return row2 ? {
+    id: row2.id,
+    workspaceId: row2.workspace_id,
+    repoRootAbs: row2.repo_root_abs ?? null,
+    githubRemote: row2.github_remote ?? probe.githubRemote,
+    displayName: row2.display_name,
+    schemaVersion: row2.schema_version
+  } : null;
+}
+async function isNeonReachableForWrite(deps) {
+  if (deps.neonReachable !== void 0) return deps.neonReachable;
+  const usingInjectedDb = deps.db !== void 0;
+  if (!usingInjectedDb && !isPostgresConfigured()) {
+    emitProbeFailure(deps.probe, {
+      reason: "not-configured",
+      attempt: 1,
+      attempts: 1,
+      timeoutMs: 0,
+      elapsedMs: 0,
+      willRetry: false,
+      error: new Error(
+        "isPostgresConfigured() is false \u2014 no DATABASE_URL env var and no usable ~/.heyspex/credentials.yaml. Neon was never contacted."
+      )
+    });
+    return false;
+  }
+  return runNeonReachabilityProbe(async () => {
+    const db = deps.db ?? getPostgresDb();
+    await db.execute(sql`select 1`);
+  }, deps.probe);
+}
+async function upsertWorkspaceNeon(record, accountId, deps = {}) {
+  if (shouldUseCloudHttp(deps)) return upsertWorkspaceHttp(record, deps.http);
+  if (!await isNeonReachableForWrite(deps)) return false;
+  try {
+    const db = deps.db ?? getPostgresDb();
+    await db.insert(workspaces).values({
+      id: record.id,
+      accountId,
+      displayName: record.displayName,
+      ...record.githubOrg ? { githubOrg: record.githubOrg } : {}
+    }).onConflictDoUpdate({
+      target: workspaces.id,
+      set: {
+        displayName: record.displayName,
+        ...record.githubOrg ? { githubOrg: record.githubOrg } : {}
+      }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function insertWorkspaceNeonStrict(record, accountId, deps = {}) {
+  if (shouldUseCloudHttp(deps)) return insertWorkspaceStrictHttp(record, deps.http);
+  if (!await isNeonReachableForWrite(deps)) return "unreachable";
+  try {
+    const db = deps.db ?? getPostgresDb();
+    const rows = await db.insert(workspaces).values({
+      id: record.id,
+      accountId,
+      displayName: record.displayName,
+      ...record.githubOrg ? { githubOrg: record.githubOrg } : {}
+    }).onConflictDoNothing({ target: workspaces.id }).returning({ id: workspaces.id });
+    return rows.length > 0 ? "inserted" : "conflict";
+  } catch {
+    return "unreachable";
+  }
+}
+async function upsertVaultNeon(record, accountId, deps = {}) {
+  if (shouldUseCloudHttp(deps)) return upsertVaultHttp(record, deps.http);
+  if (!await isNeonReachableForWrite(deps)) return false;
+  try {
+    const db = deps.db ?? getPostgresDb();
+    await db.insert(vaults).values({
+      id: record.id,
+      workspaceId: record.workspaceId,
+      accountId,
+      displayName: record.displayName,
+      repoRootAbs: record.repoRootAbs,
+      schemaVersion: record.schemaVersion,
+      ...record.githubRemote ? { githubRemote: record.githubRemote } : {}
+    }).onConflictDoUpdate({
+      target: vaults.id,
+      set: {
+        workspaceId: record.workspaceId,
+        displayName: record.displayName,
+        repoRootAbs: record.repoRootAbs,
+        schemaVersion: record.schemaVersion,
+        updatedAt: /* @__PURE__ */ new Date(),
+        ...record.githubRemote ? { githubRemote: record.githubRemote } : {}
+      }
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findVaultByRepoIdentityNeon(accountId, probe, deps = {}) {
+  if (!probe.repoRootAbs && !probe.githubRemote) return null;
+  if (shouldUseCloudHttp(deps)) return findVaultByRepoIdentityHttp(probe, deps.http);
+  if (!await isNeonReachableForWrite(deps)) return null;
+  try {
+    const db = deps.db ?? getPostgresDb();
+    const rows = await db.select({
+      id: vaults.id,
+      workspaceId: vaults.workspaceId,
+      repoRootAbs: vaults.repoRootAbs,
+      githubRemote: vaults.githubRemote,
+      displayName: vaults.displayName,
+      schemaVersion: vaults.schemaVersion
+    }).from(vaults).where(eq(vaults.accountId, accountId));
+    const row2 = rows.find(
+      (r) => matchesRepoIdentity({ repoRootAbs: r.repoRootAbs, githubRemote: r.githubRemote }, probe)
+    );
+    return row2 ? {
+      id: row2.id,
+      workspaceId: row2.workspaceId,
+      repoRootAbs: row2.repoRootAbs,
+      githubRemote: row2.githubRemote,
+      displayName: row2.displayName,
+      schemaVersion: row2.schemaVersion
+    } : null;
+  } catch {
+    return null;
+  }
+}
+
+// spex-console/src/lib/vault-registry/workspace-create.ts
+var MAX_DISPLAY_NAME_LEN = 60;
+var MAX_SLUG_LEN = 40;
+var MAX_SLUG_SUFFIX = 9;
+function isValidExplicitId(id) {
+  if (typeof id !== "string" || id.trim() === "") return false;
+  if (id.includes("/") || id.includes("\\")) return false;
+  if (id === "." || id === "..") return false;
+  return true;
+}
+function truncateSlugAtWordBoundary(slug, maxLen) {
+  if (slug.length <= maxLen) return slug;
+  const cut = slug.slice(0, maxLen);
+  const lastDash = cut.lastIndexOf("-");
+  return lastDash > 0 ? cut.slice(0, lastDash) : cut.replace(/-$/, "");
+}
+function deriveWorkspaceSlug(displayName) {
+  const slug = displayName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return truncateSlugAtWordBoundary(slug || "workspace", MAX_SLUG_LEN);
+}
+function derivedCandidates(trimmedName) {
+  const base = deriveWorkspaceSlug(trimmedName);
+  return {
+    base,
+    candidates: [
+      base,
+      ...Array.from({ length: MAX_SLUG_SUFFIX - 1 }, (_, i) => `${base}-${i + 2}`)
+    ]
+  };
+}
+function exhaustedSlugError(trimmedName, base) {
+  return {
+    ok: false,
+    code: "duplicate_workspace",
+    message: `could not find a free slug for "${trimmedName}" -- ${base} through ${base}-${MAX_SLUG_SUFFIX} are all taken`
+  };
+}
+function createOffline(input, trimmedName, now, deps) {
+  const existingIds = new Set(loadVaultRegistry(deps.registryOpts).workspaces.map((w) => w.id));
+  let id;
+  if (input.id !== void 0) {
+    if (existingIds.has(input.id)) {
+      return {
+        ok: false,
+        code: "duplicate_workspace",
+        message: `workspace "${input.id}" already exists`
+      };
+    }
+    id = input.id;
+  } else {
+    const { base, candidates } = derivedCandidates(trimmedName);
+    const free = candidates.find((candidate) => !existingIds.has(candidate));
+    if (!free) return exhaustedSlugError(trimmedName, base);
+    id = free;
+  }
+  registerWorkspace({ id, display_name: trimmedName, created_at: now }, deps.registryOpts);
+  return {
+    ok: true,
+    workspace: { id, display_name: trimmedName, neon_written: false, registry_written: true }
+  };
+}
+async function createWorkspace(input, deps = {}) {
+  const trimmedName = input.displayName.trim();
+  if (trimmedName.length < 1 || trimmedName.length > MAX_DISPLAY_NAME_LEN) {
+    return {
+      ok: false,
+      code: "invalid_display_name",
+      message: `display name must be 1-${MAX_DISPLAY_NAME_LEN} characters (trimmed)`
+    };
+  }
+  const now = (deps.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
+  if (deps.allowIdUpsert && input.id !== void 0) {
+    if (!isValidExplicitId(input.id)) {
+      return {
+        ok: false,
+        code: "invalid_workspace_id",
+        message: `invalid workspace id "${input.id}" -- must be non-empty with no path separators`
+      };
+    }
+    const id = input.id;
+    registerWorkspace({ id, display_name: trimmedName, created_at: now }, deps.registryOpts);
+    const neonWritten = await upsertWorkspaceNeon(
+      { id, displayName: trimmedName },
+      input.accountId,
+      deps.neon
+    );
+    return {
+      ok: true,
+      workspace: {
+        id,
+        display_name: trimmedName,
+        neon_written: neonWritten,
+        registry_written: true
+      }
+    };
+  }
+  if (input.id !== void 0 && !isValidExplicitId(input.id)) {
+    return {
+      ok: false,
+      code: "invalid_workspace_id",
+      message: `invalid workspace id "${input.id}" -- must be non-empty with no path separators`
+    };
+  }
+  const { base, candidates } = input.id !== void 0 ? { base: input.id, candidates: [input.id] } : derivedCandidates(trimmedName);
+  for (const candidate of candidates) {
+    const result = await insertWorkspaceNeonStrict(
+      { id: candidate, displayName: trimmedName },
+      input.accountId,
+      deps.neon ?? {}
+    );
+    if (result === "inserted") {
+      registerWorkspace(
+        { id: candidate, display_name: trimmedName, created_at: now },
+        deps.registryOpts
+      );
+      return {
+        ok: true,
+        workspace: {
+          id: candidate,
+          display_name: trimmedName,
+          neon_written: true,
+          registry_written: true
+        }
+      };
+    }
+    if (result === "unreachable") {
+      return createOffline(input, trimmedName, now, deps);
+    }
+    if (input.id !== void 0) {
+      return {
+        ok: false,
+        code: "duplicate_workspace",
+        message: `workspace "${input.id}" already exists`
+      };
+    }
+  }
+  return exhaustedSlugError(trimmedName, base);
+}
+
+// scripts/lib/console-url-resolver.mjs
+import { readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function readCredentialsConsoleUrl({ homeDir = homedir2() } = {}) {
+  try {
+    const raw = readFileSync3(join2(homeDir, ".heyspex", "credentials.yaml"), "utf8");
+    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
+  } catch {
+    return null;
+  }
+}
+function readDiscoveryFileConsoleUrl(repoRoot) {
+  if (!repoRoot) return null;
+  for (const name of [
+    "console-url",
+    "cockpit-url"
+    /* legacy-cockpit */
+  ]) {
+    try {
+      const discovery = readFileSync3(join2(repoRoot, ".heyspex", name), "utf8").trim();
+      if (discovery.length > 0) return trimTrailingSlash(discovery);
+    } catch {
+    }
+  }
+  return null;
+}
+var ConsoleUrlUnresolvedError = class extends Error {
+  constructor() {
+    super(
+      `resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`
+    );
+    this.name = "ConsoleUrlUnresolvedError";
+  }
+};
+function resolveConsoleUrl({
+  repoRoot,
+  env = process.env,
+  homeDir = homedir2(),
+  strict = false
+} = {}) {
+  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (envUrl) return trimTrailingSlash(envUrl);
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
+  if (credentialsUrl) return credentialsUrl;
+  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
+  if (discoveryUrl) return discoveryUrl;
+  if (strict) throw new ConsoleUrlUnresolvedError();
+  return DEFAULT_CONSOLE_URL;
+}
+
+// spex-console/src/lib/cli/init.ts
+import { randomUUID } from "node:crypto";
+
+// spex-console/src/lib/cli/control-shared.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+var EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — unknown subcommand/flag, or a missing required argument. */
+  USAGE: 1,
+  /** Claim race lost — the spec is already claimed by another agent (409). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  FORBIDDEN: 15
+};
+function readPairedToken() {
+  try {
+    const raw = readFileSync4(join3(homedir3(), ".heyspex", "credentials.yaml"), "utf-8");
+    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
+    return match?.[1];
+  } catch {
+    return void 0;
+  }
+}
+
+// spex-console/src/lib/cli/init.ts
+var HEYSPEX_YAML_SCHEMA_VERSION = 2;
+var DEFAULT_CONSOLE_URL2 = resolveConsoleUrl();
+function mintVaultId() {
+  return randomUUID();
+}
+function parseVaultId(content) {
+  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
+}
+function appendVaultIdLine(content, vaultId) {
+  const trimmed = content.replace(/\n+$/, "");
+  return `${trimmed}
+vault_id: ${vaultId}
+`;
+}
+function renderHeyspexYaml(args) {
+  return [
+    `schema_version: ${HEYSPEX_YAML_SCHEMA_VERSION}`,
+    `console_url: ${args.consoleUrl}`,
+    `vault_root: ${args.vaultRoot}`,
+    `vault_id: ${args.vaultId}`,
+    ""
+  ].join("\n");
+}
+function readExistingContent(deps, markerPath) {
+  if (!deps.readFile) return null;
+  try {
+    return deps.readFile(markerPath);
+  } catch {
+    return null;
+  }
+}
+function runInit(args, deps) {
+  const markerPath = deps.joinPath(deps.repoRoot, "heyspex.yaml");
+  const exists = deps.fileExists(markerPath);
+  const existingContent = exists ? readExistingContent(deps, markerPath) : null;
+  const existingVaultId = existingContent ? parseVaultId(existingContent) : null;
+  if (exists && !args.force) {
+    if (existingVaultId) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: {
+          ok: true,
+          created: false,
+          path: markerPath,
+          reason: "already_initialized",
+          vault_id: existingVaultId
+        },
+        isError: false
+      };
+    }
+    if (existingContent === null) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: { ok: true, created: false, path: markerPath, reason: "already_initialized" },
+        isError: false
+      };
+    }
+    const mintedId = args.adoptedVaultId ?? mintVaultId();
+    const updatedContent = appendVaultIdLine(existingContent, mintedId);
+    try {
+      deps.writeFile(markerPath, updatedContent);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: `failed to write heyspex.yaml: ${message}`,
+        payload: { ok: false, error: "write_failed", path: markerPath, message },
+        isError: true
+      };
+    }
+    return {
+      code: EXIT.OK,
+      message: `Added vault_id to existing heyspex.yaml at ${markerPath} (schema_version unchanged).`,
+      payload: {
+        ok: true,
+        created: false,
+        backfilled: true,
+        path: markerPath,
+        vault_id: mintedId
+      },
+      isError: false
+    };
+  }
+  const vaultId = existingVaultId ?? args.adoptedVaultId ?? mintVaultId();
+  const content = renderHeyspexYaml({ ...args, vaultId });
+  try {
+    deps.writeFile(markerPath, content);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      code: EXIT.WRITE_FAILED,
+      message: `failed to write heyspex.yaml: ${message}`,
+      payload: { ok: false, error: "write_failed", path: markerPath, message },
+      isError: true
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `${exists ? "Overwrote" : "Wrote"} ${markerPath} (schema_version ${HEYSPEX_YAML_SCHEMA_VERSION}).`,
+    payload: {
+      ok: true,
+      created: true,
+      overwrote: exists,
+      path: markerPath,
+      schema_version: HEYSPEX_YAML_SCHEMA_VERSION,
+      console_url: args.consoleUrl,
+      vault_root: args.vaultRoot,
+      vault_id: vaultId
+    },
+    isError: false
+  };
+}
+var HELP = [
+  "Usage:",
+  "  hs init [--console-url <url>] [--vault-root <path>] [--force] [--json]",
+  "  hs init --customer-vault <dir> [--console-url <url>] [--principles <all|none|a,b>]",
+  "                          [--vault-name <name>] [--no-git] [--json]",
+  "",
+  "Write the top-level heyspex.yaml vault marker (schema_version, console_url,",
+  "vault_root, vault_id) \u2014 the committed file the console / web companion read",
+  "to bootstrap a vault. Idempotent: an existing marker is left untouched unless",
+  "--force, EXCEPT a missing vault_id is backfilled in place either way (backward",
+  "compatible \u2014 no schema_version bump). vault_id is reused exactly when already",
+  "present; a fresh one is minted only when absent.",
+  "Does not modify .heyspex/config.yaml or its templates (ADR-0009).",
+  "",
+  "--customer-vault <dir> scaffolds a REAL customer vault at <dir> instead: the",
+  "specs/ folder tree, heyspex.yaml, and every row of the template shipping",
+  "manifest (spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
+  "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
+  "plus a generated CLAUDE.md, the kept-principles index, and (unless --no-git)",
+  "one initial `git init` + commit pinning the template version. Refuses a",
+  "non-empty <dir> with a plain error. See init.customer-vault.ts.",
+  "",
+  "Flags:",
+  "  --console-url <url>  console_url value (default: $HEYSPEX_CONSOLE_URL or",
+  "                       https://console.heyspex.local).",
+  "  --vault-root <path>  vault_root value (default: specs/).",
+  "  --customer-vault <dir> Scaffold a new customer vault at <dir> (see above).",
+  "  --principles <all|none|a,b> Which universal principle docs to ship",
+  "                       (--customer-vault only). Omitted + a TTY: interactive",
+  "                       keep/skip prompt per principle. Omitted + no TTY: all.",
+  "  --vault-name <name>  Display name for the scaffolded vault (--customer-vault",
+  "                       only; default: <dir>'s basename).",
+  "  --no-git             Skip git init + the initial commit (--customer-vault only).",
+  "  --force              Overwrite an existing heyspex.yaml.",
+  "  --json               Emit a machine-readable JSON result.",
+  "  --help, -h           Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/connect-checks.ts
+var PLUGIN_SURFACE_DIRS = [
+  [".claude", "commands"],
+  [".cursor", "commands"],
+  [".cursor", "skills"],
+  [".commandcode", "skills"],
+  [".agents", "skills"]
+];
+function row(id, label, present, detail) {
+  return {
+    id,
+    label,
+    status: present ? "present" : "missing",
+    ...detail ? { detail } : {}
+  };
+}
+function readIfExists(deps, path5) {
+  return deps.fileExists(path5) ? deps.readFile(path5) : null;
+}
+var PRE_COMMIT_HOOK_MARKER = "run-pre-commit-checks.mjs";
+function hasHeyspexMcpEntry(raw) {
+  if (!raw) return false;
+  try {
+    const parsed = JSON.parse(raw);
+    return Boolean(parsed.mcpServers && Object.hasOwn(parsed.mcpServers, "heyspex"));
+  } catch {
+    return false;
+  }
+}
+function runConnectChecks(repoRoot, deps) {
+  const checks = [];
+  const yamlPath = deps.joinPath(repoRoot, "heyspex.yaml");
+  const yamlContent = readIfExists(deps, yamlPath);
+  const vaultId = yamlContent ? parseVaultId(yamlContent) : null;
+  checks.push(
+    row(
+      "heyspex_yaml",
+      "heyspex.yaml vault marker",
+      yamlContent !== null,
+      vaultId ? `vault_id: ${vaultId}` : void 0
+    )
+  );
+  const specsDir = deps.joinPath(repoRoot, "specs");
+  checks.push(row("specs_dir", "specs/ directory", deps.fileExists(specsDir)));
+  const registry = loadVaultRegistry(deps.registryOpts);
+  const vaultRecord = registry.vaults.find((v) => v.repo_root_abs === repoRoot);
+  checks.push(
+    row(
+      "vault_registered",
+      "vault registered in ~/.heyspex/registry.json",
+      Boolean(vaultRecord),
+      vaultRecord ? `id: ${vaultRecord.id}` : void 0
+    )
+  );
+  const workspaceRecord = vaultRecord ? registry.workspaces.find((w) => w.id === vaultRecord.workspace_id) : void 0;
+  checks.push(
+    row(
+      "workspace_registered",
+      "workspace registered in ~/.heyspex/registry.json",
+      Boolean(workspaceRecord),
+      workspaceRecord ? `id: ${workspaceRecord.id}` : vaultRecord ? `vault's workspace "${vaultRecord.workspace_id}" not found in registry` : "no vault registered for this repo"
+    )
+  );
+  const claudeMcpPath = deps.joinPath(repoRoot, ".mcp.json");
+  const cursorMcpPath = deps.joinPath(repoRoot, ".cursor", "mcp.json");
+  const claudeMcp = hasHeyspexMcpEntry(readIfExists(deps, claudeMcpPath));
+  const cursorMcp = hasHeyspexMcpEntry(readIfExists(deps, cursorMcpPath));
+  const mcpFound = [claudeMcp ? ".mcp.json" : null, cursorMcp ? ".cursor/mcp.json" : null].filter(
+    (v) => v !== null
+  );
+  checks.push(
+    row(
+      "mcp_entry",
+      "MCP server entry (Claude Code / Cursor)",
+      claudeMcp || cursorMcp,
+      mcpFound.length > 0 ? mcpFound.join(", ") : void 0
+    )
+  );
+  const presentPluginDirs = PLUGIN_SURFACE_DIRS.map(
+    (rel) => deps.joinPath(repoRoot, ...rel)
+  ).filter((p) => deps.fileExists(p));
+  checks.push(
+    row(
+      "plugin_surface",
+      "plugin surface trees (.claude/.cursor/.commandcode/.agents commands+skills)",
+      presentPluginDirs.length > 0,
+      presentPluginDirs.length > 0 ? presentPluginDirs.join(", ") : void 0
+    )
+  );
+  const preCommitHookPath = deps.joinPath(repoRoot, ".git", "hooks", "pre-commit");
+  const preCommitHookContent = readIfExists(deps, preCommitHookPath);
+  const gitHooksPresent = preCommitHookContent !== null && preCommitHookContent.includes(PRE_COMMIT_HOOK_MARKER);
+  checks.push(
+    row(
+      "git_hooks",
+      "git hooks (pre-commit)",
+      gitHooksPresent,
+      preCommitHookContent !== null && !gitHooksPresent ? "pre-commit exists but is not HeySpex-managed (no marker)" : void 0
+    )
+  );
+  const registryVaultId = vaultRecord?.id ?? null;
+  const idsAgree = Boolean(vaultId) && Boolean(registryVaultId) && vaultId === registryVaultId;
+  checks.push(
+    row(
+      "id_agreement",
+      "heyspex.yaml vault_id matches the registered vault id",
+      idsAgree,
+      vaultId || registryVaultId ? `marker: ${vaultId ?? "(none)"}, registry: ${registryVaultId ?? "(none)"}` : void 0
+    )
+  );
+  const connected = checks.every((c) => c.status === "present");
+  return { repo_root: repoRoot, connected, checks };
+}
+
+// spex-console/src/lib/cli/install.ts
+var MCP_REL = ["vendor", "heyspex-mcp", "cli.mjs"];
+function mcpCliPath(platformRoot, joinPath) {
+  return joinPath(platformRoot, ...MCP_REL);
+}
+function renderCursorMcpJson(cliAbsPath) {
+  return {
+    mcpServers: {
+      heyspex: {
+        type: "stdio",
+        command: "node",
+        args: [cliAbsPath],
+        env: {
+          HEYSPEX_VAULT_ROOT: "${workspaceFolder}"
+        }
+      }
+    }
+  };
+}
+function renderClaudeMcpJson(cliAbsPath) {
+  return {
+    mcpServers: {
+      heyspex: {
+        type: "stdio",
+        command: "node",
+        args: [cliAbsPath],
+        env: {
+          HEYSPEX_VAULT_ROOT: "${CLAUDE_PROJECT_DIR:-.}"
+        }
+      }
+    }
+  };
+}
+var PLUGIN_MARKETPLACE_NAME = "heyspex-marketplace";
+var PLUGIN_INSTALL_SPEC = `heyspex@${PLUGIN_MARKETPLACE_NAME}`;
+function resolvePluginSpec(platformRoot, deps) {
+  const fallback = {
+    marketplaceName: PLUGIN_MARKETPLACE_NAME,
+    pluginName: "heyspex",
+    spec: PLUGIN_INSTALL_SPEC
+  };
+  const raw = deps.readFile(pluginMarketplaceManifestPath(platformRoot, deps.joinPath));
+  if (!raw) return fallback;
+  try {
+    const parsed = JSON.parse(raw);
+    const marketplaceName = typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : fallback.marketplaceName;
+    const firstNamed = Array.isArray(parsed.plugins) ? parsed.plugins.find((p) => typeof p?.name === "string" && p.name.trim()) : void 0;
+    const pluginName = firstNamed ? firstNamed.name.trim() : fallback.pluginName;
+    return { marketplaceName, pluginName, spec: `${pluginName}@${marketplaceName}` };
+  } catch {
+    return fallback;
+  }
+}
+function pluginMarketplaceManifestPath(platformRoot, joinPath) {
+  return joinPath(platformRoot, ".claude-plugin", "marketplace.json");
+}
+var INSTALL_HELP = [
+  "Usage:",
+  "  hs install [--target <dir>] [--platform <dir>] [--force] [--dry-run] [--json]",
+  "             [--no-cursor] [--no-claude] [--claude-apply]",
+  "             [--plugin | --plugin-apply] [--plugin-scope user|project|local]",
+  "             [--no-statusline]",
+  "             [--cc | --command-code] [--register-vault [--workspace <id>]]",
+  "",
+  "Bootstrap a project vault for HeySpex agent tooling:",
+  "  \u2022 specs/ + heyspex.yaml (via hs init)",
+  "  \u2022 .cursor/mcp.json  \u2014 Cursor MCP (gitignored, machine-local path to platform MCP)",
+  "  \u2022 .mcp.json         \u2014 Claude Code project MCP (absolute platform path)",
+  "  \u2022 CLAUDE.md / AGENTS.md \u2014 thin agent contract pointing at the HeySpex MCP server",
+  "",
+  "Conflict scan: every install checks the target repo against the known-conflict",
+  "registry (beads, workflow-pm, bd hooks, \u2026). See:",
+  "  specs/protocols/customer-vault-local-install-protocol.md",
+  "",
+  "Run from the HeySpex platform repo, or pass --platform to its checkout.",
+  "Target defaults to the current directory.",
+  "",
+  "Flags:",
+  "  --target <dir>     Project repo to bootstrap (default: cwd).",
+  "  --platform <dir>   HeySpex platform checkout (default: HS_INSTALL_PLATFORM or dispatcher root).",
+  "  --claude-apply     Run `claude mcp add --scope project` after writing files.",
+  "  --plugin           Print the Claude Code plugin registration block (self-hosted",
+  "                     marketplace at the platform root \u2014 HS-QTBK prototype).",
+  "  --plugin-apply     Run `claude plugin marketplace add` + `claude plugin install`",
+  "                     after writing files. Marketplace + plugin names are read from",
+  `                     the platform's .claude-plugin/marketplace.json (fallback: ${PLUGIN_INSTALL_SPEC}).`,
+  "  --plugin-scope <s> Plugin install scope: user, project (default), or local.",
+  "                     Implies --plugin.",
+  "  --no-statusline    Skip the branded statusline (statusLine entry in the target's",
+  "                     .claude/settings.json + machine-level glyph install).",
+  "  --cc, --command-code  Print `cmdc mcp add` PowerShell one-liner for Command Code.",
+  "  --register-vault   Register this repo's vault into ~/.heyspex/registry.json during install.",
+  "  --workspace <id>   With --register-vault: ensure this workspace exists, make it active,",
+  '                     and associate the vault with it (default workspace: "default").',
+  "  --no-cursor        Skip .cursor/mcp.json.",
+  "  --no-claude        Skip .mcp.json and Claude instructions.",
+  "  --force            Overwrite existing MCP manifests and heyspex.yaml.",
+  "  --dry-run          Print the plan without writing.",
+  "  --skip-conflict-check  Skip the known-conflict registry scan.",
+  "  --json             Machine-readable result.",
+  "  --help, -h         Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/connect.ts
+function cloudWriteDetail(written, neon) {
+  if (written) return " (registry + cloud)";
+  const url = neon?.http?.consoleUrl;
+  return url ? ` (registry.json only \u2014 cloud unreachable at ${url})` : " (registry.json only \u2014 cloud unreachable)";
+}
+async function safeAdoptVaultByRepoIdentity(accountId, probe, neon) {
+  try {
+    return await findVaultByRepoIdentityNeon(accountId, probe, neon);
+  } catch {
+    return null;
+  }
+}
+function parseConnectArgs(argv) {
+  let check = false;
+  let dryRun = false;
+  let json = false;
+  let fleet = false;
+  let noDoctor = false;
+  let workspace;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--check") check = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--json") json = true;
+    else if (arg === "--fleet") fleet = true;
+    else if (arg === "--no-doctor") noDoctor = true;
+    else if (arg === "--workspace" || arg.startsWith("--workspace=")) {
+      const v = arg === "--workspace" ? argv[++i] : arg.slice("--workspace=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--workspace requires a value" } };
+      }
+      workspace = v;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (check) {
+    if (dryRun) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: "--check is read-only and does not take --dry-run (--check never writes)."
+        }
+      };
+    }
+    if (fleet) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: "--check is read-only and does not take --fleet (--check never writes)."
+        }
+      };
+    }
+    if (noDoctor) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: "--check is read-only and does not take --no-doctor (--check never writes)."
+        }
+      };
+    }
+    if (workspace !== void 0) {
+      return {
+        error: {
+          code: EXIT.USAGE,
+          message: "--check is read-only and does not take --workspace (--check never writes)."
+        }
+      };
+    }
+    return { args: { sub: "check", json } };
+  }
+  return {
+    args: {
+      sub: "run",
+      json,
+      dryRun,
+      fleet,
+      noDoctor,
+      ...workspace !== void 0 ? { workspace } : {}
+    }
+  };
+}
+function formatReport(report) {
+  const lines = [
+    `hs connect --check \u2014 ${report.repo_root}`,
+    "",
+    ...report.checks.map(
+      (c) => `  [${c.status === "present" ? "x" : " "}] ${c.label}${c.detail ? ` (${c.detail})` : ""}`
+    ),
+    "",
+    report.connected ? "Connected." : "Not connected \u2014 run `hs connect` to wire this repo up to HeySpex."
+  ];
+  return lines.join("\n");
+}
+function resolveConnectCwd(env, fallbackCwd) {
+  const invokedCwd = env.HS_INVOKED_CWD?.trim();
+  return invokedCwd ? invokedCwd : fallbackCwd;
+}
+function detectRepoRoot(startDir, deps) {
+  let dir = startDir;
+  for (let i = 0; i < 512; i++) {
+    if (deps.fileExists(deps.joinPath(dir, ".git"))) return dir;
+    const parent = deps.joinPath(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return startDir;
+}
+function detectGitRemote(repoRoot, deps) {
+  const configPath = deps.joinPath(repoRoot, ".git", "config");
+  const raw = deps.fileExists(configPath) ? deps.readFile(configPath) : null;
+  if (!raw) return null;
+  const match = raw.match(/\[remote\s+"origin"\][^[]*?\burl\s*=\s*(\S+)/);
+  return match ? match[1].trim() : null;
+}
+var CANONICAL_VAULT_SUBFOLDERS = [
+  "tasks",
+  "epics",
+  "research",
+  "memory",
+  "captures",
+  "protocols",
+  "milestones"
+];
+function bareSpecsDirWarning(specsDir, deps) {
+  let entries = [];
+  try {
+    entries = readdirSync(specsDir);
+  } catch {
+    return null;
+  }
+  if (entries.length === 0) return null;
+  const vaultShaped = CANONICAL_VAULT_SUBFOLDERS.some(
+    (sub) => deps.fileExists(deps.joinPath(specsDir, sub))
+  );
+  if (vaultShaped) return null;
+  return "specs/ exists but does not look like a HeySpex vault (no tasks/epics/... folders) - continuing, this folder becomes the repo's vault";
+}
+function slugFromPath(deps, p) {
+  return deps.basename(p).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function summarizeDoctorReport(report, ok, exitCode) {
+  if (!report) {
+    return `doctor exited ${exitCode ?? "?"} (no parseable --json output)`;
+  }
+  const results = Array.isArray(report.results) ? report.results : [];
+  const failedCount = results.filter((r) => r.status === "fail").length;
+  const warnCount = results.filter((r) => r.status === "warn").length;
+  const mode = typeof report.mode === "string" ? report.mode : void 0;
+  const modeSuffix = mode ? ` (mode: ${mode})` : "";
+  return ok ? `all required surfaces wired up${warnCount ? ` \u2014 ${warnCount} optional warning${warnCount === 1 ? "" : "s"}` : ""}${modeSuffix}` : `${failedCount} required surface${failedCount === 1 ? "" : "s"} not ready${modeSuffix}`;
+}
+async function runConnectFullRun(args, deps) {
+  const repoRoot = detectRepoRoot(deps.cwd ?? deps.repoRoot, deps);
+  const gitRemote = detectGitRemote(repoRoot, deps);
+  const report = runConnectChecks(repoRoot, deps);
+  const isPresent = (id) => report.checks.find((c) => c.id === id)?.status === "present";
+  const steps = [];
+  let failedStep;
+  let failMessage = "";
+  const warnings = [];
+  const registryBefore = loadVaultRegistry(deps.registryOpts);
+  const existingVault = registryBefore.vaults.find((v) => v.repo_root_abs === repoRoot);
+  const accountId = deps.accountId ?? resolveCliAccountId();
+  const specsDir = deps.joinPath(repoRoot, "specs");
+  if (isPresent("specs_dir")) {
+    if (!isPresent("heyspex_yaml")) {
+      const warning = bareSpecsDirWarning(specsDir, deps);
+      if (warning) warnings.push(warning);
+    }
+    steps.push({
+      id: "specs_dir",
+      label: "specs/ directory",
+      status: "skipped",
+      detail: "already exists"
+    });
+  } else if (args.dryRun) {
+    steps.push({
+      id: "specs_dir",
+      label: "specs/ directory",
+      status: "run",
+      detail: `would create ${specsDir}`
+    });
+  } else {
+    try {
+      deps.mkdir(specsDir);
+      steps.push({
+        id: "specs_dir",
+        label: "specs/ directory",
+        status: "run",
+        detail: `created ${specsDir}`
+      });
+    } catch (err) {
+      failedStep = "specs_dir";
+      failMessage = err instanceof Error ? err.message : String(err);
+      steps.push({
+        id: "specs_dir",
+        label: "specs/ directory",
+        status: "failed",
+        detail: failMessage
+      });
+    }
+  }
+  const yamlPath = deps.joinPath(repoRoot, "heyspex.yaml");
+  let vaultId;
+  if (!failedStep) {
+    if (isPresent("heyspex_yaml")) {
+      const content = deps.fileExists(yamlPath) ? deps.readFile(yamlPath) : null;
+      vaultId = content ? parseVaultId(content) ?? void 0 : void 0;
+      steps.push({
+        id: "heyspex_yaml",
+        label: "heyspex.yaml vault marker",
+        status: "skipped",
+        detail: "already initialized"
+      });
+    } else if (args.dryRun) {
+      steps.push({
+        id: "heyspex_yaml",
+        label: "heyspex.yaml vault marker",
+        status: "run",
+        detail: `would write ${yamlPath}`
+      });
+    } else {
+      let adoptedVaultId = existingVault?.id;
+      if (!adoptedVaultId) {
+        const probe = {};
+        if (repoRoot) probe.repoRootAbs = repoRoot;
+        if (gitRemote) probe.githubRemote = gitRemote;
+        if (probe.repoRootAbs || probe.githubRemote) {
+          const neonMatch = await safeAdoptVaultByRepoIdentity(accountId, probe, deps.neon);
+          if (neonMatch) adoptedVaultId = neonMatch.id;
+        }
+      }
+      const consoleUrl = resolveConsoleUrl({ repoRoot });
+      const initDeps = {
+        repoRoot,
+        fileExists: deps.fileExists,
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        joinPath: deps.joinPath
+      };
+      const initResult = runInit(
+        { consoleUrl, vaultRoot: "specs/", force: false, json: false, adoptedVaultId },
+        initDeps
+      );
+      if (initResult.isError) {
+        failedStep = "heyspex_yaml";
+        failMessage = initResult.message;
+        steps.push({
+          id: "heyspex_yaml",
+          label: "heyspex.yaml vault marker",
+          status: "failed",
+          detail: failMessage
+        });
+      } else {
+        vaultId = initResult.payload.vault_id;
+        steps.push({
+          id: "heyspex_yaml",
+          label: "heyspex.yaml vault marker",
+          status: "run",
+          detail: `wrote ${yamlPath}`
+        });
+      }
+    }
+  }
+  if (vaultId === void 0) {
+    const existingContent = deps.fileExists(yamlPath) ? deps.readFile(yamlPath) : null;
+    if (existingContent) vaultId = parseVaultId(existingContent) ?? void 0;
+  }
+  let workspaceId = existingVault?.workspace_id ?? args.workspace ?? registryBefore.active_workspace_id ?? "default";
+  const now = deps.now();
+  if (!failedStep) {
+    if (isPresent("workspace_registered")) {
+      steps.push({
+        id: "workspace_registered",
+        label: `workspace "${workspaceId}"`,
+        status: "skipped",
+        detail: "already registered"
+      });
+    } else if (args.dryRun) {
+      steps.push({
+        id: "workspace_registered",
+        label: `workspace "${workspaceId}"`,
+        status: "run",
+        detail: `would register workspace "${workspaceId}"`
+      });
+    } else {
+      try {
+        const isNewWorkspaceRequest = args.workspace !== void 0 && args.workspace === workspaceId && !registryBefore.workspaces.some((w) => w.id === args.workspace);
+        if (isNewWorkspaceRequest) {
+          const created = await createWorkspace(
+            { accountId, displayName: args.workspace },
+            { registryOpts: deps.registryOpts, neon: deps.neon, now: () => now }
+          );
+          if (!created.ok) throw new Error(created.message);
+          workspaceId = created.workspace.id;
+          steps.push({
+            id: "workspace_registered",
+            label: `workspace "${workspaceId}"`,
+            status: "run",
+            detail: `created workspace "${workspaceId}" (from "${args.workspace}")${cloudWriteDetail(created.workspace.neon_written, deps.neon)}`
+          });
+        } else {
+          registerWorkspace(
+            { id: workspaceId, display_name: workspaceId, created_at: now },
+            deps.registryOpts
+          );
+          const neonWritten = await upsertWorkspaceNeon(
+            { id: workspaceId, displayName: workspaceId },
+            accountId,
+            deps.neon
+          );
+          steps.push({
+            id: "workspace_registered",
+            label: `workspace "${workspaceId}"`,
+            status: "run",
+            detail: `registered${cloudWriteDetail(neonWritten, deps.neon)}`
+          });
+        }
+      } catch (err) {
+        failedStep = "workspace_registered";
+        failMessage = err instanceof Error ? err.message : String(err);
+        steps.push({
+          id: "workspace_registered",
+          label: `workspace "${workspaceId}"`,
+          status: "failed",
+          detail: failMessage
+        });
+      }
+    }
+  }
+  if (!failedStep) {
+    if (isPresent("vault_registered")) {
+      steps.push({
+        id: "vault_registered",
+        label: "vault registration",
+        status: "skipped",
+        detail: existingVault ? `id: ${existingVault.id}` : "already registered"
+      });
+    } else if (args.dryRun) {
+      steps.push({
+        id: "vault_registered",
+        label: "vault registration",
+        status: "run",
+        detail: vaultId ? `would register vault (id: ${vaultId})` : "would register vault (id resolved once heyspex.yaml is written)"
+      });
+    } else {
+      const resolvedVaultId = vaultId ?? slugFromPath(deps, repoRoot);
+      const displayName = deps.basename(repoRoot);
+      let schemaVersion = HEYSPEX_YAML_SCHEMA_VERSION;
+      const yamlContentAfter = deps.fileExists(yamlPath) ? deps.readFile(yamlPath) : null;
+      if (yamlContentAfter) {
+        const versionMatch = yamlContentAfter.match(/^schema_version:\s*(\d+)\s*$/m);
+        if (versionMatch) schemaVersion = Number(versionMatch[1]);
+      }
+      try {
+        registerVault(
+          {
+            id: resolvedVaultId,
+            workspace_id: workspaceId,
+            display_name: displayName,
+            repo_root_abs: repoRoot,
+            schema_version: schemaVersion,
+            registered_at: now,
+            // Persist the detected remote into the local registry write, too
+            // ([[HS-8XB6-P1EC-DIAG-connect-never-persists-the-git-remote]]
+            // fix (a)) — the exact field the repo-identity reconciliation
+            // helpers match on; a connect that never writes it makes every
+            // vault it creates unmatchable by remote on the next machine.
+            ...gitRemote ? { github_remote: gitRemote } : {}
+          },
+          deps.registryOpts
+        );
+        const neonWritten = await upsertVaultNeon(
+          {
+            id: resolvedVaultId,
+            workspaceId,
+            displayName,
+            repoRootAbs: repoRoot,
+            schemaVersion,
+            ...gitRemote ? { githubRemote: gitRemote } : {}
+          },
+          accountId,
+          deps.neon
+        );
+        vaultId = resolvedVaultId;
+        steps.push({
+          id: "vault_registered",
+          label: "vault registration",
+          status: "run",
+          detail: `registered vault "${resolvedVaultId}"${cloudWriteDetail(neonWritten, deps.neon)}`
+        });
+      } catch (err) {
+        failedStep = "vault_registered";
+        failMessage = err instanceof Error ? err.message : String(err);
+        steps.push({
+          id: "vault_registered",
+          label: "vault registration",
+          status: "failed",
+          detail: failMessage
+        });
+      }
+    }
+  }
+  const platformRoot = deps.platformRoot ?? repoRoot;
+  const runSpawned = (command, spawnArgs, opts) => {
+    if (!deps.spawn) return { ok: false, message: "no spawn capability in this caller" };
+    try {
+      const res = deps.spawn(command, spawnArgs, opts);
+      const output = `${res.stderr ?? ""}${res.stdout ?? ""}`;
+      if (res.status === 0 || /already/i.test(output)) {
+        return { ok: true, message: (res.stdout || res.stderr || "").trim() };
+      }
+      return {
+        ok: false,
+        message: (res.stderr || res.stdout || `exit ${res.status ?? "?"}`).trim()
+      };
+    } catch (err) {
+      return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+  };
+  if (!failedStep) {
+    const claudeMcpPath = deps.joinPath(repoRoot, ".mcp.json");
+    const cursorMcpPath = deps.joinPath(repoRoot, ".cursor", "mcp.json");
+    const label = "MCP server entry (Claude Code / Cursor)";
+    const claudeMissing = !deps.fileExists(claudeMcpPath);
+    const cursorMissing = !deps.fileExists(cursorMcpPath);
+    if (!claudeMissing && !cursorMissing) {
+      steps.push({ id: "mcp_entry", label, status: "skipped", detail: "already installed" });
+    } else if (args.dryRun) {
+      const toWrite = [
+        claudeMissing ? claudeMcpPath : null,
+        cursorMissing ? cursorMcpPath : null
+      ].filter((v) => v !== null);
+      steps.push({
+        id: "mcp_entry",
+        label,
+        status: "run",
+        detail: `would write ${toWrite.join(" + ")}`
+      });
+    } else {
+      try {
+        const cliPath = mcpCliPath(platformRoot, deps.joinPath);
+        const written = [];
+        if (claudeMissing) {
+          deps.writeFile(
+            claudeMcpPath,
+            `${JSON.stringify(renderClaudeMcpJson(cliPath), null, 2)}
+`
+          );
+          written.push(claudeMcpPath);
+        }
+        if (cursorMissing) {
+          deps.mkdir(deps.joinPath(repoRoot, ".cursor"));
+          deps.writeFile(
+            cursorMcpPath,
+            `${JSON.stringify(renderCursorMcpJson(cliPath), null, 2)}
+`
+          );
+          written.push(cursorMcpPath);
+        }
+        steps.push({
+          id: "mcp_entry",
+          label,
+          status: "run",
+          detail: written.length === 2 ? `wrote ${written.join(", ")}` : `backfilled missing surface: wrote ${written.join(", ")}`
+        });
+      } catch (err) {
+        failedStep = "mcp_entry";
+        failMessage = err instanceof Error ? err.message : String(err);
+        steps.push({ id: "mcp_entry", label, status: "failed", detail: failMessage });
+      }
+    }
+  }
+  if (!failedStep) {
+    const label = "Claude plugin surfaces (commands + skills)";
+    const marketplaceManifest = pluginMarketplaceManifestPath(platformRoot, deps.joinPath);
+    const pluginAvailable = deps.fileExists(marketplaceManifest);
+    if (isPresent("plugin_surface")) {
+      steps.push({ id: "plugin_surface", label, status: "skipped", detail: "already installed" });
+    } else if (!pluginAvailable) {
+      steps.push({
+        id: "plugin_surface",
+        label,
+        status: "skipped",
+        detail: "platform checkout has no .claude-plugin/marketplace.json"
+      });
+    } else if (args.dryRun) {
+      const spec = resolvePluginSpec(platformRoot, deps);
+      steps.push({
+        id: "plugin_surface",
+        label,
+        status: "run",
+        detail: `would run: claude plugin marketplace add + claude plugin install ${spec.spec}`
+      });
+    } else {
+      const spec = resolvePluginSpec(platformRoot, deps);
+      const marketplace = runSpawned("claude", ["plugin", "marketplace", "add", platformRoot], {
+        cwd: repoRoot
+      });
+      const install = marketplace.ok ? runSpawned("claude", ["plugin", "install", spec.spec, "--scope", "project"], {
+        cwd: repoRoot
+      }) : marketplace;
+      steps.push({
+        id: "plugin_surface",
+        label,
+        status: install.ok ? "run" : "skipped",
+        detail: install.ok ? `installed plugin ${spec.spec}` : install.message
+      });
+    }
+  }
+  if (!failedStep) {
+    const label = "git hooks (pre-commit / pre-push)";
+    const hooksScript = deps.joinPath(repoRoot, "scripts", "install-git-hooks.mjs");
+    const preCommitHookPath = deps.joinPath(repoRoot, ".git", "hooks", "pre-commit");
+    const foreignHookExists = deps.fileExists(preCommitHookPath);
+    if (isPresent("git_hooks")) {
+      steps.push({ id: "git_hooks", label, status: "skipped", detail: "already installed" });
+    } else if (!deps.fileExists(hooksScript)) {
+      steps.push({
+        id: "git_hooks",
+        label,
+        status: "skipped",
+        detail: "scripts/install-git-hooks.mjs not found in this repo"
+      });
+    } else if (args.dryRun) {
+      steps.push({
+        id: "git_hooks",
+        label,
+        status: "run",
+        detail: foreignHookExists ? `would repair ${preCommitHookPath} (foreign hook, no HeySpex marker) via: node ${hooksScript} --force` : `would run: node ${hooksScript}`
+      });
+    } else {
+      const result = runSpawned(
+        "node",
+        foreignHookExists ? [hooksScript, "--force"] : [hooksScript],
+        { cwd: repoRoot }
+      );
+      steps.push({
+        id: "git_hooks",
+        label,
+        status: result.ok ? "run" : "skipped",
+        detail: result.ok ? foreignHookExists ? "repaired foreign pre-commit hook via scripts/install-git-hooks.mjs --force" : "installed via scripts/install-git-hooks.mjs" : result.message
+      });
+    }
+  }
+  if (!failedStep && args.fleet) {
+    const repoKey = deps.basename(repoRoot);
+    const label = `fleet dispatch registration ("${repoKey}")`;
+    const routingTablePath = deps.joinPath(platformRoot, "dev-factory", "routing-table.json");
+    const routingUpdaterScript = deps.joinPath(
+      platformRoot,
+      "dev-factory",
+      "lib",
+      "routing-updater.mjs"
+    );
+    let alreadyRegistered = false;
+    const routingTableRaw = deps.fileExists(routingTablePath) ? deps.readFile(routingTablePath) : null;
+    if (routingTableRaw) {
+      try {
+        const parsed = JSON.parse(routingTableRaw);
+        alreadyRegistered = Boolean(parsed.repos && Object.hasOwn(parsed.repos, repoKey));
+      } catch {
+        alreadyRegistered = false;
+      }
+    }
+    if (alreadyRegistered) {
+      steps.push({
+        id: "fleet_repo",
+        label,
+        status: "skipped",
+        detail: `repo "${repoKey}" already registered in dev-factory/routing-table.json`
+      });
+    } else if (!deps.fileExists(routingUpdaterScript)) {
+      steps.push({
+        id: "fleet_repo",
+        label,
+        status: "skipped",
+        detail: "dev-factory/lib/routing-updater.mjs not found in this repo"
+      });
+    } else if (args.dryRun) {
+      steps.push({
+        id: "fleet_repo",
+        label,
+        status: "run",
+        detail: `would register repo "${repoKey}" via routing-updater.mjs --register-repo --apply`
+      });
+    } else {
+      const result = runSpawned(
+        "node",
+        [
+          routingUpdaterScript,
+          "--register-repo",
+          "--repo-key",
+          repoKey,
+          "--root",
+          repoRoot,
+          "--apply"
+        ],
+        { cwd: platformRoot }
+      );
+      steps.push({
+        id: "fleet_repo",
+        label,
+        status: result.ok ? "run" : "skipped",
+        detail: result.ok ? `registered repo "${repoKey}"` : result.message
+      });
+    }
+  }
+  let doctorOutcome;
+  if (!failedStep) {
+    const label = "hs doctor acceptance pass";
+    const doctorScript = deps.joinPath(repoRoot, "scripts", "heyspex-doctor.mjs");
+    if (args.dryRun) {
+      steps.push({
+        id: "doctor_acceptance",
+        label,
+        status: "run",
+        detail: `would run: node ${doctorScript} --json`
+      });
+    } else if (args.noDoctor) {
+      steps.push({
+        id: "doctor_acceptance",
+        label,
+        status: "skipped",
+        detail: "doctor skipped (caller runs it)"
+      });
+    } else if (!deps.spawn) {
+      steps.push({
+        id: "doctor_acceptance",
+        label,
+        status: "skipped",
+        detail: "no spawn capability in this caller"
+      });
+    } else if (!deps.fileExists(doctorScript)) {
+      steps.push({
+        id: "doctor_acceptance",
+        label,
+        status: "skipped",
+        detail: "scripts/heyspex-doctor.mjs not found in this repo"
+      });
+    } else {
+      try {
+        const res = deps.spawn("node", [doctorScript, "--json"], { cwd: repoRoot });
+        const rawOut = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+        let report2 = null;
+        try {
+          report2 = JSON.parse(res.stdout ?? "");
+        } catch {
+          report2 = null;
+        }
+        const exitCode = res.status;
+        const doctorOk = report2 ? Boolean(report2.ok) : exitCode === 0;
+        doctorOutcome = {
+          ok: doctorOk,
+          exit_code: exitCode,
+          report: report2,
+          ...report2 ? {} : { raw: rawOut }
+        };
+        const summary = summarizeDoctorReport(report2, doctorOk, exitCode);
+        if (doctorOk) {
+          steps.push({ id: "doctor_acceptance", label, status: "run", detail: summary });
+        } else {
+          failedStep = "doctor_acceptance";
+          failMessage = summary;
+          steps.push({ id: "doctor_acceptance", label, status: "failed", detail: summary });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        steps.push({
+          id: "doctor_acceptance",
+          label,
+          status: "skipped",
+          detail: `doctor spawn failed: ${message}`
+        });
+      }
+    }
+  }
+  const ok = failedStep === void 0;
+  const payload = {
+    ok,
+    repo_root: repoRoot,
+    git_remote: gitRemote,
+    dry_run: args.dryRun,
+    steps,
+    workspace_id: workspaceId,
+    ...vaultId ? { vault_id: vaultId } : {},
+    ...failedStep ? { failed_step: failedStep, error: "step_failed" } : {},
+    ...doctorOutcome ? { doctor: doctorOutcome } : {},
+    ...warnings.length > 0 ? { warnings } : {}
+  };
+  const lines = [
+    args.dryRun ? `hs connect (dry run) \u2014 ${repoRoot}` : `hs connect \u2014 ${repoRoot}`,
+    `git remote: ${gitRemote ?? "(none)"}`,
+    "",
+    ...steps.map(
+      (s) => `  [${s.status === "skipped" ? "-" : s.status === "failed" ? "!" : "x"}] ${s.label}: ${s.status}${s.detail ? ` (${s.detail})` : ""}`
+    ),
+    ...warnings.length > 0 ? warnings.map((w) => `[!] ${w}`) : [],
+    "",
+    ok ? args.dryRun ? "Dry run only \u2014 nothing was changed." : "hs connect complete." : `hs connect failed at step "${failedStep}": ${failMessage}`
+  ];
+  return {
+    code: ok ? EXIT.OK : EXIT.WRITE_FAILED,
+    message: lines.join("\n"),
+    payload,
+    isError: !ok
+  };
+}
+async function runConnect(args, deps) {
+  if (args.sub === "check") {
+    const report = runConnectChecks(deps.repoRoot, deps);
+    return {
+      code: report.connected ? EXIT.OK : 1,
+      message: formatReport(report),
+      payload: { ok: true, ...report },
+      isError: false
+    };
+  }
+  return runConnectFullRun(args, deps);
+}
+var HELP2 = [
+  "Usage:",
+  "  hs connect [--dry-run] [--json] [--fleet] [--no-doctor] [--workspace <id>]",
+  "                                                             Detect + scaffold +",
+  "                                                             register + install + verify",
+  "  hs connect --check [--json]                 Read-only report: is this repo connected?",
+  "",
+  "`hs connect` (no flags) walks up from the current directory to the repo root (.git)",
+  "and reads its git remote (no prompts), then runs each step below \u2014 skipping any",
+  "artifact that's already present, driven by the same report --check prints:",
+  "  \u2022 specs/ directory",
+  "  \u2022 heyspex.yaml vault marker (via hs init's existing logic \u2014 never a second writer)",
+  "  \u2022 workspace registration (~/.heyspex/registry.json always, Neon best-effort) \u2014 for a NEW",
+  "    vault the workspace id resolves as: explicit --workspace <id>, else the ACTIVE",
+  "    workspace from ~/.heyspex/registry.json (set by `hs workspace switch`), else",
+  '    "default" as a last resort. An already-registered vault keeps its own workspace,',
+  "    ignoring --workspace.",
+  "  \u2022 vault registration (~/.heyspex/registry.json always, Neon best-effort)",
+  "  \u2022 MCP server entry for Claude Code / Cursor (via hs install's existing render logic)",
+  "  \u2022 Claude plugin surfaces \u2014 commands + skills (via hs install's plugin registration)",
+  "  \u2022 git hooks \u2014 pre-commit / pre-push (via scripts/install-git-hooks.mjs)",
+  "  \u2022 with --fleet: fleet dispatch registration in dev-factory/routing-table.json",
+  "    (via routing-updater.mjs --register-repo --apply; skipped without --fleet)",
+  "  \u2022 doctor acceptance pass \u2014 runs `node scripts/heyspex-doctor.mjs --json` in the",
+  "    target repo once everything above succeeds; connect's own exit code IS doctor's",
+  "    (non-zero if doctor fails, even when every earlier step succeeded). Skipped by",
+  "    --dry-run (still listed as the planned final step) and by --no-doctor (for a",
+  "    caller like `hs join` that runs doctor itself right after connect).",
+  "",
+  "The installer steps never hard-fail the run on a missing/failing external CLI",
+  "(claude not on PATH, script not vendored into this repo) \u2014 they report skipped",
+  "with the reason, same best-effort philosophy as hs install's --claude-apply.",
+  "",
+  "Safe to run twice \u2014 a second run reports every step skipped. --dry-run computes",
+  "the same ordered step plan and prints it without writing anything. Exits 0 on",
+  "success, non-zero with the failing step named in the JSON payload's failed_step",
+  "(which is 'doctor_acceptance' when every step ran but the acceptance pass failed).",
+  "",
+  "Flags:",
+  "  --check      Run the read-only connection check instead of the full run.",
+  "  --dry-run    Print the step plan without writing anything (full run only).",
+  "  --fleet      Also register this repo for fleet dispatch (dev-factory/routing-table.json).",
+  "  --no-doctor  Skip the final doctor acceptance pass (the caller runs it instead).",
+  "  --workspace <id>  Workspace id for a NEW vault (full run only; an already-registered",
+  "                     vault keeps its own workspace and ignores this flag).",
+  "  --json       Emit a machine-readable JSON result.",
+  "  --help, -h   Show this help.",
+  "",
+  "Exit codes: 0 ok (or connected, for --check) \xB7 1 usage / not connected (--check) \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/defer.ts
+import { readFileSync as readFileSync5 } from "node:fs";
+import os2 from "node:os";
+import path3 from "node:path";
+function resolveSpexConsoleUrl(vaultRoot, readDiscovery, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (raw && raw.length > 0) return raw.replace(/\/+$/, "");
+  try {
+    const homeDir = opts.homeDir ?? os2.homedir();
+    const readFile2 = opts.readFile ?? ((p) => readFileSync5(p, "utf-8"));
+    const credentials = readFile2(path3.join(homeDir, ".heyspex", "credentials.yaml"));
+    const match = credentials.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    if (value && value.length > 0) return value.replace(/\/+$/, "");
+  } catch {
+  }
+  for (const name of ["console-url", "cockpit-url"]) {
+    try {
+      const discovery = readDiscovery(`${vaultRoot}/.heyspex/${name}`);
+      if (discovery && discovery.trim().length > 0) {
+        return discovery.trim().replace(/\/+$/, "");
+      }
+    } catch {
+    }
+  }
+  return DEFAULT_CONSOLE_URL;
+}
+var HELP3 = [
+  "Usage:",
+  "  hs defer <spec-id> [--until <when>] [--json] [--no-daemon]",
+  "  hs undefer <spec-id> [--json] [--no-daemon]",
+  "",
+  "Time-shift a spec via its `defer_until` frontmatter field. A deferred spec is",
+  "scheduler-invisible until the date passes, then auto-revives.",
+  "",
+  "Arguments:",
+  "  <spec-id>        The spec to defer/undefer (e.g. HS-TASK-EWL5).",
+  "",
+  "Flags:",
+  "  --until <when>   ISO date, or relative offset +Nd / +Nw / +Nm / +Ny.",
+  "                   Defaults to +1y (matches the console Defer button).",
+  "                   Ignored by `undefer` (which always clears the field).",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --no-daemon      Write straight to the vault (no console needed; CI path).",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/bin/hs-connect.ts
+function readFile(p) {
+  try {
+    return readFileSync6(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const parsed = parseConnectArgs(process2.argv.slice(3));
+  if (parsed.help) {
+    process2.stdout.write(`${HELP2}
+`);
+    process2.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs connect: ${parsed.error.message}
+`);
+    process2.exit(parsed.error.code);
+  }
+  const cwd = resolveConnectCwd(process2.env, process2.cwd());
+  const repoRoot = process2.env.HS_VAULT_ROOT ? path4.resolve(process2.env.HS_VAULT_ROOT) : cwd;
+  const platformRoot = (process2.env.HS_INSTALL_PLATFORM?.trim() || process2.env.HEYSPEX_PLATFORM_ROOT?.trim() || process2.env.HS_PKG_ROOT?.trim() || repoRoot).trim();
+  const consoleUrl = resolveSpexConsoleUrl(repoRoot, readFile);
+  const result = await runConnect(parsed.args, {
+    repoRoot,
+    cwd,
+    platformRoot: path4.resolve(platformRoot),
+    fileExists: (p) => existsSync2(p),
+    readFile,
+    writeFile: (p, c) => writeFileSync2(p, c, "utf8"),
+    mkdir: (p) => mkdirSync2(p, { recursive: true }),
+    joinPath: (...s) => path4.join(...s),
+    basename: (p) => path4.basename(p),
+    now: () => (/* @__PURE__ */ new Date()).toISOString(),
+    spawn: (command, args, opts) => {
+      const res = spawnSync(command, args, {
+        cwd: opts?.cwd,
+        encoding: "utf8",
+        shell: process2.platform === "win32"
+      });
+      return { status: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+    },
+    neon: { http: { fetchImpl: fetch, consoleUrl, token: readPairedToken() } }
+  });
+  const sink = result.isError ? process2.stderr : process2.stdout;
+  sink.write(`${parsed.args.json ? JSON.stringify(result.payload) : result.message}
+`);
+  process2.exit(result.code);
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process2.stderr.write(`hs connect: unhandled: ${message}
+`);
+  process2.exit(EXIT.WRITE_FAILED);
+});