clay-server 5.2.0-beta.4 → 5.2.0-beta.6

package/lib/yoke/codex-recovery-admission.js

@@ -0,0 +1,164 @@
+var idleRecovery = require('./codex-idle-recovery');
+
+// Serialize decisions, not whole model turns. Waiting for a target must release
+// the gate so an unrelated Driver can still answer its Worker's permissions.
+function attachRecoveryAdmission(ctx) {
+  var handoff = null;
+  var runtimes = [];
+  var targets = new Map();
+  var cleanupTasks = new Map();
+  var cleanupFailures = new Map();
+  var cleanup = Promise.resolve();
+  var unconfirmedSharedProcess = null;
+
+  function checkSharedExit() {
+    if (!unconfirmedSharedProcess) return;
+    if (unconfirmedSharedProcess.exitCode === null && unconfirmedSharedProcess.signalCode === null) {
+      throw new Error('Codex shared runtime exit could not be confirmed; recovery remains reserved.');
+    }
+    unconfirmedSharedProcess = null;
+  }
+
+  function checker(queryOpts) {
+    var epoch = ctx.state().epoch;
+    return function() {
+      idleRecovery.checkAbort(queryOpts);
+      var state = ctx.state();
+      if ((state.shuttingDown && !state.retiring) || state.epoch !== epoch) throw ctx.shutdownError();
+    };
+  }
+
+  function cleanupRuntime(runtime) {
+    if (cleanupTasks.has(runtime)) return cleanupTasks.get(runtime);
+    var task = cleanup.catch(function() { return null; }).then(function() {
+      return runtime.shutdownForRecovery();
+    }).then(function() {
+      runtimes = runtimes.filter(function(current) { return current !== runtime; });
+      targets.forEach(function(current, threadId) { if (current === runtime) targets.delete(threadId); });
+      cleanupTasks.delete(runtime);
+      return true;
+    }, function(error) {
+      console.error('[yoke/codex] Isolated recovery runtime shutdown failed:', error.message || error);
+      // Retain ownership after an unconfirmed exit. In particular, never admit
+      // a second writer just because bounded process cleanup reached its limit.
+      cleanupFailures.set(runtime, error);
+      return false;
+    });
+    cleanupTasks.set(runtime, task);
+    cleanup = task;
+    return task;
+  }
+
+  async function withAdmission(checkCurrent, action) {
+    var release;
+    var prior = handoff;
+    var own = new Promise(function(resolve) { release = resolve; });
+    var tail = Promise.resolve(prior).then(function() { return own; });
+    handoff = tail;
+    tail.then(function() { if (handoff === tail) handoff = null; });
+    try {
+      await idleRecovery.wait(prior || Promise.resolve(), checkCurrent);
+      await idleRecovery.wait(cleanup, checkCurrent);
+      checkSharedExit();
+      return await action();
+    } finally {
+      // An aborted waiter still links to its predecessor. Releasing its own
+      // slot cannot let a later caller overtake a probe that is still running.
+      release();
+    }
+  }
+
+  async function releaseTarget(threadId, checkCurrent) {
+    var prior = targets.get(threadId);
+    if (!prior) return true;
+    if (cleanupFailures.has(prior)) throw cleanupFailures.get(prior);
+    await prior.retireIdleForRecovery(checkCurrent);
+    await cleanup;
+    checkCurrent();
+    if (cleanupFailures.has(prior)) throw cleanupFailures.get(prior);
+    return !targets.has(threadId);
+  }
+
+  async function prepareShared(threadId, checkCurrent) {
+    var state = ctx.state();
+    if (state.initializing) return false;
+    var retiredThreads = [];
+    if (state.refCount > 0) {
+      var snapshots = state.entries.map(function(entry) { return entry.handle && entry.handle.getIdleRecoverySnapshot(); });
+      if (await idleRecovery.retireIdleQueries(state.entries, state.server, checkCurrent)) {
+        retiredThreads = snapshots.filter(Boolean).map(function(snapshot) { return snapshot.threadId; });
+      }
+    }
+    state = ctx.state();
+    if (!state.server) return true;
+    if (!state.refCount && await idleRecovery.runtimeCanStop(state.server, retiredThreads, checkCurrent)) {
+      var proc = state.server.proc;
+      var stopped = await ctx.stopIdle();
+      if (stopped) { unconfirmedSharedProcess = proc || null; checkSharedExit(); }
+      return stopped;
+    }
+    return idleRecovery.releaseThread(state.entries, state.server, threadId, checkCurrent);
+  }
+
+  async function waitUntilAvailable(queryOpts, action) {
+    var checkCurrent = checker(queryOpts);
+    var waiting = false;
+    if (typeof queryOpts.onRecoveryAdmission === 'function') queryOpts.onRecoveryAdmission(true);
+    try {
+      while (true) {
+        checkCurrent();
+        // Cancellation returns to the caller immediately, but an in-flight
+        // unsubscribe or shutdown retains the gate until its bounded RPC settles.
+        var result = await idleRecovery.wait(withAdmission(checkCurrent, action.bind(null, checkCurrent)), checkCurrent);
+        if (result) {
+          if (waiting && typeof queryOpts.onRecoveryWaiting === 'function') queryOpts.onRecoveryWaiting(false);
+          return result;
+        }
+        if (!waiting && typeof queryOpts.onRecoveryWaiting === 'function') queryOpts.onRecoveryWaiting(true);
+        waiting = true;
+        await idleRecovery.wait(new Promise(function(resolve) { setTimeout(resolve, 50); }), checkCurrent);
+      }
+    } finally {
+      if (typeof queryOpts.onRecoveryAdmission === 'function') queryOpts.onRecoveryAdmission(false);
+    }
+  }
+
+  function createQuery(queryOpts) {
+    return waitUntilAvailable(queryOpts, async function(checkCurrent) {
+      if (!await releaseTarget(queryOpts.resumeSessionId, checkCurrent)) return false;
+      if (!await prepareShared(queryOpts.resumeSessionId, checkCurrent)) return false;
+      checkCurrent();
+      var runtime = ctx.createRuntime(queryOpts);
+      runtimes.push(runtime);
+      targets.set(queryOpts.resumeSessionId, runtime);
+      try {
+        return await runtime.createQuery(Object.assign({}, queryOpts, {
+          isolatedRecovery: true,
+          onRuntimeFinished: function() { return cleanupRuntime(runtime); },
+        }));
+      } catch (error) {
+        await cleanupRuntime(runtime);
+        throw error;
+      }
+    });
+  }
+
+  return {
+    createQuery: createQuery,
+    pending: function() { return handoff; },
+    checkSharedExit: checkSharedExit,
+    hasTarget: function(threadId) { return targets.has(threadId); },
+    waitForTarget: function(queryOpts) {
+      return waitUntilAvailable(queryOpts, function(checkCurrent) { return releaseTarget(queryOpts.resumeSessionId, checkCurrent); });
+    },
+    shutdown: function() {
+      return Promise.all(runtimes.slice().map(cleanupRuntime)).then(function(results) {
+        checkSharedExit();
+        if (results.indexOf(false) !== -1) throw new Error('Codex recovery runtime cleanup could not be confirmed.');
+        return cleanup;
+      });
+    },
+  };
+}
+
+module.exports = { attachRecoveryAdmission: attachRecoveryAdmission };

