superbee 0.4.4-pre.10 → 0.4.4-pre.11

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.4-pre.10" }, source: { commit: "81c77f780e9c7b2dec6e83702f1627d8a1eb9dbc", 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.4-pre.11" }, source: { commit: "cef05a992af831496c63bfb020b73ccb5eba34b7", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -28987,7 +28987,7 @@ var init_command_spec = __esm({
           {
             id: "pull",
             leaves: [publicLeaf("pull", "pull", zero, 6, DIR_OUT_SURFACE)],
-            usage: "pull --doc-key <key> --out (<path> | -) [--dir <path>] [--remote <url>]",
+            usage: "pull --doc-key <key> --out (<path> | -) [--from-host] [--dir <path>] [--remote <url>]",
             summary: "Pull a doc's canonical form or a blob's raw bytes out of the store (the reverse of promote)"
           },
           {
@@ -55949,6 +55949,9 @@ function wording(client, target3, resume2) {
   const { prefix } = client;
   const failure3 = (error51) => hostedFailure(error51, target3, resume2);
   const readFailure2 = (error51, route, missing2) => {
+    if (error51 instanceof HostedReadAdapterError && error51.code === "unsupported") {
+      return new CliError("NOT_IMPLEMENTED", missing2.message, { details: { host: target3.origin, route, reason: "unsupported" }, help: missing2.help });
+    }
     if (isRouteNotServed(error51)) {
       return new CliError("NOT_IMPLEMENTED", missing2.message, { details: { host: target3.origin, route: error51.route, status: 404 }, help: missing2.help });
     }
@@ -55992,6 +55995,26 @@ function wording(client, target3, resume2) {
     reader(bundleId2) {
       return client.reader(bundleId2);
     },
+    async blobHead(bundleId2, key4, options) {
+      try {
+        return await client.blobHead(bundleId2, key4, options);
+      } catch (error51) {
+        throw readFailure2(error51, `${prefix}/blob-heads`, {
+          message: `${target3.origin} does not serve blob reads yet`,
+          help: "a later release of the host serves them"
+        });
+      }
+    },
+    async readBlob(bundleId2, key4, options) {
+      try {
+        return await client.readBlob(bundleId2, key4, options);
+      } catch (error51) {
+        throw readFailure2(error51, `${prefix}/blob-read`, {
+          message: `${target3.origin} does not serve blob reads yet`,
+          help: "a later release of the host serves them"
+        });
+      }
+    },
     within(slug) {
       return wording(client.within(slug), target3, resume2);
     },
@@ -56084,6 +56107,7 @@ var init_client2 = __esm({
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_hosted_client();
+    init_hosted_transport();
     init_errors6();
     init_invocation();
     init_command_text();
@@ -104914,6 +104938,26 @@ Options:
 import { parseArgs as parseArgs16 } from "node:util";
 import { promises as fs16 } from "node:fs";
 import path53 from "node:path";
+import { homedir as homedir30 } from "node:os";
+async function pullHostedBlob(bundle, key4, out, json4, deps2) {
+  const home2 = deps2.hosted?.auth?.home ?? homedir30();
+  const binding2 = await bindingForPath(home2, await fs16.realpath(bundle.root));
+  if (!binding2) throw new CliError("USAGE", "--from-host requires a bound hosted checkout", {
+    help: "pass --dir with the original checkout folder; ordinary pull reads a local working copy"
+  });
+  const resume2 = commandFragment`${cliInvocation()} pull --doc-key ${commandToken(key4)} --out ${commandToken(out)} --from-host --dir ${commandToken(binding2.path)}${json4 ? commandFragment` --json` : commandFragment``}`;
+  const { client } = await openCheckoutConnection(binding2, deps2.hosted, resume2, home2);
+  const head2 = await client.blobHead(binding2.bundle_id, key4);
+  if (!head2) throw new CliError("NOT_FOUND", `no hosted blob at key '${key4}'`);
+  const result3 = await client.readBlob(binding2.bundle_id, key4, { pin: head2 });
+  if (!result3) throw new CliError("CONFLICT", `hosted blob '${key4}' changed during readback`, {
+    help: "retry the same pull to read a fresh version and content type"
+  });
+  return {
+    bytes: result3.bytes,
+    fields: { route: "blob", source: "hosted", content_type: result3.contentType, version: result3.version, size_bytes: result3.bytes.byteLength }
+  };
+}
 function isDocRouteKey2(key4) {
   return key4.toLowerCase().endsWith(".md");
 }
@@ -104979,6 +105023,7 @@ async function pull2(argv2, deps2 = {}) {
       options: {
         "doc-key": { type: "string" },
         out: { type: "string" },
+        "from-host": { type: "boolean" },
         dir: { type: "string" },
         remote: { type: "string" },
         json: { type: "boolean" },
@@ -105005,12 +105050,15 @@ async function pull2(argv2, deps2 = {}) {
     });
   }
   if (out !== "-") assertPathOutsidePrivateState(path53.resolve(out));
+  if (values["from-host"] && (values.remote !== void 0 || isDocRouteKey2(key4))) {
+    throw new CliError("USAGE", "--from-host reads blobs from a bound hosted checkout; it cannot be used with --remote or a .md key");
+  }
   const bundle = await openBundle(values.dir, await resolveRemoteFlag(values.remote, values.dir));
   const mode = resolveMode(values);
   const streamMode = out === "-";
   const docRoute = isDocRouteKey2(key4);
   const runToTarget = async () => {
-    const result3 = docRoute ? await pullDoc(bundle, key4, values.remote) : await pullBlob(bundle, key4, values.remote);
+    const result3 = values["from-host"] ? await pullHostedBlob(bundle, key4, out, !!values.json, deps2) : docRoute ? await pullDoc(bundle, key4, values.remote) : await pullBlob(bundle, key4, values.remote);
     const receipt5 = { pull: "read", key: key4, ...result3.fields, out };
     const version5 = result3.fields.version;
     const fileHint = streamMode ? "<file>" : out;
@@ -105055,6 +105103,8 @@ var init_pull = __esm({
     init_doc();
     init_egress();
     init_command_text();
+    init_binding2();
+    init_checkout_connection();
     PULL_USAGE = `superbee pull \u2014 pull a doc or blob's bytes out of the store (the reverse of 'promote')
 
 Usage:
@@ -105070,6 +105120,12 @@ Routes by the --doc-key's target (case-insensitive), symmetric with 'promote':
   Any OTHER key is a BLOB: raw bytes, self-verified against the returned version (a real integrity
   check \u2014 catches transport corruption over --remote too, not just a local tautology).
 
+In a hosted checkout, the default still reads the local working copy; its blob content_type is
+inferred from the filename. --from-host explicitly reads the bound host's current blob instead,
+using its stored content type and version together as the byte-read pin. It requires sign-in as
+the checkout's person and refuses a changed pin rather than mixing observations or falling back
+to local bytes. It does not sync, place host changes, or send edits; only --out is written.
+
 --out - streams raw bytes to stdout; the receipt goes to STDERR instead (the byte stream stays
 pure), and any error also routes to stderr in that mode. --out <path> writes the file and prints the
 receipt to stdout. A destination path landing INSIDE an open LOCAL bundle carries a loud 'warning'
@@ -105082,6 +105138,8 @@ Options:
   --doc-key <key>       Source key (required)
   --out <path>          Write bytes to this local path
   --out -               Stream raw bytes to stdout; receipt -> stderr
+  --from-host           Read a blob's verified bytes and stored MIME from a bound hosted checkout's
+                         host (not documents, a local/Git bundle, or --remote)
   --dir <path>          Bundle directory (default: discovered from the cwd)
   --remote <url>        Talk to a wire-protocol server instead of a local bundle (mutually
                          exclusive with --dir; remote access is always explicit)
@@ -105181,7 +105239,7 @@ Options:
 });
 
 // ../cli/src/commands/delete.ts
-import { homedir as homedir30 } from "node:os";
+import { homedir as homedir31 } from "node:os";
 import { parseArgs as parseArgs18 } from "node:util";
 function isDocRouteKey3(key4) {
   return key4.toLowerCase().endsWith(".md");
@@ -105223,7 +105281,7 @@ async function deleteCommand(argv2, deps2 = {}) {
     );
   }
   const remote = await resolveRemoteFlag(values.remote, values.dir);
-  const home2 = deps2.hosted?.auth?.home ?? deps2.home ?? homedir30(), cwd = deps2.cwd ?? deps2.hosted?.cwd ?? process.cwd();
+  const home2 = deps2.hosted?.auth?.home ?? deps2.home ?? homedir31(), cwd = deps2.cwd ?? deps2.hosted?.cwd ?? process.cwd();
   if (deps2.home !== void 0 && deps2.hosted?.auth !== void 0 && deps2.home !== deps2.hosted.auth.home) throw new CliError("USAGE", "offline admission and hosted delivery must use the same private-state home");
   if (!remote && !isDocRouteKey3(key4)) {
     const pending = await admitOfflineBlob({ operation: "delete", key: key4, ...values.dir === void 0 ? {} : { dir: values.dir }, ...rawExpected === void 0 ? {} : { expectedVersion: rawExpected.trim() }, home: home2, cwd });
@@ -110003,7 +110061,7 @@ var init_local_operation_file = __esm({
 });
 
 // ../cli/src/operation-plugins.ts
-import { homedir as homedir31 } from "node:os";
+import { homedir as homedir32 } from "node:os";
 import path56 from "node:path";
 function refusal3(reason) {
   return new CliError("USAGE", `Local operation registration refused (${reason}).`, { details: { reason }, help: "Register a reviewed self-contained local operation bundle, preview its digest, then explicitly accept that digest. Changed code requires registration and rebinding." });
@@ -110034,17 +110092,17 @@ function parse3(raw) {
   if (total > DEFAULT_SITE_CAPABILITY_LIMITS.maxTotalDescriptorBytes) throw refusal3("operation_descriptor_limit");
   return m;
 }
-async function registerOperationPlugin(folder, accept, input = homedir31()) {
+async function registerOperationPlugin(folder, accept, input = homedir32()) {
   const result3 = await lifecycle3.register(folder, accept, input);
   return { operation: "op register", ...receipt3(result3.snapshot), accepted: result3.accepted, ..."generation" in result3 ? { generation: result3.generation } : {} };
 }
-async function listOperationPlugins(input = homedir31()) {
+async function listOperationPlugins(input = homedir32()) {
   return { operation: "op registered", plugins: (await lifecycle3.list(input)).map((s) => ({ ...receipt3(s), generation: s.pointer.generation })) };
 }
-async function removeOperationPlugin(id, input = homedir31()) {
+async function removeOperationPlugin(id, input = homedir32()) {
   return { operation: "op unregister", plugin: id, removed: await lifecycle3.remove(id, input) };
 }
-async function selectLocalOperation(id, input = homedir31()) {
+async function selectLocalOperation(id, input = homedir32()) {
   const s = await lifecycle3.select(id, input, (m, key4) => m.superbeeLocalOperations.operations.some((o) => o.id === key4));
   if (!s) return void 0;
   const d = s.manifest.superbeeLocalOperations, op2 = d.operations.find((o) => o.id === id);
@@ -110222,7 +110280,7 @@ var init_local_operation_child = __esm({
 import { spawn as spawn5 } from "node:child_process";
 import { createHash as createHash19, randomUUID as randomUUID7 } from "node:crypto";
 import { lstat as lstat10, mkdir as mkdir4, realpath as realpath9, readdir as readdir7, writeFile as writeFile3 } from "node:fs/promises";
-import { homedir as homedir32 } from "node:os";
+import { homedir as homedir33 } from "node:os";
 import path57 from "node:path";
 async function localFileBytes(file2, maximum) {
   try {
@@ -110239,10 +110297,10 @@ async function ordinaryDirectory(value, home2, bundle) {
   if (!status2.isDirectory() || status2.isSymbolicLink() || canonical2 !== value || canonical2 === bundle || within(bundle, canonical2)) throw refuse2("ordinary_output_directory_required");
   return canonical2;
 }
-async function localBundle(dir, cwd = process.cwd(), home2 = homedir32()) {
+async function localBundle(dir, cwd = process.cwd(), home2 = homedir33()) {
   const target3 = await resolveLocalBundleTarget(dir, cwd);
   assertBundleOutsidePrivateState(target3.canonicalRoot, home2);
-  const facts = await bundleHomeAt(target3.canonicalRoot, { home: typeof home2 === "string" ? home2 : homedir32() });
+  const facts = await bundleHomeAt(target3.canonicalRoot, { home: typeof home2 === "string" ? home2 : homedir33() });
   if (facts.home === "hosted") throw refuse2("hosted_local_execution_not_supported");
   if (process.platform !== "darwin" && process.platform !== "linux") throw refuse2("unsupported_supervision_platform");
   return target3.canonicalRoot;
@@ -110307,7 +110365,7 @@ async function probeToolVersion(file2, versionFlag, versionChannel) {
     child.once("exit", (code3) => void finish(code3 === 0 ? void 0 : "tool_probe_failed"));
   });
 }
-async function bindLocalOperation(operation, bundle, config2, accept, home2 = homedir32()) {
+async function bindLocalOperation(operation, bundle, config2, accept, home2 = homedir33()) {
   if (await localBundle(bundle, process.cwd(), home2) !== bundle) throw refuse2("canonical_bundle_required");
   const selection = await selectLocalOperation(operation, home2);
   if (!selection) throw refuse2("unknown_local_operation");
@@ -110433,7 +110491,7 @@ async function stopGroup(pid, grace) {
   return false;
 }
 async function runLocalOperation(operation, bundle, bindingId, input, options = {}) {
-  const home2 = options.home ?? homedir32();
+  const home2 = options.home ?? homedir33();
   if (options.exportOutput !== void 0 && (!record15(options.exportOutput) || typeof options.exportOutput.role !== "string" || !key3.test(options.exportOutput.role) || typeof options.exportOutput.path !== "string" || !options.exportOutput.path || options.exportOutput.path.includes("\0"))) throw refuse2("export_output_argument");
   if (!/^[0-9a-f-]{36}$/.test(bindingId)) throw refuse2("binding_id");
   const binding2 = JSON.parse(await readUserStateFile(home2, path57.join(canonicalUserStateDir(home2), "local-operation-bindings", `${bindingId}.json`), 65536));
@@ -110769,7 +110827,7 @@ var init_transport = __esm({
 
 // ../cli/src/source-local/run.ts
 import { realpath as realpath10 } from "node:fs/promises";
-import { homedir as homedir33 } from "node:os";
+import { homedir as homedir34 } from "node:os";
 function publicSourceReason(reason) {
   return reason === void 0 ? void 0 : typeof reason === "string" && PUBLIC_SOURCE_REASONS.has(reason) ? reason : "unclassified";
 }
@@ -110777,7 +110835,7 @@ async function context(feedId, dir, stateInput) {
   const bundle = await openBundle(dir);
   const root = await realpath10(bundle.root);
   assertPathOutsidePrivateState(root);
-  if (await bindingForPath(homedir33(), root)) throw sourceRefusal("hosted_target_unsupported");
+  if (await bindingForPath(homedir34(), root)) throw sourceRefusal("hosted_target_unsupported");
   const [registry2, edition, feed] = await Promise.all([loadKinds(bundle), readBundleOkfVersion2(bundle), readDoc2(bundle, feedId)]);
   if (feed.frontmatter.type !== "Source Feed" || typeof feed.frontmatter.connector !== "string") throw sourceRefusal("feed_invalid");
   const parsed2 = parseConnectorDoc(await readDoc2(bundle, feed.frontmatter.connector), { kinds: registry2 });
@@ -110999,7 +111057,7 @@ var init_run = __esm({
 
 // ../cli/src/source-local/snapshot.ts
 import { realpath as realpath11 } from "node:fs/promises";
-import { homedir as homedir34 } from "node:os";
+import { homedir as homedir35 } from "node:os";
 import { dirname as dirname5, resolve as resolve2 } from "node:path";
 async function guardFile(file2, home2, root) {
   const selected2 = resolve2(file2);
@@ -111031,7 +111089,7 @@ function safeError(error51) {
 async function context2(feed, dir, home2) {
   const bundle = await openBundle(dir), root = await realpath11(bundle.root);
   assertPathOutsidePrivateState(root, home2);
-  if (await bindingForPath(typeof home2 === "string" ? home2 : homedir34(), root)) throw sourceRefusal("hosted_target_unsupported");
+  if (await bindingForPath(typeof home2 === "string" ? home2 : homedir35(), root)) throw sourceRefusal("hosted_target_unsupported");
   const [registry2, edition, source2] = await Promise.all([loadKinds(bundle), readBundleOkfVersion2(bundle), readDocVersioned2(bundle, feed)]);
   const okfVersion = edition === "0.2" ? "0.2" : "0.1";
   const bound2 = bindSnapshotSource(source2.doc, registry2, { okfVersion });
@@ -111054,7 +111112,7 @@ function assertBinding(current, binding2) {
 }
 async function bindLocalSnapshot(feed, options, deps2 = {}) {
   try {
-    const home2 = deps2.stateInput ?? homedir34(), c = await context2(feed, options.dir, home2);
+    const home2 = deps2.stateInput ?? homedir35(), c = await context2(feed, options.dir, home2);
     const current = await readSourceEnvelope(sourceStateFile(c.root, feed), home2);
     assertBinding(current, c.binding);
     const preview4 = {
@@ -111125,7 +111183,7 @@ async function prepared(feed, options, home2) {
 }
 async function runLocalSnapshot(feed, options, deps2 = {}) {
   try {
-    const home2 = deps2.stateInput ?? homedir34();
+    const home2 = deps2.stateInput ?? homedir35();
     if (!options.accept) {
       const p = await prepared(feed, options, home2);
       return {
@@ -111225,7 +111283,7 @@ function selectionMap(value) {
 }
 async function checkLocalSnapshot(file2, options, deps2 = {}) {
   try {
-    const home2 = deps2.stateInput ?? homedir34();
+    const home2 = deps2.stateInput ?? homedir35();
     const snapshot3 = decodeSnapshot(await selectedBytes(file2, SNAPSHOT_MAX_BYTES, home2));
     let raw;
     try {
@@ -112173,7 +112231,7 @@ var init_status = __esm({
 
 // ../cli/src/commands/status.ts
 import { parseArgs as parseArgs29 } from "node:util";
-import { homedir as homedir35 } from "node:os";
+import { homedir as homedir36 } from "node:os";
 import { realpath as realpath12 } from "node:fs/promises";
 function cap3(rows, limit) {
   const bounded2 = limit > 0 ? rows.slice(0, limit) : rows;
@@ -112358,7 +112416,7 @@ async function status(argv2, deps2 = {}) {
     limit = Number(raw);
   }
   const remote = await resolveRemoteFlag(values.remote, values.dir);
-  const home2 = deps2.home ?? homedir35();
+  const home2 = deps2.home ?? homedir36();
   const hosted = remote ? null : await hostedCheckoutAt(values.dir, home2).catch(() => null);
   if (!remote && !hosted) await (deps2.autoPull ?? maybeAutoPull2)(values.dir);
   const now = (deps2.now ?? (() => /* @__PURE__ */ new Date()))();
@@ -144602,10 +144660,10 @@ Use \`superbee mcp status --host <id>\` to verify it and restart the host after
 });
 
 // ../cli/src/hosted/served-bundle.ts
-import { homedir as homedir36 } from "node:os";
+import { homedir as homedir37 } from "node:os";
 import path59 from "node:path";
 async function servedBundle(bundle, options = {}) {
-  const home2 = options.home ?? homedir36();
+  const home2 = options.home ?? homedir37();
   let root;
   try {
     root = (await resolveLocalBundleTarget(bundle.root)).canonicalRoot;
@@ -144783,7 +144841,7 @@ var init_served_bundle = __esm({
 });
 
 // ../cli/src/hosted/reachable.ts
-import { homedir as homedir37 } from "node:os";
+import { homedir as homedir38 } from "node:os";
 async function hostedBundleRows(client, target3, home2) {
   const listing = readBundleListing(await client.bundles());
   const folders = await liveCheckoutFolders(home2, target3);
@@ -144832,7 +144890,7 @@ async function reachableHostedBundles(options) {
   }
 }
 async function askHosts(options) {
-  const home2 = options.auth?.home ?? options.home ?? homedir37();
+  const home2 = options.auth?.home ?? options.home ?? homedir38();
   const base = options.auth ?? defaultHostedAuthDeps(home2);
   const live = [];
   for (const target3 of await candidateHosts(home2)) {
@@ -144904,7 +144962,7 @@ var init_folder_answered = __esm({
 });
 
 // ../cli/src/mcp-workspace-resolver.ts
-import { homedir as homedir38 } from "node:os";
+import { homedir as homedir39 } from "node:os";
 function createCatalogMcpWorkspaceResolver(options = {}) {
   const listEntries = options.listEntries ?? listCatalogEntries;
   const resolveEntry2 = options.resolveEntry ?? resolveCatalogEntry;
@@ -144913,7 +144971,7 @@ function createCatalogMcpWorkspaceResolver(options = {}) {
   const deriveName = options.deriveName ?? deriveBundleDisplayName;
   const reachable = options.reachable ?? (() => reachableHostedBundles({ budgetMs: MCP_HOSTED_BUDGET_MS, ...options.home !== void 0 ? { home: options.home } : {} }));
   const now = options.now ?? Date.now;
-  const home2 = options.hosted?.auth?.home ?? options.home ?? homedir38();
+  const home2 = options.hosted?.auth?.home ?? options.home ?? homedir39();
   const select = async (selector2, during) => {
     const entry = await resolveEntry2(selector2, options.home);
     const value = await during(entry.locator.path);
@@ -146490,7 +146548,7 @@ var init_host_command = __esm({
 
 // ../cli/src/mcp-install-targets.ts
 import { readFileSync as readFileSync12 } from "node:fs";
-import { homedir as homedir39 } from "node:os";
+import { homedir as homedir40 } from "node:os";
 function resolveMcpInstallTarget(value) {
   return TARGET_BY_NAME.get(value.trim().toLowerCase());
 }
@@ -146706,7 +146764,7 @@ function selectMcpRegistration(entries) {
   return entries.find((entry) => entry.name === CURRENT_MCP_REGISTRATION) ?? LEGACY_MCP_REGISTRATIONS.map((name) => entries.find((entry) => entry.name === name)).find(Boolean);
 }
 function environment(deps2) {
-  return deps2.environment ?? { home: homedir39(), env: process.env, platform: process.platform };
+  return deps2.environment ?? { home: homedir40(), env: process.env, platform: process.platform };
 }
 function inspectMcpHost(target3, deps2 = {}) {
   const input = environment(deps2);
@@ -146862,7 +146920,7 @@ var init_mcp_install_targets = __esm({
 // ../cli/src/mcp-registration.ts
 import { execFileSync as execFileSync3 } from "node:child_process";
 import { readFileSync as readFileSync13, realpathSync as realpathSync14 } from "node:fs";
-import { homedir as homedir40 } from "node:os";
+import { homedir as homedir41 } from "node:os";
 function isRecord18(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -146870,7 +146928,7 @@ function own5(value, key4) {
   return Object.prototype.hasOwnProperty.call(value, key4) ? value[key4] : void 0;
 }
 function defaultEnvironment() {
-  return { home: homedir40(), env: process.env, platform: process.platform };
+  return { home: homedir41(), env: process.env, platform: process.platform };
 }
 function isMissing(error51) {
   return isRecord18(error51) && own5(error51, "code") === "ENOENT";
@@ -147881,7 +147939,7 @@ var init_skill_compatibility = __esm({
 // ../cli/src/commands/skill.ts
 import { createHash as createHash20 } from "node:crypto";
 import { existsSync as existsSync12, lstatSync as lstatSync8, readFileSync as readFileSync14, readdirSync as readdirSync4, realpathSync as realpathSync15, renameSync as renameSync6, rmSync as rmSync5, rmdirSync as rmdirSync3 } from "node:fs";
-import { homedir as homedir41 } from "node:os";
+import { homedir as homedir42 } from "node:os";
 import { dirname as dirname6, join as join17 } from "node:path";
 import { parseArgs as parseArgs32 } from "node:util";
 function listFilesRelative(dir, prefix = "") {
@@ -147947,7 +148005,7 @@ function skillTargetsForName(dirName, scope, deps2 = {}) {
       opencode: paths.join(cwd, ".claude", "skills", dirName)
     };
   }
-  const home2 = deps2.home ?? homedir41();
+  const home2 = deps2.home ?? homedir42();
   const env = deps2.env ?? process.env;
   return {
     claude: paths.join(resolveHostConfigRoot(HOST_CONFIG_ROOTS.claude, home2, env, platform), "skills", dirName),
@@ -149114,7 +149172,7 @@ import {
   unlinkSync as unlinkSync3,
   writeFileSync as writeFileSync5
 } from "node:fs";
-import { homedir as homedir42 } from "node:os";
+import { homedir as homedir43 } from "node:os";
 import { isAbsolute as isAbsolute3, join as join18 } from "node:path";
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
@@ -149645,7 +149703,7 @@ function transitionMatchingActiveToCooldown(home2, token, now) {
 }
 function runPassiveUpdateOrientation(deps2 = {}) {
   if (currentDistribution()?.updatesEnabled === false) return void 0;
-  const home2 = deps2.home ?? homedir42();
+  const home2 = deps2.home ?? homedir43();
   const runningVersion = deps2.runningVersion ?? staticBuildIdentity().package.version;
   const now = deps2.now ?? (() => /* @__PURE__ */ new Date());
   const initial = inspectUpdateCache({ home: home2, runningVersion, now: now() });
@@ -149700,7 +149758,7 @@ function runPassiveUpdateOrientation(deps2 = {}) {
 async function runUpdateRefreshWorker(token, deps2 = {}) {
   if (currentDistribution()?.updatesEnabled === false) return;
   if (!isUpdateLeaseToken(token)) return;
-  const home2 = deps2.home ?? homedir42();
+  const home2 = deps2.home ?? homedir43();
   const runningVersion = deps2.runningVersion ?? staticBuildIdentity().package.version;
   const now = deps2.now ?? (() => /* @__PURE__ */ new Date());
   if (!parseStrictSemver(runningVersion) || !activeLeaseAuthority(home2, token, now())) return;
@@ -150412,7 +150470,7 @@ ASLITE_NO_UPDATE_CHECK, NO_UPDATE_NOTIFIER, or CI.
 
 // ../cli/src/commands/session-start.ts
 import { realpath as realpath14 } from "node:fs/promises";
-import { homedir as homedir43 } from "node:os";
+import { homedir as homedir44 } from "node:os";
 import { parseArgs as parseArgs34 } from "node:util";
 import path61 from "node:path";
 async function bundleFreshness(root, userHome, now, signIn, env) {
@@ -150432,7 +150490,7 @@ async function bundleFreshness(root, userHome, now, signIn, env) {
   return { home: "local", freshness: "local only" };
 }
 async function otherCatalogBundles(currentRoot, options = {}) {
-  const userHome = options.home ?? homedir43();
+  const userHome = options.home ?? homedir44();
   const now = options.now ?? /* @__PURE__ */ new Date();
   const deadline = Date.now() + (options.deadlineMs ?? SESSION_START_PROBE_DEADLINE_MS);
   const current = currentRoot === null ? null : await realpath14(currentRoot).catch(() => path61.resolve(currentRoot));
@@ -150473,7 +150531,7 @@ async function sessionBundleRoot(dir, known) {
   }
 }
 async function hostedSessionStartPull(binding2, budgetMs, deps2 = {}) {
-  const home2 = deps2.sync?.auth?.home ?? homedir43();
+  const home2 = deps2.sync?.auth?.home ?? homedir44();
   const state = await sessionPullState(binding2, budgetMs, home2, deps2);
   const counts = typeof state === "object" ? state : {};
   const pulledAt = (await readFreshness(home2, binding2.checkout_id).catch(() => null))?.pulled_at ?? null;
@@ -150942,12 +151000,12 @@ __export(bundle_retire_exports, {
   bundleRetire: () => bundleRetire
 });
 import { randomUUID as randomUUID9 } from "node:crypto";
-import { homedir as homedir44 } from "node:os";
+import { homedir as homedir45 } from "node:os";
 import { parseArgs as parseArgs35 } from "node:util";
 async function bundleRetire(argv2, partial2 = {}) {
   const deps2 = {
     stdout: partial2.stdout ?? ((text7) => void process.stdout.write(text7)),
-    auth: partial2.auth ?? defaultHostedAuthDeps(homedir44()),
+    auth: partial2.auth ?? defaultHostedAuthDeps(homedir45()),
     ...partial2.fetch ? { fetch: partial2.fetch } : {},
     terminal: partial2.terminal ?? processTerminal()
   };
@@ -151496,7 +151554,7 @@ var init_catalog_guard = __esm({
 
 // ../cli/src/commands/catalog.ts
 import { parseArgs as parseArgs38 } from "node:util";
-import { homedir as homedir45 } from "node:os";
+import { homedir as homedir46 } from "node:os";
 function entryReceipt(entry) {
   return {
     schema_version: 1,
@@ -151531,7 +151589,7 @@ function requestsPathField(argv2) {
 async function catalogInner(argv2, deps2) {
   const stdout = deps2.stdout ?? ((s) => void process.stdout.write(s));
   const cwd = deps2.cwd ?? (() => process.cwd());
-  const home2 = deps2.home ?? homedir45;
+  const home2 = deps2.home ?? homedir46;
   const parsed2 = parseSelectorOrUsage(
     () => parseArgs38({
       args: argv2,
@@ -152115,11 +152173,11 @@ __export(view_content_exports, {
   viewUpdate: () => viewUpdate
 });
 import { lstat as lstat11, realpath as realpath15, writeFile as writeFile4 } from "node:fs/promises";
-import { homedir as homedir46 } from "node:os";
+import { homedir as homedir47 } from "node:os";
 import path63 from "node:path";
 import { parseArgs as parseArgs41 } from "node:util";
 function homeOf(deps2) {
-  return deps2.hosted?.auth?.home ?? homedir46();
+  return deps2.hosted?.auth?.home ?? homedir47();
 }
 async function locate(sub, rawId, dir, deps2) {
   const target3 = await resolveLocalBundleTarget(dir, deps2.cwd ?? process.cwd());
@@ -153144,11 +153202,11 @@ var init_setup_plan = __esm({
 });
 
 // ../cli/src/commands/setup-hosted.ts
-import { homedir as homedir47 } from "node:os";
+import { homedir as homedir48 } from "node:os";
 import { parseArgs as parseArgs43 } from "node:util";
 async function setupHosted(argv2, partial2 = {}) {
   const stdout = partial2.stdout ?? ((text7) => void process.stdout.write(text7));
-  const auth = partial2.auth ?? defaultHostedAuthDeps(homedir47());
+  const auth = partial2.auth ?? defaultHostedAuthDeps(homedir48());
   const { values } = parseLeafOrUsage(
     () => parseArgs43({
       args: argv2,
@@ -153292,7 +153350,7 @@ import {
   stat as stat8,
   unlink as unlink11
 } from "node:fs/promises";
-import { homedir as homedir48 } from "node:os";
+import { homedir as homedir49 } from "node:os";
 import { dirname as dirname7, join as join19 } from "node:path";
 function errno3(error51) {
   return error51?.code;
@@ -153412,7 +153470,7 @@ async function preflightLegacy(input) {
 function blockedSource(error51) {
   return error51 instanceof UnsafeMigrationSource ? { reason: `legacy operational state at ${error51.display} ${error51.detail}`, command: error51.command } : { reason: "legacy operational state is not safe to migrate automatically", command: "superbee setup" };
 }
-async function inspectUserStateMigration(input = homedir48()) {
+async function inspectUserStateMigration(input = homedir49()) {
   if (staticBuildIdentity().package.name === LEGACY_BRIDGE_PACKAGE_NAME) {
     return { state: "ready", reason: "the separately published Aslite bridge retains its legacy state root", records: 0 };
   }
@@ -153591,7 +153649,7 @@ function receipt4(status2, changed, records) {
     next: { command: "superbee setup" }
   };
 }
-async function migrateUserState(input = homedir48(), hooks = {}) {
+async function migrateUserState(input = homedir49(), hooks = {}) {
   if (staticBuildIdentity().package.name === LEGACY_BRIDGE_PACKAGE_NAME) {
     throw new CliError("NOT_IMPLEMENTED", "state migration is available only from the Superbee package", { help: "npm install -g superbee" });
   }
@@ -153704,7 +153762,7 @@ var init_user_state_migration = __esm({
 });
 
 // ../cli/src/commands/setup.ts
-import { homedir as homedir49 } from "node:os";
+import { homedir as homedir50 } from "node:os";
 import { parseArgs as parseArgs44 } from "node:util";
 function setupHost(value) {
   return MCP_INSTALL_TARGETS.find((target3) => target3.id === value)?.id;
@@ -153906,7 +153964,7 @@ async function setup(argv2, injected = {}) {
   const deps2 = {
     stdout,
     cwd: injected.cwd ?? (() => process.cwd()),
-    home: injected.home ?? homedir49,
+    home: injected.home ?? homedir50,
     inspectDistribution: injected.inspectDistribution ?? (() => resolvePersistentInstallAuthority()),
     inspectSkill: injected.inspectSkill ?? ((selectedScope) => inspectSkillStatus(selectedScope)),
     inspectHook: injected.inspectHook ?? ((selectedScope) => inspectHookStatus(selectedScope)),
@@ -154171,13 +154229,13 @@ var init_loopback = __esm({
 });
 
 // ../cli/src/commands/hosted-auth.ts
-import { homedir as homedir50 } from "node:os";
+import { homedir as homedir51 } from "node:os";
 import { parseArgs as parseArgs45 } from "node:util";
 function commandDeps(deps2) {
   return {
     stdout: deps2.stdout ?? ((text7) => void process.stdout.write(text7)),
     stderr: deps2.stderr ?? ((text7) => void process.stderr.write(text7)),
-    auth: deps2.auth ?? defaultHostedAuthDeps(homedir50())
+    auth: deps2.auth ?? defaultHostedAuthDeps(homedir51())
   };
 }
 function iso(ms) {
@@ -154787,14 +154845,14 @@ var init_node = __esm({
 
 // ../cli/src/commands/export.ts
 import { randomBytes as randomBytes11 } from "node:crypto";
-import { homedir as homedir51 } from "node:os";
+import { homedir as homedir52 } from "node:os";
 import { link as link3, lstat as lstat13, mkdir as mkdir6, open as open4, readdir as readdir10, realpath as realpath16, rename as rename3, rm as rm2, unlink as unlink13 } from "node:fs/promises";
 import path65 from "node:path";
 import { parseArgs as parseArgs46 } from "node:util";
 function exportDeps(partial2) {
   return {
     stdout: partial2.stdout ?? ((text7) => void process.stdout.write(text7)),
-    auth: partial2.auth ?? defaultHostedAuthDeps(homedir51()),
+    auth: partial2.auth ?? defaultHostedAuthDeps(homedir52()),
     cwd: partial2.cwd ?? process.cwd(),
     ...partial2.fetch ? { fetch: partial2.fetch } : {}
   };
@@ -155951,14 +156009,14 @@ var init_checkout_adopt = __esm({
 });
 
 // ../cli/src/commands/checkout.ts
-import { homedir as homedir52 } from "node:os";
+import { homedir as homedir53 } from "node:os";
 import { lstat as lstat15, mkdir as mkdir7, readFile as readFile5, readdir as readdir11, realpath as realpath18, rmdir as rmdir3, stat as stat9, unlink as unlink14 } from "node:fs/promises";
 import path67 from "node:path";
 import { parseArgs as parseArgs47 } from "node:util";
 function checkoutDeps(partial2) {
   return {
     stdout: partial2.stdout ?? ((text7) => void process.stdout.write(text7)),
-    auth: partial2.auth ?? defaultHostedAuthDeps(homedir52()),
+    auth: partial2.auth ?? defaultHostedAuthDeps(homedir53()),
     cwd: partial2.cwd ?? process.cwd(),
     ...partial2.fetch ? { fetch: partial2.fetch } : {}
   };
@@ -156668,7 +156726,7 @@ __export(op_local_exports, {
 });
 import { parseArgs as parseArgs48 } from "node:util";
 import path68 from "node:path";
-import { homedir as homedir53 } from "node:os";
+import { homedir as homedir54 } from "node:os";
 async function localOp(argv2, deps2) {
   const sub = argv2[0];
   if (!["register", "registered", "unregister", "bind", "list", "run"].includes(sub ?? "")) throw new CliError("USAGE", "Unknown local operation command.");
@@ -156693,7 +156751,7 @@ async function localOp(argv2, deps2) {
     deps2.stdout(renderUsage(OP_USAGE));
     return;
   }
-  const cwd = deps2.cwd ?? process.cwd(), home2 = deps2.hosted?.auth?.home ?? homedir53();
+  const cwd = deps2.cwd ?? process.cwd(), home2 = deps2.hosted?.auth?.home ?? homedir54();
   if (values.local !== true) throw new CliError("USAGE", "Local operation registration and binding require --local.");
   if (!["register", "registered", "unregister", "list", "bind", "run"].includes(sub ?? "")) throw new CliError("USAGE", "Unknown local operation command.");
   if (values.input !== void 0) throw new CliError("USAGE", "Local operations require --input-file.");
@@ -156761,7 +156819,7 @@ var init_op_local = __esm({
 });
 
 // ../cli/src/commands/op.ts
-import { homedir as homedir54 } from "node:os";
+import { homedir as homedir55 } from "node:os";
 import path69 from "node:path";
 import { parseArgs as parseArgs49 } from "node:util";
 async function op(argv2, deps2 = {}) {
@@ -156782,7 +156840,7 @@ async function op(argv2, deps2 = {}) {
 }
 async function homeOf2(dir, deps2) {
   const target3 = await resolveLocalBundleTarget(dir, deps2.cwd ?? process.cwd());
-  const facts = await bundleHomeAt(target3.canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir54() });
+  const facts = await bundleHomeAt(target3.canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir55() });
   return facts.home === "hosted" ? { home: "hosted", binding: facts.binding } : { home: facts.home };
 }
 function noHostOperations(home2) {
@@ -157083,7 +157141,7 @@ Options:
 });
 
 // ../cli/src/hosted/inbox-session.ts
-import { homedir as homedir55 } from "node:os";
+import { homedir as homedir56 } from "node:os";
 function helpFor(command) {
   return command === "notify" ? commandFragment`${cliInvocation()} notify --help` : commandFragment`${cliInvocation()} inbox --help`;
 }
@@ -157095,7 +157153,7 @@ async function checkoutOf(scope, deps2) {
     if (scope.dir === void 0 && error51 instanceof CliError && error51.code === "NOT_FOUND") return null;
     throw error51;
   }
-  const facts = await bundleHomeAt(canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir55() });
+  const facts = await bundleHomeAt(canonicalRoot, { home: deps2.hosted?.auth?.home ?? homedir56() });
   return facts.home === "hosted" ? facts.binding : null;
 }
 async function openInboxSession(command, scope, deps2, resumeFor, options = {}) {
@@ -158986,7 +159044,7 @@ var init_publish_staged = __esm({
 // ../cli/src/commands/publish.ts
 import { randomUUID as randomUUID10 } from "node:crypto";
 import { lstat as lstat16, readFile as readFile6, realpath as realpath19, unlink as unlink15 } from "node:fs/promises";
-import { homedir as homedir56 } from "node:os";
+import { homedir as homedir57 } from "node:os";
 import path72 from "node:path";
 import { parseArgs as parseArgs53 } from "node:util";
 function publishDeps(partial2) {
@@ -158994,7 +159052,7 @@ function publishDeps(partial2) {
     stdout: partial2.stdout ?? ((text7) => void process.stdout.write(text7)),
     stderr: partial2.stderr ?? ((text7) => void process.stderr.write(text7)),
     ...partial2.sleep ? { sleep: partial2.sleep } : {},
-    auth: partial2.auth ?? defaultHostedAuthDeps(homedir56()),
+    auth: partial2.auth ?? defaultHostedAuthDeps(homedir57()),
     cwd: partial2.cwd ?? process.cwd(),
     ...partial2.fetch ? { fetch: partial2.fetch } : {}
   };
@@ -159632,12 +159690,12 @@ Examples:
 });
 
 // ../cli/src/commands/access.ts
-import { homedir as homedir57 } from "node:os";
+import { homedir as homedir58 } from "node:os";
 import { parseArgs as parseArgs54 } from "node:util";
 function accessDeps(partial2) {
   return {
     stdout: partial2.stdout ?? ((text7) => void process.stdout.write(text7)),
-    auth: partial2.auth ?? defaultHostedAuthDeps(homedir57()),
+    auth: partial2.auth ?? defaultHostedAuthDeps(homedir58()),
     ...partial2.fetch ? { fetch: partial2.fetch } : {}
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.4-pre.10",
+  "version": "0.4.4-pre.11",
   "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

@@ -370,6 +370,15 @@ superbee sync --resolve keep --doc index.md     # the next sync sends yours over
 
 ## Ordinary files (SVGs, images, `data/*.json`)
 
+`pull --doc-key <key> --out <path> --from-host --dir <checkout>` reads one blob's bytes and stored
+content type directly from the bound host, using its version and content type together as the
+read pin. It checks the checkout's signed-in person and workspace and verifies the returned bytes.
+A changed pin, denied access or unsupported host refuses without falling back to local bytes.
+It does not sync, send edits or refresh the working copy; only the requested output is written.
+Use `--out -` for raw stdout with the receipt on stderr. Ordinary `pull` still reads the local
+working copy, including unsent edits; its content type is inferred from the filename. The explicit
+host option is for blobs only and cannot be combined with `--remote`.
+
 Files other than `.md` documents are ordinary files. Sync sends and refreshes only **tracked**
 ones. Treat an edit to a tracked file as a publish: the next `superbee sync` sends it to the hosted
 bundle for everyone.