@byok-sdk/client 0.1.0

package/dist/bin/commands/approvals.d.ts

@@ -0,0 +1,31 @@
+import { connectControlClient } from '../control-client';
+export interface ApprovalsListDeps {
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+    /** DI for tests: substitute the real control-socket connection attempt. */
+    connectControl?: typeof connectControlClient;
+    /** DI for tests: pin "now" for deterministic age rendering — see `formatApprovalsListLines`. */
+    now?: () => number;
+}
+/**
+ * Finding F4 (cross-model adversarial review): `byok-agent approvals` —
+ * before this command existed, an operator had no way to ever learn a
+ * pending approval's `approvalId` short of reading raw `audit.jsonl`
+ * entries by hand (and even that only worked if the daemon happened to
+ * surface one there at all): `approve`/`reject` both *require* an
+ * `approvalId`, but nothing in this CLI ever printed one.
+ *
+ * Lists the control socket's `approvals.list` result — the exact same
+ * `ApprovalRegistry` entries `approve`/`reject` resolve against
+ * (`create-daemon.ts`'s method registry, backed by `daemon/approvals.ts`) —
+ * as one line per pending approval: `approvalId`, `taskId`, `age`, and a
+ * (possibly truncated — see `formatApprovalsListLines`) summary excerpt.
+ *
+ * No persisted-state fallback, mirroring `approve`/`reject`
+ * (`commands/approve-reject.ts`): a pending approval only ever means
+ * anything against a LIVE daemon, so daemon-unreachable is reported as a
+ * clear, specific error (and this command exits non-zero) rather than a
+ * silent "no approvals" — those are different outcomes and a script
+ * parsing this output needs to be able to tell them apart.
+ */
+export declare function runApprovalsCommand(storeDir: string, productId: string, deps?: ApprovalsListDeps): Promise<void>;

package/dist/bin/commands/approve-reject.d.ts

@@ -0,0 +1,29 @@
+import { connectControlClient } from '../control-client';
+export interface ApproveRejectDeps {
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+    /** DI for tests: substitute the real control-socket connection attempt. */
+    connectControl?: typeof connectControlClient;
+}
+/**
+ * M4 Phase 2: `approve`/`reject` now genuinely work from a separate,
+ * short-lived CLI invocation — they call the control socket's
+ * `approvals.resolve` method (`create-daemon.ts`'s method registry, backed
+ * by `daemon/approvals.ts`'s `ApprovalRegistry`) rather than requiring a
+ * `Daemon` this same process just started (which never worked at all: see
+ * git history for the pre-M4 version of this module, which called
+ * `daemon.approve`/`daemon.reject` directly and always failed with
+ * "daemon is not started" for exactly that reason — `byok-agent.ts` used to
+ * not even dispatch to these commands as a result).
+ *
+ * Still honest about what these can resolve TODAY: no bundled runtime
+ * adapter (pi/claude/codex) raises an approval yet (see `create-daemon.ts`'s
+ * `toRuntimeInfoCapabilities` doc comment), so nothing ever calls
+ * `ApprovalRegistry.register()` in this SDK version — every `approve`/
+ * `reject` against a real daemon today resolves to the registry's own
+ * `not_found` error, UNLESS the daemon isn't reachable at all, in which case
+ * that's reported first. Both failure modes are reported with a clear,
+ * specific message rather than a generic "not started" one.
+ */
+export declare function runApproveCommand(storeDir: string, productId: string, approvalId: string, deps?: ApproveRejectDeps): Promise<void>;
+export declare function runRejectCommand(storeDir: string, productId: string, approvalId: string, reason: string | undefined, deps?: ApproveRejectDeps): Promise<void>;

package/dist/bin/commands/doctor.d.ts

@@ -0,0 +1,15 @@
+import type { DaemonConfig } from '../../index';
+import { type CollectDiagnosticsOptions } from '../../diagnostics/diagnostics';
+export interface DoctorOptions extends CollectDiagnosticsOptions {
+    json?: boolean;
+    fix?: boolean;
+    confirmed?: boolean;
+    log?: (line: string) => void;
+}
+export declare class DoctorConfirmationRequiredError extends Error {
+    constructor();
+}
+export declare class DoctorDaemonRunningError extends Error {
+    constructor();
+}
+export declare function runDoctorCommand(config: DaemonConfig, options?: DoctorOptions): Promise<void>;

package/dist/bin/commands/pair.d.ts

