heyspex 0.2.0 → 0.2.2

package/dist/cli/hs-defer.mjs

@@ -39,11 +39,26 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// 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, join, resolve } from "node:path";
-function credentialsFilePath(homeDir = homedir()) {
+function credentialsFilePath(homeDir = heyspexHome()) {
   return join(homeDir, ".heyspex", "credentials.yaml");
 }
 function parseMcpToken(raw) {
@@ -139,7 +154,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) {
@@ -152,6 +167,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";
@@ -163,9 +179,9 @@ var init_credentials = __esm({
 
 // scripts/lib/dev-mode.mjs
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
+import { homedir as homedir3 } from "node:os";
 import { join as join2 } from "node:path";
-function devModeFilePath(homeDir = homedir2()) {
+function devModeFilePath(homeDir = heyspexHome()) {
   return join2(homeDir, ".heyspex", DEV_MODE_FILENAME);
 }
 function normalizeMode(raw) {
@@ -190,7 +206,7 @@ function deriveSemantics(mode, reliance) {
     vaultWriteMode: local ? "local" : "cloud"
   };
 }
-function readLocalDevModeRecord({ homeDir = homedir2(), readFile = defaultReadFile } = {}) {
+function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
     raw = readFile(devModeFilePath(homeDir));
@@ -220,7 +236,7 @@ function readLocalDevModeRecord({ homeDir = homedir2(), readFile = defaultReadFi
 }
 function resolveDevMode({
   env = process.env,
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = void 0
 } = {}) {
@@ -283,6 +299,7 @@ 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";
@@ -293,7 +310,7 @@ var init_dev_mode = __esm({
 
 // scripts/lib/console-url-resolver.mjs
 import { readFileSync as readFileSync3 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
+import { homedir as homedir4 } from "node:os";
 import { join as join3 } from "node:path";
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, "");
@@ -317,7 +334,7 @@ function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
   } catch {
   }
 }
-function readCredentialsConsoleUrl({ homeDir = homedir3(), readFile = defaultReadFile2 } = {}) {
+function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile2 } = {}) {
   try {
     const raw = readFile(join3(homeDir, ".heyspex", "credentials.yaml"));
     const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
@@ -353,7 +370,7 @@ function resolveModeEnvelope({ env, homeDir }) {
 function resolveConsoleUrl({
   repoRoot: repoRoot2,
   env = process.env,
-  homeDir = homedir3(),
+  homeDir = heyspexHome(),
   strict = false,
   devMode,
   log = (line) => process.stderr.write(line),
@@ -386,6 +403,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"]);
@@ -401,11 +419,26 @@ var init_console_url_resolver = __esm({
   }
 });
 
+// spex-console/src/lib/heyspex-home.ts
+import { homedir as homedir5 } 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 homedir5();
+}
+var init_heyspex_home2 = __esm({
+  "spex-console/src/lib/heyspex-home.ts"() {
+    "use strict";
+  }
+});
+
 // vendor/heyspex-mcp/session-owner.mjs
 import { readFileSync as readFileSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
+import { homedir as homedir6 } from "node:os";
 import { join as join4 } from "node:path";
-function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir4(), 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 });
@@ -413,6 +446,7 @@ function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir4(),
 var init_session_owner = __esm({
   "vendor/heyspex-mcp/session-owner.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
   }
 });
@@ -426,11 +460,10 @@ var init_default_workspace = __esm({
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import os2 from "node:os";
 function resolveConfiguredAccountId(opts = {}) {
   return resolveSessionOwnerUncached({
     env: opts.env ?? process.env,
-    homeDir: opts.homeDir ?? os2.homedir(),
+    homeDir: opts.homeDir ?? heyspexHome2(),
     readFile: opts.readFile ?? ((p) => readFileSync5(p, "utf-8"))
   });
 }
@@ -464,6 +497,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.";
@@ -1157,7 +1191,7 @@ var init_diagnose_skeleton = __esm({
 });
 
 // dist/cli/._sql-orm-inert.cli-shim.mjs
-var inert, customType, drizzle, sql, and, or, eq, ne, isNull, asc, gt, count, inArray, bigint, bigserial, boolean, foreignKey, index, integer, jsonb, pgEnum, pgTable, primaryKey, text, timestamp, uniqueIndex;
+var inert, customType, drizzle, sql, and, or, eq, ne, isNull, desc, asc, gt, count, 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";
@@ -1183,6 +1217,7 @@ var init_sql_orm_inert_cli_shim = __esm({
     eq = inert;
     ne = inert;
     isNull = inert;
+    desc = inert;
     asc = inert;
     gt = inert;
     count = inert;
@@ -1214,7 +1249,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";
@@ -1656,7 +1691,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",
@@ -2849,11 +2890,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()
+        )
       ]
     );
   }
@@ -3143,10 +3216,9 @@ var init_types = __esm({
 
 // spex-console/src/lib/vault-registry/registry-file.ts
 import { existsSync, mkdirSync as mkdirSync3, readFileSync as readFileSync6, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { homedir as homedir5 } from "node:os";
 import { dirname as dirname2, join as join5, resolve as resolve2 } from "node:path";
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join5(homedir5(), ".heyspex");
+  return opts.registryDir ?? join5(heyspexHome2(), ".heyspex");
 }
 function vaultRegistryFilePath(opts = {}) {
   return join5(vaultRegistryDir(opts), "registry.json");
@@ -3300,6 +3372,7 @@ function accountPointersOf(registry, accountId) {
 var init_registry_file = __esm({
   "spex-console/src/lib/vault-registry/registry-file.ts"() {
     "use strict";
+    init_heyspex_home2();
     init_types();
     init_types();
   }
@@ -3478,6 +3551,30 @@ function isAbsolutePathForCompare(p) {
   const s = p.trim();
   return /^[\\/]/.test(s) || /^[a-zA-Z]:[\\/]/.test(s);
 }
+function expandPinPlaceholders(value, repoRoot2) {
+  return value.replace(/\$\{(?:CLAUDE_PROJECT_DIR|workspaceFolder)(?::-[^}]*)?\}/g, repoRoot2);
+}
+function lexicalJoin(base, rel) {
+  const parts = `${base}/${rel}`.replace(/\\/g, "/").split("/");
+  const out = [];
+  for (const seg of parts) {
+    if (seg === "" && out.length > 0) continue;
+    if (seg === ".") continue;
+    if (seg === ".." && out.length > 1) {
+      out.pop();
+      continue;
+    }
+    out.push(seg);
+  }
+  return out.join("/");
+}
+function parseMarkerVaultPath(content) {
+  const m = content.match(/^vault_path:[ \t]*(.+?)[ \t]*$/m);
+  if (!m) return null;
+  const v = m[1].trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
+  if (!v || v.includes("${") || /^[\\/]/.test(v) || /^[a-zA-Z]:[\\/]/.test(v)) return null;
+  return v;
+}
 function readPinnedVaultRoot(repoRoot2, deps) {
   const pins = [];
   for (const rel of SATELLITE_MANIFEST_RELS) {
@@ -3494,9 +3591,13 @@ function readPinnedVaultRoot(repoRoot2, deps) {
     }
     if (typeof value !== "string") continue;
     const trimmed = value.trim();
-    if (!trimmed || trimmed.includes("${")) continue;
-    if (!isAbsolutePathForCompare(trimmed)) continue;
-    pins.push({ source: rel.join("/"), value: trimmed });
+    if (!trimmed) continue;
+    const expanded = expandPinPlaceholders(trimmed, repoRoot2);
+    if (expanded.includes("${")) continue;
+    if (/^[a-zA-Z]:(?![\\/])/.test(expanded)) continue;
+    const abs = isAbsolutePathForCompare(expanded) ? expanded.includes("..") ? lexicalJoin(expanded, ".") : expanded : lexicalJoin(repoRoot2, expanded);
+    if (expanded !== trimmed && isAtOrUnder(abs, repoRoot2)) continue;
+    pins.push({ source: rel.join("/"), value: abs });
   }
   return pins;
 }
@@ -3547,6 +3648,24 @@ function readMarkerVaultId(dir) {
     return null;
   }
 }
+function readMarkerSatellite(dir) {
+  let raw;
+  try {
+    raw = readFileSync7(path2.join(dir, "heyspex.yaml"), "utf8");
+  } catch {
+    return null;
+  }
+  const vaultPath = parseMarkerVaultPath(raw);
+  if (!vaultPath) return null;
+  const vaultId = parseMarkerVaultId(raw);
+  const candidate = path2.resolve(dir, vaultPath);
+  let vaultRootAbs = null;
+  if (candidate.toLowerCase() !== path2.resolve(dir).toLowerCase() && isVaultRootDir(candidate)) {
+    const theirs = readMarkerVaultId(candidate);
+    if (!vaultId || !theirs || theirs === vaultId) vaultRootAbs = candidate;
+  }
+  return { vaultId, vaultRootAbs };
+}
 function isVaultRootDir(dir) {
   const norm = (p) => path2.resolve(p).replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
   if (norm(dir) === norm(tmpdir())) return false;
@@ -3567,6 +3686,14 @@ function findCwdVaultOrAttachment(startDir, stopAt) {
   const boundary = stopAt ? path2.resolve(stopAt) : null;
   let dir = startDir;
   for (let i = 0; i < 256; i += 1) {
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return {
+        repoRootAbs: marked.vaultRootAbs ?? dir,
+        satellite: true,
+        markerVaultId: marked.vaultId
+      };
+    }
     const pinned = readPinnedVaultRoot(dir, deps).find((pin) => !isAtOrUnder(pin.value, dir));
     if (pinned) return { repoRootAbs: path2.resolve(pinned.value), satellite: true };
     if (isVaultRootDir(dir)) return { repoRootAbs: dir, satellite: false };
@@ -3612,6 +3739,9 @@ async function resolveActiveVaultRoot(options2 = {}) {
   const cwdMatch = findCwdVaultOrAttachment(cwdBase, options2.cwdWalkRoot);
   if (cwdMatch?.satellite) {
     onTier({ tier: "satellite-pin", outcome: "resolved", detail: cwdMatch.repoRootAbs });
+    if (cwdMatch.markerVaultId) {
+      return finalize(cwdMatch.markerVaultId, path2.resolve(cwdMatch.repoRootAbs), "satellite-pin");
+    }
     return finalizePathTier(cwdMatch.repoRootAbs, "satellite-pin");
   }
   if (cwdMatch) {
@@ -4795,6 +4925,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]+)$/);
@@ -5197,6 +5376,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({
@@ -5427,6 +5639,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;
@@ -5440,11 +5653,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,
@@ -5585,12 +5805,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";
@@ -8154,7 +8375,7 @@ var init_plan_tier = __esm({
 
 // spex-console/src/lib/db/clients/vault-router.ts
 import { existsSync as existsSync4, readFileSync as readFileSync8 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
+import { homedir as homedir7 } from "node:os";
 import { join as join6 } from "node:path";
 function normalizeDatabaseRef(raw) {
   if (typeof raw !== "string") return null;
@@ -8287,7 +8508,7 @@ var init_vault_router = __esm({
     init_postgres_client_cli_shim();
     DEDICATED_DB_ENV_PREFIX = "HEYSPEX_DEDICATED_DB_";
     DEDICATED_REFS_ENV = "DEDICATED_DATABASE_REFS";
-    CREDENTIALS_PATH = join6(homedir6(), ".heyspex", "credentials.yaml");
+    CREDENTIALS_PATH = join6(homedir7(), ".heyspex", "credentials.yaml");
     REF_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
     ROUTER_KEY = Symbol.for("heyspex.vaultRouter");
     globalRouter = globalThis;

package/dist/cli/hs-dev.mjs

@@ -6,12 +6,24 @@ import process3 from "node:process";
 
 // spex-console/src/lib/dev-mode.ts
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
 import { join as join2 } from "node:path";
 
+// spex-console/src/lib/heyspex-home.ts
+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();
+}
+
+// scripts/lib/heyspex-home.mjs
+import { homedir as homedir2 } from "node:os";
+
 // vendor/heyspex-mcp/credentials.mjs
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import os, { homedir } from "node:os";
+import os, { homedir as homedir3 } from "node:os";
 import { dirname, join, resolve } from "node:path";
 function underTestRunner(env = process.env) {
   return Boolean(env.VITEST) || Boolean(env.NODE_TEST_CONTEXT);
@@ -74,12 +86,12 @@ function deriveSemantics(mode, reliance) {
     vaultWriteMode: local ? "local" : "cloud"
   };
 }
-function devModeFilePath(homeDir = homedir2()) {
+function devModeFilePath(homeDir = heyspexHome()) {
   return join2(homeDir, ".heyspex", "dev-mode.json");
 }
 var defaultReadFile = (p) => readFileSync2(p, "utf8");
 function readLocalDevModeRecord({
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile
 } = {}) {
   let raw;
@@ -114,7 +126,7 @@ function readLocalDevModeRecord({
 }
 function resolveDevMode({
   env = process.env,
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = void 0
 } = {}) {
@@ -228,7 +240,7 @@ function upsertCredentialsYamlKeys(homeDir, updates, deps = {}) {
   return filePath;
 }
 function readCredentialsMcpToken({
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile
 } = {}) {
   try {
@@ -265,7 +277,7 @@ async function discardResponseBody(res) {
 async function fetchCloudDevMode({
   consoleUrl,
   fetchImpl = fetch,
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   timeoutMs = 4e3
 }) {
@@ -305,7 +317,7 @@ var DevModeNotAdminError = class extends Error {
 };
 async function applyDevMode(targetMode, targetReliance, deps = {}) {
   const {
-    homeDir = homedir2(),
+    homeDir = heyspexHome(),
     fetchImpl = fetch,
     source = "cli",
     now = () => (/* @__PURE__ */ new Date()).toISOString(),