@wrongstack/core 0.303.0 → 0.305.1

package/dist/infrastructure/index.js

@@ -30,9 +30,9 @@ var init_protocol = __esm({
 // src/session-catalog/endpoint.ts
 import { createHash as createHash2 } from "node:crypto";
 import * as os3 from "node:os";
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 function normalizedPath(value) {
-  const resolved = path8.resolve(value);
+  const resolved = path9.resolve(value);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function sessionCatalogProjectServerKey(projectDir) {
@@ -43,10 +43,10 @@ function sessionCatalogProjectServerEndpoint(projectDir) {
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\wrongstack-session-catalog-v${SESSION_CATALOG_PROTOCOL_VERSION}-${key}`;
   }
-  return path8.join(os3.tmpdir(), `wssc-v${SESSION_CATALOG_PROTOCOL_VERSION}`, `${key}.sock`);
+  return path9.join(os3.tmpdir(), `wssc-v${SESSION_CATALOG_PROTOCOL_VERSION}`, `${key}.sock`);
 }
 function sessionCatalogProjectServerMetadataPath(projectDir) {
-  return path8.join(projectDir, SESSION_CATALOG_METADATA_FILE);
+  return path9.join(projectDir, SESSION_CATALOG_METADATA_FILE);
 }
 var SESSION_CATALOG_METADATA_FILE;
 var init_endpoint = __esm({
@@ -59,9 +59,9 @@ var init_endpoint = __esm({
 
 // src/session-catalog/client.ts
 import { spawn } from "node:child_process";
-import * as fs6 from "node:fs";
+import * as fs7 from "node:fs";
 import * as net from "node:net";
-import * as path9 from "node:path";
+import * as path10 from "node:path";
 import { fileURLToPath } from "node:url";
 function locateServer(moduleUrl, exists) {
   for (const candidate of [
@@ -78,22 +78,22 @@ function locateServer(moduleUrl, exists) {
   }
   return null;
 }
-function resolveSessionCatalogDaemonAvailability(moduleUrl = import.meta.url, exists = fs6.existsSync) {
+function resolveSessionCatalogDaemonAvailability(moduleUrl = import.meta.url, exists = fs7.existsSync) {
   if (process.env["WRONGSTACK_SESSION_CATALOG_INLINE"] || process.env["WRONGSTACK_SESSION_CATALOG_SERVER"] === "0")
     return { kind: "inline-requested" };
   const url = locateServer(moduleUrl, exists);
   return url ? { kind: "available", url } : { kind: "missing-build" };
 }
-function resolveSessionCatalogProjectServerUrl(moduleUrl = import.meta.url, exists = fs6.existsSync) {
+function resolveSessionCatalogProjectServerUrl(moduleUrl = import.meta.url, exists = fs7.existsSync) {
   const availability = resolveSessionCatalogDaemonAvailability(moduleUrl, exists);
   return availability.kind === "available" ? availability.url : null;
 }
 function normalize2(value) {
-  const resolved = path9.resolve(value);
+  const resolved = path10.resolve(value);
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function delay(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 var CONNECT_TIMEOUT_MS, START_TIMEOUT_MS, CALL_TIMEOUT_MS, MAX_PENDING_REQUESTS, MAX_EVENT_LISTENERS, SessionCatalogProjectClient;
 var init_client = __esm({
@@ -172,7 +172,7 @@ var init_client = __esm({
         if (result.stopped) {
           const metadataPath = sessionCatalogProjectServerMetadataPath(this.options.projectDir);
           const deadline = Date.now() + 5e3;
-          while (fs6.existsSync(metadataPath) && Date.now() < deadline) await delay(20);
+          while (fs7.existsSync(metadataPath) && Date.now() < deadline) await delay(20);
           if (result.pid && result.pid !== process.pid) {
             while (Date.now() < deadline) {
               try {
@@ -194,8 +194,8 @@ var init_client = __esm({
         this.socket = null;
         this.info = null;
         if (socket && !socket.destroyed)
-          await new Promise((resolve8) => {
-            socket.once("close", resolve8);
+          await new Promise((resolve9) => {
+            socket.once("close", resolve9);
             socket.end();
           });
       }
@@ -233,7 +233,7 @@ var init_client = __esm({
         this.info = null;
         this.authToken = void 0;
         this.buffer = "";
-        return new Promise((resolve8, reject) => {
+        return new Promise((resolve9, reject) => {
           const socket = net.createConnection(this.endpoint);
           this.socket = socket;
           socket.setEncoding("utf8");
@@ -246,7 +246,7 @@ var init_client = __esm({
             clearTimeout(timer);
             this.connectResolve = null;
             this.connectReject = null;
-            resolve8();
+            resolve9();
           };
           this.connectReject = (error) => {
             clearTimeout(timer);
@@ -265,7 +265,7 @@ var init_client = __esm({
         if (this.authToken === void 0) {
           try {
             const parsed = JSON.parse(
-              fs6.readFileSync(sessionCatalogProjectServerMetadataPath(this.options.projectDir), "utf8")
+              fs7.readFileSync(sessionCatalogProjectServerMetadataPath(this.options.projectDir), "utf8")
             );
             if (typeof parsed.authToken === "string" && parsed.authToken)
               this.authToken = parsed.authToken;
@@ -291,7 +291,7 @@ var init_client = __esm({
         });
         if (encoded.length > SESSION_CATALOG_MAX_FRAME_CHARS)
           return Promise.reject(new Error("Session Catalog request exceeded frame limit"));
-        return new Promise((resolve8, reject) => {
+        return new Promise((resolve9, reject) => {
           const timer = setTimeout(() => {
             const pending = this.pending.get(id);
             if (!pending) return;
@@ -303,7 +303,7 @@ var init_client = __esm({
             );
           }, timeoutMs);
           timer.unref?.();
-          this.pending.set(id, { resolve: resolve8, reject, timer });
+          this.pending.set(id, { resolve: resolve9, reject, timer });
           socket.write(encoded);
         });
       }
@@ -420,10 +420,10 @@ __export(registry_exports, {
   hasProjectSessionRegistry: () => hasProjectSessionRegistry
 });
 import { randomUUID } from "node:crypto";
-import * as fs7 from "node:fs/promises";
-import * as path10 from "node:path";
+import * as fs8 from "node:fs/promises";
+import * as path11 from "node:path";
 function getProjectSessionRegistry(globalRoot) {
-  const key = globalRoot !== void 0 ? path10.resolve(globalRoot) : lastRegistryKey;
+  const key = globalRoot !== void 0 ? path11.resolve(globalRoot) : lastRegistryKey;
   if (!key)
     throw new Error("SessionRegistry not initialized. Call getSessionRegistry(globalRoot) first.");
   let registry = registries.get(key);
@@ -446,7 +446,7 @@ function getProjectSessionRegistry(globalRoot) {
 }
 function hasProjectSessionRegistry(globalRoot) {
   if (globalRoot === void 0) return registries.size > 0;
-  return registries.has(path10.resolve(globalRoot));
+  return registries.has(path11.resolve(globalRoot));
 }
 var HEARTBEAT_INTERVAL_MS, AGENT_WRITE_THROTTLE_MS, MAX_PROJECT_CLIENTS, MAX_GLOBAL_ROOTS, ProjectSessionRegistry, registries, lastRegistryKey;
 var init_registry = __esm({
@@ -472,7 +472,7 @@ var init_registry = __esm({
       agentTimer;
       lastAgentWriteAt = 0;
       bindingKey(projectDir) {
-        const resolved = path10.resolve(projectDir);
+        const resolved = path11.resolve(projectDir);
         return process.platform === "win32" ? resolved.toLowerCase() : resolved;
       }
       async closeBinding(binding) {
@@ -482,7 +482,7 @@ var init_registry = __esm({
         await binding.client.close();
       }
       binding(projectSlug2, projectRoot) {
-        const projectDir = path10.join(this.globalRoot, "projects", projectSlug2);
+        const projectDir = path11.join(this.globalRoot, "projects", projectSlug2);
         const key = this.bindingKey(projectDir);
         let binding = this.clients.get(key);
         if (!binding) {
@@ -497,7 +497,7 @@ var init_registry = __esm({
           }
           binding = {
             projectDir,
-            projectRoot: path10.resolve(projectRoot),
+            projectRoot: path11.resolve(projectRoot),
             client: new SessionCatalogProjectClient({ projectDir, projectRoot })
           };
           this.clients.set(key, binding);
@@ -658,20 +658,20 @@ var init_registry = __esm({
         }
       }
       async list() {
-        const projectsDir = path10.join(this.globalRoot, "projects");
+        const projectsDir = path11.join(this.globalRoot, "projects");
         let directories = [];
         try {
-          directories = (await fs7.readdir(projectsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).slice(0, 1e3).map((entry) => entry.name);
+          directories = (await fs8.readdir(projectsDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).slice(0, 1e3).map((entry) => entry.name);
         } catch {
           return [];
         }
         const snapshots = await Promise.all(
           directories.map(async (slug) => {
-            const projectDir = path10.join(projectsDir, slug);
+            const projectDir = path11.join(projectsDir, slug);
             let client;
             try {
               const metadata = JSON.parse(
-                await fs7.readFile(sessionCatalogProjectServerMetadataPath(projectDir), "utf8")
+                await fs8.readFile(sessionCatalogProjectServerMetadataPath(projectDir), "utf8")
               );
               if (typeof metadata.projectRoot !== "string" || !metadata.projectRoot) return [];
               client = new SessionCatalogProjectClient({
@@ -690,14 +690,14 @@ var init_registry = __esm({
       }
       async listByProject(projectSlug2) {
         const current = this.current;
-        if (current && path10.basename(current.binding.projectDir) === projectSlug2) {
+        if (current && path11.basename(current.binding.projectDir) === projectSlug2) {
           return current.binding.client.call("list_live", {}).catch(() => []);
         }
-        const projectDir = path10.join(this.globalRoot, "projects", projectSlug2);
+        const projectDir = path11.join(this.globalRoot, "projects", projectSlug2);
         let client;
         try {
           const metadata = JSON.parse(
-            await fs7.readFile(sessionCatalogProjectServerMetadataPath(projectDir), "utf8")
+            await fs8.readFile(sessionCatalogProjectServerMetadataPath(projectDir), "utf8")
           );
           if (typeof metadata.projectRoot !== "string") return [];
           client = new SessionCatalogProjectClient({ projectDir, projectRoot: metadata.projectRoot });
@@ -719,7 +719,7 @@ var init_registry = __esm({
         });
       }
       get registryPath() {
-        return path10.join(this.globalRoot, "projects");
+        return path11.join(this.globalRoot, "projects");
       }
       async dispose() {
         await this.unregister().catch(() => void 0);
@@ -2192,9 +2192,9 @@ function createContextManagerTool(opts = {}) {
 var contextManagerTool = createContextManagerTool();
 
 // src/boot.ts
-import * as fs8 from "node:fs/promises";
+import * as fs9 from "node:fs/promises";
 import * as os4 from "node:os";
-import * as path11 from "node:path";
+import * as path12 from "node:path";
 
 // src/security/secret-vault.ts
 import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
@@ -2571,23 +2571,21 @@ function unwrapDataKey(buf, keyFile) {
     });
   }
 }
-function checkKeyFilePermissions(keyFile, opts) {
-  if (process.platform === "win32") return;
+function keyFileNeedsHardening(keyFile, opts) {
+  if (process.platform === "win32") return false;
   const warn = opts?.warn ?? ((msg) => console.warn(msg));
   try {
-    const stat4 = fs2.statSync(keyFile);
-    const actualMode = stat4.mode & 511;
+    const stat5 = fs2.statSync(keyFile);
+    const actualMode = stat5.mode & 511;
     if (actualMode !== KEY_FILE_MODE) {
-      void restrictFilePermissions(keyFile, {
-        label: "secret-vault",
-        warn
-      }).catch(() => void 0);
       warn(
         `Key file ${keyFile} has mode ${actualMode.toString(8)} \u2014 expected ${KEY_FILE_MODE.toString(8)}. Hardening\u2026`
       );
+      return true;
     }
   } catch {
   }
+  return false;
 }
 function writeKeyFileAtomicSync(keyFile, content) {
   const tmp = `${keyFile}.${randomBytes(4).toString("hex")}.tmp`;
@@ -2653,6 +2651,14 @@ var DefaultSecretVault = class {
     }).catch(() => void 0);
     this.pendingHardening.push(p);
   }
+  /** Detect and schedule repair of a pre-existing POSIX key with loose mode bits. */
+  checkKeyFilePermissions() {
+    if (keyFileNeedsHardening(this.keyFile, {
+      warn: (msg) => this.logWarn(msg)
+    })) {
+      this.scheduleKeyHardening();
+    }
+  }
   /** Flush all pending key-file hardening promises. */
   flushHardening() {
     if (this.pendingHardening.length === 0) return Promise.resolve();
@@ -2740,7 +2746,7 @@ var DefaultSecretVault = class {
       writeKeyFileAtomicSync(this.keyFile, keyFileBuf);
     }
     this.scheduleKeyHardening();
-    checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+    this.checkKeyFilePermissions();
     this.key = newKey;
     this._keyVersion = newVersion;
     return { oldVersion, newVersion };
@@ -2756,12 +2762,9 @@ var DefaultSecretVault = class {
     const passphrase = getVaultPassphrase();
     if (!passphrase || !this.key) return;
     try {
-      writeKeyFileAtomicSync(
-        this.keyFile,
-        wrapDataKey(this.key, this._keyVersion, passphrase)
-      );
+      writeKeyFileAtomicSync(this.keyFile, wrapDataKey(this.key, this._keyVersion, passphrase));
       this.scheduleKeyHardening();
-      checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+      this.checkKeyFilePermissions();
     } catch {
     }
   }
@@ -2773,13 +2776,13 @@ var DefaultSecretVault = class {
         const { key: key2, version } = unwrapDataKey(buf, this.keyFile);
         this.key = key2;
         this._keyVersion = version;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         return this.key;
       }
       if (buf.length === KEY_BYTES) {
         this.key = buf;
         this._keyVersion = 1;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         this.migrateToWrappedIfPassphrase();
         return this.key;
       }
@@ -2803,7 +2806,7 @@ var DefaultSecretVault = class {
         }
         this.key = Buffer.from(key2);
         this._keyVersion = version;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         this.migrateToWrappedIfPassphrase();
         return this.key;
       }
@@ -2830,13 +2833,13 @@ var DefaultSecretVault = class {
         const { key: winnerKey, version } = unwrapDataKey(buf, this.keyFile);
         this.key = winnerKey;
         this._keyVersion = version;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         return this.key;
       }
       if (buf.length === KEY_BYTES) {
         this.key = buf;
         this._keyVersion = 1;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         return this.key;
       }
       if (buf.length === VERSIONED_KEY_FILE_SIZE) {
@@ -2852,7 +2855,7 @@ var DefaultSecretVault = class {
         const winnerKey = buf.subarray(KEY_FILE_MAGIC.length + 1);
         this.key = Buffer.from(winnerKey);
         this._keyVersion = version;
-        checkKeyFilePermissions(this.keyFile, { warn: (msg) => this.logWarn(msg) });
+        this.checkKeyFilePermissions();
         return this.key;
       }
       throw new ConfigError({
@@ -3190,6 +3193,9 @@ var DEFAULT_TOOLS_CONFIG = Object.freeze({
   disabledTools: Object.freeze([]),
   autoExtendLimit: true,
   restrictToProjectRoot: true,
+  // Off by default: the board is a record of the work, not a permit for it.
+  // See ToolsConfig.kanbanGovernance for what turning it on costs and gates.
+  kanbanGovernance: false,
   loopDetection: Object.freeze({
     mode: "steer-then-cut",
     steerThreshold: 3,
@@ -3247,6 +3253,7 @@ var CONFIG_BEHAVIOR_DEFAULTS = {
     disabledTools: DEFAULT_TOOLS_CONFIG.disabledTools,
     autoExtendLimit: DEFAULT_TOOLS_CONFIG.autoExtendLimit,
     restrictToProjectRoot: DEFAULT_TOOLS_CONFIG.restrictToProjectRoot,
+    kanbanGovernance: DEFAULT_TOOLS_CONFIG.kanbanGovernance,
     loopDetection: DEFAULT_TOOLS_CONFIG.loopDetection
   },
   log: { level: "info" },
@@ -3631,10 +3638,18 @@ var IN_PROJECT_DENIED_PATHS = [
   {
     path: "tools.restrictToProjectRoot",
     reason: "The other half of the filesystem confinement switch."
+  },
+  {
+    // Denied for the direction that loosens: the flag defaults to false, so a
+    // repo can only ever use it to turn OFF a gate the user deliberately
+    // enabled. Same class as `tools.restrictToProjectRoot` — a control the
+    // operator owns, not the checked-out repository.
+    path: "tools.kanbanGovernance",
+    reason: "Repo-committed config could disable a Kanban governance gate the operator switched on, letting product mutations run outside any managed card."
   }
 ];
-function deleteNestedPath(target, path12) {
-  const segments = path12.split(".");
+function deleteNestedPath(target, path13) {
+  const segments = path13.split(".");
   const last = segments[segments.length - 1];
   if (last === void 0) return false;
   let cursor = target;
@@ -3691,16 +3706,16 @@ function assertInProjectAllowListComplete() {
     );
   }
   const orphanedPaths = IN_PROJECT_DENIED_PATHS.filter(
-    ({ path: path12 }) => !IN_PROJECT_ALLOWED_KEYS.has(path12.split(".")[0] ?? "")
-  ).map(({ path: path12 }) => path12);
+    ({ path: path13 }) => !IN_PROJECT_ALLOWED_KEYS.has(path13.split(".")[0] ?? "")
+  ).map(({ path: path13 }) => path13);
   if (orphanedPaths.length > 0) {
     problems.push(
       `IN_PROJECT_DENIED_PATHS entr(ies) whose top-level parent is not allowed: ` + orphanedPaths.join(", ") + ". The parent is already stripped wholesale, so the nested denial is dead \u2014 remove it."
     );
   }
   const malformedPaths = IN_PROJECT_DENIED_PATHS.filter(
-    ({ path: path12 }) => path12.split(".").length < 2 || path12.split(".").some((s) => s.length === 0)
-  ).map(({ path: path12 }) => path12);
+    ({ path: path13 }) => path13.split(".").length < 2 || path13.split(".").some((s) => s.length === 0)
+  ).map(({ path: path13 }) => path13);
   if (malformedPaths.length > 0) {
     problems.push(
       `IN_PROJECT_DENIED_PATHS entr(ies) are not dotted nested paths: ` + malformedPaths.join(", ") + ". Top-level keys belong in KNOWN_DENIED_IN_PROJECT instead."
@@ -3728,8 +3743,8 @@ function stripUnsafeInProjectFields(inProject, sourcePath, warn = (msg) => conso
     }
     stripped.push(k);
   }
-  for (const { path: path12 } of IN_PROJECT_DENIED_PATHS) {
-    if (deleteNestedPath(out, path12)) stripped.push(path12);
+  for (const { path: path13 } of IN_PROJECT_DENIED_PATHS) {
+    if (deleteNestedPath(out, path13)) stripped.push(path13);
   }
   if (stripped.length > 0) {
     warn(
@@ -4338,8 +4353,8 @@ var DefaultConfigLoader = class _DefaultConfigLoader {
     const t0 = Date.now();
     let mtimeMs = null;
     try {
-      const stat4 = await fs5.stat(file);
-      mtimeMs = stat4.mtimeMs;
+      const stat5 = await fs5.stat(file);
+      mtimeMs = stat5.mtimeMs;
       const cached = this.jsonCache.get(file);
       if (cached && cached.mtimeMs === mtimeMs) {
         return structuredClone(cached.value);
@@ -4630,6 +4645,115 @@ function isAlreadyExistsError(error) {
   return error?.code === "EEXIST";
 }
 
+// src/utils/project-state-guard.ts
+import * as fs6 from "node:fs";
+import * as fsp3 from "node:fs/promises";
+import * as path8 from "node:path";
+var PROJECT_STATE_DIRECTORY = ".wrongstack";
+var DEFAULT_POLL_INTERVAL_MS = 1e3;
+var REPAIR_DEBOUNCE_MS = 25;
+var ACTIVE_GUARD_KEY = /* @__PURE__ */ Symbol.for("wrongstack.activeProjectStateGuard");
+var globalScope = globalThis;
+globalScope[ACTIVE_GUARD_KEY] ??= {};
+var activeGuard = globalScope[ACTIVE_GUARD_KEY];
+function normalizedRoot(root) {
+  const resolved = path8.resolve(root);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function concernsProjectState(filename) {
+  if (filename === null) return true;
+  const firstSegment = String(filename).replaceAll("\\", "/").split("/")[0];
+  return firstSegment?.toLowerCase() === PROJECT_STATE_DIRECTORY;
+}
+async function startProjectStateGuard(projectRoot, options = {}) {
+  const root = path8.resolve(projectRoot);
+  const directory = path8.join(root, PROJECT_STATE_DIRECTORY);
+  const pollIntervalMs = Math.max(25, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+  let closed = false;
+  let repairPending = false;
+  let repairInFlight;
+  let repairTimer;
+  const ensureDirectory = async () => {
+    await fsp3.mkdir(directory, { recursive: true });
+  };
+  const ensureInvariant = async () => {
+    await ensureDirectory();
+    try {
+      await ensureProjectGitignore(root);
+    } catch (error) {
+      options.onError?.(error);
+    }
+  };
+  const scheduleRepair = () => {
+    if (closed) return;
+    repairPending = true;
+    if (repairInFlight || repairTimer) return;
+    repairTimer = setTimeout(() => {
+      repairTimer = void 0;
+      repairInFlight = (async () => {
+        while (!closed && repairPending) {
+          repairPending = false;
+          try {
+            const rootState = await fsp3.stat(root).catch(() => void 0);
+            if (!rootState?.isDirectory()) return;
+            await ensureInvariant();
+          } catch (error) {
+            options.onError?.(error);
+          }
+        }
+      })().finally(() => {
+        repairInFlight = void 0;
+        if (repairPending && !closed) scheduleRepair();
+      });
+    }, REPAIR_DEBOUNCE_MS);
+    repairTimer.unref?.();
+  };
+  await ensureDirectory();
+  await ensureProjectGitignore(root).catch((error) => options.onError?.(error));
+  let watcher;
+  try {
+    watcher = fs6.watch(root, { persistent: false }, (_eventType, filename) => {
+      if (concernsProjectState(filename) || String(filename).toLowerCase() === ".gitignore") {
+        scheduleRepair();
+      }
+    });
+    watcher.on("error", (error) => {
+      options.onError?.(error);
+      watcher = void 0;
+      scheduleRepair();
+    });
+  } catch (error) {
+    options.onError?.(error);
+  }
+  const poll = setInterval(scheduleRepair, pollIntervalMs);
+  poll.unref?.();
+  return {
+    directory,
+    close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(poll);
+      if (repairTimer) clearTimeout(repairTimer);
+      repairTimer = void 0;
+      try {
+        watcher?.close();
+      } catch {
+      }
+      watcher = void 0;
+    }
+  };
+}
+async function activateProjectStateGuard(projectRoot, options = {}) {
+  const root = normalizedRoot(projectRoot);
+  if (activeGuard.root === root && activeGuard.guard) return activeGuard.guard;
+  const next = await startProjectStateGuard(projectRoot, options);
+  const previous = activeGuard.guard;
+  activeGuard.root = root;
+  activeGuard.guard = next;
+  previous?.close();
+  return next;
+}
+
 // src/boot.ts
 async function bootConfig(options = {}) {
   const {
@@ -4638,17 +4762,18 @@ async function bootConfig(options = {}) {
     loadSyncConfig = true,
     skipIdentityValidation = false
   } = options;
-  const cwd = typeof flags["cwd"] === "string" ? path11.resolve(flags["cwd"]) : process.cwd();
+  const cwd = typeof flags["cwd"] === "string" ? path12.resolve(flags["cwd"]) : process.cwd();
   const pathResolver = new DefaultPathResolver(cwd);
   const projectRoot = pathResolver.projectRoot;
   const projectIdentityRoot = canonicalProjectRoot(projectRoot);
   const userHome = os4.homedir();
   const wpaths = resolveWstackPaths({ projectRoot });
   assertProjectRootOutsideStateDir(projectRoot, wpaths.globalRoot);
-  await fs8.mkdir(wpaths.globalRoot, { recursive: true });
-  await fs8.mkdir(wpaths.profilesDir, { recursive: true });
-  await fs8.mkdir(wpaths.projectDir, { recursive: true });
-  await fs8.mkdir(wpaths.projectSessions, { recursive: true });
+  await activateProjectStateGuard(projectRoot);
+  await fs9.mkdir(wpaths.globalRoot, { recursive: true });
+  await fs9.mkdir(wpaths.profilesDir, { recursive: true });
+  await fs9.mkdir(wpaths.projectDir, { recursive: true });
+  await fs9.mkdir(wpaths.projectSessions, { recursive: true });
   let registeredProjectId;
   try {
     registeredProjectId = (await readProjectIdentity(projectRoot))?.projectId;
@@ -4823,7 +4948,7 @@ async function migrateLegacyConfig(wpaths) {
   const rootFp = wpaths.globalConfig;
   let legacyRaw;
   try {
-    legacyRaw = await fs8.readFile(rootFp, "utf8");
+    legacyRaw = await fs9.readFile(rootFp, "utf8");
   } catch {
     return;
   }
@@ -4836,12 +4961,12 @@ async function migrateLegacyConfig(wpaths) {
   );
   const profileFp = wpaths.profileConfig(activeProfile);
   try {
-    await fs8.access(profileFp);
+    await fs9.access(profileFp);
     return;
   } catch (err) {
     if (err.code !== "ENOENT") return;
   }
-  await fs8.mkdir(path11.dirname(profileFp), { recursive: true });
+  await fs9.mkdir(path12.dirname(profileFp), { recursive: true });
   const profileContent = { ...result.value };
   delete profileContent["activeProfile"];
   await atomicWrite(profileFp, JSON.stringify(profileContent, null, 2), { mode: 384 });
@@ -4853,64 +4978,64 @@ async function migrateLegacyConfig(wpaths) {
 }
 var PROFILE_STATE_PAIRS = [
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "statusline.json"),
+    globalSrc: (w) => path12.join(w.globalRoot, "statusline.json"),
     profileDst: (w, n) => w.profileStatuslineConfig(n)
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "mode.json"),
+    globalSrc: (w) => path12.join(w.globalRoot, "mode.json"),
     profileDst: (w, n) => w.profileModeConfig(n)
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "provider-status.json"),
+    globalSrc: (w) => path12.join(w.globalRoot, "provider-status.json"),
     profileDst: (w, n) => w.profileProviderStatus(n)
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "update-cache.json"),
+    globalSrc: (w) => path12.join(w.globalRoot, "update-cache.json"),
     profileDst: (w, n) => w.profileUpdateCache(n)
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "memory.md"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "memory.md")
+    globalSrc: (w) => path12.join(w.globalRoot, "memory.md"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "memory.md")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "history"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "history")
+    globalSrc: (w) => path12.join(w.globalRoot, "history"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "history")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "sync.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "sync.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "sync.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "sync.json")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "sync-state.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "sync-state.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "sync-state.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "sync-state.json")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "prompt-usage.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "prompt-usage.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "prompt-usage.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "prompt-usage.json")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "custom-context-modes.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "custom-context-modes.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "custom-context-modes.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "custom-context-modes.json")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "desktop.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "desktop.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "desktop.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "desktop.json")
   },
   {
-    globalSrc: (w) => path11.join(w.globalRoot, "installed-skills.json"),
-    profileDst: (w, n) => path11.join(w.profilesDir, n, "installed-skills.json")
+    globalSrc: (w) => path12.join(w.globalRoot, "installed-skills.json"),
+    profileDst: (w, n) => path12.join(w.profilesDir, n, "installed-skills.json")
   },
   ...["skills", "prompts", "instructions", "design-kits", "desktop", "settings"].map(
     (directory) => ({
-      globalSrc: (w) => path11.join(w.globalRoot, directory),
-      profileDst: (w, n) => path11.join(w.profilesDir, n, directory)
+      globalSrc: (w) => path12.join(w.globalRoot, directory),
+      profileDst: (w, n) => path12.join(w.profilesDir, n, directory)
     })
   )
 ];
 async function migrateProfileFiles(wpaths) {
   let profileName = wpaths.profileName;
   try {
-    const raw = await fs8.readFile(wpaths.globalConfig, "utf8");
+    const raw = await fs9.readFile(wpaths.globalConfig, "utf8");
     const parsed = safeParse(raw);
     if (parsed.ok && parsed.value && typeof parsed.value.activeProfile === "string") {
       profileName = safeProfileName(parsed.value.activeProfile);
@@ -4918,7 +5043,7 @@ async function migrateProfileFiles(wpaths) {
   } catch {
   }
   try {
-    await fs8.mkdir(path11.join(wpaths.profilesDir, profileName), { recursive: true });
+    await fs9.mkdir(path12.join(wpaths.profilesDir, profileName), { recursive: true });
   } catch {
     return;
   }
@@ -4927,16 +5052,16 @@ async function migrateProfileFiles(wpaths) {
     const dst = pair.profileDst(wpaths, profileName);
     let srcIsDir;
     try {
-      srcIsDir = (await fs8.stat(src)).isDirectory();
+      srcIsDir = (await fs9.stat(src)).isDirectory();
     } catch {
       continue;
     }
     try {
-      const dstStat = await fs8.stat(dst);
+      const dstStat = await fs9.stat(dst);
       if (dstStat.isDirectory() === srcIsDir) {
         continue;
       }
-      await fs8.rm(dst, { recursive: true, force: true });
+      await fs9.rm(dst, { recursive: true, force: true });
     } catch (err) {
       const code = err.code;
       if (code !== "ENOENT") {
@@ -4947,19 +5072,19 @@ async function migrateProfileFiles(wpaths) {
     }
     try {
       if (srcIsDir) {
-        await fs8.cp(src, dst, { recursive: true, errorOnExist: false, force: false });
+        await fs9.cp(src, dst, { recursive: true, errorOnExist: false, force: false });
       } else {
-        const content = await fs8.readFile(src);
-        await fs8.writeFile(dst, content, { mode: 384 });
+        const content = await fs9.readFile(src);
+        await fs9.writeFile(dst, content, { mode: 384 });
       }
     } catch {
     }
   }
 }
 function assertProjectRootOutsideStateDir(projectRoot, globalRoot) {
-  const stateNamespace = path11.resolve(globalRoot, "projects");
-  const rel = path11.relative(stateNamespace, path11.resolve(projectRoot));
-  if (rel.startsWith("..") || path11.isAbsolute(rel)) return;
+  const stateNamespace = path12.resolve(globalRoot, "projects");
+  const rel = path12.relative(stateNamespace, path12.resolve(projectRoot));
+  if (rel.startsWith("..") || path12.isAbsolute(rel)) return;
   throw new Error(
     `Refusing to start: the resolved project root is inside WrongStack's per-project state directory.
   project root: ${projectRoot}
@@ -4969,7 +5094,7 @@ This usually means a WrongStack process was spawned with a state path as its wor
 }
 async function writeProjectMeta(paths, projectRoot, projectId) {
   try {
-    await fs8.mkdir(paths.projectDir, { recursive: true });
+    await fs9.mkdir(paths.projectDir, { recursive: true });
     const meta = {
       hash: paths.projectHash,
       slug: paths.projectSlug,
@@ -4982,10 +5107,10 @@ async function writeProjectMeta(paths, projectRoot, projectId) {
   }
 }
 async function registerProjectInManifest(paths, projectRoot, events, workingDir, projectId) {
-  const manifestPath = path11.join(paths.globalRoot, "projects.json");
+  const manifestPath = path12.join(paths.globalRoot, "projects.json");
   try {
     const t0 = Date.now();
-    const raw = await fs8.readFile(manifestPath, "utf8");
+    const raw = await fs9.readFile(manifestPath, "utf8");
     events?.emit("storage.read", {
       sessionId: "~boot~",
       store: "project",
@@ -5011,7 +5136,7 @@ async function registerProjectInManifest(paths, projectRoot, events, workingDir,
   try {
     let manifest;
     try {
-      const raw = await fs8.readFile(manifestPath, "utf8");
+      const raw = await fs9.readFile(manifestPath, "utf8");
       manifest = JSON.parse(raw);
     } catch {
       manifest = { projects: [] };
@@ -5024,7 +5149,7 @@ async function registerProjectInManifest(paths, projectRoot, events, workingDir,
       if (workingDir) existing.lastWorkingDir = workingDir;
     } else {
       const slug = paths.projectSlug;
-      const name = path11.basename(projectRoot);
+      const name = path12.basename(projectRoot);
       const entry = {
         name,
         root: projectRoot,
@@ -5058,32 +5183,32 @@ async function registerProjectInManifest(paths, projectRoot, events, workingDir,
   }
 }
 async function cleanupStaleProjects(wpaths) {
-  const projectsRoot = path11.dirname(wpaths.projectDir);
+  const projectsRoot = path12.dirname(wpaths.projectDir);
   let entries;
   try {
-    entries = await fs8.readdir(projectsRoot, { withFileTypes: true });
+    entries = await fs9.readdir(projectsRoot, { withFileTypes: true });
   } catch {
     return;
   }
-  const stateNamespace = path11.resolve(projectsRoot);
+  const stateNamespace = path12.resolve(projectsRoot);
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const projectPath = path11.join(projectsRoot, entry.name);
-    const metaPath = path11.join(projectPath, "meta.json");
+    const projectPath = path12.join(projectsRoot, entry.name);
+    const metaPath = path12.join(projectPath, "meta.json");
     try {
-      const raw = await fs8.readFile(metaPath, "utf8");
+      const raw = await fs9.readFile(metaPath, "utf8");
       const meta = JSON.parse(raw);
       if (typeof meta.root !== "string") continue;
-      const rel = path11.relative(stateNamespace, path11.resolve(meta.root));
-      const nested = rel !== "" && !rel.startsWith("..") && !path11.isAbsolute(rel);
+      const rel = path12.relative(stateNamespace, path12.resolve(meta.root));
+      const nested = rel !== "" && !rel.startsWith("..") && !path12.isAbsolute(rel);
       if (nested) {
-        await fs8.rm(projectPath, { recursive: true, force: true });
+        await fs9.rm(projectPath, { recursive: true, force: true });
         continue;
       }
       try {
-        await fs8.access(meta.root);
+        await fs9.access(meta.root);
       } catch {
-        await fs8.rm(projectPath, { recursive: true, force: true });
+        await fs9.rm(projectPath, { recursive: true, force: true });
       }
     } catch {
     }