@@ -0,0 +1,7 @@
+import { type Daemon, type DaemonConfig } from '../../index';
+export interface PairDeps {
+    log?: (line: string) => void;
+    /** DI for tests: skip constructing a real `createDaemon(config)` and drive a stub/pre-built instance instead. */
+    daemon?: Pick<Daemon, 'pair'>;
+}
+export declare function runPairCommand(config: DaemonConfig, code: string, deps?: PairDeps): Promise<void>;

package/dist/bin/commands/runtimes.d.ts

@@ -0,0 +1,7 @@
+import { type DaemonConfig, type RuntimeAdapter } from '../../index';
+export interface RuntimesDeps {
+    log?: (line: string) => void;
+    /** DI for tests: probe these adapters instead of constructing the real bundled pi/claude/codex set. */
+    adapters?: RuntimeAdapter[];
+}
+export declare function runRuntimesCommand(config: DaemonConfig, deps?: RuntimesDeps): Promise<void>;

package/dist/bin/commands/service.d.ts

@@ -0,0 +1,54 @@
+import { type DaemonConfig, type ServiceDefinition, type ServiceLifecycle } from '../../index';
+export interface ServiceCommandDeps {
+    log?: (line: string) => void;
+    /** DI for tests: drive a pre-built lifecycle instead of the real platform-dispatched `createServiceLifecycle`. */
+    lifecycle?: ServiceLifecycle;
+}
+/**
+ * Builds the SAME `ServiceDefinition` every one of `install`/`uninstall`/
+ * `service-start`/`service-stop`/`service-status` derives — critical so
+ * `uninstall`/`service-stop`/`service-status` compute the exact same
+ * service name (and, on Windows, install directory) `install` used,
+ * without requiring the operator to re-supply identical ad hoc flags to
+ * five separate invocations. `--name`/`--agent-bin`/`--node-bin`/
+ * `--winsw-bin`/`--winsw-install-dir` are override escape hatches; every
+ * default is derived deterministically from `config` alone (mirrors
+ * `bin/config.ts`'s own doc comment: every subcommand loads config the same
+ * way).
+ *
+ * `agentBin` defaults to `process.argv[1]` — the actual script path Node is
+ * currently running, always correct regardless of how this CLI was
+ * invoked (global install, `npx`, a product's own `node_modules/.bin`
+ * symlink) — NOT an `import.meta`-based guess; see
+ * `lifecycle/create-service-lifecycle.ts`'s doc comment for why this
+ * module family never tries to resolve that path itself. A product
+ * shipping a single compiled binary (`templates/packaging/`) instead of
+ * `node + byok-agent.js` should pass `--agent-bin`/`--node-bin` explicitly,
+ * or construct a `ServiceDefinition` directly via `createServiceLifecycle`
+ * rather than this convenience CLI subcommand.
+ *
+ * `configPath` is resolved to an ABSOLUTE path before being baked into the
+ * generated service's `--config <path>` argument: a service launched by
+ * launchd/systemd/WinSW starts with the OS service manager's OWN minimal
+ * environment and working directory, not the operator's interactive shell
+ * — a relative path here would resolve against whatever cwd the service
+ * manager happens to choose, not where the operator ran `install` from.
+ */
+export declare function buildServiceDefinition(config: DaemonConfig, configPath: string, rest: string[]): ServiceDefinition;
+/**
+ * Generates the platform service definition (plist/unit/WinSW xml),
+ * registers it with the OS service manager, and starts it — see
+ * `lifecycle/create-service-lifecycle.ts` for the per-platform mechanics.
+ * On Windows, `--winsw-bin <path>` is required (the product-bundled WinSW
+ * executable — Decision-6: this SDK never bundles/downloads it itself; see
+ * `templates/service/winsw/README.md`).
+ */
+export declare function runInstallCommand(config: DaemonConfig, configPath: string, rest: string[], deps?: ServiceCommandDeps): Promise<void>;
+/** Stops (if running) and fully removes the service registration + generated definition file. Safe to call when not installed. */
+export declare function runUninstallCommand(config: DaemonConfig, configPath: string, rest: string[], deps?: ServiceCommandDeps): Promise<void>;
+/** Starts an already-installed service (named so it never collides with the existing `start`, which runs the daemon in the foreground — see `byok-agent.ts`'s header comment). */
+export declare function runServiceStartCommand(config: DaemonConfig, configPath: string, rest: string[], deps?: ServiceCommandDeps): Promise<void>;
+/** Stops a running service without uninstalling it. */
+export declare function runServiceStopCommand(config: DaemonConfig, configPath: string, rest: string[], deps?: ServiceCommandDeps): Promise<void>;
+/** Reports installed/running state straight from the platform's own service manager. */
+export declare function runServiceStatusCommand(config: DaemonConfig, configPath: string, rest: string[], deps?: ServiceCommandDeps): Promise<void>;

