@byok-sdk/client 0.2.0 → 0.4.0

package/dist/daemon/observer.d.ts

@@ -20,8 +20,8 @@ import type { ConnectionState } from './ws-transport';
  * - `ConnectionManagerOptions.onEnvelope`/`onStateChange` — likewise already
  *   `create-daemon.ts`'s own closures (`(envelope) =>
  *   runner?.handleEnvelope(envelope)`, `(state) => { connectionState = state;
- *   }`). `onEnvelope` additionally exposes the raw INBOUND `task.offer` — the
- *   one event with no corresponding outbound envelope of its own — see
+ *   }`). `onEnvelope` additionally exposes the raw INBOUND offer variants —
+ *   the one event class with no corresponding outbound envelope of its own — see
  *   `handleInboundEnvelope`.
  *
  * Neither seam required adding anything to `TaskRunnerDeps`/`TaskRunner`
@@ -188,6 +188,57 @@ export type DaemonEvent = {
         conflicted: number;
     };
     errorCategory?: string;
+} | {
+    kind: 'runtime-disposal-failed';
+    ts: string;
+    taskId: string;
+    runtimeId: string;
+    stage: 'signal' | 'quiescence' | 'cleanup';
+    reason: string;
+}
+/**
+ * Plan `device-assertion-broker`: one `assertion.issue` control call
+ * resolved — either an assertion was minted (`issued`) or one of the six
+ * fail-closed gates refused (`denied`, with `reason` naming which one; see
+ * `ASSERTION_ISSUE_ERROR_CODES`, `control-protocol.ts`).
+ *
+ * ONE kind for both outcomes, so an operator reading the feed sees the
+ * issuance rate and the refusal rate on the same line shape rather than
+ * having to correlate two.
+ *
+ * The signature and the envelope bytes are NOT fields of this event and
+ * never can be. That is structural, not a redaction rule: `bin/audit-log.ts`
+ * can only drop what it is handed, and an event type that cannot carry a
+ * signature cannot leak one into a durable file no matter how the audit
+ * projection is later edited. What IS carried is the metadata an incident
+ * needs — which audience, which `jti` (so a suspect assertion presented to
+ * the host's cloud can be traced back to the exact local call that minted
+ * it), and when it expires.
+ *
+ * codex round-2 F4 — the union is split by `result` for the same structural
+ * reason: on the ISSUED path `audience` came from this daemon's own
+ * configured allowlist (operator-authored, safe verbatim), but on the DENIED
+ * path it is whatever the CALLER sent — free text that could be a PEM, a
+ * signature, or any secret shaped as an audience. So the denied variant has
+ * NO raw `audience` field at all; it carries only `audienceSize` (a byte
+ * count), computed at event-construction time (`noteDeviceAssertion`). The
+ * raw denied audience therefore never reaches the observer feed, `format.ts`,
+ * daemon stdout, or the audit file — there is no field to carry it, rather
+ * than a redactor that has to remember to strip it.
+ */
+ | {
+    kind: 'device-assertion';
+    ts: string;
+    result: 'issued';
+    audience: string;
+    jti: string;
+    expiresAt: string;
+} | {
+    kind: 'device-assertion';
+    ts: string;
+    result: 'denied';
+    reason: string;
+    audienceSize?: number;
 };
 export type DaemonEventListener = (event: DaemonEvent) => void;
 export type Unsubscribe = () => void;
