@hellolynk-ai/workbuddy-mcp 0.0.0-stage → 0.3.97

package/hellolynk-client-pack-pin.json

@@ -0,0 +1,4 @@
+{
+  "contract": "hellolynk-client-npm-pack-pin-v1",
+  "manifestSha256": "ec5f18618a17fe5c1a07de4f2a01ab3b9d195ff3ebab4a2ac789da0e7c234ca8"
+}

package/integrations/workbuddy/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hellolynk-ai/workbuddy-mcp",
+  "version": "0.3.97",
+  "private": true,
+  "type": "module",
+  "description": "WorkBuddy one-click bridge for local HelloLynk Messaging.",
+  "scripts": {
+    "smoke": "node test/workbuddy-stdio-smoke.mjs",
+    "test": "node test/workbuddy-stdio-smoke.mjs && node test/local-web-smoke.mjs && node test/local-web-package-smoke.mjs && node test/workbench-process-smoke.mjs && node test/pending-consumption-smoke.mjs && node test/pending-loopback-smoke.mjs && node --test test/model-inbox-caller.test.mjs test/proxy-reply.test.mjs test/native-task-store.test.mjs test/native-task-worker.test.mjs test/origin-routes.test.mjs test/native-task-scheduled.test.mjs test/native-task-debug-startup.test.mjs test/native-task-service-registration.test.mjs test/native-task-upgrade.test.mjs",
+    "smoke:web": "node test/local-web-smoke.mjs",
+    "build:immutable-package": "node scripts/build-local-web-package.mjs --output workbuddy-immutable-package",
+    "smoke:pending": "node test/pending-consumption-smoke.mjs",
+    "smoke:pending:loopback": "node test/pending-loopback-smoke.mjs"
+  }
+}

package/integrations/workbuddy/server/host-lifecycle.mjs

