@hellolynk-ai/codex-plugin 0.0.0-stage → 0.2.100

package/plugins/hellolynk-codex/runtime/core/hellolynk-workbench-action-grants.mjs

@@ -0,0 +1,457 @@
+import crypto from "node:crypto";
+
+export const HELLOLYNK_WORKBENCH_ACTION_GRANT_TTL_MS = 60_000;
+export const HELLOLYNK_WORKBENCH_ACTION_GRANT_CAPACITY = 1_024;
+
+const MIN_TTL_MS = 30_000;
+const MAX_TTL_MS = 90_000;
+const MAX_CAPACITY = 4_096;
+const MAX_IDENTIFIER_BYTES = 256;
+const MAX_TARGET_BYTES = 1_024;
+const MAX_PAYLOAD_BYTES = 256 * 1_024;
+const MAX_PAYLOAD_DEPTH = 64;
+const TOKEN_BYTES = 32;
+const TOKEN_PREFIX = "hwag_";
+const TOKEN_PATTERN = /^hwag_[A-Za-z0-9_-]{43}$/;
+const ISSUE_KEYS = Object.freeze([
+  "adapterId",
+  "adapterInstanceId",
+  "capabilityId",
+  "delegateId",
+  "expectedRevision",
+  "hostGeneration",
+  "idempotencyKey",
+  "payload",
+  "principalId",
+  "target",
+  "tool",
+]);
+const CONSUME_KEYS = Object.freeze([...ISSUE_KEYS, "actionGrant"].sort());
+const BINDING_FIELDS = Object.freeze([
+  "hostGeneration",
+  "principalId",
+  "capabilityId",
+  "adapterId",
+  "delegateId",
+  "adapterInstanceId",
+  "tool",
+  "target",
+  "payloadDigest",
+  "expectedRevision",
+  "idempotencyKey",
+]);
+const AUTHORIZED_RESULT = Object.freeze({ authorized: true });
+const KNOWN_FAILED_OUTCOME = "known-failed";
+const UNKNOWN_OUTCOME = "unknown";
+const REGISTRY_INTERNALS = new WeakMap();
+
+export class HelloLynkWorkbenchActionGrantError extends Error {
+  constructor(code, statusCode, outcome = null) {
+    super(code);
+    this.name = "HelloLynkWorkbenchActionGrantError";
+    this.code = code;
+    this.statusCode = statusCode;
+    if (outcome != null) this.outcome = outcome;
+  }
+}
+
+/*
+ * This registry is deliberately process-local. Recreating the Host creates an
+ * empty registry, so a grant can never survive a Host restart. The raw token and
+ * original payload are never retained: the Map key is SHA-256(token), while the
+ * record contains only normalized authority bindings and a payload digest.
+ */
+export function createHelloLynkWorkbenchActionGrantRegistry(options = {}) {
+  const clock = normalizeClock(options.clock);
+  const randomBytes = normalizeRandomBytes(options.randomBytes);
+  const ttlMs = normalizeTtl(options.ttlMs);
+  const capacity = normalizeCapacity(options.capacity);
+  const grants = new Map();
+  const tombstones = new Map();
+  let lastObservedNowMs = null;
+
+  function issue(value) {
+    const binding = normalizeBinding(value, ISSUE_KEYS, "issue");
+    const nowMs = monotonicNow();
+    pruneExpired(nowMs);
+    if (grants.size >= capacity) {
+      throw failure("host_workbench_action_grant_capacity_exceeded", 503);
+    }
+
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const tokenBytes = readRandomBytes(randomBytes);
+      const actionGrant = `${TOKEN_PREFIX}${tokenBytes.toString("base64url")}`;
+      if (!TOKEN_PATTERN.test(actionGrant)) continue;
+      const tokenDigest = digestText(actionGrant);
+      if (grants.has(tokenDigest) || tombstones.has(tokenDigest)) continue;
+
+      const expiresAtMs = nowMs + ttlMs;
+      if (!Number.isSafeInteger(expiresAtMs)) {
+        throw failure("host_workbench_action_grant_clock_invalid", 500);
+      }
+      grants.set(tokenDigest, Object.freeze({ ...binding, expiresAtMs }));
+      return Object.freeze({ actionGrant, expiresAtMs });
+    }
+
+    throw failure("host_workbench_action_grant_generation_failed", 500);
+  }
+
+  function consume(value) {
+    // Extract and burn a well-formed, known token before validating any other
+    // field. A malformed binding therefore cannot be retried with the same grant.
+    // A successful burn becomes an outcome-unknown tombstone synchronously,
+    // before the caller can enter an attachment check or an async handler.
+    const rawToken = ownDataProperty(value, "actionGrant");
+    const tokenDigest = typeof rawToken === "string" && TOKEN_PATTERN.test(rawToken)
+      ? digestText(rawToken)
+      : null;
+    if (!tokenDigest) throw invalidGrant(KNOWN_FAILED_OUTCOME);
+
+    const record = grants.get(tokenDigest);
+    if (!record) {
+      const tombstone = tombstones.get(tokenDigest);
+      // A syntactically valid but unrecognized token may be a consumed token
+      // whose bounded tombstone has expired or been evicted. We cannot prove
+      // that its write never started, so the safe public outcome is unknown.
+      throw invalidGrant(tombstone?.outcome ?? UNKNOWN_OUTCOME);
+    }
+    grants.delete(tokenDigest);
+
+    let binding;
+    try {
+      binding = normalizeBinding(value, CONSUME_KEYS, "consume");
+    } catch {
+      rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, record.expiresAtMs);
+      throw invalidGrant(KNOWN_FAILED_OUTCOME);
+    }
+
+    let nowMs;
+    try {
+      nowMs = monotonicNow();
+    } catch {
+      // This record was still active and has not crossed the Host execution
+      // boundary, so a clock failure can be classified as known-failed.
+      rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, record.expiresAtMs);
+      throw invalidGrant(KNOWN_FAILED_OUTCOME);
+    }
+    if (record.expiresAtMs <= nowMs) {
+      rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, nowMs + ttlMs);
+      throw invalidGrant(KNOWN_FAILED_OUTCOME);
+    }
+    for (const field of BINDING_FIELDS) {
+      if (record[field] !== binding[field]) {
+        rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, nowMs + ttlMs);
+        throw invalidGrant(KNOWN_FAILED_OUTCOME);
+      }
+    }
+    rememberTombstone(tokenDigest, UNKNOWN_OUTCOME, nowMs + ttlMs);
+    return AUTHORIZED_RESULT;
+  }
+
+  function prune() {
+    return pruneExpired(monotonicNow());
+  }
+
+  function monotonicNow() {
+    let nowMs;
+    try {
+      nowMs = readNow(clock);
+    } catch (error) {
+      failClosedActiveGrants();
+      throw error;
+    }
+    if (lastObservedNowMs != null && nowMs < lastObservedNowMs) {
+      // Keep the high-water mark: the registry remains fail-closed until the
+      // clock catches up, instead of silently extending outstanding TTLs.
+      failClosedActiveGrants();
+      throw failure("host_workbench_action_grant_clock_invalid", 500);
+    }
+    lastObservedNowMs = nowMs;
+    return nowMs;
+  }
+
+  function pruneExpired(nowMs) {
+    let pruned = 0;
+    for (const [tokenDigest, grant] of grants) {
+      if (grant.expiresAtMs <= nowMs) {
+        grants.delete(tokenDigest);
+        rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, nowMs + ttlMs);
+        pruned += 1;
+      }
+    }
+    for (const [tokenDigest, tombstone] of tombstones) {
+      if (tombstone.expiresAtMs <= nowMs) {
+        tombstones.delete(tokenDigest);
+        pruned += 1;
+      }
+    }
+    return pruned;
+  }
+
+  function failClosedActiveGrants() {
+    const fallbackExpiry = (lastObservedNowMs ?? 0) + ttlMs;
+    for (const [tokenDigest, grant] of grants) {
+      rememberTombstone(
+        tokenDigest,
+        KNOWN_FAILED_OUTCOME,
+        Math.max(grant.expiresAtMs, fallbackExpiry),
+      );
+    }
+    grants.clear();
+  }
+
+  function rememberTombstone(tokenDigest, outcome, expiresAtMs) {
+    if (tombstones.has(tokenDigest)) tombstones.delete(tokenDigest);
+    while (tombstones.size >= capacity) {
+      tombstones.delete(tombstones.keys().next().value);
+    }
+    tombstones.set(tokenDigest, Object.freeze({ outcome, expiresAtMs }));
+  }
+
+  const registry = Object.freeze({
+    issue,
+    consume,
+    prune,
+    get size() {
+      pruneExpired(monotonicNow());
+      return grants.size;
+    },
+    get capacity() {
+      return capacity;
+    },
+    get ttlMs() {
+      return ttlMs;
+    },
+  });
+  REGISTRY_INTERNALS.set(registry, Object.freeze({ grants, rememberTombstone, tombstones }));
+  return registry;
+}
+
+export function rejectConsumedHelloLynkWorkbenchActionGrant(registry, actionGrant) {
+  const internal = REGISTRY_INTERNALS.get(registry);
+  if (!internal) throw failure("host_workbench_action_grant_registry_invalid", 500);
+  if (typeof actionGrant !== "string" || !TOKEN_PATTERN.test(actionGrant)) return false;
+  const tokenDigest = digestText(actionGrant);
+  const tombstone = internal.tombstones.get(tokenDigest);
+  if (!tombstone || tombstone.outcome !== UNKNOWN_OUTCOME) return false;
+  internal.rememberTombstone(tokenDigest, KNOWN_FAILED_OUTCOME, tombstone.expiresAtMs);
+  return true;
+}
+
+export function revokeHelloLynkWorkbenchActionGrants(registry, value) {
+  const internal = REGISTRY_INTERNALS.get(registry);
+  if (!internal) throw failure("host_workbench_action_grant_registry_invalid", 500);
+  const hasAttachment = value && Object.hasOwn(value, "adapterInstanceId");
+  try {
+    assertExactObject(
+      value,
+      hasAttachment
+        ? ["adapterInstanceId", "capabilityId", "hostGeneration"]
+        : ["capabilityId", "hostGeneration"],
+    );
+    const authority = {
+      hostGeneration: boundedString(value.hostGeneration, MAX_IDENTIFIER_BYTES),
+      capabilityId: boundedString(value.capabilityId, MAX_IDENTIFIER_BYTES),
+      ...(hasAttachment ? {
+        adapterInstanceId: boundedString(value.adapterInstanceId, MAX_IDENTIFIER_BYTES),
+      } : {}),
+    };
+    let revoked = 0;
+    for (const [tokenDigest, grant] of internal.grants) {
+      if (grant.hostGeneration === authority.hostGeneration
+        && grant.capabilityId === authority.capabilityId
+        && (!hasAttachment || grant.adapterInstanceId === authority.adapterInstanceId)) {
+        internal.grants.delete(tokenDigest);
+        internal.rememberTombstone(
+          tokenDigest,
+          KNOWN_FAILED_OUTCOME,
+          grant.expiresAtMs,
+        );
+        revoked += 1;
+      }
+    }
+    return revoked;
+  } catch (error) {
+    if (error instanceof HelloLynkWorkbenchActionGrantError) throw error;
+    throw failure("host_workbench_action_grant_binding_invalid", 400);
+  }
+}
+
+function normalizeBinding(value, expectedKeys, operation) {
+  try {
+    assertExactObject(value, expectedKeys);
+    return Object.freeze({
+      hostGeneration: boundedString(value.hostGeneration, MAX_IDENTIFIER_BYTES),
+      principalId: boundedString(value.principalId, MAX_IDENTIFIER_BYTES),
+      capabilityId: boundedString(value.capabilityId, MAX_IDENTIFIER_BYTES),
+      adapterId: boundedString(value.adapterId, MAX_IDENTIFIER_BYTES),
+      delegateId: boundedString(value.delegateId, MAX_IDENTIFIER_BYTES),
+      adapterInstanceId: boundedString(value.adapterInstanceId, MAX_IDENTIFIER_BYTES),
+      tool: boundedString(value.tool, MAX_IDENTIFIER_BYTES),
+      target: boundedString(value.target, MAX_TARGET_BYTES),
+      payloadDigest: digestPayload(value.payload),
+      expectedRevision: value.expectedRevision == null
+        ? null
+        : boundedString(value.expectedRevision, MAX_IDENTIFIER_BYTES),
+      idempotencyKey: boundedString(value.idempotencyKey, MAX_IDENTIFIER_BYTES),
+    });
+  } catch {
+    if (operation === "consume") throw invalidGrant();
+    throw failure("host_workbench_action_grant_binding_invalid", 400);
+  }
+}
+
+function assertExactObject(value, expectedKeys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("invalid");
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw new TypeError("invalid");
+  if (Object.getOwnPropertySymbols(value).length !== 0) throw new TypeError("invalid");
+  const actual = Object.keys(value).sort();
+  if (actual.length !== expectedKeys.length) throw new TypeError("invalid");
+  for (let index = 0; index < expectedKeys.length; index += 1) {
+    if (actual[index] !== expectedKeys[index]) throw new TypeError("invalid");
+    const descriptor = Object.getOwnPropertyDescriptor(value, actual[index]);
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) throw new TypeError("invalid");
+  }
+  if (Object.getOwnPropertyNames(value).length !== actual.length) throw new TypeError("invalid");
+}
+
+function boundedString(value, maxBytes) {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim()) {
+    throw new TypeError("invalid");
+  }
+  if (Buffer.byteLength(value, "utf8") > maxBytes) throw new TypeError("invalid");
+  return value;
+}
+
+function digestPayload(value) {
+  const canonical = canonicalJson(value, new Set(), 0);
+  if (Buffer.byteLength(canonical, "utf8") > MAX_PAYLOAD_BYTES) throw new TypeError("invalid");
+  return digestText(canonical);
+}
+
+function canonicalJson(value, ancestors, depth) {
+  if (depth > MAX_PAYLOAD_DEPTH) throw new TypeError("invalid");
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("invalid");
+    return JSON.stringify(value);
+  }
+  if (!value || typeof value !== "object") throw new TypeError("invalid");
+  if (ancestors.has(value)) throw new TypeError("invalid");
+  if (Object.getOwnPropertySymbols(value).length !== 0) throw new TypeError("invalid");
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) throw new TypeError("invalid");
+      if (Object.getOwnPropertyNames(value).length !== value.length + 1) {
+        throw new TypeError("invalid");
+      }
+      const entries = [];
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) throw new TypeError("invalid");
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) {
+          throw new TypeError("invalid");
+        }
+        entries.push(canonicalJson(value[index], ancestors, depth + 1));
+      }
+      return `[${entries.join(",")}]`;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) throw new TypeError("invalid");
+    const keys = Object.keys(value).sort();
+    if (Object.getOwnPropertyNames(value).length !== keys.length) throw new TypeError("invalid");
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) {
+        throw new TypeError("invalid");
+      }
+    }
+    const entries = keys.map((key) => (
+      `${JSON.stringify(key)}:${canonicalJson(value[key], ancestors, depth + 1)}`
+    ));
+    return `{${entries.join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function ownDataProperty(value, key) {
+  if (!value || typeof value !== "object") return null;
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeClock(value) {
+  if (value == null) return Object.freeze({ now: () => Date.now() });
+  if (!value || typeof value.now !== "function") {
+    throw failure("host_workbench_action_grant_clock_invalid", 500);
+  }
+  return value;
+}
+
+function normalizeRandomBytes(value) {
+  if (value == null) return crypto.randomBytes;
+  if (typeof value !== "function") {
+    throw failure("host_workbench_action_grant_random_source_invalid", 500);
+  }
+  return value;
+}
+
+function normalizeTtl(value) {
+  const ttlMs = value ?? HELLOLYNK_WORKBENCH_ACTION_GRANT_TTL_MS;
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < MIN_TTL_MS || ttlMs > MAX_TTL_MS) {
+    throw failure("host_workbench_action_grant_ttl_invalid", 500);
+  }
+  return ttlMs;
+}
+
+function normalizeCapacity(value) {
+  const capacity = value ?? HELLOLYNK_WORKBENCH_ACTION_GRANT_CAPACITY;
+  if (!Number.isSafeInteger(capacity) || capacity < 1 || capacity > MAX_CAPACITY) {
+    throw failure("host_workbench_action_grant_capacity_invalid", 500);
+  }
+  return capacity;
+}
+
+function readNow(clock) {
+  const nowMs = clock.now();
+  if (!Number.isSafeInteger(nowMs) || nowMs < 0) {
+    throw failure("host_workbench_action_grant_clock_invalid", 500);
+  }
+  return nowMs;
+}
+
+function readRandomBytes(randomBytes) {
+  let value;
+  try {
+    value = randomBytes(TOKEN_BYTES);
+  } catch {
+    throw failure("host_workbench_action_grant_generation_failed", 500);
+  }
+  if (!(value instanceof Uint8Array) || value.byteLength !== TOKEN_BYTES) {
+    throw failure("host_workbench_action_grant_generation_failed", 500);
+  }
+  return Buffer.from(value);
+}
+
+function digestText(value) {
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+function invalidGrant(outcome) {
+  return failure("host_workbench_action_grant_invalid", 403, outcome);
+}
+
+function failure(code, statusCode, outcome = null) {
+  return new HelloLynkWorkbenchActionGrantError(code, statusCode, outcome);
+}

package/plugins/hellolynk-codex/runtime/core/hellolynk-workbench-connection.mjs

@@ -0,0 +1,234 @@
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import safety from "./hellolynk-runtime-safety.cjs";
+import { createNeutralHostInstallationStore, defaultNeutralHostStoreRoot } from "./hellolynk-neutral-host-installation-store.mjs";
+import { verifyPinnedNeutralHostRuntime } from "./hellolynk-neutral-host-launcher.mjs";
+import { prepareWindowsClientRoot, secureWindowsClientReleaseTree } from "./hellolynk-platform-credential-store.mjs";
+import { runRelayClientCli } from "./hellolynk-relay-client-cli.mjs";
+import { createHelloLynkAccountLauncher } from "./hellolynk-neutral-host-assembly.mjs";
+import { ACCOUNT_CLIENTS, clientAccountBaseRoot, createClientAccountActions } from "./hellolynk-client-account.mjs";
+
+const CLIENTS = new Set(ACCOUNT_CLIENTS);
+const CONFIRMATION_URL = /^https:\/\/hellolynk\.com\/account\?deviceRequest=devreq_[a-f0-9]{48}$/;
+
+// Restricted to our account pages, including the current device-confirmation
+// link. No arbitrary URL or shell text can come from the browser.
+export function createWorkbenchAccountOpener(options = {}) {
+  const launch = createHelloLynkAccountLauncher({ ...options, baseUrl: "https://hellolynk.com" });
+  return async ({ url } = {}) => {
+    if (typeof url !== "string" || (!/^https:\/\/hellolynk\.com\/account(?:#(?:keys|devices))?$/.test(url)
+      && !CONFIRMATION_URL.test(url))) throw code("workbench_portal_target_invalid", 400);
+    const parsed = new URL(url);
+    const deviceRequest = parsed.searchParams.get("deviceRequest");
+    const result = await launch({ target: parsed.hash.slice(1) || "account", ...(deviceRequest ? { deviceRequest } : {}) });
+    if (!result.opened) throw code("workbench_portal_open_failed", 502);
+    return { opened: true };
+  };
+}
+
+export function isWorkbenchConnectionRequired(error) {
+  return ["host_installation_missing", "host_delegate_binding_missing", "workbench_connection_required"].includes(error?.code)
+    || /^neutral_(?:codex|openclaw|trae_work|workbuddy|cursor|dsh|claude_code)_binding_configuration_required$/.test(String(error?.code || ""));
+}
+
+export function workbenchConnectionError(error) {
+  return isWorkbenchConnectionRequired(error) ? code("workbench_connection_required", 409) : error;
+}
+
+export function validateWorkbenchConnectionInput(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== "hellolynkId,instanceName"
+    || typeof value.hellolynkId !== "string"
+    || !safety.classifyHelloLynkStableId(value.hellolynkId)) throw code("workbench_connect_id_invalid", 400);
+  if (typeof value.instanceName !== "string" || [...value.instanceName].length > 80
+    || /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/u.test(value.instanceName)) {
+    throw code("workbench_connect_name_invalid", 400);
+  }
+  return {
+    hellolynkId: value.hellolynkId,
+    // The enrollment layer has the durable intent needed to distinguish an
+    // exact legacy retry from a new name. Preserve the value until then.
+    instanceName: value.instanceName,
+  };
+}
+
+// One small adapter for the existing enrollment and binding commands. Client,
+// package and local store come from the installed integration, never the page.
+export function createWorkbenchConnection(options) {
+  if (!CLIENTS.has(options?.client) || !path.isAbsolute(options?.releaseRoot || "")) throw code("workbench_connect_configuration_invalid");
+  const env = options.env || process.env;
+  const storeRoot = options.storeRoot || env.HELLOLYNK_NEUTRAL_STORE_ROOT || defaultNeutralHostStoreRoot("win32", env);
+  if (!path.isAbsolute(storeRoot)) throw code("workbench_connect_configuration_invalid");
+  let busy = false;
+  const accounts = createClientAccountActions(options);
+  const connect = async (input, revision = accounts.readAccountState().revision) => {
+    const validated = validateWorkbenchConnectionInput(input);
+    if (busy) throw code("workbench_connect_busy", 409);
+    busy = true;
+    try {
+      const result = await accounts.runForAccount(revision, (selectedRoot) => executeJson(
+        path.join(options.releaseRoot, "runtime/core/hellolynk-workbench-connection.mjs"),
+        ["connect", options.client, options.releaseRoot, selectedRoot], env, validated));
+      if (result?.status === "confirmation_required" && CONFIRMATION_URL.test(result.verificationUrl)) {
+        return { status: result.status, verificationUrl: result.verificationUrl };
+      }
+      if (result?.status !== "registered") throw code("workbench_connect_result_invalid", 502);
+      return publicRegistration(result);
+    } finally { busy = false; }
+  };
+  return Object.assign(connect, accounts);
+}
+
+export function createWorkbenchAccountActions(options) {
+  return createClientAccountActions(options);
+}
+
+async function connectAccount(client, sourceRoot, storeRoot, input) {
+  if (process.platform !== "win32") throw code("workbench_connect_windows_only", 400);
+  if (!CLIENTS.has(client) || !path.isAbsolute(sourceRoot) || !path.isAbsolute(storeRoot)
+    || path.basename(storeRoot).toLowerCase() !== "host") throw code("workbench_connect_configuration_invalid");
+  const value = validateWorkbenchConnectionInput(input);
+  const currentRoot = path.dirname(storeRoot);
+  const releaseCurrentRoot = path.dirname(clientAccountBaseRoot(storeRoot));
+  const profileId = `hellolynk-host-${client}-v2`;
+  const profileManifest = path.join(storeRoot, "profile-manifest-v1.json");
+  const pin = JSON.parse(await fs.readFile(path.join(sourceRoot, "runtime/neutral-host-release-pin.json"), "utf8"));
+  const binding = {
+    adapterId: client, profileId, version: 2, scopes: [], region: "intl",
+    principalId: "connection-preflight", delegateId: "connection-preflight", hostInstallationId: "connection-preflight",
+    releaseRoot: sourceRoot, releaseManifestSha256: pin.manifestSha256,
+    runnerRelativePath: "runtime/neutral-host-bootstrap.mjs", runtimeRoot: path.join(storeRoot, "runtime"), profileManifestPath: profileManifest,
+  };
+  await verifyPinnedNeutralHostRuntime(binding);
+  await prepareWindowsClientRoot(currentRoot);
+  const releaseRoot = await retainRelease(binding, releaseCurrentRoot, client);
+  await createNeutralHostInstallationStore({ root: storeRoot }).createId();
+  const activationArgs = ["--client", client, "--final-current-root", currentRoot, "--root", storeRoot,
+    "--release-current-root", releaseCurrentRoot,
+    "--release-root", releaseRoot, "--expected-release-manifest-sha256", pin.manifestSha256, "--profile-manifest", profileManifest];
+  const activationScript = path.join(releaseRoot, "runtime/connect-activate.mjs");
+  const preflight = await executeJson(activationScript, [...activationArgs, "--preflight", "true", "--pre-bind", "true"], process.env);
+  if (preflight?.ok !== true || preflight.preflight !== true || preflight.preBind !== true || preflight.readOnly !== true
+    || preflight.releaseManifestSha256 !== pin.manifestSha256 || preflight.clients?.length !== 1
+    || preflight.clients[0]?.adapterId !== client || preflight.clients[0]?.bindingUpdated !== false) throw code("workbench_connect_preflight_invalid");
+  const result = await runRelayClientCli(["connect", "--hellolynk-id", value.hellolynkId,
+    "--base-url", "https://hellolynk.com", "--root", currentRoot, "--neutral-host-root", storeRoot,
+    "--adapter", client, "--profile", profileId, ...(value.instanceName ? ["--instance-name", value.instanceName] : [])]);
+  if (result?.ok !== true || result.hellolynkId !== value.hellolynkId) throw code("workbench_connect_result_invalid");
+  if (result.status === "confirmation_required" && CONFIRMATION_URL.test(result.verificationUrl)) {
+    return { status: result.status, verificationUrl: result.verificationUrl };
+  }
+  if (result.status !== "registered" || result.clientType !== client || result.profileId !== profileId
+    || result.hostProfileRegistered !== true || result.configPath !== path.join(currentRoot, "profiles", `${profileId}.json`)) {
+    throw code("workbench_connect_result_invalid");
+  }
+  const activated = await executeJson(activationScript, activationArgs, process.env);
+  if (activated?.ok !== true || activated.releaseManifestSha256 !== pin.manifestSha256
+    || activated.clients?.length !== 1 || activated.clients[0]?.adapterId !== client) throw code("workbench_connect_activation_invalid");
+  return publicRegistration(result);
+}
+
+function publicRegistration(result) {
+  return { status: "registered",
+    ...(typeof result.instanceName === "string" ? { instanceName: result.instanceName } : {}),
+    ...(result.recoveredExistingName === true ? { recoveredExistingName: true } : {}) };
+}
+
+async function retainRelease(binding, currentRoot, client) {
+  const releases = path.join(currentRoot, "releases");
+  const sourceRoot = path.resolve(binding.releaseRoot);
+  // Normal installers already put the package here. Codex's disposable plugin
+  // cache needs a durable copy of the verified runtime before creating a binding.
+  if (sourceRoot.startsWith(`${releases}${path.sep}`)) {
+    await secureWindowsClientReleaseTree(currentRoot, path.relative(releases, sourceRoot).split(path.sep)[0], { verifyOnly: true });
+    return sourceRoot;
+  }
+  // Prefer the installed package that supplied this exact Codex cache. This
+  // keeps the binding and installer diagnostics pointed at the same release.
+  if (client === "codex") {
+    for (const entry of (await fs.readdir(releases, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isDirectory() || !/^codex-[a-f0-9]{64}$/.test(entry.name)) continue;
+      const candidate = path.join(releases, entry.name, "plugins/hellolynk-codex");
+      let pin;
+      try { pin = JSON.parse(await fs.readFile(path.join(candidate, "runtime/neutral-host-release-pin.json"), "utf8")); }
+      catch { continue; }
+      if (pin.manifestSha256 !== binding.releaseManifestSha256) continue;
+      await secureWindowsClientReleaseTree(currentRoot, entry.name, { verifyOnly: true });
+      await verifyPinnedNeutralHostRuntime({ ...binding, releaseRoot: candidate });
+      return candidate;
+    }
+  }
+  const id = `${client}-connection-${binding.releaseManifestSha256}`;
+  const target = path.join(releases, id);
+  try {
+    await fs.lstat(target);
+    await secureWindowsClientReleaseTree(currentRoot, id, { verifyOnly: true });
+    await verifyPinnedNeutralHostRuntime({ ...binding, releaseRoot: target });
+    return target;
+  } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  const stageId = `.${id}.install-${crypto.randomUUID()}`;
+  const stage = path.join(releases, stageId);
+  await fs.mkdir(stage, { recursive: true, mode: 0o700 });
+  try {
+    const manifestPath = path.join(sourceRoot, "runtime/neutral-host-release-manifest.json");
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    const paths = ["runtime/neutral-host-release-pin.json", "runtime/neutral-host-release-manifest.json",
+      ...manifest.files.map((item) => item.path.startsWith("release/") ? item.path.slice(8) : `runtime/${item.path}`)];
+    for (const relative of paths) {
+      const destination = path.resolve(stage, relative);
+      if (!destination.startsWith(`${stage}${path.sep}`)) throw code("workbench_connect_release_invalid");
+      await fs.mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+      await fs.writeFile(destination, await fs.readFile(path.join(sourceRoot, relative)), { flag: "wx", mode: 0o600 });
+    }
+    await verifyPinnedNeutralHostRuntime({ ...binding, releaseRoot: stage });
+    await secureWindowsClientReleaseTree(currentRoot, stageId);
+    try { await fs.rename(stage, target); }
+    catch (error) { if (!["EEXIST", "ENOTEMPTY", "EPERM"].includes(error?.code)) throw error; }
+    await secureWindowsClientReleaseTree(currentRoot, id, { verifyOnly: true });
+    await verifyPinnedNeutralHostRuntime({ ...binding, releaseRoot: target });
+    return target;
+  } finally {
+    if (path.dirname(stage) === releases && path.basename(stage) === stageId) await fs.rm(stage, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function executeJson(script, args, env, input) {
+  const executable = await safety.resolveHelloLynkStandaloneNode({ env });
+  return new Promise((resolve, reject) => {
+    const child = execFile(executable, [script, ...args], {
+      cwd: path.dirname(script), shell: false, windowsHide: true, timeout: 150_000,
+      maxBuffer: 256 * 1024, encoding: "utf8", env: safety.standaloneHelloLynkNodeEnvironment(env),
+    }, (error, stdout, stderr) => {
+      if (error) {
+        let failure; try { failure = JSON.parse(stderr); } catch {}
+        const safe = failure?.error;
+        return reject(code(typeof safe === "string" && /^[a-z][a-z0-9_]{1,127}$/.test(safe)
+          ? safe : error.killed ? "workbench_connect_timeout" : "workbench_connect_failed"));
+      }
+      try { resolve(JSON.parse(stdout)); } catch { reject(code("workbench_connect_result_invalid")); }
+    });
+    child.stdin?.on("error", () => {}); // execFile's callback reports early exit.
+    child.stdin?.end(input ? JSON.stringify(input) : undefined);
+  });
+}
+
+function code(value, status = 503) { return Object.assign(new Error(value), { code: value, status }); }
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  Promise.resolve().then(async () => {
+    if (process.argv.length !== 6 || process.argv[2] !== "connect") throw code("workbench_connect_arguments_invalid");
+    let input = "";
+    for await (const chunk of process.stdin) {
+      input += chunk;
+      if (Buffer.byteLength(input) > 4096) throw code("workbench_connect_input_invalid");
+    }
+    return connectAccount(process.argv[3], process.argv[4], process.argv[5], JSON.parse(input));
+  }).then((result) => process.stdout.write(`${JSON.stringify(result)}\n`), (error) => {
+    const safe = String(error?.code || error?.message || "");
+    process.stderr.write(`${JSON.stringify({ ok: false, error: /^[a-z][a-z0-9_]{1,127}$/.test(safe) ? safe : "workbench_connect_failed" })}\n`);
+    process.exitCode = 1;
+  });
+}