@byok-sdk/client 0.1.0

package/dist/daemon/observer.d.ts

@@ -0,0 +1,345 @@
+import { type AgentEvent, type BlobRef, type Envelope, type RuntimeInfo, type TaskState } from '@byok-sdk/protocol';
+import type { ConnectionState } from './ws-transport';
+/**
+ * M3-2a: local observability for the daemon — the seam a CLI (M3-2b) drives a
+ * live task feed, a task list, and approve/reject/unpair from, all LOCALLY
+ * against a running daemon (no SaaS-side polling required).
+ *
+ * Sourcing, without editing `task-runner.ts`: `TaskRunner` never calls
+ * anything in this file directly and has no notion it exists. Every
+ * task-lifecycle transition it makes is already observable from OUTSIDE the
+ * class through two seams `create-daemon.ts` itself owns and constructs:
+ *
+ * - `TaskRunnerDeps.send` (the callback `TaskRunner` calls for every
+ *   `task.claim` / `task.started` / `task.progress` / `task.artifact` /
+ *   `task.await_approval` / `task.complete` / `task.fail` / `task.decline` /
+ *   `task.cancelled` it ever emits) — `create-daemon.ts` already builds this
+ *   closure itself (`send: (envelope) => connection?.send(envelope)`); this
+ *   module just gets a chance to look at the same envelope before it goes
+ *   out. See `handleOutboundEnvelope`.
+ * - `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
+ *   `handleInboundEnvelope`.
+ *
+ * Neither seam required adding anything to `TaskRunnerDeps`/`TaskRunner`
+ * itself: both were already plain functions `create-daemon.ts` constructs,
+ * so wrapping them (call this module first, then the real behavior,
+ * unchanged) is the entire integration.
+ */
+/** Every local event kind this daemon can emit — see {@link DaemonEvent}. */
+export type DaemonEventKind = DaemonEvent['kind'];
+export type DaemonEvent = {
+    kind: 'offered';
+    ts: string;
+    taskId: string;
+    runtime?: string;
+} | {
+    kind: 'claimed';
+    ts: string;
+    taskId: string;
+    claimedRuntime?: string;
+} | {
+    kind: 'started';
+    ts: string;
+    taskId: string;
+}
+/** One per normalized `AgentEvent` (not one per `task.progress` batch) — matches "a live task feed" better than re-exposing the wire's own batching. */
+ | {
+    kind: 'progress';
+    ts: string;
+    taskId: string;
+    event: AgentEvent;
+} | {
+    kind: 'artifact';
+    ts: string;
+    taskId: string;
+    name: string;
+    contentType: string;
+    inline?: string;
+    blobRef?: BlobRef;
+}
+/**
+ * Finding F4: `approvalId` is populated whenever `TaskRunner` dispatched
+ * this approval THROUGH the normal `requestApproval`/`onApprovalDispatched`
+ * path (see `noteApprovalDispatched`) — `undefined` only for a
+ * hypothetical caller of `handleOutboundEnvelope` that never went through
+ * that hook (there is no other producer of `task.await_approval` today).
+ * This is the one piece of information an operator needs to actually
+ * call `approve`/`reject` (or the `approvals` CLI command) against this
+ * specific pending decision — before this fix, nothing surfaced it
+ * outside the control socket's `approvals.list`/`approvals.request`
+ * internals.
+ */
+ | {
+    kind: 'awaiting-approval';
+    ts: string;
+    taskId: string;
+    summary: string;
+    approvalId?: string;
+} | {
+    kind: 'completed';
+    ts: string;
+    taskId: string;
+    summary: string;
+    sessionRef: string;
+}
+/**
+ * Covers BOTH a post-claim `task.fail` and a pre-claim `task.decline` —
+ * `preClaim` distinguishes the two. This mirrors the protocol's own
+ * `Offered -> Failed` convention (docs/protocol.md "Declined vs. Failed";
+ * `TASK_TRANSITIONS`, `@byok-sdk/protocol`): a decline and a failure are the
+ * same outcome from a dispatcher's point of view, so this module doesn't
+ * invent a parallel `declined` kind the wire model itself doesn't have.
+ */
+ | {
+    kind: 'failed';
+    ts: string;
+    taskId: string;
+    reason: string;
+    retryable: boolean;
+    preClaim?: boolean;
+} | {
+    kind: 'cancelled';
+    ts: string;
+    taskId: string;
+    reason?: string;
+} | {
+    kind: 'connection';
+    ts: string;
+    state: ConnectionState;
+} | {
+    kind: 'paired';
+    ts: string;
+    deviceId: string;
+} | {
+    kind: 'unpaired';
+    ts: string;
+} | {
+    kind: 'runtimes-detected';
+    ts: string;
+    runtimes: RuntimeInfo[];
+}
+/** M4 Phase 2: the control socket's `shutdown` RPC was invoked — emitted once, before this daemon starts tearing itself down, so it lands in the audit log via the exact same subscribe->append plumbing every other event already uses (see `bin/commands/start.ts`). Informational only — do NOT gate any teardown decision on this event; see `shutdown-complete`. */
+ | {
+    kind: 'shutdown-requested';
+    ts: string;
+    reason: string;
+}
+/**
+ * M4 Phase 2: emitted once, AFTER the control-socket-driven shutdown
+ * sequence has fully finished — active tasks reported failed over the
+ * (at that point still-open) connection, then the connection/control
+ * socket actually closed (see `create-daemon.ts`'s `performControlShutdown`,
+ * which calls this last). This is the event `bin/commands/start.ts` must
+ * wait for before treating the daemon as done: reacting to
+ * `shutdown-requested` instead would race `daemon.stop()` against the
+ * still-in-flight `task.fail` send and silently drop it (confirmed via a
+ * real regression — see `daemon-control-socket.test.ts`).
+ *
+ * Finding F5(b): `undeliveredOutboxCount`, when defined, is the honest
+ * post-drain read of `ConnectionManager.outboxLength()` — 0 means the
+ * bounded outbox drain (see `ConnectionManager.stop`) genuinely finished
+ * before the connection closed; a positive number means that many
+ * envelopes (almost certainly including a `task.fail`
+ * `shutdownActiveTasks` just enqueued) never actually left the outbox.
+ * `undefined` only for a hypothetical caller of `noteShutdownComplete`
+ * that didn't pass one — `create-daemon.ts`'s own `performControlShutdown`
+ * (the only real producer of this event) always does.
+ */
+ | {
+    kind: 'shutdown-complete';
+    ts: string;
+    reason: string;
+    undeliveredOutboxCount?: number;
+}
+/**
+ * M4 Phase 3 hardening: a wire `task.approve`/`task.reject` (or this
+ * device's own redelivered copy of one) arrived for an out-of-band
+ * approval a DIFFERENT, faster path (a racing local `approvals.resolve`
+ * over the control socket, or this exact decision arriving twice) had
+ * already resolved — `TaskRunner.handleApprove`/`handleReject`
+ * (`task-runner.ts`) emit this instead of failing the task a second time.
+ * Audit-only: never gates any teardown/task-state decision, purely a
+ * record that a stale message was seen and correctly ignored — see
+ * `NoPendingApprovalError`'s own doc comment (`task-runner.ts`) for the
+ * full race this closes.
+ */
+ | {
+    kind: 'stale-approval-decision';
+    ts: string;
+    taskId: string;
+    decision: 'approve' | 'reject';
+    reason?: string;
+} | {
+    kind: 'git-workspace';
+    ts: string;
+    taskId: string;
+    workspaceId: string;
+    phase: string;
+    headChanged?: boolean;
+    commitsSinceBaseline?: number;
+    dirty?: {
+        staged: number;
+        unstaged: number;
+        untracked: number;
+        conflicted: number;
+    };
+    errorCategory?: string;
+};
+export type DaemonEventListener = (event: DaemonEvent) => void;
+export type Unsubscribe = () => void;
+/** `daemon.tasks()`'s per-task view — current local state + whatever summary/outcome was last reported for it. */
+export interface DaemonTaskInfo {
+    taskId: string;
+    state: TaskState;
+    runtime?: string;
+    /** Actual runtime selected for this task, as reported by the outbound `task.claim` payload. Distinct from `runtime`, which remains the requested offer runtime. */
+    claimedRuntime?: string;
+    /** Last known human-readable text for this task's current state: an await-approval summary, a complete summary, or a fail/cancel reason — whichever was most recently reported. */
+    summary?: string;
+    /** Only set once this task has actually reached `task.complete`. */
+    sessionRef?: string;
+    /** `true` only when `state === 'Failed'` resulted from a pre-claim `task.decline` rather than a post-claim `task.fail` — see the `DaemonEvent` `failed` variant's doc comment. */
+    declined?: boolean;
+    updatedAt: string;
+}
+/**
+ * M3-B parity (see `task-runner.ts`'s `MAX_TRACKED_TASK_IDS` doc comment,
+ * same rationale): this daemon is meant to run as a long-lived background
+ * service, so a per-task registry that only ever grows is a slow memory
+ * leak. Only TERMINAL entries (`Complete`/`Failed`/`Cancelled`) are ever
+ * evicted, oldest first — active entries are never removed here, the same
+ * way `TaskRunner.tasks` itself is bounded by real concurrency rather than
+ * an explicit cap.
+ */
+export declare const MAX_TRACKED_TASKS = 2000;
+/**
+ * Owns both halves of the local observability surface: the pub/sub
+ * (`subscribe`/`emit`) and the derived per-task registry (`tasks`). A plain
+ * `Set<listener>` with `subscribe` returning its own removal closure — not
+ * `node:events`' `EventEmitter` — keeps unsubscribe trivially leak-free
+ * (delete-by-reference, no string event names, no listener-count footguns)
+ * and keeps `DaemonEvent` a single typed union instead of a per-event-name
+ * overload table.
+ */
+export declare class DaemonObserver {
+    private readonly listeners;
+    private readonly taskInfo;
+    /**
+     * Finding F4: `approvalId` for a taskId's NEXT `task.await_approval`,
+     * stashed by `noteApprovalDispatched` and consumed (read + deleted) the
+     * moment `handleOutboundEnvelope`'s `task.await_approval` case actually
+     * emits the corresponding `awaiting-approval` event — see that hook's own
+     * doc comment for why this is always populated first (both calls happen
+     * synchronously, in that order, from `TaskRunner.dispatchApproval`).
+     * Read-and-delete keeps this self-bounding: an entry never outlives the
+     * one event it was stashed for, so this can never leak across a
+     * long-lived daemon's lifetime the way an evict-on-schedule cache would
+     * need explicit bookkeeping to avoid.
+     */
+    private readonly pendingApprovalIdByTask;
+    subscribe(listener: DaemonEventListener): Unsubscribe;
+    /** Current locally-known tasks, in first-seen order. */
+    tasks(): DaemonTaskInfo[];
+    /**
+     * Feed a raw INBOUND (server -> daemon) envelope. Deliberately narrow: only
+     * `task.offer` 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`
+     * resuming, `task.fail`, ...) — see `handleOutboundEnvelope`, which is
+     * where those are actually reported from.
+     */
+    handleInboundEnvelope(envelope: Envelope): void;
+    /**
+     * Feed a raw OUTBOUND (daemon -> server) envelope — this is where every
+     * task-lifecycle local event actually comes from: `TaskRunner` already
+     * calls `deps.send(...)` for each of these at exactly the moment its own
+     * state machine decides the transition happened.
+     */
+    handleOutboundEnvelope(envelope: Envelope): void;
+    noteConnectionState(state: ConnectionState): void;
+    notePaired(deviceId: string): void;
+    noteUnpaired(): void;
+    noteRuntimesDetected(runtimes: RuntimeInfo[]): void;
+    /** M4 Phase 2: see the `shutdown-requested` `DaemonEvent` variant's own doc comment. */
+    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;
+    /** 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: {
+        taskId: string;
+        workspaceId: string;
+        phase: string;
+        headChanged?: boolean;
+        commitsSinceBaseline?: number;
+        dirty?: {
+            staged: number;
+            unstaged: number;
+            untracked: number;
+            conflicted: number;
+        };
+        errorCategory?: string;
+    }): void;
+    /**
+     * Finding F4: wired from `TaskRunnerDeps.onApprovalDispatched`, called
+     * synchronously by `TaskRunner.dispatchApproval` BEFORE its own
+     * `deps.send(createEnvelope('task.await_approval', ...))` — stashes
+     * `approvalId` so `handleOutboundEnvelope`'s `task.await_approval` case
+     * (triggered by that very `send` call) can attach it to the
+     * `awaiting-approval` `DaemonEvent` it emits. Never emits anything
+     * itself — purely a handoff, same as `upsertTask`'s bookkeeping role for
+     * other events.
+     */
+    noteApprovalDispatched(taskId: string, approvalId: string): void;
+    private upsertTask;
+    /**
+     * Finding P2/#11 (observer half): the "no terminal entry to evict" branch
+     * used to just give up and leave the registry unbounded for as long as
+     * every tracked task stayed nonterminal (many concurrent/stuck offers that
+     * never reach Complete/Failed/Cancelled — the exact case this cap exists
+     * for, since a normal quickly-resolving workload always has terminal
+     * entries to evict well before this). Falling back to "never evict" here
+     * defeats the whole point of `MAX_TRACKED_TASKS`. Fix: fall back to
+     * evicting the OLDEST entry regardless of state (same insertion-order
+     * idiom as everywhere else this file/`task-runner.ts` bound a collection),
+     * logged since it's a real, if rare, observability loss — this registry is
+     * a local READ-MODEL only (see the module doc comment), never consulted by
+     * `TaskRunner`'s own state machine, so evicting a still-active task's
+     * entry here can't affect that task's actual execution — it only means
+     * `tasks()`/a CLI's task list can no longer show it until it reports
+     * another transition (which re-inserts it via `upsertTask`).
+     */
+    private evictIfNeeded;
+    /**
+     * Listener errors are caught here so a broken subscriber (e.g. a CLI's
+     * rendering bug) can never propagate back into the real send/onEnvelope
+     * path this module wraps — see this file's own module doc comment.
+     *
+     * Finding #6: `DaemonEventListener` is typed `(event: DaemonEvent) =>
+     * void`, but TypeScript's structural typing does not stop a caller from
+     * subscribing an `async` function (or anything else returning a promise)
+     * where a void-returning callback is expected — nothing here ever
+     * validates that at runtime. The `try`/`catch` below only ever catches a
+     * SYNCHRONOUS throw; an async listener doesn't throw synchronously, it
+     * RETURNS an already-rejected (or later-rejecting) promise, which sails
+     * straight past that catch. Left unhandled, that promise's rejection
+     * becomes an `unhandledRejection` on the process — which, depending on
+     * the host's Node version/flags, can crash the entire daemon over one
+     * subscriber's bug (e.g. a CLI's own progress renderer awaiting something
+     * that throws). Fix: treat the listener's return value as "possibly a
+     * promise" regardless of its declared type, and attach a `.catch` so a
+     * later rejection is caught and logged exactly like a synchronous throw,
+     * never left to become unhandled. This call stays synchronous itself
+     * (never `await`s a listener) — `emit` is invoked from the send/cursor
+     * path (`handleOutboundEnvelope`/`handleInboundEnvelope`, wired in
+     * directly from `create-daemon.ts`'s `send`/`onEnvelope` closures) and
+     * must never make a subscriber's own async work a precondition for
+     * cursor advancement or the next envelope being processed.
+     */
+    private emit;
+}

