superbee 0.4.2-pre.3 → 0.4.2

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = 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.2-pre.3" }, source: { commit: "ab47b44609c0dbf90257f5ffc2d739915818b719", 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.2" }, source: { commit: "069a42092f39d8261ccd4322c0dc7ff5488aa2c8", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -12923,8 +12923,7 @@ function isConceptDocPath(relPath) {
   return relPath.endsWith(".md") && !isReservedFile(relPath);
 }
 function nameStatusRows(out) {
-  const fields2 = out.split("\0");
-  if (fields2.length > 0 && fields2[fields2.length - 1] === "") fields2.pop();
+  const fields2 = nulFields(out);
   const rows = [];
   for (let i = 0; i + 1 < fields2.length; i += 2) {
     const letter = (fields2[i] ?? "").trim().charAt(0);
@@ -13004,13 +13003,8 @@ ${bodyLines2.join("\n")}
   return { committed: true, sha, subject, docs };
 }
 function malformedOutgoingDocuments(boardPath) {
-  const listed2 = runGit(boardPath, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames"]);
-  if (listed2.status !== 0) throw classifyGitError(failureOf(["status"], listed2));
   const held2 = [];
-  for (const record6 of listed2.stdout.split("\0")) {
-    if (record6.length < 4) continue;
-    const code3 = record6.slice(0, 2);
-    const relPath = record6.slice(3);
+  for (const { status: code3, path: relPath } of readStatusRows(boardPath, { allUntracked: true })) {
     if (code3.includes("D") || !isConceptDocPath(relPath)) continue;
     const file2 = path7.join(boardPath, relPath);
     const content3 = readRegularFile(file2);
@@ -13239,7 +13233,6 @@ function fetchRebaseResolving(boardPath, exportDir) {
   const r2 = runGit(boardPath, [...idFlags, "rebase", boardRef], { rebase: true, timeoutMs: NETWORK_TIMEOUT_MS });
   if (r2.status === 0) return { status: "clean" };
   if (!detectStaleRebase(boardPath)) throw classifyGitError(failureOf(["rebase", boardRef], r2));
-  const listConflicted = () => mustGit(boardPath, ["diff", "--name-only", "-z", "--diff-filter=U"]).split("\0").filter((l) => l.length > 0);
   const byPath = /* @__PURE__ */ new Map();
   try {
     let stops = 0;
@@ -13250,7 +13243,7 @@ function fetchRebaseResolving(boardPath, exportDir) {
           `sync's converging rebase did not terminate after ${MAX_REBASE_STOPS} stops \u2014 aborting to leave the board unchanged`
         );
       }
-      const conflicted = listConflicted();
+      const conflicted = conflictedPaths(boardPath);
       if (conflicted.length === 0) {
         runGit(boardPath, [...idFlags, "rebase", "--skip"], { rebase: true });
         continue;
@@ -13306,13 +13299,8 @@ function fetchRebaseResolving(boardPath, exportDir) {
   return { status: "resolved", conflicts: [...byPath.values()] };
 }
 function privateStateInOutgoingWorktree(boardPath) {
-  const listed2 = runGit(boardPath, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames"]);
-  if (listed2.status !== 0) throw classifyGitError(failureOf(["status"], listed2));
   const found = [];
-  for (const record6 of listed2.stdout.split("\0")) {
-    if (record6.length < 4) continue;
-    const code3 = record6.slice(0, 2);
-    const relPath = record6.slice(3);
+  for (const { status: code3, path: relPath } of readStatusRows(boardPath, { allUntracked: true })) {
     if (code3.includes("D")) continue;
     const finding = privateStateFinding(relPath, readPrivateStateCandidate(path7.join(boardPath, relPath)));
     if (finding) found.push(finding);
@@ -13532,10 +13520,42 @@ function currentBranch(top) {
   const r2 = runGit(top, ["rev-parse", "--abbrev-ref", "HEAD"]);
   return r2.status === 0 ? r2.stdout.trim() : "HEAD";
 }
+function nulFields(out) {
+  const fields2 = out.split("\0");
+  if (fields2.at(-1) === "") fields2.pop();
+  return fields2;
+}
+function readStatusRows(dir, opts = {}) {
+  const args = [
+    "status",
+    "--porcelain=v1",
+    "-z",
+    ...opts.renamePolicy === "configured" ? [] : ["--no-renames"],
+    ...opts.allUntracked ? ["--untracked-files=all"] : [],
+    ...opts.prefix ? ["--", opts.prefix] : []
+  ];
+  const r2 = runGit(dir, args);
+  if (r2.status !== 0) {
+    if (opts.tolerateFailure) return [];
+    throw classifyGitError(failureOf(args, r2));
+  }
+  const fields2 = nulFields(r2.stdout);
+  const rows = [];
+  for (let i = 0; i < fields2.length; i += 1) {
+    const record6 = fields2[i];
+    if (record6.length < 4) continue;
+    const status2 = record6.slice(0, 2).trim();
+    const row4 = { status: status2, path: record6.slice(3) };
+    if (status2.includes("R") || status2.includes("C")) row4.originalPath = fields2[++i];
+    rows.push(row4);
+  }
+  return rows;
+}
+function conflictedPaths(dir) {
+  return nulFields(mustGit(dir, ["diff", "--name-only", "--no-renames", "-z", "--diff-filter=U"]));
+}
 function statusRows(dir, prefix) {
-  const r2 = runGit(dir, ["status", "--porcelain", ...prefix ? ["--", prefix] : []]);
-  if (r2.status !== 0) return [];
-  return r2.stdout.split("\n").map((l) => l.trimEnd()).filter((l) => l.length > 0).map((l) => ({ status: l.slice(0, 2).trim(), path: l.slice(3) }));
+  return readStatusRows(dir, { prefix, tolerateFailure: true, renamePolicy: "configured" });
 }
 function countUncommitted(boardPath, prefix) {
   return statusRows(boardPath, prefix).length;
@@ -21506,7 +21526,7 @@ var init_nofollow_read = __esm({
   }
 });
 
-// ../cli/src/hosted/export-archive.ts
+// ../core/src/portable-export.ts
 import { createHash as createHash6 } from "node:crypto";
 function crc32(bytes) {
   let crc = 4294967295;
@@ -21645,7 +21665,7 @@ function verifyExport(archive, bundleId, options = {}) {
   }
   if (!isRecord7(manifest)) throw new ExportArchiveError("manifest_mismatch", "the manifest is not an object");
   if (manifest.format !== EXPORT_FORMAT) {
-    throw new ExportArchiveError("unsupported_format", `the export format is ${JSON.stringify(manifest.format)}; this CLI reads ${EXPORT_FORMAT}`);
+    throw new ExportArchiveError("unsupported_format", `the export format is ${JSON.stringify(manifest.format)}; this reader accepts ${EXPORT_FORMAT}`);
   }
   const source = manifest.source;
   const counts = manifest.counts;
@@ -21712,25 +21732,81 @@ function verifyExport(archive, bundleId, options = {}) {
   if (collision) {
     throw new ExportArchiveError("unsafe_path", `the archive holds paths one folder cannot keep apart: ${JSON.stringify(collision[0])} and ${JSON.stringify(collision[1])}`);
   }
-  return {
+  return rememberVerified({
     source: { tenantId: source.tenantId, bundleId: source.bundleId, revision: source.revision, okfEdition: source.okfEdition },
     exportedAt: manifest.exportedAt,
     counts: tally,
     entries,
     bytes,
     ...page ? { page } : {}
+  }, [{ sha256: sha256Hex2(manifests[0].data), bytes: manifests[0].data.byteLength }], archive.byteLength);
+}
+function inventoryOf(verified2) {
+  return verified2.entries.map((entry) => ({
+    path: entry.path,
+    kind: entry.kind,
+    bytes: entry.bytes.byteLength,
+    sha256: sha256Hex2(entry.bytes)
+  })).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+function fingerprintOf(verified2) {
+  return JSON.stringify({
+    source: verified2.source,
+    exportedAt: verified2.exportedAt,
+    counts: verified2.counts,
+    bytes: verified2.bytes,
+    page: verified2.page,
+    entries: verified2.entries.map((entry) => ({
+      path: entry.path,
+      kind: entry.kind,
+      bytes: entry.bytes.byteLength,
+      sha256: sha256Hex2(entry.bytes)
+    }))
+  });
+}
+function rememberVerified(verified2, manifests, archiveBytes) {
+  const snapshot2 = {
+    source: { ...verified2.source },
+    exportedAt: verified2.exportedAt,
+    counts: { ...verified2.counts },
+    entries: verified2.entries.map((entry) => ({ ...entry, bytes: Uint8Array.from(entry.bytes) })),
+    bytes: verified2.bytes,
+    ...verified2.page ? { page: { ...verified2.page, counts: { ...verified2.page.counts } } } : {}
+  };
+  const state = {
+    snapshot: snapshot2,
+    archiveBytes,
+    fingerprint: fingerprintOf(verified2),
+    provenance: {
+      source: { ...verified2.source },
+      exportedAt: verified2.exportedAt,
+      manifests: manifests.map((manifest) => ({ ...manifest })),
+      inventorySha256: sha256Hex2(new TextEncoder().encode(JSON.stringify(inventoryOf(verified2))))
+    }
   };
+  verifiedStates.set(verified2, state);
+  verifiedStates.set(snapshot2, state);
+  return verified2;
 }
-var EXPORT_MANIFEST, IN_PLACE_STAGING, IN_PLACE_JOURNAL, EXPORT_FORMAT, MAX_EXPORT_ENTRIES, MAX_EXPORT_BYTES, LOCAL, CENTRAL, END, UTF8_NAMES, ExportArchiveError, CRC_TABLE, sha256Hex2, utf8, WINDOWS_DEVICE_NAMES, fold3, ExportPageChain;
-var init_export_archive = __esm({
-  "../cli/src/hosted/export-archive.ts"() {
+function exportProvenance(verified2) {
+  const state = verifiedStates.get(verified2);
+  if (!state || state.fingerprint !== fingerprintOf(verified2)) {
+    throw new ExportArchiveError("manifest_mismatch", "the verified export handle is absent or changed");
+  }
+  return {
+    ...state.provenance,
+    source: { ...state.provenance.source },
+    manifests: state.provenance.manifests.map((manifest) => ({ ...manifest }))
+  };
+}
+var EXPORT_MANIFEST, EXPORT_FORMAT, MAX_EXPORT_ENTRIES, MAX_EXPORT_BYTES, LOCAL, CENTRAL, END, UTF8_NAMES, ExportArchiveError, CRC_TABLE, sha256Hex2, utf8, WINDOWS_DEVICE_NAMES, fold3, ExportPageChain, verifiedStates;
+var init_portable_export = __esm({
+  "../core/src/portable-export.ts"() {
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
-    init_src();
+    init_paths();
     EXPORT_MANIFEST = "superbee-export.json";
-    IN_PLACE_STAGING = ".superbee-export-partial";
-    IN_PLACE_JOURNAL = "journal.json";
     EXPORT_FORMAT = "superbee-export/1";
     MAX_EXPORT_ENTRIES = 20001;
     MAX_EXPORT_BYTES = 128 * 1024 * 1024;
@@ -21763,17 +21839,23 @@ var init_export_archive = __esm({
       #pages = [];
       #from = 0;
       #ended = false;
+      #archiveBytes = 0;
       /** Adds the next page; answers its next cursor, or undefined once the export is whole. */
       add(verified2) {
-        const page = verified2.page;
-        const first = this.#pages[0] ?? verified2;
+        exportProvenance(verified2);
+        const state = verifiedStates.get(verified2);
+        const accepted = state.snapshot;
+        const page = accepted.page;
+        const first = this.#pages[0] ?? accepted;
         if (!page || !first.page || this.#ended) throw new ExportArchiveError("manifest_mismatch", "a paged export answered a page outside its run");
         const counts = first.page.counts;
-        if (verified2.source.tenantId !== first.source.tenantId || verified2.source.bundleId !== first.source.bundleId || verified2.source.revision !== first.source.revision || verified2.source.okfEdition !== first.source.okfEdition || page.counts.documents !== counts.documents || page.counts.reserved !== counts.reserved || page.counts.blobs !== counts.blobs || page.total !== first.page.total || page.total !== counts.documents + counts.reserved + counts.blobs || page.total > MAX_EXPORT_ENTRIES - 1) {
+        if (accepted.source.tenantId !== first.source.tenantId || accepted.source.bundleId !== first.source.bundleId || accepted.source.revision !== first.source.revision || accepted.source.okfEdition !== first.source.okfEdition || page.counts.documents !== counts.documents || page.counts.reserved !== counts.reserved || page.counts.blobs !== counts.blobs || page.total !== first.page.total || page.total !== counts.documents + counts.reserved + counts.blobs || page.total > MAX_EXPORT_ENTRIES - 1) {
           throw new ExportArchiveError("manifest_mismatch", "the pages do not describe one export of one revision");
         }
         if (page.from !== this.#from) throw new ExportArchiveError("manifest_mismatch", "the pages leave a gap or overlap");
-        this.#pages.push(verified2);
+        if (state.archiveBytes > MAX_EXPORT_BYTES - this.#archiveBytes) throw malformed2("the pages are larger than an export carries");
+        this.#archiveBytes += state.archiveBytes;
+        this.#pages.push(accepted);
         this.#from += page.count;
         if (page.next === void 0) this.#ended = true;
         return page.next;
@@ -21788,7 +21870,7 @@ var init_export_archive = __esm({
         let bytes = 0;
         for (const verified2 of this.#pages) {
           for (const entry of verified2.entries) {
-            entries.push(entry);
+            entries.push({ ...entry, bytes: Uint8Array.from(entry.bytes) });
             tally[entry.kind === "document" ? "documents" : entry.kind === "reserved" ? "reserved" : "blobs"] += 1;
             bytes += entry.bytes.byteLength;
           }
@@ -21806,9 +21888,23 @@ var init_export_archive = __esm({
         if (collision) {
           throw new ExportArchiveError("unsafe_path", `the archive holds paths one folder cannot keep apart: ${JSON.stringify(collision[0])} and ${JSON.stringify(collision[1])}`);
         }
-        return { source: first.source, exportedAt: first.exportedAt, counts: tally, entries, bytes };
+        return rememberVerified({ source: { ...first.source }, exportedAt: first.exportedAt, counts: tally, entries, bytes }, this.#pages.flatMap((verified2) => exportProvenance(verified2).manifests), this.#archiveBytes);
       }
     };
+    verifiedStates = /* @__PURE__ */ new WeakMap();
+  }
+});
+
+// ../cli/src/hosted/export-archive.ts
+var IN_PLACE_STAGING, IN_PLACE_JOURNAL;
+var init_export_archive = __esm({
+  "../cli/src/hosted/export-archive.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_portable_export();
+    IN_PLACE_STAGING = ".superbee-export-partial";
+    IN_PLACE_JOURNAL = "journal.json";
   }
 });
 
@@ -26582,10 +26678,12 @@ function chunked(items, size) {
   for (let start = 0; start < items.length; start += size) out.push(items.slice(start, start + size));
   return out;
 }
-function concurrencyOf(options) {
-  const value = options.concurrency ?? DEFAULT_CONCURRENCY;
-  if (!Number.isInteger(value) || value < 1) throw new InvalidInputError(`concurrency must be an integer of at least 1, got ${String(value)}`);
-  return value;
+function admitFetchOptions(options) {
+  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+  if (!Number.isInteger(concurrency) || concurrency < 1) throw new InvalidInputError(`concurrency must be an integer of at least 1, got ${String(concurrency)}`);
+  const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new InvalidInputError(`batchSize must be a safe integer of at least 1, got ${String(batchSize)}`);
+  return { batchSize, concurrency };
 }
 async function forEachBatch(batches, concurrency, work) {
   let next = 0;
@@ -26705,7 +26803,7 @@ async function wireFor(remote, local, feature, options) {
   return (await capabilitiesOf(local, wire))[feature] ? wire : null;
 }
 async function bootstrap(remote, local, options = {}) {
-  const concurrency = concurrencyOf(options);
+  const { batchSize, concurrency } = admitFetchOptions(options);
   const backend = await runtimeBackend(local);
   const bodyMode2 = await admitBodyMode(backendOf(local));
   const validateReadSide = bodyMode2 ? () => assertBodyRemoteEdition(remote, bodyMode2) : void 0;
@@ -26724,7 +26822,6 @@ async function bootstrap(remote, local, options = {}) {
     const rootIndex = await remote.readReserved("", "index.md");
     if (rootIndex) await backend.writeReserved("", "index.md", rootIndex.content);
   }
-  const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
   const findings = [];
   const held2 = [];
   const written = /* @__PURE__ */ new Map();
@@ -26984,6 +27081,16 @@ async function retireQuietly(backend, mode, target3) {
 function conflictResolutionKey(id) {
   return `conflict-resolution:${id}`;
 }
+function documentResolutionKey(id) {
+  return `conflict-resolution-document:${id}`;
+}
+async function readConflictResolution(local, id) {
+  const backend = backendOf(local);
+  const identity = await backend.readMeta(documentResolutionKey(id));
+  if (typeof identity !== "string") return void 0;
+  const receipt3 = await backend.readMeta(conflictResolutionKey(identity));
+  return receipt3?.id === identity && receipt3.reviewed?.id === id ? receipt3 : void 0;
+}
 async function readConflictRemote(remote, id) {
   try {
     const read = await remote.read(id);
@@ -27054,7 +27161,7 @@ async function resolveConflict(local, remote, reviewed, choice, options = {}) {
   if (reviewedShared.version !== review.remote.version || reviewedShared.content !== review.remote.content || reviewedShared.tombstone !== review.remote.tombstone) throw new ConflictReviewStaleError();
   if (current.deleting && selected2.kind === "revise") throw new InvalidInputError("A deletion in conflict is resolved by keeping the deletion or taking the shared version.");
   const resolvedAt = options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
-  const requestId2 = selected2.kind === "take-remote" ? null : mintRequestId();
+  const requestId2 = selected2.kind === "take-remote" || current.deleting && shared.base.version === null ? null : mintRequestId();
   const receipt3 = {
     // The original conflict identity lets a caller recover the receipt after a lost local reply.
     id: current.intents[0].requestId,
@@ -27066,6 +27173,7 @@ async function resolveConflict(local, remote, reviewed, choice, options = {}) {
   const resolveIntents = { expected: current.intents };
   const meta3 = [
     { key: conflictResolutionKey(receipt3.id), value: receipt3 },
+    { key: documentResolutionKey(review.id), value: receipt3.id },
     // Someone else's deletion is never remembered as this working copy's own: a later create of
     // the id acknowledges nothing and meets the conflict again, until an explicit keep.
     { key: baseKey(review.id), value: { version: shared.base.version, content: shared.base.content } }
@@ -27074,7 +27182,7 @@ async function resolveConflict(local, remote, reviewed, choice, options = {}) {
   if (current.deleting && selected2.kind === "keep-local") {
     if (shared.base.version === null) {
       await backend.deleteJournaled(review.id, common);
-      return { receipt: { ...receipt3, replacementRequestId: null }, version: null, intent: null };
+      return { receipt: receipt3, version: null, intent: null };
     }
     const deleted = await backend.deleteJournaled(review.id, {
       ...common,
@@ -27538,7 +27646,7 @@ async function lastKnownDigest(backend) {
   return { digest: marker.headsDigest, lastPull: read };
 }
 async function pull(local, remote, options = {}) {
-  const concurrency = concurrencyOf(options);
+  const { batchSize, concurrency } = admitFetchOptions(options);
   const backend = await runtimeBackend(local);
   const bodyMode2 = await admitBodyMode(backendOf(local));
   const validateReadSide = bodyMode2 ? () => assertBodyRemoteEdition(remote, bodyMode2) : void 0;
@@ -27638,7 +27746,7 @@ async function pull(local, remote, options = {}) {
     }
   };
   let consistent = true;
-  const fetchAndApply = (candidates2, listing) => forEachBatch(chunked(candidates2, options.batchSize ?? DEFAULT_BATCH_SIZE), concurrency, async (batch) => {
+  const fetchAndApply = (candidates2, listing) => forEachBatch(chunked(candidates2, batchSize), concurrency, async (batch) => {
     if (superseded) return;
     const premises2 = bodyMode2 ? await captureBodyRefresh(backendOf(local), bodyMode2, batch) : void 0;
     if (!listing) {
@@ -37502,33 +37610,40 @@ function resolvedRecord(binding, id, choice, fileState, sends, already = false,
     help: sends ? [sync3] : []
   };
 }
-function resolvedKey(id) {
-  return `cli-resolved:${id}`;
+function folderResolutionKey(id) {
+  return `cli-folder-resolved:${id}`;
 }
-async function beginResolution(store, id, choice) {
+async function beginFolderResolution(store, id, choice) {
   if (choice === "take") return;
   const after = (await store.listIntents()).reduce((max, row4) => Math.max(max, row4.sequence), 0);
-  await store.writeMeta(resolvedKey(id), { choice, after });
+  await store.writeMeta(folderResolutionKey(id), { choice, after });
 }
-async function recordResolution(store, id, choice) {
+async function recordFolderResolution(store, id, choice) {
   if (choice === "take") {
-    await store.writeMeta(resolvedKey(id), null);
+    await store.writeMeta(folderResolutionKey(id), null);
     return;
   }
   const requestIds = (await store.readWithJournal(id)).intents.filter((row4) => row4.state !== "acknowledged").map((row4) => row4.requestId);
-  await store.writeMeta(resolvedKey(id), { choice, requestIds });
+  await store.writeMeta(folderResolutionKey(id), { choice, requestIds });
 }
 function isResolution(record6, row4) {
-  if (!record6?.choice) return false;
-  if (Array.isArray(record6.requestIds)) return record6.requestIds.includes(row4.requestId);
-  return typeof record6.after === "number" && row4.sequence > record6.after;
+  return !!record6?.choice && Array.isArray(record6.requestIds) && record6.requestIds.includes(row4.requestId);
 }
 async function resolveAgain(session, id, choice, resumeCommand) {
-  const { binding, store, projection } = session;
+  const { binding, store, projection, local } = session;
   const file2 = path38.join(binding.path, `${id}.md`);
-  const earlier = await store.readMeta(resolvedKey(id));
   const rows = (await store.readWithJournal(id)).intents.filter((row5) => row5.state !== "acknowledged");
+  const receipt3 = await readConflictResolution(local, id);
+  const folder = await store.readMeta(folderResolutionKey(id));
+  const journal = receipt3 ? { choice: receipt3.choice === "keep-local" ? "keep" : receipt3.choice === "revise" ? "revise" : "take", requestIds: receipt3.replacementRequestId === null ? [] : [receipt3.replacementRequestId] } : void 0;
+  const earlier = folder && rows[0] && isResolution(folder, rows[0]) ? folder : journal ?? folder ?? await store.readMeta(`cli-resolved:${id}`);
   const sync3 = syncCommand2(binding);
+  if (earlier?.choice && rows.length > 0 && !Array.isArray(earlier.requestIds) && typeof earlier.after === "number") {
+    throw new CliError("CONFLICT", `'${id}' has an interrupted resolution whose replacement identity is unknown; its pending work is preserved`, {
+      details: { reason: "resolution_identity_unknown", id, earlier: earlier.choice, states: rows.map((row5) => row5.state) },
+      help: `run ${sync3} to send the existing edit; if it reports a conflict on '${id}', inspect and resolve that one`
+    });
+  }
   if (!earlier?.choice || rows.length === 0 || !isResolution(earlier, rows[0])) {
     throw new CliError("CONFLICT", `'${id}' has an unsent change but no conflict to resolve; the next sync sends it`, {
       details: { reason: "unsent_change", id, states: rows.map((row5) => row5.state) },
@@ -37557,11 +37672,14 @@ async function resolveAgain(session, id, choice, resumeCommand) {
   await store.writeJournaled(id, { id, frontmatter: parsed2.frontmatter, body: parsed2.body }, {
     expectedVersion: current.document?.version ?? null,
     supersede: { requestId: row4.requestId, expectedState: "pending", expectedAttempts: 0 },
-    meta: [{ key: baseKey(id), value: { version: row4.base, content: row4.baseContent } }]
+    meta: [
+      { key: baseKey(id), value: { version: row4.base, content: row4.baseContent } },
+      { key: folderResolutionKey(id), value: null },
+      { key: `cli-resolved:${id}`, value: null }
+    ]
   });
   if (bytes === null) delete projection.files[id];
   const exported = await exportCheckout(binding.path, store, projection, { only: /* @__PURE__ */ new Set([id]), placeMissing: true });
-  await store.writeMeta(resolvedKey(id), null);
   await session.persist();
   return resolvedRecord(binding, id, choice, exported.placed.length > 0 ? bytes === null ? "restored" : "replaced" : "unchanged", false, false, earlier.choice);
 }
@@ -37830,10 +37948,10 @@ async function runResolve2(binding, values, deps, mode) {
       throw error51;
     }
     await assertInspectedCurrent(session, id, remoteVersionOf(conflict), choice);
-    await beginResolution(store, id, choice);
     let fileState;
     if (conflict.kind === "folder") {
       if (conflict.deleted && choice !== "take") await assertInspectedTombstone(session, id, null, choice);
+      await beginFolderResolution(store, id, choice);
       fileState = await resolveFolder(session, id, choice, conflict, resumeCommand);
     } else {
       const deleting = conflict.review.local.deleted === true;
@@ -37891,7 +38009,7 @@ async function runResolve2(binding, values, deps, mode) {
       }
     }
     await store.writeMeta(inspectedKey(id), null);
-    await recordResolution(store, id, choice);
+    if (conflict.kind === "folder") await recordFolderResolution(store, id, choice);
     await session.persist();
     return resolvedRecord(binding, id, choice, fileState, choice !== "take");
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.2-pre.3",
+  "version": "0.4.2",
   "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": [
@@ -37,6 +37,10 @@
     "./bundle-descriptor": {
       "types": "./dist/bundle-descriptor/index.d.ts",
       "default": "./dist/bundle-descriptor.mjs"
+    },
+    "./portable-export": {
+      "types": "./dist/portable-export.d.ts",
+      "default": "./dist/portable-export.mjs"
     }
   },
   "files": [
@@ -86,6 +90,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 a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or 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 a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or 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"
 }