package/dist/bin/commands/start.d.ts

@@ -0,0 +1,21 @@
+import { type Daemon, type DaemonConfig } from '../../index';
+export interface StartDeps {
+    log?: (line: string) => void;
+    error?: (line: string) => void;
+    /** DI for tests: drive a pre-built (e.g. stub-adapter-backed) `Daemon` instead of the real `createDaemon(config)`. */
+    daemon?: Daemon;
+    /** Test hook: fires once `daemon.start()` has resolved and the banner line has been logged — lets a test abort deterministically instead of racing real timing. Unused by the real CLI entry. */
+    onReady?: () => void;
+    /** Required: there is no sane default "never stop" signal. The real CLI entry (`byok-agent.ts`) wires this to SIGINT/SIGTERM; tests wire their own `AbortController`. */
+    signal: AbortSignal;
+}
+/**
+ * Runs the daemon in the foreground until `deps.signal` aborts. Every
+ * `DaemonEvent` it observes is (a) appended to `<storeDir>/audit.jsonl` —
+ * the only channel a separate `status`/`tasks`/`runtimes` invocation has
+ * into this process' state, see `byok-agent.ts`'s header comment — and (b)
+ * printed as one line to stdout via the SAME formatter `tasks --follow`
+ * uses when tailing that log, so watching `start`'s own stdout and tailing
+ * the audit log show identical text.
+ */
+export declare function runStartCommand(config: DaemonConfig, deps: StartDeps): Promise<void>;

package/dist/bin/commands/status.d.ts

@@ -0,0 +1,25 @@
+import { type DaemonConfig, type RuntimeAdapter } from '../../index';
+import { connectControlClient } from '../control-client';
+export interface StatusDeps {
+    log?: (line: string) => void;
+    /** DI for tests: probe these adapters instead of constructing the real bundled pi/claude/codex set. */
+    adapters?: RuntimeAdapter[];
+    /** DI for tests: substitute the real control-socket connection attempt. */
+    connectControl?: typeof connectControlClient;
+}
+/**
+ * `paired`/`deviceId` are read straight off `DeviceStore` on disk (NOT via
+ * a freshly-constructed `Daemon.status()`) — a `Daemon` this process just
+ * constructed has never called `start()`/`pair()`, so its in-memory
+ * `AuthManager` never loaded the on-disk record and would always report
+ * `paired: false` even for a device that's genuinely paired. See
+ * `byok-agent.ts`'s header comment for the full read-model rationale.
+ *
+ * M4 Phase 2: after the persisted-state view above, this ALSO tries the
+ * control socket (see `control-client.ts`) — if a `byok-agent start` (or
+ * the installed service) is actually running right now, its live pid/
+ * uptime/transport/active-tasks are appended, clearly marked `live-`; if
+ * not reachable, one line says so and the persisted view above stands on
+ * its own, exactly as before this feature existed.
+ */
+export declare function runStatusCommand(config: DaemonConfig, deps?: StatusDeps): Promise<void>;

package/dist/bin/commands/support-bundle.d.ts

@@ -0,0 +1,7 @@
+import type { DaemonConfig } from '../../index';
+import type { CollectDiagnosticsOptions } from '../../diagnostics/diagnostics';
+export interface SupportBundleOptions extends CollectDiagnosticsOptions {
+    outputPath: string;
+    log?: (line: string) => void;
+}
+export declare function runSupportBundleCommand(config: DaemonConfig, options: SupportBundleOptions): Promise<void>;

package/dist/bin/commands/tasks.d.ts

