@aiworker/web 1.22.0 → 1.23.0

package/server/lib/project-context/DOCUMENTATION.md.bak

@@ -1,160 +0,0 @@
-# Project Context
-
-Server-owned storage for the Project Notes surface: free-form notes, todos, and
-plan markdown files.
-
-The managed Chats root (`~/.config/openchamber/chats`) is also one context owner. Every dated per-session directory beneath it resolves to that root, so Notes, Todo, Plans, pinned knowledge, and project memory are shared across ordinary chats without registering Chats as a user project.
-
-## Ownership
-
-| Path | Owner | Contents |
-|---|---|---|
-| `<projectsDir>/<projectId>.json` | shared UI (`packages/ui/src/lib/openchamberConfig.ts`), plus server-owned `version` / `scheduledTasks` | worktree setup, draft starters, project actions |
-| `<projectsDir>/<projectId>/context.json` | **this module, exclusively** | notes, todos, plan manifest |
-| `<projectsDir>/<projectId>/plans/*.md` | **this module, exclusively** | plan bodies |
-
-The split is the point. Both files were previously one, written by the client
-with a whole-file read-modify-write. Adding a server writer to that file would
-have made unrelated features (project actions, draft starters) clobber notes
-across processes, with no lock able to span both sides. Separate files remove
-the shared resource instead of trying to coordinate access to it.
-
-Nothing outside this module may write `context.json` or the `plans` directory.
-
-## Storage format
-
-```json
-{
-  "version": 2,
-  "notes": [{
-    "id": "", "body": "", "createdAt": 0, "updatedAt": 0,
-    "source": "manual | selection | agent",
-    "origin": { "sessionId": "", "messageId": "" }
-  }],
-  "todos": [{ "id": "", "text": "", "completed": false, "createdAt": 0 }],
-  "plans": [{ "id": "", "file": "1700000000-title.md", "title": "", "createdAt": 0 }]
-}
-```
-
-Notes are entries, not one blob. Version 1 stored a single string; it converts
-to a single `manual` note on read (an empty string converts to no notes at
-all). The conversion lives in the read path rather than a separate migration
-pass so that every reader — including one racing a writer — sees one shape.
-Legacy `pinned` fields may remain in existing files but are ignored; attachment
-ownership lives in each session's metadata.
-
-`source` records where a note came from, and `origin` links it back to the
-message it was distilled from, so a note taken off a chat selection can be
-traced to its conversation.
-
-Notes and todos are written through separate routes. That split is what stops a
-todo toggle from persisting half-typed notes alongside it, and stops an
-agent-authored note from clobbering a concurrent todo change.
-
-Plan links store a **base name**, never a path. The file always lives in
-`<projectId>/plans/`, so moving the project storage directory cannot invalidate
-a reference and a caller can never address a file outside it. `title` is
-denormalized into the manifest so listing plans costs one read rather than one
-read per plan; `readPlan` returns the title parsed from the file, which wins if
-the two ever disagree.
-
-## Routes
-
-| Method | Route | Notes |
-|---|---|---|
-| GET | `/api/project-context/:projectId` | full context; missing file is `200` empty |
-| PUT | `/api/project-context/:projectId/todos` | replaces the whole list; returns committed context |
-| POST | `/api/project-context/:projectId/notes` | `201`; takes `{body, source?, origin?}` |
-| PATCH | `/api/project-context/:projectId/notes/:noteId` | patches `body`; legacy `pinned` input is ignored by session knowledge; `404` when unknown |
-| DELETE | `/api/project-context/:projectId/notes/:noteId` | `404` when unknown |
-| PATCH | `/api/project-context/:projectId/plans/:planId` | legacy project pin state only; session attachment uses session knowledge; `404` when unknown |
-| GET | `/api/project-context/:projectId/plans/:planId` | `404` when the link or its markdown is gone |
-| POST | `/api/project-context/:projectId/plans` | `201`; takes `{title, body}`, never a path |
-| PUT | `/api/project-context/:projectId/plans/:planId` | takes the whole `{raw}` document; `404` when the link or its markdown is gone |
-| DELETE | `/api/project-context/:projectId/plans/:planId` | `404` when unknown |
-
-**Body parsing is attached per route.** This server has no global JSON parser:
-`core-routes` parses only an allowlist of `/api` path prefixes so the generic
-OpenCode proxy keeps an unread request stream, and every other `/api` request
-passes through untouched. A write route that forgets `express.json()` therefore
-sees `req.body` as `undefined` and rejects every request as a malformed body —
-which is exactly how this shipped once. `routes.http.test.js` mounts the routes
-on a bare express app so that failure mode fails the suite instead of the user.
-
-`projectId` is validated against `/^[a-zA-Z0-9._:-]+$/`, which rejects
-separators and traversal. Validation failures are `400`; malformed stored data
-and I/O failures are `500`.
-
-## Invariants
-
-- **Missing is not malformed.** A missing `context.json` is authoritative empty
-  data. Unparseable JSON is a failure that propagates as `500`, so the client
-  preserves what it already has instead of rendering an empty panel over intact
-  data on disk.
-- **Writes are serialized per project** through an in-process lock, and land via
-  write-to-temp + rename so a crash cannot leave a half-written file.
-- **`readContext` never takes the lock.** Every mutator calls it while already
-  holding the lock, so locking there would deadlock. The legacy migration it can
-  trigger is safe unlocked: both writes are atomic renames of identical content.
-- **Plan create writes markdown before the manifest entry**; delete removes the
-  manifest entry before the file. Either partial failure leaves an unreferenced
-  markdown file, which is inert. The reverse order would leave a manifest entry
-  that renders as a plan and fails to open.
-- **Plan update takes the raw document, not title + body.** The editor owns
-  the file verbatim; reassembling it from parsed parts would rewrite the
-  heading and reformat what the user typed. The manifest title is re-derived
-  from the saved content, and the file name never changes with the title — it
-  is the stable identity behind the link.
-- **Plan update refuses to recreate a deleted file.** If the markdown vanished
-  underneath an open editor the link is already dead; writing would resurrect
-  content the user believes was discarded, so it returns `404` instead.
-- **A note patch touches only the fields it names.** Pinning sends `pinned`
-  alone, so it cannot roll back an edit that landed between the two requests,
-  and editing does not reset a pin. Editing bumps `updatedAt`; pinning does not,
-  because a pin is not a change to what the note says.
-- **A note body can be clamped but never blanked.** An empty body is rejected
-  rather than stored, since a note with nothing in it is indistinguishable from
-  a delete the user did not ask for.
-- **Notes are capped at 200 per project.** Past that, creation fails loudly
-  instead of silently evicting the oldest entry.
-- **Per-entry sanitization never fails the whole read.** A malformed todo or
-  plan link is dropped; the rest of the context still loads.
-
-## Legacy migration
-
-`projectNotes`, `projectTodos`, and `projectPlanFiles` originally lived in
-`<projectId>.json`. On the first read with no `context.json`, those three keys
-are moved out and deleted from the client-owned file; every other key is
-preserved untouched.
-
-Plan links carried absolute paths. Migration converts each to a base name. A
-file already in the plans directory is used in place; one referenced from
-elsewhere — a stale path left by an earlier project id — is copied in rather
-than dropped. A link whose markdown cannot be found at all is discarded, since
-it could not have been opened either way.
-
-The legacy keys are removed only after `context.json` is durably written, so any
-failure simply leaves the migration to run again on the next read. Repeat and
-concurrent reads converge on identical content.
-
-## Cross-module contract
-
-`packages/web/server/lib/opencode/settings-runtime.js` merges project storage
-when a project id changes. Its `mergeProjectContextFiles` step must run before
-`moveDirectoryContents`, because that mover only renames into a free
-destination and would otherwise discard the old `context.json` whenever the
-destination already had one.
-
-`mergeProjectContextFiles` merges every list by identity and deliberately does
-not convert a version 1 string note: this module owns that conversion, and
-doing it in two places would mean two definitions of the same migration.
-
-`mergeProjectConfigData` still merges the legacy `projectNotes` /
-`projectTodos` / `projectPlanFiles` keys. That is deliberate: a project whose
-context has not been migrated yet keeps its data in `<projectId>.json`, and the
-migration picks it up from the merged destination afterwards.
-
-## Tests
-
-- `runtime.test.js` — storage, sanitization, migration, locking, plan lifecycle.
-- `routes.test.js` — status-code mapping, payload validation, failure surfacing.

