@byok-sdk/client 0.1.0

package/dist/daemon/task-runner.d.ts

@@ -0,0 +1,862 @@
+import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload } from '@byok-sdk/protocol';
+import { type RuntimeAdapter } from '../types';
+import { type ApprovalDecision, type ApprovalOrigin, type ApprovalRegistry } from './approvals';
+import type { BlobResolver } from './blob-client';
+import type { TaskQueueWatermark } from './control-protocol';
+import { type ProgressBatcherOptions } from './progress-batcher';
+import type { SessionWorkspaceStore } from './session-workspace-store';
+import type { GitWorkspaceManager, GitWorkspaceObservation } from './git-workspace';
+import type { GitWorkspaceStore, GitWorkspacePhase } from './git-workspace-store';
+/**
+ * M4 Phase 3: default wait for `requestApproval` (see its own doc comment)
+ * before force-resolving an unanswered out-of-band approval as a fail-closed
+ * rejection — generous enough for a real human to actually notice and act on
+ * an approval prompt, short enough that a genuinely abandoned task doesn't
+ * tie up daemon/task bookkeeping forever. Overridable via
+ * `TaskRunnerDeps.approvalTimeoutMs` (ultimately `DaemonConfig`-configurable —
+ * see `create-daemon.ts`).
+ */
+export declare const DEFAULT_APPROVAL_TIMEOUT_MS: number;
+/**
+ * Finding F5(a) (cross-model adversarial review): bound on how long
+ * `shutdownTask` waits for a single task's OWN `session.interrupt()` before
+ * giving up on it specifically and reporting `task.fail` anyway. Without an
+ * INNER bound here, a hung `interrupt()` (a misbehaving runtime adapter
+ * whose promise never settles) meant `task.fail` for THAT task was never
+ * sent at all — not eventually, not ever — because the send was sequenced
+ * strictly AFTER the `await`. The OUTER deadline
+ * `create-daemon.ts`'s `performControlShutdown` races `shutdownActiveTasks`
+ * against (`SHUTDOWN_TASK_TEARDOWN_DEADLINE_MS`) does not help: racing at
+ * that layer only unblocks the CALLER to proceed to `stop()`/closing the
+ * connection — it does nothing to unstick THIS function's own
+ * still-suspended `await`, which just keeps running (harmlessly, since
+ * nothing awaits it anymore) in the background forever after, its
+ * `deps.send` line never reached. Deliberately shorter than the outer
+ * 10s deadline so one hung task's own interrupt can't itself consume the
+ * whole outer budget and starve however many OTHER tasks
+ * `shutdownActiveTasks` awaits concurrently via `Promise.all`. Overridable
+ * via `TaskRunnerDeps.shutdownInterruptTimeoutMs` (ultimately
+ * `DaemonOverrides.shutdown.taskInterruptTimeoutMs` — see `create-daemon.ts`).
+ */
+export declare const DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS = 5000;
+/**
+ * M4 Phase 4 (fold-in from the P3 gate): bound on how many `requestApproval`
+ * calls may sit QUEUED (not yet dispatched — see that method's own doc
+ * comment) for the same task at once. Claude's parallel tool use can fire
+ * more than one concurrent approval request for the same taskId; this is a
+ * defensive ceiling on that fan-out, mirroring `approvals.ts`'s own
+ * `MAX_PENDING_APPROVALS` (a whole-daemon cap) one level down (a per-task
+ * cap) — not a realistic workload limit. A request arriving once a task's
+ * queue is already at this size is rejected fail-closed immediately, the
+ * same shape `requestApproval` already uses for an unknown/inactive taskId.
+ */
+export declare const MAX_PENDING_APPROVALS_PER_TASK = 16;
+/**
+ * M4 Phase 3 hardening (orchestrator-directed fix): thrown by the
+ * `ctx.approvalChannel.resolve` closure built in `handleOffer` below when
+ * this task has no CURRENTLY pending out-of-band approval to resolve.
+ * Distinguished from a plain `Error` specifically so `handleApprove`/
+ * `handleReject` can tell "a wire task.approve/task.reject arrived for an
+ * approval a DIFFERENT, faster path (a racing local `approvals.resolve`, or
+ * this exact decision arriving twice) already resolved" — a benign,
+ * expected race, audit-worthy but never task-state-affecting — apart from
+ * "the session's own resolveApproval() failed for some other, genuine
+ * reason" (an adapter-level problem, which still fails the task exactly as
+ * before). Only ever thrown for an adapter that actually wires up a real
+ * approval channel (claude, under `confirm` mode) — pi/codex's own
+ * `resolveApproval()` still throw their own unrelated, adapter-specific
+ * "not supported at all" errors, which are NOT instances of this class and
+ * therefore still fall through to the pre-existing fail-the-task behavior,
+ * unchanged.
+ */
+export declare class NoPendingApprovalError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * M3-B: cap for both `finishedTaskIds` and `pendingCancelled` below (each
+ * gains one entry per finished/cancelled task and was never pruned) — fine
+ * for the short-lived CLI invocations M0-M2 ran as, but M3 turns the daemon
+ * into a background service meant to stay up for weeks, so unbounded growth
+ * here is a real, if slow, memory leak. Each collection evicts its OLDEST
+ * (first-inserted) entry once over this cap — the same bounded-ring idiom
+ * `ConnectionHub`'s per-device dedup window already uses server-side
+ * (packages/server/src/hub.ts's `DEDUP_RING_CAPACITY`), just applied here to
+ * task ids. `Map`/`Set` iterate in insertion order (ECMA-262), so "oldest"
+ * always means "finished/cancelled longest ago" — neither collection is
+ * touched on a read, only on insert, so eviction order depends purely on
+ * insertion time. See `finishedTaskIds` and `pendingCancelled`'s own doc
+ * comments below for why a cap this size can't remove an entry either
+ * invariant still needs.
+ */
+export declare const MAX_TRACKED_TASK_IDS = 2000;
+/**
+ * M5 batch-3 (workstream 2): stable, documented reason PREFIX a `task.fail`
+ * carries when `payload.limits.maxDurationMs` (daemon-authoritative
+ * wall-clock enforcement — see `armMaxDurationTimer`) is exceeded. Only the
+ * prefix itself is the contract an embedder can match against
+ * (`reason.startsWith(...)`); everything after it is human-readable detail,
+ * not part of the stable shape.
+ */
+export declare const MAX_DURATION_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxDurationMs";
+/** M5 batch-3 (workstream 2): same contract as {@link MAX_DURATION_EXCEEDED_REASON_PREFIX}, for `DaemonConfig.maxTaskOutputBytes` — see `TaskRunner.pump`'s own per-event byte counting. */
+export declare const MAX_OUTPUT_BYTES_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxTaskOutputBytes";
+/**
+ * M5 batch-3 (workstream 2): default cap (64 MiB) on accumulated
+ * (approximate) agent-event output bytes this daemon tolerates for a single
+ * task before tearing it down as a resource-limit violation — see
+ * `TaskRunnerDeps.maxTaskOutputBytes` and `DaemonConfig.maxTaskOutputBytes`
+ * (`create-daemon.ts`) for the full contract, including the
+ * zero/negative-is-a-config-error / `Number.POSITIVE_INFINITY`-is-the-real-
+ * opt-out pin.
+ */
+export declare const DEFAULT_MAX_TASK_OUTPUT_BYTES: number;
+export interface TaskRunnerDeps {
+    adapters: RuntimeAdapter[];
+    runtimeAllowlist?: string[];
+    /**
+     * M5 batch-3 (workstream 1): auto-select priority order for `pickAdapter`'s
+     * no-explicit-runtime branch — see `DaemonConfig.runtimePreference`'s own
+     * doc comment (`create-daemon.ts`) for the full rationale behind this
+     * existing at all. Unset defaults to {@link DEFAULT_RUNTIME_PREFERENCE}
+     * (pi LAST, deliberately — product decision: pi is this SDK's fallback
+     * runtime, not its default). Independent of `runtimeAllowlist` above
+     * (which restricts WHICH runtimes are eligible at all) — this only orders
+     * the attempt sequence among whatever that allowlist, if set, already let
+     * through.
+     */
+    runtimePreference?: RuntimeId[];
+    /** M5: see `DaemonConfig.runtimeEnvironment`'s own doc comment (`create-daemon.ts`) — the per-device, per-runtime env-allowlist override `handleOffer` merges into `buildRuntimeEnv`'s `locallyAllowedNames`. */
+    runtimeEnvironment?: Record<string, {
+        allow?: string[];
+    }>;
+    permissionDefaults?: PermissionPolicy;
+    workspaceRoot: string;
+    deviceId: string;
+    send: (envelope: Envelope) => void;
+    blobClient: BlobResolver;
+    batcherOptions?: ProgressBatcherOptions;
+    /**
+     * Finding #3 (session/workspace continuity): persists `sessionRef ->
+     * workspaceDir` across daemon restarts so a `task.offer` naming a
+     * previously-reported `sessionRef` reuses that exact workspace instead of
+     * a fresh `workspaceRoot/<taskId>` — see `handleOffer` and
+     * `SessionWorkspaceStore`'s own doc comment.
+     */
+    sessionWorkspaces: SessionWorkspaceStore;
+    gitWorkspaceManager?: GitWorkspaceManager;
+    gitWorkspaceStore?: GitWorkspaceStore;
+    onGitWorkspaceEvent?: (event: {
+        taskId: string;
+        workspaceId: string;
+        phase: GitWorkspacePhase;
+        observation?: GitWorkspaceObservation;
+        errorCategory?: string;
+    }) => void;
+    /**
+     * M4 Phase 3: this daemon's control-socket identity + the shared registry
+     * backing the control socket's own `approvals.list`/`approvals.resolve`
+     * methods (`create-daemon.ts` constructs ONE `ApprovalRegistry` and passes
+     * the SAME instance here) — see `requestApproval`'s own doc comment for
+     * why `TaskRunner` needs a handle on all three. `storeDir`/`productId` are
+     * copied verbatim into every task's `TaskContext.approvalChannel`.
+     */
+    approvalRegistry: ApprovalRegistry;
+    storeDir: string;
+    productId: string;
+    /** Default `requestApproval` timeout — see {@link DEFAULT_APPROVAL_TIMEOUT_MS}. */
+    approvalTimeoutMs?: number;
+    /**
+     * M4 Phase 3 hardening: called by `handleApprove`/`handleReject` instead of
+     * failing the task when the referenced approval turns out to be stale
+     * (see {@link NoPendingApprovalError}) — an audit-only signal, never
+     * gating any task-state decision. `create-daemon.ts` wires this to
+     * `DaemonObserver.noteStaleApprovalDecision`, the same way every other
+     * locally-observable daemon event reaches the audit log/`tasks --follow`.
+     * Optional so a caller that doesn't care about this audit trail (e.g. a
+     * minimal test harness) isn't forced to supply one.
+     */
+    onStaleApprovalDecision?: (taskId: string, decision: ApprovalDecision, reason?: string) => void;
+    /**
+     * Finding F4 (cross-model adversarial review): operators had no way to
+     * ever learn a pending approval's `approvalId` short of reading raw
+     * audit-log JSON — `approve`/`reject` require one, but nothing surfaced
+     * it. Called synchronously from `dispatchApproval`, BEFORE `deps.send`'s
+     * own `task.await_approval` — `create-daemon.ts` wires this to
+     * `DaemonObserver.noteApprovalDispatched`, which stashes `approvalId`
+     * keyed by `taskId` so the observer's `task.await_approval` handling
+     * (triggered by that very `deps.send` call, synchronously, right after
+     * this) can attach it to the `awaiting-approval` `DaemonEvent` it emits
+     * (see `observer.ts`'s own doc comment). Optional so a minimal test
+     * harness that doesn't care about this audit-trail detail isn't forced
+     * to supply one — mirrors `onStaleApprovalDecision`'s own contract.
+     */
+    onApprovalDispatched?: (taskId: string, approvalId: string) => void;
+    /** Finding F5(a): overrides {@link DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS} — see `teardownActiveTask`'s own doc comment. Also the grace window `teardownActiveTask`'s hard-kill escalation (`session.close()`) gets once `session.interrupt()` itself fails to settle in time — see that method's own doc comment for why the same window is reused for both steps. */
+    shutdownInterruptTimeoutMs?: number;
+    /**
+     * M5 batch-3 (workstream 2): overrides {@link DEFAULT_MAX_TASK_OUTPUT_BYTES}
+     * — see that constant's own doc comment and `DaemonConfig.maxTaskOutputBytes`
+     * (`create-daemon.ts`) for the full contract. Validated (rejecting
+     * zero/negative) at the `DaemonConfig` layer, not here — this seam trusts
+     * its caller, same as every other optional numeric override on this
+     * interface (`shutdownInterruptTimeoutMs`, `approvalTimeoutMs`).
+     */
+    maxTaskOutputBytes?: number;
+    /**
+     * M4 (additive-minor, `task.approval_resolved`): the negotiated
+     * `conn.ack.capabilities` of the CURRENTLY (or most recently) connected
+     * server — read fresh at call time (mirrors `getCursor`/`getToken`'s own
+     * "read fresh, not captured once" convention elsewhere in this codebase),
+     * since the capability is learned asynchronously, after this `TaskRunner`
+     * is already constructed (`create-daemon.ts`'s `start()` builds `deps`
+     * before `connection` exists). `create-daemon.ts` wires this to
+     * `ConnectionManager.getServerCapabilities`. Optional, and treated as "no
+     * capabilities" when absent, so a minimal test harness that doesn't care
+     * about this gate isn't forced to supply one — see `sendApprovalResolved`.
+     */
+    getServerCapabilities?: () => readonly string[];
+    /**
+     * S3b (L-002): a pre-claim veto on new offers, consulted once per offer
+     * immediately after the redelivery-dedup check and ahead of every other
+     * admission check in `handleOffer`.
+     *
+     * It exists for local storage pressure (architecture §12.7.2.1's hard
+     * watermark: "停止接收新的普通 task；仍允许 terminal/truth flush、删除、导出、
+     * doctor 与恢复操作"). Placing it here rather than deeper in `handleOffer`
+     * is what makes that split real: an offer never reaches adapter selection,
+     * workspace creation, or `task.claim`, so declining costs nothing on disk —
+     * while every path that FINISHES existing work runs through code this seam
+     * is not on, and keeps working.
+     *
+     * Synchronous, matching every other single-purpose callback on this
+     * interface. A decline is `retryable` by the guard's own decision — pressure
+     * is a property of THIS device at THIS moment, so a dispatcher re-routing
+     * the task elsewhere genuinely helps; a guard declining for a reason that
+     * will not change says so.
+     *
+     * Optional and absent by default: with no guard supplied, `handleOffer`
+     * behaves exactly as it did before this seam existed.
+     */
+    admissionGuard?: (offer: {
+        readonly taskId: string;
+        readonly payload: TaskOfferPayload;
+    }) => AdmissionGuardDecision;
+}
+/** See {@link TaskRunnerDeps.admissionGuard}. */
+export type AdmissionGuardDecision = {
+    readonly admit: true;
+} | {
+    readonly admit: false;
+    readonly reason: string;
+    readonly retryable: boolean;
+};
+/**
+ * Per-connection task orchestration: offer -> (decline | claim -> adapter
+ * session -> started) -> seq-ordered progress batches -> complete/fail/
+ * cancelled, plus approve/reject/cancel/steer handling.
+ *
+ * M1 rework (docs/protocol.md §3, §5, §10 — `packages/protocol` is frozen,
+ * not editable here): pre-claim rejections (unknown/disallowed runtime,
+ * policy exceeding this device's ceiling) now send `task.decline` and never
+ * claim at all — `TASK_TRANSITIONS.Offered` gained a direct `-> Failed` edge
+ * precisely so this no longer has to claim-then-fail. A successful claim is
+ * followed by `task.started` only once the adapter session has actually
+ * started (`task.claim` alone no longer implies `Running`). Cancellation
+ * reports the explicit `task.cancelled` message instead of the old
+ * `task.fail({reason:'cancelled'})` convention.
+ */
+export declare class TaskRunner {
+    private readonly deps;
+    private readonly tasks;
+    /**
+     * Finding F4 (cancel lost during the offer-processing window): a
+     * `task.cancel` for a taskId that hasn't finished `handleOffer` yet (still
+     * awaiting adapter detection / instruction resolution / workspace setup /
+     * `adapter.start()`) has no `this.tasks` entry to land on — it used to be
+     * silently dropped, and the runtime session `handleOffer` was about to
+     * register would then run an unsupervised ("zombie") turn nobody asked
+     * for anymore. Recording the taskId here lets `handleOffer` consult it at
+     * the two points where it can still safely react (see its body): before
+     * claiming at all (decline instead of ever starting a session), and right
+     * after `adapter.start()` resolves but before this task is registered as
+     * active (tear the just-started session down immediately, before its
+     * event loop ever pumps a single event). Consumed (deleted) at whichever
+     * checkpoint handles it; a cancel for a taskId that's already active,
+     * already finished, or never offered at all leaves a harmless entry that
+     * nothing will ever consult.
+     *
+     * M3-B: that last sentence is exactly the unbounded-growth vector this
+     * needed closed for long-lived operation — a cancel for a taskId nobody
+     * ever claims (unknown, already active, or already finished) leaves a
+     * permanent entry with nothing left to consume it. Bounded to
+     * `MAX_TRACKED_TASK_IDS` via `setPendingCancelled` below, oldest evicted
+     * first: safe because every entry this field's correctness actually
+     * depends on is consumed (deleted) by one of `handleOffer`'s two
+     * checkpoints within that SAME task's own offer-processing window — one
+     * in-flight task's startup latency, nowhere near enough churn for eviction
+     * to remove an entry still inside its consuming window before it's read.
+     */
+    private readonly pendingCancelled;
+    /**
+     * Finding #5 (Codex counterexample): taskIds currently INSIDE `handleOffer`
+     * — from the moment it decides an offer is worth processing until it
+     * reaches one of its own resolution points (decline, fail, the
+     * checkpoint-2 cancel-teardown, or successful registration into
+     * `this.tasks`). Bounded eviction on `pendingCancelled` (below) must never
+     * remove an entry for a taskId in this set: doing so is exactly the bug —
+     * block task A in `adapter.start()`, deliver A's own `task.cancel` (so
+     * `pendingCancelled` gets an entry for A while A is still in-flight),
+     * then deliver `MAX_TRACKED_TASK_IDS` more cancels for unrelated taskIds
+     * nobody ever offered — under naive oldest-wins eviction, A's entry (the
+     * single oldest) gets evicted purely because of unrelated churn, so when
+     * `adapter.start()` finally resolves, checkpoint 2 finds no cancel marker
+     * and the already-cancelled task starts a real session. See
+     * `evictPendingCancelled` below for the fix, and
+     * `task-runner-bounded-collections.test.ts` for a test mirroring this
+     * exact scenario. Membership here is naturally tiny (bounded by this
+     * device's real concurrent-offer-processing count, nowhere near
+     * `MAX_TRACKED_TASK_IDS`), so scanning past it to find an evictable entry
+     * costs nothing.
+     */
+    private readonly inFlightOffers;
+    /**
+     * Finding P2 (Fix 2c): taskIds that have reached a terminal outcome
+     * (Complete/Failed/Cancelled) this session — populated in `finish()`.
+     * While `ConnectionManager`'s stalled-cursor long-poll re-pull is frozen
+     * behind an unrelated failing seq, it can legitimately redeliver an
+     * ALREADY-succeeded `task.offer` — the client's own cursor hasn't advanced
+     * past it yet (docs/protocol.md §9's "cursor advance timing" rule
+     * explicitly relies on redelivered handlers being idempotent for exactly
+     * this reason). `handleOffer` must treat a redelivered offer for a taskId
+     * that's already active (`this.tasks`) or already finished (this set) as
+     * a no-op — never a second `adapter.start()` call, which would orphan the
+     * first session.
+     *
+     * M3-B: unbounded otherwise — a long-lived daemon that's finished many
+     * thousands of tasks over its uptime would keep every single taskId
+     * forever. Bounded to `MAX_TRACKED_TASK_IDS` via `addFinishedTaskId`
+     * below, oldest evicted first. Safe for the redelivery-idempotency
+     * invariant above because the stalled-cursor scenario above redelivers
+     * this device's own recent backlog for one connection, not an arbitrary
+     * point in this daemon's whole history — this device would have to claim
+     * and finish `MAX_TRACKED_TASK_IDS` more tasks before a genuinely-still-
+     * pending redelivery for an older taskId even arrives, let alone gets
+     * processed, for eviction to ever remove an entry that redelivery still
+     * needed.
+     *
+     * Finding #5 (honesty follow-up): unlike `pendingCancelled`, plain
+     * oldest-first eviction IS correct here — every entry in this set is
+     * already fully resolved (finish() only adds a taskId after it reached a
+     * terminal outcome), so there is no "in-flight" entry an eviction could
+     * corrupt out from under a running `handleOffer()`. The assumption above
+     * is a HEURISTIC bound, not a proof: it holds as long as no single
+     * connection's genuinely-still-pending redelivery backlog ever exceeds
+     * `MAX_TRACKED_TASK_IDS` finished tasks, which is a real (if distant)
+     * possibility for an extremely long-stalled connection, not a
+     * mathematical impossibility. Should it ever be violated, the failure
+     * mode is strictly milder than `pendingCancelled`'s own pre-fix bug: a
+     * redelivered `task.offer` for an evicted, already-finished taskId would
+     * re-run `handleOffer` from scratch — at worst a duplicate
+     * claim/start/complete for a task that already succeeded once — never a
+     * task that should be dead starting a brand-new session against explicit
+     * cancellation intent.
+     */
+    private readonly finishedTaskIds;
+    /**
+     * M4 Phase 2 (daemon control socket `shutdown` RPC): set once by
+     * {@link stopAcceptingOffers}, checked at the very top of `handleOffer` —
+     * see that method's own doc comment for why offers must stop being
+     * claimed BEFORE currently-active tasks are reported failed in
+     * {@link shutdownActiveTasks}, not after. Irreversible for this
+     * `TaskRunner` instance; a fresh one is constructed on the daemon's next
+     * `start()`.
+     */
+    private stoppingOffers;
+    constructor(deps: TaskRunnerDeps);
+    get activeTaskCount(): number;
+    /** M5 batch-3 (workstream 2): effective `maxTaskOutputBytes` cap for this daemon — see {@link DEFAULT_MAX_TASK_OUTPUT_BYTES}'s own doc comment. */
+    private get maxTaskOutputBytes();
+    /**
+     * M4 Phase 4 (part B.3, observability): per-active-task queue watermarks
+     * for the control socket's `status` result — see
+     * `control-protocol.ts`'s `TaskQueueWatermark` doc comment for why this
+     * reflects the daemon's own progress-batcher backlog and in-flight
+     * approval count, not the adapter's own event-queue depth.
+     */
+    getQueueWatermarks(): TaskQueueWatermark[];
+    /** M4 Phase 2: stop claiming any FUTURE `task.offer` — see `stoppingOffers`'s own doc comment. Idempotent. */
+    stopAcceptingOffers(): void;
+    /**
+     * M4 Phase 2: best-effort shutdown of every currently ACTIVE task, for the
+     * control socket's `shutdown` RPC. Mirrors `handleCancel`'s best-effort
+     * `session.interrupt()` style (an interrupt failure is swallowed; the
+     * terminal message is sent either way) but reports `task.fail` rather than
+     * `task.cancelled` — these tasks aren't ending because the SERVER
+     * cancelled them, they're ending because this device is shutting down.
+     * `retryable: true` throughout: nothing about the task/policy itself was
+     * ever at fault, only this device's own availability right now.
+     *
+     * Snapshots `this.tasks` into a plain array up front rather than iterating
+     * the live `Map` — `finish()` (called per task below) deletes from that
+     * same map as each shutdown settles, and a snapshot avoids relying on
+     * "mutate while iterating" semantics being followed correctly here.
+     *
+     * Must be called AFTER {@link stopAcceptingOffers} and BEFORE the
+     * connection is closed: the caller (`create-daemon.ts`'s
+     * `performControlShutdown`) awaits this method to fully settle — every
+     * `task.fail` actually enqueued via `deps.send` — before it ever calls
+     * `stop()` (which closes the connection). Stopping offers first (rather
+     * than closing the connection first) is what prevents a new
+     * `task.offer` from being claimed in the window while these are being
+     * torn down.
+     *
+     * This ordering invariant is NOT just about `performControlShutdown`'s
+     * own internal statement order — it also depends on nothing ELSE
+     * closing the connection first. A real regression (gatekeeper-caught,
+     * fixed in `create-daemon.ts`/`bin/commands/start.ts`) had exactly that
+     * happen: `start.ts` used to wake up on the EARLIER `shutdown-requested`
+     * event (fired synchronously, before this method even calls
+     * `session.interrupt()`) and call `daemon.stop()` itself, racing ahead
+     * and closing the connection before this method's `task.fail` send ever
+     * reached the outbox drain. `start.ts` now waits for the LATER
+     * `shutdown-complete` event (emitted only after `performControlShutdown`'s
+     * own `stop()` call has already resolved), so it can no longer race
+     * ahead of this method — see `daemon-control-socket.test.ts`'s dedicated
+     * regression test for the exact scenario.
+     */
+    shutdownActiveTasks(reason: string): Promise<void>;
+    /**
+     * M5 batch-3 (workstream 2): the ONE shared per-task teardown sequence —
+     * "reuse the exact interrupt/teardown machinery `shutdownActiveTasks`
+     * uses, do not invent a second teardown path" applies to BOTH callers:
+     * graceful daemon shutdown ({@link shutdownTask}, `retryable: true`) and
+     * resource-limit enforcement ({@link failActiveTaskForResourceLimit},
+     * `retryable: false`, wall-clock `maxDurationMs` / output-cap
+     * `maxTaskOutputBytes`).
+     *
+     * Finding F5(a) (pre-existing, unchanged by this refactor):
+     * `session.interrupt()` is raced against `timeoutMs`
+     * ({@link DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS}, overridable via
+     * `TaskRunnerDeps.shutdownInterruptTimeoutMs`) rather than awaited
+     * unconditionally, so a hung `interrupt()` (a misbehaving adapter) can
+     * never block `task.fail` from being sent at all.
+     *
+     * New in this batch — hard-kill escalation: when `interrupt()` does NOT
+     * settle within that same grace window, `session.close()` is tried next
+     * (ALSO raced against `timeoutMs`, for the identical reason: a hung
+     * `close()` must not be able to block this forever either — which matters
+     * far more here than it used to for the pre-existing graceful-shutdown-only
+     * caller, since THAT path is additionally bounded by an outer deadline
+     * (`SHUTDOWN_TASK_TEARDOWN_DEADLINE_MS`/`DaemonConfig.shutdownGraceMs`,
+     * `create-daemon.ts`), while resource-limit enforcement fires during
+     * ordinary operation with no such outer bound watching it). `close()` is
+     * every adapter's harder teardown primitive — an actual process-level kill
+     * (SIGTERM, or `taskkill /F` on Windows — see e.g.
+     * `ClaudeProcessClient.kill()`/`PiRpcClient.kill()`) as opposed to pi's own
+     * soft in-band `interrupt()` (an RPC `abort` message that leaves the
+     * process alive and resumable) — so escalating to it is the closest thing
+     * to a "hard kill" the `Session` interface exposes. `finish()` below calls
+     * `session.close()` again regardless (documented idempotent) — this isn't
+     * a substitute for that, only an earlier, bounded attempt at actually
+     * stopping a stuck runtime before this method gives up and reports failure
+     * anyway.
+     *
+     * Re-checks task identity (`this.tasks.get(...) === active`) immediately
+     * before sending `task.fail`: the interrupt/hard-kill race above has await
+     * points during which a DIFFERENT path (a racing `task.cancel`/
+     * `task.reject`, or the session completing normally on its own) may have
+     * already finished this exact task and sent its own terminal message.
+     * Sending a SECOND terminal message for an already-finished task would be
+     * a genuine protocol bug, not a benign race — mirrors `pump()`'s own
+     * identity-check guard for the same class of race.
+     */
+    private teardownActiveTask;
+    /** Graceful-shutdown caller of {@link teardownActiveTask} — see `shutdownActiveTasks`'s own doc comment. `retryable: true`: nothing about the task/policy itself was ever at fault, only this device's own availability right now. */
+    private shutdownTask;
+    /**
+     * M5 batch-3 (workstream 2): shared entry point for both resource-limit
+     * enforcers (wall-clock `maxDurationMs` — {@link armMaxDurationTimer} —
+     * and output-cap `maxTaskOutputBytes` — see `pump`). Looks the task up
+     * FRESH by id and no-ops if it's already gone — finished via any other
+     * path (normal completion, cancel, reject, daemon shutdown, or a
+     * DIFFERENT resource-limit trip already caught it first). `retryable:
+     * false` unconditionally: hitting a configured resource ceiling is never a
+     * transient/environmental failure a retry could fix — the same task under
+     * the same limits would just hit it again.
+     */
+    private failActiveTaskForResourceLimit;
+    /**
+     * M5 batch-3 (workstream 2): daemon-authoritative wall-clock enforcement
+     * for `payload.limits.maxDurationMs` — previously accepted and silently
+     * ignored (see `handleOffer`'s own doc comment on the `limits.maxTokens`
+     * gate for the historical context this superseded). Armed once, at the
+     * moment this task is registered as active (`handleOffer`, still inside
+     * the synchronous construct -> register -> arm -> pump handoff — arming a
+     * timer is synchronous, `setTimeout` never invokes its callback in the
+     * same tick, so this doesn't reopen the race that handoff's own doc
+     * comment guards against). Cleared unconditionally in `finish()` so every
+     * terminal outcome leaves no dangling timer and can never double-fail an
+     * already-finished task — the fresh `this.tasks.get` lookup in
+     * `failActiveTaskForResourceLimit`/`teardownActiveTask`'s own identity
+     * re-check is the second, belt-and-suspenders layer of that same guarantee
+     * for the rare case the timer's callback was already scheduled before
+     * `finish()` had a chance to clear it.
+     */
+    private armMaxDurationTimer;
+    handleEnvelope(envelope: Envelope): Promise<void>;
+    private handleOffer;
+    /** Protocol §7: an instruction too large to inline arrives as a `blobRef` — resolve it via the blob client rather than failing closed. */
+    private resolveInstruction;
+    private pump;
+    /**
+     * Protocol §7: an `artifact` `AgentEvent` only names a file the runtime
+     * wrote into the task workspace (`name`/`contentType` — it carries no
+     * content of its own); this reads it from disk and sends the actual
+     * `task.artifact` wire message — inline (base64) under 64KB, or via blob
+     * upload above that, with a sha-256 `contentHash`.
+     *
+     * Finding F7/N5: `name` is untrusted (it's whatever the runtime/agent
+     * reported — ultimately model-influenced) and used to be `path.join`'d
+     * onto `workspaceDir` with no check that the result stayed inside it, so
+     * `../../<anything>` (or an absolute `name`, which `path.resolve` accepts
+     * verbatim as the whole path) could read and exfiltrate an arbitrary file
+     * on the host as a task artifact. A later fix (`resolveArtifactPath`)
+     * closed the traversal case by realpath-checking containment, but still
+     * returned a path string that was reopened by pathname afterward — a
+     * check-then-use TOCTOU race letting the final component be swapped for
+     * an out-of-workspace symlink between the check and the read.
+     * `openArtifact` now opens the file (with `O_NOFOLLOW`) and verifies the
+     * resulting file descriptor directly; this reads from that same handle,
+     * never re-opening by pathname. Read/upload failures (including a
+     * rejected name or a blocked symlink swap) are also not silent: they
+     * surface as a loud `error` `AgentEvent` batched into `task.progress`,
+     * and are logged — the task itself can still reach `task.complete`
+     * normally, but the dropped artifact is now visible in the event stream
+     * rather than swallowed.
+     */
+    private sendArtifact;
+    /** Loud, non-silent artifact failure (finding F7): logged, and folded into this task's own progress stream as an `error` AgentEvent rather than swallowed — the task itself can still complete normally, but the omission is now visible. */
+    private reportArtifactError;
+    private handleCancel;
+    /** M3-B: bounded insert for `pendingCancelled` — see its class-level doc comment and `MAX_TRACKED_TASK_IDS`. Evicts the oldest SAFE-TO-EVICT entry once over cap — see `evictPendingCancelled` (finding #5: not simply "the oldest entry", which could be an in-flight offer's own cancel marker). */
+    private setPendingCancelled;
+    /**
+     * Finding #5 (Codex counterexample — see `inFlightOffers`'s class-level
+     * doc comment for the exact scenario): evicts the OLDEST entry that is
+     * NOT a taskId currently inside `handleOffer`'s in-flight window, rather
+     * than unconditionally the single oldest entry. `Map` iterates in
+     * insertion order, so this is "oldest entry that's safe to drop," which
+     * only differs from "the oldest entry, period" when that oldest entry
+     * happens to belong to a task still being processed — exactly the case
+     * that must never be evicted, since `handleOffer`'s own checkpoint 2
+     * still needs to observe it.
+     *
+     * `inFlightOffers` is naturally tiny (bounded by this device's real
+     * concurrent-offer-processing count — normally single digits, driven by
+     * how many `task.offer`s are simultaneously mid-`adapter.start()` — nowhere
+     * near `MAX_TRACKED_TASK_IDS`), so this scan is cheap in practice: it
+     * finds a safe entry at or near the front almost always. The only case
+     * where NO entry is safe to evict is every single tracked cancel
+     * belonging to a currently in-flight offer, which would require this
+     * device to have `MAX_TRACKED_TASK_IDS` offers mid-processing
+     * simultaneously — implausible, but handled without corrupting anything:
+     * this insert is simply allowed to leave the map one entry over cap
+     * rather than evict something still needed, and it shrinks back under cap
+     * as those in-flight offers resolve and their entries get CONSUMED
+     * (deleted by `handleOffer` itself) rather than evicted.
+     */
+    private evictPendingCancelled;
+    /**
+     * S0/H-006: an inbound `task.steer` is normally impossible for a runtime
+     * that cannot steer — the hub gates it at claim-time capability
+     * (`steer_unsupported_runtime`) and never sends the envelope. If one
+     * arrives anyway (a forged sender, a pre-gate server, a device whose
+     * adapter set changed), the session throws {@link SteerUnsupportedError},
+     * which is a PERMANENT property of that runtime, not a transient failure.
+     *
+     * Rethrowing it would hand it to `ConnectionManager.process()`
+     * (`connection-manager.ts` `stalledAtSeq`), which freezes the cursor at
+     * that seq and redelivers the same envelope forever — every retry
+     * guaranteed to fail identically, and every later envelope for every
+     * other task blocked behind it. So this is classified as a
+     * non-retryable protocol/authority error: record it and return normally,
+     * which acks the envelope and lets the cursor advance. Nothing is
+     * swallowed — the steer simply has no reachable success state, and the
+     * honest terminal action is to log it and move on.
+     *
+     * Every OTHER error stays transient and is rethrown untouched, preserving
+     * the existing stall/redelivery semantics exactly.
+     */
+    private handleSteer;
+    /**
+     * M4 Phase 3: the daemon-side half of the out-of-band approval channel
+     * (`types.ts`'s `ApprovalChannel`) — called from `create-daemon.ts`'s
+     * `approvals.request` control method, itself called by `byok-approval-mcp`
+     * (a claude-spawned MCP-server child process, NOT the adapter/session
+     * in-process — see `ApprovalChannel`'s own doc comment for the full why
+     * this seam exists at all rather than an `AgentEvent`).
+     *
+     * Deliberately independent of the dormant `needs_approval` `AgentEvent`
+     * path in `pump()` below (~line 611): empirically confirmed (M4 Phase 3
+     * STEP 0), claude's own stream-json output emits NOTHING while a
+     * permission-prompt-tool call is outstanding — the gap between a `tool_use`
+     * frame and its `tool_result` is invisible on the wire, indistinguishable
+     * from ordinary model "thinking" latency. `pump()`'s for-await loop over
+     * `active.session.events` therefore has no event to ever branch on for
+     * this case; the ONLY signal that a task is paused arrives out-of-band,
+     * over the control socket, which is exactly what this method is for. The
+     * `needs_approval` path stays dormant, untouched, for a hypothetical
+     * future adapter whose runtime DOES expose the pause on its own event
+     * stream.
+     *
+     * Sends `task.await_approval` (protocol §5), registers a fresh entry in
+     * `deps.approvalRegistry`, and races it against `deps.approvalTimeoutMs`
+     * (default {@link DEFAULT_APPROVAL_TIMEOUT_MS}) — an unanswered request
+     * force-resolves as a fail-closed rejection once the deadline passes. Both
+     * that timeout AND a real decision (server wire `task.approve`/
+     * `task.reject` via `handleApprove`/`handleReject` below, OR the local
+     * CLI's `approvals.resolve` in `control-server.ts`) converge on the exact
+     * same `ApprovalRegistry.resolve()` call — "first resolution wins, the
+     * loser is a clean already-resolved no-op" is `ApprovalRegistry`'s own
+     * existing guarantee, reused here rather than reimplemented.
+     *
+     * Fails closed immediately (no registry entry ever created) for a `taskId`
+     * that isn't currently active on this device — a stale/unknown/
+     * already-finished task has nothing to pause.
+     *
+     * M4 Phase 4 (fold-in from the P3 gate — concurrent-approval-overwrite
+     * fix): claude's parallel tool use can call this MORE THAN ONCE for the
+     * SAME task before the first call's approval is resolved — each parallel
+     * tool call is its own independent `byok-approval-mcp` `tools/call`
+     * request, and the MCP protocol lets several be in flight on one
+     * connection at once (see `byok-approval-mcp.ts`'s own doc comment on
+     * sharing one control-socket connection across them). Before this fix,
+     * `active.pendingApprovalId = approvalId` above was unconditional — a
+     * second concurrent call for the same task silently overwrote the first
+     * call's id, so only the LATEST request was ever wire-resolvable
+     * (`ctx.approvalChannel.resolve`, below, and any server `task.approve`/
+     * `task.reject`, both resolve by looking up `active.pendingApprovalId`);
+     * every earlier one could only ever time out.
+     *
+     * Fix: only ONE approval per task is ever actually DISPATCHED (registered
+     * in `approvalRegistry` + `task.await_approval` sent + its own timeout
+     * window running) at a time — see `dispatchApproval` below. A second
+     * (third, ...) concurrent call for a task that already has one dispatched
+     * queues (FIFO, `active.approvalQueue`) instead of overwriting anything,
+     * and is only dispatched — with its OWN fresh approvalId and its OWN
+     * timeout window starting at THAT dispatch, not at this call's arrival —
+     * once the currently-dispatched one resolves (see
+     * `dispatchNextQueuedApproval`). The MCP callers on the other end are
+     * already independently blocked, each awaiting its own `requestApproval`
+     * promise, so this added latency for a queued request is transparent to
+     * them: nothing here changes what claude itself observes beyond "the
+     * answer took a bit longer." Bounded by
+     * {@link MAX_PENDING_APPROVALS_PER_TASK}: a request arriving once this
+     * task's queue is already full is rejected fail-closed immediately,
+     * mirroring the unknown/inactive-taskId case above.
+     *
+     * C1 (cross-model review, P1): `onOrigin`, if supplied, is invoked
+     * synchronously — strictly BEFORE this method's own returned promise
+     * resolves — with the `ApprovalOrigin` (`'wire' | 'local'`) the eventual
+     * decision actually resolved through (see `ApprovalRegistry.resolve`'s own
+     * `origin` parameter). Purely additive/internal: every existing caller
+     * (`byok-approval-mcp.ts`, `create-daemon.ts`'s control socket, this file's
+     * own tests) omits it and observes exactly the same `{approved, reason}`
+     * resolution as before. `pump()`'s dormant `needs_approval` branch is the
+     * one caller that supplies it, to decide whether it still needs to
+     * forward the decision into `active.session.resolveApproval()` itself —
+     * see that branch's own doc comment for why origin can't simply ride
+     * along on the resolved value instead.
+     */
+    requestApproval(taskId: string, summary: string, onOrigin?: (origin: ApprovalOrigin) => void): Promise<{
+        approved: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Actually dispatch one approval request for `active`'s task: register it
+     * in `deps.approvalRegistry`, send its `task.await_approval`, and start its
+     * own `deps.approvalTimeoutMs` window — see `requestApproval`'s own doc
+     * comment for why this is split out (only ever ONE dispatched per task at
+     * a time; everything else queues). Called either immediately
+     * (`requestApproval`, nothing else pending for this task) or from
+     * `dispatchNextQueuedApproval` once the previously-dispatched request for
+     * this same task resolves.
+     *
+     * C1: `onOrigin` — see `requestApproval`'s own doc comment — is forwarded
+     * verbatim from whichever caller dispatched this (directly, or via
+     * `QueuedApprovalRequest.onOrigin` once `dispatchNextQueuedApproval` pulls
+     * it off the queue) and invoked from the registered `onResolve` callback
+     * below, BEFORE `resolve(...)` — so it always fires strictly before this
+     * method's own returned promise settles.
+     */
+    private dispatchApproval;
+    /**
+     * M4 (additive-minor, `task.approval_resolved` — see `messages.ts`'s own
+     * doc comment on `TaskApprovalResolvedPayloadSchema` for the full wire
+     * rationale): report a LOCALLY-resolved approval to the server
+     * immediately, gated on the negotiated `approval_resolved` capability
+     * (`deps.getServerCapabilities` — an old server that never advertises it
+     * never receives this message; the daemon then falls back to the
+     * pre-existing implicit-resume inference, unconditionally, exactly as
+     * before this message existed — the N/N-1 compatibility path).
+     *
+     * Ordering (verified by `task-runner-approval-resolved.test.ts`): this is
+     * called, and therefore `deps.send` pushes this envelope onto the outbox,
+     * SYNCHRONOUSLY from the `onResolve` callback above — strictly BEFORE the
+     * `resolve(...)` call on the very next line that unblocks whatever was
+     * awaiting `requestApproval()`'s promise (`byok-approval-mcp`, ultimately
+     * the paused runtime turn). Any further progress from the resumed session
+     * can only be produced AFTER that unblock, which needs at least one more
+     * microtask/event-loop turn — so `task.approval_resolved` is always queued
+     * ahead of it with no extra bookkeeping needed here.
+     */
+    private sendApprovalResolved;
+    /**
+     * FIFO: once a task's currently-dispatched approval resolves (real
+     * decision or timeout), dispatch the next queued request for that SAME
+     * task, if any — see `requestApproval`'s own doc comment. A no-op when
+     * nothing is queued.
+     */
+    private dispatchNextQueuedApproval;
+    /**
+     * Acceptance finding 1 (dormant `needs_approval` branch bypassing the
+     * approval registry): resolves whatever `deps.approvalRegistry` entry
+     * `pendingId` names (if any — a caller passes `undefined` when nothing was
+     * pending to begin with), tagged `'wire'` — the same origin
+     * `ctx.approvalChannel.resolve` already uses for a server-sent
+     * `task.approve`/`task.reject` (see `ApprovalOrigin`'s own doc comment:
+     * `'wire'` is what keeps `sendApprovalResolved` from echoing
+     * `task.approval_resolved` back to a server that already knows this
+     * decision, since it sent it).
+     *
+     * Needed because `active.session.resolveApproval()` is adapter-defined:
+     * - A channel-based session (claude) already resolves this exact registry
+     *   entry itself, via `ctx.approvalChannel.resolve` (`handleOffer` above)
+     *   — by the time this runs, that entry is already gone, so this call
+     *   throws `ApprovalNotFoundError`, swallowed below: the same
+     *   first-resolution-wins race every other caller of `.resolve()` in this
+     *   file already treats as benign (see e.g. `dispatchApproval`'s own
+     *   timeout branch).
+     * - A stream-based session (the dormant `needs_approval` path in `pump()`,
+     *   now dispatched via `requestApproval` exactly like a real out-of-band
+     *   approval) resolves ONLY through its own in-process `resolveApproval()`
+     *   call — nothing else ever touches `deps.approvalRegistry` for it, so
+     *   without this call its registry entry and `active.pendingApprovalId`
+     *   would otherwise linger until this approval's own timeout (or the task
+     *   finishing) instead of clearing the moment the decision actually lands
+     *   — which would leave any OTHER approval queued behind it
+     *   (`active.approvalQueue`) stuck waiting for that same timeout.
+     *
+     * Called from `handleApprove`/`handleReject` AFTER `active.session
+     * .resolveApproval()` has already been given the decision — never before,
+     * since for the channel-based case that call is what actually resolves
+     * the registry entry `pendingId` names.
+     *
+     * CRITICAL follow-up to finding 1 above: `pendingId` is a required
+     * parameter — deliberately NOT read from `active.pendingApprovalId` inside
+     * this method (indeed, this method no longer takes `active` at all). For a
+     * channel-based session (claude), the `await active.session
+     * .resolveApproval()` in `handleApprove`/`handleReject` BELOW THIS CALL is
+     * exactly what synchronously drives `ctx.approvalChannel.resolve` ->
+     * `approvalRegistry.resolve(A)` -> A's own `onResolve`
+     * (`dispatchApproval` above) -> `dispatchNextQueuedApproval` — and that
+     * last step, still inside the SAME synchronous call and therefore still
+     * strictly BEFORE the caller's own `await` settles, dispatches the next
+     * queued approval (B) and reassigns `active.pendingApprovalId = B`. A
+     * caller that read `active.pendingApprovalId` only AFTER that `await`
+     * returned (as this method itself used to, before it took `pendingId` as a
+     * parameter) would therefore observe B, not A — resolving B (silently,
+     * with A's decision: an auto-approve or a force-reject of an approval no
+     * one ever actually decided) instead of the already-gone entry for A this
+     * call is actually meant to (harmlessly) no-op against. Callers now
+     * capture the target id BEFORE that await (`handleApprove`/`handleReject`
+     * below) so this can only ever be asked to resolve the id it was meant to
+     * all along. See `task-runner-approval.test.ts`'s channel-routing
+     * regression test for this exact interleaving reproduced end to end.
+     */
+    private clearPendingApproval;
+    /**
+     * Protocol §5 approval flow: the server's own state already moved
+     * `AwaitApproval -> Running` before this best-effort notification arrives
+     * (§4) — resuming the session is what makes `task.progress` continue.
+     *
+     * M4 Phase 3 hardening (orchestrator-directed fix): a wire `task.approve`
+     * can legitimately arrive AFTER a different, faster path (a racing local
+     * `approvals.resolve` over the control socket, or this exact message
+     * redelivered) already resolved the SAME approval — `ApprovalRegistry`'s
+     * own "first resolution wins" guarantee means `session.resolveApproval()`
+     * throws {@link NoPendingApprovalError} for that loser, not because
+     * anything is actually wrong. Before this fix, ANY thrown error here
+     * (stale or genuine) failed the whole task — for the stale case that
+     * meant a task the winning path had ALREADY correctly resumed (and which
+     * may go on to complete normally) got marked `Failed` anyway, purely
+     * because a second, now-meaningless notification arrived late. Stale is
+     * now an audit-only no-op; a genuine failure (the session itself
+     * couldn't resume for some real reason) still fails the task exactly as
+     * before.
+     */
+    private handleApprove;
+    /**
+     * Protocol §5 approval flow: the server's own state already moved
+     * `AwaitApproval -> Failed` before this best-effort notification arrives
+     * (§4) — the daemon's job is just to stop the session and prove it via
+     * `task.fail`.
+     *
+     * M4 Phase 3 hardening (orchestrator-directed fix): same race as
+     * `handleApprove` above, but the pre-fix bug here was worse — this method
+     * unconditionally interrupted the session and sent `task.fail` regardless
+     * of whether `resolveApproval` even threw, so a stale/late wire
+     * `task.reject` (the local CLI, or a racing wire approve, already
+     * resolved this exact approval a different way) would tear down and fail
+     * a task that was already correctly approved and possibly still running
+     * fine. Now: a {@link NoPendingApprovalError} short-circuits to an
+     * audit-only no-op BEFORE the interrupt/fail/finish sequence — nothing
+     * about this task's state is touched. Any OTHER outcome (success, or a
+     * genuine non-staleness error) falls through to the existing
+     * interrupt+`task.fail`+finish sequence unchanged: the server's own
+     * record already moved `AwaitApproval -> Failed` for a REAL reject
+     * (§4's "server state is authoritative on its own action" rule), so the
+     * daemon must still conform to that regardless of whether telling the
+     * session about it succeeded.
+     */
+    private handleReject;
+    /** Pre-claim, fail-closed rejection (protocol §3.2) — never claims first. */
+    private decline;
+    private fail;
+    private observeGit;
+    private updateGitPhaseBestEffort;
+    private finish;
+    /** M3-B: bounded insert for `finishedTaskIds` — see its class-level doc comment and `MAX_TRACKED_TASK_IDS`. Evicts the oldest (first-inserted) entry once over cap, same idiom as `ConnectionHub.checkAndRecordDuplicate` (packages/server/src/hub.ts). */
+    private addFinishedTaskId;
+    /** `reuseDir`, when set (a known sessionRef's recorded workspace), is used verbatim instead of a fresh `workspaceRoot/<taskId>` directory — `mkdir recursive` is idempotent either way, so ensuring-exists is safe to do unconditionally. */
+    private resolveWorkspaceDir;
+    /**
+     * M5 batch-3 (workstream 1): selects which adapter runs this offer, now
+     * gated on both PRESENCE (`adapter.detect()`, as before) and CAPABILITY
+     * (`adapterSupportsMode` — can this adapter even express `policyMode`?
+     * new in this batch) — pre-claim, in both the explicit-runtime and
+     * auto-select branches.
+     *
+     * Explicit-runtime branch (`requestedRuntime` set): semantics otherwise
+     * unchanged from before this batch — allowlist and known-adapter checks
+     * first, THEN the new capability check, THEN presence. A capability
+     * mismatch here is a permanent characteristic of naming THIS runtime with
+     * THIS policy (e.g. pi never supports `confirm`, on any device, by
+     * design — `pi/permission-mapping.ts`) — `retryable: false`, the same
+     * class as "not in allowlist"/"unknown runtime" above it, since retrying
+     * this exact (runtime, mode) pair anywhere changes nothing.
+     *
+     * Auto-select branch (`requestedRuntime` absent): candidates are ordered
+     * by `runtimePreference` (default {@link DEFAULT_RUNTIME_PREFERENCE}) —
+     * see `orderByPreference` — then walked in that order; a candidate that
+     * can't express `policyMode` is skipped (not detected at all — capability
+     * is checked first, cheaper than a real subprocess probe) and the walk
+     * continues down the preference order, exactly as "skip non-supporting
+     * adapters and continue down the order" describes. If NOTHING eligible
+     * supports the mode, `retryable: true` — unlike the explicit branch, this
+     * is device-specific (which runtimes happen to be installed here), so a
+     * different device's installed runtime set might satisfy it.
+     */
+    private pickAdapter;
+}