superbee 0.1.4-pre.1 → 0.1.5-pre.1

package/README.md

@@ -40,24 +40,32 @@ know invisible to the humans they work for. Superbee fixes all three:
 The npm package ships one self-contained executable with zero runtime dependencies, plus an
 Agent Skill that teaches agents how to use it.
 
-## Install Steps
+## How do I download Superbee on Windows?
 
-**Requirements: Node.js 20 or newer on macOS, Linux, or Windows.** On Windows, Superbee keeps
-per-user operational state under `%LOCALAPPDATA%\Superbee` and uses Windows-native containment and
-path-identity checks instead of relying on synthesized POSIX mode bits. Native Windows behavior and
-the globally installed `superbee.cmd` entrypoint are covered by the required CI contract.
+**Requirements: Node.js 20 or newer on macOS, Linux, or native Windows.** You do not need WSL,
+Ubuntu, or Docker. On Windows, Superbee keeps per-user operational state under
+`%LOCALAPPDATA%\Superbee`; npm installs the command as `superbee.cmd`.
 
-1. Install the CLI globally:
+Superbee currently has two npm release channels:
 
-   ```sh
-   npm install -g superbee
-   ```
+- `latest` is the stable channel selected by bare `superbee`. Its current release predates native
+  Windows support.
+- `next` is the prerelease channel. It contains the current native-Windows build.
 
-2. Once superbee is installed, ask your AI agent to run `superbee setup`. Setup walks the
-   agent through the remaining integration steps (Agent Skill, SessionStart hook, MCP
-   registration) and orients it to the Superbee environment. It is read-only — it inspects
-   your configuration and returns one safe next command at a time, so the agent (with your
-   approval) performs any actual changes.
+Install the current prerelease on Windows:
+
+```powershell
+npm install -g superbee@next
+superbee.cmd setup
+```
+
+On macOS or Linux, the stable channel remains available with `npm install -g superbee`. To test the
+same prerelease as Windows, install `superbee@next` instead.
+
+After installation, ask your AI agent to run `superbee setup` (`superbee.cmd setup` when invoking
+the Windows shim explicitly). Setup walks the agent through Agent Skill, SessionStart hook, and MCP
+registration. It is read-only: it inspects your configuration and returns one safe next command at
+a time, so the agent performs any actual changes with your approval.
 
 Upgrading from the legacy `@holaxis/aslite` package or the retired marketplace plugin? Install
 `superbee` alongside it, have your agent run `superbee setup` to migrate the exact legacy

package/dist/publication-bridge.mjs

@@ -3947,46 +3947,69 @@ async function selectLockRoot(options2) {
   await ensurePrivateLockRoot(lockRoot);
   return lockRoot;
 }
+var WINDOWS_CLAIM_CONTENTION_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
+async function classifyLockClaimFailure(error, lockPath) {
+  const code = error.code;
+  if (code === "EEXIST") return "contention";
+  if (process.platform !== "win32" || !WINDOWS_CLAIM_CONTENTION_CODES.has(code ?? "")) return "terminal";
+  try {
+    await fs.lstat(lockPath);
+    return "contention";
+  } catch (probeError) {
+    const probeCode = probeError.code;
+    return probeCode === "ENOENT" || probeCode === "ENOTDIR" ? "unwitnessed-windows-sharing-error" : "terminal";
+  }
+}
 async function claimLockPath(lockPath, owner, waitMs, pollMs) {
   const started = owner.created_at_ms;
+  let unwitnessedWindowsRetryUsed = false;
   while (true) {
     try {
       await fs.mkdir(lockPath, { mode: 448 });
-      try {
-        await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
-`, {
-          encoding: "utf8",
-          flag: "wx",
-          mode: 384
-        });
-      } catch (err) {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
-        });
-        throw err;
+    } catch (err) {
+      const failure = await classifyLockClaimFailure(err, lockPath);
+      if (failure === "terminal") throw err;
+      if (failure === "unwitnessed-windows-sharing-error") {
+        if (unwitnessedWindowsRetryUsed) throw err;
+        unwitnessedWindowsRetryUsed = true;
+        continue;
+      } else {
+        unwitnessedWindowsRetryUsed = false;
       }
-      return async () => {
-        const current = await readOwner(lockPath);
-        if (current?.token !== owner.token) {
-          throw new FilesystemMutationLockError(
-            `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: current === null }
-          );
-        }
-        try {
-          await fs.rm(lockPath, { recursive: true, force: false });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          throw new FilesystemMutationLockError(
-            `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: false }
-          );
-        }
-      };
+      if (Date.now() - started >= waitMs) throw timeoutError(lockPath, await readOwner(lockPath), owner.target);
+      await delay(pollMs);
+      continue;
+    }
+    try {
+      await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
+`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 384
+      });
     } catch (err) {
-      if (err.code !== "EEXIST") throw err;
+      await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      throw err;
     }
