@alook/daemon 0.0.152

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Alook
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md

@@ -0,0 +1,342 @@
+# @alook/daemon
+
+A **pure, host-neutral agent-runtime "driver" abstraction** in TypeScript.
+
+It documents — as compilable code — how a host adapts many different AI coding
+runtimes (Claude Code, Codex, Gemini, Kimi, Pi, Copilot, Cursor, OpenCode,
+Antigravity) behind one uniform interface, and how it delivers messages into a
+running agent (the "steering" mechanism).
+
+The backend hardcodes **no specific host platform**. The agent always invokes a
+stable CLI name (`alook`); `cliTransport.ts` writes a small wrapper by that
+name into a per-launch state dir, prepends it to `PATH`, and forwards to the
+host's real `targetCommand` — **decoupling the agent-facing name from the host's
+real binary** (the host can rename/relocate its CLI without touching the agent
+surface). It also injects an `ALOOK_*` env contract. The default
+`MOCK_CLI_CONFIG` wires no `targetCommand` (the wrapper errors if invoked); a
+real deployment passes its own `CliTransportConfig` (CLI name, env prefix,
+`targetCommand`) and its own system-prompt communication guide. The abstraction
+is what's reusable — plug in whatever host you like.
+
+> **Provenance.** The shapes, protocols, flag strings, and control flow here were
+> derived by studying how production agent-runtime daemons drive these CLIs, then
+> re-expressed as a tidy, generic abstraction. It is original code, not a copy of
+> any vendor source, and carries no platform-specific glue.
+
+---
+
+## The big idea
+
+The daemon never speaks a runtime's native protocol directly. Each runtime is
+wrapped by a **`Driver`** (`src/types.ts`) that knows how to:
+
+1. **`spawn`** (or `createSession`) — launch the runtime,
+2. **`encodeStdinMessage`** — encode an outgoing user message for the runtime's
+   input channel,
+3. **`parseLine`** — normalize the runtime's output into a tiny shared event
+   vocabulary (`ParsedEvent`: `session_init`, `thinking`, `text`, `tool_call`,
+   `tool_output`, `compaction_*`, `turn_end`, `error`, `telemetry`).
+
+A generic **session host** then runs the process and fans `ParsedEvent`s out to
+the daemon:
+
+- `ChildProcessRuntimeSession` (`src/runtime/runtimeSession.ts`) for CLI runtimes.
+- `SdkRuntimeSession` (`src/runtime/sdkRuntimeSession.ts`) for in-process SDK
+  runtimes (pi).
+
+Because everything downstream consumes the same `ParsedEvent` stream and the
+same `Driver` capability flags, the rest of the daemon is transport-agnostic.
+
+---
+
+## Two delivery models (the heart of it)
+
+When a message arrives, what happens depends on the runtime's lifecycle:
+
+### Persistent runtimes (claude, codex, kimi, pi)
+One long-lived process spans many turns. A new message is **written onto the
+still-open input channel** — no restart. This is "steering."
+
+- **`direct`** (codex, kimi, pi): write immediately; the runtime
+  tolerates injection any time.
+- **`gated`** (claude): a raw write mid-stream could collide with an active
+  signed thinking block, so writes are **held until a safe boundary**. Two state
+  machines implement this:
+  - `RuntimeTurnState` (`src/runtime/turnState.ts`) — the instantaneous gate:
+    `canSteerBusy = currentTurnId && !steeringGateActive`. Tool boundary closes
+    the gate; progress / turn-start reopens it.
+  - `apmStateMachine` (`src/runtime/apmStateMachine.ts`) — the policy reducers
+    that decide *when* to flush queued inbox notices and emit the concrete
+    `notify_stdin` / `deliver_stdin` effects (clause `SMR-002`). Flushing is
+    blocked while `outstanding_tool_uses > 0`, while `compacting`, while
+    `reviewing` (Codex review mode), or when `tool_boundary_flush_disabled`.
+    Compaction *and* review exit are treated as safe flush boundaries.
+
+For Claude specifically, the input channel is **stream-json**: the process is
+launched with `--input-format stream-json --output-format stream-json
+--include-partial-messages`, and each message is one NDJSON line
+`{"type":"user","message":{"role":"user","content":[{"type":"text","text":…}]}}`.
+
+### Per-turn runtimes (gemini, copilot, cursor, opencode, antigravity)
+The process handles exactly one turn and exits. `supportsStdinNotification` is
+`false` and `encodeStdinMessage` returns `null`. A new message means a **brand-new
+process**; the agent re-checks the inbox each wake. This lifecycle
+(`lifecycle.kind: "per_turn"`) drives the `## Message Notifications` section
+generated by `buildCliSystemPrompt` — no driver hand-writes this reminder.
+`opencode` is a special per-turn case: it defers spawning until a concrete
+message and terminates the process on turn end.
+
+---
+
+## Runtime comparison
+
+| Runtime | Lifecycle | Transport / protocol | Steering | Initial input | Output format |
+|---|---|---|---|---|---|
+| **claude** | persistent | child process, stream-json NDJSON | `gated` | `{type:"user",…}` line on stdin | stream-json |
+| **codex** | persistent | child process, JSON-RPC 2.0 (`app-server --listen stdio://`) | `direct` (`turn/steer`) | `initialize` → `thread/start`/`resume` | JSON-RPC notifications |
+| **kimi** | persistent | child process, JSON-RPC "wire" | `direct` (`steer`) | `initialize` → `prompt` | JSON-RPC events |
+| **pi** | persistent | in-process SDK (`@earendil-works/pi-coding-agent`), multi-provider | `direct` | `session.prompt()` | SDK event callback |
+| **gemini** | per-turn | child process, stream-json | none | prompt on stdin, then close | stream-json |
+| **copilot** | per-turn | child process, JSON | none | prompt as `-p` arg | JSON events |
+| **cursor** | per-turn | child process, stream-json | none | prompt as trailing arg | stream-json |
+| **opencode** | per-turn (defer-spawn, terminate-on-end) | child process, JSON | none | prompt as `-- <arg>` | JSON events |
+| **antigravity** | per-turn | child process, **plain text** | none | prompt on stdin, then close | plain text lines |
+
+(Each driver's exact launch flags live in its file under `src/drivers/`.)
+
+---
+
+## Layout
+
+```
+src/
+  types.ts                       # Driver interface + ParsedEvent + lifecycle/capability types
+  index.ts                       # public entry point
+  logger.ts                      # tiny structured logger (ALOOK_LOG_LEVEL); wired through
+                                  #   wsControlChannel.ts/agentRouter.ts/managerRuntime.ts too, not just cli/daemonStart.ts
+  drivers/
+    index.ts                     # getDriver(runtimeId) registry  ← start here
+    cliTransport.ts              # shared: state dir, token, decoupling cliName wrapper -> targetCommand, env
+    systemPrompt.ts              # shared: standing-prompt assembly
+    probe.ts                     # CLI/binary detection + version
+    claude.ts                    # Claude Code driver
+    claudeLaunch.ts              #   args / command / spawn-spec / prompt-file
+    claudeProviderIsolation.ts   #   custom-provider HOME/config isolation
+    claudeEventNormalizer.ts     #   stream-json → ParsedEvent
+    codex.ts / codexEventNormalizer.ts / codexTelemetrySidecar.ts
+    gemini.ts  copilot.ts  cursor.ts  opencode.ts  antigravity.ts
+    kimi.ts                      # child-process Kimi (JSON-RPC wire)
+    pi.ts                        # in-process Pi SDK (multi-provider)
+  runtime/
+    runtimeSession.ts            # ChildProcessRuntimeSession + descriptor
+    sdkRuntimeSession.ts         # SdkRuntimeSession (in-process)
+    turnState.ts                 # instantaneous steering gate
+    apmStateMachine.ts           # gated-delivery policy reducers (SMR-002)
+    progressState.ts             # liveness / stall detection
+    notificationState.ts         # inbox-notice de-dup + batching
+    errorDiagnostics.ts          # runtime-error classification + scrubbing
+  inbox/
+    projection.ts                # bucket pending messages by target → notice snapshots
+    stateMachine.ts              # pre-action freshness guard (forward / hold / bypass)
+  manager/
+    managerPolicy.ts             # pure reducer: single-flight, wake/sleep, queue+coalesce, stalled
+    managerRuntime.ts            # AgentProcessManager: applies effects to real sessions
+  server/
+    contract.ts                  # ServerApi (data) + EnrollmentApi (machine→runner key) + HostControlChannel (control) + AdminApi
+    wsControlServer.ts           # server end of the control plane over ws (machine-key authed)
+    wsControlChannel.ts          # host end: WebSocket HostControlChannel (injectable socket, reconnect + heartbeat + resync)
+  daemon/
+    createDaemon.ts              # runtime-agnostic daemon factory (driver/sessionFactory/runtimes INJECTED; no test code)
+  cli/
+    index.ts                     # the `alook` agent CLI skeleton (message send / inbox pull)
+    proxyServerApi.ts            # agent data-plane client: voucher → proxy → server (identity from the voucher)
+  credentials/
+    credentialProxy.ts           # CredentialBroker (mint/revoke/check per-voucher vouchers) + local key-swapping proxy
+scripts/
+  daemon.ts                      # DAEMON process: thin launcher — wraps `alook daemon start` for local dev
+```
+
+## Host orchestration (manager + server)
+
+Beyond driving a single runtime, the backend includes the **host-side**
+orchestration so it can run agents end-to-end:
+
+- **`manager/`** — `AgentProcessManager` schedules processes. Decisions live in a
+  pure reducer (`managerPolicy.ts`: single-flight one-process-per-agent, wake/sleep,
+  message queue + coalesce, stalled detection → `spawn`/`send`/`stop`/`terminate_stalled`
+  effects); a thin executor (`managerRuntime.ts`) applies them to real sessions and
+  feeds runtime events back in. `AgentRouter` consumes the control plane (below).
+- **`server/`** — the agent ⇄ server boundary, split into two planes that share
+  one contract (`contract.ts`):
+  - **data plane** (`ServerApi`): what the `alook` CLI calls — `send` / `inboxPull` /
+    `ack` / `read` / `listChannels`, addressed by path-style `ChannelRef`s.
+  - **control plane** (`HostCommand` + `HostControlChannel`): server → host commands
+    (`agent:wake` / `agent:stop`; plus `bot:*` lifecycle frames). `agent:wake` carries a
+    bodiless `UnreadNotice` (channel + latest seq, no message content) — the DAEMON
+    (`AgentRouter`/`AgentProcessManager`), not the server, decides whether to spawn a
+    process, notify an already-running one, or coalesce the notice for the next turn.
+  There is no in-process fixture standing in for the server: `wsControlServer.ts`
+  (server end) and `wsControlChannel.ts` (host end, injectable socket +
+  exponential-backoff reconnect + heartbeat) carry the `HostCommand` frames over
+  a real WebSocket (`ws://127.0.0.1` in local dev, a real `ws-do` URL in
+  production). A real server connection is the same `WsControlChannel` pointed
+  at a real URL — nothing upstream changes.
+
+`tests/integration/daemon/control-plane.test.ts` wires a real `WsControlChannel`
+against a running `ws-do dev` server into a complete loop: seed a server/bot/
+machine, post a message as a human owner over real HTTP, and assert the daemon's
+control channel receives the resulting `agent:wake` `HostCommand` — then, acting
+as the agent (no CLI spawned), replies over the real credential chain
+(enroll → voucher → proxy → X-Agent-Id) and asserts the reply is readable back
+over real HTTP. See "Point a daemon at real infra locally" below for how to run
+the pieces this test drives by hand.
+
+## Credentials (zero-trust isolation)
+
+A spawned runtime needs *some* credential to call back to the server, but handing
+it the real API key means the agent process (and any tool it runs) can read it,
+can't be scoped, and a leak forces a rotation. `credentials/credentialProxy.ts`
+implements the **voucher** pattern instead — the same shape a production daemon
+uses:
+
+1. The host starts one local key-swapping proxy on `127.0.0.1` (loopback only).
+2. For each launch, a `CredentialBroker` **mints a per-launch voucher** (`vch_…`)
+   into a 0600 file. The child is given `<PREFIX>_PROXY_URL` +
+   `<PREFIX>_PROXY_TOKEN_FILE` + its capability set — **never the real key**.
+3. The child's CLI calls the proxy with `Authorization: Bearer vch_…`.
+4. The proxy validates the voucher, **swaps in the real `Bearer <hostApiKey>`**,
+   stamps `X-Agent-Id` / `X-Client` / `X-Agent-Active-Capabilities`, and forwards
+   to the host-supplied upstream.
+
+This buys **credential isolation** (the agent only ever holds a voucher),
+**capability scoping** (the proxy rejects endpoints outside the voucher's caps),
+and **revocability** (vouchers are per-launch and individually revocable; rotating
+a leaked voucher never touches the real key). This is the **only** credential path
+— `cliTransport` requires `ctx.credentialProxy` (a running broker + proxy URL) and
+throws without it; there is no plaintext fallback that would hand the agent a real
+key. Everything is host-neutral: the real key, upstream URL, voucher prefix, and
+header names all come from the host via `CredentialBrokerConfig`.
+
+`src/credentials/credentialProxy.test.ts` covers the swap, voucher rejection
+(`invalid local agent proxy token`), capability scoping, and revocation against a
+throwaway upstream.
+
+### Three key tiers (and where each lives)
+
+A production daemon keeps **three** credential tiers, not two — important for
+understanding what `hostApiKey` should be:
+
+1. **Machine master key** — authenticates the daemon to the server and is used to
+   **mint** per-agent credentials. Held in daemon memory only (not persisted to
+   disk or keychain). ⚠️ In the current daemon it is passed as a process **argv**
+   (`--api-key …`), so any local process can read its full value via `ps aux`.
+   Mitigation: source it from an env var, a 0600 file, or the OS keychain instead
+   of argv. This proxy **never forwards the master key**.
+2. **Per-agent runner credential** — the server mints one per agent (scoped to
+   that agent, individually revocable) when the daemon asks with the master key.
+   This is what the proxy actually swaps in and forwards upstream, and what
+   belongs in `CredentialBrokerConfig.hostApiKey`. Minting it from the master key
+   is **host-side orchestration** and is intentionally out of scope for this
+   backend.
+3. **`vch_` voucher** — minted by `CredentialBroker` per launch, written to a 0600
+   file, and the only credential the agent process ever sees.
+
+## Inbox layer (freshness)
+
+Two pieces govern how messages reach the agent and how outgoing actions are
+gated:
+
+- **`inbox/projection.ts`** — `projectAgentInboxSnapshot` buckets pending
+  messages by target (channel / DM / thread) and projects each into the
+  metadata-only summary surfaced as an `[inbox notice: …]` (count, first,
+  latest, sender, flags). No bodies — the agent pulls those with
+  `alook inbox pull`.
+- **`inbox/stateMachine.ts`** — `planAgentInboxSideEffect` is the "don't reply on
+  stale context" guard. Before an outward action (`send` / `task_claim` /
+  `task_update`) it compares the model's seen `seq` boundary against pending
+  messages and returns **forward** (let it through), **held** (hold the action,
+  surface the latest few unseen messages as held context to reconcile first —
+  this is the "Freshness hold → saved as a draft" you can hit when messaging a
+  busy agent), or **bypass** (explicit `continueAnyway`). It is a pure function
+  producing a stable `producerFactId`; clause ids `SMR-002` (consume) and
+  `SMR-006` (held envelope) are preserved.
+
+## Build & run
+
+This project uses **pnpm** (see the `packageManager` field).
+
+```bash
+pnpm install
+pnpm run typecheck           # tsc --noEmit (passes clean)
+pnpm test                    # vitest — unit tests only (drivers/manager/inbox/credentials/server)
+pnpm run test:integration    # real infra: requires wrangler dev + ws-do dev + wake-worker dev (see below)
+```
+
+Unit behavior is covered by `src/**/*.test.ts`. Full control-plane and
+credential-chain behavior against real infra is covered by
+[`tests/integration/daemon/`](../../tests/integration/daemon) — see that
+directory for the executable reference of how the pieces fit together over
+the network (real `WsControlChannel` over a real WebSocket, real
+`enroll-agent`/credential-proxy HTTP calls, no in-process shortcuts).
+
+### Point a daemon at real infra locally
+
+There's no mock server to stand in for `src/web`/`src/ws-do` — a daemon
+always talks to the real thing. To drive one by hand in local dev, run the
+real servers and walk the real credential chain (`cmt_` pairing token →
+`cmk_` daemon credential → `crk_` per-agent runner key):
+
+**Terminal 1 — the web app + control-plane DO:**
+
+```bash
+pnpm --filter @alook/web dev      # http://localhost:3000
+pnpm --filter @alook/ws-do dev    # ws://localhost:8789
+```
+
+**Terminal 2 — pair + activate a machine**, then start a daemon with the
+resulting `cmk_...` credential:
+
+```bash
+# 1. As a signed-in user, create a pairing token:
+curl -s -X POST http://localhost:3000/api/community/machines/pair \
+  -H "Cookie: <session-cookie>" | tee /tmp/pair.json
+# → { "tokenId": "cmt_…", "expiresAt": "…" }
+
+# 2. Exchange it for a daemon credential:
+curl -s -X POST http://localhost:3000/api/community/daemon/activate \
+  -H "Authorization: Bearer $(jq -r .tokenId /tmp/pair.json)" \
+  -H "content-type: application/json" \
+  -d '{"hostname":"my-laptop","platform":"darwin","arch":"arm64"}'
+# → { "credential": "cmk_…", "machineId": "cm_…", "expiresAt": null }
+
+# 3. Start the daemon with that credential:
+ALOOK_MACHINE_KEY=cmk_… \
+ALOOK_SERVER_URL=http://localhost:3000 \
+ALOOK_SERVER_WS_URL=ws://localhost:8789 \
+pnpm run daemon
+```
+
+A bot bound to this machine (via the community UI/API) can now be woken by
+posting a message in a channel it's a member of — the real wake-producer path
+(`src/web` → `src/wake-worker` → `src/ws-do`) delivers `agent:wake` over the
+daemon's real `WsControlChannel`.
+
+> **Run the source, not `dist/` (yet).** `pnpm run build` emits JS, but the
+> current Bundler-resolution emit produces extensionless relative imports that
+> Node's native ESM rejects (`Cannot find module './types'`). Until that's
+> switched to NodeNext or bundled, consume the library through a TS toolchain
+> (tsx / ts-node / vite / esbuild / webpack).
+
+## Usage sketch
+
+```ts
+import { getDriver, createChildProcessRuntimeSession } from "@alook/daemon";
+
+const driver = getDriver("claude");
+const session = createChildProcessRuntimeSession(driver, ctx);
+session.on("runtime_event", (e) => handleParsedEvent(e));
+await session.start({ text: initialPrompt });
+
+// Later, a message arrives while the agent is working:
+session.send({ text: "new message from #general", mode: "busy" }); // steer
+```