package/lib/yoke/configuration.js

@@ -0,0 +1,13 @@
+// Serializable descriptions of implemented provider controls. Legacy setting
+// keys and message names describe persistence compatibility, never authority.
+var claude = {
+  auto: true,
+  permissionModes: [{ value: 'default', label: 'Ask' }, { value: 'plan', label: 'Plan' }, { value: 'acceptEdits', label: 'Auto-accept edits' }],
+  thinking: { options: ['disabled', 'adaptive', 'budget'], budget: true },
+};
+var codex = {
+  approval: { options: [{ value: 'never', label: 'Auto' }, { value: 'untrusted', label: 'Untrusted' }, { value: 'on-request', label: 'Ask' }], state: 'codexApproval', message: 'set_codex_approval', key: 'approval' },
+  sandbox: { options: [{ value: 'read-only', label: 'Read Only' }, { value: 'workspace-write', label: 'Workspace' }, { value: 'danger-full-access', label: 'Full Access' }], state: 'codexSandbox', message: 'set_codex_sandbox', key: 'sandbox' },
+  webSearch: { options: [{ value: 'disabled', label: 'Off' }, { value: 'cached', label: 'Cached' }, { value: 'live', label: 'Live' }], state: 'codexWebSearch', message: 'set_codex_websearch', key: 'webSearch' },
+};
+module.exports = { claude: claude, codex: codex };