@@ -246,7 +297,7 @@ export declare class DaemonObserver {
     tasks(): DaemonTaskInfo[];
     /**
      * Feed a raw INBOUND (server -> daemon) envelope. Deliberately narrow: only
-     * `task.offer` produces a local event here — every other inbound type
+     * either offer variant produces a local event here — every other inbound type
      * (`task.cancel`/`task.steer`/`task.approve`/`task.reject`) is a
      * best-effort notification whose OWN observable effect already surfaces
      * through the daemon's outbound envelopes (`task.cancelled`, `task.progress`
@@ -269,6 +320,27 @@ export declare class DaemonObserver {
     noteShutdownRequested(reason: string): void;
     /** M4 Phase 2: see the `shutdown-complete` `DaemonEvent` variant's own doc comment (finding F5(b): `undeliveredOutboxCount`). */
     noteShutdownComplete(reason: string, undeliveredOutboxCount?: number): void;
+    /**
+     * Plan `device-assertion-broker`: see the `device-assertion` `DaemonEvent`
+     * variant's own doc comment. The parameter type is what keeps the signature
+     * out — there is no field to pass one through.
+     *
+     * codex round-2 F4: the DENIED caller can pass its raw `audience` here, but
+     * it is converted to a byte SIZE the instant the event is constructed and the
+     * raw string is dropped — it is never placed on the emitted `DaemonEvent`, so
+     * it cannot reach a subscriber, `format.ts`, stdout, or the audit file. The
+     * ISSUED `audience` came from the allowlist and is kept verbatim.
+     */
+    noteDeviceAssertion(event: {
+        result: 'issued';
+        audience: string;
+        jti: string;
+        expiresAt: string;
+    } | {
+        result: 'denied';
+        reason: string;
+        audience?: string;
+    }): void;
     /** M4 Phase 3 hardening: see the `stale-approval-decision` `DaemonEvent` variant's own doc comment. */
     noteStaleApprovalDecision(taskId: string, decision: 'approve' | 'reject', reason?: string): void;
     noteGitWorkspace(event: {
@@ -285,6 +357,12 @@ export declare class DaemonObserver {
         };
         errorCategory?: string;
     }): void;
+    noteRuntimeDisposalFailure(event: {
+        taskId: string;
+        runtimeId: string;
+        stage: 'signal' | 'quiescence' | 'cleanup';
+        reason: string;
+    }): void;
     /**
      * Finding F4: wired from `TaskRunnerDeps.onApprovalDispatched`, called
      * synchronously by `TaskRunner.dispatchApproval` BEFORE its own

package/dist/daemon/presence-publisher.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Presence producer (§12.3): a periodic `{ level: 'online' }` heartbeat to
+ * `PUT /byok/presence`, started only when the deployment's capability
+ * declaration contains `presence.hints` (ADR-010 — see `capabilities-client.ts`).
+ *
+ * Three properties this module deliberately holds:
+ *
+ *  - **Only `online`.** The five levels exist in core, but nothing downstream
+ *    consumes a `thinking`/`working`/`error` mapping yet, so none is invented
+ *    here. That also keeps the rule below trivially true.
+ *  - **It never reads or writes task state.** Presence is a lossy, unsigned,
+ *    TTL-bounded hint that must never become coordination or execution state
+ *    (`@byok-sdk/core`'s `presence.ts` module doc). This publisher's only input
+ *    is a clock.
+ *  - **Stopping IS the offline signal.** No explicit `offline` publish on
+ *    shutdown: the hosted hint carries a TTL and expiry means *absence*, so a
+ *    daemon that stops beating disappears on its own. Publishing `offline` too
+ *    would express the same fact through a second channel that a crashed daemon
+ *    could never use anyway.
+ *
+ * Auth reuses the daemon's one device-token lifecycle: {@link authedFetch}
+ * attaches the current bearer and, on a 401, renews once through `AuthManager`
+ * and retries exactly once. A revoked device (`DeviceRevokedError`) stops this
+ * publisher permanently — there is no recourse but a fresh `pair()`, so
+ * retrying would be a pure spin.
+ */
+import { type ToolsetId } from '@byok-sdk/protocol';
+import type { AuthManager } from './auth-manager';
+/**
+ * Client-side defaults, chosen against the hosted defaults
+ * (`@byok-sdk/cloud`'s `DEFAULT_PRESENCE_TTL_MS` = 90s,
+ * `DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS` = 5s) and core §12.7.5's suggested
+ * 60-120s presence TTL. Spelled out here rather than imported: the daemon must
+ * not depend on the hosted package, and these are this producer's own cadence
+ * expectations, not a mirror of any deployment's configuration.
+ *
+ * The invariant that matters is `minimumIntervalMs < intervalMs < ttlMs`,
+ * asserted in the constructor: beat faster than the store's throttle and every
+ * other beat is rejected as `hint_rate_limited`; beat slower than the TTL and
+ * the device flickers offline between beats.
+ */
+export declare const DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const DEFAULT_PRESENCE_TTL_MS = 90000;
+export declare const DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS = 5000;
+/**
+ * The cadence invariant, as a function so the two places that need it — this
+ * module's constructor and `create-daemon.ts`'s synchronous config validation —
+ * share one authority instead of two spellings of the same band.
+ *
+ * @throws {Error} when the cadence is outside `minimumIntervalMs < intervalMs < ttlMs`.
+ */
+export declare function assertPresenceHeartbeatCadence(cadence: {
+    intervalMs: number;
+    ttlMs: number;
+    minimumIntervalMs: number;
+}): void;
+export interface PresencePublisherOptions {
+    serverUrl: string;
+    auth: AuthManager;
+    /** Sorted logical IDs only. Executable MCP definitions and credentials remain device-local. */
+    configuredToolsets?: readonly ToolsetId[];
+    /** Heartbeat cadence. Must sit strictly between {@link PresencePublisherOptions.minimumIntervalMs} and {@link PresencePublisherOptions.ttlMs}. */
+    intervalMs?: number;
+    /** The deployment's presence hint TTL, as this daemon understands it. Only used to validate the cadence. */
+    ttlMs?: number;
+    /** The deployment's minimum accepted interval between publications, as this daemon understands it. Only used to validate the cadence. */
+    minimumIntervalMs?: number;
+    /**
+     * Observable degradation sink — one line per publish failure and one for the
+     * permanent stop. The daemon passes its `console.warn` convention; tests read
+     * it directly instead of scraping stdout.
+     */
+    onDegraded?: (reason: string) => void;
+}
+/**
+ * Periodic `online` heartbeat. Construct once per `start()`, {@link stop} it in
+ * the shutdown sequence.
+ *
+ * The loop is a self-rescheduling `setTimeout` rather than `setInterval`: a slow
+ * publish must delay the next beat, not queue a second one behind it.
+ */
+export declare class PresencePublisher {
+    private readonly opts;
+    private readonly url;
+    private readonly intervalMs;
+    private timer;
+    private running;
+    /** Set once a revoked device is observed. Terminal: `start()` will not restart this instance. */
+    private stoppedPermanently;
+    constructor(opts: PresencePublisherOptions);
+    /** Publishes immediately, then every `intervalMs`. Idempotent; a no-op after a permanent stop. */
+    start(): void;
+    /** Stops the cadence. Idempotent, and the only "offline" signal this producer emits — the hint's TTL does the rest. */
+    stop(): void;
+    private schedule;
+    private beat;
+    private stopPermanently;
+}

package/dist/daemon/runtime-capabilities.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeCapabilities as ProtocolRuntimeCapabilities } from '@byok-sdk/protocol';
 import type { RuntimeCapabilities } from '../types';
 /**
- * Maps a `RuntimeAdapter`'s own internal `capabilities()` result
+ * Maps a frozen `RuntimeAdapterDescriptor`'s internal `capabilities` value
  * (`../types.ts`'s `RuntimeCapabilities` — `{steer, resume,
  * approvalInteractive, permissionModes}`, always-required fields) onto the
  * wire's `RuntimeCapabilities` shape (`@byok-sdk/protocol` — the same field names,

package/dist/daemon/skill-pack-installer.d.ts

@@ -0,0 +1,116 @@
+import { type CapabilityDeclaration } from '@byok-sdk/core';
+import type { AuthManager } from './auth-manager';
+/**
+ * The hosted capability this pipeline gates on. A plain string, not an import
+ * from `@byok-sdk/cloud`: the daemon must not gain a dependency on the hosted
+ * implementation, and ADR-010 makes capability names deployment vocabulary that
+ * core validates the shape of but never the meaning of. Same rule the presence
+ * producer's `PRESENCE_HINTS_CAPABILITY` follows.
+ */
+export declare const SKILL_PACKS_CAPABILITY = "skills.pack";
+/** Directory under `dataDir` this module owns end to end. */
+export declare const SKILL_PACKS_DIRNAME = "skill-packs";
+/** Per-pack pointer at the installed content-addressed revision. */
+export declare const SKILL_PACK_LOCK_FILENAME = "lock.json";
+/** Append-only install/refusal record, beside the packs it describes. */
+export declare const SKILL_PACK_AUDIT_FILENAME = "audit.jsonl";
+export declare const SKILL_PACK_LOCK_SCHEMA = "byok-skill-pack-lock-v1";
+/**
+ * Ceiling on a single HTTP response this pipeline will read into memory.
+ *
+ * Deliberately derived from the pack cap rather than chosen independently: the
+ * largest legitimate manifest list is bounded by what a pack may declare, and a
+ * response beyond that is refused before it is parsed rather than after. A
+ * transfer cap that is not evaluated is the exact failure this plan set out not
+ * to repeat.
+ */
+export declare const SKILL_PACK_RESPONSE_MAX_BYTES: number;
+export declare const SKILL_PACK_INSTALL_ERROR_CODES: readonly ['capability_unavailable', 'transport_failed', 'response_invalid', 'response_too_large', 'manifest_invalid', 'content_rejected', 'store_unsafe'];
+export type SkillPackInstallErrorCode = (typeof SKILL_PACK_INSTALL_ERROR_CODES)[number];
+/**
+ * Every way an install can be refused, as one type with a `code`.
+ *
+ * Code-based branching rather than a class per failure — the same idiom
+ * `@byok-sdk/core` uses — because a caller only ever needs two decisions from
+ * this: "was the channel unavailable" (retry later, or the deployment simply
+ * does not offer it) versus "was the content refused" (a publication problem
+ * nobody on this device can fix by retrying).
+ */
+export declare class SkillPackInstallError extends Error {
+    readonly code: SkillPackInstallErrorCode;
+    readonly packName: string | undefined;
+    constructor(code: SkillPackInstallErrorCode, message: string, options?: {
+        cause?: unknown;
+        packName?: string;
+    });
+}
+/** What a device recorded about one installed pack. Mirrors `lock.json` on disk. */
+export interface SkillPackLock {
+    readonly schema: typeof SKILL_PACK_LOCK_SCHEMA;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly content_hash: string;
+    /** The deployment the pack came from, normalized to its http(s) origin. Never a token, never a path. */
+    readonly source: string;
+    readonly installed_at: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly sha256: string;
+        readonly bytes: number;
+    }[];
+}
+export interface InstalledSkillPack {
+    readonly name: string;
+    readonly lock: SkillPackLock;
+    /** Absolute path of the content-addressed revision `lock.json` points at. */
+    readonly directory: string;
+}
+export interface InstallSkillPacksOptions {
+    /** The SDK data directory. A daemon passes its `storeDir`; the pack tree lives beside its other private state. */
+    readonly dataDir: string;
+    readonly serverUrl: string;
+    readonly auth: AuthManager;
+    /** The declaration read from `GET /byok/capabilities`. Never re-derived here, and never assumed. */
+    readonly declaration: CapabilityDeclaration;
+    readonly signal?: AbortSignal;
+}
+export interface SkillPackInstallResult {
+    readonly installed: readonly InstalledSkillPack[];
+    /** Packs already present at the same content hash. Re-installing is a no-op, not a rewrite. */
+    readonly unchanged: readonly string[];
+}
+/** The store root this module owns. */
+export declare function skillPacksRoot(dataDir: string): string;
+/**
+ * Fetches, verifies and installs every pack this deployment offers.
+ *
+ * @throws {SkillPackInstallError} `capability_unavailable` before any request
+ * is issued when the declaration does not name `skills.pack`.
+ */
+export declare function installSkillPacks(options: InstallSkillPacksOptions): Promise<SkillPackInstallResult>;
+/**
+ * Every pack this device has a valid lock for, sorted by name.
+ *
+ * Reads only the locks — never the pack bytes — so a caller listing what is
+ * installed pays nothing for packs it is not about to project.
+ */
+export declare function listInstalledSkillPacks(dataDir: string): Promise<readonly InstalledSkillPack[]>;
+export interface ProjectedSkillPack {
+    readonly name: string;
+    readonly contentHash: string;
+    readonly targetDir: string;
+    readonly files: readonly string[];
+}
+/**
+ * Copies an installed pack's files into a host-chosen directory.
+ *
+ * Copy, not symlink, and re-verified on the way out: the store is on the same
+ * machine as whatever else runs there, so the bytes are hashed again and
+ * compared against the lock before they are handed to a runtime. An install
+ * that was verified last week is not evidence about the file on disk today.
+ *
+ * @throws {SkillPackInstallError} `store_unsafe` for a missing pack, a symlink
+ * anywhere in the pack, or a file whose bytes no longer match the lock.
+ */
+export declare function projectSkillPack(dataDir: string, name: string, targetDir: string): Promise<ProjectedSkillPack>;

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