package/dist/daemon/operational-health.d.ts

@@ -0,0 +1,87 @@
+import { promises as fs } from 'node:fs';
+export type OperationalHealthState = 'healthy' | 'degraded' | 'recovering';
+export type OperationalFailureSource = 'reconnect' | 'upload' | 'maintenance' | 'lifecycle';
+export interface OperationalCrashRecord {
+    detectedAt: string;
+    previousRunStartedAt: string;
+}
+export declare const OPERATIONAL_HEALTH_FILENAME = "operational-health.json";
+export declare const MAX_OPERATIONAL_HEALTH_FILE_BYTES: number;
+export interface OpenOperationalHealthFile {
+    handle: Awaited<ReturnType<typeof fs.open>>;
+    stat: import('node:fs').BigIntStats;
+}
+/**
+ * Bind the pathname to a regular-file handle before any bytes are read.
+ * POSIX additionally gets O_NOFOLLOW/O_NONBLOCK. On Windows those flags are
+ * unavailable, so the pre-open lstat plus handle/path identity checks are the
+ * fail-closed authority: a static reparse point is rejected before open, and
+ * a raced replacement cannot match the already-observed inode/file state.
+ */
+export declare function openOperationalHealthFile(storeDir: string): Promise<OpenOperationalHealthFile | undefined>;
+export type OperationalHealthFileInspection = {
+    status: 'missing';
+} | {
+    status: 'valid';
+    sizeBytes: number;
+    state: OperationalHealthState;
+    failureCount: number;
+    crashCount: number;
+    currentRunStartedAt?: string;
+    lastCrashAt?: string;
+} | {
+    status: 'corrupt';
+    sizeBytes: number;
+    reason: string;
+} | {
+    status: 'unavailable';
+    sizeBytes?: number;
+    reason: string;
+};
+export type OperationalHealthSnapshot = {
+    availability: 'available';
+    state: OperationalHealthState;
+    failureCount: number;
+    windowMs: number;
+    failureThreshold: number;
+    crashCount: number;
+    lastCrashAt?: string;
+    currentRunStartedAt?: string;
+} | {
+    availability: 'unavailable';
+    reason: string;
+};
+export interface OperationalHealthOptions {
+    windowMs?: number;
+    failureThreshold?: number;
+    maxFailures?: number;
+    maxCrashes?: number;
+    clock?: () => Date;
+    runId?: () => string;
+    pid?: number;
+}
+export declare class OperationalHealthTracker {
+    #private;
+    constructor(storeDir: string, options?: OperationalHealthOptions);
+    startRun(): Promise<OperationalHealthSnapshot>;
+    recordFailure(source: OperationalFailureSource): Promise<void>;
+    recordSuccess(_source: OperationalFailureSource): Promise<void>;
+    markCleanStop(): Promise<void>;
+    snapshot(): OperationalHealthSnapshot;
+}
+/**
+ * Read-only S7-b inspection seam. Unlike `OperationalHealthTracker.startRun`,
+ * this never writes a run marker, prunes history, or repairs malformed bytes;
+ * doctor can therefore report on an offline daemon without changing the very
+ * evidence it is inspecting.
+ */
+declare function inspectOperationalHealthHandle(handle: Awaited<ReturnType<typeof fs.open>>, expected?: import('node:fs').BigIntStats): Promise<Exclude<OperationalHealthFileInspection, {
+    status: 'missing';
+}>>;
+/**
+ * Open a pathname-bound regular-file handle before inspecting. POSIX uses
+ * no-follow/non-blocking flags; Windows uses the pre-open and post-open
+ * pathname/handle identity checks in openOperationalHealthFile.
+ */
+export declare function inspectOperationalHealthFile(storeDir: string): Promise<OperationalHealthFileInspection>;
+export { inspectOperationalHealthHandle };