package/server/lib/quota/DOCUMENTATION.md.bak

@@ -1,123 +0,0 @@
-# Quota Module Documentation
-
-## Purpose
-This module fetches quota and usage signals for supported providers in the web server runtime.
-
-## Entrypoints and structure
-- `packages/web/server/lib/quota/index.js`: public entrypoint imported by `packages/web/server/index.js`.
-- `packages/web/server/lib/quota/routes.js`: Express route registration for quota endpoints.
-- `packages/web/server/lib/quota/providers/index.js`: provider registry, configured-provider list, and provider dispatcher.
-- `packages/web/server/lib/quota/providers/google/`: Google-specific auth, API, and transform modules.
-- `packages/web/server/lib/quota/providers/claude/`: Claude credential discovery, usage transforms, and rate-limit handling.
-- `packages/web/server/lib/quota/utils/`: shared auth, transform, and formatting helpers.
-
-## Supported provider IDs (dispatcher)
-
-These provider IDs are currently dispatchable via `fetchQuotaForProvider(providerId)` in `packages/web/server/lib/quota/providers/index.js`.
-
-| Provider ID | Display name | Module | Auth aliases/keys |
-| --- | --- | --- | --- |
-| `claude` | Claude | `providers/claude/` | Claude Code Keychain entry, Claude Code credentials file, OpenCode `auth.json` (`anthropic`, `claude`), `CLAUDE_CODE_OAUTH_TOKEN` |
-| `codex` | Codex | `providers/codex.js` | `openai`, `codex`, `chatgpt` |
-| `command-code` | Command Code | `providers/command-code.js` | `command-code` OAuth/API credential in OpenCode `auth.json`, or `COMMAND_CODE_API_KEY` |
-| `cursor` | Cursor | `providers/cursor.js` | Environment/token files, AiWorker-managed credentials, or explicit one-time Cursor import |
-| `crof` | CrofAI | `providers/crof.js` | `crof` (API key under `key` or `token`) |
-| `deepseek` | DeepSeek | `providers/deepseek.js` | `deepseek` (API key under `key` or `token`) |
-| `google` | Google | `providers/google/index.js` | `google`, `google.oauth`, Antigravity accounts file |
-| `github-copilot` | GitHub Copilot | `providers/copilot.js` | `github-copilot`, `copilot` |
-| `github-copilot-addon` | GitHub Copilot Add-on | `providers/copilot.js` | `github-copilot`, `copilot` |
-| `kimi-for-coding` | Kimi for Coding | `providers/kimi.js` | `kimi-for-coding`, `kimi` |
-| `nano-gpt` | NanoGPT | `providers/nanogpt.js` | `nano-gpt`, `nanogpt`, `nano_gpt` |
-| `openrouter` | OpenRouter | `providers/openrouter.js` | `openrouter` |
-| `zai-coding-plan` | z.ai | `providers/zai.js` | `zai-coding-plan`, `zai`, `z.ai` |
-| `zhipuai-coding-plan` | Zhipu AI Coding Plan | `providers/zhipuai-coding-plan.js` | `zhipuai-coding-plan`, `zhipuai`, `zhipu` |
-| `minimax-coding-plan` | MiniMax Coding Plan (minimax.io) | `providers/minimax-coding-plan.js` / `providers/minimax-shared.js` | `minimax-coding-plan` |
-| `minimax-cn-coding-plan` | MiniMax Coding Plan (minimaxi.com) | `providers/minimax-cn-coding-plan.js` / `providers/minimax-shared.js` | `minimax-cn-coding-plan` |
-| `ollama-cloud` | Ollama Cloud | `providers/ollama-cloud.js` | Manual cookie stored under `~/.config/openchamber/quota/` |
-| `wafer` | Wafer.ai | `providers/wafer.js` | `wafer`, `wafer-ai`, `wafer_ai`, `wafer.ai` |
-| `opencode-go` | OpenCode Go | `providers/opencode-go.js` | `opencode-go` API key from OpenCode `auth.json` |
-| `neuralwatt` | NeuralWatt | `providers/neuralwatt.js` | `neuralwatt` (API key under `key` or `token`) |
-| `xai` | xAI | `providers/xai.js` | `xai` OAuth entry in OpenCode `auth.json` |
-
-## Internal-only provider module
-- `providers/openai.js` exists for logic parity/reuse but is intentionally not registered for dispatcher ID routing.
-
-## Response contract
-All providers should return results via shared helpers to preserve API shape:
-- Required fields: `providerId`, `providerName`, `ok`, `configured`, `usage`, `fetchedAt`
-- Optional field: `error`
-- Unsupported provider requests should return `ok: false`, `configured: false`, `error: Unsupported provider`
-
-Provider modules must export `providerId`, `providerName`, `aliases`, `isConfigured(auth?)`, and `fetchQuota()`.
-`fetchQuota()` should return a quota result with `usage.windows` keyed by window name (for example `5h`, `7d`, `daily`) and optional provider-specific `usage.models` data.
-
-Ollama Cloud and Cursor credentials are explicitly managed through Settings. OpenCode Go usage uses `GET https://opencode.ai/zen/go/v1/usage` with the `opencode-go` API key from OpenCode `auth.json` as a bearer token. The server validates managed credentials before atomic `0600` writes and never returns secrets through its API. AiWorker never scans browser cookie stores or automatically reads Cursor storage; Cursor import is an explicit one-time user action and never modifies Cursor's database.
-
-Command Code usage resolves account scope through `GET /alpha/whoami`, then reads server-backed credit balances and five-hour/weekly limits from `GET /alpha/billing/credits?orgId=...`. Personal accounts return `org: null` and use `/alpha/billing/credits` without an `orgId`; organization accounts include their organization id. Web/Electron and VS Code read the standard `command-code` OpenCode auth entry (including OAuth `access`) or `COMMAND_CODE_API_KEY`; credentials remain in the owning runtime and are never returned to shared UI.
-
-On the first OpenCode Go usage refresh after upgrading, AiWorker deletes the obsolete `quota/opencode-go.json` credential file without reading its cookie value.
-
-## Claude credential and limit semantics
-
-Claude quota reports the subscription limits Claude Code itself is bound by, read from `GET https://api.anthropic.com/api/oauth/usage`.
-
-- **Credential sources**, in priority order: the macOS Keychain entry `Claude Code-credentials`, then `${CLAUDE_CONFIG_DIR:-~/.claude}/.credentials.json` (the Linux/WSL location), then the OpenCode `auth.json` entry, then `CLAUDE_CODE_OAUTH_TOKEN`. The Keychain wins on macOS because the credentials file there is a leftover Claude Code no longer updates.
-- **All sources are read-only.** AiWorker never writes to Claude Code's credential store and never refreshes the OAuth token, because Anthropic does not support two live refresh tokens for one `client_id` — refreshing here would sign the user out of Claude Code. Credentials are read fresh per request so a Claude Code refresh is picked up immediately; an expired token yields an explicit "open Claude Code to sign in again" error rather than a bare 401.
-- **Limits come from the `limits` array**, keyed by `kind`: `session` maps to the `5h` window, `weekly_all` to `7d`, and `weekly_scoped` to a per-model `7d` window named by `scope.model.display_name`. The legacy `five_hour`/`seven_day` fields are only a fallback; `seven_day_sonnet`/`seven_day_opus` are no longer populated by Anthropic. Unrecognized limit kinds and Anthropic's rotating internal code names (`nimbus_quill`, `tangelo`, ...) are ignored rather than guessed at.
-- **Extra usage** is reported as the `extra_usage` window from `spend`, only while `spend.enabled` is true, with a money `valueLabel`.
-- **Rate limiting**: Anthropic returns 429 aggressively. The last successful usage payload is cached in memory and reserved during a cooldown (`Retry-After`, else five minutes, capped at one hour). The cache is keyed by a hash of the access and refresh tokens, so switching accounts drops it instead of showing the previous account's numbers.
-- **Runtime parity**: Web/Electron and VS Code preserve the last successful Claude values during the same bounded 429 cooldown. Quota dispatchers also coalesce concurrent refreshes for the same provider in each runtime, while requests for different providers remain parallel.
-
-## Add a new provider (quick steps)
-1. Choose module shape based on complexity:
-   - Simple providers: create `packages/web/server/lib/quota/providers/<provider>.js`.
-   - Complex providers (multi-source auth, multiple API calls, non-trivial transforms): create `packages/web/server/lib/quota/providers/<provider>/` with split modules like Google (`index.js`, `auth.js`, `api.js`, `transforms.js`).
-2. Export `providerId`, `providerName`, `aliases`, `isConfigured`, and `fetchQuota`.
-3. Use shared helpers from `packages/web/server/lib/quota/utils/index.js` (`buildResult`, `toUsageWindow`, auth/conversion helpers) to keep payload shape consistent.
-4. Register the provider in `packages/web/server/lib/quota/providers/index.js`.
-5. If needed for direct use, export a named fetcher from `packages/web/server/lib/quota/providers/index.js` and `packages/web/server/lib/quota/index.js`.
-6. Update this file with the new provider ID, module path, and alias/auth details.
-7. Validate with `bun run type-check`, `bun run lint`, and `bun run build`.
-
-## MiniMax M3 / Token Plan migration
-
-In 2025/2026 MiniMax rebranded "Coding Plan" to "Token Plan" alongside the M3 model release. The API underwent breaking changes:
-
-- **Endpoint fallback**: The provider tries `/v1/token_plan/remains` (M3) first, falling back to legacy `/v1/api/openplatform/coding_plan/remains`.
-- **Field semantics**: On the `token_plan/remains` endpoint, `current_interval_usage_count` returns **remaining** quota (not consumed). The provider computes `used = total - remaining` for this endpoint. The legacy `coding_plan/remains` endpoint retains the old semantics (`usage_count = consumed`).
-- **Percentage-based plans**: Legacy Coding Plan accounts return `current_interval_total_count: 0` but include `current_interval_remaining_percent`. The provider prefers this field when count fields are absent.
-- **model_remains array**: Now contains entries for multiple model categories (chat, speech, video, image). The provider selects the chat-model entry by matching `MiniMax-M*`, then `general`/`chat`/`text` by name, then any entry with a remaining percent.
-- **Window status**: The `current_interval_status` and `current_weekly_status` fields indicate whether a window is active. Status `3` means the window is not applicable for the current plan tier (e.g. legacy plans without weekly limits). The provider omits inactive windows.
-
-## Kimi for Coding field semantics
-
-`GET https://api.kimi.com/coding/v1/usages` is inconsistent about which field carries consumption:
-- The weekly `usage` block returns `used` (consumed) with no `remaining` field.
-- Each `limits[].detail` rate-limit block returns `remaining` (available) with no `used` field.
-
-The provider computes `usedPercent` from whichever of `used`/`remaining` is present (`used` takes precedence when both exist) rather than assuming one field name. Both `packages/web/server/lib/quota/providers/kimi.js` and `packages/vscode/src/quotaProviders.ts` (`fetchKimiQuota`) must stay in sync — the VS Code extension duplicates this parsing logic rather than importing it.
-
-## GitHub Copilot quota semantics
-
-GitHub Copilot usage exposes only the `premium_interactions` snapshot as the
-`premium_interactions` window. Shared UI labels that window **AI Credits** and treats it as
-the provider's primary usage marker. Legacy chat-request quota and unlimited
-completion quota are intentionally omitted. Keep
-`packages/web/server/lib/quota/providers/copilot.js` and
-`packages/vscode/src/quotaProviders.ts` in sync.
-
-The `/copilot_internal/user` endpoint is undocumented; its quota semantics mirror
-what `microsoft/vscode-copilot-chat` consumes (`CopilotUserQuotaInfo`). Each
-snapshot carries `entitlement`, `remaining`, `unlimited`, and
-`percent_remaining`. Providers must honor these rules:
-
-- `unlimited: true` renders a percent-less window with an "Unlimited" value label.
-- Percent math requires a positive `entitlement`; entitlements of `0`, `-1`, or null are unusable.
-- When entitlement/remaining are unusable, fall back to `100 - percent_remaining`.
-- Snapshots other than `premium_interactions` (legacy annual plans) yield zero windows.
-
-## Notes for contributors
-- Keep provider IDs stable; clients use them directly.
-- Avoid adding alias-based dispatch in `fetchQuotaForProvider`; dispatch currently expects exact provider IDs.
-- Keep Google behavior changes isolated and review `providers/google/*` together.
-- Z.ai Coding Plan exposes separate 5-hour and weekly token/credit limit entries plus a monthly `TIME_LIMIT` for MCP tools. The API renamed the limit type from `TOKENS_LIMIT` to `CREDIT_LIMIT` (same `unit`/`number` window semantics); `CREDIT_LIMIT` entries additionally carry `usage` (total), `currentValue` (consumed), and `remaining`, surfaced as a credit `valueLabel`, and the payload's `data.level` becomes `planLabel`. Web and VS Code must preserve these windows and stay in sync.

