botmux 3.10.0 → 3.23.1

package/dist/core/worker-pool.d.ts

@@ -1,788 +0,0 @@
-/**
- * Worker pool — manages forking, killing, and lifecycle of worker processes.
- * Extracted from daemon.ts for modularity.
- */
-import { type ChildProcess } from 'node:child_process';
-import { type CardUsageSnapshot } from '../im/lark/md-card.js';
-import { killPersistentBackendTarget } from './persistent-backend.js';
-import { type RestartObserver } from './restart-coordinator.js';
-/** Symmetric lifecycle fence: relay must not start while another operation is
- * still restarting, spawning, suspending, or closing this worker generation. */
-export declare function isSessionLifecycleInFlight(ds: DaemonSession): boolean;
-export declare function getDaemonBootId(): string;
-/** Read one frozen native-usage snapshot at the reply boundary. Card delivery
- * remains best-effort even when a CLI has no supported transcript or a usage
- * resolver fails. */
-export declare function getDaemonSessionUsageSnapshot(ds: DaemonSession, effectiveCliId?: CliId, opts?: {
-    fresh?: boolean;
-}): CardUsageSnapshot;
-/** Reply-card (final output / adopt preamble / local-turn) usage. Only the
- * `'footer'` display mode surfaces usage here; `'streaming'` and `'off'` yield a
- * concrete empty snapshot. Keeping the display decision out of the native usage
- * reader leaves accounting and dashboard consumers intact; the concrete empty
- * snapshot (rather than undefined) also freezes "hidden" over final-output
- * retries. */
-export declare function getDaemonReplyCardUsageSnapshot(ds: DaemonSession, effectiveCliId?: CliId): CardUsageSnapshot;
-/** Streaming-card usage. Only the `'streaming'` display mode (the default)
- * surfaces usage in the live card body; `'footer'` and `'off'` yield empty.
- * Returns a concrete empty snapshot on any config failure so the streaming
- * renderer stays best-effort. `fresh` forces an exact read at meaningful
- * boundaries (turn end / idle); intra-turn ticks leave it false to ride the
- * reader's reparse throttle and stay off the disk. */
-export declare function getDaemonStreamingCardUsageSnapshot(ds: DaemonSession, effectiveCliId?: CliId, opts?: {
-    fresh?: boolean;
-}): CardUsageSnapshot;
-import type { CliId } from '../adapters/cli/types.js';
-import type { CliTurnPayload, DaemonToWorker, WorkerToDaemon, Session } from '../types.js';
-import { type DaemonSession } from './types.js';
-import { type CliUsageLimitState } from '../utils/cli-usage-limit.js';
-import { type VcMeetingListenerTopicKey } from '../services/vc-meeting-listener-topic-store.js';
-type WorkerStartupState = {
-    ready: boolean;
-    failureNotified: boolean;
-    /** Init turn attribution frozen at fork. A durable VC delivery is dispatched
-     *  (queued) into a not-yet-ready worker; if that worker dies before ready
-     *  (fork ENOENT, syntax/import crash, abrupt exit) the fork-level `error` and
-     *  pre-ready `exit` paths must route the failure through the same receipt/lease
-     *  gate as a structured error, not reply out-of-band. */
-    initTurnId?: string;
-    initDispatchAttempt?: number;
-};
-export declare const TRANSFER_DETACH_FENCE_PICKER_MS = 8000;
-export interface WorkerSessionReplyOptions {
-    uuid?: string;
-    quoteMessageId?: string;
-    beforeQuoteFallback?: () => void | Promise<void>;
-    /** Do not fan meeting-derived content out through user-configured outbound
-     * hooks. Dedicated VC replies have one audited external effect: Lark. */
-    suppressHook?: boolean;
-    /** Exact daemon session that produced this output. Dedicated VC receivers
-     * share a visible chat anchor with ordinary sessions, so the anchor alone
-     * cannot identify the transcript/lifecycle owner. */
-    sourceSessionId?: string;
-    /** Automatic VC delivery presentation. Explicit human IM replies omit this
-     * and continue to follow their quote/thread context. */
-    placement?: 'auto' | 'chat' | 'topic';
-    meetingTopicKey?: VcMeetingListenerTopicKey;
-}
-export interface WorkerPoolCallbacks {
-    sessionReply: (rootId: string, content: string, msgType?: string, larkAppId?: string, turnId?: string, opts?: WorkerSessionReplyOptions) => Promise<string>;
-    getSessionWorkingDir: (ds?: DaemonSession) => string;
-    getActiveCount: () => number;
-    /** Close a stale session (message withdrawn, etc.) */
-    closeSession: (ds: DaemonSession) => void;
-    /** Re-check the per-bot resident-session cap after a process starts or an
-     * over-cap busy session becomes idle. Optional for unit-test callers. */
-    enforceLiveSessionCap?: () => void;
-    /** Durable consumers subscribe to transcript-backed turn completion here.
-     *  Optional so ordinary sessions and tests keep their existing behavior. */
-    onTurnTerminal?: (ds: DaemonSession, terminal: Extract<WorkerToDaemon, {
-        type: 'turn_terminal';
-    }>, context: {
-        workerGeneration: number;
-    }) => void | Promise<void>;
-    /** A hidden fresh-topic schedule can be reclaimed once its exact turn is
-     * settled. Transcript-backed CLIs report `terminal`; screen-only/remote
-     * adapters use the existing debounced idle edge as a compatibility fallback. */
-    onDeferredScheduleTurnSettled?: (ds: DaemonSession, context: {
-        turnId: string;
-        source: 'terminal' | 'idle';
-    }) => void | Promise<void>;
-    /** A process exit makes every unresolved receipt dispatched to this exact
-     *  worker generation ambiguous; the receiver decides retry policy. */
-    onWorkerExit?: (ds: DaemonSession, context: {
-        sessionId: string;
-        workerGeneration: number;
-        code: number | null;
-        signal: NodeJS.Signals | null;
-    }) => void | Promise<void>;
-    /** The managed CLI can crash and auto-restart inside a still-live Node
-     *  worker. Durable receipts dispatched to this generation become ambiguous
-     *  even though `onWorkerExit` will not fire. */
-    onCliExit?: (ds: DaemonSession, context: {
-        sessionId: string;
-        workerGeneration: number;
-        code: number | null;
-        signal: string | null;
-    }) => void | Promise<void>;
-    /** Boot recovery worker confirms its old persistent CLI was fenced before
-     * receiver delivery endpoints may accept a replay. */
-    onReceiverResetReady?: (ds: DaemonSession, context: {
-        sessionId: string;
-        turnId: string;
-        dispatchAttempt: number;
-    }) => void;
-    /** Runtime lease-expiry worker confirms the exact attempt is no longer able
-     * to execute before the receiver accepts its replay. */
-    onDurableExpiryReady?: (ds: DaemonSession, context: {
-        sessionId: string;
-        turnId: string;
-        dispatchAttempt: number;
-        workerGeneration: number;
-        disposition: 'queued_removed' | 'cli_fenced';
-    }) => void;
-}
-/**
- * Initialise worker-pool callbacks. Must be called once before forkWorker().
- */
-export declare function initWorkerPool(cb: WorkerPoolCallbacks): void;
-export declare function setActiveSessionsRegistry(m: Map<string, DaemonSession>): void;
-export declare function listActiveSessions(): DaemonSession[];
-/** Linear-scan lookup of the active-sessions Map by `Session.sessionId`.
- *  The Map's actual key is `sessionKey(rootId, larkAppId)` (composite), so we
- *  cannot use Map.get here. */
-export declare function findActiveBySessionId(sessionId: string): DaemonSession | undefined;
-/** Direct access to the active-sessions Map. Reserved for callers that need
- *  to mutate (e.g. resumeSession reactivating a closed record); read-only
- *  callers should prefer listActiveSessions / findActiveBySessionId. */
-export declare function getActiveSessionsRegistry(): Map<string, DaemonSession> | undefined;
-/**
- * True iff this DaemonSession represents a real CLI-backed conversation
- * that's safe to migrate via /relay. Returns false for daemon-command
- * scratch placeholders (the `worker:null + hasHistory:false` records that
- * daemon.ts creates for /help, an unfinished picker /relay, etc.) — those
- * have no CLI history, no tmux, and migrating them yields an empty shell
- * in the target chat with a fake "已就绪" M1.
- *
- * Why not just `!!ds.worker || ds.hasHistory`:
- *   - `ds.worker` is runtime-only; null after daemon restart until
- *     forkWorker re-attaches.
- *   - `ds.hasHistory` is a runtime field too — restoreActiveSessions sets
- *     it `true` UNCONDITIONALLY for any persisted non-adopt session
- *     (session-manager.ts:618). A scratch that survived a restart comes
- *     back with hasHistory:true, defeating the guard.
- *
- * Use persisted markers instead: `ds.session.cliId` and
- * `ds.session.lastCliInput` are written ONLY after a real worker started
- * the CLI (worker-pool's fork path stamps cliId; rememberLastCliInput
- * writes lastCliInput on every input). Daemon-command scratches never set
- * either, so the predicate survives restart and is robust across paths.
- *
- * Apply at every relay surface that consumes a candidate `ds`:
- *   - relay-picker.ts collectRelayPickerEntries (don't list scratches)
- *   - card-handler.ts relay_confirm preflight (don't M1 + transferSession a scratch)
- *   - this file's transferSession depth defense (catch any caller that bypassed both upstream guards)
- *   - command-handler.ts /relay --create leader guard
- */
-export declare function isRelayableRealSession(ds: DaemonSession): boolean;
-/** A worker-less row that never represented a CLI and carries no deferred
- * user intent. Only this narrow class is safe to evict as command scaffolding. */
-export declare function isDisposableCommandScratch(ds: DaemonSession): boolean;
-/** Worker lifecycle readiness is independent from Web Terminal availability.
- * Legacy/test sessions predate workerReady, so retain the old port inference
- * only while the explicit flag is absent. */
-export declare function workerHasInitialized(ds: DaemonSession): boolean;
-/** Capability of the backend frozen onto this worker/session generation. */
-export declare function sessionSupportsWebTerminal(ds: DaemonSession): boolean;
-/** Empty means this session intentionally has no Web Terminal surface. */
-export declare function readableTerminalUrlFor(ds: DaemonSession): string;
-export declare function writableTerminalLinkFor(ds: DaemonSession): string | undefined;
-/** How often the live streaming card is re-PATCHed with fresh usage while a
- *  turn executes. 12s stays off the prompt-cache-friendly path; the tick reads
- *  with fresh:true so it bypasses (does not merely out-wait) the usage reader's
- *  15s reparse throttle — the transcript grows per tool step, so each refresh
- *  folds only the newly appended bytes. */
-export declare const USAGE_REFRESH_INTERVAL_MS = 12000;
-/** Single source of truth for "this session should be periodically re-rendering
- *  its streaming card with fresh usage right now". Used by both the arm gate and
- *  the interval tick so arm/clear is a state-boundary invariant, not tied to one
- *  PATCH path. Requires: an actively-working turn, a live (non-sentinel, not a
- *  new-turn handoff) streaming card, the worker initialized (NOT a Web-Terminal
- *  port — ZMX reports ready with port=0), usageDisplay='streaming', and a CLI
- *  that actually has a native-usage transcript (gemini/opencode/pi/… have none
- *  → nothing to show). */
-export declare function usageRefreshShouldRun(ds: DaemonSession): boolean;
-/** Re-render the current streaming card with the freshest usage snapshot. The
- *  interval tick is self-correcting: if the session no longer qualifies (turn
- *  settled, card gone, limit, etc.) it clears its own timer, bounding any missed
- *  explicit clear to a single interval. Reads with fresh:true so the periodic
- *  PATCH actually beats the cost reader's 15s reparse throttle. */
-export declare function refreshStreamingCardUsage(ds: DaemonSession): void;
-/** Bring the periodic usage refresh in line with current state — arm when the
- *  session qualifies, clear otherwise. Idempotent; safe to call after ANY
- *  lastScreenStatus assignment or streaming-card lifecycle change. This is the
- *  single choke point that makes the timer a state-boundary invariant. */
-export declare function syncUsageRefreshTimer(ds: DaemonSession): void;
-/**
- * PATCH the live streaming card with the freshest riff sandbox URL. Mirrors
- * {@link scheduleLocalCliOpenReadinessPatch}: when the card POST is still
- * in-flight (streamCardId === sentinel) the refresh is parked on
- * `pendingRiffUrlCardRefresh` and flushed once the POST lands — the riff
- * accessUrl typically arrives inside exactly that window (task-execute returns
- * within ~1s of the initial card POST), and without the pending flag the
- * in-card writable link would stay stale until the next status-edge PATCH.
- */
-export declare function scheduleRiffAccessUrlPatch(ds: DaemonSession): void;
-export declare function clearUsageLimitState(ds: DaemonSession): void;
-export declare function cardUsageLimit(ds: DaemonSession): CliUsageLimitState | undefined;
-export declare function restoreUsageLimitRuntimeState(ds: DaemonSession): void;
-export declare const CARD_POSTING_SENTINEL = "__posting__";
-/**
- * Move the current streaming card into `frozenCards` without freezing it
- * cosmetically. The next successful card POST will sweep it via
- * `recallFrozenCards`. Used on paths that bypass the normal freeze step
- * (worker dead before a new turn, repo switch tearing down the session) so
- * we never delete the only visible card before its successor exists — if
- * fork / worker_ready / POST fails, the parked card stays in the thread.
- *
- * Lazy-loads `frozenCards` from disk if the in-memory Map is missing
- * (post daemon-restart, before any card-handler action has loaded it).
- * Without this, parking would synthesize an empty Map and the subsequent
- * `saveFrozenCards` would overwrite earlier turns' entries on disk —
- * stranding their cards in the thread with no way to recall them.
- *
- * No-op when there is no live card to park.
- */
-export declare function parkStreamCard(ds: DaemonSession): void;
-/**
- * Delete previously-frozen streaming cards from Lark and clear the cache.
- * Called whenever a new streaming card becomes the active one — old turns'
- * cards just add visual clutter when scrolling thread history.
- *
- * Lazy-loads `frozenCards` from disk if the in-memory Map is missing
- * (post daemon-restart). Best-effort delete; failures (already withdrawn,
- * expired) are non-fatal.
- *
- * Skips any entry whose messageId matches `ds.streamCardId` — guards the
- * daemon-restart window where a turn was frozen (entry persisted to disk)
- * but a new card was never POSTed before the crash. After restart the same
- * messageId is the live `streamCardId` again, and recalling it would delete
- * the only card the user can see.
- */
-export declare function recallFrozenCards(ds: DaemonSession): void;
-/**
- * Force-post a fresh streaming card for `ds`, bypassing the per-bot
- * `disableStreamingCard` opt-out. Backs the `/card` command: a user can
- * manually summon a live card in an otherwise-quiet session. Parks the current
- * card (if any) first so `recallFrozenCards` withdraws it once the fresh one
- * lands — the thread ends up with a single live card. Returns false when the
- * worker isn't initialized yet, so the caller can surface a friendly "not
- * ready" message. A ready backend without Web Terminal still gets the card.
- *
- * Note: this does NOT itself flip `ds.streamingCardForced` — the caller sets
- * that so the card keeps live-patching afterwards even when the bot opted out.
- */
-export declare function postFreshStreamingCard(ds: DaemonSession, sessionReply: (rootId: string, content: string, msgType?: string, larkAppId?: string, turnId?: string) => Promise<string>): Promise<boolean>;
-/**
- * Audience for a private `/card`: the bot's `allowedUsers` (the canOperate set —
- * owner & co-owners), deduped, `ou_` only. Talk-only grants (`globalGrants` /
- * `chatGrants`) and a bare triggerer are intentionally NOT included: the private
- * card is owner-only. A grant-authorized user who runs `/card` therefore does
- * not receive a card (matches the "授权人不发" rule). Empty when the bot has no
- * `allowedUsers` (fully-open mode → no owner to send to).
- */
-export declare function resolvePrivateCardAudience(ds: DaemonSession): string[];
-/**
- * Private `/card`: build a one-shot snapshot of the current terminal and send it
- * as an ephemeral (visible-to-one) card to each open_id in `audience`, one API
- * call each (concurrency-capped). Never posts a group-visible card and never
- * patches — privacy is the whole point, so there is deliberately no fallback.
- * Returns per-recipient counts so the caller can report progress without leaking
- * the audience list into the chat.
- */
-export declare function postPrivateSnapshotCard(ds: DaemonSession, audience: string[]): Promise<{
-    sent: number;
-    total: number;
-    notReady: boolean;
-}>;
-/**
- * Deliver the write-enabled session card (the "🔑 获取操作链接" card, which carries
- * a write-token terminal URL + manage buttons) privately to a single operator.
- *
- * Prefers an in-chat "visible-to-you" ephemeral card in a flat group so the
- * operator never has to leave the conversation. Thread-scope sessions and
- * chat-scope sessions currently folded into a thread go straight to DM:
- * Feishu may accept their ephemeral message without rendering it in the topic
- * panel. p2p chats also DM directly (the DM lands in that same 1:1 chat).
- *
- * Other group chats attempt ephemeral first and fall back to DM on ANY failure.
- *
- * Both channels are private, so the DM fallback never leaks the write token —
- * unlike the private /card snapshot (which fails closed), here we fail OVER.
- *
- * Returns the channel actually used, or 'failed' if both errored.
- */
-export declare function deliverWriteLinkCard(ds: DaemonSession, operatorOpenId: string, cardJson: string): Promise<'ephemeral' | 'dm' | 'failed'>;
-export interface WriteLinkOwnerDelivery {
-    ok: boolean;
-    error?: 'terminal_unavailable' | 'terminal_unsupported' | 'no_owner' | 'delivery_failed';
-    delivered: number;
-    total: number;
-    channels: Array<'ephemeral' | 'dm' | 'failed'>;
-}
-/**
- * Build the write-enabled session card (writable terminal URL + manage buttons)
- * for `ds`, or null when the terminal isn't up yet (no worker port/token).
- * Shared by the owner-fanout ({@link deliverWriteLinkCardToOwners}, behind
- * `botmux term-link`) and the single-operator delivery
- * ({@link deliverWritableTerminalCardTo}, behind the `/term` slash command).
- */
-export declare function buildWritableTerminalCard(ds: DaemonSession): string | null;
-/**
- * Build the write-enabled session card for `ds` and deliver it privately to the
- * bot's owner(s) — the payload behind the `botmux term-link` CLI command.
- *
- * Mirrors the in-chat "🔑 获取操作链接" button flow ({@link deliverWriteLinkCard}),
- * but fans out to the owner audience ({@link resolvePrivateCardAudience}) instead
- * of a single click-operator: a CLI caller has no Lark identity, so "deliver to
- * the owner(s)" is the closest equivalent of "deliver to the person who asked".
- * Each owner gets an in-chat visible-to-you ephemeral card, auto-falling back to
- * a private DM in topic / p2p chats. The write token therefore only ever rides
- * these private channels — it is never returned to the CLI caller / stdout.
- */
-export declare function deliverWriteLinkCardToOwners(ds: DaemonSession): Promise<WriteLinkOwnerDelivery>;
-/**
- * Deliver the writable-terminal card privately to a single operator — the `/term`
- * slash command's payload (the owner who typed it; owner-gated in command-handler).
- * Same private ephemeral→DM channel as the "🔑 获取操作链接" card button. Returns
- * 'not_ready' when the terminal isn't up yet, else the channel actually used.
- */
-export declare function deliverWritableTerminalCardTo(ds: DaemonSession, operatorOpenId: string): Promise<'ephemeral' | 'dm' | 'failed' | 'not_ready' | 'unsupported'>;
-export interface SubstituteControlCardDelivery {
-    sent: number;
-    total: number;
-}
-/**
- * DM a control card to the bot's owner(s) for a substitute-mode session.
- * ZMX receives a manage-only card because it has no Web Terminal surface.
- * Guards against duplicate sends via `session.substituteControlCardSent`.
- */
-export declare function deliverSubstituteControlCard(ds: DaemonSession): Promise<SubstituteControlCardDelivery>;
-/**
- * Deliver a status confirmation (restart / session-closed / resume) as a
- * "visible-to-the-operator-only" ephemeral message in a plain group; on failure
- * (topic groups reject with 18053) or in p2p, fall back to the normal visible
- * reply (`reply`). `content` is the card JSON when msgType==='interactive',
- * otherwise the plain text. Topic-group / p2p behavior is unchanged.
- *
- * IMPORTANT: ephemeral is only attempted for flat **chat-scope** sessions. The
- * ephemeral API (`ephemeral/v1/send`) takes a `chat_id` only — it has no
- * thread/root anchoring — so for a **thread-scope** session (a 话题 inside a
- * 普通群, or a 话题群 topic) an ephemeral card would escape the topic and land at
- * the group top-level. 话题群 happened to reject ephemeral with 18053 and fall
- * back to the in-thread reply, but a 话题 inside a 普通群 succeeds and leaks the
- * card out of the thread. So thread-scope sessions always take the visible
- * `reply()` path, which routes back into the thread (`reply_in_thread`).
- */
-export declare function deliverEphemeralOrReply(ds: DaemonSession, operatorOpenId: string | undefined, content: string, msgType: 'text' | 'interactive', reply: () => Promise<unknown>): Promise<void>;
-/**
- * Queue a card PATCH. If no PATCH is in-flight, sends immediately.
- * Otherwise stores the card JSON on `ds.pendingCardJson` (overwriting
- * any previously queued value — only the latest state matters).
- */
-export declare function scheduleCardPatch(ds: DaemonSession, cardJson: string, turnId?: string): void;
-export declare const restartCounts: Map<string, {
-    count: number;
-    lastAt: number;
-}>;
-/**
- * Ensure built-in skills are installed for a given CLI.
- * Synchronous and idempotent — runs once per CLI per daemon lifecycle.
- */
-export declare function ensureCliSkills(cliId: CliId, cliPathOverride?: string): void;
-/**
- * Ensure per-CLI environment is set up for this daemon lifecycle: install
- * built-in skills and the single stable Botmux MCP Gateway entry.
- * Both steps are idempotent and best-effort.
- */
-export declare function ensureCliEnv(cliId: CliId, cliPathOverride?: string): void;
-/** Unconditionally sweep botmux-owned skills out of the user's global
- *  `~/.claude/skills`. botmux owns the `botmux-` namespace there and injects its
- *  skills per-session via `--plugin-dir`, so anything matching is a leak that
- *  would otherwise surface (and mis-fire) in the user's standalone `claude`.
- *  Idempotent & best-effort — safe to call repeatedly. */
-export declare function sweepGlobalBotmuxSkills(): void;
-/** Pre-accept Claude Code's per-project folder-trust dialog for `workingDir`.
- *  Claude keys trust off realpath(cwd) (its getcwd(3) is already realpath'd),
- *  so seed that path. Merge-safe + best-effort: only ADDS the flag, never
- *  clobbers other keys; any failure is swallowed so it can't block spawn. */
-export declare function ensureClaudeFolderTrust(workingDir: string, stateJsonPath?: string): void;
-export declare function killWorker(ds: DaemonSession): void;
-/**
- * Retire the old worker generation during a routing transfer without applying
- * ordinary `/close` semantics to its backend.
- *
- * The replacement worker reuses the same logical session after this completion
- * fence. Sending `close` here would call `destroySession()` in the old worker
- * and race that replacement's persistent-backend reattach. A worker-less
- * session is already detached, so unlike killWorker() this path must never
- * destroy its orphaned backing resource.
- */
-export declare function detachWorkerForTransfer(ds: DaemonSession, opts?: {
-    timeoutMs?: number;
-}): Promise<boolean>;
-/**
- * Whether a worker-less restart must first destroy the session's persistent
- * backing pane. Adopt sessions are excluded — botmux never owned the user's
- * pane, so killing it would violate the bridge invariant. Pure so the
- * adopt-skip decision is unit-testable without spawning a worker.
- */
-export declare function shouldDestroyPaneBeforeRestart(ds: Pick<DaemonSession, 'initConfig' | 'adoptedFrom'>): boolean;
-/**
- * Live-worker /restart 携带的最新 per-bot env（bots.json `env`）。worker 收到
- * restart 时在 respawn 前全量覆盖 lastInitConfig.env —— 否则 live-worker 重启
- * 一直用 fork 时刻的旧快照，dashboard 改完 env（如切 provider 的
- * ANTHROPIC_BASE_URL/TOKEN）后 /restart 并不会生效（只有 refork 路径生效）。
- * 三分态返回：对象 = 最新 env；null = 明确清空（dashboard 已删）；
- * undefined = 取不到（bot 已注销等异常），让 worker 保持快照不动（=旧行为）。
- * 只热更 env 一个字段：sandbox/backendType 是刻意 freeze-once 的设计（见
- * forkWorker init 注释），cliId 换 CLI 会踩 resume transcript 对齐，均不带。
- */
-export declare function latestPerBotEnvForRestart(ds: DaemonSession): Record<string, string> | null | undefined;
-/** Join or start one correlated physical restart for a session. */
-export declare function requestSessionRestart(ds: DaemonSession, observer: RestartObserver): {
-    attemptId: string;
-    joined: boolean;
-} | undefined;
-export declare function __testOnly_resetRestartCoordinator(): void;
-export declare function suspendWorker(ds: DaemonSession, reason?: string): boolean;
-export declare function teardownAuthoritativePersistentBackingBeforeClose(target: DaemonSession | Session): void;
-/**
- * Idempotent close: kill worker if alive, mark Session status='closed' + closedAt,
- * publish session.exited (if a live worker was killed) and session.update
- * (if the persistence row transitioned to closed).
- *
- * Calling this on an unknown sessionId, an already-closed session, or a session
- * whose worker died asynchronously must still resolve with `{ ok: true }`.
- */
-export declare function closeSession(sessionId: string): Promise<{
-    ok: true;
-    alreadyClosed: boolean;
-    known: boolean;
-}>;
-/**
- * Close can arrive through daemon IPC before startup restore has registered the
- * persisted row. In that window there is no DaemonSession for killWorker(), but
- * a stamped persistent backing may still be running. Tear down only backends
- * whose ownership is explicit; never touch adopted user panes, queued rows, or
- * legacy rows whose backend is unknown.
- */
-export declare function destroyUnregisteredPersistentBacking(session: Session, kill?: typeof killPersistentBackendTarget): boolean;
-/**
- * Return an active persisted row that deliberately reserves this routing key
- * after an inconclusive exact-backend teardown.
- *
- * The store is the durable authority rather than a process-local Set: a daemon
- * restart must not forget the quarantine and create a second runtime beside a
- * possibly-live ZMX/other persistent target. Closed rows are ignored so an
- * operator's successful close immediately releases the route.
- */
-export declare function findQuarantinedRoutingConflict(key: string, larkAppId: string, candidateSessionId?: string): Session | undefined;
-/**
- * Synchronous registration gate for creation paths that previously used a
- * bare Map.set(). A daemon close can update the shared Session object while
- * the creator is awaiting Lark/project metadata; never publish that now-closed
- * row back into the live routing map when the continuation resumes.
- */
-export declare function setActiveSessionIfActive(map: Map<string, DaemonSession>, key: string, ds: DaemonSession): boolean;
-export declare function setActiveSessionSafe(map: Map<string, DaemonSession>, key: string, ds: DaemonSession): Promise<boolean>;
-/**
- * Roll back a freshly-created row rejected by the registration CAS, then read
- * the routing winner *after* that asynchronous rollback finishes.
- *
- * Message handlers use this to hand an already-deduped inbound event to a
- * concurrent HTTP/dashboard/restore winner instead of silently dropping it.
- * The post-await lookup matters: close cleanup must never return a stale object
- * that another continuation replaced while the rollback was in flight.
- */
-export declare function rollbackRejectedSessionAndGetWinner(map: Map<string, DaemonSession>, key: string, rejected: DaemonSession, rollback?: (sessionId: string) => Promise<unknown>): Promise<DaemonSession | undefined>;
-type TransferBufferedInput = Extract<DaemonToWorker, {
-    type: 'message' | 'raw_input' | 'inject_command' | 'coco_drive_picker' | 'set_display_mode' | 'refresh_screen' | 'term_action';
-}>;
-export declare function __testOnly_resetOrdinaryImDeliveries(): void;
-export declare function isSessionTransferring(ds: DaemonSession): boolean;
-/** Register follow-up work that must run only after the relay gate is fully
- * released. Returns false when no transfer is active, so callers can proceed
- * immediately without a check-then-register race. */
-export declare function deferUntilSessionTransferSettled(ds: DaemonSession, callback: () => void): boolean;
-/** Route user/automation input through the transfer fence. Messages accepted
- * during detach are replayed byte-for-byte to the replacement generation.
- */
-export declare function sendWorkerSessionInput(ds: DaemonSession, message: TransferBufferedInput): boolean;
-/**
- * Transfer an active session from its current chat to a new chat. The CLI
- * process keeps running inside its tmux session — only the routing fields
- * (chatId, rootMessageId, scope) and activeSessions key are rewritten. After
- * the rewrite, forkWorker spawns a new worker that re-attaches to the same
- * `bmx-<sessionId>` tmux, so the AI's transcript continues without break.
- *
- * Visible side effects:
- *   - Lark messages in the *source* chat remain where they were — we have no
- *     API to move them. Only the worker's *routing* moves; the AI's memory
- *     follows via the CLI's persistent jsonl on disk.
- *   - Cards posted by the prior worker stay in the source chat. We clear
- *     streamCardId/Nonce/imageKey so the new worker posts fresh cards in the
- *     target chat instead of trying to PATCH unreachable old ones.
- *
- * Pre-conditions (entry guards, all checked synchronously up-front — no
- * idle-wait loop; busy workers are refused immediately so the caller can
- * report a deterministic outcome and the user retries when the worker
- * quiets):
- *   - Session must be currently active (live worker + activeSessions entry)
- *   - Source must not be a pendingRepo placeholder (no CLI ever started)
- *   - Source must not be an adopted external-tmux session
- *   - Source worker must be in idle/limited (or already dead) — otherwise
- *     refuse with `worker_busy`
- *   - Target chat must not already host a real chat-scope session for the
- *     same bot (`target_chat_has_session`). Scratch (worker:null) occupants
- *     are NOT a conflict — they're command-time placeholders and we close
- *     them in-line to free the slot before continuing.
- *
- * Idempotent for `same_chat`: returns error without side effects when the
- * source chat equals the target chat.
- */
-export declare function transferSession(sessionId: string, targetChatId: string, targetRootMessageId: string, 
-/**
- * Target chat type.
- *   'group' → topic groups are supported via `targetScope: 'thread'`;
- *             `/relay --create` builds the target by createGroupWithBots so
- *             it's a regular group by construction; the cross-daemon
- *             migrate-to-chat IPC inherits the same target.
- *   'p2p'   → the bot's DM. Flat DMs (p2pMode 'chat') land chat-scope on the
- *             chatId anchor; thread-mode DMs land thread-scope on a DM 话题
- *             root. The session's chatType flips with the move so post-relay
- *             inbound routing / picker labels / reply targeting treat it as
- *             a DM. Carried from the picker card's `target_chat_type`.
- * The runtime check just below catches raw-string casting at module
- * boundaries (mocks, HTTP body parses, future bypasses).
- */
-targetChatType: 'group' | 'p2p', 
-/**
- * Target routing scope for the relayed session.
- *   'chat'   → anchor = chatId (flat top-level; `/relay --create`, migrate
- *              IPC, and普通群 flat-mode picker all use this — current behavior).
- *   'thread' → anchor = `targetRootMessageId` (a Lark 话题/thread); replies
- *              go reply_in_thread. Picker computes this via
- *              resolveRelayTargetRouting for 话题群 / new-topic / shared /
- *              线程内回复.
- */
-targetScope: 'thread' | 'chat', opts?: {
-    /** @internal Override for tests — the real implementation forks a child
-     *  process and tries to attach to tmux, neither of which is appropriate
-     *  in a unit test environment. Defaults to module-level forkWorker. */
-    forkWorkerImpl?: typeof forkWorker;
-    /** @internal Override for tests — mirror of forkWorkerImpl for the
-     * transfer-only worker detach path. */
-    detachWorkerImpl?: (ds: DaemonSession) => boolean | void | Promise<boolean | void>;
-    /** Detach-fence budget (ms) for the observer teardown handshake. Defaults
-     *  to the tight TRANSFER_DETACH_FENCE_MS, which the cross-daemon peer path
-     *  needs to stay inside the leader's 5s HTTP abort. In-process callers with
-     *  no HTTP ceiling (the picker relay_confirm) pass a larger value
-     *  (TRANSFER_DETACH_FENCE_PICKER_MS) so a slightly-slow-but-clean teardown
-     *  is not misclassified as a failure. Ignored when detachWorkerImpl is set
-     *  (test doubles don't observe a real fence). */
-    detachTimeoutMs?: number;
-}): Promise<{
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-}>;
-/** True when this session can be byte-level forked via a CLI-native primitive.
- *  Refuses codex-app outright, and refuses a plain `codex` session that is
- *  running in Hybrid RPC mode (its live thread lives in the app-server, not a
- *  forkable local rollout). */
-export declare function isForkCapableSession(ds: DaemonSession): boolean;
-/**
- * Fork a session: create a SECOND, independent botmux session that inherits the
- * source's full context at the current node, landing at a different anchor
- * (another group / topic). The source session is left completely untouched and
- * keeps running — this is the non-destructive sibling of {@link transferSession}
- * (relay MOVES one session shell; fork COPIES into a new shell).
- *
- * Context inheritance is delegated to the CLI's native fork primitive
- * (`--fork-session` / `codex fork`) via the child's one-shot
- * `pendingForkSession` marker: the child's first spawn resumes the SOURCE's
- * CLI-native transcript but writes forward into a fresh CLI-minted id. botmux
- * never copies transcript bytes itself.
- *
- * Shares transferSession's front guards (mid-turn / adopt / pendingRepo /
- * vc-receiver / target-anchor occupancy) but performs NONE of its destructive
- * steps (no source card freeze, no worker detach, no source registry delete, no
- * source routing rewrite).
- */
-export declare function forkSession(sessionId: string, targetChatId: string, targetRootMessageId: string, targetChatType: 'group' | 'p2p', targetScope: 'thread' | 'chat', opts?: {
-    forkWorkerImpl?: typeof forkWorker;
-    childTitle?: string;
-    forkTaskText?: string;
-    larkThreadId?: string;
-    buildInitialPrompt?: (childSessionId: string) => string | CliTurnPayload;
-    turnId?: string;
-    senderOpenId?: string;
-    senderIsBot?: boolean;
-}): Promise<{
-    ok: true;
-    childSessionId: string;
-} | {
-    ok: false;
-    error: string;
-}>;
-/** Send one normal (non-raw) worker turn while applying the per-bot Codex App
- * clean-input gate at message acceptance time. This freezes the sidecar onto
- * the IPC item, so later config flips do not mutate an already queued turn. */
-export declare function sendWorkerInput(ds: DaemonSession, payload: string | CliTurnPayload, turnId?: string, opts?: {
-    dispatchAttempt?: number;
-}): boolean;
-export declare function forkWorker(ds: DaemonSession, promptInput: string | CliTurnPayload, resumeOrTurnId?: boolean | string | {
-    resume?: boolean;
-    turnId?: string;
-    dispatchAttempt?: number;
-    restartAttemptId?: string;
-}): void;
-/**
- * Clear the stuck-warning authority markers WITHOUT patching the card. Used by
- * ACK paths (tui_keys_delivered / stuck_warning_expired) where the caller has
- * already resolved the card to its final state — we only need to drop the
- * nonce/cardId/turnId so a late duplicate click cannot re-inject keys.
- */
-export declare function clearStuckWarningAuthority(ds: DaemonSession): void;
-/**
- * Resolve any active stuck-warning card (PATCH it to "done") AND clear its
- * markers. Called from every path where the CLI can recover or be replaced:
- * prompt_ready, claude_exit, worker exit/kill/suspend/refork, and the worker's
- * own stale-card notification. Centralising here avoids missing an exit path
- * and leaving a clickable card that can inject keys into a different CLI.
- *
- * ACK paths (tui_keys_delivered / stuck_warning_expired) do NOT use this —
- * they patch the card themselves with a context-specific message and then call
- * clearStuckWarningAuthority() to drop the markers.
- */
-export declare function invalidateStuckWarning(ds: DaemonSession, reason: string): void;
-declare function setupWorkerHandlers(ds: DaemonSession, worker: ChildProcess, startupState?: WorkerStartupState, reservedWorkerGeneration?: number): void;
-declare function finalOutputDedupeKey(ds: DaemonSession, msg: Extract<WorkerToDaemon, {
-    type: 'final_output';
-}>): string;
-/**
- * Turn-end half of the two-phase turn reactions (auto-on for card-off sessions,
- * i.e. streaming card disabled). The 冲! "received" reactions are added per-message at the daemon
- * acceptance point (`noteTurnReceived`); the screen_update handler calls this
- * only on working|analyzing → idle|limited (not cold-start starting→idle), to
- * flip every pending ✋ on this session to ✅ DONE and clear the list. When
- * silentTurnReactions is enabled after a ✋ has already landed, we only remove
- * that received reaction and do not add DONE. Binding the start to the message
- * (not a status edge) means type-ahead / busy-batched messages each get their
- * own reaction and all settle together here.
- *
- * Every Feishu call is best-effort — a failure only means a missing emoji, so it
- * must never throw into the status pipeline (callers invoke as `void`).
- */
-declare function finishTurnReactions(ds: DaemonSession): Promise<void>;
-/** Deliver a bridge `final_output` to Lark. The worker emits each turn
- *  exactly once (it pops the turn off its queue at emit time), so the
- *  daemon owns retries on transient failures. After 3 attempts we log
- *  and give up — the user's answer is lost; better than leaking memory
- *  via an unbounded retry loop. */
-declare function deliverFinalOutput(ds: DaemonSession, msg: Extract<WorkerToDaemon, {
-    type: 'final_output';
-}>, t: string, attempt: number, stillCurrent?: () => boolean, frozenUsage?: CardUsageSnapshot): void;
-/** Test-only alias so the retry pipeline can be exercised without a real
- *  fork. Intentionally underscored to discourage non-test callers. */
-export declare const __testOnly_deliverFinalOutput: typeof deliverFinalOutput;
-export declare const __testOnly_setupWorkerHandlers: typeof setupWorkerHandlers;
-export declare const __testOnly_reserveWorkerGeneration: typeof reserveWorkerGeneration;
-export declare const __testOnly_finishTurnReactions: typeof finishTurnReactions;
-export declare const __testOnly_finalOutputDedupeKey: typeof finalOutputDedupeKey;
-declare function reserveWorkerGeneration(ds: DaemonSession): number;
-/**
- * Is the file sandbox active such that /adopt must be refused? A sandbox can
- * only be established at spawn time (bwrap wrap / Seatbelt profile); adopt
- * attaches to an ALREADY-running host process, so it could only ever run
- * UNsandboxed. From-strict UNION of every source that can require isolation:
- *  - live per-bot `sandbox` / legacy `readIsolation`,
- *  - the global `BOTMUX_SANDBOX=1` (sandboxEnabled()),
- *  - the session's FROZEN sandbox decision (`session.sandbox`, recorded at
- *    creation). forkWorker treats the frozen decision as authoritative, so a
- *    session created sandboxed must stay un-adoptable even if the admin later
- *    toggles the bot's global flag OFF — otherwise its `/adopt` would attach to
- *    an unsandboxed live process. The reverse (bot=true / session=false) is
- *    also caught by the union, which is the safe direction.
- * Callers reject at the ENTRY point (before persisting `adoptedFrom` / replying
- * "adopted") — see command-handler's `/adopt`, the adopt_select card, and the
- * session-manager restore branch. Resume/cold-start is unaffected: those spawn
- * a fresh CLI, which the sandbox wraps normally.
- */
-export declare function adoptSandboxBlocked(botCfg: {
-    sandbox?: boolean;
-    readIsolation?: boolean;
-    apiOnly?: boolean;
-}, session?: {
-    sandbox?: boolean;
-    chatId?: string;
-}): boolean;
-export declare function forkAdoptWorker(ds: DaemonSession, opts?: {
-    restoredFromMetadata?: boolean;
-    prompt?: string;
-    turnId?: string;
-}): void;
-/** A live process, reduced to what orphan detection needs. */
-export interface ProcSnapshot {
-    pid: number;
-    ppid: number;
-    /** Full command line (argv joined by spaces). */
-    cmd: string;
-}
-/**
- * Enumerate live processes as {pid, ppid, cmd}. Linux reads `/proc` directly
- * (the rest of the worker code already relies on /proc); other POSIX shells out
- * to `ps`. Returns `[]` on Windows or on any failure — callers then reap
- * nothing, so "can't tell" can never escalate into a wrong kill.
- */
-export declare function listProcesses(): ProcSnapshot[];
-/**
- * Reap worker processes orphaned by a previous daemon that died WITHOUT running
- * its graceful shutdown — SIGKILL, OOM, or an uncaught crash. The shutdown()
- * path in daemon.ts already SIGKILLs stragglers on SIGTERM, but a hard kill
- * skips it entirely: the workers get re-parented to init (ppid==1), and because
- * a fresh worker's pid overwrites `session.pid`, killStalePids can never reach
- * them again. Each leaks ~0.5 GB and they pile up across restarts (observed:
- * 22 orphans / 3.3 GB on a dev box; daemon.ts records a prior 841-orphan /
- * ~65 GB incident).
- *
- * Identification is deliberately conservative — a process is reaped only if it
- * BOTH:
- *   1. has ppid==1 — its forking daemon is gone. A live daemon's workers are
- *      parented to that daemon, so this never touches a running worker, even
- *      under the one-daemon-per-bot layout or when several daemons start at
- *      once; and
- *   2. references THIS install's worker script in its command line — so we
- *      never touch another botmux install or an unrelated `worker.js`.
- *
- * Process listing and the kill syscall are injectable for tests. Returns the
- * number of orphans actually reaped.
- */
-export declare function reapOrphanWorkers(opts?: {
-    procs?: ProcSnapshot[];
-    kill?: (pid: number, signal: NodeJS.Signals) => void;
-    workerPath?: string;
-}): number;
-export declare function killStalePids(activeSessions_: Session[], runtimeSessions?: ReadonlyMap<string, DaemonSession>): void;
-/**
- * Sweep dead CLI-pid marker files out of `.botmux-cli-pids/`. Each marker is
- * named for the PID that wrote it; when that PID is gone the file is a landmine —
- * the kernel eventually recycles the number onto an unrelated process, and a
- * `botmux send` climbing its ancestry can then read a since-exited session's
- * marker and route the message into the WRONG bot's session. (Fix A already
- * rejects such a marker at read time by verifying procStart / the env session
- * id; this GC removes the file so the collision can't even be attempted, and
- * keeps the directory from growing without bound — graceful worker exit unlinks
- * its own marker, but SIGKILL / crash / force-kill do not.)
- *
- * Cross-daemon safe: with many daemons sharing one data dir, a DEAD pid cannot
- * belong to any live daemon's session, so unlinking its marker never races a
- * peer. A live pid's marker is always left untouched. The tiny window where a
- * PID is recycled between the liveness probe and unlink is benign — the new
- * owner rewrites its marker on the next turn, and Fix A makes a briefly-missing
- * marker fall back to the correct env id, never to a wrong session.
- *
- * `isPidAlive` is injectable so tests are deterministic regardless of what PIDs
- * the host has actually allocated (picking a "surely-dead" literal is unsafe —
- * it can be below pid_max and collide with a live process on a busy runner).
- * Production uses `process.kill(pid, 0)`: a signal-0 probe that never kills.
- * Conservative on every ambiguity — only a definitively-dead PID is swept.
- */
-export declare function defaultPidLiveness(pid: number): boolean;
-export declare function sweepDeadPidMarkers(dataDir?: string, isPidAlive?: (pid: number) => boolean): number;
-export declare function setCurrentCliVersion(v: string, runtimeKey?: string): void;
-export declare function getCurrentCliVersion(runtimeKey?: string): string;
-export {};
-//# sourceMappingURL=worker-pool.d.ts.map