package/dist/daemon/policy.d.ts

@@ -0,0 +1,16 @@
+import type { PermissionPolicy } from '@byok-sdk/protocol';
+export interface PolicyDecision {
+    ok: boolean;
+    /** The merged, effective policy. Only meaningful when `ok` is true. */
+    policy: PermissionPolicy;
+    /** Present when `ok` is false. */
+    reason?: string;
+}
+/**
+ * Merge an offered task policy against the daemon operator's configured
+ * ceiling, fail-closed. This is a runtime-agnostic safety gate independent
+ * of whether the eventually-chosen adapter can even express the result — see
+ * each adapter's own permission mapping for that second, adapter-specific
+ * gate (e.g. `mapPermissionPolicyToPiArgs`).
+ */
+export declare function computeEffectivePolicy(offered: PermissionPolicy, ceiling: PermissionPolicy | undefined): PolicyDecision;

package/dist/daemon/progress-batcher.d.ts

@@ -0,0 +1,31 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+export type ProgressEmitter = (seq: number, events: AgentEvent[]) => void;
+export interface ProgressBatcherOptions {
+    /** Flush immediately once this many events are buffered. Default 10. */
+    maxBatchSize?: number;
+    /** Otherwise flush at most this often (ms) while events are pending. Default 250 (~4/sec). */
+    flushIntervalMs?: number;
+}
+/**
+ * Coalesces a task's `AgentEvent`s into seq-ordered `task.progress` batches:
+ * flush immediately at `maxBatchSize` events, otherwise at most every
+ * `flushIntervalMs` while anything is buffered. One instance per task —
+ * `seq` is a per-task monotonic counter starting at 1.
+ */
+export declare class ProgressBatcher {
+    private readonly emit;
+    private buffer;
+    private seq;
+    private timer;
+    private readonly maxBatchSize;
+    private readonly flushIntervalMs;
+    constructor(emit: ProgressEmitter, options?: ProgressBatcherOptions);
+    push(event: AgentEvent): void;
+    /** M4 Phase 4 (part B.3, observability): events buffered right now, not yet flushed as a `task.progress` batch — a cheap per-task queue-depth watermark for the daemon's control-socket `status` result (see `task-runner.ts`'s `getQueueWatermarks`). */
+    get pendingCount(): number;
+    flush(): void;
+    /** Stop the pending flush timer without flushing (used on teardown). */
+    stop(): void;
+    private ensureTimer;
+    private clearTimer;
+}

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

