superbee 0.3.0-pre.2 → 0.3.0-pre.5

package/README.md

@@ -37,6 +37,11 @@ and write through a small command-line tool.
   needs a network. The document schemas, called kinds, live inside the bundle, so it describes
   its own structure.
 
+Bees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows
+the next bee where to build and what belongs where. Superbee works the same way: people and
+agents record what they learn in a structure that fits their domain, and that structure guides
+whoever works next. Each session builds on the last instead of starting over.
+
 The npm package is one self-contained executable with zero runtime dependencies, plus an Agent
 Skill, an instruction file your agent loads, that teaches it how to use the tool.
 

package/SKILL.md

@@ -88,8 +88,12 @@ When the tone fits, a single 🐝 may mark a successful Superbee outcome.
 
 ## Hosted checkouts
 
-- In a folder made by `superbee checkout` the host is the authority. On `AUTH_REQUIRED` (exit 4), relay `details.sign_in_url` to the person, then re-run the same command; `superbee setup hosted` signs in and picks the default workspace in one step.
-- Run `superbee sync` once at the end of a batch of edits. Any concurrent change to one document, even to different frontmatter keys, is a conflict: read `$REFS/hosted-checkout.md`, then `sync --inspect --doc <id>` and `--resolve keep|take|revise --doc <id>`. `--resolve` records a decision and never sends: run `superbee sync` after keep or revise. Deleted files sync as deletes; when sync reports `deletions_held`, never accept it yourself: name the documents and ask the person to run its `--accept-deletes` command in their own terminal (it asks them to type the count, and refuses your shell), else run `--restore-deletes`. A refusal that says to do something in the Superbee app is for the person: tell them, and never work around it.
+- In a folder made by `superbee checkout` the host is the authority. On `AUTH_REQUIRED` (exit 4), relay `details.sign_in_url` to the person, then re-run the same command; `superbee setup hosted` signs in and picks the default workspace in one step, and `superbee catalog list --hosted` lists the bundle ids you can check out. A folder reported with `copy_of_checkout` was moved, copied or restored and is not bound: read `$REFS/hosted-checkout.md` before `superbee checkout --adopt`, and let the person confirm the host. `superbee publish --to hosted` moves a local bundle or Git board to hosted: preview it, and add `--yes` only when the person asks.
+- Run `superbee sync` once at the end of a batch of edits; resolve conflicts as below. Deleted files sync as deletes; when sync reports `deletions_held`, never accept it yourself: name the documents and ask the person to run its `--accept-deletes` command in their own terminal (it asks them to type the count, and refuses your shell), else run `--restore-deletes`. A refusal that says to do something in the Superbee app is for the person: tell them, and never work around it. Take a bundle out of hosted only when the person asks: `superbee export` (read `$REFS/hosted-checkout.md` first).
+
+## Sync conflicts
+
+- A Git board and a hosted checkout share one playbook. When `superbee sync` exits 5 with conflict rows, run `superbee sync --inspect --doc <id>` to see your version and theirs, then `superbee sync --resolve keep|take|revise --doc <id>`: keep writes yours over theirs, take keeps theirs, revise keeps the document as you edited it to the merged result. `--resolve` never sends: run `superbee sync` after keep or revise. A Git board has already kept the teammate's version and saved yours aside; a hosted checkout keeps your file, treats any concurrent change to one document (even different frontmatter keys) as a conflict, and is explained in `$REFS/hosted-checkout.md`.
 
 ## Host setup
 

package/dist/publication-bridge.mjs

@@ -3575,6 +3575,12 @@ function processExists(pid) {
     return err.code !== "ESRCH";
   }
 }
+var HELD_TOKENS = Symbol.for("superbee.filesystem-lock.held-tokens");
+var heldTokens = globalThis[HELD_TOKENS] ??= /* @__PURE__ */ new Set();
+function ownerIsGone(owner) {
+  if (owner.pid !== process.pid) return !processExists(owner.pid);
+  return !heldTokens.has(owner.token) && owner.created_at_ms < Date.now() - process.uptime() * 1e3;
+}
 function staleLockQuarantinePath(lockPath, owner) {
   const tokenHash = createHash("sha256").update(owner.token).digest("hex");
   return `${lockPath}.stale-${tokenHash}`;
@@ -3589,7 +3595,9 @@ async function pathExists(candidate) {
   }
 }
 async function quarantineStaleLock(lockPath, owner, policy) {
-  if (owner.hostname !== hostname() || processExists(owner.pid)) return false;
+  if (owner.hostname !== hostname() || !ownerIsGone(owner)) return false;
+  const current = await readOwner(lockPath);
+  if (current === null || current.token !== owner.token) return false;
   const quarantinePath = staleLockQuarantinePath(lockPath, owner);
   try {
     await fs.rename(lockPath, quarantinePath);
@@ -3639,17 +3647,26 @@ async function ensurePrivateLockRoot(root, policy) {
     );
   }
 }