-    if (Date.now() - started >= waitMs) throw timeoutError(lockPath, await readOwner(lockPath), owner.target);
-    await delay(pollMs);
+    return async () => {
+      const current = await readOwner(lockPath);
+      if (current?.token !== owner.token) {
+        throw new FilesystemMutationLockError(
+          `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: current === null }
+        );
+      }
+      try {
+        await fs.rm(lockPath, { recursive: true, force: false });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new FilesystemMutationLockError(
+          `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: false }
+        );
+      }
+    };
   }
 }
 function newOwner(target) {
@@ -5038,6 +5061,10 @@ var VALID_FIELDS_KEYS = /* @__PURE__ */ new Set([
   "descriptions"
 ]);
 var MISPLACED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["enum", "enums", "values", "constraints"]);
+var CLAIM_COORDINATE_KEYS = [
+  ["owner_field", "ownerField"],
+  ["state_field", "stateField"]
+];
 function parseConventionDoc(doc) {
   const fm = doc.frontmatter;
   const governs = typeof fm.governs === "string" ? fm.governs.trim() : "";
@@ -5346,6 +5373,35 @@ function parseConventionDoc(doc) {
       if (Object.keys(parsed).length > 0) expectsInbound = parsed;
     }
   }
+  const claimSource = fm.claim;
+  let claim;
+  if (claimSource !== void 0) {
+    if (!isPlainObject(claimSource)) {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has a non-map 'claim' key (${describeShape(claimSource)}; expected a map declaring 'owner_field' and/or 'state_field'); ignoring it.`,
+        field: "claim",
+        severity: "warning"
+      });
+    } else {
+      const parsed = {};
+      for (const [key, target] of CLAIM_COORDINATE_KEYS) {
+        const declared = claimSource[key];
+        if (declared === void 0) continue;
+        if (!isScalar(declared) || String(declared).trim() === "") {
+          warnings.push({
+            code: "KIND_CONVENTION_BAD_MEMBER",
+            message: `kind convention '${doc.id}' has a malformed 'claim.${key}' (${describeShape(declared)}; expected a declared field name); skipping it.`,
+            field: `claim.${key}`,
+            severity: "warning"
+          });
+          continue;
+        }
+        parsed[target] = String(declared).trim();
+      }
+      if (parsed.ownerField !== void 0 || parsed.stateField !== void 0) claim = parsed;
+    }
+  }
   const sections = Array.isArray(fm.sections) ? fm.sections.filter((s) => typeof s === "string" && s.trim() !== "") : void 0;
   const title = typeof fm.title === "string" && fm.title.trim() !== "" ? fm.title.trim() : governs;
   let description;
@@ -5378,6 +5434,7 @@ function parseConventionDoc(doc) {
   if (sections && sections.length > 0) kind.sections = sections;
   if (freshnessHorizon !== void 0) kind.freshnessHorizon = freshnessHorizon;
   if (browseCollapsed !== void 0) kind.browseCollapsed = browseCollapsed;
+  if (claim !== void 0) kind.claim = claim;
   return {
     ok: true,
     kind,

package/dist/publication.mjs

@@ -31901,46 +31901,69 @@ async function selectLockRoot(options2) {
   await ensurePrivateLockRoot(lockRoot);
   return lockRoot;
 }
+var WINDOWS_CLAIM_CONTENTION_CODES = /* @__PURE__ */ new Set(["EACCES", "EBUSY", "EPERM"]);
+async function classifyLockClaimFailure(error, lockPath) {
+  const code2 = error.code;
+  if (code2 === "EEXIST") return "contention";
+  if (process.platform !== "win32" || !WINDOWS_CLAIM_CONTENTION_CODES.has(code2 ?? "")) return "terminal";
+  try {
+    await fs.lstat(lockPath);
+    return "contention";
+  } catch (probeError) {
+    const probeCode = probeError.code;
+    return probeCode === "ENOENT" || probeCode === "ENOTDIR" ? "unwitnessed-windows-sharing-error" : "terminal";
+  }
+}
 async function claimLockPath(lockPath, owner, waitMs, pollMs) {
   const started = owner.created_at_ms;
+  let unwitnessedWindowsRetryUsed = false;
   while (true) {
     try {
       await fs.mkdir(lockPath, { mode: 448 });
-      try {
-        await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
+    } catch (err) {
+      const failure = await classifyLockClaimFailure(err, lockPath);
+      if (failure === "terminal") throw err;
+      if (failure === "unwitnessed-windows-sharing-error") {
+        if (unwitnessedWindowsRetryUsed) throw err;
+        unwitnessedWindowsRetryUsed = true;
+        continue;
+      } else {
+        unwitnessedWindowsRetryUsed = false;
+      }
+      if (Date.now() - started >= waitMs) throw timeoutError(lockPath, await readOwner(lockPath), owner.target);
+      await delay(pollMs);
+      continue;
+    }
+    try {
+      await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
 `, {
-          encoding: "utf8",
-          flag: "wx",
-          mode: 384
-        });
-      } catch (err) {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
-        });
-        throw err;
-      }
-      return async () => {
-        const current = await readOwner(lockPath);
-        if (current?.token !== owner.token) {
-          throw new FilesystemMutationLockError(
-            `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: current === null }
-          );
-        }
-        try {
-          await fs.rm(lockPath, { recursive: true, force: false });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          throw new FilesystemMutationLockError(
-            `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
-            { lockPath, owner: current, stale: false, malformed: false }
-          );
-        }
-      };
+        encoding: "utf8",
+        flag: "wx",
+        mode: 384
+      });
     } catch (err) {
-      if (err.code !== "EEXIST") throw err;
+      await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      throw err;
     }