@@ -0,0 +1,36 @@
+import type { RuntimeCapabilities as ProtocolRuntimeCapabilities } from '@byok-sdk/protocol';
+import type { RuntimeCapabilities } from '../types';
+/**
+ * Maps a `RuntimeAdapter`'s own internal `capabilities()` result
+ * (`../types.ts`'s `RuntimeCapabilities` — `{steer, resume,
+ * approvalInteractive, permissionModes}`, always-required fields) onto the
+ * wire's `RuntimeCapabilities` shape (`@byok-sdk/protocol` — the same field names,
+ * but all-optional).
+ *
+ * Every field, `approvalInteractive` included, is a pure passthrough of the
+ * adapter's own self-report: the adapter is the single source of truth for
+ * what its runtime can do, and this function does no interpretation of its
+ * own. Previously `approvalInteractive` was hardcoded `false` at the sole
+ * caller, which had gone stale — as of M4 Phase 3 claude genuinely does
+ * support interactive approval, via `--permission-prompt-tool` routing
+ * `ClaudeSession.resolveApproval` into the local out-of-process MCP approval
+ * channel (`bin/byok-approval-mcp.ts`) under `policy.mode: 'confirm'` (see
+ * docs/protocol.md §5.1/§11.2) — so the wire advertised a capability claim no
+ * adapter owned. pi and codex report `false` for the same honest reason they
+ * always did: neither has any notion of pausing for approval
+ * (`resolveApproval()` throws unconditionally for both — see `../types.ts`'s
+ * `Session.resolveApproval` doc comment).
+ *
+ * This lives in its own module, rather than beside either of its two callers,
+ * because those two callers sit on opposite sides of an import edge:
+ * `create-daemon.ts` imports `task-runner.ts`, so exporting the mapper from
+ * `create-daemon.ts` would make `task-runner.ts` import back into it and close
+ * a cycle. A leaf module with no local imports beyond `../types` is the one
+ * place both can reach.
+ *
+ * The connection-level `interactive-approval` flag (`CAPABILITY_FLAGS`,
+ * `@byok-sdk/protocol`) is a separate, connection-scoped signal and is NOT derived
+ * from this: `create-daemon.ts`'s `computeCapabilities` keeps its own
+ * semantics.
+ */
+export declare function toRuntimeInfoCapabilities(caps: RuntimeCapabilities): ProtocolRuntimeCapabilities;