-function timeoutError(lockPath, owner, guarded) {
+async function timeoutError(lockPath, snapshot, guarded) {
+  let diagnosed = snapshot;
+  let stale = false;
+  if (snapshot !== null && snapshot.hostname === hostname() && ownerIsGone(snapshot)) {
+    const current = await readOwner(lockPath);
+    if (current?.token === snapshot.token) stale = true;
+    else diagnosed = current;
+  }
+  const owner = diagnosed;
   const malformed = owner === null;
   const sameHost = owner?.hostname === hostname();
-  const stale = owner !== null && sameHost && !processExists(owner.pid);
   let message;
   if (malformed) {
     message = `timed out waiting for filesystem mutation lock '${lockPath}'; its owner metadata is missing or malformed. Inspect and remove the lock only after confirming no process is mutating the target, then retry.`;
   } else if (stale) {
     message = `stale filesystem mutation lock '${lockPath}' belongs to absent PID ${owner.pid} on ${owner.hostname}. Inspect and remove the lock, then retry.`;
+  } else if (!sameHost) {
+    message = `filesystem mutation lock '${lockPath}' is held by PID ${owner.pid} on ${owner.hostname}, which is not this host (${hostname()}); whether its holder is alive cannot be checked from here, so the lock is never reclaimed automatically. A person must check it: once no process on ${owner.hostname} is mutating the target (this host may have been renamed since the lock was taken), remove the lock, then retry.`;
   } else {
-    message = `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation.`;
+    message = `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation. If it stays held, PID ${owner.pid} may no longer be the process that claimed it, because a process id is reused after its process exits: remove the lock only after confirming no process is mutating the target.`;
   }
   const heldFor = owner !== null && owner.target !== guarded ? ` Its holder recorded '${owner.target}' for the same lock key.` : "";
   return new FilesystemMutationLockError(`${message} The lock guards '${guarded}'.${heldFor}`, { lockPath, owner, stale, malformed });
@@ -3697,11 +3714,12 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
         if (await quarantineStaleLock(lockPath, existingOwner, policy)) continue;
         existingOwner = await readOwner(lockPath);
       }
-      if (Date.now() - started >= waitMs) throw timeoutError(lockPath, existingOwner, owner.target);
+      if (Date.now() - started >= waitMs) throw await timeoutError(lockPath, existingOwner, owner.target);
       await delay(pollMs);
       continue;
     }
     const claimed = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