@@ -1,5 +1,6 @@
-import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload } from '@byok-sdk/protocol';
-import { type RuntimeAdapter } from '../types';
+import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type McpToolsetConfig, type RuntimeAdapter } from '../types';
+import { type RuntimeDisposalStage } from '../runtime-failure';
 import { type ApprovalDecision, type ApprovalOrigin, type ApprovalRegistry } from './approvals';
 import type { BlobResolver } from './blob-client';
 import type { TaskQueueWatermark } from './control-protocol';
@@ -101,6 +102,56 @@ export declare const MAX_TRACKED_TASK_IDS = 2000;
 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";
+/**
+ * additive-minor (`task.complete.document`): same stable-PREFIX contract as
+ * {@link MAX_DURATION_EXCEEDED_REASON_PREFIX} above, carried by every
+ * `task.fail` this daemon reports because a configured
+ * `DaemonConfig.resultDocument` extractor produced a document that could not
+ * be delivered — over the cap, not JSON-serializable, or destined for a
+ * server that never advertised the `result-document` capability. All three
+ * are `retryable: false`: none of them can come out differently on a retry
+ * against the same server with the same extractor. Everything after the
+ * prefix is human-readable detail (including the measured size), not part of
+ * the stable shape.
+ *
+ * There is deliberately no "send it anyway" or "send it truncated" path.
+ * A document is the task's PRIMARY structured result, so quietly dropping or
+ * mangling it would report success while destroying the thing the task
+ * existed to produce.
+ */
+export declare const RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX = "result document undeliverable";
+/**
+ * The task identity handed to a {@link ResultDocumentExtractor} alongside the
+ * final output text. Deliberately minimal — identity only, no session
+ * handle, no workspace path, no adapter: this seam exists to turn text the
+ * runtime already produced into the product's own JSON, not to become a
+ * general-purpose end-of-task callback with access to the daemon's innards.
+ */
+export interface ResultDocumentTask {
+    readonly taskId: string;
+    readonly sessionRef: string;
+}
+/**
+ * Host-supplied glue that turns a finished task's final output into the
+ * product's structured terminal result (`task.complete.document`). Returning
+ * `undefined` means "this task has no structured result" and completes the
+ * task exactly as it would have without an extractor configured at all.
+ *
+ * SYNCHRONOUS by contract, like every other single-purpose callback on
+ * `TaskRunnerDeps`, and the runtime ENFORCES that rather than trusting it:
+ * the returned value is treated as data and JSON-encoded as-is, never
+ * awaited, so a returned promise would encode to an empty document (`{}`) —
+ * a well-formed, under-cap, and completely WRONG result. A thenable return
+ * is therefore rejected exactly like a throw (`task.fail`, `retryable:
+ * false`), because delivering a confidently wrong terminal result is worse
+ * than delivering none.
+ *
+ * Throwing is a real outcome, not a nuisance: it fails the task
+ * (`retryable: false`) rather than completing it without the result the
+ * extractor was supposed to produce — see {@link
+ * RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}.
+ */
+export type ResultDocumentExtractor = (finalOutput: string, task: ResultDocumentTask) => unknown;
 /**
  * M5 batch-3 (workstream 2): default cap (64 MiB) on accumulated
  * (approximate) agent-event output bytes this daemon tolerates for a single
@@ -130,6 +181,8 @@ export interface TaskRunnerDeps {
     runtimeEnvironment?: Record<string, {
         allow?: string[];
     }>;
+    /** Validated, device-local registry keyed by wire-level logical toolset id. */
+    mcpToolsets?: ReadonlyMap<string, McpToolsetConfig>;
     permissionDefaults?: PermissionPolicy;
     workspaceRoot: string;
     deviceId: string;