package/dist/daemon/session-workspace-store.d.ts

@@ -0,0 +1,75 @@
+/** What's recoverable for a given `sessionRef` — see the class doc comment. */
+export interface SessionWorkspaceRecord {
+    workspaceDir: string;
+    /**
+     * The underlying runtime's own resumable session identifier.
+     */
+    runtimeSessionId: string;
+    /** Additive workspace kind; missing legacy values remain plain. */
+    workspaceKind?: 'plain' | 'git';
+    /** Opaque private Git workspace ledger identifier. */
+    gitWorkspaceId?: string;
+}
+/**
+ * Persists `sessionRef -> {workspaceDir, runtimeSessionId}` across daemon
+ * restarts (finding #3 from the 2026-07-16 live GLM run): a `task.offer`
+ * carrying a `sessionRef` this device has previously reported (via a prior
+ * task's `task.complete.sessionRef`) reuses that exact workspace directory
+ * as the new task's cwd — which is what lets a runtime adapter's own resume
+ * mechanism (e.g. pi's `--session <id>`, scoped to the cwd/project a session
+ * was created under — see pi-adapter.ts) actually find the session again.
+ * An unknown or absent `sessionRef` is simply not in this map, and
+ * `task-runner.ts` treats that identically to "no sessionRef was ever
+ * offered" — fresh workspace, fresh session.
+ *
+ * One JSON file under `storeDir`, mirroring `DeviceStore`/`CursorStore`'s
+ * own persistence style: always read/write straight through to disk, no
+ * in-memory cache that could go stale or need invalidating across multiple
+ * `TaskRunner`/daemon instances sharing the same `storeDir` (exactly the
+ * "map persisted across daemon restart" requirement).
+ *
+ * Two correctness properties `task-runner.ts` depends on, neither of which
+ * a bare `fs.writeFile` + independent `fs.readFile` calls actually gives
+ * you:
+ *
+ * 1. **No torn reads.** `record()` is deliberately fire-and-forgotten from
+ *    `handleOffer` (see its call site) — it must never block `task.started`
+ *    on a disk write. But a bare `fs.writeFile` is not atomic: it truncates
+ *    the file before writing the new bytes, so a `get()` racing an
+ *    in-flight `record()` on another task's offer can `JSON.parse` a
+ *    half-written file, fail, and silently fall back to `{}` (see `load()`)
+ *    — resolving what should have been a resume to a fresh workspace.
+ *    `save()` below instead writes to a private temp file in the same
+ *    directory and `fs.rename`s it onto the real path, which POSIX
+ *    guarantees is atomic when both paths share a filesystem (true here —
+ *    same directory): any concurrent reader sees either the fully-old or
+ *    fully-new bytes, never a partial write.
+ * 2. **No lost updates.** Two `record()` calls for two different
+ *    `sessionRef`s that overlap (both `load()` the same on-disk snapshot,
+ *    each mutate their own key into their own in-memory copy, then `save()`
+ *    back to back) would otherwise let the second `save()` overwrite the
+ *    first's key with a snapshot that never saw it — each individual
+ *    `save()` being atomic does not prevent this. `enqueue()` below chains
+ *    every `get()`/`record()` through one serial promise queue per
+ *    instance, so no two load-modify-save cycles (or a read and a
+ *    concurrent write) ever interleave.
+ */
+export declare class SessionWorkspaceStore {
+    private readonly filePath;
+    /**
+     * Serial "mutex" queue: every `get()`/`record()` chains its work off this
+     * promise and replaces it, so operations on this instance always run
+     * one-at-a-time, in call order — never interleaved. The queue's own tail
+     * is never allowed to reject (a failed task must not wedge every
+     * subsequent caller behind a rejected promise); the failure still
+     * propagates to that call's own caller via the returned promise.
+     */
+    private queue;
+    constructor(storeDir: string);
+    get(sessionRef: string): Promise<SessionWorkspaceRecord | undefined>;
+    record(sessionRef: string, entry: SessionWorkspaceRecord): Promise<void>;
+    /** See the class doc comment's "no lost updates" property. */
+    private enqueue;
+    private load;
+    private save;
+}

