superbee 0.4.0-pre.3 → 0.4.0

package/README.md

@@ -53,11 +53,7 @@ Requires Node.js 20 or newer on macOS and Linux. Native Windows is not supported
 npm install -g superbee
 ```
 
-Stable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:
-
-```sh
-npm install -g superbee@next
-```
+Stable releases publish on npm's `latest` tag and prereleases on `next`.
 
 Windows adapters and the `superbee-windows` executable live in a separate repository and are
 not included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target2) => (target2 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.0-pre.3" }, source: { commit: "f7eb4a1599830a30ed00834895b9ac95d55bfd56", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.0" }, source: { commit: "b2911c7f26c60d6648ad2d53a1962259cb8b3a08", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -11645,41 +11645,6 @@ var init_src = __esm({
   }
 });
 
-// ../cli/src/filesystem-runtime.ts
-function cliFilesystemRuntime() {
-  const host = currentFilesystemHost();
-  if (!host) return defaultRuntime ??= createFilesystemRuntime();
-  let runtime = runtimes.get(host);
-  if (!runtime) {
-    runtime = createFilesystemRuntime(host);
-    runtimes.set(host, runtime);
-  }
-  return runtime;
-}
-function configuredBundle(root) {
-  return { root, backend: cliFilesystemRuntime().backend(root) };
-}
-function configuredInitBundle(root, options) {
-  return cliFilesystemRuntime().initBundle(root, options);
-}
-function withCliFilesystemMutationLock(target2, body, options) {
-  return cliFilesystemRuntime().withMutationLock(target2, body, options);
-}
-function isFilesystemBundle(bundle) {
-  return !bundle.backend || bundle.backend instanceof FilesystemBackend;
-}
-var runtimes, defaultRuntime;
-var init_filesystem_runtime = __esm({
-  "../cli/src/filesystem-runtime.ts"() {
-    "use strict";
-    init_define_SUPERBEE_BUILD_IDENTITY();
-    init_define_SUPERBEE_UPDATE_POLICY();
-    init_src();
-    init_runtime_context();
-    runtimes = /* @__PURE__ */ new WeakMap();
-  }
-});
-
 // ../board-git/src/errors.ts
 function isBoardGitError(v2) {
   if (typeof v2 !== "object" || v2 === null) return false;
@@ -14113,6 +14078,41 @@ var init_src2 = __esm({
   }
 });
 
+// ../cli/src/filesystem-runtime.ts
+function cliFilesystemRuntime() {
+  const host = currentFilesystemHost();
+  if (!host) return defaultRuntime ??= createFilesystemRuntime();
+  let runtime = runtimes.get(host);
+  if (!runtime) {
+    runtime = createFilesystemRuntime(host);
+    runtimes.set(host, runtime);
+  }
+  return runtime;
+}
+function configuredBundle(root) {
+  return { root, backend: cliFilesystemRuntime().backend(root) };
+}
+function configuredInitBundle(root, options) {
+  return cliFilesystemRuntime().initBundle(root, options);
+}
+function withCliFilesystemMutationLock(target2, body, options) {
+  return cliFilesystemRuntime().withMutationLock(target2, body, options);
+}
+function isFilesystemBundle(bundle) {
+  return !bundle.backend || bundle.backend instanceof FilesystemBackend;
+}
+var runtimes, defaultRuntime;
+var init_filesystem_runtime = __esm({
+  "../cli/src/filesystem-runtime.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_src();
+    init_runtime_context();
+    runtimes = /* @__PURE__ */ new WeakMap();
+  }
+});
+
 // ../cli/src/actor-guidance.ts
 function legacyEnvCleanup(env) {
   return env[LEGACY_ACTOR_VARIABLE] === void 0 ? "" : `; unset ${LEGACY_ACTOR_VARIABLE}`;
@@ -15317,7 +15317,7 @@ var init_env_policy = __esm({
 });
 
 // ../cli/src/bundle.ts
-import { constants as constants3, promises as fs3 } from "node:fs";
+import { closeSync as closeSync3, constants as constants3, fstatSync as fstatSync3, openSync as openSync3, promises as fs3, readSync } from "node:fs";
 import path14 from "node:path";
 async function exists(p2) {
   try {
@@ -15327,6 +15327,21 @@ async function exists(p2) {
     return false;
   }
 }
+function looksLikeBundle(dir) {
+  let fd;
+  try {
+    fd = openSync3(path14.join(dir, "index.md"), constants3.O_RDONLY | (constants3.O_NOFOLLOW ?? 0) | (constants3.O_NONBLOCK ?? 0));
+    if (!fstatSync3(fd).isFile()) return false;
+    const buffer = Buffer.alloc(16 * 1024);
+    const text4 = buffer.subarray(0, readSync(fd, buffer, 0, buffer.length, 0)).toString("utf8");
+    const block = /^---\r?\n([\s\S]*?)\r?\n---\r?(?:\n|$)/.exec(text4);
+    return block !== null && /^okf_version\s*:/m.test(block[1]);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== void 0) closeSync3(fd);
+  }
+}
 function resolveTargetDir(dirFlag) {
   return path14.resolve(dirFlag ?? process.cwd());
 }
@@ -16551,7 +16566,7 @@ async function openBundle(dirFlag, remoteFlag) {
   await assertResolvedLocalRouteIdentity(route);
   return route.bundle;
 }
-var CONVENTIONAL_BUNDLE_DIR_NAME, LEGACY_CONVENTIONAL_BUNDLE_DIR_NAME, SUPERBEE_PROJECT_BINDING_FILE_NAME, PROJECT_BINDING_FILE_NAME, PROJECT_BINDING_FILE_NAMES, HOSTED_PROBE_STATUSES, HOSTED_PROBE_PATH, HOSTED_PROBE_TIMEOUT_MS, API_KEY_ENV_VAR, SUPERBEE_API_KEY_ENV_VAR, REMOTE_ENV_VAR, createOnlyFs;
+var TOP_LEVEL_BUNDLE_MOVE, CONVENTIONAL_BUNDLE_DIR_NAME, LEGACY_CONVENTIONAL_BUNDLE_DIR_NAME, SUPERBEE_PROJECT_BINDING_FILE_NAME, PROJECT_BINDING_FILE_NAME, PROJECT_BINDING_FILE_NAMES, HOSTED_PROBE_STATUSES, HOSTED_PROBE_PATH, HOSTED_PROBE_TIMEOUT_MS, API_KEY_ENV_VAR, SUPERBEE_API_KEY_ENV_VAR, REMOTE_ENV_VAR, createOnlyFs;
 var init_bundle2 = __esm({
   "../cli/src/bundle.ts"() {
     "use strict";
@@ -16571,6 +16586,7 @@ var init_bundle2 = __esm({
     init_bound_board_owner();
     init_env_policy();
     init_command_text();
+    TOP_LEVEL_BUNDLE_MOVE = `move the bundle at the work tree's top into ${BUNDLE_DIR}/ (index.md, conventions/ and its document folders; \`git mv\` if they are committed, \`mv\` if not)`;
     CONVENTIONAL_BUNDLE_DIR_NAME = BUNDLE_DIR;
     LEGACY_CONVENTIONAL_BUNDLE_DIR_NAME = LEGACY_BUNDLE_DIR;
     SUPERBEE_PROJECT_BINDING_FILE_NAME = ".superbee.json";
