heyspex 0.2.0 → 0.2.1

package/dist/cli/hs-vault-pull.mjs

@@ -18,6 +18,10 @@ var __esm = (fn, res) => function __init() {
 var __commonJS = (cb, mod) => function __require2() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc2) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -59,11 +63,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 +178,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 +191,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 +203,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 +213,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 +248,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 +296,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 +343,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 +450,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,29 +481,32 @@ 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";
+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";
 var init_dev_mode = __esm({
   "scripts/lib/dev-mode.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
   }
 });
 
 // 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";
 var init_console_url_resolver = __esm({
   "scripts/lib/console-url-resolver.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_dev_mode();
   }
 });
@@ -482,13 +549,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 = {}) {
@@ -521,6 +587,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.";
@@ -974,12 +1041,12 @@ var require_stringify = __commonJS({
         throw new TypeError('expected "' + language + '.stringify" to be a function');
       }
       data = Object.assign({}, file.data, data);
-      const open = opts.delimiters[0];
+      const open2 = opts.delimiters[0];
       const close = opts.delimiters[1];
       const matter4 = engine.stringify(data, options2).trim();
       let buf = "";
       if (matter4 !== "{}") {
-        buf = newline(open) + newline(matter4) + newline(close);
+        buf = newline(open2) + newline(matter4) + newline(close);
       }
       if (typeof file.excerpt === "string" && file.excerpt !== "") {
         if (str2.indexOf(file.excerpt.trim()) === -1) {
@@ -1007,11 +1074,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);
@@ -1076,7 +1143,7 @@ var require_parse = __commonJS({
 var require_gray_matter = __commonJS({
   "node_modules/gray-matter/index.js"(exports2, module2) {
     "use strict";
-    var fs9 = __require("fs");
+    var fs12 = __require("fs");
     var sections = require_section_matter();
     var defaults = require_defaults();
     var stringify = require_stringify();
@@ -1103,18 +1170,18 @@ var require_gray_matter = __commonJS({
     }
     function parseMatter(file, options2) {
       const opts = defaults(options2);
-      const open = opts.delimiters[0];
+      const open2 = opts.delimiters[0];
       const close = "\n" + opts.delimiters[1];
       let str2 = file.content;
       if (opts.language) {
         file.language = opts.language;
       }
-      const openLen = open.length;
-      if (!utils.startsWith(str2, open, openLen)) {
+      const openLen = open2.length;
+      if (!utils.startsWith(str2, open2, openLen)) {
         excerpt(file, opts);
         return file;
       }
-      if (str2.charAt(openLen) === open.slice(-1)) {
+      if (str2.charAt(openLen) === open2.slice(-1)) {
         return file;
       }
       str2 = str2.slice(openLen);
@@ -1160,7 +1227,7 @@ var require_gray_matter = __commonJS({
       return stringify(file, data, options2);
     };
     matter4.read = function(filepath, options2) {
-      const str2 = fs9.readFileSync(filepath, "utf8");
+      const str2 = fs12.readFileSync(filepath, "utf8");
       const file = matter4(str2, options2);
       file.path = filepath;
       return file;
@@ -1170,9 +1237,9 @@ var require_gray_matter = __commonJS({
     };
     matter4.language = function(str2, options2) {
       const opts = defaults(options2);
-      const open = opts.delimiters[0];
+      const open2 = opts.delimiters[0];
       if (matter4.test(str2)) {
-        str2 = str2.slice(open.length);
+        str2 = str2.slice(open2.length);
       }
       const language = str2.slice(0, str2.search(/\r?\n/));
       return {
@@ -1214,7 +1281,7 @@ var init_diagnose_skeleton = __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";
@@ -1237,6 +1304,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;
@@ -1265,7 +1334,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";
@@ -1707,7 +1776,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",
@@ -2900,18 +2975,50 @@ 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()
+        )
       ]
     );
   }
 });
 
 // spex-console/src/lib/api-key-service.ts
-import { createHash, randomBytes, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
+import { createHash as createHash2, randomBytes, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 var DEFAULT_ROTATION_GRACE_WINDOW_MS;
 var init_api_key_service = __esm({
   "spex-console/src/lib/api-key-service.ts"() {
@@ -3070,7 +3177,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 path4 from "node:path";
 var init_vault_resolve2 = __esm({
@@ -3109,7 +3216,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 path5 from "node:path";
 function fallbackSpecsDir() {
   const override = process.env.HEYSPEX_VAULT_DIR;
@@ -3142,7 +3249,7 @@ var init_active = __esm({
 });
 
 // spex-console/src/lib/control-plane/statusline-focus-cache.ts
-import fs2 from "node:fs";
+import fs4 from "node:fs";
 import path6 from "node:path";
 var init_statusline_focus_cache = __esm({
   "spex-console/src/lib/control-plane/statusline-focus-cache.ts"() {
@@ -3462,8 +3569,8 @@ function singleFlightDebounce(fn, delayMs) {
     })();
   }
   return function debounced() {
-    return new Promise((resolve4, reject) => {
-      const resolver = { resolve: resolve4, reject };
+    return new Promise((resolve7, reject) => {
+      const resolver = { resolve: resolve7, reject };
       if (inFlight) {
         if (queuedResolvers) {
           queuedResolvers.push(resolver);
@@ -3756,6 +3863,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]+)$/);
@@ -3820,6 +3976,9 @@ ${fm}
 ---
 ${body}`;
 }
+function parseSpecMarkdown(raw) {
+  return (0, import_gray_matter.default)(raw);
+}
 var import_gray_matter, YAML_STRINGIFY_OPTIONS;
 var init_vault_frontmatter = __esm({
   "spex-console/src/lib/vault-frontmatter.ts"() {
@@ -3843,10 +4002,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 basename4 = 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}-${basename4}`;
 }
 function materializeSpecMarkdown(bundle) {
   return stringifySpecMarkdown(bundle.bodyText, bundle.frontmatter);
@@ -4155,6 +4314,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({
@@ -4385,6 +4577,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;
@@ -4398,11 +4591,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,
@@ -4543,12 +4743,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";
@@ -4806,7 +5007,7 @@ var init_diagnose_spawned = __esm({
 });
 
 // spex-console/src/lib/guardrail-naming.ts
-import fs3 from "node:fs";
+import fs5 from "node:fs";
 import path7 from "node:path";
 var init_guardrail_naming = __esm({
   "spex-console/src/lib/guardrail-naming.ts"() {
@@ -4815,8 +5016,8 @@ var init_guardrail_naming = __esm({
 });
 
 // spex-console/src/lib/indexer/parser.ts
-import { createHash as createHash2 } from "node:crypto";
-import { promises as fs4 } from "node:fs";
+import { createHash as createHash3 } from "node:crypto";
+import { promises as fs6 } from "node:fs";
 import path8 from "node:path";
 var import_gray_matter2;
 var init_parser = __esm({
@@ -4923,7 +5124,7 @@ var init_scoped_context = __esm({
 
 // spex-console/src/lib/indexer/indexer-service.ts
 import { spawnSync } from "node:child_process";
-import { promises as fs5 } from "node:fs";
+import { promises as fs7 } from "node:fs";
 import path9 from "node:path";
 var init_indexer_service = __esm({
   "spex-console/src/lib/indexer/indexer-service.ts"() {
@@ -4942,7 +5143,7 @@ var init_indexer_service = __esm({
 });
 
 // spex-console/src/lib/indexer/outbox-index-feeder.ts
-import { promises as fs6 } from "node:fs";
+import { promises as fs8 } from "node:fs";
 import path10 from "node:path";
 var init_outbox_index_feeder = __esm({
   "spex-console/src/lib/indexer/outbox-index-feeder.ts"() {
@@ -5322,8 +5523,8 @@ 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 { promises as fs7 } from "node:fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync12, statSync } from "node:fs";
+import { promises as fs9 } from "node:fs";
 import path13 from "node:path";
 import yaml3 from "js-yaml";
 function normalizeDateField(value) {
@@ -5365,18 +5566,18 @@ function extractBodyLinks(body) {
   return links;
 }
 function toSummary(absPath, root, fm, body) {
-  const basename = path13.basename(absPath).replace(/\.md$/i, "");
+  const basename4 = path13.basename(absPath).replace(/\.md$/i, "");
   const relPath = path13.relative(root, absPath).split(path13.sep).join("/");
   return {
-    id: typeof fm.id === "string" && fm.id ? fm.id : basename,
-    name: typeof fm.name === "string" && fm.name ? fm.name : basename,
+    id: typeof fm.id === "string" && fm.id ? fm.id : basename4,
+    name: typeof fm.name === "string" && fm.name ? fm.name : basename4,
     type: typeof fm.type === "string" ? fm.type : "unknown",
     status: typeof fm.status === "string" ? fm.status : "unknown",
     effort: typeof fm.effort === "number" ? fm.effort : null,
     owner: typeof fm.owner === "string" ? fm.owner : null,
     tags: Array.isArray(fm.tags) ? fm.tags.map(String) : [],
     archived: fm.archived === true,
-    basename,
+    basename: basename4,
     relPath,
     links: extractBodyLinks(body),
     created: normalizeDateField(fm.created),
@@ -5462,9 +5663,9 @@ function invalidateVaultCacheForFile(absPath) {
   else evictProcessVaultHotRows();
 }
 function specIdFromAbsPath(absPath) {
-  const basename = path13.basename(absPath).replace(/\.md$/i, "");
-  if (!basename) return null;
-  const parsed = parseSpecId(basename);
+  const basename4 = path13.basename(absPath).replace(/\.md$/i, "");
+  if (!basename4) return null;
+  const parsed = parseSpecId(basename4);
   if (parsed?.era === 3 && parsed.fileKey) return `HS-${parsed.fileKey.toUpperCase()}`;
   return null;
 }
@@ -5555,8 +5756,8 @@ async function writeSpecBytesToVault(relPath, content) {
   try {
     const absPath = path13.join(vaultRoot(), relPath);
     const dir = path13.dirname(absPath);
-    await fs7.mkdir(dir, { recursive: true });
-    await fs7.writeFile(absPath, content, "utf8");
+    await fs9.mkdir(dir, { recursive: true });
+    await fs9.writeFile(absPath, content, "utf8");
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (isLocalVaultMode()) {
@@ -5568,7 +5769,7 @@ async function writeSpecBytesToVault(relPath, content) {
 async function parseLoadedSpec(absPath, root) {
   let raw;
   try {
-    raw = await fs7.readFile(absPath, "utf8");
+    raw = await fs9.readFile(absPath, "utf8");
   } catch {
     return null;
   }
@@ -5718,45 +5919,1761 @@ var init_vault = __esm({
   }
 });
 
-// spex-console/bin/hs-vault-pull.ts
-import { readFileSync as readFileSync12 } from "node:fs";
-import path14 from "node:path";
-import process4 from "node:process";
+// node_modules/readdirp/esm/index.js
+import { stat, lstat, readdir, realpath } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { resolve as presolve, relative as prelative, join as pjoin, sep as psep } from "node:path";
+function readdirp(root, options2 = {}) {
+  let type = options2.entryType || options2.type;
+  if (type === "both")
+    type = EntryTypes.FILE_DIR_TYPE;
+  if (type)
+    options2.type = type;
+  if (!root) {
+    throw new Error("readdirp: root argument is required. Usage: readdirp(root, options)");
+  } else if (typeof root !== "string") {
+    throw new TypeError("readdirp: root argument must be a string. Usage: readdirp(root, options)");
+  } else if (type && !ALL_TYPES.includes(type)) {
+    throw new Error(`readdirp: Invalid type passed. Use one of ${ALL_TYPES.join(", ")}`);
+  }
+  options2.root = root;
+  return new ReaddirpStream(options2);
+}
+var EntryTypes, defaultOptions, RECURSIVE_ERROR_CODE, NORMAL_FLOW_ERRORS, ALL_TYPES, DIR_TYPES, FILE_TYPES, isNormalFlowError, wantBigintFsStats, emptyFn, normalizeFilter, ReaddirpStream;
+var init_esm = __esm({
+  "node_modules/readdirp/esm/index.js"() {
+    "use strict";
+    EntryTypes = {
+      FILE_TYPE: "files",
+      DIR_TYPE: "directories",
+      FILE_DIR_TYPE: "files_directories",
+      EVERYTHING_TYPE: "all"
+    };
+    defaultOptions = {
+      root: ".",
+      fileFilter: (_entryInfo) => true,
+      directoryFilter: (_entryInfo) => true,
+      type: EntryTypes.FILE_TYPE,
+      lstat: false,
+      depth: 2147483648,
+      alwaysStat: false,
+      highWaterMark: 4096
+    };
+    Object.freeze(defaultOptions);
+    RECURSIVE_ERROR_CODE = "READDIRP_RECURSIVE_ERROR";
+    NORMAL_FLOW_ERRORS = /* @__PURE__ */ new Set(["ENOENT", "EPERM", "EACCES", "ELOOP", RECURSIVE_ERROR_CODE]);
+    ALL_TYPES = [
+      EntryTypes.DIR_TYPE,
+      EntryTypes.EVERYTHING_TYPE,
+      EntryTypes.FILE_DIR_TYPE,
+      EntryTypes.FILE_TYPE
+    ];
+    DIR_TYPES = /* @__PURE__ */ new Set([
+      EntryTypes.DIR_TYPE,
+      EntryTypes.EVERYTHING_TYPE,
+      EntryTypes.FILE_DIR_TYPE
+    ]);
+    FILE_TYPES = /* @__PURE__ */ new Set([
+      EntryTypes.EVERYTHING_TYPE,
+      EntryTypes.FILE_DIR_TYPE,
+      EntryTypes.FILE_TYPE
+    ]);
+    isNormalFlowError = (error) => NORMAL_FLOW_ERRORS.has(error.code);
+    wantBigintFsStats = process.platform === "win32";
+    emptyFn = (_entryInfo) => true;
+    normalizeFilter = (filter) => {
+      if (filter === void 0)
+        return emptyFn;
+      if (typeof filter === "function")
+        return filter;
+      if (typeof filter === "string") {
+        const fl = filter.trim();
+        return (entry) => entry.basename === fl;
+      }
+      if (Array.isArray(filter)) {
+        const trItems = filter.map((item) => item.trim());
+        return (entry) => trItems.some((f) => entry.basename === f);
+      }
+      return emptyFn;
+    };
+    ReaddirpStream = class extends Readable {
+      constructor(options2 = {}) {
+        super({
+          objectMode: true,
+          autoDestroy: true,
+          highWaterMark: options2.highWaterMark
+        });
+        const opts = { ...defaultOptions, ...options2 };
+        const { root, type } = opts;
+        this._fileFilter = normalizeFilter(opts.fileFilter);
+        this._directoryFilter = normalizeFilter(opts.directoryFilter);
+        const statMethod = opts.lstat ? lstat : stat;
+        if (wantBigintFsStats) {
+          this._stat = (path15) => statMethod(path15, { bigint: true });
+        } else {
+          this._stat = statMethod;
+        }
+        this._maxDepth = opts.depth ?? defaultOptions.depth;
+        this._wantsDir = type ? DIR_TYPES.has(type) : false;
+        this._wantsFile = type ? FILE_TYPES.has(type) : false;
+        this._wantsEverything = type === EntryTypes.EVERYTHING_TYPE;
+        this._root = presolve(root);
+        this._isDirent = !opts.alwaysStat;
+        this._statsProp = this._isDirent ? "dirent" : "stats";
+        this._rdOptions = { encoding: "utf8", withFileTypes: this._isDirent };
+        this.parents = [this._exploreDir(root, 1)];
+        this.reading = false;
+        this.parent = void 0;
+      }
+      async _read(batch) {
+        if (this.reading)
+          return;
+        this.reading = true;
+        try {
+          while (!this.destroyed && batch > 0) {
+            const par = this.parent;
+            const fil = par && par.files;
+            if (fil && fil.length > 0) {
+              const { path: path15, depth } = par;
+              const slice = fil.splice(0, batch).map((dirent) => this._formatEntry(dirent, path15));
+              const awaited = await Promise.all(slice);
+              for (const entry of awaited) {
+                if (!entry)
+                  continue;
+                if (this.destroyed)
+                  return;
+                const entryType = await this._getEntryType(entry);
+                if (entryType === "directory" && this._directoryFilter(entry)) {
+                  if (depth <= this._maxDepth) {
+                    this.parents.push(this._exploreDir(entry.fullPath, depth + 1));
+                  }
+                  if (this._wantsDir) {
+                    this.push(entry);
+                    batch--;
+                  }
+                } else if ((entryType === "file" || this._includeAsFile(entry)) && this._fileFilter(entry)) {
+                  if (this._wantsFile) {
+                    this.push(entry);
+                    batch--;
+                  }
+                }
+              }
+            } else {
+              const parent = this.parents.pop();
+              if (!parent) {
+                this.push(null);
+                break;
+              }
+              this.parent = await parent;
+              if (this.destroyed)
+                return;
+            }
+          }
+        } catch (error) {
+          this.destroy(error);
+        } finally {
+          this.reading = false;
+        }
+      }
+      async _exploreDir(path15, depth) {
+        let files;
+        try {
+          files = await readdir(path15, this._rdOptions);
+        } catch (error) {
+          this._onError(error);
+        }
+        return { files, depth, path: path15 };
+      }
+      async _formatEntry(dirent, path15) {
+        let entry;
+        const basename4 = this._isDirent ? dirent.name : dirent;
+        try {
+          const fullPath = presolve(pjoin(path15, basename4));
+          entry = { path: prelative(this._root, fullPath), fullPath, basename: basename4 };
+          entry[this._statsProp] = this._isDirent ? dirent : await this._stat(fullPath);
+        } catch (err) {
+          this._onError(err);
+          return;
+        }
+        return entry;
+      }
+      _onError(err) {
+        if (isNormalFlowError(err) && !this.destroyed) {
+          this.emit("warn", err);
+        } else {
+          this.destroy(err);
+        }
+      }
+      async _getEntryType(entry) {
+        if (!entry && this._statsProp in entry) {
+          return "";
+        }
+        const stats = entry[this._statsProp];
+        if (stats.isFile())
+          return "file";
+        if (stats.isDirectory())
+          return "directory";
+        if (stats && stats.isSymbolicLink()) {
+          const full = entry.fullPath;
+          try {
+            const entryRealPath = await realpath(full);
+            const entryRealPathStats = await lstat(entryRealPath);
+            if (entryRealPathStats.isFile()) {
+              return "file";
+            }
+            if (entryRealPathStats.isDirectory()) {
+              const len = entryRealPath.length;
+              if (full.startsWith(entryRealPath) && full.substr(len, 1) === psep) {
+                const recursiveError = new Error(`Circular symlink detected: "${full}" points to "${entryRealPath}"`);
+                recursiveError.code = RECURSIVE_ERROR_CODE;
+                return this._onError(recursiveError);
+              }
+              return "directory";
+            }
+          } catch (error) {
+            this._onError(error);
+            return "";
+          }
+        }
+      }
+      _includeAsFile(entry) {
+        const stats = entry && entry[this._statsProp];
+        return stats && this._wantsEverything && !stats.isDirectory();
+      }
+    };
+  }
+});
 
-// spex-console/src/lib/cli/control-shared.ts
-init_hs_command();
-init_console_fetch();
-init_credentials();
-init_session_owner();
-init_vault_less_endpoints();
-init_registry_file();
-import path from "node:path";
-var VAULT_ID_HEADER = "x-heyspex-vault-id";
-var ACCOUNT_ID_HEADER = "x-heyspex-account-id";
-function scopeHeadersFor(scope, method, path15) {
-  if (scope === "none") {
-    if (!isVaultLessEndpoint(method, path15)) {
-      throw new Error(
-        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path15} is vault-scoped and must name { accountId, vaultId }.`
-      );
+// node_modules/chokidar/esm/handler.js
+import { watchFile, unwatchFile, watch as fs_watch } from "fs";
+import { open, stat as stat2, lstat as lstat2, realpath as fsrealpath } from "fs/promises";
+import * as sysPath from "path";
+import { type as osType } from "os";
+function createFsWatchInstance(path15, options2, listener, errHandler, emitRaw) {
+  const handleEvent = (rawEvent, evPath) => {
+    listener(path15);
+    emitRaw(rawEvent, evPath, { watchedPath: path15 });
+    if (evPath && path15 !== evPath) {
+      fsWatchBroadcast(sysPath.resolve(path15, evPath), KEY_LISTENERS, sysPath.join(path15, evPath));
     }
-    return {};
-  }
-  return { [VAULT_ID_HEADER]: scope.vaultId, [ACCOUNT_ID_HEADER]: scope.accountId };
-}
-function cloudRequestScope(scope) {
-  const named = { accountId: scope.accountId, vaultId: scope.vaultId };
-  return {
-    ...named,
-    headersFor: (method, path15) => isVaultLessEndpoint(method, path15) ? {} : scopeHeadersFor(named, method, path15)
   };
+  try {
+    return fs_watch(path15, {
+      persistent: options2.persistent
+    }, handleEvent);
+  } catch (error) {
+    errHandler(error);
+    return void 0;
+  }
 }
+var STR_DATA, STR_END, STR_CLOSE, EMPTY_FN, pl, isWindows, isMacos, isLinux, isFreeBSD, isIBMi, EVENTS, EV, THROTTLE_MODE_WATCH, statMethods, KEY_LISTENERS, KEY_ERR, KEY_RAW, HANDLER_KEYS, binaryExtensions, isBinaryPath, foreach, addAndConvert, clearItem, delFromSet, isEmptySet, FsWatchInstances, fsWatchBroadcast, setFsWatchListener, FsWatchFileInstances, setFsWatchFileListener, NodeFsHandler;
+var init_handler = __esm({
+  "node_modules/chokidar/esm/handler.js"() {
+    "use strict";
+    STR_DATA = "data";
+    STR_END = "end";
+    STR_CLOSE = "close";
+    EMPTY_FN = () => {
+    };
+    pl = process.platform;
+    isWindows = pl === "win32";
+    isMacos = pl === "darwin";
+    isLinux = pl === "linux";
+    isFreeBSD = pl === "freebsd";
+    isIBMi = osType() === "OS400";
+    EVENTS = {
+      ALL: "all",
+      READY: "ready",
+      ADD: "add",
+      CHANGE: "change",
+      ADD_DIR: "addDir",
+      UNLINK: "unlink",
+      UNLINK_DIR: "unlinkDir",
+      RAW: "raw",
+      ERROR: "error"
+    };
+    EV = EVENTS;
+    THROTTLE_MODE_WATCH = "watch";
+    statMethods = { lstat: lstat2, stat: stat2 };
+    KEY_LISTENERS = "listeners";
+    KEY_ERR = "errHandlers";
+    KEY_RAW = "rawEmitters";
+    HANDLER_KEYS = [KEY_LISTENERS, KEY_ERR, KEY_RAW];
+    binaryExtensions = /* @__PURE__ */ new Set([
+      "3dm",
+      "3ds",
+      "3g2",
+      "3gp",
+      "7z",
+      "a",
+      "aac",
+      "adp",
+      "afdesign",
+      "afphoto",
+      "afpub",
+      "ai",
+      "aif",
+      "aiff",
+      "alz",
+      "ape",
+      "apk",
+      "appimage",
+      "ar",
+      "arj",
+      "asf",
+      "au",
+      "avi",
+      "bak",
+      "baml",
+      "bh",
+      "bin",
+      "bk",
+      "bmp",
+      "btif",
+      "bz2",
+      "bzip2",
+      "cab",
+      "caf",
+      "cgm",
+      "class",
+      "cmx",
+      "cpio",
+      "cr2",
+      "cur",
+      "dat",
+      "dcm",
+      "deb",
+      "dex",
+      "djvu",
+      "dll",
+      "dmg",
+      "dng",
+      "doc",
+      "docm",
+      "docx",
+      "dot",
+      "dotm",
+      "dra",
+      "DS_Store",
+      "dsk",
+      "dts",
+      "dtshd",
+      "dvb",
+      "dwg",
+      "dxf",
+      "ecelp4800",
+      "ecelp7470",
+      "ecelp9600",
+      "egg",
+      "eol",
+      "eot",
+      "epub",
+      "exe",
+      "f4v",
+      "fbs",
+      "fh",
+      "fla",
+      "flac",
+      "flatpak",
+      "fli",
+      "flv",
+      "fpx",
+      "fst",
+      "fvt",
+      "g3",
+      "gh",
+      "gif",
+      "graffle",
+      "gz",
+      "gzip",
+      "h261",
+      "h263",
+      "h264",
+      "icns",
+      "ico",
+      "ief",
+      "img",
+      "ipa",
+      "iso",
+      "jar",
+      "jpeg",
+      "jpg",
+      "jpgv",
+      "jpm",
+      "jxr",
+      "key",
+      "ktx",
+      "lha",
+      "lib",
+      "lvp",
+      "lz",
+      "lzh",
+      "lzma",
+      "lzo",
+      "m3u",
+      "m4a",
+      "m4v",
+      "mar",
+      "mdi",
+      "mht",
+      "mid",
+      "midi",
+      "mj2",
+      "mka",
+      "mkv",
+      "mmr",
+      "mng",
+      "mobi",
+      "mov",
+      "movie",
+      "mp3",
+      "mp4",
+      "mp4a",
+      "mpeg",
+      "mpg",
+      "mpga",
+      "mxu",
+      "nef",
+      "npx",
+      "numbers",
+      "nupkg",
+      "o",
+      "odp",
+      "ods",
+      "odt",
+      "oga",
+      "ogg",
+      "ogv",
+      "otf",
+      "ott",
+      "pages",
+      "pbm",
+      "pcx",
+      "pdb",
+      "pdf",
+      "pea",
+      "pgm",
+      "pic",
+      "png",
+      "pnm",
+      "pot",
+      "potm",
+      "potx",
+      "ppa",
+      "ppam",
+      "ppm",
+      "pps",
+      "ppsm",
+      "ppsx",
+      "ppt",
+      "pptm",
+      "pptx",
+      "psd",
+      "pya",
+      "pyc",
+      "pyo",
+      "pyv",
+      "qt",
+      "rar",
+      "ras",
+      "raw",
+      "resources",
+      "rgb",
+      "rip",
+      "rlc",
+      "rmf",
+      "rmvb",
+      "rpm",
+      "rtf",
+      "rz",
+      "s3m",
+      "s7z",
+      "scpt",
+      "sgi",
+      "shar",
+      "snap",
+      "sil",
+      "sketch",
+      "slk",
+      "smv",
+      "snk",
+      "so",
+      "stl",
+      "suo",
+      "sub",
+      "swf",
+      "tar",
+      "tbz",
+      "tbz2",
+      "tga",
+      "tgz",
+      "thmx",
+      "tif",
+      "tiff",
+      "tlz",
+      "ttc",
+      "ttf",
+      "txz",
+      "udf",
+      "uvh",
+      "uvi",
+      "uvm",
+      "uvp",
+      "uvs",
+      "uvu",
+      "viv",
+      "vob",
+      "war",
+      "wav",
+      "wax",
+      "wbmp",
+      "wdp",
+      "weba",
+      "webm",
+      "webp",
+      "whl",
+      "wim",
+      "wm",
+      "wma",
+      "wmv",
+      "wmx",
+      "woff",
+      "woff2",
+      "wrm",
+      "wvx",
+      "xbm",
+      "xif",
+      "xla",
+      "xlam",
+      "xls",
+      "xlsb",
+      "xlsm",
+      "xlsx",
+      "xlt",
+      "xltm",
+      "xltx",
+      "xm",
+      "xmind",
+      "xpi",
+      "xpm",
+      "xwd",
+      "xz",
+      "z",
+      "zip",
+      "zipx"
+    ]);
+    isBinaryPath = (filePath) => binaryExtensions.has(sysPath.extname(filePath).slice(1).toLowerCase());
+    foreach = (val, fn) => {
+      if (val instanceof Set) {
+        val.forEach(fn);
+      } else {
+        fn(val);
+      }
+    };
+    addAndConvert = (main2, prop, item) => {
+      let container = main2[prop];
+      if (!(container instanceof Set)) {
+        main2[prop] = container = /* @__PURE__ */ new Set([container]);
+      }
+      container.add(item);
+    };
+    clearItem = (cont) => (key) => {
+      const set = cont[key];
+      if (set instanceof Set) {
+        set.clear();
+      } else {
+        delete cont[key];
+      }
+    };
+    delFromSet = (main2, prop, item) => {
+      const container = main2[prop];
+      if (container instanceof Set) {
+        container.delete(item);
+      } else if (container === item) {
+        delete main2[prop];
+      }
+    };
+    isEmptySet = (val) => val instanceof Set ? val.size === 0 : !val;
+    FsWatchInstances = /* @__PURE__ */ new Map();
+    fsWatchBroadcast = (fullPath, listenerType, val1, val2, val3) => {
+      const cont = FsWatchInstances.get(fullPath);
+      if (!cont)
+        return;
+      foreach(cont[listenerType], (listener) => {
+        listener(val1, val2, val3);
+      });
+    };
+    setFsWatchListener = (path15, fullPath, options2, handlers) => {
+      const { listener, errHandler, rawEmitter } = handlers;
+      let cont = FsWatchInstances.get(fullPath);
+      let watcher;
+      if (!options2.persistent) {
+        watcher = createFsWatchInstance(path15, options2, listener, errHandler, rawEmitter);
+        if (!watcher)
+          return;
+        return watcher.close.bind(watcher);
+      }
+      if (cont) {
+        addAndConvert(cont, KEY_LISTENERS, listener);
+        addAndConvert(cont, KEY_ERR, errHandler);
+        addAndConvert(cont, KEY_RAW, rawEmitter);
+      } else {
+        watcher = createFsWatchInstance(
+          path15,
+          options2,
+          fsWatchBroadcast.bind(null, fullPath, KEY_LISTENERS),
+          errHandler,
+          // no need to use broadcast here
+          fsWatchBroadcast.bind(null, fullPath, KEY_RAW)
+        );
+        if (!watcher)
+          return;
+        watcher.on(EV.ERROR, async (error) => {
+          const broadcastErr = fsWatchBroadcast.bind(null, fullPath, KEY_ERR);
+          if (cont)
+            cont.watcherUnusable = true;
+          if (isWindows && error.code === "EPERM") {
+            try {
+              const fd = await open(path15, "r");
+              await fd.close();
+              broadcastErr(error);
+            } catch (err) {
+            }
+          } else {
+            broadcastErr(error);
+          }
+        });
+        cont = {
+          listeners: listener,
+          errHandlers: errHandler,
+          rawEmitters: rawEmitter,
+          watcher
+        };
+        FsWatchInstances.set(fullPath, cont);
+      }
+      return () => {
+        delFromSet(cont, KEY_LISTENERS, listener);
+        delFromSet(cont, KEY_ERR, errHandler);
+        delFromSet(cont, KEY_RAW, rawEmitter);
+        if (isEmptySet(cont.listeners)) {
+          cont.watcher.close();
+          FsWatchInstances.delete(fullPath);
+          HANDLER_KEYS.forEach(clearItem(cont));
+          cont.watcher = void 0;
+          Object.freeze(cont);
+        }
+      };
+    };
+    FsWatchFileInstances = /* @__PURE__ */ new Map();
+    setFsWatchFileListener = (path15, fullPath, options2, handlers) => {
+      const { listener, rawEmitter } = handlers;
+      let cont = FsWatchFileInstances.get(fullPath);
+      const copts = cont && cont.options;
+      if (copts && (copts.persistent < options2.persistent || copts.interval > options2.interval)) {
+        unwatchFile(fullPath);
+        cont = void 0;
+      }
+      if (cont) {
+        addAndConvert(cont, KEY_LISTENERS, listener);
+        addAndConvert(cont, KEY_RAW, rawEmitter);
+      } else {
+        cont = {
+          listeners: listener,
+          rawEmitters: rawEmitter,
+          options: options2,
+          watcher: watchFile(fullPath, options2, (curr, prev) => {
+            foreach(cont.rawEmitters, (rawEmitter2) => {
+              rawEmitter2(EV.CHANGE, fullPath, { curr, prev });
+            });
+            const currmtime = curr.mtimeMs;
+            if (curr.size !== prev.size || currmtime > prev.mtimeMs || currmtime === 0) {
+              foreach(cont.listeners, (listener2) => listener2(path15, curr));
+            }
+          })
+        };
+        FsWatchFileInstances.set(fullPath, cont);
+      }
+      return () => {
+        delFromSet(cont, KEY_LISTENERS, listener);
+        delFromSet(cont, KEY_RAW, rawEmitter);
+        if (isEmptySet(cont.listeners)) {
+          FsWatchFileInstances.delete(fullPath);
+          unwatchFile(fullPath);
+          cont.options = cont.watcher = void 0;
+          Object.freeze(cont);
+        }
+      };
+    };
+    NodeFsHandler = class {
+      constructor(fsW) {
+        this.fsw = fsW;
+        this._boundHandleError = (error) => fsW._handleError(error);
+      }
+      /**
+       * Watch file for changes with fs_watchFile or fs_watch.
+       * @param path to file or dir
+       * @param listener on fs change
+       * @returns closer for the watcher instance
+       */
+      _watchWithNodeFs(path15, listener) {
+        const opts = this.fsw.options;
+        const directory = sysPath.dirname(path15);
+        const basename4 = sysPath.basename(path15);
+        const parent = this.fsw._getWatchedDir(directory);
+        parent.add(basename4);
+        const absolutePath = sysPath.resolve(path15);
+        const options2 = {
+          persistent: opts.persistent
+        };
+        if (!listener)
+          listener = EMPTY_FN;
+        let closer;
+        if (opts.usePolling) {
+          const enableBin = opts.interval !== opts.binaryInterval;
+          options2.interval = enableBin && isBinaryPath(basename4) ? opts.binaryInterval : opts.interval;
+          closer = setFsWatchFileListener(path15, absolutePath, options2, {
+            listener,
+            rawEmitter: this.fsw._emitRaw
+          });
+        } else {
+          closer = setFsWatchListener(path15, absolutePath, options2, {
+            listener,
+            errHandler: this._boundHandleError,
+            rawEmitter: this.fsw._emitRaw
+          });
+        }
+        return closer;
+      }
+      /**
+       * Watch a file and emit add event if warranted.
+       * @returns closer for the watcher instance
+       */
+      _handleFile(file, stats, initialAdd) {
+        if (this.fsw.closed) {
+          return;
+        }
+        const dirname7 = sysPath.dirname(file);
+        const basename4 = sysPath.basename(file);
+        const parent = this.fsw._getWatchedDir(dirname7);
+        let prevStats = stats;
+        if (parent.has(basename4))
+          return;
+        const listener = async (path15, newStats) => {
+          if (!this.fsw._throttle(THROTTLE_MODE_WATCH, file, 5))
+            return;
+          if (!newStats || newStats.mtimeMs === 0) {
+            try {
+              const newStats2 = await stat2(file);
+              if (this.fsw.closed)
+                return;
+              const at = newStats2.atimeMs;
+              const mt = newStats2.mtimeMs;
+              if (!at || at <= mt || mt !== prevStats.mtimeMs) {
+                this.fsw._emit(EV.CHANGE, file, newStats2);
+              }
+              if ((isMacos || isLinux || isFreeBSD) && prevStats.ino !== newStats2.ino) {
+                this.fsw._closeFile(path15);
+                prevStats = newStats2;
+                const closer2 = this._watchWithNodeFs(file, listener);
+                if (closer2)
+                  this.fsw._addPathCloser(path15, closer2);
+              } else {
+                prevStats = newStats2;
+              }
+            } catch (error) {
+              this.fsw._remove(dirname7, basename4);
+            }
+          } else if (parent.has(basename4)) {
+            const at = newStats.atimeMs;
+            const mt = newStats.mtimeMs;
+            if (!at || at <= mt || mt !== prevStats.mtimeMs) {
+              this.fsw._emit(EV.CHANGE, file, newStats);
+            }
+            prevStats = newStats;
+          }
+        };
+        const closer = this._watchWithNodeFs(file, listener);
+        if (!(initialAdd && this.fsw.options.ignoreInitial) && this.fsw._isntIgnored(file)) {
+          if (!this.fsw._throttle(EV.ADD, file, 0))
+            return;
+          this.fsw._emit(EV.ADD, file, stats);
+        }
+        return closer;
+      }
+      /**
+       * Handle symlinks encountered while reading a dir.
+       * @param entry returned by readdirp
+       * @param directory path of dir being read
+       * @param path of this item
+       * @param item basename of this item
+       * @returns true if no more processing is needed for this entry.
+       */
+      async _handleSymlink(entry, directory, path15, item) {
+        if (this.fsw.closed) {
+          return;
+        }
+        const full = entry.fullPath;
+        const dir = this.fsw._getWatchedDir(directory);
+        if (!this.fsw.options.followSymlinks) {
+          this.fsw._incrReadyCount();
+          let linkPath;
+          try {
+            linkPath = await fsrealpath(path15);
+          } catch (e) {
+            this.fsw._emitReady();
+            return true;
+          }
+          if (this.fsw.closed)
+            return;
+          if (dir.has(item)) {
+            if (this.fsw._symlinkPaths.get(full) !== linkPath) {
+              this.fsw._symlinkPaths.set(full, linkPath);
+              this.fsw._emit(EV.CHANGE, path15, entry.stats);
+            }
+          } else {
+            dir.add(item);
+            this.fsw._symlinkPaths.set(full, linkPath);
+            this.fsw._emit(EV.ADD, path15, entry.stats);
+          }
+          this.fsw._emitReady();
+          return true;
+        }
+        if (this.fsw._symlinkPaths.has(full)) {
+          return true;
+        }
+        this.fsw._symlinkPaths.set(full, true);
+      }
+      _handleRead(directory, initialAdd, wh, target, dir, depth, throttler) {
+        directory = sysPath.join(directory, "");
+        throttler = this.fsw._throttle("readdir", directory, 1e3);
+        if (!throttler)
+          return;
+        const previous = this.fsw._getWatchedDir(wh.path);
+        const current = /* @__PURE__ */ new Set();
+        let stream = this.fsw._readdirp(directory, {
+          fileFilter: (entry) => wh.filterPath(entry),
+          directoryFilter: (entry) => wh.filterDir(entry)
+        });
+        if (!stream)
+          return;
+        stream.on(STR_DATA, async (entry) => {
+          if (this.fsw.closed) {
+            stream = void 0;
+            return;
+          }
+          const item = entry.path;
+          let path15 = sysPath.join(directory, item);
+          current.add(item);
+          if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path15, item)) {
+            return;
+          }
+          if (this.fsw.closed) {
+            stream = void 0;
+            return;
+          }
+          if (item === target || !target && !previous.has(item)) {
+            this.fsw._incrReadyCount();
+            path15 = sysPath.join(dir, sysPath.relative(dir, path15));
+            this._addToNodeFs(path15, initialAdd, wh, depth + 1);
+          }
+        }).on(EV.ERROR, this._boundHandleError);
+        return new Promise((resolve7, reject) => {
+          if (!stream)
+            return reject();
+          stream.once(STR_END, () => {
+            if (this.fsw.closed) {
+              stream = void 0;
+              return;
+            }
+            const wasThrottled = throttler ? throttler.clear() : false;
+            resolve7(void 0);
+            previous.getChildren().filter((item) => {
+              return item !== directory && !current.has(item);
+            }).forEach((item) => {
+              this.fsw._remove(directory, item);
+            });
+            stream = void 0;
+            if (wasThrottled)
+              this._handleRead(directory, false, wh, target, dir, depth, throttler);
+          });
+        });
+      }
+      /**
+       * Read directory to add / remove files from `@watched` list and re-read it on change.
+       * @param dir fs path
+       * @param stats
+       * @param initialAdd
+       * @param depth relative to user-supplied path
+       * @param target child path targeted for watch
+       * @param wh Common watch helpers for this path
+       * @param realpath
+       * @returns closer for the watcher instance.
+       */
+      async _handleDir(dir, stats, initialAdd, depth, target, wh, realpath2) {
+        const parentDir = this.fsw._getWatchedDir(sysPath.dirname(dir));
+        const tracked = parentDir.has(sysPath.basename(dir));
+        if (!(initialAdd && this.fsw.options.ignoreInitial) && !target && !tracked) {
+          this.fsw._emit(EV.ADD_DIR, dir, stats);
+        }
+        parentDir.add(sysPath.basename(dir));
+        this.fsw._getWatchedDir(dir);
+        let throttler;
+        let closer;
+        const oDepth = this.fsw.options.depth;
+        if ((oDepth == null || depth <= oDepth) && !this.fsw._symlinkPaths.has(realpath2)) {
+          if (!target) {
+            await this._handleRead(dir, initialAdd, wh, target, dir, depth, throttler);
+            if (this.fsw.closed)
+              return;
+          }
+          closer = this._watchWithNodeFs(dir, (dirPath, stats2) => {
+            if (stats2 && stats2.mtimeMs === 0)
+              return;
+            this._handleRead(dirPath, false, wh, target, dir, depth, throttler);
+          });
+        }
+        return closer;
+      }
+      /**
+       * Handle added file, directory, or glob pattern.
+       * Delegates call to _handleFile / _handleDir after checks.
+       * @param path to file or ir
+       * @param initialAdd was the file added at watch instantiation?
+       * @param priorWh depth relative to user-supplied path
+       * @param depth Child path actually targeted for watch
+       * @param target Child path actually targeted for watch
+       */
+      async _addToNodeFs(path15, initialAdd, priorWh, depth, target) {
+        const ready = this.fsw._emitReady;
+        if (this.fsw._isIgnored(path15) || this.fsw.closed) {
+          ready();
+          return false;
+        }
+        const wh = this.fsw._getWatchHelpers(path15);
+        if (priorWh) {
+          wh.filterPath = (entry) => priorWh.filterPath(entry);
+          wh.filterDir = (entry) => priorWh.filterDir(entry);
+        }
+        try {
+          const stats = await statMethods[wh.statMethod](wh.watchPath);
+          if (this.fsw.closed)
+            return;
+          if (this.fsw._isIgnored(wh.watchPath, stats)) {
+            ready();
+            return false;
+          }
+          const follow = this.fsw.options.followSymlinks;
+          let closer;
+          if (stats.isDirectory()) {
+            const absPath = sysPath.resolve(path15);
+            const targetPath = follow ? await fsrealpath(path15) : path15;
+            if (this.fsw.closed)
+              return;
+            closer = await this._handleDir(wh.watchPath, stats, initialAdd, depth, target, wh, targetPath);
+            if (this.fsw.closed)
+              return;
+            if (absPath !== targetPath && targetPath !== void 0) {
+              this.fsw._symlinkPaths.set(absPath, targetPath);
+            }
+          } else if (stats.isSymbolicLink()) {
+            const targetPath = follow ? await fsrealpath(path15) : path15;
+            if (this.fsw.closed)
+              return;
+            const parent = sysPath.dirname(wh.watchPath);
+            this.fsw._getWatchedDir(parent).add(wh.watchPath);
+            this.fsw._emit(EV.ADD, wh.watchPath, stats);
+            closer = await this._handleDir(parent, stats, initialAdd, depth, path15, wh, targetPath);
+            if (this.fsw.closed)
+              return;
+            if (targetPath !== void 0) {
+              this.fsw._symlinkPaths.set(sysPath.resolve(path15), targetPath);
+            }
+          } else {
+            closer = this._handleFile(wh.watchPath, stats, initialAdd);
+          }
+          ready();
+          if (closer)
+            this.fsw._addPathCloser(path15, closer);
+          return false;
+        } catch (error) {
+          if (this.fsw._handleError(error)) {
+            ready();
+            return path15;
+          }
+        }
+      }
+    };
+  }
+});
 
-// spex-console/src/lib/cli/init.ts
-init_console_url_resolver();
-import { randomUUID } from "node:crypto";
-function parseVaultId(content) {
-  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
+// node_modules/chokidar/esm/index.js
+var esm_exports = {};
+__export(esm_exports, {
+  FSWatcher: () => FSWatcher,
+  WatchHelper: () => WatchHelper,
+  default: () => esm_default,
+  watch: () => watch
+});
+import { stat as statcb } from "fs";
+import { stat as stat3, readdir as readdir2 } from "fs/promises";
+import { EventEmitter } from "events";
+import * as sysPath2 from "path";
+function arrify(item) {
+  return Array.isArray(item) ? item : [item];
+}
+function createPattern(matcher) {
+  if (typeof matcher === "function")
+    return matcher;
+  if (typeof matcher === "string")
+    return (string) => matcher === string;
+  if (matcher instanceof RegExp)
+    return (string) => matcher.test(string);
+  if (typeof matcher === "object" && matcher !== null) {
+    return (string) => {
+      if (matcher.path === string)
+        return true;
+      if (matcher.recursive) {
+        const relative3 = sysPath2.relative(matcher.path, string);
+        if (!relative3) {
+          return false;
+        }
+        return !relative3.startsWith("..") && !sysPath2.isAbsolute(relative3);
+      }
+      return false;
+    };
+  }
+  return () => false;
+}
+function normalizePath(path15) {
+  if (typeof path15 !== "string")
+    throw new Error("string expected");
+  path15 = sysPath2.normalize(path15);
+  path15 = path15.replace(/\\/g, "/");
+  let prepend = false;
+  if (path15.startsWith("//"))
+    prepend = true;
+  const DOUBLE_SLASH_RE2 = /\/\//;
+  while (path15.match(DOUBLE_SLASH_RE2))
+    path15 = path15.replace(DOUBLE_SLASH_RE2, "/");
+  if (prepend)
+    path15 = "/" + path15;
+  return path15;
+}
+function matchPatterns(patterns, testString, stats) {
+  const path15 = normalizePath(testString);
+  for (let index2 = 0; index2 < patterns.length; index2++) {
+    const pattern = patterns[index2];
+    if (pattern(path15, stats)) {
+      return true;
+    }
+  }
+  return false;
+}
+function anymatch(matchers, testString) {
+  if (matchers == null) {
+    throw new TypeError("anymatch: specify first argument");
+  }
+  const matchersArray = arrify(matchers);
+  const patterns = matchersArray.map((matcher) => createPattern(matcher));
+  if (testString == null) {
+    return (testString2, stats) => {
+      return matchPatterns(patterns, testString2, stats);
+    };
+  }
+  return matchPatterns(patterns, testString);
+}
+function watch(paths, options2 = {}) {
+  const watcher = new FSWatcher(options2);
+  watcher.add(paths);
+  return watcher;
+}
+var SLASH, SLASH_SLASH, ONE_DOT, TWO_DOTS, STRING_TYPE, BACK_SLASH_RE, DOUBLE_SLASH_RE, DOT_RE, REPLACER_RE, isMatcherObject, unifyPaths, toUnix, normalizePathToUnix, normalizeIgnored, getAbsolutePath, EMPTY_SET, DirEntry, STAT_METHOD_F, STAT_METHOD_L, WatchHelper, FSWatcher, esm_default;
+var init_esm2 = __esm({
+  "node_modules/chokidar/esm/index.js"() {
+    "use strict";
+    init_esm();
+    init_handler();
+    SLASH = "/";
+    SLASH_SLASH = "//";
+    ONE_DOT = ".";
+    TWO_DOTS = "..";
+    STRING_TYPE = "string";
+    BACK_SLASH_RE = /\\/g;
+    DOUBLE_SLASH_RE = /\/\//;
+    DOT_RE = /\..*\.(sw[px])$|~$|\.subl.*\.tmp/;
+    REPLACER_RE = /^\.[/\\]/;
+    isMatcherObject = (matcher) => typeof matcher === "object" && matcher !== null && !(matcher instanceof RegExp);
+    unifyPaths = (paths_) => {
+      const paths = arrify(paths_).flat();
+      if (!paths.every((p) => typeof p === STRING_TYPE)) {
+        throw new TypeError(`Non-string provided as watch path: ${paths}`);
+      }
+      return paths.map(normalizePathToUnix);
+    };
+    toUnix = (string) => {
+      let str2 = string.replace(BACK_SLASH_RE, SLASH);
+      let prepend = false;
+      if (str2.startsWith(SLASH_SLASH)) {
+        prepend = true;
+      }
+      while (str2.match(DOUBLE_SLASH_RE)) {
+        str2 = str2.replace(DOUBLE_SLASH_RE, SLASH);
+      }
+      if (prepend) {
+        str2 = SLASH + str2;
+      }
+      return str2;
+    };
+    normalizePathToUnix = (path15) => toUnix(sysPath2.normalize(toUnix(path15)));
+    normalizeIgnored = (cwd = "") => (path15) => {
+      if (typeof path15 === "string") {
+        return normalizePathToUnix(sysPath2.isAbsolute(path15) ? path15 : sysPath2.join(cwd, path15));
+      } else {
+        return path15;
+      }
+    };
+    getAbsolutePath = (path15, cwd) => {
+      if (sysPath2.isAbsolute(path15)) {
+        return path15;
+      }
+      return sysPath2.join(cwd, path15);
+    };
+    EMPTY_SET = Object.freeze(/* @__PURE__ */ new Set());
+    DirEntry = class {
+      constructor(dir, removeWatcher) {
+        this.path = dir;
+        this._removeWatcher = removeWatcher;
+        this.items = /* @__PURE__ */ new Set();
+      }
+      add(item) {
+        const { items } = this;
+        if (!items)
+          return;
+        if (item !== ONE_DOT && item !== TWO_DOTS)
+          items.add(item);
+      }
+      async remove(item) {
+        const { items } = this;
+        if (!items)
+          return;
+        items.delete(item);
+        if (items.size > 0)
+          return;
+        const dir = this.path;
+        try {
+          await readdir2(dir);
+        } catch (err) {
+          if (this._removeWatcher) {
+            this._removeWatcher(sysPath2.dirname(dir), sysPath2.basename(dir));
+          }
+        }
+      }
+      has(item) {
+        const { items } = this;
+        if (!items)
+          return;
+        return items.has(item);
+      }
+      getChildren() {
+        const { items } = this;
+        if (!items)
+          return [];
+        return [...items.values()];
+      }
+      dispose() {
+        this.items.clear();
+        this.path = "";
+        this._removeWatcher = EMPTY_FN;
+        this.items = EMPTY_SET;
+        Object.freeze(this);
+      }
+    };
+    STAT_METHOD_F = "stat";
+    STAT_METHOD_L = "lstat";
+    WatchHelper = class {
+      constructor(path15, follow, fsw) {
+        this.fsw = fsw;
+        const watchPath = path15;
+        this.path = path15 = path15.replace(REPLACER_RE, "");
+        this.watchPath = watchPath;
+        this.fullWatchPath = sysPath2.resolve(watchPath);
+        this.dirParts = [];
+        this.dirParts.forEach((parts) => {
+          if (parts.length > 1)
+            parts.pop();
+        });
+        this.followSymlinks = follow;
+        this.statMethod = follow ? STAT_METHOD_F : STAT_METHOD_L;
+      }
+      entryPath(entry) {
+        return sysPath2.join(this.watchPath, sysPath2.relative(this.watchPath, entry.fullPath));
+      }
+      filterPath(entry) {
+        const { stats } = entry;
+        if (stats && stats.isSymbolicLink())
+          return this.filterDir(entry);
+        const resolvedPath = this.entryPath(entry);
+        return this.fsw._isntIgnored(resolvedPath, stats) && this.fsw._hasReadPermissions(stats);
+      }
+      filterDir(entry) {
+        return this.fsw._isntIgnored(this.entryPath(entry), entry.stats);
+      }
+    };
+    FSWatcher = class extends EventEmitter {
+      // Not indenting methods for history sake; for now.
+      constructor(_opts = {}) {
+        super();
+        this.closed = false;
+        this._closers = /* @__PURE__ */ new Map();
+        this._ignoredPaths = /* @__PURE__ */ new Set();
+        this._throttled = /* @__PURE__ */ new Map();
+        this._streams = /* @__PURE__ */ new Set();
+        this._symlinkPaths = /* @__PURE__ */ new Map();
+        this._watched = /* @__PURE__ */ new Map();
+        this._pendingWrites = /* @__PURE__ */ new Map();
+        this._pendingUnlinks = /* @__PURE__ */ new Map();
+        this._readyCount = 0;
+        this._readyEmitted = false;
+        const awf = _opts.awaitWriteFinish;
+        const DEF_AWF = { stabilityThreshold: 2e3, pollInterval: 100 };
+        const opts = {
+          // Defaults
+          persistent: true,
+          ignoreInitial: false,
+          ignorePermissionErrors: false,
+          interval: 100,
+          binaryInterval: 300,
+          followSymlinks: true,
+          usePolling: false,
+          // useAsync: false,
+          atomic: true,
+          // NOTE: overwritten later (depends on usePolling)
+          ..._opts,
+          // Change format
+          ignored: _opts.ignored ? arrify(_opts.ignored) : arrify([]),
+          awaitWriteFinish: awf === true ? DEF_AWF : typeof awf === "object" ? { ...DEF_AWF, ...awf } : false
+        };
+        if (isIBMi)
+          opts.usePolling = true;
+        if (opts.atomic === void 0)
+          opts.atomic = !opts.usePolling;
+        const envPoll = process.env.CHOKIDAR_USEPOLLING;
+        if (envPoll !== void 0) {
+          const envLower = envPoll.toLowerCase();
+          if (envLower === "false" || envLower === "0")
+            opts.usePolling = false;
+          else if (envLower === "true" || envLower === "1")
+            opts.usePolling = true;
+          else
+            opts.usePolling = !!envLower;
+        }
+        const envInterval = process.env.CHOKIDAR_INTERVAL;
+        if (envInterval)
+          opts.interval = Number.parseInt(envInterval, 10);
+        let readyCalls = 0;
+        this._emitReady = () => {
+          readyCalls++;
+          if (readyCalls >= this._readyCount) {
+            this._emitReady = EMPTY_FN;
+            this._readyEmitted = true;
+            process.nextTick(() => this.emit(EVENTS.READY));
+          }
+        };
+        this._emitRaw = (...args) => this.emit(EVENTS.RAW, ...args);
+        this._boundRemove = this._remove.bind(this);
+        this.options = opts;
+        this._nodeFsHandler = new NodeFsHandler(this);
+        Object.freeze(opts);
+      }
+      _addIgnoredPath(matcher) {
+        if (isMatcherObject(matcher)) {
+          for (const ignored of this._ignoredPaths) {
+            if (isMatcherObject(ignored) && ignored.path === matcher.path && ignored.recursive === matcher.recursive) {
+              return;
+            }
+          }
+        }
+        this._ignoredPaths.add(matcher);
+      }
+      _removeIgnoredPath(matcher) {
+        this._ignoredPaths.delete(matcher);
+        if (typeof matcher === "string") {
+          for (const ignored of this._ignoredPaths) {
+            if (isMatcherObject(ignored) && ignored.path === matcher) {
+              this._ignoredPaths.delete(ignored);
+            }
+          }
+        }
+      }
+      // Public methods
+      /**
+       * Adds paths to be watched on an existing FSWatcher instance.
+       * @param paths_ file or file list. Other arguments are unused
+       */
+      add(paths_, _origAdd, _internal) {
+        const { cwd } = this.options;
+        this.closed = false;
+        this._closePromise = void 0;
+        let paths = unifyPaths(paths_);
+        if (cwd) {
+          paths = paths.map((path15) => {
+            const absPath = getAbsolutePath(path15, cwd);
+            return absPath;
+          });
+        }
+        paths.forEach((path15) => {
+          this._removeIgnoredPath(path15);
+        });
+        this._userIgnored = void 0;
+        if (!this._readyCount)
+          this._readyCount = 0;
+        this._readyCount += paths.length;
+        Promise.all(paths.map(async (path15) => {
+          const res = await this._nodeFsHandler._addToNodeFs(path15, !_internal, void 0, 0, _origAdd);
+          if (res)
+            this._emitReady();
+          return res;
+        })).then((results) => {
+          if (this.closed)
+            return;
+          results.forEach((item) => {
+            if (item)
+              this.add(sysPath2.dirname(item), sysPath2.basename(_origAdd || item));
+          });
+        });
+        return this;
+      }
+      /**
+       * Close watchers or start ignoring events from specified paths.
+       */
+      unwatch(paths_) {
+        if (this.closed)
+          return this;
+        const paths = unifyPaths(paths_);
+        const { cwd } = this.options;
+        paths.forEach((path15) => {
+          if (!sysPath2.isAbsolute(path15) && !this._closers.has(path15)) {
+            if (cwd)
+              path15 = sysPath2.join(cwd, path15);
+            path15 = sysPath2.resolve(path15);
+          }
+          this._closePath(path15);
+          this._addIgnoredPath(path15);
+          if (this._watched.has(path15)) {
+            this._addIgnoredPath({
+              path: path15,
+              recursive: true
+            });
+          }
+          this._userIgnored = void 0;
+        });
+        return this;
+      }
+      /**
+       * Close watchers and remove all listeners from watched paths.
+       */
+      close() {
+        if (this._closePromise) {
+          return this._closePromise;
+        }
+        this.closed = true;
+        this.removeAllListeners();
+        const closers = [];
+        this._closers.forEach((closerList) => closerList.forEach((closer) => {
+          const promise = closer();
+          if (promise instanceof Promise)
+            closers.push(promise);
+        }));
+        this._streams.forEach((stream) => stream.destroy());
+        this._userIgnored = void 0;
+        this._readyCount = 0;
+        this._readyEmitted = false;
+        this._watched.forEach((dirent) => dirent.dispose());
+        this._closers.clear();
+        this._watched.clear();
+        this._streams.clear();
+        this._symlinkPaths.clear();
+        this._throttled.clear();
+        this._closePromise = closers.length ? Promise.all(closers).then(() => void 0) : Promise.resolve();
+        return this._closePromise;
+      }
+      /**
+       * Expose list of watched paths
+       * @returns for chaining
+       */
+      getWatched() {
+        const watchList = {};
+        this._watched.forEach((entry, dir) => {
+          const key = this.options.cwd ? sysPath2.relative(this.options.cwd, dir) : dir;
+          const index2 = key || ONE_DOT;
+          watchList[index2] = entry.getChildren().sort();
+        });
+        return watchList;
+      }
+      emitWithAll(event, args) {
+        this.emit(event, ...args);
+        if (event !== EVENTS.ERROR)
+          this.emit(EVENTS.ALL, event, ...args);
+      }
+      // Common helpers
+      // --------------
+      /**
+       * Normalize and emit events.
+       * Calling _emit DOES NOT MEAN emit() would be called!
+       * @param event Type of event
+       * @param path File or directory path
+       * @param stats arguments to be passed with event
+       * @returns the error if defined, otherwise the value of the FSWatcher instance's `closed` flag
+       */
+      async _emit(event, path15, stats) {
+        if (this.closed)
+          return;
+        const opts = this.options;
+        if (isWindows)
+          path15 = sysPath2.normalize(path15);
+        if (opts.cwd)
+          path15 = sysPath2.relative(opts.cwd, path15);
+        const args = [path15];
+        if (stats != null)
+          args.push(stats);
+        const awf = opts.awaitWriteFinish;
+        let pw;
+        if (awf && (pw = this._pendingWrites.get(path15))) {
+          pw.lastChange = /* @__PURE__ */ new Date();
+          return this;
+        }
+        if (opts.atomic) {
+          if (event === EVENTS.UNLINK) {
+            this._pendingUnlinks.set(path15, [event, ...args]);
+            setTimeout(() => {
+              this._pendingUnlinks.forEach((entry, path16) => {
+                this.emit(...entry);
+                this.emit(EVENTS.ALL, ...entry);
+                this._pendingUnlinks.delete(path16);
+              });
+            }, typeof opts.atomic === "number" ? opts.atomic : 100);
+            return this;
+          }
+          if (event === EVENTS.ADD && this._pendingUnlinks.has(path15)) {
+            event = EVENTS.CHANGE;
+            this._pendingUnlinks.delete(path15);
+          }
+        }
+        if (awf && (event === EVENTS.ADD || event === EVENTS.CHANGE) && this._readyEmitted) {
+          const awfEmit = (err, stats2) => {
+            if (err) {
+              event = EVENTS.ERROR;
+              args[0] = err;
+              this.emitWithAll(event, args);
+            } else if (stats2) {
+              if (args.length > 1) {
+                args[1] = stats2;
+              } else {
+                args.push(stats2);
+              }
+              this.emitWithAll(event, args);
+            }
+          };
+          this._awaitWriteFinish(path15, awf.stabilityThreshold, event, awfEmit);
+          return this;
+        }
+        if (event === EVENTS.CHANGE) {
+          const isThrottled = !this._throttle(EVENTS.CHANGE, path15, 50);
+          if (isThrottled)
+            return this;
+        }
+        if (opts.alwaysStat && stats === void 0 && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
+          const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path15) : path15;
+          let stats2;
+          try {
+            stats2 = await stat3(fullPath);
+          } catch (err) {
+          }
+          if (!stats2 || this.closed)
+            return;
+          args.push(stats2);
+        }
+        this.emitWithAll(event, args);
+        return this;
+      }
+      /**
+       * Common handler for errors
+       * @returns The error if defined, otherwise the value of the FSWatcher instance's `closed` flag
+       */
+      _handleError(error) {
+        const code = error && error.code;
+        if (error && code !== "ENOENT" && code !== "ENOTDIR" && (!this.options.ignorePermissionErrors || code !== "EPERM" && code !== "EACCES")) {
+          this.emit(EVENTS.ERROR, error);
+        }
+        return error || this.closed;
+      }
+      /**
+       * Helper utility for throttling
+       * @param actionType type being throttled
+       * @param path being acted upon
+       * @param timeout duration of time to suppress duplicate actions
+       * @returns tracking object or false if action should be suppressed
+       */
+      _throttle(actionType, path15, timeout) {
+        if (!this._throttled.has(actionType)) {
+          this._throttled.set(actionType, /* @__PURE__ */ new Map());
+        }
+        const action = this._throttled.get(actionType);
+        if (!action)
+          throw new Error("invalid throttle");
+        const actionPath = action.get(path15);
+        if (actionPath) {
+          actionPath.count++;
+          return false;
+        }
+        let timeoutObject;
+        const clear = () => {
+          const item = action.get(path15);
+          const count2 = item ? item.count : 0;
+          action.delete(path15);
+          clearTimeout(timeoutObject);
+          if (item)
+            clearTimeout(item.timeoutObject);
+          return count2;
+        };
+        timeoutObject = setTimeout(clear, timeout);
+        const thr = { timeoutObject, clear, count: 0 };
+        action.set(path15, thr);
+        return thr;
+      }
+      _incrReadyCount() {
+        return this._readyCount++;
+      }
+      /**
+       * Awaits write operation to finish.
+       * Polls a newly created file for size variations. When files size does not change for 'threshold' milliseconds calls callback.
+       * @param path being acted upon
+       * @param threshold Time in milliseconds a file size must be fixed before acknowledging write OP is finished
+       * @param event
+       * @param awfEmit Callback to be called when ready for event to be emitted.
+       */
+      _awaitWriteFinish(path15, threshold, event, awfEmit) {
+        const awf = this.options.awaitWriteFinish;
+        if (typeof awf !== "object")
+          return;
+        const pollInterval = awf.pollInterval;
+        let timeoutHandler;
+        let fullPath = path15;
+        if (this.options.cwd && !sysPath2.isAbsolute(path15)) {
+          fullPath = sysPath2.join(this.options.cwd, path15);
+        }
+        const now = /* @__PURE__ */ new Date();
+        const writes = this._pendingWrites;
+        function awaitWriteFinishFn(prevStat) {
+          statcb(fullPath, (err, curStat) => {
+            if (err || !writes.has(path15)) {
+              if (err && err.code !== "ENOENT")
+                awfEmit(err);
+              return;
+            }
+            const now2 = Number(/* @__PURE__ */ new Date());
+            if (prevStat && curStat.size !== prevStat.size) {
+              writes.get(path15).lastChange = now2;
+            }
+            const pw = writes.get(path15);
+            const df = now2 - pw.lastChange;
+            if (df >= threshold) {
+              writes.delete(path15);
+              awfEmit(void 0, curStat);
+            } else {
+              timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval, curStat);
+            }
+          });
+        }
+        if (!writes.has(path15)) {
+          writes.set(path15, {
+            lastChange: now,
+            cancelWait: () => {
+              writes.delete(path15);
+              clearTimeout(timeoutHandler);
+              return event;
+            }
+          });
+          timeoutHandler = setTimeout(awaitWriteFinishFn, pollInterval);
+        }
+      }
+      /**
+       * Determines whether user has asked to ignore this path.
+       */
+      _isIgnored(path15, stats) {
+        if (this.options.atomic && DOT_RE.test(path15))
+          return true;
+        if (!this._userIgnored) {
+          const { cwd } = this.options;
+          const ign = this.options.ignored;
+          const ignored = (ign || []).map(normalizeIgnored(cwd));
+          const ignoredPaths = [...this._ignoredPaths];
+          const list = [...ignoredPaths.map(normalizeIgnored(cwd)), ...ignored];
+          this._userIgnored = anymatch(list, void 0);
+        }
+        return this._userIgnored(path15, stats);
+      }
+      _isntIgnored(path15, stat4) {
+        return !this._isIgnored(path15, stat4);
+      }
+      /**
+       * Provides a set of common helpers and properties relating to symlink handling.
+       * @param path file or directory pattern being watched
+       */
+      _getWatchHelpers(path15) {
+        return new WatchHelper(path15, this.options.followSymlinks, this);
+      }
+      // Directory helpers
+      // -----------------
+      /**
+       * Provides directory tracking objects
+       * @param directory path of the directory
+       */
+      _getWatchedDir(directory) {
+        const dir = sysPath2.resolve(directory);
+        if (!this._watched.has(dir))
+          this._watched.set(dir, new DirEntry(dir, this._boundRemove));
+        return this._watched.get(dir);
+      }
+      // File helpers
+      // ------------
+      /**
+       * Check for read permissions: https://stackoverflow.com/a/11781404/1358405
+       */
+      _hasReadPermissions(stats) {
+        if (this.options.ignorePermissionErrors)
+          return true;
+        return Boolean(Number(stats.mode) & 256);
+      }
+      /**
+       * Handles emitting unlink events for
+       * files and directories, and via recursion, for
+       * files and directories within directories that are unlinked
+       * @param directory within which the following item is located
+       * @param item      base path of item/directory
+       */
+      _remove(directory, item, isDirectory) {
+        const path15 = sysPath2.join(directory, item);
+        const fullPath = sysPath2.resolve(path15);
+        isDirectory = isDirectory != null ? isDirectory : this._watched.has(path15) || this._watched.has(fullPath);
+        if (!this._throttle("remove", path15, 100))
+          return;
+        if (!isDirectory && this._watched.size === 1) {
+          this.add(directory, item, true);
+        }
+        const wp = this._getWatchedDir(path15);
+        const nestedDirectoryChildren = wp.getChildren();
+        nestedDirectoryChildren.forEach((nested) => this._remove(path15, nested));
+        const parent = this._getWatchedDir(directory);
+        const wasTracked = parent.has(item);
+        parent.remove(item);
+        if (this._symlinkPaths.has(fullPath)) {
+          this._symlinkPaths.delete(fullPath);
+        }
+        let relPath = path15;
+        if (this.options.cwd)
+          relPath = sysPath2.relative(this.options.cwd, path15);
+        if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
+          const event = this._pendingWrites.get(relPath).cancelWait();
+          if (event === EVENTS.ADD)
+            return;
+        }
+        this._watched.delete(path15);
+        this._watched.delete(fullPath);
+        const eventName = isDirectory ? EVENTS.UNLINK_DIR : EVENTS.UNLINK;
+        if (wasTracked && !this._isIgnored(path15))
+          this._emit(eventName, path15);
+        this._closePath(path15);
+      }
+      /**
+       * Closes all watchers for a path
+       */
+      _closePath(path15) {
+        this._closeFile(path15);
+        const dir = sysPath2.dirname(path15);
+        this._getWatchedDir(dir).remove(sysPath2.basename(path15));
+      }
+      /**
+       * Closes only file-specific watchers
+       */
+      _closeFile(path15) {
+        const closers = this._closers.get(path15);
+        if (!closers)
+          return;
+        closers.forEach((closer) => closer());
+        this._closers.delete(path15);
+      }
+      _addPathCloser(path15, closer) {
+        if (!closer)
+          return;
+        let list = this._closers.get(path15);
+        if (!list) {
+          list = [];
+          this._closers.set(path15, list);
+        }
+        list.push(closer);
+      }
+      _readdirp(root, opts) {
+        if (this.closed)
+          return;
+        const options2 = { type: EVENTS.ALL, alwaysStat: true, lstat: true, ...opts, depth: 0 };
+        let stream = readdirp(root, options2);
+        this._streams.add(stream);
+        stream.once(STR_CLOSE, () => {
+          stream = void 0;
+        });
+        stream.once(STR_END, () => {
+          if (stream) {
+            this._streams.delete(stream);
+            stream = void 0;
+          }
+        });
+        return stream;
+      }
+    };
+    esm_default = { watch, FSWatcher };
+  }
+});
+
+// spex-console/bin/hs-vault-pull.ts
+import { readFileSync as readFileSync13 } from "node:fs";
+import path14 from "node:path";
+import process4 from "node:process";
+
+// spex-console/src/lib/cli/control-shared.ts
+init_hs_command();
+init_console_fetch();
+init_credentials();
+init_session_owner();
+init_vault_less_endpoints();
+init_registry_file();
+import path from "node:path";
+var VAULT_ID_HEADER = "x-heyspex-vault-id";
+var ACCOUNT_ID_HEADER = "x-heyspex-account-id";
+function scopeHeadersFor(scope, method, path15) {
+  if (scope === "none") {
+    if (!isVaultLessEndpoint(method, path15)) {
+      throw new Error(
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path15} is vault-scoped and must name { accountId, vaultId }.`
+      );
+    }
+    return {};
+  }
+  return { [VAULT_ID_HEADER]: scope.vaultId, [ACCOUNT_ID_HEADER]: scope.accountId };
+}
+function cloudRequestScope(scope) {
+  const named = { accountId: scope.accountId, vaultId: scope.vaultId };
+  return {
+    ...named,
+    headersFor: (method, path15) => isVaultLessEndpoint(method, path15) ? {} : scopeHeadersFor(named, method, path15)
+  };
+}
+
+// spex-console/src/lib/cli/init.ts
+init_console_url_resolver();
+import { randomUUID } from "node:crypto";
+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");
@@ -5822,6 +7739,7 @@ var PULL_HELP = [
   "Usage:",
   "  hs pull [--apply] [--only <id|basename>[,...]] [--overwrite]",
   "          [--from <console-url>] [--detail] [--json]",
+  "  hs pull --apply --watch [--interval <seconds>] [--push [--force]] [--from <console-url>]",
   "",
   "Options:",
   "  --apply             Actually write. WITHOUT it, hs pull only REPORTS a plan.",
@@ -5831,6 +7749,16 @@ var PULL_HELP = [
   "  --from <url>        Source console (default: the cloud console, app.heyspex.com).",
   "  --detail            List every skipped spec instead of a bounded sample.",
   "  --json              Emit the raw result object.",
+  "  --watch             Keep running: pull now, then every --interval seconds,",
+  "                      backing off while idle. Requires --apply. One line per",
+  "                      tick that wrote something, silence otherwise. This is",
+  "                      what the Companion runs (SpexRelay's cloud \u2192 local leg).",
+  "  --interval <s>      Base tick for --watch (default 60).",
+  "  --push              With --watch: also run the disk -> cloud leg. File edits under",
+  "                      specs/ are pushed (1 s debounce, never status, never creating",
+  "                      specs, never over a newer cloud copy). A file with no sync",
+  "                      record is only SEEDED, never pushed. See `hs push`.",
+  "  --force             With --push: let a disk edit overwrite a newer cloud copy.",
   "",
   "Which vault: --vault <id> (global flag) > this repo's heyspex.yaml vault_id >",
   "the account's active vault read from the console. The registry.json pointer",
@@ -5843,11 +7771,18 @@ var PULL_HELP = [
   "  2   Usage error",
   "  11  No vault could be resolved, or --apply would write another vault into this repo",
   "",
-  "One direction only: cloud \u2192 disk. Never pushes, never deletes. A spec that",
-  "already exists on disk is skipped and reported, never silently overwritten.",
+  "Without --push: cloud \u2192 disk only; never deletes. A spec already on disk is",
+  "skipped and reported, except one the last sync wrote and nobody edited since",
+  "(sync ledger), which fast-forwards to a newer cloud copy.",
   "Fixes the custody gap in [[HS-OQNH-21DO-DIAG-cloud-written-specs-are-invisible-to]]."
 ].join("\n");
-var FLAGS_WITH_VALUES = /* @__PURE__ */ new Set(["--only", "--from"]);
+var DEFAULT_WATCH_INTERVAL_SEC = 60;
+var FLAGS_WITH_VALUES = /* @__PURE__ */ new Set(["--only", "--from", "--interval"]);
+function parseIntervalSec(value) {
+  if (!/^\d+$/.test(value)) return null;
+  const n = Number(value);
+  return n >= 1 ? n : null;
+}
 function parsePullArgs(argv) {
   const tokens = argv[0] === "pull" ? argv.slice(1) : [...argv];
   if (tokens.includes("--help") || tokens.includes("-h")) return { help: true };
@@ -5857,7 +7792,27 @@ function parsePullArgs(argv) {
     detail: false,
     json: false,
     only: [],
-    from: null
+    from: null,
+    watch: false,
+    intervalSec: DEFAULT_WATCH_INTERVAL_SEC,
+    push: false,
+    force: false
+  };
+  const applyValued = (flag, value) => {
+    if (flag === "--only") {
+      args.only.push(
+        ...value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
+      );
+      return null;
+    }
+    if (flag === "--interval") {
+      const n = parseIntervalSec(value);
+      if (n === null) return `--interval must be a whole number of seconds >= 1 (got \`${value}\`)`;
+      args.intervalSec = n;
+      return null;
+    }
+    args.from = value;
+    return null;
   };
   for (let i = 0; i < tokens.length; i++) {
     const tok = tokens[i];
@@ -5867,13 +7822,8 @@ function parsePullArgs(argv) {
         return { error: { message: `${tok} requires a value`, code: PULL_EXIT.USAGE } };
       }
       i++;
-      if (tok === "--only") {
-        args.only.push(
-          ...value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
-        );
-      } else {
-        args.from = value.trim();
-      }
+      const problem = applyValued(tok, value.trim());
+      if (problem) return { error: { message: problem, code: PULL_EXIT.USAGE } };
       continue;
     }
     const eq2 = tok.indexOf("=");
@@ -5883,13 +7833,8 @@ function parsePullArgs(argv) {
       if (value.length === 0) {
         return { error: { message: `${flag} requires a value`, code: PULL_EXIT.USAGE } };
       }
-      if (flag === "--only") {
-        args.only.push(
-          ...value.split(",").map((s) => s.trim()).filter((s) => s.length > 0)
-        );
-      } else {
-        args.from = value;
-      }
+      const problem = applyValued(flag, value);
+      if (problem) return { error: { message: problem, code: PULL_EXIT.USAGE } };
       continue;
     }
     switch (tok) {
@@ -5905,10 +7850,31 @@ function parsePullArgs(argv) {
       case "--json":
         args.json = true;
         break;
+      case "--watch":
+        args.watch = true;
+        break;
+      case "--push":
+        args.push = true;
+        break;
+      case "--force":
+        args.force = true;
+        break;
       default:
         return { error: { message: `unknown option \`${tok}\``, code: PULL_EXIT.USAGE } };
     }
   }
+  if (args.watch && !args.apply) {
+    return { error: { message: "--watch requires --apply", code: PULL_EXIT.USAGE } };
+  }
+  if (args.push && !args.watch) {
+    return { error: { message: "--push requires --watch --apply", code: PULL_EXIT.USAGE } };
+  }
+  if (args.force && !args.push) {
+    return { error: { message: "--force requires --push", code: PULL_EXIT.USAGE } };
+  }
+  if (args.watch && args.json) {
+    return { error: { message: "--watch cannot be combined with --json", code: PULL_EXIT.USAGE } };
+  }
   return { args };
 }
 
@@ -5950,7 +7916,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,
@@ -5958,9 +7924,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) {
@@ -5982,8 +7948,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,
@@ -6005,13 +7974,157 @@ async function resolveSyncVaultTargetFromEnv(deps) {
     markerVaultId,
     registryRowId,
     pointer,
-    verb: deps.verb
+    verb: deps.verb,
+    allowPointer
   });
 }
 
 // spex-console/bin/hs-vault-pull.ts
 init_vault_workspace_shared();
 
+// spex-console/src/lib/vault-sync/dirty.ts
+import { promises as fs3, watch as fsWatch } from "node:fs";
+import nodePath2 from "node:path";
+
+// spex-console/src/lib/vault-sync/ledger.ts
+import { createHash } from "node:crypto";
+import { promises as fs2 } from "node:fs";
+import nodePath from "node:path";
+var VAULT_RUNTIME_DIR = ".heyspex";
+var LEDGER_FILE = "vault-sync-ledger.json";
+function ledgerPath(vaultRoot2) {
+  return nodePath.join(vaultRoot2, VAULT_RUNTIME_DIR, LEDGER_FILE);
+}
+function hashContent(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function parseLedger(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json)) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(json)) {
+    if (!v || typeof v !== "object") continue;
+    const e = v;
+    if (typeof e.hash !== "string" || e.hash.length === 0) continue;
+    out[k] = {
+      hash: e.hash,
+      remoteUpdatedAt: typeof e.remoteUpdatedAt === "string" ? e.remoteUpdatedAt : null,
+      at: typeof e.at === "string" ? e.at : "",
+      by: e.by === "push" ? "push" : "pull"
+    };
+  }
+  return out;
+}
+function createLedgerStore(vaultRoot2, { now = () => /* @__PURE__ */ new Date() } = {}) {
+  const file = ledgerPath(vaultRoot2);
+  const pending = /* @__PURE__ */ new Map();
+  let chain = Promise.resolve();
+  async function readDisk() {
+    try {
+      return parseLedger(await fs2.readFile(file, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+  async function writeAtomic(ledger) {
+    await fs2.mkdir(nodePath.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await fs2.writeFile(tmp, `${JSON.stringify(ledger)}
+`, "utf8");
+    let lastErr;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      try {
+        await fs2.rename(tmp, file);
+        return;
+      } catch (err) {
+        lastErr = err;
+        await new Promise((r) => setTimeout(r, 25 * (attempt + 1)));
+      }
+    }
+    await fs2.rm(tmp, { force: true }).catch(() => {
+    });
+    throw lastErr;
+  }
+  return {
+    async snapshot() {
+      const disk = await readDisk();
+      for (const [k, v] of pending) disk[k] = v;
+      return disk;
+    },
+    record(relPath, entry) {
+      pending.set(relPath, { ...entry, at: entry.at ?? now().toISOString() });
+    },
+    flush() {
+      chain = chain.then(async () => {
+        if (pending.size === 0) return;
+        const batch = new Map(pending);
+        const merged = await readDisk();
+        for (const [k, v] of batch) merged[k] = v;
+        await writeAtomic(merged);
+        for (const [k, v] of batch) if (pending.get(k) === v) pending.delete(k);
+      });
+      return chain;
+    }
+  };
+}
+
+// spex-console/src/lib/vault-sync/dirty.ts
+var DIRTY_FILE = "vault-dirty";
+function dirtyMarkerPath(vaultRoot2) {
+  return nodePath2.join(vaultRoot2, VAULT_RUNTIME_DIR, DIRTY_FILE);
+}
+async function writeDirtyMarker(vaultRoot2, id, now = () => /* @__PURE__ */ new Date()) {
+  const file = dirtyMarkerPath(vaultRoot2);
+  await fs3.mkdir(nodePath2.dirname(file), { recursive: true });
+  await fs3.writeFile(file, JSON.stringify({ id, at: now().toISOString() }), "utf8");
+}
+function parseDirtyMarker(raw) {
+  try {
+    const j = JSON.parse(raw);
+    return typeof j.id === "string" && j.id.trim() ? { id: j.id.trim(), at: typeof j.at === "string" ? j.at : "" } : null;
+  } catch {
+    return null;
+  }
+}
+function watchDirtyMarker(vaultRoot2, onDirty, { debounceMs = 100 } = {}) {
+  const file = dirtyMarkerPath(vaultRoot2);
+  let timer = null;
+  let closed = false;
+  let watcher = null;
+  try {
+    void fs3.mkdir(nodePath2.dirname(file), { recursive: true }).then(() => {
+      if (closed) return;
+      try {
+        watcher = fsWatch(nodePath2.dirname(file), (_evt, name) => {
+          if (name && String(name) !== DIRTY_FILE) return;
+          if (timer) clearTimeout(timer);
+          timer = setTimeout(async () => {
+            try {
+              const m = parseDirtyMarker(await fs3.readFile(file, "utf8"));
+              if (m) onDirty(m.id);
+            } catch {
+            }
+          }, debounceMs);
+        });
+        watcher.on("error", () => {
+        });
+      } catch {
+      }
+    });
+  } catch {
+  }
+  return () => {
+    closed = true;
+    if (timer) clearTimeout(timer);
+    watcher?.close();
+  };
+}
+
 // spex-console/src/lib/vault-sync/pull.ts
 function normalizeSpecRelPath(raw) {
   if (typeof raw !== "string") return null;
@@ -6029,6 +8142,10 @@ function normalizeSpecRelPath(raw) {
   if (!/\.md$/i.test(p)) return null;
   return p;
 }
+function hasDotSegment(relPath) {
+  const segments = relPath.split("/");
+  return segments.slice(0, -1).some((s) => s.startsWith("."));
+}
 function basenameOfRelPath(relPath) {
   const last = relPath.split("/").pop() ?? relPath;
   return last.replace(/\.md$/i, "");
@@ -6040,11 +8157,11 @@ function selectRemoteRefs(remote, only) {
   const selected = [];
   for (const ref of remote) {
     const id = (ref.id ?? "").toLowerCase();
-    const basename = (ref.basename ?? "").toLowerCase();
+    const basename4 = (ref.basename ?? "").toLowerCase();
     let hit = null;
     for (const sel of selectors) {
       const s = sel.toLowerCase();
-      if (id === s || basename === s || id.startsWith(`${s}-`) || basename.startsWith(`${s}-`)) {
+      if (id === s || basename4 === s || id.startsWith(`${s}-`) || basename4.startsWith(`${s}-`)) {
         hit = sel;
         break;
       }
@@ -6056,6 +8173,18 @@ function selectRemoteRefs(remote, only) {
   }
   return { selected, unmatched: selectors.filter((s) => !matched.has(s)) };
 }
+function instantMs(value) {
+  return typeof value === "string" && value ? Date.parse(value) : Number.NaN;
+}
+function canFastForward(ref, relPath, local) {
+  const entry = local.ledger?.[relPath];
+  const disk = local.hashes?.get(relPath);
+  if (!entry || !disk || disk !== entry.hash) return null;
+  const remote = instantMs(ref.updatedAt);
+  const seen = instantMs(entry.remoteUpdatedAt);
+  if (Number.isNaN(remote) || Number.isNaN(seen) || remote <= seen) return null;
+  return entry.hash;
+}
 function decidePullPlan({
   remote,
   local,
@@ -6071,11 +8200,11 @@ function decidePullPlan({
     if (!localByBasename.has(base)) localByBasename.set(base, norm);
   }
   const pull = [];
-  const skip = [];
+  const skip2 = [];
   for (const ref of remote) {
     const relPath = normalizeSpecRelPath(ref.relPath ?? null);
     if (!relPath) {
-      skip.push({
+      skip2.push({
         id: ref.id,
         relPath: null,
         reason: "unsafe-path",
@@ -6083,18 +8212,43 @@ function decidePullPlan({
       });
       continue;
     }
-    const basename = basenameOfRelPath(relPath);
+    const basename4 = basenameOfRelPath(relPath);
+    if (hasDotSegment(relPath)) {
+      skip2.push({
+        id: ref.id,
+        relPath,
+        reason: "trashed-path",
+        detail: "soft-deleted on the remote \u2014 the pull never resurrects a .trash/ row"
+      });
+      continue;
+    }
     if (localRelPaths.has(relPath)) {
+      const ffHash = overwrite ? null : canFastForward(ref, relPath, local);
       if (overwrite) {
-        pull.push({ id: ref.id, relPath, basename, overwrites: true });
+        pull.push({
+          id: ref.id,
+          relPath,
+          basename: basename4,
+          overwrites: true,
+          remoteUpdatedAt: ref.updatedAt ?? void 0
+        });
+      } else if (ffHash) {
+        pull.push({
+          id: ref.id,
+          relPath,
+          basename: basename4,
+          overwrites: true,
+          remoteUpdatedAt: ref.updatedAt ?? void 0,
+          fastForwardFromHash: ffHash
+        });
       } else {
-        skip.push({ id: ref.id, relPath, reason: "present-on-disk" });
+        skip2.push({ id: ref.id, relPath, reason: "present-on-disk" });
       }
       continue;
     }
-    const elsewhere = localByBasename.get(basename.toLowerCase());
+    const elsewhere = localByBasename.get(basename4.toLowerCase());
     if (elsewhere) {
-      skip.push({
+      skip2.push({
         id: ref.id,
         relPath,
         reason: "basename-exists-elsewhere",
@@ -6102,19 +8256,54 @@ function decidePullPlan({
       });
       continue;
     }
-    pull.push({ id: ref.id, relPath, basename, overwrites: false });
+    pull.push({
+      id: ref.id,
+      relPath,
+      basename: basename4,
+      overwrites: false,
+      remoteUpdatedAt: ref.updatedAt ?? void 0
+    });
   }
-  return { pull, skip };
+  return { pull, skip: skip2 };
 }
 async function runVaultPull(deps, options2 = {}) {
   const dryRun = options2.dryRun !== false;
   const overwrite = options2.overwrite === true;
-  const remote = await deps.listRemote();
-  const { selected, unmatched } = selectRemoteRefs(remote, options2.only);
+  let remote;
+  let selected;
+  let unmatched;
+  if (options2.direct && deps.getRemoteRef && options2.only && options2.only.length > 0) {
+    selected = [];
+    unmatched = [];
+    for (const sel of options2.only) {
+      const ref = await deps.getRemoteRef(sel);
+      if (ref) selected.push(ref);
+      else unmatched.push(sel);
+    }
+    remote = selected;
+  } else {
+    remote = await deps.listRemote();
+    ({ selected, unmatched } = selectRemoteRefs(remote, options2.only));
+  }
   const localRelPaths = await deps.listLocal();
+  const ledger = deps.readLedger && !overwrite ? await deps.readLedger() : void 0;
+  const hashes = /* @__PURE__ */ new Map();
+  if (ledger && deps.hashLocal) {
+    const onDisk = new Set(localRelPaths.map((p) => normalizeSpecRelPath(p) ?? p));
+    for (const ref of selected) {
+      const rel = normalizeSpecRelPath(ref.relPath ?? null);
+      if (!rel || !onDisk.has(rel)) continue;
+      const entry = ledger[rel];
+      const rem = instantMs(ref.updatedAt);
+      const seen = instantMs(entry?.remoteUpdatedAt);
+      if (!entry || Number.isNaN(rem) || Number.isNaN(seen) || rem <= seen) continue;
+      const h = await deps.hashLocal(rel);
+      if (h) hashes.set(rel, h);
+    }
+  }
   const plan = decidePullPlan({
     remote: selected,
-    local: { relPaths: localRelPaths },
+    local: { relPaths: localRelPaths, ledger, hashes },
     overwrite
   });
   const written = [];
@@ -6132,7 +8321,19 @@ async function runVaultPull(deps, options2 = {}) {
           continue;
         }
         const bytes = deps.serialize(content.body, content.frontmatter);
-        await deps.writeSpec(item.relPath, bytes);
+        if (item.fastForwardFromHash && deps.hashLocal) {
+          const nowHash = await deps.hashLocal(item.relPath);
+          if (nowHash !== item.fastForwardFromHash) {
+            plan.skip.push({
+              id: item.id,
+              relPath: item.relPath,
+              reason: "present-on-disk",
+              detail: "edited locally while the pull ran - not overwritten"
+            });
+            continue;
+          }
+        }
+        await deps.writeSpec(item.relPath, bytes, { overwrite: item.overwrites });
         written.push({
           id: item.id,
           relPath: item.relPath,
@@ -6141,7 +8342,11 @@ async function runVaultPull(deps, options2 = {}) {
         });
         if (deps.afterWrite) {
           try {
-            await deps.afterWrite(item.relPath);
+            await deps.afterWrite(item.relPath, {
+              id: item.id,
+              content: bytes,
+              remoteUpdatedAt: item.remoteUpdatedAt ?? null
+            });
           } catch {
           }
         }
@@ -6154,6 +8359,12 @@ async function runVaultPull(deps, options2 = {}) {
       }
     }
   }
+  if (!dryRun && deps.finish) {
+    try {
+      await deps.finish();
+    } catch {
+    }
+  }
   return {
     dryRun,
     remoteCount: remote.length,
@@ -6165,9 +8376,10 @@ async function runVaultPull(deps, options2 = {}) {
   };
 }
 var SKIP_LABELS = {
-  "present-on-disk": "already on disk (use --overwrite to replace)",
+  "present-on-disk": "already on disk (use --overwrite to replace; files unmodified since the last sync fast-forward on their own)",
   "basename-exists-elsewhere": "same basename lives at another path \u2014 not touched",
-  "unsafe-path": "remote row has no safe vault-relative .md path"
+  "unsafe-path": "remote row has no safe vault-relative .md path",
+  "trashed-path": "soft-deleted on the remote (.trash/) \u2014 never resurrected"
 };
 function formatPullSummary(result, { detail = false, sampleSize = 5 } = {}) {
   const lines = [];
@@ -6222,23 +8434,22 @@ function formatPullSummary(result, { detail = false, sampleSize = 5 } = {}) {
 }
 
 // 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 fs10 } from "node:fs";
+import nodePath3 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 defaultReadFile = (p) => readFileSync9(p, "utf8");
+var defaultReadFile = (p) => readFileSync10(p, "utf8");
 function readCredentialsMcpToken({
-  homeDir = homedir8(),
+  homeDir = heyspexHome2(),
   readFile = defaultReadFile
 } = {}) {
   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 {
@@ -6247,6 +8458,7 @@ function readCredentialsMcpToken({
 }
 
 // spex-console/src/lib/vault-sync/pull-io.ts
+init_heyspex_home2();
 init_vault();
 init_vault_frontmatter();
 var LIST_FIELDS = "id,basename,relPath,type,status,updated,updatedAt";
@@ -6262,7 +8474,7 @@ var VaultPullSourceError = class extends Error {
 };
 function resolvePullToken({
   env = process.env,
-  homeDir = homedir9()
+  homeDir = heyspexHome2()
 } = {}) {
   const fromEnv = env.HEYSPEX_MCP_TOKEN?.trim();
   if (fromEnv) return fromEnv;
@@ -6361,22 +8573,68 @@ async function fetchRemoteSpecContent(http, item) {
   }
   return { body: spec.body, frontmatter };
 }
+function remoteStamp(spec) {
+  if (!spec) return null;
+  const fm = spec.frontmatter;
+  for (const candidate of [fm?.updated, spec.updatedAt, spec.updated]) {
+    const raw = candidate instanceof Date ? candidate.toISOString() : candidate;
+    if (typeof raw === "string" && raw.trim()) {
+      const ms = Date.parse(raw);
+      if (!Number.isNaN(ms)) return /T/.test(raw) ? new Date(ms).toISOString() : raw.trim();
+    }
+  }
+  return null;
+}
+async function fetchRemoteRefAndContent(http, selector) {
+  const { status, json, text: text2 } = await getJson(http, `api/specs/${encodeURIComponent(selector)}`);
+  if (status === 404) return null;
+  if (status !== 200) {
+    throw new VaultPullSourceError(
+      `GET /api/specs/${selector} returned ${status}: ${text2.slice(0, 200)}`,
+      status
+    );
+  }
+  const spec = json?.spec;
+  const fm = spec?.frontmatter && typeof spec.frontmatter === "object" ? spec.frontmatter : null;
+  if (!spec || typeof spec.body !== "string" || !fm || Object.keys(fm).length === 0) {
+    throw new VaultPullSourceError(`GET /api/specs/${selector} returned no usable spec`, status);
+  }
+  return {
+    ref: {
+      id: String(spec.id ?? fm.id ?? ""),
+      basename: typeof spec.basename === "string" ? spec.basename : null,
+      relPath: typeof spec.relPath === "string" ? spec.relPath : null,
+      type: typeof spec.type === "string" ? spec.type : null,
+      status: typeof spec.status === "string" ? spec.status : null,
+      updated: typeof spec.updated === "string" ? spec.updated : null,
+      updatedAt: remoteStamp(spec)
+    },
+    content: { body: spec.body, frontmatter: fm }
+  };
+}
+async function hashFile(abs) {
+  try {
+    return hashContent(await fs10.readFile(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
 async function listLocalSpecRelPaths(root = vaultRoot()) {
   const out = [];
   async function walk(dir) {
     let entries;
     try {
-      entries = await fs8.readdir(dir, { withFileTypes: true });
+      entries = await fs10.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = nodePath.join(dir, entry.name);
+      const full = nodePath3.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
         await walk(full);
       } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
-        out.push(nodePath.relative(root, full).split(nodePath.sep).join("/"));
+        out.push(nodePath3.relative(root, full).split(nodePath3.sep).join("/"));
       }
     }
   }
@@ -6388,21 +8646,659 @@ function createVaultPullDeps({
   token,
   fetchImpl,
   localRoot,
-  scopeHeaders
+  scopeHeaders,
+  ledger,
+  onLocalWrite
 }) {
   const http = { baseUrl, token, fetchImpl, scopeHeaders };
+  const prefetched = /* @__PURE__ */ new Map();
   return {
     listRemote: () => listRemoteSpecs(http),
-    fetchRemoteSpec: (item) => fetchRemoteSpecContent(http, item),
+    getRemoteRef: async (selector) => {
+      const hit = await fetchRemoteRefAndContent(http, selector);
+      if (!hit) return null;
+      if (hit.ref.basename) prefetched.set(hit.ref.basename, hit.content);
+      return hit.ref;
+    },
+    fetchRemoteSpec: async (item) => {
+      const cached = prefetched.get(item.basename);
+      if (cached) {
+        prefetched.delete(item.basename);
+        return cached;
+      }
+      return fetchRemoteSpecContent(http, item);
+    },
+    readLedger: ledger ? () => ledger.snapshot() : void 0,
+    hashLocal: (relPath) => hashFile(nodePath3.join(localRoot ?? vaultRoot(), relPath)),
+    finish: ledger ? () => ledger.flush() : void 0,
     listLocal: () => listLocalSpecRelPaths(localRoot ?? vaultRoot()),
     serialize: stringifySpecMarkdown,
-    writeSpec: localRoot ? async (relPath, content) => {
-      const abs = nodePath.join(localRoot, relPath);
-      await fs8.mkdir(nodePath.dirname(abs), { recursive: true });
-      await fs8.writeFile(abs, content, "utf8");
+    writeSpec: localRoot ? async (relPath, content, opts) => {
+      const abs = nodePath3.join(localRoot, relPath);
+      await fs10.mkdir(nodePath3.dirname(abs), { recursive: true });
+      onLocalWrite?.(relPath);
+      await fs10.writeFile(abs, content, {
+        encoding: "utf8",
+        flag: opts?.overwrite === true ? "w" : "wx"
+      });
     } : (relPath, content) => writeSpecBytesToVault(relPath, content),
-    afterWrite: (relPath) => updateVaultCacheEntry(nodePath.join(localRoot ?? vaultRoot(), relPath))
+    afterWrite: async (relPath, info) => {
+      if (ledger && info) {
+        ledger.record(relPath, {
+          hash: hashContent(info.content),
+          remoteUpdatedAt: info.remoteUpdatedAt,
+          by: "pull"
+        });
+      }
+      await updateVaultCacheEntry(nodePath3.join(localRoot ?? vaultRoot(), relPath));
+    }
+  };
+}
+
+// spex-console/src/lib/vault-sync/pull-watch.ts
+var DEFAULT_WATCH_OPTIONS = {
+  baseIntervalMs: 6e4,
+  // 120 s: a cloud-side console edit lands within ~2 minutes worst case. A tick
+  // is ~14 list GETs for ~7,000 specs (500 rows/page) + one GET per changed
+  // spec, so an idle vault costs ~7 req/min at the ceiling - well inside the
+  // list route's budget. Local writes use the dirty-marker fast path instead.
+  maxIntervalMs: 12e4,
+  backoffFactor: 1.5
+};
+function nextWatchDelay(previousMs, outcome, opts = DEFAULT_WATCH_OPTIONS) {
+  if (outcome === "wrote") return opts.baseIntervalMs;
+  const prev = previousMs ?? opts.baseIntervalMs;
+  return Math.min(opts.maxIntervalMs, Math.round(prev * opts.backoffFactor));
+}
+function classifyTick(result) {
+  if (result.written.length > 0) return "wrote";
+  if (result.failed.length > 0) return "error";
+  return "idle";
+}
+function formatWatchTick(result, sourceLabel) {
+  const lines = [];
+  if (result.written.length > 0) {
+    lines.push({
+      level: "info",
+      line: `relay: pulled ${result.written.length} spec(s) from ${sourceLabel}`
+    });
+    for (const w of result.written) {
+      lines.push({ level: "info", line: `  ${w.overwrote ? "~" : "+"} ${w.relPath}  (${w.id})` });
+    }
+  }
+  for (const f of result.failed) {
+    lines.push({
+      level: "warn",
+      line: `relay: failed to pull ${f.relPath} (${f.id}) \u2014 ${f.error}`
+    });
+  }
+  return lines;
+}
+async function runPullWatch(deps, opts = DEFAULT_WATCH_OPTIONS) {
+  const summary = { ticks: 0, written: 0, failed: 0, errors: 0 };
+  let delay = null;
+  while (!deps.signal.aborted) {
+    const dirty = deps.takeDirty?.() ?? [];
+    if (dirty.length > 0 && deps.pullDirty && delay !== null) {
+      try {
+        const result = await deps.pullDirty(dirty);
+        summary.written += result.written.length;
+        summary.failed += result.failed.length;
+        for (const { level, line } of formatWatchTick(result, deps.sourceLabel)) {
+          deps.log(level, line);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        deps.log("warn", `relay: refresh of ${dirty.join(", ")} failed - ${message}`);
+      }
+      if (deps.signal.aborted) break;
+      await deps.sleep(delay, deps.signal);
+      continue;
+    }
+    summary.ticks += 1;
+    let outcome;
+    try {
+      const result = await deps.pullOnce();
+      summary.written += result.written.length;
+      summary.failed += result.failed.length;
+      for (const { level, line } of formatWatchTick(result, deps.sourceLabel)) {
+        deps.log(level, line);
+      }
+      outcome = classifyTick(result);
+    } catch (err) {
+      summary.errors += 1;
+      const message = err instanceof Error ? err.message : String(err);
+      deps.log("warn", `relay: pull from ${deps.sourceLabel} failed \u2014 ${message}`);
+      outcome = "error";
+    }
+    if (deps.signal.aborted) break;
+    delay = nextWatchDelay(delay, outcome, opts);
+    await deps.sleep(delay, deps.signal);
+  }
+  return summary;
+}
+
+// spex-console/src/lib/vault-sync/push.ts
+init_vault_frontmatter();
+var skip = (reason, detail) => ({
+  reason,
+  push: false,
+  ...detail ? { detail } : {}
+});
+function readSpecIdentity(content) {
+  try {
+    const data = parseSpecMarkdown(content).data ?? {};
+    const id = typeof data.id === "string" ? data.id.trim() : "";
+    const type = typeof data.type === "string" ? data.type.trim() : "";
+    return id && type ? { id, type } : null;
+  } catch {
+    return null;
+  }
+}
+function precheckPush(local, ledger, explicit = false) {
+  const rel = normalizeSpecRelPath(local.relPath);
+  if (!rel) return skip("unsafe-path", local.relPath);
+  if (hasDotSegment(rel))
+    return skip("trashed-path", "files under a dot-folder (.trash/) never sync");
+  if (!explicit && ledger && ledger.hash === local.hash)
+    return skip("unchanged", "disk matches the last sync");
+  if (!readSpecIdentity(local.content)) {
+    return skip("no-id", "no id:/type: in the frontmatter - not a spec the cloud can address");
+  }
+  return null;
+}
+function decidePushPlan({
+  local,
+  ledger,
+  remote,
+  force = false,
+  allowUnledgered = false
+}) {
+  const entry = isLedgerEntry(ledger) ? ledger : ledger?.[local.relPath];
+  const pre = precheckPush(local, entry, allowUnledgered);
+  if (pre) return pre;
+  if (!remote)
+    return skip("new-on-disk", "no remote row - hs never creates cloud specs from a disk file");
+  if (!entry && !allowUnledgered) {
+    return skip("seeded", "no sync record yet - recorded as the baseline, nothing sent");
+  }
+  if (remote.bytes === local.content) {
+    return skip("identical", "disk already equals the remote serialization");
+  }
+  const remoteMs = instantMs(remote.updatedAt);
+  let newer = false;
+  let why = "";
+  if (entry) {
+    const seen = instantMs(entry.remoteUpdatedAt);
+    newer = !Number.isNaN(remoteMs) && !Number.isNaN(seen) && remoteMs > seen;
+    why = `remote updated ${remote.updatedAt} > last synced ${entry.remoteUpdatedAt}`;
+  } else if (!Number.isNaN(remoteMs)) {
+    newer = local.mtimeMs === void 0 || local.mtimeMs < remoteMs;
+    why = `no sync record; remote updated ${remote.updatedAt} is not older than the disk file`;
+  }
+  if (newer && !force) return skip("remote-newer", why);
+  return { reason: "push", push: true, ...newer ? { forced: true, detail: why } : {} };
+}
+function isLedgerEntry(v) {
+  return !!v && typeof v === "object" && typeof v.hash === "string";
+}
+function jsonSafe(value) {
+  if (value instanceof Date) {
+    const iso = value.toISOString();
+    return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso;
+  }
+  if (Array.isArray(value)) return value.map(jsonSafe);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, jsonSafe(v)]));
+  }
+  return value;
+}
+function buildPushPayload(content) {
+  const parsed = parseSpecMarkdown(content);
+  const frontmatter = jsonSafe({ ...parsed.data ?? {} });
+  delete frontmatter.status;
+  return { id: String(frontmatter.id ?? ""), frontmatter, body: parsed.content };
+}
+function matchesOnly(relPath, id, only) {
+  const base = basenameOfRelPath(relPath).toLowerCase();
+  const lid = (id ?? "").toLowerCase();
+  return only.some((sel) => {
+    const s = sel.toLowerCase();
+    return base === s || lid === s || base.startsWith(`${s}-`) || lid.startsWith(`${s}-`);
+  });
+}
+async function runVaultPush(deps, options2 = {}) {
+  const dryRun = options2.dryRun !== false;
+  const only = (options2.only ?? []).map((s) => s.trim()).filter(Boolean);
+  const allowUnledgered = options2.allowUnledgered === true || only.length > 0;
+  const result = {
+    dryRun,
+    scanned: 0,
+    pushed: [],
+    skipped: [],
+    conflicts: [],
+    warnings: [],
+    failed: [],
+    unmatchedSelectors: [],
+    deferred: []
+  };
+  const ledger = await deps.readLedger();
+  let relPaths = options2.paths ? [...options2.paths] : await deps.listLocal();
+  relPaths = relPaths.map((p) => normalizeSpecRelPath(p) ?? p);
+  let remoteIndex = null;
+  if (deps.listRemote) {
+    remoteIndex = /* @__PURE__ */ new Map();
+    for (const r of await deps.listRemote()) {
+      if (r.basename) remoteIndex.set(r.basename.toLowerCase(), r.updatedAt ?? null);
+    }
+  }
+  const matchedSelectors = /* @__PURE__ */ new Set();
+  let puts = 0;
+  for (const relPath of relPaths) {
+    const local = await deps.readLocal(relPath);
+    if (!local) continue;
+    const identity = readSpecIdentity(local.content);
+    if (only.length > 0) {
+      if (!matchesOnly(relPath, identity?.id ?? null, only)) continue;
+      for (const sel of only) {
+        if (matchesOnly(relPath, identity?.id ?? null, [sel])) matchedSelectors.add(sel);
+      }
+    }
+    result.scanned += 1;
+    const entry = ledger[relPath];
+    const pl2 = {
+      relPath,
+      content: local.content,
+      hash: local.hash,
+      mtimeMs: local.mtimeMs
+    };
+    const item = (reason, detail) => ({
+      relPath,
+      id: identity?.id ?? null,
+      reason,
+      ...detail ? { detail } : {}
+    });
+    const pre = precheckPush(pl2, entry, allowUnledgered);
+    if (pre) {
+      result.skipped.push(item(pre.reason, pre.detail));
+      continue;
+    }
+    const basename4 = basenameOfRelPath(relPath);
+    if (remoteIndex) {
+      const stamp = remoteIndex.get(basename4.toLowerCase());
+      if (stamp === void 0) {
+        result.skipped.push(
+          item("new-on-disk", "no remote row - hs never creates cloud specs from a disk file")
+        );
+        continue;
+      }
+      if (!entry && !allowUnledgered) {
+        if (!dryRun) {
+          deps.recordLedger(relPath, { hash: local.hash, remoteUpdatedAt: stamp, by: "push" });
+        }
+        result.skipped.push(
+          item("seeded", "no sync record yet - recorded as the baseline, nothing sent")
+        );
+        continue;
+      }
+    }
+    let remote;
+    try {
+      remote = await deps.fetchRemote(basename4);
+    } catch (err) {
+      result.failed.push({
+        relPath,
+        id: identity?.id ?? null,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    const decision = decidePushPlan({
+      local: pl2,
+      ledger: entry,
+      remote: remote ? { updatedAt: remote.updatedAt, bytes: deps.serialize(remote.body, remote.frontmatter) } : null,
+      force: options2.force === true,
+      allowUnledgered
+    });
+    if (decision.reason === "seeded" && remote && !dryRun) {
+      deps.recordLedger(relPath, {
+        hash: local.hash,
+        remoteUpdatedAt: remote.updatedAt,
+        by: "push"
+      });
+    }
+    if (decision.reason === "identical" && remote && !dryRun) {
+      deps.recordLedger(relPath, {
+        hash: local.hash,
+        remoteUpdatedAt: remote.updatedAt,
+        by: "push"
+      });
+    }
+    if (!decision.push) {
+      (decision.reason === "remote-newer" ? result.conflicts : result.skipped).push(
+        item(decision.reason, decision.detail)
+      );
+      continue;
+    }
+    if (dryRun) {
+      result.pushed.push(item("push", decision.detail));
+      continue;
+    }
+    if (options2.maxPuts !== void 0 && puts >= options2.maxPuts) {
+      result.deferred.push(item("push", "rate cap for this run"));
+      continue;
+    }
+    const payload = buildPushPayload(local.content);
+    puts += 1;
+    let put;
+    try {
+      put = await deps.putRemote(basename4, {
+        frontmatter: payload.frontmatter,
+        body: payload.body
+      });
+    } catch (err) {
+      result.failed.push({
+        relPath,
+        id: payload.id,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    if (!put.ok) {
+      result.failed.push({
+        relPath,
+        id: payload.id,
+        error: put.error ?? `PUT returned ${put.status}`
+      });
+      if (put.status === 429) {
+        result.retryAfterSec = put.retryAfterSec ?? 60;
+        break;
+      }
+      continue;
+    }
+    if (put.statusIgnored) {
+      result.warnings.push(
+        `${relPath}: status is owned by PATCH /api/specs/${payload.id}/status - the disk status was not pushed`
+      );
+    }
+    deps.recordLedger(relPath, {
+      hash: local.hash,
+      remoteUpdatedAt: put.updatedAt ?? null,
+      by: "push"
+    });
+    result.pushed.push(item("push", decision.detail));
+    try {
+      await deps.markDirty?.(payload.id);
+    } catch {
+    }
+  }
+  result.unmatchedSelectors = only.filter((s) => !matchedSelectors.has(s));
+  try {
+    await deps.flushLedger();
+  } catch {
+  }
+  return result;
+}
+
+// spex-console/src/lib/vault-sync/push-io.ts
+import { promises as fs11 } from "node:fs";
+import nodePath4 from "node:path";
+init_vault_frontmatter();
+async function putRemoteSpec(http, id, payload) {
+  const { baseUrl, token, fetchImpl = fetch } = http;
+  const path15 = `/api/specs/${encodeURIComponent(id)}`;
+  const scope = http.accountId && http.vaultId ? cloudRequestScope({ accountId: http.accountId, vaultId: http.vaultId }).headersFor(
+    "PUT",
+    "/api/specs/:id"
+  ) : http.scopeHeaders ?? {};
+  const headers = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    ...scope
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetchImpl(`${baseUrl}${path15}`, {
+    method: "PUT",
+    headers,
+    body: JSON.stringify({ frontmatter: payload.frontmatter, body: payload.body })
+  });
+  const text2 = await res.text();
+  let json = null;
+  try {
+    json = JSON.parse(text2);
+  } catch {
+  }
+  if (res.status !== 200) {
+    const retry = Number(res.headers.get("retry-after"));
+    return {
+      ok: false,
+      status: res.status,
+      error: `PUT ${path15} returned ${res.status}: ${text2.slice(0, 200)}`,
+      ...res.status === 429 && Number.isFinite(retry) && retry > 0 ? { retryAfterSec: retry } : {}
+    };
+  }
+  const spec = json?.spec ?? null;
+  return {
+    ok: true,
+    status: 200,
+    updatedAt: remoteStamp(spec),
+    statusIgnored: json?.status_ignored === true
+  };
+}
+async function fetchPushRemote(http, basename4) {
+  const { status, json, text: text2 } = await getJson(http, `api/specs/${encodeURIComponent(basename4)}`);
+  if (status === 404) return null;
+  if (status !== 200) {
+    throw new VaultPullSourceError(
+      `GET /api/specs/${basename4} returned ${status}: ${text2.slice(0, 200)}`,
+      status
+    );
+  }
+  const spec = json?.spec;
+  const fm = spec?.frontmatter && typeof spec.frontmatter === "object" ? spec.frontmatter : null;
+  if (!spec || typeof spec.body !== "string" || !fm) {
+    throw new VaultPullSourceError(`GET /api/specs/${basename4} returned no usable spec`, status);
+  }
+  return {
+    id: String(spec.id ?? fm.id ?? ""),
+    updatedAt: remoteStamp(spec),
+    body: spec.body,
+    frontmatter: fm
+  };
+}
+function createVaultPushDeps({
+  baseUrl,
+  token,
+  fetchImpl,
+  vaultRoot: vaultRoot2,
+  scopeHeaders,
+  accountId,
+  vaultId,
+  ledger = createLedgerStore(vaultRoot2),
+  withListIndex = false,
+  markDirty
+}) {
+  const http = {
+    baseUrl,
+    token,
+    fetchImpl,
+    scopeHeaders,
+    accountId,
+    vaultId
+  };
+  const specsRoot = nodePath4.join(vaultRoot2, "specs");
+  return {
+    listLocal: () => listLocalSpecRelPaths(specsRoot),
+    readLocal: async (relPath) => {
+      const abs = nodePath4.join(specsRoot, relPath);
+      try {
+        const [content, stat4] = await Promise.all([fs11.readFile(abs, "utf8"), fs11.stat(abs)]);
+        return { content, hash: hashContent(content), mtimeMs: stat4.mtimeMs };
+      } catch {
+        return null;
+      }
+    },
+    readLedger: () => ledger.snapshot(),
+    fetchRemote: (basename4) => fetchPushRemote(http, basename4),
+    listRemote: withListIndex ? () => listRemoteSpecs(http) : void 0,
+    serialize: stringifySpecMarkdown,
+    putRemote: (basename4, payload) => putRemoteSpec(http, basename4, payload),
+    recordLedger: (relPath, entry) => ledger.record(relPath, entry),
+    flushLedger: () => ledger.flush(),
+    markDirty
+  };
+}
+
+// spex-console/src/lib/vault-sync/push-watch.ts
+var realClock = {
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (h) => clearTimeout(h)
+};
+var DEFAULT_PUSH_OPTIONS = {
+  debounceMs: 1e3,
+  recentPullWriteMs: 2e3,
+  maxPutsPerWindow: 20,
+  windowMs: 36e5
+};
+function formatPushTick(result) {
+  const out = [];
+  for (const p of result.pushed) {
+    out.push({ level: "info", line: `relay: pushed ${p.relPath} (${p.id ?? "?"}) to the cloud` });
+  }
+  for (const c of result.conflicts) {
+    const ref = c.id ?? c.relPath;
+    out.push({
+      level: "warn",
+      line: `relay: conflict ${c.relPath} (${c.id ?? "?"}) - the cloud copy changed since the last sync; kept both. hs pull --overwrite --only ${ref}  |  hs push --force --only ${ref} --apply`
+    });
+  }
+  for (const f of result.failed) {
+    out.push({
+      level: "warn",
+      line: `relay: push failed ${f.relPath} (${f.id ?? "?"}) - ${f.error}`
+    });
+  }
+  for (const w of result.warnings) out.push({ level: "warn", line: `relay: push warning ${w}` });
+  return out;
+}
+function createPushScheduler(deps, opts = DEFAULT_PUSH_OPTIONS) {
+  const { clock } = deps;
+  const timers = /* @__PURE__ */ new Map();
+  const ready = /* @__PURE__ */ new Set();
+  const pullWrites = /* @__PURE__ */ new Map();
+  const putTimes = [];
+  let running = null;
+  let retryHandle = null;
+  let blockedUntil = 0;
+  let disposed = false;
+  const budget = () => {
+    const cutoff = clock.now() - opts.windowMs;
+    while (putTimes.length > 0 && putTimes[0] <= cutoff) putTimes.shift();
+    return Math.max(0, opts.maxPutsPerWindow - putTimes.length);
+  };
+  function scheduleRetry(ms) {
+    if (retryHandle || disposed) return;
+    retryHandle = clock.setTimeout(() => {
+      retryHandle = null;
+      void drain();
+    }, ms);
+  }
+  async function runDrain() {
+    while (ready.size > 0 && !disposed) {
+      const wait = blockedUntil - clock.now();
+      if (wait > 0) return scheduleRetry(wait);
+      const room = budget();
+      if (room === 0) {
+        deps.log(
+          "warn",
+          `relay: push deferred - hourly write cap (${opts.maxPutsPerWindow}) reached; ${ready.size} pending`
+        );
+        return scheduleRetry(Math.max(1e3, putTimes[0] + opts.windowMs - clock.now()));
+      }
+      const batch = [...ready];
+      ready.clear();
+      let result;
+      try {
+        result = await deps.pushPaths(batch, room);
+      } catch (err) {
+        deps.log(
+          "warn",
+          `relay: push failed - ${err instanceof Error ? err.message : String(err)}`
+        );
+        continue;
+      }
+      for (const { level, line } of formatPushTick(result)) deps.log(level, line);
+      for (const p of result.pushed) if (!result.dryRun) putTimes.push(clock.now());
+      for (const d of result.deferred) ready.add(d.relPath);
+      if (result.retryAfterSec) {
+        blockedUntil = clock.now() + result.retryAfterSec * 1e3;
+        for (const f of result.failed) ready.add(f.relPath);
+      }
+    }
+  }
+  function drain() {
+    if (!running) {
+      running = runDrain().finally(() => {
+        running = null;
+        if (ready.size > 0 && !disposed && blockedUntil <= clock.now() && budget() > 0)
+          void drain();
+      });
+    }
+    return running;
+  }
+  return {
+    notify(relPath) {
+      if (disposed) return;
+      const wrote = pullWrites.get(relPath);
+      if (wrote !== void 0 && clock.now() - wrote < opts.recentPullWriteMs) return;
+      const existing = timers.get(relPath);
+      if (existing) clock.clearTimeout(existing);
+      timers.set(
+        relPath,
+        clock.setTimeout(() => {
+          timers.delete(relPath);
+          ready.add(relPath);
+          void drain();
+        }, opts.debounceMs)
+      );
+    },
+    notePullWrite(relPath) {
+      pullWrites.set(relPath, clock.now());
+      const pending = timers.get(relPath);
+      if (pending) {
+        clock.clearTimeout(pending);
+        timers.delete(relPath);
+      }
+    },
+    async idle() {
+      while (running) await running;
+    },
+    dispose() {
+      disposed = true;
+      for (const h of timers.values()) clock.clearTimeout(h);
+      timers.clear();
+      if (retryHandle) clock.clearTimeout(retryHandle);
+    }
+  };
+}
+async function startPushFileWatch(specsRoot, scheduler) {
+  const chokidar = await Promise.resolve().then(() => (init_esm2(), esm_exports));
+  const nodePath5 = await import("node:path");
+  const watcher = chokidar.watch(specsRoot, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 },
+    ignored: (p) => {
+      const rel = nodePath5.relative(specsRoot, p).split(nodePath5.sep);
+      return rel.some((seg) => seg.startsWith(".") && seg !== "");
+    }
+  });
+  const onFile = (abs) => {
+    if (!/\.md$/i.test(abs)) return;
+    scheduler.notify(nodePath5.relative(specsRoot, abs).split(nodePath5.sep).join("/"));
   };
+  watcher.on("add", onFile).on("change", onFile);
+  return () => watcher.close();
 }
 
 // spex-console/bin/run-entry.ts
@@ -6434,9 +9330,25 @@ function runEntry(name, main2, options2 = {}) {
 }
 
 // spex-console/bin/hs-vault-pull.ts
+function makeSleeper() {
+  let wakeNow = null;
+  const sleep = (ms, signal) => new Promise((resolve7) => {
+    if (signal.aborted) return resolve7();
+    const done = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      wakeNow = null;
+      resolve7();
+    };
+    const timer = setTimeout(done, ms);
+    wakeNow = done;
+    signal.addEventListener("abort", done, { once: true });
+  });
+  return { sleep, wake: () => wakeNow?.() };
+}
 function readMarkerVaultId(vaultRoot2) {
   try {
-    return parseVaultId(readFileSync12(path14.join(vaultRoot2, "heyspex.yaml"), "utf8"));
+    return parseVaultId(readFileSync13(path14.join(vaultRoot2, "heyspex.yaml"), "utf8"));
   } catch {
     return null;
   }
@@ -6513,20 +9425,118 @@ ${PULL_HELP}
     accountId: account.accountId,
     vaultId: target.vaultId
   }).headersFor("GET", "/api/specs");
-  try {
-    const result = await runVaultPull(
-      createVaultPullDeps({
+  const ledger = createLedgerStore(vaultRoot2);
+  let pushScheduler = null;
+  const deps = createVaultPullDeps({
+    baseUrl,
+    token,
+    scopeHeaders,
+    localRoot: path14.join(vaultRoot2, "specs"),
+    ledger,
+    onLocalWrite: (relPath) => pushScheduler?.notePullWrite(relPath)
+  });
+  if (args.watch) {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process4.once("SIGINT", stop);
+    process4.once("SIGTERM", stop);
+    process4.stdout.write(
+      `vault: ${target.vaultId} (source: ${target.source} \u2014 ${target.detail})
+source: ${baseUrl}
+watch: every ${args.intervalSec}s while active, backing off to ${Math.round(Math.max(DEFAULT_WATCH_OPTIONS.maxIntervalMs, args.intervalSec * 1e3) / 1e3)}s while idle
+`
+    );
+    const log = (level, line) => (level === "warn" ? process4.stderr : process4.stdout).write(`${line}
+`);
+    const { sleep, wake } = makeSleeper();
+    const dirtyIds = /* @__PURE__ */ new Set();
+    const closeDirty = watchDirtyMarker(vaultRoot2, (id) => {
+      dirtyIds.add(id);
+      wake();
+    });
+    process4.stdout.write(`dirty-trigger: ${dirtyMarkerPath(vaultRoot2)}
+`);
+    let closePushWatch = null;
+    if (args.push) {
+      const common = {
         baseUrl,
         token,
+        vaultRoot: vaultRoot2,
         scopeHeaders,
-        localRoot: path14.join(vaultRoot2, "specs")
-      }),
+        accountId: account.accountId,
+        vaultId: target.vaultId,
+        ledger,
+        markDirty: (id) => writeDirtyMarker(vaultRoot2, id)
+      };
+      const eventDeps = createVaultPushDeps(common);
+      const sweepDeps = createVaultPushDeps({ ...common, withListIndex: true });
+      const cap = DEFAULT_PUSH_OPTIONS.maxPutsPerWindow;
+      pushScheduler = createPushScheduler({
+        clock: realClock,
+        log,
+        pushPaths: (paths, maxPuts) => runVaultPush(eventDeps, {
+          dryRun: false,
+          force: args.force,
+          paths,
+          maxPuts
+        })
+      });
+      try {
+        const sweep = await runVaultPush(sweepDeps, {
+          dryRun: false,
+          force: args.force,
+          maxPuts: cap
+        });
+        const seeded = sweep.skipped.filter((i) => i.reason === "seeded").length;
+        for (const { level, line } of formatPushTick(sweep)) log(level, line);
+        process4.stdout.write(
+          `push: ready \u2014 ${seeded} spec(s) newly baselined, ${sweep.pushed.length} pushed, ${sweep.conflicts.length} conflict(s); watching specs/ (cap ${cap} writes/hour)
+`
+        );
+      } catch (err) {
+        log(
+          "warn",
+          `relay: push startup sweep failed \u2014 ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      closePushWatch = await startPushFileWatch(path14.join(vaultRoot2, "specs"), pushScheduler);
+    }
+    const summary = await runPullWatch(
+      {
+        pullOnce: () => runVaultPull(deps, { dryRun: false, overwrite: args.overwrite, only: args.only }),
+        sleep,
+        log,
+        signal: controller.signal,
+        sourceLabel: baseUrl,
+        takeDirty: () => {
+          const ids = [...dirtyIds];
+          dirtyIds.clear();
+          return ids;
+        },
+        pullDirty: (ids) => runVaultPull(deps, { dryRun: false, only: ids, direct: true })
+      },
       {
-        dryRun: !args.apply,
-        overwrite: args.overwrite,
-        only: args.only
+        ...DEFAULT_WATCH_OPTIONS,
+        baseIntervalMs: args.intervalSec * 1e3,
+        maxIntervalMs: Math.max(DEFAULT_WATCH_OPTIONS.maxIntervalMs, args.intervalSec * 1e3)
       }
     );
+    closeDirty();
+    pushScheduler?.dispose();
+    await closePushWatch?.();
+    process4.stdout.write(
+      `watch stopped after ${summary.ticks} tick(s): ${summary.written} pulled, ${summary.failed} failed
+`
+    );
+    process4.exitCode = PULL_EXIT.OK;
+    return;
+  }
+  try {
+    const result = await runVaultPull(deps, {
+      dryRun: !args.apply,
+      overwrite: args.overwrite,
+      only: args.only
+    });
     if (args.json) {
       process4.stdout.write(
         `${JSON.stringify(