package/dist/daemon/store.d.ts

@@ -0,0 +1,54 @@
+import { type EnsureSecureDirOptions } from '../util/secure-dir';
+export interface DeviceRecord {
+    deviceId: string;
+    /** Current access token (JWT), renewed via challenge/token without re-pairing (protocol §6.2). */
+    accessToken: string;
+    /** ISO-8601 expiry for `accessToken` (our best knowledge of it — see auth-manager.ts for how this is derived after `/byok/pair`, which reports no explicit expiry itself). */
+    expiresAt: string;
+    /** Ed25519 private key, PKCS8 PEM. Never leaves this device. Stored as a 0600 file; OS keychain integration is deferred (tracked as a future roadmap item, not promised for any specific milestone). */
+    devicePrivateKeyPem: string;
+    /** Ed25519 public key, base64url — re-sent verbatim on a post-revocation re-pair (protocol §6.3). */
+    devicePublicKey: string;
+}
+/**
+ * Persists the device identity issued by `pair()` — deviceId, current
+ * access token + its expiry, and the device's own Ed25519 keypair. This is
+ * the ONLY credential material the daemon itself ever holds — never a
+ * runtime's own credentials (see the credential-isolation rule on
+ * `RuntimeAdapter`). Stored 0600 under `storeDir` (default
+ * `~/.byok/<productId>/`); OS keychain storage is deferred (tracked as a
+ * future roadmap item, not promised for any specific milestone).
+ */
+export declare class DeviceStore {
+    private readonly secureDirOptions?;
+    private readonly filePath;
+    /**
+     * `secureDirOptions` is a test-only DI seam (mirrors `EnsureSecureDirOptions`'s
+     * own `run`/`platform` overrides) — every real caller omits it, getting
+     * real `ensureSecureDir(storeDir)` behavior unchanged. It exists so
+     * finding R4's fail-closed contract ("on win32, an `icacls` failure makes
+     * `save()` — and thus `AuthManager.pair()` — reject with a clear typed
+     * `SecureDirHardeningError` instead of silently persisting an
+     * ACL-unprotected credential") is verifiable from a real `darwin`/`linux`
+     * CI/dev machine, not just asserted.
+     */
+    constructor(storeDir: string, secureDirOptions?: EnsureSecureDirOptions | undefined);
+    static defaultDir(productId: string): string;
+    /**
+     * Resolve the one store pathname every daemon/CLI component must share.
+     * A configured relative path is anchored once at process entry rather than
+     * being reinterpreted after a diagnostics operation temporarily changes
+     * cwd to pin a quarantine directory inode.
+     */
+    static resolveDir(productId: string, configured?: string): string;
+    load(): Promise<DeviceRecord | undefined>;
+    /**
+     * Read and remove the exact bounded, no-follow device record under the
+     * caller's mutation lease. The hard-link guard keeps the inspected inode
+     * identifiable until the synchronous pathname check and unlink complete.
+     */
+    remove(): Promise<DeviceRecord | undefined>;
+    save(record: DeviceRecord): Promise<void>;
+    clear(): Promise<void>;
+    private openBounded;
+}