very-happy-cli 0.2.158 → 0.2.160

package/dist/runClaude-Ba01qT-u.mjs

@@ -0,0 +1,848 @@
+import os from 'node:os';
+import { c as claimSessionOrExit, a as applyServerSnapshot, w as withoutServerSnapshot, m as mergeReconnectMetadata } from './sessionLock-D-EG2CfG.mjs';
+import { randomUUID } from 'node:crypto';
+import { c as connectionState, A as ApiClient, s as startOfflineReconnection } from './api-CLMUr-SX.mjs';
+import { l as logger } from './logger-6HYUEXNk.mjs';
+import { p as packageJson } from './package-BhaKlnxz.mjs';
+import { readSettings } from './persistence-HGW_ZVs9.mjs';
+import { s as spawnOriginTags } from './createSessionMetadata-CVVkGjxV.mjs';
+import { P as PROMPT_QUEUE_CAPABILITY } from './index-qdS1friN.mjs';
+import { c as configuration } from './configuration-RfeNjFmd.mjs';
+import { n as notifyDaemonSessionStarted } from './controlClient-BGbDcgWS.mjs';
+import { g as getInitialMachineMetadata } from './machineMetadata-oOzBfDfs.mjs';
+import { p as projectPath } from './projectPath-BTBIMB57.mjs';
+import { resolve, join } from 'node:path';
+import { a as applySandboxPermissionPolicy, r as resolveInitialClaudePermissionMode, m as mapToClaudeMode, b as resolveRemoteClaudePermissionMode, c as reconcilePublishedPermissionMode } from './permissionMode-Cr5JCbB7.mjs';
+import { d as decodeBase64, e as encodeBase64 } from './authRelay-DSAvg1uv.mjs';
+import { readFile } from 'node:fs/promises';
+import { D as DEFAULT_CLAUDE_PERMISSION_MODE } from './defaultPermissionMode-BnxJPVHT.mjs';
+import { C as CLAUDE_ATTACHMENT_KINDS, s as stripAttachmentManifest } from './attachmentContent-_kxRznNf.mjs';
+import { p as planClaudeStartup } from './startupPlan-DFMyNgAs.mjs';
+import 'node:fs';
+import 'axios';
+import 'node:events';
+import 'socket.io-client';
+import './attachmentLimits-yba1uHFO.mjs';
+import 'zod';
+import './limits-DIo7rEBR.mjs';
+import './time-D0XyHOid.mjs';
+import './lidState-CeEt442o.mjs';
+import 'os';
+import 'child_process';
+import './registerCommonHandlers-Ccvsz7Ou.mjs';
+import 'util';
+import 'fs/promises';
+import 'crypto';
+import 'path';
+import 'cross-spawn';
+import '@paralleldrive/cuid2';
+import './sync-C8gyQFMc.mjs';
+import './backgroundTaskActivity-8PdPxrvy.mjs';
+import './contentLogMetadata-BlWI0egu.mjs';
+import 'chalk';
+import 'node:util';
+import './detectCLI-CSGMlV51.mjs';
+import 'fs';
+import './localHappyAgentAuth-C-HQyiv6.mjs';
+import 'tweetnacl';
+import 'url';
+
+const DEFAULT_CLAUDE_MODEL = void 0;
+const DEFAULT_CLAUDE_EFFORT = void 0;
+async function runClaude(credentials, options = {}) {
+  logger.debug(`[CLAUDE] ===== CLAUDE MODE STARTING =====`);
+  logger.debug(`[CLAUDE] This is the Claude agent, NOT Gemini`);
+  options = { ...options, claudeEnvVars: { ...options.claudeEnvVars, HAPPY_MANAGED: "1" } };
+  const workingDirectory = process.cwd();
+  const isAssistantVariant = process.env.HAPPY_SESSION_VARIANT === "assistant";
+  if (isAssistantVariant) {
+    try {
+      const { bootstrapAssistantHome } = await import('./bootstrap-hxXPCFMx.mjs');
+      await bootstrapAssistantHome();
+    } catch (error) {
+      logger.debug("[START] Assistant home bootstrap failed:", error);
+    }
+  }
+  logger.debug(`[START] Happy process started pid=${process.pid} node=${process.version} cwd=${workingDirectory}`);
+  logger.debug(`[START] Options: startedBy=${options.startedBy}, startingMode=${options.startingMode}`);
+  if (options.startedBy === "daemon" && options.startingMode === "local") {
+    throw new Error("Daemon-spawned sessions cannot use local/interactive mode. Use --happy-starting-mode remote or spawn sessions directly from terminal.");
+  }
+  const depsLoad = import('./runClaudeDeps-DOt79DjU.mjs');
+  depsLoad.catch(() => {
+  });
+  const reconnectRequested = Boolean(
+    process.env.HAPPY_RECONNECT_SESSION_ID && process.env.HAPPY_RECONNECT_ENCRYPTION_KEY && process.env.HAPPY_RECONNECT_ENCRYPTION_VARIANT
+  );
+  const startupPlan = planClaudeStartup({ startedBy: options.startedBy, reconnect: reconnectRequested });
+  connectionState.setBackend("Claude");
+  const api = await ApiClient.create(credentials);
+  let state = {};
+  const settings = await readSettings();
+  let machineId = settings?.machineId;
+  const sandboxConfig = options.noSandbox ? void 0 : settings?.sandboxConfig;
+  const sandboxEnabled = Boolean(sandboxConfig?.enabled);
+  const initialPermissionMode = applySandboxPermissionPolicy(
+    resolveInitialClaudePermissionMode(options.permissionMode ?? DEFAULT_CLAUDE_PERMISSION_MODE, options.claudeArgs),
+    sandboxEnabled
+  );
+  const dangerouslySkipPermissions = initialPermissionMode === "bypassPermissions" || initialPermissionMode === "yolo" || sandboxEnabled || Boolean(options.claudeArgs?.includes("--dangerously-skip-permissions"));
+  if (!machineId) {
+    console.error(`[START] No machine ID found in settings, which is unexpected since authAndSetupMachineIfNeeded should have created it. Please report this issue on https://github.com/Mereithhh/very-happy/issues`);
+    process.exit(1);
+  }
+  logger.debug(`Using machineId: ${machineId}`);
+  const sessionTag = randomUUID();
+  if (startupPlan.registerMachine) {
+    await api.getOrCreateMachine({
+      machineId,
+      metadata: getInitialMachineMetadata()
+    });
+  }
+  const forkedFromSessionId = process.env.HAPPY_FORKED_FROM_SESSION_ID;
+  const forkedFromMessageId = process.env.HAPPY_FORKED_FROM_MESSAGE_ID;
+  const importedFromClaudeSessionId = process.env.HAPPY_IMPORTED_FROM_CLAUDE_SESSION_ID;
+  const importTitle = process.env.HAPPY_IMPORT_TITLE;
+  const originTags = spawnOriginTags(process.env, "claude");
+  let metadata = {
+    path: workingDirectory,
+    host: os.hostname(),
+    version: packageJson.version,
+    os: os.platform(),
+    machineId,
+    homeDir: os.homedir(),
+    happyHomeDir: configuration.happyHomeDir,
+    happyLibDir: projectPath(),
+    happyToolsDir: resolve(projectPath(), "tools", "unpacked"),
+    startedFromDaemon: options.startedBy === "daemon",
+    hostPid: process.pid,
+    startedBy: options.startedBy || "terminal",
+    // Initialize lifecycle state
+    lifecycleState: "running",
+    lifecycleStateSince: Date.now(),
+    flavor: "claude",
+    ...process.env.VH_TEAM_OPERATION_ID ? { teamOperationId: process.env.VH_TEAM_OPERATION_ID } : {},
+    // Advertise composer support before the first SDK response. Otherwise
+    // a brand-new session cannot pick a PDF until after sending once.
+    attachmentKinds: [...CLAUDE_ATTACHMENT_KINDS],
+    queueCancellation: true,
+    capabilities: ["claude-steer-v1", "claude-live-permission-v1", "claude-live-permission-v2", "claude-btw-v1", "claude-runtime-controls-v1", "claude-opus-5-5-v1", PROMPT_QUEUE_CAPABILITY],
+    // Effective mode this process enforces. Kept current by
+    // publishPermissionMode below; the web renders it instead of guessing.
+    permissionMode: mapToClaudeMode(initialPermissionMode ?? "default"),
+    sandbox: sandboxConfig?.enabled ? sandboxConfig : null,
+    dangerouslySkipPermissions,
+    ...forkedFromSessionId ? { parentSessionId: forkedFromSessionId } : {},
+    ...forkedFromMessageId ? { forkedFromMessageId } : {},
+    ...importedFromClaudeSessionId ? { importedFromClaudeSessionId } : {},
+    ...importTitle ? { summary: { text: importTitle, updatedAt: Date.now() } } : {},
+    ...isAssistantVariant ? { variant: "assistant" } : {},
+    // B-091/B-303: dispatched sessions (daemon spawn RPC exports
+    // HAPPY_SPAWNED_BY, B-069) are born tagged with their spawn origin so
+    // every list shows where the work came from. NOT on the meta-agent
+    // itself — that one is the variant above and never joins the lists at
+    // all. (Shared helper: the other flavors get the same tag via
+    // createSessionMetadata.)
+    ...originTags ? { tags: originTags } : {}
+  };
+  const reconnectSessionId = process.env.HAPPY_RECONNECT_SESSION_ID;
+  const reconnectKeyBase64 = process.env.HAPPY_RECONNECT_ENCRYPTION_KEY;
+  const reconnectVariant = process.env.HAPPY_RECONNECT_ENCRYPTION_VARIANT;
+  const reconnectSeq = process.env.HAPPY_RECONNECT_SEQ;
+  const reconnectMetadataVersion = process.env.HAPPY_RECONNECT_METADATA_VERSION;
+  const reconnectAgentStateVersion = process.env.HAPPY_RECONNECT_AGENT_STATE_VERSION;
+  let response;
+  if (reconnectSessionId && reconnectKeyBase64 && reconnectVariant) {
+    logger.debug(`[START] Reconnecting to existing session ${reconnectSessionId}`);
+    response = {
+      id: reconnectSessionId,
+      seq: parseInt(reconnectSeq || "0", 10),
+      encryptionKey: decodeBase64(reconnectKeyBase64),
+      encryptionVariant: reconnectVariant,
+      metadata,
+      metadataVersion: parseInt(reconnectMetadataVersion || "0", 10),
+      agentState: state,
+      agentStateVersion: parseInt(reconnectAgentStateVersion || "0", 10)
+    };
+  } else {
+    response = await api.getOrCreateSession({ tag: sessionTag, metadata, state });
+  }
+  if (!response) {
+    let offlineSessionId = null;
+    const { claudeLocal } = await import('./claudeLocal-BaY4fZKi.mjs');
+    const { createSessionScanner: createSessionScanner2 } = await depsLoad;
+    const reconnection = startOfflineReconnection({
+      serverUrl: configuration.serverUrl,
+      onReconnected: async () => {
+        const resp = await api.getOrCreateSession({ tag: randomUUID(), metadata, state });
+        if (!resp) throw new Error("Server unavailable");
+        const session2 = api.sessionSyncClient(resp);
+        const scanner = await createSessionScanner2({
+          sessionId: null,
+          workingDirectory,
+          onMessage: (msg) => session2.sendClaudeSessionMessage(msg)
+        });
+        if (offlineSessionId) scanner.onNewSession(offlineSessionId);
+        return { session: session2, scanner };
+      },
+      onNotify: console.log,
+      onCleanup: () => {
+      }
+    });
+    try {
+      await claudeLocal({
+        path: workingDirectory,
+        sessionId: null,
+        onSessionFound: (id) => {
+          offlineSessionId = id;
+        },
+        onThinkingChange: () => {
+        },
+        abort: new AbortController().signal,
+        claudeEnvVars: options.claudeEnvVars,
+        claudeArgs: options.claudeArgs,
+        mcpServers: {},
+        allowedTools: [],
+        sandboxConfig
+      });
+    } finally {
+      reconnection.cancel();
+    }
+    process.exit(0);
+  }
+  logger.debug(`Session created: ${response.id}`);
+  await claimSessionOrExit(response.id, { takeover: !!reconnectSessionId, flavor: "claude" });
+  if (reconnectSessionId && !await api.reactivateSession(response.id)) {
+    throw new Error(`Failed to reactivate archived session ${response.id}`);
+  }
+  let reconnectSeeded = false;
+  if (reconnectSessionId) {
+    const snapshot = await api.getSession(response.id, response.encryptionKey, response.encryptionVariant);
+    if (snapshot.ok) {
+      response = applyServerSnapshot(response, snapshot.session);
+      reconnectSeeded = true;
+      logger.debug(`[START] Reconnect seeded from server: seq=${snapshot.session.seq} metadataVersion=${snapshot.session.metadataVersion}`);
+    } else {
+      response = withoutServerSnapshot(response);
+      logger.debug(`[START] Reconnect without server snapshot (${snapshot.reason}); skipping existing messages`);
+    }
+  }
+  const earlySession = startupPlan.sessionClientBeforeWebhook ? api.sessionSyncClient(response) : null;
+  try {
+    logger.debug(`[START] Reporting session ${response.id} to daemon`);
+    const result = await notifyDaemonSessionStarted(response.id, metadata, {
+      encryptionKey: encodeBase64(response.encryptionKey),
+      encryptionVariant: response.encryptionVariant,
+      seq: response.seq,
+      metadataVersion: response.metadataVersion,
+      agentStateVersion: response.agentStateVersion
+    });
+    if (result.error) {
+      logger.debug(`[START] Failed to report to daemon (may not be running):`, result.error);
+    } else {
+      logger.debug(`[START] Reported session ${response.id} to daemon`);
+    }
+  } catch (error) {
+    logger.debug("[START] Failed to report to daemon (may not be running):", error);
+  }
+  if (!startupPlan.registerMachine) {
+    void Promise.resolve().then(() => api.getOrCreateMachine({ machineId, metadata: getInitialMachineMetadata() })).catch((error) => logger.debug("[START] Background machine registration failed:", error));
+  }
+  let deps;
+  try {
+    deps = await depsLoad;
+  } catch (error) {
+    logger.warn(`[START] Failed to load the Claude runner modules for session ${response.id}; marking it offline and exiting: ${error instanceof Error ? error.message : String(error)}`);
+    try {
+      await earlySession?.close();
+    } catch {
+    }
+    try {
+      await api.deactivateSession(response.id);
+    } catch {
+    }
+    process.exit(1);
+  }
+  const {
+    loop,
+    MessageQueue2,
+    claudeModeHash,
+    parseSpecialCommand,
+    getEnvironmentInfo,
+    startHappyServer,
+    startHookServer,
+    EditReportThrottle,
+    extractClaudeEditPaths,
+    reportSessionEditToDaemon,
+    generateHookSettingsFile,
+    cleanupHookSettingsFile,
+    registerKillSessionHandler,
+    SessionExitGate,
+    exitIntentFromArchiveFlag,
+    settleSessionOnExit,
+    registerSideQuestionHandler,
+    writeSideQuestionSettingsFile,
+    claudeCheckSession,
+    createSessionScanner,
+    getProjectPath,
+    RawJSONLinesSchema,
+    TitleGenerator,
+    BoardAnalyzer,
+    FileRateLimiter,
+    createSelfReportState,
+    withAssistantDenylist,
+    contentLogMetadata
+  } = deps;
+  logger.debugLargeJson("[START] Happy process started", getEnvironmentInfo());
+  const session = earlySession ?? api.sessionSyncClient(response, reconnectSeeded ? { initialSeq: response.seq } : void 0);
+  if (reconnectSessionId) {
+    session.suppressNextArchiveSignal();
+    if (!reconnectSeeded) session.skipExistingMessages();
+    void session.cancelUndeliveredQueuedInputs();
+    session.updateMetadata((meta) => ({
+      ...mergeReconnectMetadata(meta, metadata, Date.now()),
+      queueCancellation: true,
+      // B-262 batch 2 (B5): a reconnected process re-publishes the mode
+      // IT enforces; the server copy may still carry the previous
+      // process's value.
+      permissionMode: mapToClaudeMode(initialPermissionMode ?? "default")
+    }));
+  }
+  const forkClaudeSessionId = process.env.HAPPY_FORK_CLAUDE_SESSION_ID;
+  if (!reconnectSessionId && forkClaudeSessionId) {
+    const jsonlPath = join(getProjectPath(workingDirectory), `${forkClaudeSessionId}.jsonl`);
+    try {
+      const file = await readFile(jsonlPath, "utf-8");
+      const lines = file.split("\n");
+      let backfilled = 0;
+      for (const line of lines) {
+        if (line.trim().length === 0) continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        const result = RawJSONLinesSchema.safeParse(parsed);
+        if (!result.success) continue;
+        session.sendClaudeSessionMessage(result.data);
+        backfilled += 1;
+      }
+      logger.debug(`[FORK BACKFILL] Replayed ${backfilled} historical messages from ${jsonlPath}`);
+      session.updateMetadata((meta) => ({ ...meta, claudeSessionId: forkClaudeSessionId }));
+    } catch (error) {
+      logger.debug(`[FORK BACKFILL] Failed to read ${jsonlPath}:`, error);
+    }
+  }
+  const recentAppPromptsMaxAgeMs = 5 * 60 * 1e3;
+  const recentAppPrompts = [];
+  const promptDedupeKey = (text) => stripAttachmentManifest(text).trim();
+  const recordAppPrompt = (text) => {
+    const now = Date.now();
+    recentAppPrompts.push({ text: promptDedupeKey(text), addedAt: now });
+    const cutoff = now - recentAppPromptsMaxAgeMs;
+    while (recentAppPrompts.length > 0 && recentAppPrompts[0].addedAt < cutoff) {
+      recentAppPrompts.shift();
+    }
+  };
+  const consumeAppPrompt = (text) => {
+    const cutoff = Date.now() - recentAppPromptsMaxAgeMs;
+    const key = promptDedupeKey(text);
+    for (let i = 0; i < recentAppPrompts.length; i++) {
+      const entry = recentAppPrompts[i];
+      if (entry.addedAt < cutoff) continue;
+      if (entry.text === key) {
+        recentAppPrompts.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  };
+  let currentRunMode = options.startingMode ?? "local";
+  const titleGenerator = new TitleGenerator(session);
+  const boardSelfReport = createSelfReportState();
+  const boardAnalyzer = new BoardAnalyzer(session, {
+    enabled: settings?.boardLlm === true,
+    selfReportState: boardSelfReport,
+    fetchTasks: async () => {
+      const item = await api.kvGet("vh.board-tasks.v1");
+      if (!item) return null;
+      try {
+        const parsed = JSON.parse(Buffer.from(item.value, "base64").toString("utf8"));
+        if (!Array.isArray(parsed.tasks)) return null;
+        return parsed.tasks.filter((t) => typeof t?.id === "string" && typeof t?.title === "string" && t.status === "open").map((t) => ({ id: t.id, title: t.title }));
+      } catch {
+        return null;
+      }
+    },
+    rateLimiter: new FileRateLimiter(resolve(configuration.happyHomeDir, "board-analyzer-rate.json"))
+  });
+  session.on("claude-session-message", (body) => boardAnalyzer.noteClaudeMessage(body));
+  session.on("turn-ended", () => boardAnalyzer.onTurnEnd());
+  const editThrottle = new EditReportThrottle();
+  session.on("claude-session-message", (body) => {
+    try {
+      for (const edit of editThrottle.take(extractClaudeEditPaths(body))) {
+        reportSessionEditToDaemon({ sessionId: response.id, path: edit.path, tool: edit.tool, cwd: workingDirectory, ...edit.at !== void 0 ? { at: edit.at } : {} });
+      }
+    } catch (error) {
+      logger.debug("[START] edit report failed:", error);
+    }
+  });
+  options = { ...options, claudeEnvVars: { ...options.claudeEnvVars, VH_PEER_SESSION_ID: response.id } };
+  const initialScannerSessionId = forkClaudeSessionId ?? (metadata.claudeSessionId ?? null);
+  const remoteScanner = await createSessionScanner({
+    sessionId: initialScannerSessionId,
+    workingDirectory,
+    onMessage: (raw) => {
+      if (currentRunMode !== "remote") return;
+      if (raw.type !== "user") return;
+      if (raw.isSidechain) return;
+      const content = raw.message?.content;
+      if (typeof content !== "string") return;
+      if (content.trim().length === 0) return;
+      if (consumeAppPrompt(content)) return;
+      titleGenerator.maybeGenerate(content);
+      boardAnalyzer.noteUserMessage(content);
+      session.sendClaudeSessionMessage(raw);
+    }
+  });
+  const happyServer = await startHappyServer(session, { assistant: isAssistantVariant, selfReportState: boardSelfReport });
+  logger.debug(`[START] Happy MCP server started at ${happyServer.url}`);
+  let currentSession = null;
+  const hookServer = await startHookServer({
+    onSessionHook: (sessionId, data) => {
+      logger.debug(`[START] Session hook received: ${sessionId}`, contentLogMetadata(data));
+      remoteScanner.onNewSession(sessionId, { treatExistingAsProcessed: true });
+      if (currentSession) {
+        const previousSessionId = currentSession.sessionId;
+        if (previousSessionId !== sessionId) {
+          logger.debug(`[START] Claude session ID changed: ${previousSessionId} -> ${sessionId}`);
+          currentSession.onSessionFound(sessionId);
+        }
+      }
+    }
+  });
+  logger.debug(`[START] Hook server started on port ${hookServer.port}`);
+  const hookSettingsPath = generateHookSettingsFile(hookServer.port);
+  logger.debug(`[START] Generated hook settings file: ${hookSettingsPath}`);
+  const logPath = logger.logFilePath;
+  logger.infoDeveloper(`Session: ${response.id}`);
+  logger.infoDeveloper(`Logs: ${logPath}`);
+  session.updateAgentState((currentState) => ({
+    ...currentState,
+    controlledByUser: options.startingMode !== "remote"
+  }));
+  const messageQueue = new MessageQueue2(claudeModeHash);
+  const promptQueueDrain = session.attachPromptQueueDrain({
+    isIdle: () => messageQueue.size() === 0 && messageQueue.isWaiting()
+  });
+  messageQueue.setOnWait(() => promptQueueDrain.onIdle());
+  messageQueue.setOnDiscard((entries) => {
+    const byReason = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      if (!entry.sourceId) continue;
+      const list = byReason.get(entry.reason) ?? [];
+      list.push(entry.sourceId);
+      byReason.set(entry.reason, list);
+    }
+    for (const [reason, keys] of byReason) session.sendQueueCancelReason(keys, reason);
+  });
+  session.rpcHandlerManager.registerHandler("cancelQueuedMessage", async (params) => ({
+    removed: messageQueue.cancelPending(
+      typeof params?.localKey === "string" ? params.localKey : void 0,
+      typeof params?.text === "string" ? params.text : void 0
+    )
+  }));
+  let currentPermissionMode = initialPermissionMode;
+  let publishedPermissionMode = mapToClaudeMode(initialPermissionMode ?? "default");
+  const publishPermissionMode = (mode) => {
+    currentPermissionMode = mode;
+    const published = mapToClaudeMode(mode ?? "default");
+    if (published === publishedPermissionMode) return;
+    publishedPermissionMode = published;
+    session.updateMetadata((meta) => ({ ...meta, permissionMode: published }));
+  };
+  const publishEffectivePermissionMode = (effective) => {
+    const decision = reconcilePublishedPermissionMode({
+      intent: mapToClaudeMode(currentPermissionMode ?? "default"),
+      published: publishedPermissionMode,
+      effective
+    });
+    if (!decision) return;
+    if (decision.mismatch) {
+      logger.warn(`[loop] Claude Code enforces permission mode '${effective}' but this process asked for '${mapToClaudeMode(currentPermissionMode ?? "default")}' \u2014 check ~/.claude settings (permissions.deny/ask/defaultMode/disableBypassPermissionsMode). Publishing the effective mode.`);
+    }
+    if (decision.publish !== publishedPermissionMode) {
+      publishedPermissionMode = decision.publish;
+      session.updateMetadata((meta) => ({ ...meta, permissionMode: decision.publish }));
+    }
+  };
+  let lastExplicitModeSwitchAt = 0;
+  let currentModel = options.model ?? DEFAULT_CLAUDE_MODEL;
+  let currentFallbackModel = void 0;
+  let currentCustomSystemPrompt = void 0;
+  let currentAppendSystemPrompt = void 0;
+  let currentAllowedTools = void 0;
+  let currentDisallowedTools = withAssistantDenylist(void 0, isAssistantVariant);
+  let currentEffort = DEFAULT_CLAUDE_EFFORT;
+  registerSideQuestionHandler(session.rpcHandlerManager, {
+    getClaudeSessionId: () => {
+      const id = currentSession?.sessionId ?? null;
+      return id && claudeCheckSession(id, workingDirectory) ? id : null;
+    },
+    getModel: () => currentModel,
+    cwd: workingDirectory,
+    getEnv: () => options.claudeEnvVars,
+    settingsPath: writeSideQuestionSettingsFile(configuration.happyHomeDir),
+    // B-482: in remote mode the launcher parks the live Query's /btw entry
+    // on the session while the Query is alive; local mode never sets it.
+    getLiveQuery: () => currentSession?.getSideQuestionLive() ?? null
+  });
+  const resetCurrentModeDefaults = () => {
+    currentModel = options.model ?? DEFAULT_CLAUDE_MODEL;
+    currentFallbackModel = void 0;
+    currentCustomSystemPrompt = void 0;
+    currentAppendSystemPrompt = void 0;
+    currentAllowedTools = void 0;
+    currentDisallowedTools = withAssistantDenylist(void 0, isAssistantVariant);
+    currentEffort = DEFAULT_CLAUDE_EFFORT;
+    logger.debug("[loop] Reset current mode defaults after abort");
+  };
+  session.onFileEvent((fileEvent) => {
+    const ev = fileEvent.content.data.ev;
+    logger.debug(`[loop] File event received: ${ev.name} (${ev.size} bytes, ref: ${ev.ref})`);
+    const downloadPromise = (async () => {
+      try {
+        const decrypted = await session.downloadAndDecryptAttachment(ev.ref);
+        if (!decrypted) {
+          logger.debug(`[loop] Failed to decrypt attachment: ${ev.name}`);
+          return null;
+        }
+        logger.debug(`[loop] Attachment decrypted: ${ev.name} (${decrypted.length} bytes)`);
+        return { data: decrypted, mimeType: ev.mimeType ?? "image/jpeg", name: ev.name };
+      } catch (error) {
+        logger.debug(`[loop] Failed to download attachment: ${ev.name}`, { error });
+        return null;
+      }
+    })();
+    session.trackAttachmentDownload(downloadPromise);
+  });
+  session.onUserMessage(async (message) => {
+    if (message?.content?.text) {
+      titleGenerator.maybeGenerate(message.content.text);
+      boardAnalyzer.noteUserMessage(message.content.text);
+    }
+    const attachmentsForThisMessage = await session.drainAttachmentsForUserMessage();
+    let messagePermissionMode = currentPermissionMode;
+    const messageCreatedAt = message.createdAt;
+    const staleModeSnapshot = message.meta?.permissionMode !== void 0 && typeof messageCreatedAt === "number" && messageCreatedAt < lastExplicitModeSwitchAt;
+    if (staleModeSnapshot) {
+      logger.debug(`[loop] Ignoring stale meta.permissionMode=${message.meta?.permissionMode} (message ${messageCreatedAt} predates explicit switch ${lastExplicitModeSwitchAt}); keeping ${currentPermissionMode}`);
+    } else if (message.meta?.permissionMode) {
+      const previousPermissionMode = currentPermissionMode;
+      messagePermissionMode = resolveRemoteClaudePermissionMode(
+        currentPermissionMode,
+        message.meta.permissionMode,
+        sandboxEnabled
+      );
+      publishPermissionMode(messagePermissionMode);
+      const ignoredDefaultDowngrade = (previousPermissionMode === "bypassPermissions" || previousPermissionMode === "yolo") && message.meta.permissionMode === "default" && currentPermissionMode === previousPermissionMode;
+      if (ignoredDefaultDowngrade) {
+        logger.debug(`[loop] Ignoring permission mode downgrade from ${previousPermissionMode} to default`);
+      } else {
+        logger.debug(`[loop] Permission mode updated from user message to: ${currentPermissionMode}`);
+      }
+    } else {
+      logger.debug(`[loop] User message received with no permission mode override, using current: ${currentPermissionMode}`);
+    }
+    let messageModel = currentModel;
+    if (message.meta?.hasOwnProperty("model")) {
+      messageModel = message.meta.model || void 0;
+      currentModel = messageModel;
+      logger.debug(`[loop] Model updated from user message: ${messageModel || "reset to default"}`);
+    } else {
+      logger.debug(`[loop] User message received with no model override, using current: ${currentModel || "default"}`);
+    }
+    let messageCustomSystemPrompt = currentCustomSystemPrompt;
+    if (message.meta?.hasOwnProperty("customSystemPrompt")) {
+      messageCustomSystemPrompt = message.meta.customSystemPrompt || void 0;
+      currentCustomSystemPrompt = messageCustomSystemPrompt;
+      logger.debug(`[loop] Custom system prompt updated from user message: ${messageCustomSystemPrompt ? "set" : "reset to none"}`);
+    } else {
+      logger.debug(`[loop] User message received with no custom system prompt override, using current: ${currentCustomSystemPrompt ? "set" : "none"}`);
+    }
+    let messageFallbackModel = currentFallbackModel;
+    if (message.meta?.hasOwnProperty("fallbackModel")) {
+      messageFallbackModel = message.meta.fallbackModel || void 0;
+      currentFallbackModel = messageFallbackModel;
+      logger.debug(`[loop] Fallback model updated from user message: ${messageFallbackModel || "reset to none"}`);
+    } else {
+      logger.debug(`[loop] User message received with no fallback model override, using current: ${currentFallbackModel || "none"}`);
+    }
+    let messageAppendSystemPrompt = currentAppendSystemPrompt;
+    if (message.meta?.hasOwnProperty("appendSystemPrompt")) {
+      messageAppendSystemPrompt = message.meta.appendSystemPrompt || void 0;
+      currentAppendSystemPrompt = messageAppendSystemPrompt;
+      logger.debug(`[loop] Append system prompt updated from user message: ${messageAppendSystemPrompt ? "set" : "reset to none"}`);
+    } else {
+      logger.debug(`[loop] User message received with no append system prompt override, using current: ${currentAppendSystemPrompt ? "set" : "none"}`);
+    }
+    let messageAllowedTools = currentAllowedTools;
+    if (message.meta?.hasOwnProperty("allowedTools")) {
+      messageAllowedTools = message.meta.allowedTools || void 0;
+      currentAllowedTools = messageAllowedTools;
+      logger.debug(`[loop] Allowed tools updated from user message: ${messageAllowedTools ? messageAllowedTools.join(", ") : "reset to none"}`);
+    } else {
+      logger.debug(`[loop] User message received with no allowed tools override, using current: ${currentAllowedTools ? currentAllowedTools.join(", ") : "none"}`);
+    }
+    let messageDisallowedTools = currentDisallowedTools;
+    if (message.meta?.hasOwnProperty("disallowedTools")) {
+      messageDisallowedTools = withAssistantDenylist(message.meta.disallowedTools || void 0, isAssistantVariant);
+      currentDisallowedTools = messageDisallowedTools;
+      logger.debug(`[loop] Disallowed tools updated from user message: ${messageDisallowedTools ? messageDisallowedTools.join(", ") : "reset to none"}`);
+    } else {
+      logger.debug(`[loop] User message received with no disallowed tools override, using current: ${currentDisallowedTools ? currentDisallowedTools.join(", ") : "none"}`);
+    }
+    let messageEffort = currentEffort;
+    const VALID_EFFORTS = /* @__PURE__ */ new Set(["low", "medium", "high", "xhigh", "max"]);
+    if (message.meta?.hasOwnProperty("effort")) {
+      const incoming = message.meta.effort;
+      if (incoming === null || incoming === void 0) {
+        messageEffort = void 0;
+        currentEffort = void 0;
+        logger.debug(`[loop] Effort reset to default`);
+      } else if (typeof incoming === "string" && VALID_EFFORTS.has(incoming)) {
+        messageEffort = incoming;
+        currentEffort = messageEffort;
+        logger.debug(`[loop] Effort updated from user message: ${messageEffort}`);
+      } else {
+        logger.debug(`[loop] Ignoring invalid effort from user message: ${String(incoming)}`);
+      }
+    } else {
+      logger.debug(`[loop] User message received with no effort override, using current: ${currentEffort ?? "default"}`);
+    }
+    const specialCommand = parseSpecialCommand(message.content.text);
+    if (specialCommand.type === "compact") {
+      logger.debug("[start] Detected /compact command");
+      const enhancedMode2 = {
+        permissionMode: messagePermissionMode || "default",
+        model: messageModel,
+        fallbackModel: messageFallbackModel,
+        customSystemPrompt: messageCustomSystemPrompt,
+        appendSystemPrompt: messageAppendSystemPrompt,
+        allowedTools: messageAllowedTools,
+        disallowedTools: messageDisallowedTools,
+        effort: messageEffort
+      };
+      messageQueue.pushIsolateAndClear(specialCommand.originalMessage || message.content.text, enhancedMode2, attachmentsForThisMessage, message.localKey);
+      logger.debug("[start] /compact command pushed to queue:", {
+        ...contentLogMetadata(message.content.text),
+        attachmentCount: attachmentsForThisMessage?.length ?? 0,
+        hasMetadata: Boolean(message.meta)
+      });
+      return;
+    }
+    if (specialCommand.type === "clear") {
+      logger.debug("[start] Detected /clear command");
+      const enhancedMode2 = {
+        permissionMode: messagePermissionMode || "default",
+        model: messageModel,
+        fallbackModel: messageFallbackModel,
+        customSystemPrompt: messageCustomSystemPrompt,
+        appendSystemPrompt: messageAppendSystemPrompt,
+        allowedTools: messageAllowedTools,
+        disallowedTools: messageDisallowedTools,
+        effort: messageEffort
+      };
+      messageQueue.pushIsolateAndClear(specialCommand.originalMessage || message.content.text, enhancedMode2, attachmentsForThisMessage, message.localKey);
+      logger.debug("[start] /clear command pushed to queue:", {
+        ...contentLogMetadata(message.content.text),
+        attachmentCount: attachmentsForThisMessage?.length ?? 0,
+        hasMetadata: Boolean(message.meta)
+      });
+      return;
+    }
+    if (specialCommand.type === "mcp" || specialCommand.type === "skills") {
+      if (currentRunMode === "local") {
+        logger.debug(`[start] /${specialCommand.type} in local mode \u2014 passing through to Claude Code`);
+      } else {
+        logger.debug(`[start] Detected /${specialCommand.type} command in remote mode`);
+        const metadata2 = session.getMetadata();
+        let responseText;
+        if (specialCommand.type === "mcp") {
+          const servers = metadata2?.mcpServers;
+          if (servers && servers.length > 0) {
+            responseText = "**MCP Servers**\n\n" + servers.map((s) => `- **${s.name}** \u2014 ${s.status}`).join("\n");
+          } else {
+            responseText = "No MCP servers configured. Session may still be initializing \u2014 try again after sending a message.";
+          }
+        } else {
+          const skills = metadata2?.skills ?? metadata2?.slashCommands;
+          if (skills && skills.length > 0) {
+            responseText = "**Available Skills**\n\n" + skills.map((s) => `- /${s}`).join("\n");
+          } else {
+            responseText = "No skills available. Session may still be initializing \u2014 try again after sending a message.";
+          }
+        }
+        session.sendClaudeSessionMessage({
+          type: "assistant",
+          uuid: randomUUID(),
+          parentUuid: null,
+          isSidechain: false,
+          sessionId: session.sessionId || "unknown",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          message: {
+            role: "assistant",
+            model: "system",
+            content: [{ type: "text", text: responseText }]
+          }
+        });
+        return;
+      }
+    }
+    const enhancedMode = {
+      permissionMode: messagePermissionMode || "default",
+      model: messageModel,
+      fallbackModel: messageFallbackModel,
+      customSystemPrompt: messageCustomSystemPrompt,
+      appendSystemPrompt: messageAppendSystemPrompt,
+      allowedTools: messageAllowedTools,
+      disallowedTools: messageDisallowedTools,
+      effort: messageEffort
+    };
+    if (message.meta?.delivery === "steer" && currentRunMode === "remote") {
+      const accepted = await currentSession?.trySteer({
+        message: message.content.text,
+        mode: enhancedMode,
+        attachments: attachmentsForThisMessage
+      }) === true;
+      if (accepted) {
+        logger.debug("User message steered into current turn:", {
+          ...contentLogMetadata(message.content.text),
+          attachmentCount: attachmentsForThisMessage?.length ?? 0
+        });
+        return;
+      }
+      logger.debug("[start] Steer arrived without a compatible live turn; falling back to queue");
+    }
+    messageQueue.push(message.content.text, enhancedMode, attachmentsForThisMessage, message.localKey);
+    logger.debug("User message pushed to queue:", {
+      ...contentLogMetadata(message.content.text),
+      attachmentCount: attachmentsForThisMessage?.length ?? 0,
+      hasMetadata: Boolean(message.meta)
+    });
+  });
+  const exitGate = new SessionExitGate();
+  const cleanup = async (opts = { archive: true }) => {
+    const intent = exitGate.claim(exitIntentFromArchiveFlag(opts.archive));
+    if (intent === null) {
+      logger.debug(`[START] Termination (archive=${opts.archive ?? true}) ignored: cleanup already running as ${exitGate.current}`);
+      return;
+    }
+    logger.debug(`[START] Received termination signal, cleaning up (archive=${intent === "archive"})...`);
+    promptQueueDrain.close();
+    try {
+      if (session) {
+        currentSession?.cleanup();
+        await settleSessionOnExit(session.sessionId, intent, {
+          updateMetadata: (handler) => session.updateMetadata(handler),
+          sendSessionDeath: () => session.sendSessionDeath(),
+          archiveSession: (id) => api.archiveSession(id),
+          deactivateSession: (id) => api.deactivateSession(id),
+          log: (message, ...args) => logger.debug(message, ...args)
+        });
+        await session.flush();
+        await session.close();
+      }
+      happyServer.stop();
+      hookServer.stop();
+      cleanupHookSettingsFile(hookSettingsPath);
+      await remoteScanner.cleanup();
+      logger.debug("[START] Cleanup complete, exiting");
+      process.exit(0);
+    } catch (error) {
+      logger.debug("[START] Error during cleanup:", error);
+      process.exit(1);
+    }
+  };
+  process.on("SIGTERM", () => {
+    void cleanup({ archive: false });
+  });
+  process.on("SIGINT", () => {
+    void cleanup({ archive: false });
+  });
+  process.on("uncaughtException", (error) => {
+    logger.debug("[START] Uncaught exception:", error);
+    if (currentSession?.isAborting()) {
+      logger.debug("[START] Uncaught exception during abort teardown \u2014 swallowing, not archiving");
+      return;
+    }
+    void cleanup({ archive: true });
+  });
+  process.on("unhandledRejection", (reason) => {
+    logger.debug("[START] Unhandled rejection:", reason);
+    if (currentSession?.isAborting()) {
+      logger.debug("[START] Unhandled rejection during abort teardown \u2014 swallowing, not archiving");
+      return;
+    }
+    void cleanup({ archive: true });
+  });
+  registerKillSessionHandler(session.rpcHandlerManager, () => cleanup({ archive: true }), session);
+  const exitCode = await loop({
+    path: workingDirectory,
+    model: options.model,
+    permissionMode: initialPermissionMode,
+    startingMode: options.startingMode,
+    messageQueue,
+    api,
+    allowedTools: happyServer.toolNames.map((toolName) => `mcp__happy__${toolName}`),
+    onModeChange: (newMode) => {
+      currentRunMode = newMode;
+      session.sendSessionEvent({ type: "switch", mode: newMode });
+      session.updateAgentState((currentState) => ({
+        ...currentState,
+        controlledByUser: newMode === "local"
+      }));
+    },
+    onSessionReady: (sessionInstance) => {
+      currentSession = sessionInstance;
+    },
+    // B-355: remember exactly what the SDK is about to write to the Claude
+    // transcript, so the JSONL scanner below recognises it as ours.
+    onPromptFinalized: recordAppPrompt,
+    onAbort: resetCurrentModeDefaults,
+    onPermissionModeChange: (mode) => {
+      lastExplicitModeSwitchAt = Date.now();
+      publishPermissionMode(mode);
+      logger.debug(`[loop] Permission mode updated from session RPC / approval to: ${mode}`);
+    },
+    onEffectivePermissionMode: (mode) => publishEffectivePermissionMode(mode),
+    mcpServers: {
+      "happy": {
+        type: "http",
+        url: happyServer.url
+      }
+    },
+    session,
+    claudeEnvVars: options.claudeEnvVars,
+    claudeArgs: options.claudeArgs,
+    sandboxConfig,
+    hookSettingsPath,
+    jsRuntime: options.jsRuntime
+  });
+  currentSession?.cleanup();
+  session.sendSessionDeath();
+  logger.debug("Waiting for socket to flush...");
+  await session.flush();
+  logger.debug("Closing session...");
+  await session.close();
+  happyServer.stop();
+  logger.debug("Stopped Happy MCP server");
+  hookServer.stop();
+  cleanupHookSettingsFile(hookSettingsPath);
+  logger.debug("Stopped Hook server and cleaned up settings file");
+  process.exit(exitCode);
+}
+
+export { runClaude };