-    if (Date.now() - started >= waitMs) throw timeoutError(lockPath, await readOwner(lockPath), owner.target);
-    await delay(pollMs);
+    return async () => {
+      const current = await readOwner(lockPath);
+      if (current?.token !== owner.token) {
+        throw new FilesystemMutationLockError(
+          `refusing to release filesystem mutation lock '${lockPath}' because its owner token changed; the mutation may have completed, inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: current === null }
+        );
+      }
+      try {
+        await fs.rm(lockPath, { recursive: true, force: false });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new FilesystemMutationLockError(
+          `mutation completed but filesystem lock '${lockPath}' could not be removed (${message}); inspect the lock before retrying.`,
+          { lockPath, owner: current, stale: false, malformed: false }
+        );
+      }
+    };
   }
 }
 function newOwner(target) {
@@ -33027,6 +33050,10 @@ var VALID_FIELDS_KEYS = /* @__PURE__ */ new Set([
   "descriptions"
 ]);
 var MISPLACED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set(["enum", "enums", "values", "constraints"]);
+var CLAIM_COORDINATE_KEYS = [
+  ["owner_field", "ownerField"],
+  ["state_field", "stateField"]
+];
 function parseConventionDoc(doc) {
   const fm = doc.frontmatter;
   const governs = typeof fm.governs === "string" ? fm.governs.trim() : "";
@@ -33335,6 +33362,35 @@ function parseConventionDoc(doc) {
       if (Object.keys(parsed).length > 0) expectsInbound = parsed;
     }
   }
+  const claimSource = fm.claim;
+  let claim;
+  if (claimSource !== void 0) {
+    if (!isPlainObject(claimSource)) {
+      warnings.push({
+        code: "KIND_CONVENTION_BAD_SHAPE",
+        message: `kind convention '${doc.id}' has a non-map 'claim' key (${describeShape(claimSource)}; expected a map declaring 'owner_field' and/or 'state_field'); ignoring it.`,
+        field: "claim",
+        severity: "warning"
+      });
+    } else {
+      const parsed = {};
+      for (const [key, target] of CLAIM_COORDINATE_KEYS) {
+        const declared = claimSource[key];
+        if (declared === void 0) continue;
+        if (!isScalar(declared) || String(declared).trim() === "") {
+          warnings.push({
+            code: "KIND_CONVENTION_BAD_MEMBER",
+            message: `kind convention '${doc.id}' has a malformed 'claim.${key}' (${describeShape(declared)}; expected a declared field name); skipping it.`,
+            field: `claim.${key}`,
+            severity: "warning"
+          });
+          continue;
+        }
+        parsed[target] = String(declared).trim();
+      }
+      if (parsed.ownerField !== void 0 || parsed.stateField !== void 0) claim = parsed;
+    }
+  }
   const sections = Array.isArray(fm.sections) ? fm.sections.filter((s) => typeof s === "string" && s.trim() !== "") : void 0;
   const title = typeof fm.title === "string" && fm.title.trim() !== "" ? fm.title.trim() : governs;
   let description;
@@ -33367,6 +33423,7 @@ function parseConventionDoc(doc) {
   if (sections && sections.length > 0) kind.sections = sections;
   if (freshnessHorizon !== void 0) kind.freshnessHorizon = freshnessHorizon;
   if (browseCollapsed !== void 0) kind.browseCollapsed = browseCollapsed;
+  if (claim !== void 0) kind.claim = claim;
   return {
     ok: true,
     kind,
@@ -43191,18 +43248,37 @@ async function authorizePublicationRoot(requested) {
 }
 async function assertPublicationRoot(identity) {
   let entry;
+  try {
+    entry = await lstat(identity.requested);
+  } catch (error) {
+    const code2 = error.code;
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") {
+      throw new PublicationError("SOURCE_CHANGED", "the publication source identity became unavailable during capture", { retryable: true, cause: error });
+    }
+    throw new PublicationError("IO_ERROR", "the publication source identity could not be read during capture", { cause: error });
+  }
+  if (entry.isSymbolicLink() || !entry.isDirectory()) {
+    throw new PublicationError("SOURCE_CHANGED", "the publication source root changed during capture", {
+      retryable: true,
+      expected: { canonical: identity.canonical, dev: identity.dev, ino: identity.ino },
+      actual: { symlink: entry.isSymbolicLink(), directory: entry.isDirectory() }
+    });
+  }
   let canonical2;
   let current;
   try {
-    [entry, canonical2, current] = await Promise.all([
-      lstat(identity.requested),
+    [canonical2, current] = await Promise.all([
       realpath(identity.requested),
       stat(identity.requested)
     ]);
   } catch (error) {
-    throw new PublicationError("SOURCE_CHANGED", "the publication source identity became unavailable during capture", { retryable: true, cause: error });
+    const code2 = error.code;
+    if (code2 === "ENOENT" || code2 === "ENOTDIR") {
+      throw new PublicationError("SOURCE_CHANGED", "the publication source identity became unavailable during capture", { retryable: true, cause: error });
+    }
+    throw new PublicationError("IO_ERROR", "the publication source identity could not be read during capture", { cause: error });
   }
-  if (entry.isSymbolicLink() || !entry.isDirectory() || !current.isDirectory() || canonical2 !== identity.canonical || current.dev !== identity.dev || current.ino !== identity.ino) {
+  if (!current.isDirectory() || canonical2 !== identity.canonical || current.dev !== identity.dev || current.ino !== identity.ino) {
     throw new PublicationError("SOURCE_CHANGED", "the publication source root changed during capture", {
       retryable: true,
       expected: { canonical: identity.canonical, dev: identity.dev, ino: identity.ino },
@@ -43378,6 +43454,16 @@ function mapCaptureError(error) {
   }
   return new PublicationError("INVALID_BUNDLE", error instanceof Error ? error.message : "the bundle is invalid", { cause: error });
 }
+async function classifyCaptureError(error, rootIdentity) {
+  const mapped = mapCaptureError(error);
+  if (mapped.code !== "IO_ERROR") return mapped;
+  try {
+    await assertPublicationRoot(rootIdentity);
+  } catch (rootError) {
+    if (rootError instanceof PublicationError && rootError.code === "SOURCE_CHANGED") return rootError;
+  }
+  return mapped;
+}
 function addObject(objects, bytes, mediaType, representation) {
   const digest2 = sha256(bytes);
   if (!objects.has(digest2)) objects.set(digest2, bytes.slice());
@@ -43577,7 +43663,7 @@ async function capturePublicationSnapshot(options2) {
       }
       return handle;
     } catch (error) {
-      lastError = mapCaptureError(error);
+      lastError = await classifyCaptureError(error, rootIdentity);
       if (!lastError.retryable || attempt === maxAttempts) throw lastError;
     }
   }