@@ -18702,15 +18718,30 @@ var init_recipe_source = __esm({
 import { parseArgs } from "node:util";
 import { existsSync as existsSync5 } from "node:fs";
 import path17 from "node:path";
-function insideGitRepo(dir) {
+function gitWorkTreeTop(dir) {
   let cur = path17.resolve(dir);
+  let found = null;
   for (; ; ) {
-    if (existsSync5(path17.join(cur, ".git"))) return true;
+    if (existsSync5(path17.join(cur, ".git"))) {
+      if (!BUNDLE_DIRS.includes(path17.basename(cur))) return cur;
+      found ??= cur;
+    }
     const parent = path17.dirname(cur);
-    if (parent === cur) return false;
+    if (parent === cur) return found;
     cur = parent;
   }
 }
+function plainInitDir(cwd) {
+  const top = gitWorkTreeTop(cwd);
+  if (top === null) return void 0;
+  for (let dir = path17.resolve(cwd); ; dir = path17.dirname(dir)) {
+    if (existsSync5(path17.join(dir, "index.md"))) return dir;
+    const conventional = BUNDLE_DIRS.find((name) => existsSync5(path17.join(dir, name, "index.md")));
+    if (conventional) return path17.join(dir, conventional);
+    if (dir === top || path17.dirname(dir) === dir) break;
+  }
+  return path17.join(top, BUNDLE_DIR);
+}
 async function init(argv2, deps = {}) {
   const stdout = deps.stdout ?? ((s) => void process.stdout.write(s));
   const { values } = parseLeafOrUsage(
@@ -18770,7 +18801,7 @@ async function init(argv2, deps = {}) {
   );
   let root;
   let bundle;
-  const initDir = boundRoute?.kind === "bound-local" ? boundRoute.bundle.root : values.dir;
+  const initDir = boundRoute?.kind === "bound-local" ? boundRoute.bundle.root : values.dir ?? (boundRoute ? void 0 : plainInitDir(process.cwd()));
   if (createOnly) {
     if (boundRoute) await assertResolvedLocalRouteIdentity(boundRoute);
     const result3 = await withCreateOnlyTarget(
@@ -18803,8 +18834,11 @@ async function init(argv2, deps = {}) {
   }
   const receipt2 = { init: "ok", root: bundle.root, recipe: recipeApplied };
   if (warnings.length > 0) receipt2.warnings = warnings;
-  if (insideGitRepo(root)) {
-    receipt2.hint = `this bundle is local until shared \u2014 if the project already shares a board, \`${cliInvocation()} sync\` joins it (never init there, that mints a divergent second bundle); to start sharing this one, \`${cliInvocation()} sync --establish\``;
+  const top = gitWorkTreeTop(root);
+  if (top !== null) {
+    const joinFirst = `this bundle is local until shared \u2014 if the project already shares a board, \`${cliInvocation()} sync\` joins it (never init there, that mints a divergent second bundle); `;
+    const conventional = path17.dirname(root) === top && BUNDLE_DIRS.includes(path17.basename(root));
+    receipt2.hint = !conventional ? path17.resolve(root) === path17.resolve(top) ? `${joinFirst}${TOP_LEVEL_BUNDLE_MOVE}, then \`${cliInvocation()} sync --establish\`` : `${joinFirst}only the work tree's ${BUNDLE_DIR}/ folder can be shared, and this bundle is not it (\`${cliInvocation()} init --dir ${commandQuoted(path17.join(top, BUNDLE_DIR))}\` makes that one)` : existsSync5(path17.join(root, ".git")) ? `this is the project's shared board; \`${cliInvocation()} sync\` keeps it current` : `${joinFirst}to start sharing this one, \`${cliInvocation()} sync --establish\``;
   }
   const target2 = values.dir === void 0 ? commandLiteral("") : commandFragment` --dir ${commandQuoted(root)}`;
   const help2 = [];
@@ -18825,6 +18859,7 @@ var init_init = __esm({
     init_define_SUPERBEE_UPDATE_POLICY();
     init_output2();
     init_src();
+    init_src2();
     init_filesystem_runtime();
     init_bundle2();
     init_errors4();
@@ -18841,7 +18876,9 @@ Usage:
   superbee init [--dir <path>] [--okf-version <v>] [--recipe <name-or-path>] [--create-only]
 
 Options:
-  --dir <path>            Directory to init the bundle in (default: the current directory)
+  --dir <path>            Directory to init the bundle in (default: the current directory; inside
+                           a Git work tree, its top-level .superbee/ folder, which
+                           'sync --establish' shares, unless the current directory is a bundle)
   --okf-version <v>       Compatibility override for legacy integrations (normally omit; use 0.1
                            only when a legacy consumer requires it). Other versions remain readable
                            but are not authorable
@@ -18863,10 +18900,10 @@ Options:
 });
 
 // ../cli/src/commands/doc/common.ts
-import { fstatSync as fstatSync3 } from "node:fs";
+import { fstatSync as fstatSync4 } from "node:fs";
 function hasRealStdinInput() {
   try {
-    const stats = fstatSync3(0);
+    const stats = fstatSync4(0);
     if (stats.isFIFO() || stats.isFile() || stats.isSocket()) return true;
     return currentHost().hasAdditionalStdinInput(stats);
   } catch {
@@ -19136,9 +19173,11 @@ Options:
   --offset <n>         Page the record's body: 'body' is the page starting at character n (a
                        JavaScript string index, 0 for the first page) and 'range' says where it sits:
                        offset, end, total_chars, total_bytes, complete, and next_offset while more
-                       follows. A page ends within --max-bytes of UTF-8, never splits a character,
-                       and ends just after a line where one is near its end. A page is NOT the
-                       document: never write it back as the body.
+                       follows. The page without next_offset is the last; complete is true only
+                       when the whole body fit in one page, so page on next_offset. A page ends
+                       within --max-bytes of UTF-8, never splits a character, and ends just after a
+                       line where one is near its end. A page is NOT the document: never write it
+                       back as the body.
   --max-bytes <n>      The page's body bound in UTF-8 bytes, 1024 to 983040 (default 32768). Implies
                        --offset 0 when --offset is absent.
   --expected-version <v>
@@ -20862,7 +20901,7 @@ var init_binding = __esm({
 });
 
 // ../cli/src/nofollow-read.ts
-import { closeSync as closeSync3, constants as constants5, fstatSync as fstatSync4, lstatSync as lstatSync4, openSync as openSync3, readFileSync as readFileSync8 } from "node:fs";
+import { closeSync as closeSync4, constants as constants5, fstatSync as fstatSync5, lstatSync as lstatSync4, openSync as openSync4, readFileSync as readFileSync8 } from "node:fs";
 function leafIdentity(filePath) {
   try {
     const leaf = lstatSync4(filePath);
@@ -20885,19 +20924,19 @@ function readLeafSync(filePath, flags, hasNoFollow) {
   }
   let descriptor;
   try {
-    descriptor = openSync3(filePath, flags);
+    descriptor = openSync4(filePath, flags);
   } catch (error51) {
     return error51.code === "ENOENT" ? { state: "missing" } : { state: "unsafe" };
   }
   try {
-    const opened = fstatSync4(descriptor);
+    const opened = fstatSync5(descriptor);
     if (!opened.isFile()) return { state: "unsafe" };
     if (expected && (opened.dev !== expected.dev || opened.ino !== expected.ino)) return { state: "unsafe" };
     return { state: "present", bytes: readFileSync8(descriptor) };
   } catch {
     return { state: "unsafe" };
   } finally {
-    closeSync3(descriptor);
+    closeSync4(descriptor);
   }
 }
 function readRegularFileTextNoFollowSync(filePath) {
@@ -22118,7 +22157,7 @@ async function hostedWriteHost(flag, home2, retry) {
   if (candidates.size > 1) {
     const hosts = [...candidates].sort();
     const signedOut = hosts.filter((host) => !stored.includes(host));
-    throw new CliError("USAGE", `more than one hosted Superbee host could be meant (${hosts.join(", ")}); name the one this write is for with --host`, {
+    throw new CliError("USAGE", `more than one hosted Superbee host could be meant (${hosts.join(", ")}); name the one this command is for with --host`, {
       details: {
         reason: "ambiguous_host",
         hosts,
@@ -25875,6 +25914,9 @@ function bundleOf(target2) {
 function baseKey(id) {
   return `base:${id}`;
 }
+function holdsVersion(base, version3) {
+  return base !== void 0 && base.version === version3 && base.refetch !== true;
+}
 function baseRow(id, base) {
   return { key: baseKey(id), value: base };
 }
@@ -26584,7 +26626,7 @@ async function settleIntent(local, requestId2, outcome, attempts, options = {})
         requestId2,
         "in_flight",
         { state: "acknowledged", attempts, acknowledgedVersion: outcome.version, ...finding ? { finding } : {} },
-        { meta: [baseRow(current.target, { version: outcome.version, content: current.content }), acknowledged] }
+        { meta: [baseRow(current.target, { version: outcome.version, content: current.content, ...finding ? { refetch: true } : {} }), acknowledged] }
       );
     }
     case "conflict": {
@@ -26895,7 +26937,7 @@ async function pull(local, remote, options = {}) {
       return;
     }
     const base = fenced ? fenced.base : await backend.readMeta(baseKey(id));
-    if (base?.version === head.version) {
+    if (holdsVersion(base, head.version)) {
       report.unchanged.push(id);
       return;
     }
@@ -26972,7 +27014,7 @@ async function pull(local, remote, options = {}) {
       continue;
     }
     const base = await backend.readMeta(baseKey(head.id));
-    if (base?.version === head.version) report.unchanged.push(head.id);
+    if (holdsVersion(base, head.version)) report.unchanged.push(head.id);
     else {
       candidates.push(head.id);
       versions.set(head.id, head.version);
@@ -33855,6 +33897,13 @@ function establishNextSteps(inv) {
 function assertPlainBundleShape(bundlePath, inv) {
   const bundleDir = path31.basename(bundlePath);
   const runInitHelp = `${inv} init --create-only --dir ${commandToken(BUNDLE_DIR)}`;
+  if (bundleDir === BUNDLE_DIR && !existsSync9(path31.join(bundlePath, "index.md")) && looksLikeBundle(path31.dirname(bundlePath))) {
+    throw new CliError(
+      "RUNTIME",
+      `this repository's top folder is itself a bundle, and establish shares only a '${bundleDir}/' folder \u2014 ${TOP_LEVEL_BUNDLE_MOVE}, then re-run establish`,
+      { help: `mkdir -p ${bundleDir} && git mv index.md ${bundleDir}/ (plain mv if never committed), then the same for conventions/ if present and each document folder, then ${inv} sync --establish` }
+    );
+  }
   if (!existsSync9(bundlePath)) {
     throw new CliError(
       "RUNTIME",
@@ -35774,6 +35823,25 @@ function intentFrontmatter(row4, okfVersion) {
     return null;
   }
 }
+async function hostRestamped(store, acknowledged, folder, projection) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const id of acknowledged.keys()) {
+    const base = await store.readMeta(baseKey(id));
+    if (base?.refetch !== true) continue;
+    const bytes = await fs13.readFile(path34.join(folder, `${id}.md`)).catch(() => null);
+    const entry = projection.files[id];
+    if (bytes !== null && entry !== void 0 && !entry.deleted && digestOf(bytes) === entry.digest) ids.add(id);
+    else {
+      const { refetch: _refetch, ...kept } = base;
+      try {
+        await store.writeMeta(baseKey(id), kept, { expected: { present: true, value: base } });
+      } catch (error51) {
+        if (!(error51 instanceof JournalGuardConflict)) throw error51;
+      }
+    }
+  }
+  return ids;
+}
 function recordLanded(landed, row4, okfVersion) {
   const frontmatter = intentFrontmatter(row4, okfVersion);
   if (isConventionId(row4.target)) {
@@ -36037,7 +36105,8 @@ async function runSync(binding, values, deps, mode) {
       throw await readFailure(error51, session, resumeCommand, await unsent());
     }
     const hold = await recordHostHold(store, heldSink.value, scan3.hold);
-    const second = first.report.held.some((id) => outcome.acknowledged.has(id)) ? await pullAndExport() : null;
+    const restamped = await hostRestamped(store, outcome.acknowledged, binding.path, projection);
+    const second = first.report.held.some((id) => outcome.acknowledged.has(id)) || restamped.size > 0 ? await pullAndExport() : null;
     const pulled = second?.report ?? first.report;
     let root;
     try {
@@ -36046,7 +36115,14 @@ async function runSync(binding, values, deps, mode) {
       throw await readFailure(error51, session, resumeCommand, await unsent());
     }
     const exported = {
-      placed: [...first.placed.placed, ...second?.placed.placed ?? [], ...root.refreshed ? [ROOT_INDEX] : []],
+      // A document this run sent and only took back with the host's stamps is not one received
+      // (accepted: a change by someone else in the same instant is not counted either, and after
+      // a crash between the acknowledgement and this pull, the next run counts it once).
+      placed: [
+        ...first.placed.placed,
+        ...(second?.placed.placed ?? []).filter((id) => !restamped.has(id)),
+        ...root.refreshed ? [ROOT_INDEX] : []
+      ],
       removed: [...first.placed.removed, ...second?.placed.removed ?? []],
       kept: second?.placed.kept ?? first.placed.kept,
       held: second?.placed.held ?? first.placed.held
@@ -125428,15 +125504,15 @@ __export(update_orientation_exports, {
 });
 import { randomBytes as randomBytes7 } from "node:crypto";
 import {
-  closeSync as closeSync4,
+  closeSync as closeSync5,
   constants as constants7,
   fchmodSync as fchmodSync2,
-  fstatSync as fstatSync5,
+  fstatSync as fstatSync6,
   fsyncSync as fsyncSync2,
   linkSync as linkSync3,
   lstatSync as lstatSync9,
-  openSync as openSync4,
-  readSync,
+  openSync as openSync5,
+  readSync as readSync2,
   renameSync as renameSync7,
   unlinkSync as unlinkSync3,
   writeFileSync as writeFileSync5
@@ -125607,17 +125683,17 @@ function inspectStateDirectory(home2) {
   const flags = constants7.O_RDONLY | constants7.O_DIRECTORY | (constants7.O_NOFOLLOW ?? 0);
   let descriptor;
   try {
-    descriptor = openSync4(directory, flags);
+    descriptor = openSync5(directory, flags);
   } catch (error51) {
     return errno2(error51) === "ENOENT" ? "missing" : "unsafe";
   }
   try {
-    const stats = fstatSync5(descriptor);
+    const stats = fstatSync6(descriptor);
     return stats.isDirectory() && privateOwnerAndMode(home2, stats, 448) ? "safe" : "unsafe";
   } catch {
     return "unsafe";
   } finally {
-    closeSync4(descriptor);
+    closeSync5(descriptor);
   }
 }
 function readPrivateFile(home2, filePath, maxBytes) {
@@ -125631,19 +125707,19 @@ function readPrivateFile(home2, filePath, maxBytes) {
   const flags = constants7.O_RDONLY | (constants7.O_NOFOLLOW ?? 0) | (constants7.O_NONBLOCK ?? 0);
   let descriptor;
   try {
-    descriptor = openSync4(filePath, flags);
+    descriptor = openSync5(filePath, flags);
   } catch (error51) {
     return errno2(error51) === "ENOENT" ? { state: "missing" } : { state: "unsafe" };
   }
   try {
-    const stats = fstatSync5(descriptor);
+    const stats = fstatSync6(descriptor);
     if (!stats.isFile() || stats.dev !== before.dev || stats.ino !== before.ino || !privateOwnerAndMode(home2, stats, 384) || stats.size > maxBytes) {
       return { state: "unsafe" };
     }
     const bytes = Buffer.allocUnsafe(maxBytes + 1);
     let offset = 0;
     while (offset < bytes.byteLength) {
-      const count5 = readSync(descriptor, bytes, offset, bytes.byteLength - offset, null);
+      const count5 = readSync2(descriptor, bytes, offset, bytes.byteLength - offset, null);
       if (count5 === 0) break;
       offset += count5;
     }
@@ -125663,7 +125739,7 @@ function readPrivateFile(home2, filePath, maxBytes) {
   } catch {
     return { state: "unsafe" };
   } finally {
-    closeSync4(descriptor);
+    closeSync5(descriptor);
   }
 }
 function inspectUpdateCache(input) {
@@ -125745,7 +125821,7 @@ function writeCompleteTemp(home2, directory, baseName, content3, maxBytes) {
   const temporary = join17(directory, `.${baseName}.${randomBytes7(16).toString("hex")}.tmp`);
   let descriptor;
   try {
-    descriptor = openSync4(
+    descriptor = openSync5(
       temporary,
       constants7.O_WRONLY | constants7.O_CREAT | constants7.O_EXCL | (constants7.O_NOFOLLOW ?? 0),
       384
@@ -125753,13 +125829,13 @@ function writeCompleteTemp(home2, directory, baseName, content3, maxBytes) {
     writeFileSync5(descriptor, content3, "utf8");
     if (currentPrivateStateHost().enforcePrivateMode) fchmodSync2(descriptor, 384);
     fsyncSync2(descriptor);
-    closeSync4(descriptor);
+    closeSync5(descriptor);
     descriptor = void 0;
     return temporary;
   } catch (error51) {
     if (descriptor !== void 0) {
       try {
-        closeSync4(descriptor);
+        closeSync5(descriptor);
       } catch {
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.0-pre.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [
@@ -86,6 +86,6 @@
     "darwin",
     "linux"
   ],
-  "readme": "# superbee\n\nShared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in\nyour repo.\n\nSuperbee is pre-1.0. Commands and formats may change between releases.\n\n## What is Superbee?\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they know\ninvisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a\nfolder of markdown documents, by convention `.superbee/` at your project root, that agents read\nand write through a small command-line tool.\n\n- **Context that persists.** Agents write context notes, decisions, plans, and research into the\n  bundle. The next session, or a different agent, picks up where the last one left off. An\n  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session\n  automatically.\n- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the\n  version it last read; if anyone changed the document since, the write fails with a typed\n  conflict error instead of silently overwriting their work.\n- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on\n  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and\n  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which\n  shares the bundle with teammates through the board: a copy of the bundle kept on its own git\n  branch, separate from your code.\n- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a\n  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle\n  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can\n  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.\n- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set\n  of exit codes. Agents act on responses without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of\n  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it\n  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1\n  bundles keep working as they are. Reading and writing the bundle works offline; only sharing\n  needs a network. The document schemas, called kinds, live inside the bundle, so it describes\n  its own structure.\n\nBees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows\nthe next bee where to build and what belongs where. Superbee works the same way: people and\nagents record what they learn in a structure that fits their domain, and that structure guides\nwhoever works next. Each session builds on the last instead of starting over.\n\nThe npm package is one self-contained executable with zero runtime dependencies, plus an Agent\nSkill, an instruction file your agent loads, that teaches it how to use the tool.\n\n## Install\n\nRequires Node.js 20 or newer on macOS and Linux. Native Windows is not supported by this package.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:\n\n```sh\nnpm install -g superbee@next\n```\n\nWindows adapters and the `superbee-windows` executable live in a separate repository and are\nnot included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a\nLinux platform and the normal installation applies. An experimental, unsupported native Windows\nbuild is available as open source, with build-from-source instructions: https://github.com/Holaxis-ai/superbee-windows-cli\n\n### Upgrading an existing Windows installation\n\nThe first release containing the Windows extraction removes native Windows support from this\npackage. Its npm `os` metadata permits only `darwin` and `linux`, so a Windows upgrade to an affected\nversion is rejected with `EBADPLATFORM`. This applies to existing prerelease users too. Forcing the\ninstallation does not restore support: the executable refuses commands on unsupported hosts\nbefore running them (the bare `--version` flag can still identify the installed build).\n\nThere is no supported Windows replacement on npm. The alternatives are WSL2 or the experimental\nbuild from source at https://github.com/Holaxis-ai/superbee-windows-cli; neither carries a\nfirst-party support promise for native Windows. An older installed version is not converted or\nremoved by this source change, and existing bundle files are not migrated by it. Review the affected release's notes before changing an existing\nWindows installation. macOS/Linux users can continue using the normal installation and setup flow.\n\nRun `superbee version --check` to compare your install with the current stable release.\n\n## First run: let your agent finish setup\n\n`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and\nMCP server registration, where MCP is the Model Context Protocol) are installed by your agent,\nnot by hand. Ask it:\n\n> Run `superbee setup` and follow its instructions.\n\nSetup itself changes nothing. It inspects your configuration and returns one safe next command at\na time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,\nplus Claude Desktop for the MCP registration only.\n\n## Everyday use\n\nYou rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the\nrequest into CLI calls:\n\n- \"Set up a Superbee bundle for this project and track our tasks in it.\"\n- \"Write up what we decided about the auth design as a doc, and link it to the task.\"\n- \"What did the last session leave off on? Check the context notes.\"\n- \"Sync the board so my teammate's agent sees this.\"\n- \"Give me a view of the open tasks grouped by owner.\"\n\nBehind those requests the agent uses a small set of commands: `init --dir .superbee` creates the\nbundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,\n`doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and\n`sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`\ngives each one's full reference.\n\nThe two commands meant for you are the ones that show you the knowledge:\n\n```sh\nsuperbee ui --open        # the whole bundle, rendered in your browser\nsuperbee doc open <id>    # one document, by an id from `superbee list`\n```\n\n## Upgrading from aslite\n\nIf you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install\n`superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then\nrun `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and\n`.agentstate.json` bindings keep working with no migration.\n\n## Learn more\n\nThe [repository](https://github.com/Holaxis-ai/superbee) holds the source, the\n[CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/superbee/AXI-CONTRACT.md),\nand the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
+  "readme": "# superbee\n\nShared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in\nyour repo.\n\nSuperbee is pre-1.0. Commands and formats may change between releases.\n\n## What is Superbee?\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they know\ninvisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a\nfolder of markdown documents, by convention `.superbee/` at your project root, that agents read\nand write through a small command-line tool.\n\n- **Context that persists.** Agents write context notes, decisions, plans, and research into the\n  bundle. The next session, or a different agent, picks up where the last one left off. An\n  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session\n  automatically.\n- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the\n  version it last read; if anyone changed the document since, the write fails with a typed\n  conflict error instead of silently overwriting their work.\n- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on\n  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and\n  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which\n  shares the bundle with teammates through the board: a copy of the bundle kept on its own git\n  branch, separate from your code.\n- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a\n  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle\n  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can\n  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.\n- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set\n  of exit codes. Agents act on responses without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of\n  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it\n  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1\n  bundles keep working as they are. Reading and writing the bundle works offline; only sharing\n  needs a network. The document schemas, called kinds, live inside the bundle, so it describes\n  its own structure.\n\nBees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows\nthe next bee where to build and what belongs where. Superbee works the same way: people and\nagents record what they learn in a structure that fits their domain, and that structure guides\nwhoever works next. Each session builds on the last instead of starting over.\n\nThe npm package is one self-contained executable with zero runtime dependencies, plus an Agent\nSkill, an instruction file your agent loads, that teaches it how to use the tool.\n\n## Install\n\nRequires Node.js 20 or newer on macOS and Linux. Native Windows is not supported by this package.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`.\n\nWindows adapters and the `superbee-windows` executable live in a separate repository and are\nnot included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a\nLinux platform and the normal installation applies. An experimental, unsupported native Windows\nbuild is available as open source, with build-from-source instructions: https://github.com/Holaxis-ai/superbee-windows-cli\n\n### Upgrading an existing Windows installation\n\nThe first release containing the Windows extraction removes native Windows support from this\npackage. Its npm `os` metadata permits only `darwin` and `linux`, so a Windows upgrade to an affected\nversion is rejected with `EBADPLATFORM`. This applies to existing prerelease users too. Forcing the\ninstallation does not restore support: the executable refuses commands on unsupported hosts\nbefore running them (the bare `--version` flag can still identify the installed build).\n\nThere is no supported Windows replacement on npm. The alternatives are WSL2 or the experimental\nbuild from source at https://github.com/Holaxis-ai/superbee-windows-cli; neither carries a\nfirst-party support promise for native Windows. An older installed version is not converted or\nremoved by this source change, and existing bundle files are not migrated by it. Review the affected release's notes before changing an existing\nWindows installation. macOS/Linux users can continue using the normal installation and setup flow.\n\nRun `superbee version --check` to compare your install with the current stable release.\n\n## First run: let your agent finish setup\n\n`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and\nMCP server registration, where MCP is the Model Context Protocol) are installed by your agent,\nnot by hand. Ask it:\n\n> Run `superbee setup` and follow its instructions.\n\nSetup itself changes nothing. It inspects your configuration and returns one safe next command at\na time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,\nplus Claude Desktop for the MCP registration only.\n\n## Everyday use\n\nYou rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the\nrequest into CLI calls:\n\n- \"Set up a Superbee bundle for this project and track our tasks in it.\"\n- \"Write up what we decided about the auth design as a doc, and link it to the task.\"\n- \"What did the last session leave off on? Check the context notes.\"\n- \"Sync the board so my teammate's agent sees this.\"\n- \"Give me a view of the open tasks grouped by owner.\"\n\nBehind those requests the agent uses a small set of commands: `init --dir .superbee` creates the\nbundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,\n`doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and\n`sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`\ngives each one's full reference.\n\nThe two commands meant for you are the ones that show you the knowledge:\n\n```sh\nsuperbee ui --open        # the whole bundle, rendered in your browser\nsuperbee doc open <id>    # one document, by an id from `superbee list`\n```\n\n## Upgrading from aslite\n\nIf you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install\n`superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then\nrun `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and\n`.agentstate.json` bindings keep working with no migration.\n\n## Learn more\n\nThe [repository](https://github.com/Holaxis-ai/superbee) holds the source, the\n[CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/superbee/AXI-CONTRACT.md),\nand the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
   "readmeFilename": "README.md"
 }

package/references/hosted-checkout.md

@@ -150,10 +150,11 @@ the host accepts it. Never shorten someone else's document just to make it sync.
 
 Read a large document a page at a time instead of pulling it whole into context: `superbee doc read
 <id> --offset 0 --json` answers `body` as one page of about 32 KiB with `range` (`complete`,
-`next_offset`); continue with `--offset <next_offset> --expected-version <head_version>` until
-`complete` is true. A page is not the document: never write it back as the body. To edit, use `doc
-read <id> --body-out <path-outside-bundle>`, edit that file, then `doc update <id> --body-file
-<path> --expected-version <version>`.
+`next_offset`); continue with `--offset <next_offset> --expected-version <head_version>` while
+`next_offset` is present. The page without `next_offset` is the last one; `complete` is true only
+when the whole body fit in one page, so never loop on it. A page is not the document: never write
+it back as the body. To edit, use `doc read <id> --body-out <path-outside-bundle>`, edit that file,
+then `doc update <id> --body-file <path> --expected-version <version>`.
 
 ## Host reads with no verb yet: `op list` and `op run`