@@ -0,0 +1,27 @@
+import { type DaemonConfig } from '../../index';
+import { connectControlClient } from '../control-client';
+export interface TasksListDeps {
+    log?: (line: string) => void;
+}
+/** `byok-agent tasks` (no `--follow`): current known tasks, reconstructed from the audit log — see `byok-agent.ts`'s header comment. */
+export declare function runTasksListCommand(config: DaemonConfig, deps?: TasksListDeps): Promise<void>;
+export interface TasksFollowDeps {
+    log?: (line: string) => void;
+    /** Required — see `commands/start.ts`'s identical `StartDeps.signal` doc comment for why there's no sane default. */
+    signal: AbortSignal;
+    pollIntervalMs?: number;
+    /** DI for tests: substitute the real control-socket connection attempt. */
+    connectControl?: typeof connectControlClient;
+}
+/**
+ * `byok-agent tasks --follow`: M4 Phase 2 — prefers a LIVE stream over the
+ * control socket's `tasks.subscribe` method (see `control-client.ts`),
+ * which taps the exact same `DaemonObserver` events `start`'s own stdout
+ * already shows, full fidelity, as they happen. Falls back to tailing the
+ * SAME `audit.jsonl` a running `start` appends to (like `tail -f`, not a
+ * full replay — run plain `byok-agent tasks` first for history) whenever
+ * the control socket isn't reachable (daemon not running, or an older
+ * daemon build with no control socket at all) — see `byok-agent.ts`'s
+ * header comment for the historical rationale this fallback preserves.
+ */
+export declare function runTasksFollowCommand(config: DaemonConfig, deps: TasksFollowDeps): Promise<void>;

package/dist/bin/commands/unpair.d.ts

