heyspex 0.2.0 → 0.2.2

package/dist/cli/hs-index-rebuild.mjs

@@ -59,11 +59,26 @@ var init_hs_command = __esm({
   }
 });
 
+// scripts/lib/heyspex-home.mjs
+import { homedir } from "node:os";
+function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+var init_heyspex_home = __esm({
+  "scripts/lib/heyspex-home.mjs"() {
+    "use strict";
+  }
+});
+
 // vendor/heyspex-mcp/credentials.mjs
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import os, { homedir } from "node:os";
+import os, { homedir as homedir2 } from "node:os";
 import { dirname as dirname2, join as join2, resolve } from "node:path";
-function credentialsFilePath(homeDir = homedir()) {
+function credentialsFilePath(homeDir = heyspexHome()) {
   return join2(homeDir, ".heyspex", "credentials.yaml");
 }
 function parseMcpToken(raw) {
@@ -159,7 +174,7 @@ function readLegacyConfigAccountId(read, homeDir) {
   const value = raw?.match(CONFIG_ACCOUNT_ID_RE)?.[1]?.trim() ?? "";
   return value || null;
 }
-function readCurrentAccountId({ homeDir = homedir(), readFile } = {}) {
+function readCurrentAccountId({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, "utf8"));
   const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
   if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
@@ -172,6 +187,7 @@ var MCP_TOKEN_LINE_RE, CREDENTIALS_SCHEMA_VERSION, LEGACY_ACCOUNT_ID, ACCOUNT_FI
 var init_credentials = __esm({
   "vendor/heyspex-mcp/credentials.mjs"() {
     "use strict";
+    init_heyspex_home();
     MCP_TOKEN_LINE_RE = /^mcp_token:[ \t]*["']?([^"'\r\n#]+)/m;
     CREDENTIALS_SCHEMA_VERSION = 2;
     LEGACY_ACCOUNT_ID = "legacy";
@@ -183,9 +199,9 @@ var init_credentials = __esm({
 
 // vendor/heyspex-mcp/session-owner.mjs
 import { readFileSync as readFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
+import { homedir as homedir3 } from "node:os";
 import { join as join3 } from "node:path";
-function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir2(), readFile } = {}) {
+function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
   const fromEnv = typeof env?.HS_ACCOUNT_ID === "string" ? env.HS_ACCOUNT_ID.trim() : "";
   if (fromEnv) return fromEnv;
   return readCurrentAccountId({ homeDir, readFile });
@@ -193,6 +209,7 @@ function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir2(),
 var init_session_owner = __esm({
   "vendor/heyspex-mcp/session-owner.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
   }
 });
@@ -227,20 +244,47 @@ var init_vault_less_endpoints = __esm({
   }
 });
 
+// scripts/lib/shared-path-helpers.mjs
+import { isAbsolute, resolve as resolve2, sep } from "node:path";
+var init_shared_path_helpers = __esm({
+  "scripts/lib/shared-path-helpers.mjs"() {
+    "use strict";
+  }
+});
+
+// vendor/heyspex-mcp/write-outbox.mjs
+import {
+  readdirSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2,
+  mkdirSync as mkdirSync2,
+  existsSync as existsSync2,
+  renameSync as renameSync2,
+  rmSync
+} from "node:fs";
+import { basename, join as join4, isAbsolute as isAbsolute2 } from "node:path";
+var init_write_outbox = __esm({
+  "vendor/heyspex-mcp/write-outbox.mjs"() {
+    "use strict";
+    init_shared_path_helpers();
+  }
+});
+
 // vendor/heyspex-mcp/vault-resolve.mjs
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { homedir as homedir3, tmpdir } from "node:os";
-import { dirname as dirname3, join as join4, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir4, tmpdir } from "node:os";
+import { dirname as dirname3, join as join5, resolve as resolve3 } from "node:path";
 var init_vault_resolve = __esm({
   "vendor/heyspex-mcp/vault-resolve.mjs"() {
     "use strict";
+    init_heyspex_home();
   }
 });
 
 // vendor/heyspex-mcp/console-fetch.mjs
-import { readFileSync as readFileSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { join as join5 } from "node:path";
+import { readFileSync as readFileSync5 } from "node:fs";
+import { homedir as homedir5 } from "node:os";
+import { join as join6 } from "node:path";
 function isCloudVaultId(value) {
   return typeof value === "string" && CLOUD_VAULT_ID_RE.test(value.trim());
 }
@@ -248,16 +292,33 @@ var CLOUD_VAULT_ID_RE, SCOPE_REFUSAL_CODES;
 var init_console_fetch = __esm({
   "vendor/heyspex-mcp/console-fetch.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
     init_session_owner();
     init_vault_less_endpoints();
     init_hs_command();
+    init_write_outbox();
     init_vault_resolve();
     CLOUD_VAULT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
   }
 });
 
+// spex-console/src/lib/heyspex-home.ts
+import { homedir as homedir6 } from "node:os";
+function heyspexHome2(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir6();
+}
+var init_heyspex_home2 = __esm({
+  "spex-console/src/lib/heyspex-home.ts"() {
+    "use strict";
+  }
+});
+
 // spex-console/src/lib/vault-registry/types.ts
 function emptyVaultRegistry() {
   return {
@@ -278,14 +339,13 @@ var init_types = __esm({
 });
 
 // spex-console/src/lib/vault-registry/registry-file.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
-import { dirname as dirname4, join as join6, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname4, join as join7, resolve as resolve4 } from "node:path";
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join6(homedir5(), ".heyspex");
+  return opts.registryDir ?? join7(heyspexHome2(), ".heyspex");
 }
 function vaultRegistryFilePath(opts = {}) {
-  return join6(vaultRegistryDir(opts), "registry.json");
+  return join7(vaultRegistryDir(opts), "registry.json");
 }
 function isNonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
@@ -386,9 +446,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync3(filePath)) return { kind: "missing" };
+  if (!existsSync4(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync5(filePath, "utf8");
+    const raw = readFileSync6(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -417,17 +477,18 @@ function loadVaultRegistry(opts = {}) {
 var init_registry_file = __esm({
   "spex-console/src/lib/vault-registry/registry-file.ts"() {
     "use strict";
+    init_heyspex_home2();
     init_types();
     init_types();
   }
 });
 
 // scripts/lib/dev-mode.mjs
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { join as join7 } from "node:path";
-function devModeFilePath(homeDir = homedir6()) {
-  return join7(homeDir, ".heyspex", DEV_MODE_FILENAME);
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join8 } from "node:path";
+function devModeFilePath(homeDir = heyspexHome()) {
+  return join8(homeDir, ".heyspex", DEV_MODE_FILENAME);
 }
 function normalizeMode(raw) {
   const v = String(raw ?? "").trim().toLowerCase();
@@ -451,7 +512,7 @@ function deriveSemantics(mode, reliance) {
     vaultWriteMode: local ? "local" : "cloud"
   };
 }
-function readLocalDevModeRecord({ homeDir = homedir6(), readFile = defaultReadFile } = {}) {
+function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
     raw = readFile(devModeFilePath(homeDir));
@@ -481,7 +542,7 @@ function readLocalDevModeRecord({ homeDir = homedir6(), readFile = defaultReadFi
 }
 function resolveDevMode({
   env = process.env,
-  homeDir = homedir6(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = void 0
 } = {}) {
@@ -544,18 +605,19 @@ var CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, DEV_MODE_FILENAME, defaultReadFile;
 var init_dev_mode = __esm({
   "scripts/lib/dev-mode.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
     CLOUD_CONSOLE_URL = "https://app.heyspex.com";
     LOCAL_CONSOLE_URL = "http://localhost:3000";
     DEV_MODE_FILENAME = "dev-mode.json";
-    defaultReadFile = (p) => readFileSync6(p, "utf8");
+    defaultReadFile = (p) => readFileSync7(p, "utf8");
   }
 });
 
 // scripts/lib/console-url-resolver.mjs
-import { readFileSync as readFileSync7 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
-import { join as join8 } from "node:path";
+import { readFileSync as readFileSync8 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { join as join9 } from "node:path";
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
@@ -578,9 +640,9 @@ function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
   } catch {
   }
 }
-function readCredentialsConsoleUrl({ homeDir = homedir7(), readFile = defaultReadFile2 } = {}) {
+function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile2 } = {}) {
   try {
-    const raw = readFile(join8(homeDir, ".heyspex", "credentials.yaml"));
+    const raw = readFile(join9(homeDir, ".heyspex", "credentials.yaml"));
     const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
     const value = match?.[1]?.trim();
     return value && value.length > 0 ? trimTrailingSlash(value) : null;
@@ -589,12 +651,12 @@ function readCredentialsConsoleUrl({ homeDir = homedir7(), readFile = defaultRea
   }
 }
 function defaultReadFile2(p) {
-  return readFileSync7(p, "utf8");
+  return readFileSync8(p, "utf8");
 }
 function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery: readDiscovery2 = defaultReadFile2 } = {}) {
   if (!repoRoot) return null;
   try {
-    const discovery = String(readDiscovery2(join8(repoRoot, ".heyspex", "console-url")) ?? "").trim();
+    const discovery = String(readDiscovery2(join9(repoRoot, ".heyspex", "console-url")) ?? "").trim();
     if (discovery.length > 0) return trimTrailingSlash(discovery);
   } catch {
   }
@@ -614,7 +676,7 @@ function resolveModeEnvelope({ env, homeDir }) {
 function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir7(),
+  homeDir = heyspexHome(),
   strict = false,
   devMode,
   log = (line) => process.stderr.write(line),
@@ -647,6 +709,7 @@ var DEFAULT_CONSOLE_URL, LOOPBACK_HOSTS, staleLoopbackCredentialsWarned, Console
 var init_console_url_resolver = __esm({
   "scripts/lib/console-url-resolver.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_dev_mode();
     DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
     LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
@@ -700,13 +763,12 @@ var init_default_workspace = __esm({
 });
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
-import { readFileSync as readFileSync8 } from "node:fs";
-import os2 from "node:os";
+import { readFileSync as readFileSync9 } from "node:fs";
 function resolveConfiguredAccountId(opts = {}) {
   return resolveSessionOwnerUncached({
     env: opts.env ?? process.env,
-    homeDir: opts.homeDir ?? os2.homedir(),
-    readFile: opts.readFile ?? ((p) => readFileSync8(p, "utf-8"))
+    homeDir: opts.homeDir ?? heyspexHome2(),
+    readFile: opts.readFile ?? ((p) => readFileSync9(p, "utf-8"))
   });
 }
 function resolveCloudAccountIdOrRefuse(opts = {}) {
@@ -739,6 +801,7 @@ var CLOUD_ACCOUNT_ID_REQUIRED_MESSAGE;
 var init_vault_workspace_shared = __esm({
   "spex-console/src/lib/cli/vault-workspace-shared.ts"() {
     "use strict";
+    init_heyspex_home2();
     init_session_owner();
     init_default_workspace();
     CLOUD_ACCOUNT_ID_REQUIRED_MESSAGE = "refusing -- no signed-in account (no HS_ACCOUNT_ID env var, and no account_id: in ~/.heyspex/config.yaml). Run `hs login` first; nothing was written.";
@@ -1225,11 +1288,11 @@ var require_excerpt = __commonJS({
       if (typeof opts.excerpt === "function") {
         return opts.excerpt(file, opts);
       }
-      const sep = file.data.excerpt_separator || opts.excerpt_separator;
-      if (sep == null && (opts.excerpt === false || opts.excerpt == null)) {
+      const sep2 = file.data.excerpt_separator || opts.excerpt_separator;
+      if (sep2 == null && (opts.excerpt === false || opts.excerpt == null)) {
         return file;
       }
-      const delimiter2 = typeof opts.excerpt === "string" ? opts.excerpt : sep || opts.delimiters[0];
+      const delimiter2 = typeof opts.excerpt === "string" ? opts.excerpt : sep2 || opts.delimiters[0];
       const idx = file.content.indexOf(delimiter2);
       if (idx !== -1) {
         file.excerpt = file.content.slice(0, idx);
@@ -1294,7 +1357,7 @@ var require_parse = __commonJS({
 var require_gray_matter = __commonJS({
   "node_modules/gray-matter/index.js"(exports2, module2) {
     "use strict";
-    var fs10 = __require("fs");
+    var fs11 = __require("fs");
     var sections = require_section_matter();
     var defaults = require_defaults();
     var stringify = require_stringify();
@@ -1378,7 +1441,7 @@ var require_gray_matter = __commonJS({
       return stringify(file, data, options2);
     };
     matter4.read = function(filepath, options2) {
-      const str2 = fs10.readFileSync(filepath, "utf8");
+      const str2 = fs11.readFileSync(filepath, "utf8");
       const file = matter4(str2, options2);
       file.path = filepath;
       return file;
@@ -1526,13 +1589,13 @@ function bareFileKeyOf(input) {
   if (KNOWN_TYPE_LABELS.has(token)) return null;
   return FILE_KEY_RE.test(token) ? token : null;
 }
-function isEra3SpecId(id, basename) {
+function isEra3SpecId(id, basename2) {
   const raw = String(id ?? "").trim();
   if (!raw) return false;
   if (parseSpecId(raw)?.era === 3) return true;
   const fileKey = bareFileKeyOf(raw);
   if (!fileKey) return false;
-  const parsed = parseSpecId(basename ?? "");
+  const parsed = parseSpecId(basename2 ?? "");
   return parsed?.era === 3 && (parsed.fileKey ?? "").toUpperCase() === fileKey;
 }
 var FILE_KEY_RE, KNOWN_TYPE_LABELS, RULED_FAMILY_SURNAMES, FAMILY_KEYED_TYPE_LABELS, FAMILY_KEY_SHAPE_RE;
@@ -1858,7 +1921,7 @@ var init_parser = __esm({
 });
 
 // dist/cli/._sql-orm-inert.cli-shim.mjs
-var inert, customType, sql, and, eq, isNull, inArray, bigint, bigserial, boolean, foreignKey, index, integer, jsonb, pgEnum, pgTable, primaryKey, text, timestamp, uniqueIndex;
+var inert, customType, sql, and, eq, isNull, desc, gt, inArray, bigint, bigserial, boolean, foreignKey, index, integer, jsonb, pgEnum, pgTable, primaryKey, text, timestamp, uniqueIndex;
 var init_sql_orm_inert_cli_shim = __esm({
   "dist/cli/._sql-orm-inert.cli-shim.mjs"() {
     "use strict";
@@ -1881,6 +1944,8 @@ var init_sql_orm_inert_cli_shim = __esm({
     and = inert;
     eq = inert;
     isNull = inert;
+    desc = inert;
+    gt = inert;
     inArray = inert;
     bigint = inert;
     bigserial = inert;
@@ -1909,7 +1974,7 @@ var init_interfaces = __esm({
 });
 
 // spex-console/src/lib/db/schema/postgres.ts
-var edgeTypeEnum, validationSeverityEnum, outboxOpEnum, tsvector, specs, tags, edges, wikilinks, specLinks, aliases, validationIssues, indexMeta, frontmatterFields, eventOutbox, captureSessions, handoffContext, claimEventKindEnum, activeClaimStatusEnum, pendingReasonEnum, focusEventKindEnum, specEventKindEnum, focusPin, captureFocusPin, captureFocusSelection, focusSelection, focusSkips, activeClaims, claimWaiters, fileClaims, claimEvents, focusEvents, focusAreas, focusAreasEvents, specEvents, rateLimitBuckets, userVaults, milestoneSnapshots, modelRegistryEntries, launchIntentStatusEnum, launchIntents, companionRelayPresence, companionSettingsStore, consoleSettingsStore, wipLedger, wipLedgerArchive, gatherResults, agentSessions, usageEvents, streamEvents, jobStreams, resolutionStatusEnum, resolutionFocusPin, resolutionLedger, workspaces, vaults, accountSettings, vaultGrants, pendingVaultGrants, githubInstallations, fleetMachines, fleetTasks, fleetResults, userApiKeys, apiKeys, mcpSessions, pairingCodes, companionSessions, inviteRequests, notifications, webhookIngestions, specSettlements;
+var edgeTypeEnum, validationSeverityEnum, outboxOpEnum, tsvector, specs, tags, edges, wikilinks, specLinks, aliases, validationIssues, indexMeta, frontmatterFields, eventOutbox, captureSessions, handoffContext, claimEventKindEnum, activeClaimStatusEnum, pendingReasonEnum, focusEventKindEnum, specEventKindEnum, focusPin, captureFocusPin, captureFocusSelection, focusSelection, focusSkips, activeClaims, claimWaiters, fileClaims, claimEvents, focusEvents, focusAreas, focusAreasEvents, specEvents, rateLimitBuckets, userVaults, milestoneSnapshots, modelRegistryEntries, launchIntentStatusEnum, launchIntents, companionRelayPresence, companionSettingsStore, consoleSettingsStore, wipLedger, wipLedgerArchive, gatherResults, agentSessions, usageEvents, streamEvents, jobStreams, resolutionStatusEnum, resolutionFocusPin, resolutionLedger, workspaces, vaults, accountSettings, vaultGrants, pendingVaultGrants, githubInstallations, fleetMachines, fleetTasks, fleetResults, userApiKeys, apiKeys, mcpSessions, pairingCodes, companionSessions, inviteRequests, notifications, webhookIngestions, specSettlements, sessionBranchDeclarations;
 var init_postgres = __esm({
   "spex-console/src/lib/db/schema/postgres.ts"() {
     "use strict";
@@ -2351,7 +2416,13 @@ var init_postgres = __esm({
       "priority_change",
       "parent_change",
       "claim_acquired",
-      "claim_released"
+      "claim_released",
+      // Collaborator write audit (HS-FWB6, migration 0077).
+      "spec_created",
+      "spec_edited",
+      "spec_deleted",
+      "capture_written",
+      "wip_recorded"
     ]);
     focusPin = pgTable(
       "focus_pin",
@@ -3544,11 +3615,43 @@ var init_postgres = __esm({
         // `owner/name`
         branch: text("branch").notNull(),
         commitSha: text("commit_sha").notNull(),
-        settledAt: timestamp("settled_at", { withTimezone: true }).notNull().default(sql`now()`)
+        settledAt: timestamp("settled_at", { withTimezone: true }).notNull().default(sql`now()`),
+        // The pull request that carries this settlement
+        // ([[HS-9D25-CWPX-EPIC-branch-lifecycle-open-a-pull-request]]). NULL until
+        // the branch has gone quiet and a PR was opened or found; a write made
+        // after its PR merged stays NULL, which is what triggers the next PR.
+        pullRequestNumber: integer("pull_request_number"),
+        pullRequestUrl: text("pull_request_url")
       },
       (table) => [
         // "latest settlement for this spec" — the read path's only query.
-        index("spec_settlements_spec_settled_idx").on(table.specId, table.settledAt.desc())
+        index("spec_settlements_spec_settled_idx").on(table.specId, table.settledAt.desc()),
+        // The PR sweep's only query: branches with settlements not yet in a PR.
+        index("spec_settlements_unproposed_idx").on(table.vaultId, table.repo, table.branch).where(sql`${table.pullRequestNumber} IS NULL`)
+      ]
+    );
+    sessionBranchDeclarations = pgTable(
+      "session_branch_declarations",
+      {
+        id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+        vaultId: text("vault_id").notNull().default(DEFAULT_VAULT_ID),
+        actorKey: text("actor_key").notNull(),
+        sessionId: text("session_id").notNull(),
+        branch: text("branch").notNull(),
+        declaredAt: timestamp("declared_at", { withTimezone: true }).notNull().default(sql`now()`),
+        expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+      },
+      (table) => [
+        uniqueIndex("session_branch_declarations_uq").on(
+          table.vaultId,
+          table.actorKey,
+          table.sessionId
+        ),
+        index("session_branch_declarations_lookup_idx").on(
+          table.vaultId,
+          table.actorKey,
+          table.declaredAt.desc()
+        )
       ]
     );
   }
@@ -4465,7 +4568,7 @@ var init_satellite = __esm({
 });
 
 // spex-console/src/lib/vault-resolve/index.ts
-import { existsSync as existsSync4, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync11 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import path5 from "node:path";
 var init_vault_resolve2 = __esm({
@@ -4504,7 +4607,7 @@ var init_resolve_status = __esm({
 });
 
 // spex-console/src/lib/vault-resolve/active.ts
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import path6 from "node:path";
 var ACTIVE_VAULT_CACHE_KEY, cacheStore;
 var init_active = __esm({
@@ -4714,8 +4817,8 @@ function singleFlightDebounce(fn, delayMs) {
     })();
   }
   return function debounced() {
-    return new Promise((resolve4, reject) => {
-      const resolver = { resolve: resolve4, reject };
+    return new Promise((resolve5, reject) => {
+      const resolver = { resolve: resolve5, reject };
       if (inFlight) {
         if (queuedResolvers) {
           queuedResolvers.push(resolver);
@@ -5008,6 +5111,55 @@ var init_branch_policy = __esm({
   }
 });
 
+// spex-console/src/lib/git-export/branch-resolver.ts
+function isValidSessionBranch(name, defaultBranch) {
+  const b = name.trim();
+  if (!b) return { ok: false, reason: "branch name is empty" };
+  if (b === defaultBranch) {
+    return { ok: false, reason: `\`${b}\` is the default branch; the drain never writes it` };
+  }
+  if (PROTECTED_SESSION_BRANCHES.includes(b)) {
+    return { ok: false, reason: `\`${b}\` is a protected ref` };
+  }
+  const hasControlChar = [...b].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127);
+  if (hasControlChar || /[\s~^:?*[\\]/.test(b)) {
+    return { ok: false, reason: "branch name contains characters git refs do not allow" };
+  }
+  if (b.includes("..") || b.includes("@{") || b.includes("//")) {
+    return { ok: false, reason: "branch name contains a forbidden sequence (.. @{ //)" };
+  }
+  if (b.startsWith("/") || b.endsWith("/") || b.startsWith("-") || b.endsWith(".") || b === "@") {
+    return { ok: false, reason: "branch name has a forbidden leading or trailing character" };
+  }
+  if (b.split("/").some((seg) => seg.startsWith(".") || seg.endsWith(".lock"))) {
+    return {
+      ok: false,
+      reason: "branch name has a path segment starting with . or ending in .lock"
+    };
+  }
+  return { ok: true };
+}
+function resolveSessionTargetBranch(input) {
+  const dated = resolveTargetBranch({
+    user: input.user,
+    date: input.date,
+    defaultBranch: input.defaultBranch
+  });
+  const declared = input.sessionBranch?.trim();
+  if (!declared) return { branch: dated, source: "dated" };
+  const check = isValidSessionBranch(declared, input.defaultBranch);
+  if (!check.ok) return { branch: dated, source: "dated", reason: check.reason };
+  return { branch: declared, source: "session" };
+}
+var PROTECTED_SESSION_BRANCHES;
+var init_branch_resolver = __esm({
+  "spex-console/src/lib/git-export/branch-resolver.ts"() {
+    "use strict";
+    init_branch_policy();
+    PROTECTED_SESSION_BRANCHES = ["main", "master", "HEAD", "trunk"];
+  }
+});
+
 // spex-console/src/lib/git-export/config.ts
 function parseGithubRemote(githubRemote) {
   const match = githubRemote.match(/^([^/\s]+)\/([^/\s]+)$/);
@@ -5095,10 +5247,10 @@ function trashPathFor(relPath, now) {
   const normalized = relPath.split("\\").join("/");
   const slashIdx = normalized.lastIndexOf("/");
   const folder = slashIdx === -1 ? "" : normalized.slice(0, slashIdx);
-  const basename = slashIdx === -1 ? normalized : normalized.slice(slashIdx + 1);
+  const basename2 = slashIdx === -1 ? normalized : normalized.slice(slashIdx + 1);
   const stamp = now.toISOString().replace(/[:.]/g, "-");
   const trashDir = folder ? `${folder}/.trash` : ".trash";
-  return `${trashDir}/${stamp}-${basename}`;
+  return `${trashDir}/${stamp}-${basename2}`;
 }
 function materializeSpecMarkdown(bundle) {
   return stringifySpecMarkdown(bundle.bodyText, bundle.frontmatter);
@@ -5407,6 +5559,39 @@ var init_github_client = __esm({
   }
 });
 
+// spex-console/src/lib/git-export/session-branch-store.ts
+async function readActiveDeclaration(db, vaultId, actorKey, now) {
+  const rows = await db.select().from(sessionBranchDeclarations).where(
+    and(
+      eq(sessionBranchDeclarations.vaultId, vaultId),
+      eq(sessionBranchDeclarations.actorKey, actorKey),
+      gt(sessionBranchDeclarations.expiresAt, now)
+    )
+  ).orderBy(desc(sessionBranchDeclarations.declaredAt)).limit(1);
+  const row = rows[0];
+  if (!row) return null;
+  return {
+    vaultId: row.vaultId,
+    actorKey: row.actorKey,
+    sessionId: row.sessionId,
+    branch: row.branch,
+    declaredAt: row.declaredAt.toISOString(),
+    expiresAt: row.expiresAt.toISOString()
+  };
+}
+async function readActiveSessionBranch(db, vaultId, actorKey, now) {
+  return (await readActiveDeclaration(db, vaultId, actorKey, now))?.branch ?? null;
+}
+var SESSION_BRANCH_TTL_MS;
+var init_session_branch_store = __esm({
+  "spex-console/src/lib/git-export/session-branch-store.ts"() {
+    "use strict";
+    init_sql_orm_inert_cli_shim();
+    init_postgres();
+    SESSION_BRANCH_TTL_MS = 12 * 60 * 60 * 1e3;
+  }
+});
+
 // spex-console/src/lib/git-export/settlement-store.ts
 async function recordSettlement(tx, input) {
   await tx.insert(specSettlements).values({
@@ -5637,6 +5822,7 @@ async function processVault(db, vaultId, env, now, deps, batchLimit, jobTimeoutM
         result: { status: "error", message: target.message }
       };
     }
+    const lookupSessionBranch = deps.lookupSessionBranch ?? ((vId, actor) => readActiveSessionBranch(tx, vId, actor, now()));
     const { config, tokenSource, installationId } = target;
     const provider = createPatCommitProvider(() => config.token);
     let pendingSettlement = null;
@@ -5650,11 +5836,18 @@ async function processVault(db, vaultId, env, now, deps, batchLimit, jobTimeoutM
       fetchBundles: (specIds) => fetchDrainBundles(tx, vaultId, specIds),
       resolveActorIdentity,
       commit: async (plan, message, coAuthor) => {
-        const targetBranch = resolveTargetBranch({
+        let sessionBranch = null;
+        try {
+          sessionBranch = await lookupSessionBranch(vaultId, coAuthor.name);
+        } catch {
+          sessionBranch = null;
+        }
+        const targetBranch = resolveSessionTargetBranch({
           user: coAuthor.name,
           date: now(),
-          defaultBranch: config.branch
-        });
+          defaultBranch: config.branch,
+          sessionBranch
+        }).branch;
         const outcome = await commitPlanToGitHub(
           provider,
           config,
@@ -5795,12 +5988,13 @@ var init_drain_runner = __esm({
     init_postgres();
     init_github_app();
     init_advisory_lock();
-    init_branch_policy();
+    init_branch_resolver();
     init_config();
     init_drain();
     init_drain_skip();
     init_export_status();
     init_github_client();
+    init_session_branch_store();
     init_settlement_store();
     BOT_NAME = "heyspex-bot";
     BOT_EMAIL = "bot@heyspex.app";
@@ -6237,7 +6431,7 @@ var init_search_body_hit = __esm({
 
 // spex-console/src/lib/vault.ts
 import { spawn } from "node:child_process";
-import { readdirSync, readFileSync as readFileSync11, statSync } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync12, statSync } from "node:fs";
 import { promises as fs7 } from "node:fs";
 import path13 from "node:path";
 import yaml3 from "js-yaml";
@@ -6357,8 +6551,8 @@ var init_vault = __esm({
 
 // spex-console/bin/hs-index-rebuild.ts
 import { execSync } from "node:child_process";
-import { appendFileSync, mkdirSync as mkdirSync5, readFileSync as readFileSync12 } from "node:fs";
-import { promises as fs9 } from "node:fs";
+import { appendFileSync, mkdirSync as mkdirSync6, readFileSync as readFileSync13 } from "node:fs";
+import { promises as fs10 } from "node:fs";
 import path14 from "node:path";
 import process4 from "node:process";
 
@@ -6527,7 +6721,7 @@ function resolveSyncVaultTarget(input) {
       detail: `heyspex.yaml vault_id${drift}`
     };
   }
-  if (input.pointer.status === "read" && input.pointer.vaultId) {
+  if (input.allowPointer && input.pointer.status === "read" && input.pointer.vaultId) {
     return {
       ok: true,
       vaultId: input.pointer.vaultId,
@@ -6535,9 +6729,9 @@ function resolveSyncVaultTarget(input) {
       detail: "this account's active vault, read from the console (heyspex.yaml names none)"
     };
   }
-  const why = input.pointer.status === "unreadable" ? `the console could not answer for the active vault (${input.pointer.detail})` : "the console reports no active vault for this account";
+  const why = !input.allowPointer ? "the account-wide active vault is not a binding and was not consulted (set HEYSPEX_ALLOW_POINTER_VAULT=1 to follow it on purpose)" : input.pointer.status === "unreadable" ? `the console could not answer for the active vault (${input.pointer.detail})` : "the console reports no active vault for this account";
   return refuse(
-    `cannot tell which vault to ${verb === "pull" ? "pull into" : verb === "index reconcile" ? "reconcile" : "rebuild"}: heyspex.yaml names no vault_id and ${why}. Nothing was changed. The registry.json pointer copy was deliberately not used (it can be stale and target the wrong vault). Name the vault: \`hs --vault <id> ${verb}\`; check this repo's wiring with \`hs connect --check\`; or set the account pointer with \`hs vault switch <id>\`.`
+    `cannot tell which vault to ${verb === "pull" ? "pull into" : verb === "push" ? "push from" : verb === "import" ? "import into" : verb === "index reconcile" ? "reconcile" : "rebuild"}: heyspex.yaml names no vault_id and ${why}. Nothing was changed. The registry.json pointer copy was deliberately not used (it can be stale and target the wrong vault). Name the vault: \`hs --vault <id> ${verb}\`; check this repo's wiring with \`hs connect --check\`; or bind this repo with a heyspex.yaml vault_id (a committed satellite marker is portable).`
   );
 }
 async function resolveSyncVaultTargetFromEnv(deps) {
@@ -6559,8 +6753,11 @@ async function resolveSyncVaultTargetFromEnv(deps) {
   } catch {
     registryRowId = null;
   }
+  const allowPointer = ["1", "true", "yes"].includes(
+    (deps.env.HEYSPEX_ALLOW_POINTER_VAULT ?? "").trim().toLowerCase()
+  );
   let pointer = { status: "unreadable", detail: "not read" };
-  if (!override && !markerVaultId) {
+  if (!override && !markerVaultId && allowPointer) {
     const http = {
       fetchImpl: deps.fetchImpl ?? fetch,
       consoleUrl: deps.consoleUrl,
@@ -6582,7 +6779,8 @@ async function resolveSyncVaultTargetFromEnv(deps) {
     markerVaultId,
     registryRowId,
     pointer,
-    verb: deps.verb
+    verb: deps.verb,
+    allowPointer
   });
 }
 
@@ -6743,23 +6941,22 @@ async function runReindex(input) {
 init_validator();
 
 // spex-console/src/lib/vault-sync/pull-io.ts
-import { promises as fs8 } from "node:fs";
-import { homedir as homedir9 } from "node:os";
-import nodePath from "node:path";
+import { promises as fs9 } from "node:fs";
+import nodePath2 from "node:path";
 
 // spex-console/src/lib/dev-mode.ts
+init_heyspex_home2();
 init_credentials();
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { join as join9 } from "node:path";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join10 } from "node:path";
 var CLOUD_CONSOLE_URL2 = "https://app.heyspex.com";
-var defaultReadFile3 = (p) => readFileSync9(p, "utf8");
+var defaultReadFile3 = (p) => readFileSync10(p, "utf8");
 function readCredentialsMcpToken({
-  homeDir = homedir8(),
+  homeDir = heyspexHome2(),
   readFile = defaultReadFile3
 } = {}) {
   try {
-    const raw = readFile(join9(homeDir, ".heyspex", "credentials.yaml"));
+    const raw = readFile(join10(homeDir, ".heyspex", "credentials.yaml"));
     const match = raw.match(/^mcp_token:\s*["']?([^"'\r\n#]+)/m);
     return match?.[1]?.trim() || null;
   } catch {
@@ -6768,11 +6965,19 @@ function readCredentialsMcpToken({
 }
 
 // spex-console/src/lib/vault-sync/pull-io.ts
+init_heyspex_home2();
 init_vault();
 init_vault_frontmatter();
+
+// spex-console/src/lib/vault-sync/ledger.ts
+import { createHash as createHash3 } from "node:crypto";
+import { promises as fs8 } from "node:fs";
+import nodePath from "node:path";
+
+// spex-console/src/lib/vault-sync/pull-io.ts
 function resolvePullToken({
   env = process.env,
-  homeDir = homedir9()
+  homeDir = heyspexHome2()
 } = {}) {
   const fromEnv = env.HEYSPEX_MCP_TOKEN?.trim();
   if (fromEnv) return fromEnv;
@@ -6896,7 +7101,7 @@ function currentGitHead(vaultRoot2) {
 }
 function appendJournal(vaultRoot2, message) {
   const heyspexDir = path14.join(vaultRoot2, ".heyspex");
-  mkdirSync5(heyspexDir, { recursive: true });
+  mkdirSync6(heyspexDir, { recursive: true });
   const logPath = path14.join(heyspexDir, "index-rebuild.log");
   const ts = (/* @__PURE__ */ new Date()).toISOString();
   appendFileSync(logPath, `[${ts}] ${message}
@@ -6904,7 +7109,7 @@ function appendJournal(vaultRoot2, message) {
 }
 function readDiscovery(p) {
   try {
-    return readFileSync12(p, "utf-8");
+    return readFileSync13(p, "utf-8");
   } catch {
     return null;
   }
@@ -6916,7 +7121,7 @@ function resolveConsole(args) {
 }
 async function loadCrosswalk(vaultRoot2) {
   try {
-    const raw = await fs9.readFile(path14.join(vaultRoot2, ".heyspex", "id-crosswalk.json"), "utf8");
+    const raw = await fs10.readFile(path14.join(vaultRoot2, ".heyspex", "id-crosswalk.json"), "utf8");
     const parsed = JSON.parse(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6926,7 +7131,7 @@ async function loadCrosswalk(vaultRoot2) {
 async function walkLocal(args) {
   const specsDir = path14.join(args.vaultRoot, "specs");
   const files = [];
-  for await (const file of fs9.glob("**/*.md", { cwd: specsDir })) {
+  for await (const file of fs10.glob("**/*.md", { cwd: specsDir })) {
     files.push(path14.join(specsDir, file));
   }
   files.sort();
@@ -6934,7 +7139,7 @@ async function walkLocal(args) {
   let failed = 0;
   for (const abs of files) {
     try {
-      const content = await fs9.readFile(abs, "utf8");
+      const content = await fs10.readFile(abs, "utf8");
       const relPath = path14.relative(args.vaultRoot, abs).split(path14.sep).join("/");
       const parsed = parseSpecFromContent(content, {
         relPath,