package/lib/yoke/discovery.js

@@ -0,0 +1,70 @@
+// Installation resolution shared by adapter creation, startup and product UI.
+// This never starts a provider; callers may replace resolvers for isolated tests.
+var fs = require('fs');
+var cp = require('child_process');
+function onPath(binary, user) {
+  try {
+    if (user && !/^[a-z_][a-z0-9_-]*\$?$/i.test(user)) return null;
+    var command = user ? 'su' : process.platform === 'win32' ? 'where' : 'which';
+    var args = user ? ['-', user, '-c', 'which ' + binary] : [binary];
+    if (!/^[a-zA-Z0-9_.-]+$/.test(binary)) return null;
+    var result = cp.execFileSync(command, args, { encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+    return String(result || '').trim().split(/\r?\n/)[0] || null;
+  } catch (error) { return null; }
+}
+// Native commands require an executable regular file. SDK-owned JavaScript
+// entries are readable files launched through Node, not native executables.
+function validEntry(file, script) {
+  try {
+    if (typeof file !== 'string' || !file || !fs.statSync(file).isFile()) return false;
+    fs.accessSync(file, script && /\.(?:c|m)?js$/i.test(file) ? fs.constants.R_OK : fs.constants.X_OK);
+    return true;
+  } catch (error) { return false; }
+}
+function explicitEntry(env, name, script) {
+  if (!Object.prototype.hasOwnProperty.call(env, name)) return undefined;
+  if (!validEntry(env[name], script)) throw new Error('Invalid explicit provider executable: ' + name);
+  return env[name];
+}
+function pathResolver(binary, override) {
+  return function(options) {
+    options = options || {};
+    var env = options.env || process.env;
+    if (!options.user && override) {
+      var explicit = explicitEntry(env, override, false);
+      if (explicit !== undefined) return explicit;
+    }
+    var resolved = onPath(binary, options.user);
+    return options.user || validEntry(resolved, false) ? resolved : null;
+  };
+}
+function bundledResolver(find, binary) {
+  return function(options) {
+    options = options || {};
+    // The mapped account cannot inherit the daemon account's installation.
+    if (options.user) return onPath(binary, options.user);
+    // The runtime resolver owns all fallback policy. Adding a discovery-only
+    // PATH fallback would advertise a runtime that its adapter cannot start.
+    return find();
+  };
+}
+function acpResolver(vendor) {
+  return function(options) {
+    if (options && options.user) return null;
+    var profiles = require('./acp-agent-profiles');
+    return profiles.findAcpAgentPath(profiles.getAcpAgentProfile(vendor));
+  };
+}
+function installed(options) {
+  var registry = options && options.registry || require('./vendor-registry').VENDOR_REGISTRY;
+  var result = {};
+  Object.keys(registry).forEach(function(vendor) {
+    var info = registry[vendor];
+    result[vendor] = false;
+    if (options && options.user && info.osUserIsolation !== true) return;
+    if (typeof info.resolveExecutable !== 'function') return;
+    try { result[vendor] = !!info.resolveExecutable(options || {}); } catch (error) {}
+  });
+  return result;
+}
+module.exports = { installed: installed, pathResolver: pathResolver, bundledResolver: bundledResolver, acpResolver: acpResolver, validEntry: validEntry, explicitEntry: explicitEntry };

package/lib/yoke/errors.js

@@ -0,0 +1,8 @@
+function classify(provider, text) {
+  var service = require('./provider-contract').resolve(provider).classifyError;
+  return typeof service === 'function' ? service(text) : null;
+}
+function contextOverflow(error) {
+  return /prompt is too long|context_length|maximum context length/i.test(String(error || ""));
+}
+module.exports = { contextOverflow: contextOverflow, classify: classify };

package/lib/yoke/host-environment.js

@@ -0,0 +1,7 @@
+// Provider compatibility at the host boundary. No effects occur on import.
+function prepare(env) { delete env.CLAUDECODE; }
+function reaper(env) {
+  return { idleMs: Number(env.CLAY_ADAPTER_IDLE_MS) || Number(env.CLAY_CODEX_IDLE_MS) || 5 * 60 * 1000,
+    reapMs: Number(env.CLAY_ADAPTER_REAPER_MS) || Number(env.CLAY_CODEX_REAPER_MS) || 60 * 1000 };
+}
+module.exports = { prepare: prepare, reaper: reaper };

package/lib/yoke/index.js

@@ -16,11 +16,12 @@ var createGrokAdapter = require("./adapters/grok").createGrokAdapter;
 var createCopilotAdapter = require("./adapters/copilot").createCopilotAdapter;
 var createQwenAdapter = require("./adapters/qwen").createQwenAdapter;
 var createJunieAdapter = require("./adapters/junie").createJunieAdapter;
+var createMuseAdapter = require("./adapters/muse").createMuseAdapter;
 var createKiroAdapter = require("./adapters/kiro").createKiroAdapter;
 
 // Keep the first session in a new project predictable. This order is also
 // used by the UI when a project has no remembered vendor yet.
-var DEFAULT_VENDOR_ORDER = ["claude", "codex", "grok", "kimi", "copilot", "qwen", "junie", "antigravity", "opencode", "kiro"];
+var DEFAULT_VENDOR_ORDER = ["claude", "codex", "muse", "grok", "kimi", "copilot", "qwen", "junie", "antigravity", "opencode", "kiro"];
 
 function resolveDefaultVendor(availableVendors) {
   availableVendors = availableVendors || {};
@@ -97,6 +98,8 @@ function createAdapter(opts) {
     adapter = createJunieAdapter(opts);
   } else if (vendor === "kiro") {
     adapter = createKiroAdapter(opts);
+  } else if (vendor === "muse") {
+    adapter = createMuseAdapter(opts);
   } else {
     throw new Error("[YOKE] Unknown adapter vendor: " + vendor);
   }
@@ -262,6 +265,7 @@ function checkAuth() {
     qwen: !!lookupBinary("qwen"),
     junie: !!lookupBinary("junie"),
     kiro: checkKiro(),
+    muse: null,
   };
   logAuthCheck(_authCache);
   return _authCache;
@@ -280,54 +284,8 @@ function checkAuth() {
 var _installedCache = null;
 
 function checkInstalled() {
-  if (_installedCache) return _installedCache;
-
-  var fs = require("fs");
-  var execFileSync = require("child_process").execFileSync;
-  var result = { claude: false, codex: false, antigravity: false, opencode: false, kimi: false, grok: false, copilot: false, qwen: false, junie: false, kiro: false };
-  try {
-    if (process.platform === "win32") execFileSync("where", ["claude"], { timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-    else execFileSync("which", ["claude"], { timeout: 3000, stdio: ["pipe", "pipe", "pipe"] });
-    result.claude = true;
-  } catch (e) {}
-  try {
-    var findKiroPath = require("./kiro-acp-server").findKiroPath;
-    var kiroBin = findKiroPath();
-    if (kiroBin && fs.existsSync(kiroBin)) result.kiro = true;
-  } catch (e) {}
-  try {
-    var codexBin = null;
-    try {
-      var findCodexPath = require("./codex-app-server").findCodexPath;
-      codexBin = findCodexPath();
-      if (codexBin && fs.existsSync(codexBin)) {
-        result.codex = true;
-      }
-    } catch (e) {}
-
-    if (!result.codex) {
-      var whichOut = process.platform === "win32"
-        ? execFileSync("where", ["codex"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] })
-        : execFileSync("which", ["codex"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
-      if (whichOut.trim()) result.codex = true;
-    }
-  } catch (e) {}
-  try {
-    var antigravityBinary = process.platform === "win32"
-      ? execFileSync("where", ["agy"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] })
-      : execFileSync("which", ["agy"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
-    result.antigravity = !!antigravityBinary.trim();
-  } catch (e) {}
-  var acpVendorKeys = ["opencode", "kimi", "grok", "copilot", "qwen", "junie"];
-  for (var acpIndex = 0; acpIndex < acpVendorKeys.length; acpIndex++) {
-    try {
-      var acpProfiles = require("./acp-agent-profiles");
-      var acpVendor = acpVendorKeys[acpIndex];
-      result[acpVendor] = !!acpProfiles.findAcpAgentPath(acpProfiles.getAcpAgentProfile(acpVendor));
-    } catch (e) {}
-  }
-  _installedCache = result;
-  return result;
+  if (!_installedCache) _installedCache = require("./discovery").installed();
+  return _installedCache;
 }
 
 function invalidateAuthCache() {
@@ -352,7 +310,7 @@ function createAdapters(opts) {
   // Tests can supply a fixed installation snapshot without probing or spawning
   // vendor binaries; production callers always use the cached host scan.
   var installed = opts._installed || checkInstalled();
-  var auth = { claude: false, codex: false, antigravity: false, opencode: false, kimi: false, grok: false, copilot: false, qwen: false, junie: false, kiro: false };
+  var auth = { claude: false, codex: false, antigravity: false, opencode: false, kimi: false, grok: false, copilot: false, qwen: false, junie: false, kiro: false, muse: false };
   var adapters = {};
 
   function supportsConfiguredIsolation(vendor) {
@@ -390,7 +348,7 @@ function createAdapters(opts) {
     }
   }
 
-  var subprocessVendors = ["antigravity", "opencode", "kimi", "grok", "copilot", "qwen", "junie"];
+  var subprocessVendors = ["antigravity", "opencode", "kimi", "grok", "copilot", "qwen", "junie", "muse"];
   for (var subprocessIndex = 0; subprocessIndex < subprocessVendors.length; subprocessIndex++) {
     var subprocessVendor = subprocessVendors[subprocessIndex];
     var subprocessInfo = vendorRegistry.getVendorInfo(subprocessVendor);

package/lib/yoke/interface.js

@@ -21,6 +21,25 @@ var INITIALIZE_TIMEOUT_MS = 90000;
 
 /*
  * Optional adapter event contract:
+ *   { yokeType: "turn_activity", phase: "waiting" | "running" | "background", turnId?, disposition? }
+ * Waiting reports a pending submission/acknowledged queue, never model
+ * reasoning. Running requires an observed native start. Background means the
+ * foreground yielded while real terminals remain pending. These presentation
+ * facts never settle a turn or authorize tools; human decision surfaces take
+ * precedence. Common processing records them for live/replayed progress UI.
+ *
+ *   { yokeType: "foreground_available" }
+ * Observed next-message admission while background work retains its real
+ * terminal. Offers one queue admission bound to this exact live query. Does
+ * not emit result/done, clear processing, settle reviews or complete tasks.
+ * Common processing persists an assistant_boundary presentation event before
+ * offering admission. Live/replayed clients flush the current assistant bubble
+ * at this boundary without treating it as a terminal or completing tools.
+ * Stop, paused delivery and query replacement invalidate the admission.
+ * A later successful result may carry backgroundOnly: true when its earlier
+ * foreground yielded to a newer accepted message. It accounts for that send
+ * without settling the newer turn's reviews or user-work completion callbacks.
+ *
  *   { yokeType: "background_tasks_changed", tasks: [{ task_id, task_type, description }] }
  *
  * Each event replaces the complete live set. An adapter that emits this event
@@ -29,6 +48,25 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  * and adapters that emit nothing simply have no background-task indicator.
  */
 
+/*
+ * Optional image output event (independent of image input or invocation APIs):
+ *   { yokeType: "generated_image", toolId, blockId, data, mediaType,
+ *     prompt, savedPath, transparentBackground, isError, status }
+ * data is base64 image bytes (the common processor also accepts data URLs).
+ * toolId identifies this output; blockId associates any existing tool display.
+ * prompt is optional observed prompt text; savedPath is optional provenance,
+ * never authority to open a provider path. transparentBackground is true/false
+ * only when observed, otherwise null. Failed output sets isError and carries
+ * no successful image bytes. Common processing saves bytes, persists imageRefs
+ * and sends authenticated project URLs; failed saves become tool errors.
+ * The historical name covers provider-produced image artifacts, not proof of
+ * model generation. Emit only observed bytes, never an input echo, guessed
+ * filename or opaque artifact reference. Codex normalizes imageGeneration;
+ * Muse can read an explicitly typed raster outputRef through item/readOutput.
+ * This optional event does not imply pushMessage image-input support, an
+ * always-available model tool, or a dedicated adapter.generateImage() method.
+ */
+
 /**
  * Validate that an adapter object implements all required methods.
  * Throws if any are missing. Development-time safety net only.
@@ -40,6 +78,84 @@ var INITIALIZE_TIMEOUT_MS = 90000;
  *   .createToolServer(def): ToolServer (opaque)
  *   .createQuery(opts): QueryHandle
  *
+ * Optional query orchestration contract (.queryContract):
+ *   toolTransport: "sdk-mcp" | "dynamic" | "stdio-mcp" (absent: unsupported)
+ *   catalogLifetime: "query" | "conversation"
+ *   externalToolTransport?: "dynamic" for remotely discovered definitions
+ *   defaultUserInputMode?: "fallback" | "native" (auto otherwise)
+ *   questionGuidance?(): string; provider-specific protocol guidance
+ *   permissionModes?: string[]; implemented native modes, e.g. "auto"
+ *   mcpPermissionOverrides?: true only for a working handle override setter
+ *   interruptionMessage?: string; truthful feedback after Stop
+ *   catalogVersion?(session, family): number
+ *   recordCatalog?(session, versions): void
+ *   staleCatalogReason?: string
+ *
+ * Conversation catalogs are immutable on resume. The host uses semantic tool
+ * families (schedules, questions, browser, issues, knowledge, linear) and their
+ * required revisions to request an exact-query recovery bridge. Adapter-owned
+ * mapping reads/writes persisted provider fields, including legacy names. A
+ * missing reader means unknown catalog; a missing writer never records success.
+ * Writers run only after a matching session_started event on the same live
+ * session/query generation. Creating a handle alone is not catalog confirmation.
+ * SDK transports must actually mount createToolServer output; dynamic transports
+ * must dispatch dynamicTools/callDynamicTool and deliver sessionMcpServer on
+ * resume or reject startup truthfully. These declarations never authorize tools:
+ * owner/foreign checks, target/review authority and live generation checks remain
+ * in common services. Stop cancels pending input/effects immediately; uncertain
+ * effects must not replay automatically. Provider protocols stay adapter-side.
+ * Init-free contracts live beside adapters and are also exposed by the registry
+ * for product controls before adapter initialization. Other providers retain
+ * their existing declared stdio transport or default to unsupported.
+ *
+ * Init-free provider services (adapter.providerContract or registry entry):
+ *   mapQueryOptions(intent): object. Translates validated common intent to SDK
+ *     namespaces; host never builds CLAUDE/CODEX/ACP/KIRO envelopes. Intent
+ *     includes settings, thinking, nativePermissionMode/nativeBypass, readOnly,
+ *     isolation, resumeAt, instructionSources, betas and start time. readOnly
+ *     must dominate bypass, sandbox and search options. Unknown providers have
+ *     no extra options; declared invalid/missing implementations must not imply
+ *     success. Legacy persisted names remain accepted through provider codecs.
+ *   configuration: serializable permission/thinking/approval/sandbox/search
+ *     descriptions. These describe supported controls, never authorization.
+ *   settings: defaults(), messages(settings), change(message, settings) returns
+ *     a validated patch and response; host owns persistence and socket access.
+ *   normalizeContext(value): { usedTokens, windowTokens, measurement, source }.
+ *     measurement is observed, estimated or unavailable. Zero is a measurement;
+ *     unknown is null. Billing totals are not context occupancy. YOKE usage
+ *     projects result/account-quota history to the same client contract.
+ *   authenticationReply(text), classifyError(text): protocol interpretation.
+ *     Host handles authenticationRequired and classified errors, preserving
+ *     identity, user-visible failure and explicit resumption requirements.
+ *   resolveExecutable(options): path|null; discovery never runs the provider.
+ *     Explicit supported overrides win; mapped users cannot inherit daemon
+ *     credentials/installations. Errors or missing resolvers mean unavailable.
+ *   login command/host metadata: only known validated token-only operations;
+ *     OAuth URLs require exact hosts, PKCE, state and a loopback callback.
+ *     Host still authorizes the exact owner/terminal and async flow revision.
+ *   prepareIsolation, processControl: provider filesystem/PID protocol. Host
+ *     authorizes identity and the exact process target before effects; absent
+ *     verification refuses termination. No arbitrary shell/API dispatch.
+ *   recoveryFactory(ctx): actual begin/enqueue/event/progress/cancel/current/
+ *     valid/stopping/dispose implementation. Only the implemented confirmed
+ *     termination protocol may retry; never replay uncertain delivery. Bindings
+ *     retain the original service for immediate Stop and reject replacement
+ *     providers. Unsupported providers receive no synthesized watchdog/retry.
+ *   readSessionHistory(home, cwd, sessionId): actual provider fork-history
+ *     reader. Local-history forks bypass file reading. Missing/nonfunction
+ *     readers refuse; the host must not assume another provider's format.
+ *   supportsLegacyGuiResume(session): implements the actual terminal format;
+ *     the host retains idle/Stop/identity admission and persistence authority.
+ *   notificationHooks, maintenance, provisionUser, credentialDirectories:
+ *     bounded provider services; host owns provisioning and cleanup policy.
+ *
+ * publicInfo() sends only an explicit serializable field allowlist. Executable
+ * callbacks/services, OAuth internals and factories are never client metadata.
+ * Unknown/unsupported transports normalize to none. Declared SDK MCP transport
+ * with requested definitions must have a callable factory and non-null result;
+ * errors fail startup before admission. Capability data never grants canonical
+ * registry/query-generation authority, owner permissions or human review.
+ *
  * Optional one-shot capability:
  *   .createOneShotQuery(opts): Promise<{ handle, backendPersistence }>
  *     backendPersistence is "ephemeral" only when the adapter can verify the

package/lib/yoke/kiro-acp-server.js

@@ -8,9 +8,9 @@ var fs = require("fs");
 var { AcpProcessManager } = require("./acp-process-manager");
 
 function findKiroPath() {
-  if (process.env.KIRO_CLI_PATH && fs.existsSync(process.env.KIRO_CLI_PATH)) {
-    return process.env.KIRO_CLI_PATH;
-  }
+  var discovery = require("./discovery");
+  var explicit = discovery.explicitEntry(process.env, "KIRO_CLI_PATH", false);
+  if (explicit !== undefined) return explicit;
 
   var binName = process.platform === "win32" ? "kiro-cli.exe" : "kiro-cli";
   var realHome;
@@ -23,7 +23,7 @@ function findKiroPath() {
     "/opt/homebrew/bin/" + binName,
   ];
   for (var i = 0; i < candidates.length; i++) {
-    if (candidates[i] && fs.existsSync(candidates[i])) return candidates[i];
+    if (discovery.validEntry(candidates[i], false)) return candidates[i];
   }
 
   try {
@@ -32,7 +32,7 @@ function findKiroPath() {
       ? execFileSync("where", [binName], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] })
       : execFileSync("which", ["kiro-cli"], { timeout: 3000, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
     var resolved = out.trim().split(/\r?\n/)[0];
-    if (resolved) return resolved;
+    if (discovery.validEntry(resolved, false)) return resolved;
   } catch (e) {}
 
   throw new Error("Could not find kiro-cli binary (looked in ~/.local/bin, PATH, KIRO_CLI_PATH)");

package/lib/yoke/legacy-sessions.js

@@ -0,0 +1,89 @@
+// The existing imported terminal format. Product session creation/deletion
+// remains in the host; these are provider file/grammar projections only.
+var fs = require("fs"), path = require("path");
+var hygiene = require("./claude-transcript-hygiene");
+function directory(home, cwd) { return path.join(home, ".claude", "projects", require("../utils").encodeCwd(cwd)); }
+  function readHead(filePath) {
+    var MAX_READ = 64 * 1024;
+    try {
+      var stat = fs.statSync(filePath);
+      var fd = fs.openSync(filePath, "r");
+      var bytesToRead = Math.min(stat.size, MAX_READ);
+      var buf = Buffer.alloc(bytesToRead);
+      fs.readSync(fd, buf, 0, bytesToRead, 0);
+      fs.closeSync(fd);
+      var lines = buf.toString("utf8").split("\n");
+      var events = [];
+      for (var i = 0; i < lines.length; i++) {
+        if (!lines[i]) continue;
+        try {
+          var event = JSON.parse(lines[i]);
+          if (event && typeof event === "object") events.push(event);
+        } catch (e) {}
+      }
+      return events;
+    } catch (e) {
+      return null;
+    }
+  }
+
+function metadata(events, fp) {
+      var userCount = 0;
+      var firstUserText = null;
+      var createdAtIso = null;
+      for (var li = 0; li < events.length; li++) {
+        var ev = events[li];
+        if (ev.type === "user" && ev.message && ev.message.role === "user") {
+          userCount++;
+          if (firstUserText == null) {
+            var c = ev.message.content;
+            if (typeof c === "string") {
+              firstUserText = c;
+            } else if (Array.isArray(c)) {
+              var parts = [];
+              for (var ci = 0; ci < c.length; ci++) {
+                if (c[ci] && c[ci].type === "text" && typeof c[ci].text === "string") parts.push(c[ci].text);
+              }
+              firstUserText = parts.join("");
+            }
+            if (ev.timestamp && !createdAtIso) createdAtIso = ev.timestamp;
+          }
+        }
+      }
+
+      if (userCount === 0) return null;
+      // Defensive warmup skip (daemon also cleans these)
+      if (hygiene.isClaudeWarmupTranscript(events)) return null;
+
+      // Title: first user message trimmed/truncated. Fall back to a
+      // neutral label so the sidebar entry is identifiable.
+      var title = (firstUserText || "").trim().replace(/\s+/g, " ");
+      if (title.length > 60) title = title.slice(0, 57) + "...";
+      if (!title) title = "Imported CLI session";
+
+      var createdAt = Date.now();
+      if (createdAtIso) {
+        var t = Date.parse(createdAtIso);
+        if (!isNaN(t)) createdAt = t;
+      }
+      var lastActivity = createdAt;
+      try { lastActivity = fs.statSync(fp).mtimeMs; } catch (e) {}
+
+return { title: title, createdAt: createdAt, lastActivity: lastActivity };
+}
+function candidates(dir, known, deleted) {
+  var files;
+  try { files = fs.readdirSync(dir); } catch (error) { return []; }
+  return files.filter(function(file) { return file.endsWith(".jsonl"); }).flatMap(function(file) {
+    var id = file.slice(0, -6);
+    if (known.has(id) || deleted.has(id)) return [];
+    var filename = path.join(dir, file), events = readHead(filename);
+    var value = events && metadata(events, filename);
+    return value ? [Object.assign({ id: id, vendor: "claude" }, value)] : [];
+  });
+}
+function obsolete(dir, session) {
+  var filename = path.join(dir, session.cliSessionId + ".jsonl"), events = readHead(filename);
+  return !fs.existsSync(filename) && (!session.history || session.history.length === 0) || events && hygiene.isClaudeWarmupTranscript(events);
+}
+module.exports = { candidates: candidates, obsolete: obsolete, directory: directory, readHead: readHead, metadata: metadata, isWarmup: hygiene.isClaudeWarmupTranscript };

package/lib/yoke/login-protocol.js

@@ -0,0 +1,25 @@
+// Known provider login operations and output grammar; never accepts a command
+// from model/client input. Identity and terminal permission stay in the host.
+var PATTERNS = [/successfully logged in(?![ \t]+to[ \t]+mcp)/i, /logged in successfully/i, /login successful/i,
+  /successfully authenticated/i, /authentication successful/i, /signed in successfully/i,
+  /signed in with your [a-z ]+ account/i, /you(?:'re| are) (?:now )?(?:logged|signed) in/i];
+function stripAnsi(text) { return String(text).replace(/\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\r/g, ''); }
+function successful(text) { return PATTERNS.some(function(pattern) { return pattern.test(text); }); }
+function command(vendor, browser) {
+  var info = require('./provider-contract').resolve(vendor);
+  var operation = browser ? info.browserLoginCommand : info.terminalLoginCommand || info.loginCommand;
+  if (typeof operation !== 'string' || !/^[a-zA-Z0-9_.-]+(?: [a-zA-Z0-9_.-]+)*$/.test(operation)) throw new Error('Provider sign-in is unavailable.');
+  return operation;
+}
+function loginUrl(value, provider) {
+  try {
+    var hosts = require('./provider-contract').resolve(provider).oauthHosts || [];
+    var url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || hosts.indexOf(url.hostname) < 0) return null;
+    if (!url.searchParams.get('state') || !url.searchParams.get('code_challenge')) return null;
+    var callback = new URL(url.searchParams.get('redirect_uri'));
+    if (callback.protocol !== 'http:' || ['localhost', '127.0.0.1', '[::1]'].indexOf(callback.hostname) < 0) return null;
+    return url.href;
+  } catch (error) { return null; }
+}
+module.exports = { stripAnsi: stripAnsi, successful: successful, command: command, loginUrl: loginUrl };