package/server/lib/relay/DOCUMENTATION.md.bak

@@ -1,100 +0,0 @@
-# Relay Module Documentation
-
-## Purpose
-
-The private relay lets an AiWorker client (mobile app, browser, or another desktop) reach a user's AiWorker instance through AiWorker-hosted infrastructure when the instance is not directly reachable (behind NAT, no public URL, no tunnel). The instance dials **outbound** to the relay; nothing needs to be exposed inbound.
-
-Traffic is **end-to-end encrypted between the two endpoints** (client and host instance). The relay infrastructure forwards opaque ciphertext and cannot read application traffic — it is an untrusted transport, not a trusted middlebox.
-
-This module (`packages/web/server/lib/relay/`) is the **host side**: it runs inside the AiWorker web server (so it works for Electron desktop, headless server, and CLI installs alike). The **client side** lives in `packages/ui/src/lib/relay/`. The **relay service itself** is a separate Cloudflare Worker in the `openchamber-website` repo and only brokers connections.
-
-## The three layers
-
-Traffic is modeled as three stacked layers. The relay understands only Layer 1; Layers 2–3 exist solely between the client and the host.
-
-1. **Relay routing (Layer 1)** — outbound WebSocket connections to the relay, connection brokering, and host authentication to the relay. The relay routes each client to the correct host and forwards frames verbatim.
-2. **End-to-end encryption (Layer 2)** — an authenticated encrypted channel established directly between client and host, keyed so the relay cannot participate. Built on standard WebCrypto primitives (ECDH key agreement + AEAD framing). The host's encryption public key is distributed to the client out-of-band via the pairing payload and is the client's trust anchor.
-3. **Tunnel multiplexing (Layer 3)** — because an AiWorker client speaks many concurrent HTTP requests, an event stream (SSE), and WebSockets to one origin, the encrypted channel carries a small multiplexing protocol. It frames HTTP request/response (including streamed bodies) and WebSocket sub-streams so the whole app works over one encrypted connection.
-
-## Entrypoints and structure
-
-Host side (`packages/web/server/lib/relay/`):
-- `service.js` — thin entrypoint: relay config (enabled flag + relay URL), the management routes (`GET/POST /api/openchamber/relay/{status,enable,disable}`), a `getPairingCandidate()` accessor (the relay transport candidate folded into pairing-v2 links when enabled, consumed by the pairing-session route in `core-routes.js`), and lifecycle wiring. Started from `packages/web/server/index.js` only when the user has explicitly enabled the relay. The relay endpoint defaults to the AiWorker-hosted relay but can be pinned to a self-hosted relay via the `AIWORKER_RELAY_URL` env var (must be `ws://`/`wss://`); when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically.
-- `identity.js` — the host's stable identity: the long-lived signing keypair (shared with the push relay, defines the routing id) plus a long-lived encryption keypair (the E2EE trust anchor). Reused across restarts; never rotated implicitly.
-- `signing-key.js` — storage/derivation of the signing keypair and the routing id, shared with the notifications runtime.
-- `host-client.js` — the long-lived connection manager: one outbound control connection to the relay, a per-client data connection for each connected device, reconnect/backoff, and the E2EE responder handshake per connection.
-- `host-lock.js` — the per-machine host claim. Every local instance sharing the data dir shares the relay identity (same serverId), so concurrent relay hosts evict each other at the relay worker (`4001: Control replaced`) and paired devices land on whichever local process won last. The claim file (`<data-dir>/relay-host.lock`, `{ pid }`) makes this deterministic: `service.js` only starts the host when no LIVE process holds the claim (stale claims from dead pids are ignored), goes to `standby` otherwise, and a 30s watcher both takes over when the claimant dies and stands down when another process claims. A standby watcher waits a 2-minute grace after the claim frees before taking over, so a cleanly restarting host (app update/relaunch) — which reclaims at boot with no wait — always wins the restart window over a bystander instance. Explicit user intent — creating a pairing link or hitting `/relay/enable` — force-claims; the previous holder's watcher sees the takeover and backs off instead of fighting. Instances created with `allowPassiveHost: false` (dev servers via `AIWORKER_RELAY_HOST=off`, the Electron dev shell via `AIWORKER_ELECTRON_DEV`; `AIWORKER_RELAY_HOST=on` overrides) never start the host passively at all — boot, demand reconcile, and watcher takeover leave them in `standby`; only explicit enable/pairing hosts there. The claim is cooperative (the relay worker still enforces the single host slot); it only decides which process keeps retrying.
-- `tunnel-host.js` — the per-connection dispatcher: decrypts tunnel frames and forwards HTTP/SSE/WS to the local server over loopback, then streams responses back. Enforces a path allowlist and never injects credentials.
-- `e2ee.js`, `tunnel-codec.js` — host-side (JS) mirrors of the shared crypto and framing (see "Two implementations" below).
-
-Client side (`packages/ui/src/lib/relay/`):
-- `protocol.ts` — the shared contract: constants, frame types, message shapes. The normative source both implementations follow.
-- `crypto.ts`, `handshake.ts` — the E2EE primitives and handshake state machines (initiator + responder).
-- `tunnel-codec.ts` — Layer 3 frame codec, fragmentation, and outbound frame batching.
-- `tunnel-client.ts` — the client tunnel: exposes a `fetch()`-compatible and a WebSocket-compatible surface backed by the encrypted tunnel.
-- `tunnel-payloads.ts`, `runtime-tunnel.ts`, `runtime-socket.ts` — payload helpers, the active-tunnel singleton, and the shared "open a runtime WebSocket the right way" helper.
-
-Relay is not a separate link format: it is one transport candidate inside the unified **pairing v2** payload (`packages/ui/src/lib/connectionPayload.ts`). A relay candidate is `{ type: 'relay', relayUrl, serverId, hostEncPubJwk }` — no embedded token; the client redeems the one-time pairing secret over the tunnel like any other candidate.
-
-## What travels the tunnel
-
-Everything a client normally sends to the single AiWorker origin:
-- **HTTP** — REST endpoints and proxied OpenCode SDK calls under `/api/*`, plus `/auth/*` and `/health`.
-- **SSE** — long-lived streamed responses (the event stream and notifications). These are just HTTP responses whose body streams; the tunnel needs no special SSE handling.
-- **WebSocket** — the endpoints that use a real socket (the global event stream on platforms that support WS, terminal I/O, dictation).
-
-The host dispatcher restricts tunneled traffic to explicit path allowlists (one for HTTP, one for WS).
-
-Request bodies crossing the tunnel are buffered on the host and forwarded to loopback only once the client's `StreamEnd` frame arrives (bodies above ~512 KB stream live instead). A body whose frames were lost in transit therefore never reaches the loopback server as an empty/truncated chunked body — the host aborts the stream and the client sees an ambiguous transport failure it can retry, instead of the loopback server's bare `400` ("Failed to send message (400)" from the mobile app).
-
-## Authentication model
-
-- The tunnel is **transport only**. The AiWorker server still authenticates every tunneled request exactly as it authenticates a direct remote client. The relay path grants reachability, not authorization.
-- Clients carry their normal credential. HTTP and SSE requests authenticate with the client's bearer token (a header). **WebSocket upgrades cannot send headers**, so they authenticate with a short-lived URL-scoped token minted beforehand and passed as a query parameter. This asymmetry is important when adding new WebSocket features (see the skill).
-- The host authenticates itself to the relay with a signed handshake using its long-lived signing key.
-- Enabling the relay is explicit opt-in and disabled by default; disabling it severs all relay reachability immediately.
-
-## End-to-end flow (overview)
-
-1. **Pairing.** The host issues a pairing-v2 link (QR / deep link) carrying a one-time secret and a list of transport candidates. When the relay is enabled, one candidate is the relay transport (its endpoint, routing id, and encryption public key — the E2EE trust anchor). The client redeems the secret over the first reachable candidate; over the relay candidate it opens the E2EE tunnel first, then redeems through it, and stores the connection.
-2. **Presence.** When the relay is enabled, the host opens one outbound control connection and waits.
-3. **Connect.** The client connects for a given routing id; the relay notifies the host over the control connection; the host opens a matching per-client data connection.
-4. **Handshake.** Over that connection pair, client and host run the E2EE handshake and derive a shared encrypted channel the relay cannot read.
-5. **Traffic.** All normal app traffic is multiplexed and encrypted through that channel. On the host, decrypted requests are dispatched to the local server over loopback with the actual loopback origin, so normal origin checks still apply without trusting client-supplied origin metadata; responses stream back encrypted. Reconnects re-establish a fresh channel and the app's existing retry machinery recovers.
-
-## Candidate refresh (staying off the relay when direct works)
-
-Pairing-payload transport candidates are a snapshot: when DHCP hands the host
-machine a new LAN address, a device's saved direct candidate goes stale and the
-device silently degrades to relay-only. To recover, an already-paired client can
-call `GET /api/client-auth/connection/candidates` (UI session or client bearer;
-registered with the auth/access routes) over any live transport — including
-through the tunnel — to learn the server's **current** LAN URLs plus the relay
-candidate, and update its saved candidate set (mobile: `mobileConnections.ts`;
-desktop: `desktopRelayRestore.ts`).
-
-Identity gating: the response carries the stable `serverId` (base64url SHA-256 of
-the public signing JWK — the same identity the relay routes by, exposed by the
-relay service's `getServerId()` and echoed unauthenticated on `/health` and
-`/api/version`). Clients ignore a refresh whose `serverId` does not match their
-pinned relay identity, and verify `/health`'s `serverId` on a learned address
-**before** sending their bearer token to it — a re-assigned LAN address may now
-belong to a different machine.
-
-## Two implementations, kept in sync
-
-The E2EE and framing logic exists twice: TypeScript in `packages/ui/src/lib/relay/` (shared by the client and the normative reference) and a JavaScript mirror in this module (the host, which is plain JS ESM). They **must stay byte-compatible** — a client encrypted by one must decrypt on the other. A cross-compatibility test (`cross-compat.test.js`) imports the TS modules directly and exercises a full TS-client ↔ JS-host exchange. Any change to the wire format, frame codec, handshake, or batching must update both sides and keep that test green.
-
-## Runtime integration (client)
-
-Relay mode plugs into the existing client transport layer rather than a parallel path: `runtime-switch` activates the tunnel singleton, `runtime-fetch` routes runtime requests through it, `runtime-url`/`runtime-socket` yield tunnel-backed URLs and sockets, and `runtime-auth` mints the URL-scoped token through the tunnel. Direct-URL connections and the Electron realtime-proxy path are unaffected.
-
-## Design invariants (do not regress)
-
-- The relay never sees plaintext application traffic; it sees only routing metadata (routing id, connection identifiers, timestamps, coarse counts).
-- Pairing secrets travel in URL fragments only, never in query strings, never logged.
-- The host dispatcher never injects credentials; the server authenticates each tunneled request.
-- The tunnel is transparent to the app: adding relay support to a feature should not require the feature to know the relay exists — it goes through the shared runtime transport helpers.
-- The two implementations stay byte-compatible and the wire format is versioned/negotiated so mixed client/host app versions degrade gracefully rather than break.
-
-For the operational rules that keep future changes (new WebSocket endpoints, transport refactors, terminal/voice porting) from breaking this, load the `relay-transport` skill.