@@ -0,0 +1,124 @@
+import type { Daemon, ServiceLifecycle } from '../../index';
+import { connectControlClient, isControlDaemonGone } from '../control-client';
+/** Thrown when `unpair` didn't get a `--yes`/confirmed and either declined interactively or has no TTY to prompt on. Caught by `byok-agent.ts`'s top-level handler like any other error (clean message, exit 1) — never left to hang. */
+export declare class UnpairNotConfirmedError extends Error {
+    constructor();
+}
+/**
+ * Finding P1 #2: thrown instead of clearing the store when the OS
+ * background service (`byok-agent install`) is currently installed AND
+ * running — see this file's own module doc comment for the full "why".
+ * Unconditional: unlike {@link UnpairUnknownDaemonStateError}, `--force`
+ * never bypasses this one — it exists for a KNOWN-unsafe state, not an
+ * uncertain one.
+ */
+export declare class UnpairBlockedByRunningServiceError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Finding P1 #2 (residual, now fixed across two rounds): thrown instead of
+ * clearing the store when unpair could NOT positively confirm that no
+ * background service/daemon is running. Three shapes all collapse to
+ * "unknown", unsafe BY DEFAULT — exactly like a confirmed-running service —
+ * unless the caller opts in via `--force`:
+ *
+ * - Round 1: a `deps.lifecycle` that could not even be constructed
+ *   (unsupported platform, win32 without `--winsw-bin`, or no config to
+ *   build one from at all).
+ * - Round 1: a `status()` call that itself rejected (the query to the
+ *   platform's service manager failed outright).
+ * - Round 3: a `status()` call that RESOLVED but reported
+ *   `determinate: false` — the manager query itself could not be answered
+ *   (no reachable systemd `--user` D-Bus session, no launchd GUI domain for
+ *   this uid, permission denied), so `running: false` in that response is a
+ *   fallback, not a confirmed fact; see `lifecycle/service-types.ts`'s
+ *   `ServiceStatusResult.determinate`. Every one of `systemd.ts`/
+ *   `launchd.ts`/`winsw.ts` used to collapse exactly this case into a plain
+ *   `running: false`, which this file's `checkServiceState` then trusted at
+ *   face value — reopening the identical fail-open gap round 1 fixed for
+ *   the other two shapes.
+ *
+ * Bypassable by `--force`, deliberately unlike
+ * {@link UnpairBlockedByRunningServiceError}: this error means "can't
+ * tell", not "confirmed unsafe".
+ */
+export declare class UnpairUnknownDaemonStateError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Finding F6 (cross-model adversarial review): thrown instead of clearing
+ * the store on the LIVE (control-socket) unpair path when the daemon's
+ * actual exit could NOT be confirmed — the shutdown RPC request itself
+ * failed/never got through, teardown hung past `waitForControlExit`'s
+ * deadline, or the exit-poll otherwise never observed `isControlDaemonGone`
+ * before timing out. All three collapse to the same observable signal
+ * (`exited === false`): a daemon that never actually received/finished the
+ * shutdown is presumably STILL RUNNING, with its `AuthManager`'s proactive
+ * renewal timer ready to write a fresh `device.json` right back over
+ * whatever `unpair()` is about to clear — clearing anyway (the pre-fix
+ * behavior) meant the log line had to openly admit "did not confirm exit...
+ * local device identity has still been cleared" as if that were routine,
+ * when it is exactly the silently-self-reverting hazard finding P1 #2
+ * originally set out to close. Bypassable via `--force`, same shape as
+ * {@link UnpairUnknownDaemonStateError} — this means "can't confirm it
+ * actually stopped", an explicit, logged-as-unsafe override, never a
+ * silent default.
+ */
+export declare class UnpairExitUnconfirmedError extends Error {
+    constructor();
+}
+export interface UnpairDeps {
+    log?: (line: string) => void;
+    /** `--yes`: skip the confirmation prompt entirely. */
+    confirmed?: boolean;
+    /** Defaults to `process.stdin.isTTY` — overridable so a test never depends on the real test-runner's stdin. */
+    isTTY?: boolean;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    /**
+     * Finding P1 #2: an already-constructed lifecycle for the OS background
+     * service this product MIGHT be installed as — `byok-agent.ts`'s `unpair`
+     * dispatch builds this the same way `bin/commands/service.ts` does
+     * (`buildServiceDefinition` + `createServiceLifecycle`) and passes it
+     * through. `undefined` means "could not even check" (unsupported
+     * platform, or Windows without `--winsw-bin`) — this is NOT the same as
+     * "confirmed not running": see {@link UnpairUnknownDaemonStateError} and
+     * the module doc comment for what that residual gap means and why it's
+     * refused by default (bypassable only via `--force`).
+     */
+    lifecycle?: Pick<ServiceLifecycle, 'status'>;
+    /**
+     * Finding P1 #2 (residual): explicit opt-in to proceed when the service
+     * check could NOT positively confirm "not running" (lifecycle
+     * unavailable, or its `status()` call itself failed) — see
+     * {@link UnpairUnknownDaemonStateError}. Does NOT bypass a lifecycle that
+     * actively confirmed the service IS running
+     * ({@link UnpairBlockedByRunningServiceError} is unconditional either
+     * way) — `--force` overrides uncertainty, never a known-unsafe result.
+     *
+     * Finding F6: this SAME flag also overrides the LIVE (control-socket)
+     * path's own exit-confirmation gate — see
+     * {@link UnpairExitUnconfirmedError}. One flag, two independent unsafe
+     * overrides (whichever path this invocation actually took), each logged
+     * as an explicit WARNING rather than silently accepted.
+     */
+    force?: boolean;
+    /**
+     * M4 Phase 2: `storeDir`/`productId` to attempt a LIVE control-socket
+     * unpair before ever falling back to the service-state-based flow below
+     * — see this file's own module doc comment. Omitting either (e.g. an
+     * older test exercising only the fallback path) skips straight to that
+     * flow, exactly as before this feature existed.
+     */
+    storeDir?: string;
+    productId?: string;
+    /** DI for tests: substitute the real control-socket connection attempt. */
+    connectControl?: typeof connectControlClient;
+    /** DI for tests: substitute the real "has the daemon actually exited" probe. */
+    isControlDaemonGone?: typeof isControlDaemonGone;
+    /** How long to wait for the daemon to actually exit after `shutdown` is sent, before giving up (the store is still cleared either way — see the live-path log message). Default 15000ms. */
+    controlExitTimeoutMs?: number;
+    /** Poll interval while waiting for exit. Default 300ms. */
+    controlExitPollIntervalMs?: number;
+}
+export declare function runUnpairCommand(daemon: Pick<Daemon, 'unpair'>, deps?: UnpairDeps): Promise<void>;

package/dist/bin/commands/workspaces.d.ts

@@ -0,0 +1,16 @@
+import type { DaemonConfig } from '../../index';
+import { GitWorkspaceStore, type GitWorkspaceLedgerRecord } from '../../daemon/git-workspace-store';
+export interface WorkspacesCommandDeps {
+    log?: (line: string) => void;
+    store?: Pick<GitWorkspaceStore, 'list'>;
+    showPaths?: boolean;
+}
+declare function abbreviateCommit(value: string | undefined): string;
+declare function formatWorkspaceLine(record: GitWorkspaceLedgerRecord, showPaths: boolean): string;
+/**
+ * Lists the private Git workspace ledger without probing or changing any
+ * workspace. The ledger store already defines missing, corrupt, and future
+ * version behavior; this command deliberately preserves those outcomes.
+ */
+export declare function runWorkspacesCommand(config: DaemonConfig, deps?: WorkspacesCommandDeps): Promise<void>;
+export { abbreviateCommit, formatWorkspaceLine };

package/dist/bin/config.d.ts

@@ -0,0 +1,41 @@
+import type { DaemonConfig } from '../daemon/create-daemon';
+/**
+ * Thrown by {@link loadConfig} on a missing/unreadable/invalid config.
+ * Never calls `process.exit` itself (unlike the pre-M3-2b bin, which did) —
+ * every caller, including tests, controls its own exit behavior; only
+ * `byok-agent.ts`'s top-level `main().catch(...)` turns this into a clean
+ * stderr message + `exit(1)`.
+ */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads a `DaemonConfig` from a JSON file, if given, merged with explicit
+ * overrides (e.g. `pair`'s `--server`). Every subcommand in this bin —
+ * including the read-only ones (`status`/`runtimes`/`tasks`) — loads
+ * config the same way: they all need `productId`/`storeDir`/`branding`/
+ * `runtimeAllowlist` from the same one product install, so there is only
+ * ever one config shape to reason about.
+ */
+export declare function loadConfig(configPath: string | undefined, overrides?: Partial<DaemonConfig>): DaemonConfig;
+/**
+ * Same `storeDir` resolution `create-daemon.ts` uses internally
+ * (`config.storeDir ?? DeviceStore.defaultDir(config.productId)`) — reused
+ * here via `DeviceStore`'s own static helper (not reimplemented) so a query
+ * subcommand always looks in the exact same place `createDaemon`/
+ * `createDaemonWithAdapters` would persist to.
+ */
+export declare function resolveStoreDir(config: Pick<DaemonConfig, 'storeDir' | 'productId'>): string;
+/** Value following `flag` in `args` (e.g. `--config <path>`), or `undefined`. */
+export declare function argValue(args: string[], flag: string): string | undefined;
+/** Whether a bare boolean flag (e.g. `--follow`, `--yes`) is present anywhere in `args`. */
+export declare function hasFlag(args: string[], flag: string): boolean;
+/**
+ * Positional (non-flag) arguments, in order, with a fixed set of known
+ * `--flag <value>` pairs removed (flag AND its value). Bare boolean flags
+ * (e.g. `--follow`/`--yes`) are handled separately via {@link hasFlag} and
+ * don't need to be named here unless they'd otherwise be mistaken for a
+ * positional. Order-independent: `pair CODE --server URL` and
+ * `pair --server URL CODE` both yield `["CODE"]`.
+ */
+export declare function positionalArgs(args: string[], valueFlags?: string[]): string[];

package/dist/bin/control-client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * M4 Phase 2: the CLI-side half of the control socket — connects, performs
+ * the mutual HMAC handshake (`../daemon/control-protocol.ts`), and exposes a
+ * small `request()`/`subscribe()` surface every rewired command
+ * (`status`/`tasks --follow`/`unpair`/`approve`/`reject`) builds on.
+ *
+ * `connectControlClient` never throws for the ordinary "daemon isn't
+ * running" case — it returns a typed `{ok:false, reason}` result instead
+ * (see {@link ConnectControlResult}), so a caller can render a clean
+ * fallback message rather than catching an exception. Missing
+ * `control.token` (the daemon was never started, or was stopped) is by far
+ * the most common reason; any other connect/handshake failure collapses
+ * into the same shape — a CLI user doesn't need to know WHY the control
+ * socket isn't reachable, only that it isn't and a fallback is being used.
+ */
+export interface ControlClientOptions {
+    storeDir: string;
+    productId: string;
+    /** Default: `HANDSHAKE_TIMEOUT_MS` (3000ms) — matches the server's own handshake timeout. */
+    handshakeTimeoutMs?: number;
+    /** Default 10000ms — applied per `request()` call; never applied to `subscribe()`, which is expected to stay open indefinitely. */
+    requestTimeoutMs?: number;
+}
+export interface ControlClient {
+    /** Sends `{method, params}`, resolves with the server's `result`, or rejects with a {@link ControlError} (or a plain `Error` for a connection-level failure/timeout). */
+    request<T = unknown>(method: string, params?: unknown): Promise<T>;
+    /** Sends a streaming request; `onEvent` fires for each `event` frame. Returns a handle whose `close()` ends the WHOLE connection (per the protocol: "client may just close the connection to unsubscribe") — don't share a client between a `subscribe()` and other concurrent `request()` calls if you need them to outlive each other. */
+    subscribe(method: string, params: unknown, onEvent: (event: unknown) => void): {
+        close: () => void;
+    };
+    /** Closes the underlying connection. Safe to call more than once. */
+    close(): void;
+}
+export type ConnectControlResult = {
+    ok: true;
+    client: ControlClient;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Reads the control token, connects, and performs the handshake — see the module doc comment for why failures here collapse into `{ok:false, reason}` rather than throwing. */
+export declare function connectControlClient(opts: ControlClientOptions): Promise<ConnectControlResult>;
+/**
+ * Unpair's own poll for "has the daemon actually exited yet" (see
+ * `bin/commands/unpair.ts`): both the control token file being gone AND a
+ * fresh connect attempt being refused, checked directly rather than through
+ * a full `connectControlClient` handshake — cheaper per poll, and matches
+ * the exact two-condition check the M4 design calls for.
+ */
+export declare function isControlDaemonGone(storeDir: string, productId: string): Promise<boolean>;

package/dist/bin/format.d.ts

@@ -0,0 +1,67 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+import type { ConnectionState, DaemonBranding, DaemonEvent, DaemonTaskInfo } from '../index';
+import type { ControlStatusResult, PendingApproval } from '../daemon/control-protocol';
+import type { ProbedRuntime } from './runtime-probe';
+import type { TaskCounts, DerivedTaskInfo } from './tasks-view';
+/** Renders one `task.progress`-derived `AgentEvent` compactly — the inner payload of a `progress`-kind `DaemonEvent`. */
+export declare function formatAgentEvent(event: AgentEvent): string;
+export interface FormatDaemonEventLineOptions {
+    /**
+     * Finding F8 (cross-model adversarial review): redact an
+     * `awaiting-approval` event's `summary` to a `[redacted: N bytes]`
+     * placeholder instead of the raw text. `summary` can carry the exact
+     * tool-call text (a shell command, a file's contents) a `confirm`-mode
+     * policy is gating — `start.ts`'s stdout is captured verbatim by
+     * launchd/systemd/WinSW service logs, which have no business holding
+     * that. Default `false` (full fidelity) — every OTHER caller
+     * (`tasks --follow`'s control-socket path, which is authenticated;
+     * and its audit-log-tailing fallback, whose events are ALREADY redacted
+     * at the source by `audit-log.ts` regardless of this flag) keeps showing
+     * whatever it already legitimately can. Only `bin/commands/start.ts`
+     * sets this to `true`.
+     */
+    redactApprovalSummary?: boolean;
+}
+/**
+ * One line per `DaemonEvent`. Shared by `start` (printed to stdout live
+ * while it runs) and `tasks --follow` (tailing the identical shape back out
+ * of the audit log) so the two ways of watching the same feed read
+ * identically.
+ */
+export declare function formatDaemonEventLine(event: DaemonEvent, options?: FormatDaemonEventLineOptions): string;
+export declare function formatTaskLine(task: DaemonTaskInfo | DerivedTaskInfo): string;
+export declare function formatTaskListLines(tasks: readonly (DaemonTaskInfo | DerivedTaskInfo)[]): string[];
+export declare function formatRuntimeLines(runtimes: readonly ProbedRuntime[]): string[];
+export interface StatusView {
+    productName: string;
+    productId: string;
+    branding?: DaemonBranding;
+    paired: boolean;
+    deviceId?: string;
+    connection?: {
+        state: ConnectionState;
+        ts: string;
+    };
+    runtimes: readonly ProbedRuntime[];
+    taskCounts: TaskCounts;
+    auditLogPath: string;
+    auditLogLineCount: number;
+}
+export declare function formatStatusLines(view: StatusView): string[];
+/**
+ * M4 Phase 2: renders the control socket's live `status` result — appended
+ * after {@link formatStatusLines}' persisted-state view when a running
+ * daemon is actually reachable (see `bin/commands/status.ts`). Every line
+ * is prefixed `live-` (or is the single `live:` summary line) so it's
+ * unambiguous which lines are a live snapshot of a running process versus
+ * the historical/persisted view above them.
+ */
+export declare function formatLiveStatusLines(live: ControlStatusResult): string[];
+/**
+ * Finding F4: renders `approvals.list`'s registry entries for the new
+ * `byok-agent approvals` command (`bin/commands/approvals.ts`) — columns
+ * approvalId, taskId, age, summary excerpt, per that finding's own spec.
+ * `nowMs` is injected (rather than read via `Date.now()` here) so tests get
+ * deterministic age rendering; the real caller passes `Date.now()`.
+ */
+export declare function formatApprovalsListLines(approvals: readonly PendingApproval[], nowMs: number): string[];

package/dist/bin/runtime-probe.d.ts

@@ -0,0 +1,34 @@
+import { type RuntimeAdapter } from '../index';
+export declare const RUNTIME_PROBE_TIMEOUT_MS = 5000;
+/** The bundled adapter set `byok-agent status`/`byok-agent runtimes` probe by default — same unset-vs-set allowlist contract as `createDaemon` itself. */
+export declare function defaultRuntimeAdapters(runtimeAllowlist: string[] | undefined): RuntimeAdapter[];
+/**
+ * What `byok-agent status`/`byok-agent runtimes` show per runtime — a
+ * flattened, display-ready merge of `RuntimeDetectResult` and
+ * `RuntimeCapabilities` (see `../types.ts`). Always probed fresh (this
+ * module never reads from the daemon or the audit log) — see
+ * `byok-agent.ts`'s header comment for why a live, standalone probe is the
+ * honest choice for "what's on this machine right now" instead of a
+ * historical snapshot.
+ */
+export interface ProbedRuntime {
+    id: string;
+    present: boolean;
+    version?: string;
+    authPresent?: boolean;
+    steer: boolean;
+    resume: boolean;
+    permissionModes: string[];
+}
+/**
+ * Runs `detect()`/`capabilities()` on each adapter, in parallel. Every
+ * bundled adapter's own `detect()` already catches its own failures (e.g.
+ * `pi-adapter.ts`'s `detect()` wraps its version probe in try/catch and
+ * resolves `{present: false}` rather than rejecting) — the catch here is a
+ * defensive backstop for a `RuntimeAdapter` that doesn't hold that
+ * convention, not a workaround for an observed failure in the bundled
+ * three.
+ */
+export declare function probeRuntimes(adapters: readonly RuntimeAdapter[], options?: {
+    timeoutMs?: number;
+}): Promise<ProbedRuntime[]>;

package/dist/bin/tasks-view.d.ts

@@ -0,0 +1,49 @@
+import { type TaskState } from '@byok-sdk/protocol';
+import { type ConnectionState, type DaemonEvent, type DaemonTaskInfo } from '../index';
+export interface TaskGitStatus {
+    /** Opaque local correlation ID; never a path or commit ID. */
+    workspaceId: string;
+    phase: string;
+    headChanged?: boolean;
+    commitsSinceBaseline?: number;
+    dirty?: {
+        staged: number;
+        unstaged: number;
+        untracked: number;
+        conflicted: number;
+    };
+    errorCategory?: string;
+}
+export type DerivedTaskInfo = DaemonTaskInfo & {
+    git?: TaskGitStatus;
+};
+/**
+ * Reconstructs the same shape `DaemonObserver.tasks()` exposes to a LIVE
+ * in-process daemon, but from a REPLAYED sequence of already-logged
+ * `DaemonEvent`s instead — this is what lets a separate, short-lived
+ * `byok-agent tasks`/`status` invocation show task state without attaching
+ * to the `start` process that actually observed it (see `byok-agent.ts`'s
+ * header comment). Deliberately a standalone reducer, not a call into
+ * `DaemonObserver` itself: `DaemonObserver`'s own public methods
+ * (`handleInboundEnvelope`/`handleOutboundEnvelope`) take a raw protocol
+ * `Envelope`, not the already-normalized `DaemonEvent` this module receives
+ * from the audit log — the two shapes don't line up, so this mirrors that
+ * reducer's logic operating on `DaemonEvent.kind` directly instead.
+ */
+export declare function deriveTasksFromEvents(events: readonly DaemonEvent[]): DerivedTaskInfo[];
+/**
+ * Most recent `connection` DaemonEvent, if the log has any — used by
+ * `status` to show a best-effort "last known" transport state. Never a
+ * live/current guarantee: if `start` isn't running right now, this is
+ * simply whatever it last reported before exiting (or nothing, if it never
+ * ran at all) — see `byok-agent.ts`'s header comment.
+ */
+export declare function lastConnectionState(events: readonly DaemonEvent[]): {
+    state: ConnectionState;
+    ts: string;
+} | undefined;
+export type TaskCounts = Record<TaskState, number> & {
+    total: number;
+};
+/** Zero-filled over every `TaskState` (via `TASK_STATES`, the single authority — not a hand-maintained list) so a state with zero current tasks still renders instead of being silently absent. */
+export declare function tallyTaskStates(tasks: readonly DaemonTaskInfo[]): TaskCounts;