@@ -0,0 +1,249 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { launchPinnedNeutralHostBootstrap } from "../../../clients/core/hellolynk-neutral-host-launcher.mjs";
+
+const RUNNER_RELATIVE = "runtime/neutral-host-bootstrap.mjs";
+const LOCK_STALE_MS = 10_000;
+const SAFE_RELATIVE = /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.(?:cjs|mjs|ps1)$/;
+const REQUIRED_RUNTIME_RECORDS = Object.freeze([
+  "neutral-host-bootstrap.mjs",
+  "neutral-host-release-loader.mjs",
+  "neutral-host-release-entry.mjs",
+  "core/hellolynk-host-protected-store.mjs",
+  "core/hellolynk-local-data-migration.mjs",
+  "core/hellolynk-local-data-protection.mjs",
+  "core/hellolynk-local-identity-trust.mjs",
+  "core/hellolynk-neutral-host-installation-store.mjs",
+  "core/hellolynk-neutral-host-assembly.mjs",
+  "core/hellolynk-neutral-host-process.mjs",
+  "core/hellolynk-neutral-host-workbench-read-model.mjs",
+  "core/hellolynk-workbench-action-grants.mjs",
+  "platform/windows/hellolynk-host-protected-store.ps1",
+  "platform/windows/hellolynk-local-data-key.ps1",
+  "workbench/contract.mjs",
+]);
+
+export async function launchWorkBuddyNeutralHost(binding, options = {}) {
+  const launch = normalizeLaunchBinding(binding, options);
+  await verifyPinnedBootstrap(launch);
+  const lockPath = path.join(
+    launch.runtimeRoot,
+    "neutral-host",
+    `${tupleDigest(launch)}.workbuddy-launch.lock`,
+  );
+  await ensureSafeDirectory(launch.runtimeRoot, true);
+  await ensureSafeDirectory(path.dirname(lockPath), true);
+  const wait = options.wait || delay;
+  const deadline = Date.now() + bounded(options.lockTimeoutMs, 15_000, 500, 60_000);
+  let ownsLock = false;
+  while (Date.now() < deadline) {
+    try {
+      await fs.mkdir(lockPath, { mode: 0o700 });
+      await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({
+        contract: "hellolynk-workbuddy-host-launch-lock-v1",
+        pid: process.pid,
+        createdAtMs: Date.now(),
+      })}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      ownsLock = true;
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw codeError("neutral_workbuddy_launch_failed");
+      await ensureSafeDirectory(lockPath, false);
+      await reclaimDeadLock(lockPath).catch(() => false);
+      await wait(50);
+    }
+  }
+  if (!ownsLock) throw codeError("neutral_workbuddy_launch_lock_timeout");
+  try {
+    await launchPinnedNeutralHostBootstrap(launch, {
+      storeRoot: launch.storeRoot,
+      ...(options.spawnRunner ? { spawnRunner: options.spawnRunner } : {}),
+      ...(options.bootstrapObservationMs !== undefined ? { bootstrapObservationMs: options.bootstrapObservationMs } : {}),
+      ...(options.bootstrapFailureObservationMs !== undefined ? { bootstrapFailureObservationMs: options.bootstrapFailureObservationMs } : {}),
+      ...(options.bootstrapFailureDeadlineMs !== undefined ? { bootstrapFailureDeadlineMs: options.bootstrapFailureDeadlineMs } : {}),
+      env: options.env || process.env,
+    });
+    return Object.freeze({ started: true, owner: "workbuddy_mcp_process" });
+  } finally {
+    // Only the lock created by this process is cleaned up. The neutral Host owns
+    // its own process lifetime and stops after the last attachment lease ends.
+    await fs.rm(path.join(lockPath, "owner.json"), { force: true }).catch(() => {});
+    await fs.rmdir(lockPath).catch(() => {});
+  }
+}
+
+export async function verifyPinnedBootstrap(binding, options = {}) {
+  const launch = normalizeLaunchBinding(binding, options);
+  const pinPath = path.join(launch.releaseRoot, "runtime", "neutral-host-release-pin.json");
+  const manifestPath = path.join(launch.releaseRoot, "runtime", "neutral-host-release-manifest.json");
+  const [pinBytes, manifestBytes] = await Promise.all([
+    readSafeFile(pinPath, 16 * 1024),
+    readSafeFile(manifestPath, 256 * 1024),
+  ]);
+  const pin = parseJson(pinBytes);
+  const manifest = parseJson(manifestBytes);
+  if (!plain(pin) || !exactKeys(pin, ["contract", "manifestSha256"])
+    || pin.contract !== "hellolynk-neutral-host-release-pin-v1"
+    || pin.manifestSha256 !== launch.releaseManifestSha256
+    || sha256(manifestBytes) !== launch.releaseManifestSha256
+    || !plain(manifest) || manifest.contract !== "hellolynk-neutral-host-release-manifest-v1"
+    || !exactKeys(manifest, ["contract", "entry", "files"])
+    || !Array.isArray(manifest.files) || manifest.files.length < 3 || manifest.files.length > 256
+    || manifest.entry !== "neutral-host-release-entry.mjs") {
+    throw codeError("neutral_workbuddy_runner_integrity_invalid");
+  }
+  const records = new Map();
+  const resolvedPaths = new Map();
+  for (const item of manifest.files) {
+    if (!plain(item) || !exactKeys(item, ["path", "sha256"])
+      || !/^[a-f0-9]{64}$/.test(String(item.sha256 || ""))) fail();
+    const recordPath = String(item.path || "");
+    const file = resolveManifestFile(launch, recordPath);
+    const canonical = canonicalPath(file);
+    if (records.has(recordPath) || resolvedPaths.has(canonical)) fail();
+    const bytes = await readSafeFile(file, 2 * 1024 * 1024).catch(() => fail());
+    if (sha256(bytes) !== item.sha256) fail();
+    const record = Object.freeze({ recordPath, file, bytes });
+    records.set(recordPath, record);
+    resolvedPaths.set(canonical, record);
+  }
+  for (const required of REQUIRED_RUNTIME_RECORDS) {
+    if (!records.has(required)) fail();
+  }
+  if (!samePath(records.get("neutral-host-bootstrap.mjs").file, launch.bootstrapPath)
+    || !records.has(manifest.entry)) fail();
+  verifyStaticImportClosure(records, resolvedPaths, launch.releaseRoot);
+  return Object.freeze({ ok: true, bootstrapPath: launch.bootstrapPath, verifiedFileCount: records.size });
+}
+
+function resolveManifestFile(launch, recordPath) {
+  if (!SAFE_RELATIVE.test(recordPath) || recordPath.split("/").includes("..")) fail();
+  const releaseFile = recordPath.startsWith("release/");
+  const base = releaseFile ? launch.releaseRoot : path.join(launch.releaseRoot, "runtime");
+  const relative = releaseFile ? recordPath.slice("release/".length) : recordPath;
+  return insideRoot(base, relative);
+}
+
+function verifyStaticImportClosure(records, resolvedPaths, releaseRoot) {
+  const importPattern = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)["'](\.{1,2}\/[^"']+)["']/g;
+  for (const record of records.values()) {
+    if (!record.file.endsWith(".mjs")) continue;
+    const source = record.bytes.toString("utf8");
+    importPattern.lastIndex = 0;
+    for (let match = importPattern.exec(source); match; match = importPattern.exec(source)) {
+      const imported = path.resolve(path.dirname(record.file), ...match[1].split("/"));
+      if (!inside(releaseRoot, imported) || !resolvedPaths.has(canonicalPath(imported))) fail();
+    }
+  }
+}
+
+function insideRoot(root, relative) {
+  const result = path.resolve(root, ...relative.split("/"));
+  if (!inside(root, result)) fail();
+  return result;
+}
+
+function inside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return Boolean(relative) && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+
+function normalizeLaunchBinding(value, options) {
+  if (!plain(value)) throw codeError("neutral_workbuddy_launch_configuration_required");
+  const runtimeRoot = absolute(value.runtimeRoot);
+  const releaseRoot = absolute(value.releaseRoot);
+  const profileManifestPath = absolute(value.profileManifestPath);
+  const releaseManifestSha256 = String(value.releaseManifestSha256 || "");
+  if (value.runnerRelativePath !== RUNNER_RELATIVE || !/^[a-f0-9]{64}$/.test(releaseManifestSha256)) {
+    throw codeError("neutral_workbuddy_launch_configuration_required");
+  }
+  const derivedStoreRoot = path.dirname(runtimeRoot);
+  if (path.basename(runtimeRoot).toLowerCase() !== "runtime") {
+    throw codeError("neutral_workbuddy_launch_configuration_required");
+  }
+  const storeRoot = options.storeRoot ? absolute(options.storeRoot) : derivedStoreRoot;
+  if (!samePath(storeRoot, derivedStoreRoot)
+    || !samePath(profileManifestPath, path.join(storeRoot, "profile-manifest-v1.json"))) {
+    throw codeError("neutral_workbuddy_launch_configuration_required");
+  }
+  return Object.freeze({
+    runtimeRoot, releaseRoot, profileManifestPath, releaseManifestSha256, storeRoot,
+    runnerRelativePath: RUNNER_RELATIVE,
+    bootstrapPath: path.join(releaseRoot, ...RUNNER_RELATIVE.split("/")),
+    region: safeId(value.region), principalId: safeId(value.principalId),
+    delegateId: safeId(value.delegateId), hostInstallationId: safeId(value.hostInstallationId),
+    profileId: safeId(value.profileId), adapterId: value.adapterId === "workbuddy" ? "workbuddy" : fail(),
+    version: Number(value.version), scopes: Object.freeze([...(value.scopes || [])].map(String)),
+  });
+}
+
+async function readSafeFile(file, maximum) {
+  await assertNoReparseAncestors(file);
+  let handle;
+  try { handle = await fs.open(file, "r"); }
+  catch { throw codeError("neutral_workbuddy_runner_unavailable"); }
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.nlink !== 1n || before.size > BigInt(maximum)) fail();
+    const bytes = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    if (!sameIdentity(before, after)) fail();
+    return bytes;
+  } catch (error) {
+    if (/^neutral_workbuddy_/.test(String(error?.code || ""))) throw error;
+    throw codeError("neutral_workbuddy_runner_integrity_invalid");
+  } finally { await handle.close().catch(() => {}); }
+}
+
+async function assertNoReparseAncestors(target) {
+  const resolved = path.resolve(target);
+  const parsed = path.parse(resolved);
+  let cursor = parsed.root;
+  for (const segment of path.relative(parsed.root, resolved).split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, segment);
+    let metadata;
+    try { metadata = await fs.lstat(cursor); }
+    catch { throw codeError("neutral_workbuddy_runner_unavailable"); }
+    if (metadata.isSymbolicLink()) throw codeError("neutral_workbuddy_runner_integrity_invalid");
+  }
+}
+
+async function ensureSafeDirectory(target, create) {
+  if (create) await fs.mkdir(target, { recursive: true, mode: 0o700 });
+  const metadata = await fs.lstat(target).catch(() => null);
+  if (!metadata?.isDirectory() || metadata.isSymbolicLink()) {
+    throw codeError("neutral_workbuddy_launch_configuration_required");
+  }
+}
+
+async function reclaimDeadLock(lockPath) {
+  const metadata = await fs.lstat(lockPath);
+  let owner = null;
+  try { owner = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf8")); }
+  catch { return false; }
+  const pid = Number(owner?.pid);
+  if (Date.now() - metadata.mtimeMs <= LOCK_STALE_MS || (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))) return false;
+  await fs.rm(path.join(lockPath, "owner.json"), { force: true });
+  await fs.rmdir(lockPath).catch(() => {});
+  return true;
+}
+
+function tupleDigest(value) { return sha256(`${value.region}\0${value.principalId}\0${value.hostInstallationId}`); }
+function sha256(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
+function parseJson(value) { try { return JSON.parse(value); } catch { fail(); } }
+function sameIdentity(left, right) { return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.nlink === right.nlink; }
+function processAlive(pid) { try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } }
+function safeId(value) { const result = String(value || ""); if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]{2,198}$/.test(result)) fail(); return result; }
+function absolute(value) { const result = String(value || ""); if (!path.isAbsolute(result) || path.resolve(result) !== result) fail(); return result; }
+function samePath(left, right) { return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right; }
+function canonicalPath(value) { const result = path.resolve(value); return process.platform === "win32" ? result.toLowerCase() : result; }
+function exactKeys(value, expected) {
+  const actual = Object.keys(value).sort(); const wanted = [...expected].sort();
+  return actual.length === wanted.length && actual.every((item, index) => item === wanted[index]);
+}
+function bounded(value, fallback, minimum, maximum) { const result = Number(value ?? fallback); return Number.isSafeInteger(result) && result >= minimum && result <= maximum ? result : fallback; }
+function plain(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+function delay(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+function fail() { throw codeError("neutral_workbuddy_runner_integrity_invalid"); }
+function codeError(code) { const error = new Error(code); error.code = code; return error; }

package/integrations/workbuddy/server/mcp-proxy.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { readClientAccount } from "../../../clients/core/hellolynk-client-account.mjs";
+import { workbenchConnectionError, isWorkbenchConnectionRequired } from "../../../clients/core/hellolynk-workbench-connection.mjs";
+import { fileURLToPath } from "node:url";
+import { startInstalledClientUpdate } from "../../../clients/core/hellolynk-client-update-entry.mjs";
+import {
+  createWorkBuddyNeutralHostAdapter,
+  createWorkBuddyProtectedBindingProvider,
+  validateWorkBuddyProtectedBinding,
+} from "./neutral-host-adapter.mjs";
+import {
+  runWorkBuddyStdioMcpServer,
+  toWorkBuddyPublicErrorCode,
+  projectPendingMessages,
+} from "./mcp-server.mjs";
+import { launchWorkBuddyNeutralHost } from "./host-lifecycle.mjs";
+import { startWorkBuddyNativeTaskWorker } from "./native-task-worker.mjs";
+import { prepareWorkBuddyOriginHook, workBuddyOriginInbox, markWorkBuddyActiveScope } from "./origin-routes.mjs";
+import { readWorkBuddyModelCaller } from "./model-call-origin.mjs";
+import { nativeReplyRouteLocation } from "../../../clients/core/hellolynk-native-reply-routes.mjs";
+import { defaultNeutralHostStoreRoot } from "../../../clients/core/hellolynk-neutral-host-installation-store.mjs";
+import { startRecordedWorkBuddyNativeService, workBuddyMcpTrustRequests } from "./native-task-service-registration.mjs";
+import { closeWorkBuddyWorkbench, launchWorkBuddyWorkbench } from "./workbench-candidate.mjs";
+import { serveWorkBuddyWorkbench, serveWorkBuddyWorkbenchService } from "./workbench-process.mjs";
+export { launchDetachedWorkBuddyWorkbench, handoffWorkBuddyWorkbench, configureWorkBuddyNativeTaskService } from "./workbench-process.mjs";
+export { registerWorkBuddyNativeMcp } from "./native-task-mcp-registration.mjs";
+
+function createProxyAdapter(options) {
+  if (options.adapter) return options.adapter;
+  const updating = options.createAdapter ? Promise.resolve(null) : startInstalledClientUpdate({
+    client: "workbuddy", packageRoot: fileURLToPath(new URL("../../../", import.meta.url)), storeRoot: options.storeRoot,
+  });
+  const connect = async () => {
+    await updating;
+    const connected = await (options.createAdapter || createWorkBuddyNeutralHostAdapter)({
+    capabilityProvider: options.capabilityProvider || createWorkBuddyProtectedBindingProvider(options),
+    discoverHost: options.discoverHost,
+    requestHost: options.requestHost,
+    hostLauncher: options.hostLauncher || ((binding) => launchWorkBuddyNeutralHost(binding, {
+      storeRoot: path.dirname(binding.runtimeRoot),
+      ...(options.spawnRunner ? { spawnRunner: options.spawnRunner } : {}),
+    })),
+    adapterInstanceId: options.adapterInstanceId,
+    heartbeatMs: options.heartbeatMs,
+    });
+    try { await markWorkBuddyActiveScope(workBuddyOriginInbox(options.storeRoot || defaultNeutralHostStoreRoot()), await connected.getNativeTaskScope()); }
+    catch { /* Model calls still require matching current-account hook evidence. */ }
+    return connected;
+  };
+  const adapter = recoveringAdapter(connect, toWorkBuddyPublicErrorCode, [
+    "hostStatus", "getNativeTaskScope", "readBundle", "readUnreadCount", "markMessageRead", "deleteRead", "saveContact",
+    "deleteContact", "setAutonomousSendAuthorization", "listAuthorizedContacts", "listAuthorizedInboxMessages", "modelInbox", "listPendingMessages", "claimMessage", "claimBatch", "inboxBatch", "readAuthorizedInboxMessage", "listAuthorizedContactRequests", "readAuthorizedContactRequest", "sendAuthorizedMessage", "replyAuthorizedMessage",
+    "issueRetryGrant", "retryOutgoing", "requestHumanSend", "getHumanSendStatus",
+    "readWorkbenchSnapshot", "readWorkbenchChanges", "issueWorkbenchActionGrant", "executeWorkbenchCommand",
+  ], () => readClientAccount("workbuddy", options.storeRoot).revision);
+  // Opening the page is owned by its separate service. Do not cold-start the
+  // Host inside WorkBuddy's short-lived conversation Job just for discovery.
+  return adapter;
+}
+
+export async function runWorkBuddyWorkbenchProcess(options = {}) {
+  return serveWorkBuddyWorkbench({ ...options, adapter: createProxyAdapter(options) });
+}
+export async function runWorkBuddyWorkbenchService(options = {}) {
+  return serveWorkBuddyWorkbenchService({ ...options, adapter: createProxyAdapter(options) });
+}
+
+// Installed outside WorkBuddy's conversation Job. No AI task has to remain
+// running to receive the next message; this is an ordinary program listener.
+export async function runWorkBuddyNativeTaskService(options = {}) {
+  if (!process.env.HELLOLYNK_WORKBUDDY_DEBUG_ENDPOINT && !options.nativeTaskOptions?.debugEndpoint) throw codeError("workbuddy_native_debug_enable_required");
+  const adapter = createProxyAdapter(options);
+  // Only the installed service (package bootstrap) registers the hook that
+  // records which conversation sent each message; tests opt in explicitly.
+  const origin = options.originHook ? await prepareWorkBuddyOriginHook({
+    storeRoot: options.storeRoot || defaultNeutralHostStoreRoot(), ...(options.originHook === true ? {} : options.originHook) }) : null;
+  // The installed service approves the trust request its own release's
+  // update left; a service without a pinned release approves nothing.
+  const mcpTrust = options.root && options.expectedManifestSha256 ? workBuddyMcpTrustRequests({ storeRoot: options.storeRoot,
+    root: options.root, expectedManifestSha256: options.expectedManifestSha256 }) : null;
+  const worker = startWorkBuddyNativeTaskWorker({ adapter, ...(origin ? { originInbox: origin.inbox } : {}), mcpTrust, ...options.nativeTaskOptions });
+  const keepAlive = setInterval(() => {}, 60_000);
+  const stop = () => { void worker.close(); };
+  options.signal?.addEventListener("abort", stop, { once: true });
+  if (options.signal?.aborted) stop();
+  try {
+    await worker.ready;
+    if (!options.signal?.aborted) await new Promise((resolve) => options.signal?.addEventListener("abort", resolve, { once: true }));
+  } finally { options.signal?.removeEventListener("abort", stop); clearInterval(keepAlive); await worker.close(); await adapter.close(); }
+}
+
+// Called only by a native background shell in a dedicated HelloLynk task.
+// This process performs no model calls and emits no message content or identity.
+export async function waitForWorkBuddyPending(options = {}) {
+  if (options.signal?.aborted) return { pending: false, cancelled: true };
+  const adapter = options.adapter || await (options.createAdapter || createWorkBuddyNeutralHostAdapter)({
+    capabilityProvider: options.capabilityProvider || createWorkBuddyProtectedBindingProvider(options),
+    discoverHost: options.discoverHost, requestHost: options.requestHost,
+    hostLauncher: options.hostLauncher || ((binding) => launchWorkBuddyNeutralHost(binding, { storeRoot: path.dirname(binding.runtimeRoot) })),
+  });
+  try {
+    while (!options.signal?.aborted) {
+      const messages = projectPendingMessages(await adapter.listPendingMessages());
+      if (options.signal?.aborted) break;
+      if (messages.length) {
+        (options.output || process.stdout).write("HELLOLYNK_INBOX_PENDING\n");
+        return { pending: true };
+      }
+      try { await (options.wait || delay)(5000, undefined, { signal: options.signal }); }
+      catch (error) { if (options.signal?.aborted && error?.name === "AbortError") break; throw error; }
+    }
+    return { pending: false, cancelled: true };
+  } finally { await adapter.close(); }
+}
+
+export async function runWorkBuddyMcpProxy(options = {}) {
+  const capabilityProvider = options.capabilityProvider || (!options.adapter && !options.createAdapter
+    ? createWorkBuddyProtectedBindingProvider(options) : null);
+  const adapter = createProxyAdapter({ ...options, ...(capabilityProvider ? { capabilityProvider } : {}) });
+  const originInbox = workBuddyOriginInbox(options.storeRoot || defaultNeutralHostStoreRoot());
+  // Publish the account before tools become available and their PreToolUse hook
+  // runs. Reading the protected binding does not start a Host or receiver.
+  try {
+    const binding = capabilityProvider ? validateWorkBuddyProtectedBinding(await capabilityProvider()) : null;
+    const scope = binding ? { runtimeRoot: binding.runtimeRoot, adapterId: "workbuddy", region: binding.region,
+      principalId: binding.principalId, delegateId: binding.delegateId } : await options.adapter?.getNativeTaskScope?.();
+    if (scope) await markWorkBuddyActiveScope(originInbox, scope);
+  } catch { /* Unconnected discovery remains available; scoped calls fail closed. */ }
+  let recordedService = { configured: false, status: "not_installed" };
+  if (options.nativeTasks !== false) {
+    try { recordedService = await (options.startRecordedNativeService || startRecordedWorkBuddyNativeService)({ storeRoot: options.storeRoot }); }
+    catch (error) {
+      recordedService = { configured: true, status: "unavailable", errorCode: /^workbuddy_[a-z_]{1,100}$/.test(error?.code || "") ? error.code : "workbuddy_native_service_start_failed" };
+    }
+  }
+  // CDP must be explicitly enabled for this desktop profile. Existing MCP
+  // discovery alone must not cold-start a Host in a short-lived native Job.
+  const nativeEnabled = !recordedService.configured && options.nativeTasks !== false && Boolean(options.nativeTaskOptions?.debugEndpoint || process.env.HELLOLYNK_WORKBUDDY_DEBUG_ENDPOINT);
+  const nativeTasks = nativeEnabled ? startWorkBuddyNativeTaskWorker({ adapter, ...options.nativeTaskOptions }) : null;
+  try {
+    return await (options.runServer || runWorkBuddyStdioMcpServer)({
+      adapter,
+      getModelInboxCaller: options.getModelInboxCaller || (async (meta, name, args) => {
+        const scope = await adapter.getNativeTaskScope();
+        await markWorkBuddyActiveScope(originInbox, scope);
+        return readWorkBuddyModelCaller(originInbox,
+          meta, name, args, nativeReplyRouteLocation(scope).scopeHash);
+      }),
+      nativeTaskStatus: () => nativeTasks?.status || (recordedService.configured ? { status: recordedService.status, ...(recordedService.errorCode ? { errorCode: recordedService.errorCode } : {}) } : { status: "disabled", errorCode: "workbuddy_native_debug_enable_required" }),
+      // The resulting MCP response contains only a clean loopback URL. The
+      // one explicit top-level navigation receives a short local session.
+      openLocalWeb: options.openLocalWeb || (() => launchWorkBuddyWorkbench({ adapter })),
+      input: options.input || process.stdin,
+      output: options.output || process.stdout,
+    });
+  } finally {
+    try { await nativeTasks?.close(); await closeWorkBuddyWorkbench(); }
+    finally { await adapter.close(); }
+  }
+}
+
+function recoveringAdapter(connectAdapter, publicCode, methods, accountRevision = () => null) {
+  let current = null;
+  let pending = null;
+  let closed = false;
+  let revision = accountRevision();
+  let accountReset = null;
+  async function connect() {
+    if (closed) throw codeError("neutral_host_adapter_closed");
+    const nextRevision = accountRevision();
+    if (!accountReset && revision !== nextRevision) {
+      const old = current, previousFlight = pending;
+      current = null; pending = null; revision = nextRevision;
+      accountReset = Promise.resolve().then(async () => {
+        const previous = await previousFlight?.catch(() => null);
+        await (previous || old)?.close?.().catch(() => {});
+      }).finally(() => { accountReset = null; });
+    }
+    if (accountReset) await accountReset;
+    if (revision !== accountRevision()) throw codeError("workbench_account_changed");
+    if (current && current.state !== "dead" && current.state !== "closed") return current;
+    if (current) await current.close().catch(() => {});
+    current = null;
+    if (!pending) {
+      const generation = revision;
+      const flight = Promise.resolve().then(connectAdapter).then(async (value) => {
+        if (closed || generation !== accountRevision()) {
+          await value?.close?.().catch(() => {});
+          throw codeError("neutral_host_adapter_closed");
+        }
+        current = value;
+        return value;
+      }, (error) => { throw isWorkbenchConnectionRequired(error) ? workbenchConnectionError(error) : codeError(publicCode(error)); }).finally(() => { if (pending === flight) pending = null; });
+      pending = flight;
+    }
+    return pending;
+  }
+  const facade = {
+    async close() {
+      if (closed) return;
+      closed = true;
+      const value = current;
+      current = null;
+      await value?.close?.().catch(() => {});
+    },
+  };
+  const workbenchPair = methods.includes("issueWorkbenchActionGrant")
+    && methods.includes("executeWorkbenchCommand");
+  for (const method of methods) {
+    if (workbenchPair && ["issueWorkbenchActionGrant", "executeWorkbenchCommand"].includes(method)) continue;
+    facade[method] = async (...args) => (await connect())[method](...args);
+  }
+  if (workbenchPair) {
+    const issueWorkbenchActionGrant = async function issueWorkbenchActionGrant(command) {
+      const target = await connect();
+      requireWorkbenchPair(target);
+      return target.issueWorkbenchActionGrant(command);
+    };
+    facade.executeWorkbenchCommand = async function executeWorkbenchCommand(command, context) {
+      const target = await connect();
+      requireWorkbenchPair(target);
+      return target.executeWorkbenchCommand(command, context);
+    };
+    Object.defineProperty(facade, "issueWorkbenchActionGrant", {
+      enumerable: true,
+      get() { return !current || hasWorkbenchPair(current) ? issueWorkbenchActionGrant : undefined; },
+    });
+  }
+  return Object.freeze(facade);
+
+  function requireWorkbenchPair(value) {
+    if (!hasWorkbenchPair(value)) throw codeError("neutral_host_workbench_action_grant_unavailable");
+  }
+
+  function hasWorkbenchPair(value) {
+    return typeof value?.issueWorkbenchActionGrant === "function"
+      && value.issueWorkbenchActionGrant.length >= 1
+      && typeof value.executeWorkbenchCommand === "function"
+      && value.executeWorkbenchCommand.length >= 2;
+  }
+}
+
+export function formatWorkBuddyProxyError(error) {
+  return `${JSON.stringify({ ok: false, error: toWorkBuddyPublicErrorCode(error) })}\n`;
+}
+
+function codeError(code) { const error = new Error(code); error.code = code; return error; }
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  runWorkBuddyMcpProxy().catch((error) => {
+    process.stderr.write(formatWorkBuddyProxyError(error));
+    process.exitCode = 1;
+  });
+}