package/server/lib/scheduled-tasks/DOCUMENTATION.md.bak

@@ -1,182 +0,0 @@
-# Scheduled Tasks module
-
-Server-owned scheduled task runtime and routes for AiWorker-only automation.
-
-## Scope
-
-- Per-project scheduled task persistence is owned by `packages/web/server/lib/projects/project-config.js`.
-- Markdown loop discovery/parsing is owned by `packages/web/server/lib/scheduled-tasks/loops.js`.
-- Runtime orchestration and execution is owned by `packages/web/server/lib/scheduled-tasks/runtime.js`.
-- This module is AiWorker feature logic; it is intentionally separate from OpenCode proxy/runtime internals.
-
-## Cross-instance occurrence claiming
-
-Multiple AiWorker server processes can share the same on-disk project config
-(for example CLI `serve` on port 3000 and the Electron desktop server on port
-57123). Each process keeps its own timers, so without coordination a daily (or
-weekly / cron / once) slot would dispatch twice.
-
-Before a **scheduled** run creates a session, the runtime claims the occurrence
-in shared project config under the project write lock:
-
-- Writes `state.lastScheduledFor` to the armed `nextRunAt` timestamp and advances
-  `state.nextRunAt` to the following occurrence.
-- A second instance that loses the claim skips session creation and reschedules
-  from the winner's persisted `nextRunAt`.
-- Project config writes also take a cross-process `.json.lock` file so the
-  read-modify-write is serialized across processes, not only within one process.
-- The sharing processes may run different AiWorker versions. Normalization
-  keeps only the fields a build knows, so every writer persists tasks it did
-  not change verbatim from disk and swaps only `state` onto a task whose state
-  it updated; a task goes out normalized only when it was deliberately
-  replaced (upsert, loop adoption). An older server touching the file after a
-  run therefore cannot strip fields a newer build added, such as a task's goal
-  or auto-accept settings.
-- Lock timeout / filesystem errors on claim, manual-start, or completion state
-  writes always release the in-process running slot (via `finally`) and best-effort
-  re-arm the **next future** occurrence; they must not leave the task permanently
-  "running" or reject unhandled from the queue pump.
-- Project write locks release the in-process promise chain even when
-  `acquireProjectFileLock` times out, so a later write for the same project can
-  proceed after the on-disk lock is cleared (a hung chain would permanently wedge
-  every mutating API and strand `runTask` before its `finally`).
-- Re-arm helpers only schedule a persisted `nextRunAt` when it is still in the
-  future. A past slot (common for `once` after claim, which cannot advance
-  `nextRunAt`) falls back to `computeNextRunAt` — which returns null for a
-  consumed/past once occurrence — so a losing instance stops instead of
-  spinning delay-0 timers against the project lock.
-- On claim lock/fs failure, best-effort persist `lastStatus: error` + `lastError`
-  when nobody else claimed the occurrence, so a past `once` task is not left
-  enabled-but-inert with only a warn log. Recurring schedules still re-arm the
-  next slot.
-- On completion-write failure after a session already ran, in-memory status is
-  set to a terminal value and a single persist retry is attempted so
-  `lastStatus` does not stay `running`. Manual `runNow` still returns the
-  `sessionID` as a successful dispatch (`ok` follows run status, with
-  `persistError` set) rather than a hard 500; the run API and Scheduled Tasks
-  UI surface `persistError` as a warning toast.
-- The claim predicate rejects a duplicate solely via `lastScheduledFor` within
-  slack of this occurrence. It does not consult advanced on-disk `nextRunAt`
-  (that field is routinely overwritten by a second instance syncing inside
-  `TASK_DUE_SLACK_MS`, including on later days when `lastScheduledFor` is already
-  set from a prior claim).
-- Claiming always writes `nextRunAt` (including `undefined`) so a past once-slot
-  is cleared when there is no following occurrence.
-
-Manual `runNow` does not claim a schedule occurrence.
-
-## Files
-
-- `packages/web/server/lib/scheduled-tasks/runtime.js`
-  - Next-run computation (daily/weekly/cron compatibility)
-  - Timer scheduling and queueing
-  - Concurrency controls
-  - Session create + prompt_async execution
-  - Emits AiWorker task-run events
-
-- `packages/web/server/lib/scheduled-tasks/loops.js`
-  - Discovery of `.agents/loops/*.md` (project scope, ancestors up to the worktree root) and `~/.agents/loops/*.md` (user scope)
-  - Frontmatter parsing into scheduled-task definitions
-  - `syncProject` reconciles discovered loops with the persisted task list on every project sync (startup, task list load, task save/delete)
-
-- `packages/web/server/lib/scheduled-tasks/routes.js`
-  - Scheduled task CRUD endpoints
-  - Listing tasks reconciles loop files first, so opening the Scheduled Tasks UI discovers file additions, edits, and removals without a server restart
-  - Loop-file endpoints toggle `enabled` in frontmatter or delete the authoritative markdown file, then reconcile the project
-  - Manual run endpoint
-  - AiWorker events SSE stream endpoint
-
-## Loop file format
-
-Portable, git-commit-able scheduled-task definitions:
-
-```markdown
----
-name: daily-digest
-schedule: "0 9 * * *"
-enabled: true
-model: anthropic/claude-sonnet-4-5
-agent: plan
-timezone: Europe/Kyiv
----
-Summarize repository changes since yesterday.
-```
-
-Field mapping (model: `packages/ui/src/lib/scheduledTasksApi.ts`):
-
-| Frontmatter | Task field |
-|---|---|
-| `name` | `name` (required, max 80 characters — longer names are rejected as malformed) |
-| `schedule` | `schedule.kind: "cron"` + `schedule.cron` (required, cron-only in the portable format) |
-| `enabled` | `enabled` (default `false` — a loop only runs when the file explicitly enables it; add `enabled: true` to activate) |
-| `model` | split on the first `/` into `execution.providerID` / `execution.modelID` (required) |
-| `agent` | `execution.agent` (optional) |
-| `timezone` | `schedule.timezone` (optional, IANA; defaults to the server zone) |
-| body | `execution.prompt` (required) |
-
-`thinking_level` and `goalEnabled`/`goalTokenBudget` are not part of the portable
-format (UI/JSON-only today); `daily`/`weekly`/`once` schedules remain UI/JSON-only.
-Runtime state (`lastRunAt`, `nextRunAt`, `lastStatus`, `lastError`, `lastSessionId`,
-`lastDurationMs`) is never written to the markdown file — it continues to live in
-the project config state store.
-
-## Loop reconciliation rules
-
-`projectConfigRuntime.reconcileLoopTasks(projectID, loops)` runs inside the
-project write lock on every `syncProject` when the project path is known:
-
-- **Identity.** For loop-owned tasks (carrying the `loopFile` marker) identity
-  is the loop file path: a loop takes its task over regardless of the task's
-  current name, so renaming the loop (the `name` field, or a UI rename) renames
-  the task in place instead of leaving a stale duplicate behind. A loop whose
-  name matches a JSON task (no `loopFile`) takes that task over instead: its
-  schedule/execution/enabled are overwritten from the file while the task's
-  `id` and runtime `state` are preserved (markdown wins on conflict).
-- **UI-only fields survive adoption.** Execution fields the file format does
-  not define (`goalEnabled`, `goalTokenBudget`, `permissionAutoAccept`,
-  `variant`) are preserved from the task when a loop adopts it; only fields the
-  file defines are re-applied.
-- **Deletion.** A task carrying the `loopFile` marker whose loop file is no
-  longer discovered (removed or renamed) is unscheduled (removed from the
-  config). The marker is persisted in the config file, so removal is detected
-  across restarts. JSON-configured tasks without the marker are never removed.
-  A task whose loop file still exists but is currently unparseable is KEPT with
-  its last good definition — a transiently malformed file (mid-edit, bad merge)
-  never deletes a task or its runtime state.
-- **Creation.** Loops without a matching task are created under a deterministic
-  `loop:<scope>:<name>` id so runtime state survives restarts. At most one task
-  is driven per loop file; orphan duplicates of the same file are unscheduled.
-- **Scope precedence.** Project-scope loops shadow user-scope loops with the
-  same name; among project files the nearest ancestor wins.
-- **Malformed files** (missing `name`/`schedule`/`model`/body, invalid cron,
-  unreadable) are reported to the scheduler as `definition: null` entries and
-  warned about; they never block valid loops in the same or other scopes.
-- **Loop-file mutations.** The loop file remains authoritative. The scheduled-
-  tasks UI opens it in the built-in file editor, updates its `enabled`
-  frontmatter through the loop-file endpoint, and deletes the file through the
-  loop-file endpoint after confirmation. Each mutation reconciles the project.
-  The general task deletion API still rejects loop-sourced tasks while their
-  file exists; once the file is gone, deleting an orphan task is allowed.
-
-## Public exports (runtime.js)
-
-- `createScheduledTasksRuntime(dependencies)`
-- Returned API:
-  - `start()`
-  - `stop()`
-  - `syncAllProjects()`
-  - `syncProject(projectId)`
-  - `runNow(projectId, taskId)`
-
-## Public exports (routes.js)
-
-- `registerScheduledTaskRoutes(app, dependencies)`
-- Registers:
-  - `GET /api/projects/:projectId/scheduled-tasks`
-  - `PUT /api/projects/:projectId/scheduled-tasks`
-  - `DELETE /api/projects/:projectId/scheduled-tasks/:taskId`
-  - `PATCH /api/projects/:projectId/scheduled-tasks/:taskId/loop-file`
-  - `DELETE /api/projects/:projectId/scheduled-tasks/:taskId/loop-file`
-  - `POST /api/projects/:projectId/scheduled-tasks/:taskId/run`
-  - `GET /api/openchamber/scheduled-tasks/status`
-  - `GET /api/openchamber/events`