superbee 0.4.0-pre.3 → 0.4.0-pre.4

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-pre.4" }, source: { commit: "2f12937e983b904d7a5c529ab12c546b682bd883", 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-pre.4",
   "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": [

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`