@@ -153,13 +206,20 @@ export interface TaskRunnerDeps {
         observation?: GitWorkspaceObservation;
         errorCategory?: string;
     }) => void;
+    /** Local-only evidence that a semantic terminal outcome could not yet release its runtime ownership. */
+    onRuntimeDisposalFailure?: (event: {
+        taskId: string;
+        runtimeId: string;
+        stage: RuntimeDisposalStage;
+        reason: 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`.
+     * copied verbatim into every prepared operation's approval channel.
      */
     approvalRegistry: ApprovalRegistry;
     storeDir: string;
@@ -192,7 +252,7 @@ export interface TaskRunnerDeps {
      * 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. */
+    /** Overrides the bounded soft-interrupt window before authoritative `Session.close()` disposal begins. */
     shutdownInterruptTimeoutMs?: number;
     /**
      * M5 batch-3 (workstream 2): overrides {@link DEFAULT_MAX_TASK_OUTPUT_BYTES}
@@ -240,8 +300,22 @@ export interface TaskRunnerDeps {
      */
     admissionGuard?: (offer: {
         readonly taskId: string;
-        readonly payload: TaskOfferPayload;
+        readonly payload: AcceptedOfferPayload;
     }) => AdmissionGuardDecision;
+    /**
+     * additive-minor (`task.complete.document`): the host's structured-result
+     * extractor, consulted once per task at the moment `task.complete` is
+     * built — see {@link ResultDocumentExtractor} and `DaemonConfig
+     * .resultDocument` (`create-daemon.ts`) for the full contract.
+     *
+     * Optional, and absent by default: with no extractor supplied, the
+     * completion path is byte-identical to what it was before this seam
+     * existed — no document is computed, no capability is consulted, and
+     * `task.complete` carries exactly the fields it always did.
+     */
+    resultDocument?: {
+        readonly extract: ResultDocumentExtractor;
+    };
 }
 /** See {@link TaskRunnerDeps.admissionGuard}. */
 export type AdmissionGuardDecision = {
@@ -251,9 +325,10 @@ export type AdmissionGuardDecision = {
     readonly reason: string;
     readonly retryable: boolean;
 };
+type AcceptedOfferPayload = TaskOfferPayload | TaskOfferWithToolsetsPayload;
 /**
- * Per-connection task orchestration: offer -> (decline | claim -> adapter
- * session -> started) -> seq-ordered progress batches -> complete/fail/
+ * Per-connection task orchestration: offer -> (decline | prepare -> seal ->
+ * claim -> prepared operation -> 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,
@@ -273,13 +348,13 @@ export declare class TaskRunner {
      * 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
+     * prepared operation `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
+     * after the prepared operation 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,
@@ -305,12 +380,12 @@ export declare class TaskRunner {
      * 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
+     * block task A in prepared-operation `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
+     * the prepared operation 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
@@ -330,7 +405,7 @@ export declare class TaskRunner {
      * 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
+     * a no-op — never a second prepared-operation `start()` call, which would orphan the
      * first session.
      *
      * M3-B: unbounded otherwise — a long-lived daemon that's finished many
@@ -388,10 +463,9 @@ export declare class TaskRunner {
     /** 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
+     * Shutdown of every currently ACTIVE task for the control socket's
+     * `shutdown` RPC. Soft interrupt remains bounded, but each task's
+     * authoritative close receipt must settle successfully. 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
@@ -442,28 +516,13 @@ export declare class TaskRunner {
      * 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.
+     * After the bounded soft interrupt, `finish()` always awaits the authoritative
+     * `Session.close()` receipt. A failed receipt retains active/Git ownership;
+     * shutdown surfaces the rejection while resource enforcement leaves local
+     * evidence for a later retry.
      *
      * Re-checks task identity (`this.tasks.get(...) === active`) immediately
-     * before sending `task.fail`: the interrupt/hard-kill race above has await
+     * before sending `task.fail`: the interrupt 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.
@@ -508,6 +567,8 @@ export declare class TaskRunner {
     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;
+    /** Resolve every requested logical id locally and reject missing/colliding server authority before claim. */
+    private resolveMcpServers;
     private pump;
     /**
      * Protocol §7: an `artifact` `AgentEvent` only names a file the runtime
@@ -554,7 +615,7 @@ export declare class TaskRunner {
      *
      * `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
+     * how many `task.offer`s are simultaneously mid-prepared-operation 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
@@ -824,9 +885,66 @@ export declare class TaskRunner {
     /** Pre-claim, fail-closed rejection (protocol §3.2) — never claims first. */
     private decline;
     private fail;
+    /**
+     * additive-minor (`task.complete.document`): the whole daemon-side gate
+     * between a configured {@link ResultDocumentExtractor} and the wire —
+     * called once, from the `turn_end` completion path, immediately before
+     * `task.complete` is built.
+     *
+     * `{deliver: true}` means "go on and send `task.complete`", carrying the
+     * document when there is one. `{deliver: false}` means this method has
+     * ALREADY reported `task.fail` and finished the task; the caller must
+     * return without sending anything further.
+     *
+     * Four fail-closed branches, all `retryable: false` (see
+     * {@link RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX} for why none of them
+     * can succeed on a retry):
+     *
+     *   1. The extractor threw — its error is surfaced, never swallowed.
+     *   2. The extractor returned a thenable, violating the synchronous
+     *      contract in the one way that would otherwise ship a wrong answer.
+     *   3. The document is over the cap, not JSON-serializable, or not plain
+     *      JSON data, per `checkResultDocument` — the protocol's OWN check,
+     *      imported rather than reimplemented, so this gate and the server's
+     *      schema validation can never disagree about what is legal.
+     *   4. The connected server never advertised `result-document`. Its
+     *      tolerant `z.object()` would silently strip the field on arrival
+     *      (`version.ts`'s own flag doc comment), so "send anyway" is not a
+     *      degraded-but-working path — it is the task's primary structured
+     *      result being deleted in transit with nothing reported anywhere.
+     *
+     * The capability is checked LAST, deliberately: a document that is itself
+     * invalid is the host's own bug and is worth reporting as such even when
+     * the connected server could not have accepted any document at all. It is
+     * then re-checked once more by the caller after its own last await, since
+     * a reconnect can invalidate this answer in between (F3).
+     *
+     * **Residual window (bounded, deliberately not hacked around).** Even the
+     * caller's re-check happens before `ConnectionManager.send` hands the
+     * envelope to a transport, and a queued envelope can outlive the
+     * connection it was queued for: a reconnect between `send()` and the
+     * outbox actually draining could still deliver this `task.complete` to a
+     * rolled-back N-1 server that strips the document. Closing that would
+     * mean teaching the transport outbox to inspect payload semantics and
+     * mint a substitute `task.fail` for a task this runner already finished —
+     * a second authority over terminal outcomes living in the queue, which is
+     * worse than the window it closes. Documented instead, here and in
+     * docs/protocol.md §7.2.
+     */
+    private resolveResultDocument;
+    /**
+     * Whether the CURRENTLY connected server advertised `result-document` —
+     * read fresh on every call, never captured, because the answer changes
+     * across a reconnect (`ConnectionManager.getServerCapabilities` returns
+     * `[]` from the moment an acked connection closes until a fresh
+     * `conn.ack` repopulates it). An absent `getServerCapabilities` seam is
+     * "no capabilities", the fail-closed reading.
+     */
+    private hasResultDocumentCapability;
     private observeGit;
     private updateGitPhaseBestEffort;
     private finish;
+    private reserveSemanticTerminal;
     /** 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. */
@@ -860,3 +978,4 @@ export declare class TaskRunner {
      */
     private pickAdapter;
 }
+export {};