+    heldTokens.add(owner.token);
     try {
       await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
 `, {
@@ -3711,9 +3729,13 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
       });
     } catch (err) {
       const code = err.code;
-      if (code === "EEXIST") continue;
+      if (code === "EEXIST") {
+        heldTokens.delete(owner.token);
+        continue;
+      }
       await rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy).catch(() => {
       });
+      heldTokens.delete(owner.token);
       if (code === "ENOENT" || code === "ENOTDIR") continue;
       throw err;
     }
@@ -3728,6 +3750,7 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
           throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
         }
         await removeReleasedLock(lockPath, owner, started2, waitMs, pollMs, policy);
+        heldTokens.delete(owner.token);
       })();
       return inFlight.finally(() => {
         inFlight = void 0;

package/dist/publication.mjs

@@ -31529,6 +31529,12 @@ function processExists(pid) {
     return err.code !== "ESRCH";
   }
 }
+var HELD_TOKENS = Symbol.for("superbee.filesystem-lock.held-tokens");
+var heldTokens = globalThis[HELD_TOKENS] ??= /* @__PURE__ */ new Set();
+function ownerIsGone(owner) {
+  if (owner.pid !== process.pid) return !processExists(owner.pid);
+  return !heldTokens.has(owner.token) && owner.created_at_ms < Date.now() - process.uptime() * 1e3;
+}
 function staleLockQuarantinePath(lockPath, owner) {
   const tokenHash = createHash("sha256").update(owner.token).digest("hex");
   return `${lockPath}.stale-${tokenHash}`;
@@ -31543,7 +31549,9 @@ async function pathExists(candidate) {
   }
 }
 async function quarantineStaleLock(lockPath, owner, policy) {
-  if (owner.hostname !== hostname() || processExists(owner.pid)) return false;
+  if (owner.hostname !== hostname() || !ownerIsGone(owner)) return false;
+  const current = await readOwner(lockPath);
+  if (current === null || current.token !== owner.token) return false;
   const quarantinePath = staleLockQuarantinePath(lockPath, owner);
   try {
     await fs.rename(lockPath, quarantinePath);
@@ -31593,17 +31601,26 @@ async function ensurePrivateLockRoot(root, policy) {
     );
   }
 }
-function timeoutError(lockPath, owner, guarded) {
+async function timeoutError(lockPath, snapshot, guarded) {
+  let diagnosed = snapshot;
+  let stale = false;
+  if (snapshot !== null && snapshot.hostname === hostname() && ownerIsGone(snapshot)) {
+    const current = await readOwner(lockPath);
+    if (current?.token === snapshot.token) stale = true;
+    else diagnosed = current;
+  }
+  const owner = diagnosed;
   const malformed = owner === null;
   const sameHost = owner?.hostname === hostname();
-  const stale = owner !== null && sameHost && !processExists(owner.pid);
   let message;
   if (malformed) {
     message = `timed out waiting for filesystem mutation lock '${lockPath}'; its owner metadata is missing or malformed. Inspect and remove the lock only after confirming no process is mutating the target, then retry.`;
   } else if (stale) {
     message = `stale filesystem mutation lock '${lockPath}' belongs to absent PID ${owner.pid} on ${owner.hostname}. Inspect and remove the lock, then retry.`;
+  } else if (!sameHost) {
+    message = `filesystem mutation lock '${lockPath}' is held by PID ${owner.pid} on ${owner.hostname}, which is not this host (${hostname()}); whether its holder is alive cannot be checked from here, so the lock is never reclaimed automatically. A person must check it: once no process on ${owner.hostname} is mutating the target (this host may have been renamed since the lock was taken), remove the lock, then retry.`;
   } else {
-    message = `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation.`;
+    message = `timed out waiting for filesystem mutation lock '${lockPath}' held by PID ${owner.pid} on ${owner.hostname}; retry the mutation. If it stays held, PID ${owner.pid} may no longer be the process that claimed it, because a process id is reused after its process exits: remove the lock only after confirming no process is mutating the target.`;
   }
   const heldFor = owner !== null && owner.target !== guarded ? ` Its holder recorded '${owner.target}' for the same lock key.` : "";
   return new FilesystemMutationLockError(`${message} The lock guards '${guarded}'.${heldFor}`, { lockPath, owner, stale, malformed });
@@ -31651,11 +31668,12 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
         if (await quarantineStaleLock(lockPath, existingOwner, policy)) continue;
         existingOwner = await readOwner(lockPath);
       }
-      if (Date.now() - started >= waitMs) throw timeoutError(lockPath, existingOwner, owner.target);
+      if (Date.now() - started >= waitMs) throw await timeoutError(lockPath, existingOwner, owner.target);
       await delay(pollMs);
       continue;
     }
     const claimed = await fs.lstat(lockPath, { bigint: true }).catch(() => null);
+    heldTokens.add(owner.token);
     try {
       await fs.writeFile(path.join(lockPath, OWNER_FILE), `${JSON.stringify(owner)}
 `, {
@@ -31665,9 +31683,13 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
       });
     } catch (err) {
       const code2 = err.code;
-      if (code2 === "EEXIST") continue;
+      if (code2 === "EEXIST") {
+        heldTokens.delete(owner.token);
+        continue;
+      }
       await rollBackOwnClaim(lockPath, owner, claimed, waitMs, pollMs, policy).catch(() => {
       });
+      heldTokens.delete(owner.token);
       if (code2 === "ENOENT" || code2 === "ENOTDIR") continue;
       throw err;
     }
@@ -31682,6 +31704,7 @@ async function claimLockPath(lockPath, owner, waitMs, pollMs, policy) {
           throw changedOwnerRefusal(lockPath, current.state === "record" ? current.owner : null);
         }
         await removeReleasedLock(lockPath, owner, started2, waitMs, pollMs, policy);
+        heldTokens.delete(owner.token);
       })();
       return inFlight.finally(() => {
         inFlight = void 0;