CoWorker Hub — Self-Hosted AI Coworker Platform

CoWorker Hub — Self-Hosted AI Coworker Platform #

Product specification, version 1.0

CoWorker Hub is a self-hosted platform for running persistent AI coworkers inside a company's own infrastructure. Each coworker is a durable profile with a name, a title and a standing role, and each gets a computer of its own: a real Chromium browser with its own logins, a file workspace, and a shell. Coworkers hold conversations in durable channels, coordinate with one another through group channels and structured handoffs, learn a task from a single human demonstration and replay it later, and remember what they are told.

Every action a coworker takes — every click, keystroke, file write, shell command, MCP call and connector request — passes through a single Action Gateway that decides it before it happens and records it after. Nothing runs because a model asked nicely: capability comes from explicit grants and policy rules, the gateway denies by default, and it fails closed. Payments, messages that leave the company, and data deletion stop and wait for a named human. A person can take the keyboard at any moment, and while they hold it the coworker's own actions are refused rather than queued.

This document specifies that system completely enough for an AI agent or an engineering team to build it without asking clarifying questions. It is written for a single company deploying internally: there is no multi-tenancy, no billing, and no bring-your-own-agent framework. Every decision is made, every default is stated, and every concern has exactly one canonical section that the others reference by number.

Table of Contents #

1. Before You Start
2. Project Overview & Vision
3. Glossary & Core Concepts
4. Technology Stack & Architecture
5. Repository Layout & Code Conventions
6. Data Model & Database Schema
7. API Design & Conventions
8. Authentication, Identity & Role-Based Access Control
9. Coworker Profiles & Standing Roles
10. Channels, Conversations & Messaging
11. Agent Runtime & Orchestration Engine
12. The Computer: Container Lifecycle & Isolation
13. Browser Control Subsystem
14. File Workspace Subsystem
15. Shell Execution Subsystem
16. Action Gateway & Policy Engine
17. Approval Gates & Human Takeover
18. Live Screen Streaming & Activity Monitoring
19. Learn-by-Demonstration & Routines
20. Multi-Coworker Coordination & Handoffs
21. Memory, Preferences & Knowledge Retrieval
22. Skills Library
23. Integrations: Gmail, Outlook, Slack, Google Drive
24. MCP Connector Framework
25. Credential Vault & Secrets Management
26. Audit Trail & Compliance
27. Admin Console
28. Web Application: Design System & Component Architecture
29. Notifications & Scheduling
30. Observability, Logging & Metrics
31. Security & Privacy
32. Performance, Scale & Capacity Planning
33. Deployment, Configuration & Operations
34. Backup, Restore & Disaster Recovery
35. Testing Strategy & Quality Assurance
36. Milestones & Execution Plan
37. Executor Instructions

1. Before You Start #

This section exists so that an engineer — or an AI coding agent — can begin implementation without asking anyone a single question. It lists every real deployment decision, states the concrete default that ships, and points at the section that consumes the answer.

Every variable named below is defined in full — type, required/optional, example, consuming services — in the environment-variable catalogue in Section 33. That catalogue is the single source of truth for configuration; this section only tells you which knobs matter and what happens if you leave them alone. Where a name here and a name there could ever disagree, Section 33 wins, and its superseded-name table records every older spelling the boot validator refuses.

1.1 The Customization Questionnaire #

Twenty questions. Answer them into .env before the first docker compose up. Sixteen have a working default. Four do not and cannot — a hostname, a model API key, an embedding model, and a first administrator — because no default can invent them, and the deployment refuses to start without them rather than starting in a degraded shape nobody notices.

1.2 Expanded Notes on the Answers That Bite #

Q1/Q2 — Model provider and models. anthropic and openai are the two shipped implementations of the internal ModelProvider interface defined in Section 4.7. A third value, stub, exists only for the deterministic test harness and is refused when CWH_ENV=production. The choice is a deploy-time configuration value, not a plug-in architecture: the agent loop, the tool catalogue, the prompts, and the gateway are all ours in every case. Switching providers on an existing deployment requires only a restart of orchestrator — no migration, no data change — as long as you do not also change the embedding model, which is a different matter entirely.

Embeddings are required, not optional, and there is no degraded mode. CWH_MODEL_EMBEDDING names a model on the configured provider; there is no separate embedding provider and no separate embedding key. It must emit exactly 1536 dimensions, because the schema columns are vector(1536) (Section 6), and the assertion is explicit in CWH_MODEL_EMBEDDING_DIMENSIONS, whose only permitted value is 1536. A missing, unknown, or wrong-width embedding model is a hard boot failure with the configuration-error exit code, never a warning, never a fallback to lexical search. This is deliberate and it is the more restrictive choice: a self-hosted deployment that quietly loses semantic retrieval is worse than one that refuses to start, because nobody notices the first until the answers have been wrong for a month. Changing the embedding model on a populated deployment also fails at boot, naming the re-embedding job you must run first — vectors from two embedding models are not comparable, and mixing them is silent nonsense rather than a visible error.

Q3/Q4 — Identity. There is no local username-and-password login path in a production build. This is deliberate: it removes password storage, password reset, and credential-stuffing from the threat model entirely. A single-user development mode exists for local work and is refused at boot when CWH_ENV=production. A break-glass local administrator can be enabled for the case where the identity provider is the outage; it is off by default, rate-limited, alerted on every use, and its sessions expire in 30 minutes with no renewal. SAML and generic OIDC both support group-to-role mapping so an existing directory group can drive who is an admin or a lead. Details in Section 8.

Q5 — Hostname and TLS. Two variables, not one, and they are split deliberately: CWH_PUBLIC_URL carries the origin the application builds OAuth redirect URIs and email links from, and CWH_HOSTNAME carries the bare name Caddy serves a certificate for. They must agree, and boot validation checks that they do. Three certificate modes: acme is the default and needs ports 80 and 443 reachable for the challenge; internal issues from Caddy's local CA, which is right for a deployment reachable only on a corporate network; custom takes a certificate and key you provide, which is the air-gapped path. Changing the hostname after first boot invalidates every existing session cookie; users simply sign in again.

Q6 — Database. bundled runs PostgreSQL 18 with the pgvector extension in the Compose stack on a named volume. external expects a CWH_DATABASE_URL pointing at a PostgreSQL 18 instance where pgvector is already installed or the application role can CREATE EXTENSION. Boot-time validation checks the server version and the extension and refuses to start on a mismatch, because a silent failure here surfaces three weeks later as broken memory retrieval.

Q8/Q9 — Computers. The concurrency cap is a semaphore held by supervisor, not a hint. When all slots are taken, a run that needs a computer waits in queued and reports its position in the channel rather than failing; when the host itself has no room, the supervisor refuses with COMPUTER_CAPACITY_EXHAUSTED and reports itself not ready rather than filling the disk. Cold start is the container create-plus-Chromium-launch path, budgeted at under 20 seconds at p95; warm resume of an idle computer is budgeted at under 3 seconds (Section 32). Idle computers are frozen first and stopped later, on the two-tier ladder Section 12 owns; both are the warm path. gVisor costs roughly 10–20% CPU on browser workloads. Pay it.

Q11 — Approvals. Expiry is not neutral. An expired approval request resolves the underlying action to denied, and the run continues down its failure branch — it does not hang, and it does not retry the action. This follows the fail-closed rule in Section 16. The escalation ladder is owner → owner's team lead → any admin, a requester may never authorise their own request, and a user may never approve an action for a coworker they neither own nor lead. An admin always can, except when the admin is the requester.

Q13 — Egress. The allowlist is enforced by egress-proxy, a service of its own in the Compose file. The computer network is a Docker internal network with no default route, so the proxy is not defence in depth — it is the only route out, and a coworker container cannot reach the network without it. The allowlist is matched on hostname with single-level wildcard support (*.example.com); a bare * is refused, because "allow everything" is a mode you acknowledge, not a pattern you type. The proxy resolves the name, re-checks every resulting address, and pins the connection to the address it checked, across each of at most three redirects, which is what closes DNS rebinding. RFC 1918, loopback, link-local, CGNAT, and unique-local ranges are blocked unconditionally in both modes and refused false in production; this is what stops a coworker from being talked into fetching http://169.254.169.254/.

Q16 — Retention versus the audit trail. These are different things and conflating them is a mistake. Application logs are operational telemetry and roll off on a schedule — and the size cap bites long before the age cap does, so a deployment that needs days of history ships logs off-host. Run-payload free-text fields — the prompt text, the tool arguments, the extracted page content — are nulled on a schedule because they are bulky and sensitive; a reduced snapshot of a few hundred bytes is kept indefinitely, because it is the only input to the tools that explain a decision after the fact. The audit_events table is neither of those: it is append-only, the application database role has no UPDATE or DELETE grant on it, and there is no code path, admin action, or configuration value that removes a row. Old partitions are archived and detached by a dedicated role after their contents are exported and checksummed; they are never simply dropped. See Sections 6, 26 and 34.

Q19 — The audit anchor. The audit trail is hash-chained, and a chain verifies against itself. That proves nothing against an attacker who has the database, because they can recompute it. The anchor is the independent witness: every five minutes, and immediately on any critical event, the chain head is published somewhere off this host. Five minutes rather than hourly, because the anchor interval is exactly the window in which a rewrite is undetectable. A deployment with CWH_ENV=production and no anchor refuses to start, because without one the tamper-evidence claim is not true as deployed.

1.3 The Smallest Real Answer Set #

There is no "answer nothing" path, and a document that promised one would be lying to you at the first boot. Setting five values and taking every other default is the smallest configuration that produces a working, safe deployment:

CWH_PUBLIC_URL / CWH_HOSTNAME        the name people type
CWH_MODEL_API_KEY                    the one model key, for the selected provider
CWH_MODEL_PRIMARY                    the reasoning model id
CWH_MODEL_EMBEDDING                  the 1536-dimension embedding model id
CWH_AUTH_ADMIN_BOOTSTRAP_EMAIL       the first administrator

Plus the secrets that ./scripts/generate-secrets.sh writes for you in Section 33.6.4 — the root encryption key, the session secret, the audit fingerprint key, the supervisor token, and the two database passwords — and, before you set CWH_ENV=production, the audit anchor of Q19 and the egress allowlist of Q13.

Here is precisely what that gives you: a single-host Docker Compose deployment on four networks behind Caddy with an automatically issued public TLS certificate; a bundled PostgreSQL 18 with pgvector and a bundled Valkey; Anthropic Claude as the reasoning engine with semantic memory and knowledge retrieval fully working, because the embedding model is not optional; Google Workspace sign-in restricted to the domain of your bootstrap admin address, with you as the only admin and everyone else landing as an employee; three seeded coworkers — General Assistant, Knowledge, and Risk Analyst — visible to the whole org; up to fifty concurrent coworker computers, each with a 10 GB workspace quota, running under runc with a startup warning and an admin-console banner because your host almost certainly does not have gVisor installed; deny-by-default egress from those computers through egress-proxy to the hosts you listed and nothing else; live screen streaming at 5 fps with no frames persisted anywhere; the seeded policy rule set gating the three sensitive categories — payments and financial commitment, external messages, and data deletion — and everything else either allowed with full audit logging or, if no rule matches it, refused; approvals escalating to a team lead after 30 minutes and denying after 24 hours; in-app notifications only, because no relay is configured, with a banner in the admin console telling you that; nightly age-encrypted backups to a local path on the same disk, which is better than nothing and worse than off-host; 14-day rotated logs, 30-day run-payload text, and an audit trail that keeps everything forever.

That configuration is safe to put in front of real employees. It is not yet what you want for a regulated workload: fix the off-host audit anchor, fix gVisor, fix off-host backups, and fix a notification relay, in that order.

1.4 Fifteen-Minute Quick Start #

Prerequisites: a Linux host with kernel 5.15+, Docker Engine 27+ and the Compose v2 plugin, unprivileged user namespaces enabled, 12 vCPU / 32 GB RAM / 512 GB SSD for the small tier, ports 80 and 443 reachable, a DNS A record already pointing at the host, and git, openssl, curl, jq and age installed. The full first-run procedure — including the preflight report, the air-gapped path, and the internal-CA path — is Section 33.6. This is the same procedure, compressed.

# 1 — Get the code and check the host (≈1 min)
git clone https://github.com/your-org/coworker-hub.git /opt/coworker-hub
cd /opt/coworker-hub
./scripts/preflight.sh
#   Reports [ok]/[warn]/[fail] per check and exits non-zero on any [fail].
#   It never modifies the host. A [warn] about gVisor or AppArmor is acceptable;
#   a [fail] on user namespaces is not — Chromium's sandbox depends on them.

# 2 — Create the config and the host state directory (≈1 min)
cp .env.example .env
chmod 600 .env
sudo mkdir -p /var/lib/coworker-hub/{workspaces,profiles,backups,run/computers}
sudo chown -R 10001:10001 /var/lib/coworker-hub

# 3 — Answer the questions that have no default (≈3 min)
$EDITOR .env
#   CWH_ENV=production
#   CWH_PUBLIC_URL=https://hub.example.com
#   CWH_HOSTNAME=hub.example.com
#   CWH_HOST_STATE_DIR=/var/lib/coworker-hub
#   CWH_DOCKER_GID=$(getent group docker | cut -d: -f3)
#   CWH_AUTH_PROVIDERS=google
#   CWH_GOOGLE_CLIENT_ID=...            (redirect URI https://hub.example.com/api/v1/auth/callback)
#   CWH_AUTH_ALLOWED_EMAIL_DOMAINS=example.com
#   CWH_AUTH_ADMIN_BOOTSTRAP_EMAIL=you@example.com
#   CWH_MODEL_PROVIDER=anthropic
#   CWH_MODEL_PRIMARY=<the provider's current flagship reasoning model id>
#   CWH_MODEL_EMBEDDING=<the provider's current 1536-dimension embedding model id>
#   CWH_EGRESS_ALLOWED_HOSTS=example.com,*.example.com
#   CWH_TLS_MODE=acme
#   CWH_ACME_EMAIL=it-ops@example.com
#   CWH_AUDIT_ANCHOR_URL=https://anchor.example.com/cwh
# Secret VALUES do not go in .env — step 4 writes them to ./secrets/, and Compose
# delivers each only to the services whose role needs it.

# 4 — Generate every secret in one command (≈10 s)
./scripts/generate-secrets.sh --env-file .env --secrets-dir ./secrets
#   Writes secrets/{postgres_password,redis_password,session_secret,
#   key_encryption_key,audit_fingerprint_key,supervisor_token} at mode 0600,
#   creates the age backup identity, and fills CWH_BACKUP_ENCRYPTION_RECIPIENT.
#
#   ▲ MOVE secrets/backup-identity.txt OFF THIS HOST NOW, and BACK UP
#     secrets/key_encryption_key OFF THIS HOST NOW. The key file is the root of
#     the envelope-encryption scheme; if the host dies and the key died with it,
#     every stored credential is permanently unrecoverable. There is no escrow
#     and no recovery path. Put both in the company password manager first.
#
#   .env.example ships a PUBLISHED DEVELOPMENT KEY so a developer can start the
#   stack with one command. It is exactly 32 bytes so it passes the same
#   validator a real key passes, and its digest is on a blocklist: any
#   deployment with CWH_ENV set to staging or production refuses to boot while
#   it is in place. It is published in this document and provides no
#   confidentiality whatsoever.

# 5 — Pull the images (≈5 min on a cold host)
docker compose pull
docker compose --profile images pull
#   api, orchestrator, supervisor, egress-proxy and migrate share one image.
#   The computer image is ~2.1 GB because it carries Chromium and Playwright.

# 6 — Start the data tier and apply the schema (≈1 min)
docker compose up -d postgres valkey
docker compose run --rm migrate
#   expect the final line: "complete","applied":42,"skipped":0,"schema_version":42
cwh policy:verify
#   expect: the complete seeded rule set is present and enabled, all expressions
#           compile, and deny-by-default is confirmed against an unmatched action.

# 7 — Start everything (≈1 min)
docker compose up -d
docker compose ps
#   migrate and web showing "Exited (0)" is correct — both are one-shot.
#   Any other exit code is a failure; read the logs before continuing.

# 8 — Confirm the stack is healthy (≈30 s)
curl -fsS https://hub.example.com/api/v1/health | jq
#   expect: {"status":"ok","db":"ok","queue":"ok","supervisor":"ok",
#            "model_provider":"ok","migrations":42}
cwh doctor
#   The fuller self-test: configuration, database grants, queue, supervisor,
#   egress, model provider (including "embedding model returned 1536
#   dimensions"), policy engine, audit chain and anchor, TLS, backup.

# 9 — Sign in (≈1 min)
#   Open https://hub.example.com and complete sign-in as
#   CWH_AUTH_ADMIN_BOOTSTRAP_EMAIL. You are promoted to admin, once. Any other
#   address is refused during that window rather than silently provisioned.
#   Then remove the variable — it has done its job:
#     sed -i '/^CWH_AUTH_ADMIN_BOOTSTRAP_EMAIL=/d' .env
#     docker compose up -d --force-recreate api

# 10 — Start a coworker and give it work (≈3 min)
#   In the UI: Coworkers → "General Assistant" → Start computer.
#   Watch the state go stopped → starting → ready (< 20 s).
#   Open its direct channel and send:
#     "Open example.com and tell me the exact text of the first heading."
#   Expect: a run appears in the Activity tab, the Screen tab shows the page
#   loading live, and the coworker replies with the heading text. Every browser
#   action it took is in Admin → Audit as a separate allow decision. If it is
#   refused with EGRESS_BLOCKED, example.com is simply not in
#   CWH_EGRESS_ALLOWED_HOSTS — that is the allowlist working.
#
#   Then confirm the governance path is live:
#     "Email supplier@example.org and tell them we accept the quote."
#   Expect the run to pause in waiting_approval with a card in /approvals.

GET /api/v1/health is the aggregate application health document, it is always JSON, and it is what every runbook uses. /healthz and /readyz are the container probes and are deliberately different things (Section 7.17.2). If step 8 returns anything other than ok for all five dependency keys, stop and read the runbook in Section 33 rather than restarting the stack; each sub-check maps to a specific named failure.

2. Project Overview & Vision #

2.1 What CoWorker Hub Is #

CoWorker Hub is a self-hosted platform for AI coworkers: durable, named, role-shaped teammates that live in your company's chat channels, each with its own virtual computer — a real browser, a real file workspace, a real shell — and every consequential action they take passing through a policy gateway that can allow it, refuse it, or stop and ask a human first.

It is an internal tool. One company, one deployment, running on your infrastructure under Docker Compose. It is a web application. It is not multi-tenant, it is not a marketplace, and it is not a framework you bring your own agents to.

The one-line version: self-hosted AI coworkers with their own virtual computer, team coordination, and human-gated actions, built for internal company use.

2.2 The Problem #

Companies want AI teammates that can operate the software humans operate. Not a chatbot that summarizes a document — a colleague that opens the supplier portal, downloads the statement, opens the accounting system, matches the lines, and tells you the three that do not reconcile.

Every existing route to that is unacceptable for a company with data it cares about:

• A third-party subscription bot means your invoices, contracts, customer records, and internal chat go to somebody else's servers under somebody else's retention policy, with a governance model you did not write and cannot inspect.
• An unmodified open-source agent framework gives you a loop and a tool list and leaves the hard parts — identity, approvals, audit, credential handling, isolation, multi-agent safety — as an exercise for the reader. Those are exactly the parts that make it safe to point at a production system.
• Building from scratch means six months before the first useful run.

The gap is not intelligence. Models are good enough. The gap is governance and operability: who is allowed to do what, who approved it, what exactly happened, how do I stop it, and how do I prove any of that afterwards.

2.3 Why Self-Hosted Is the Point, Not a Feature #

Self-hosting here is not a deployment preference. It is the property that makes the rest defensible.

1. Company data never leaves company infrastructure, with exactly one auditable exception: the model provider API call, which is configurable, region-pinnable, and the only outbound dependency the product has. Files, screen frames, chat history, credentials, and the audit trail never move.
2. Credentials stay in your vault. A coworker asks the vault for a credential by name; the vault injects the value directly into the browser field or the process environment. The value never enters the model context, the transcript, a log line, or an API response.
3. The audit trail is yours. It lives in your database in its own schema under its own owner role, the application role has no UPDATE or DELETE grant on it, and its chain head is witnessed off-host so that nobody — including us, including your own admins, including someone with root on the box — can rewrite it undetectably.
4. Isolation is physical, not contractual. A coworker's computer is a container on your host, optionally under a user-space kernel, on a network with no default route and no way out except a proxy you configured.
5. The kill switch is local. Stopping a coworker is docker stop. There is no vendor to call.

2.4 The Three Roles #

Fixed, code-level roles: employee, lead, admin. Every human is exactly one of them (Section 8 owns the permission matrix).

2.5 End-to-End User Stories #

Each story is a real path through the product with binding acceptance criteria. These are the scenarios the E2E suite in Section 35 must cover.

US-1 — Ops employee hands invoice reconciliation to a coworker #

As an ops employee, I hand a monthly reconciliation to my coworker and get back a list of exceptions, so that I only look at the lines that actually disagree.

• Given I own a coworker with the standing role "Accounts Ops" whose computer is ready, when I post "Reconcile the August supplier statements against the ledger and list anything that doesn't match" in our direct channel, then the message is persisted and a run is created in state queued in one transaction, the endpoint returns 202 with the run id, and the run transitions to planning and then acting.
• The coworker requests the supplier-portal credential by name from the vault; the transcript records the credential name, the requesting coworker, the target host, and the value's character length — and never the value.
• Downloading statements and writing them to /workspace produces file.write actions that are allowed and audited; the Activity tab shows path and byte size for each, never contents.
• When the coworker finishes, then it posts a message listing each exception with the statement line, the ledger line, and the delta, and the run ends in succeeded.
• When I open the Activity tab, then every browser navigation, click, file write, and shell command appears in order with its policy decision and duration.
• The run completes within its wall-clock budget or ends failed with RUN_BUDGET_EXCEEDED, details.budget = "wall_clock", and a partial-results message. It never hangs. Time spent waiting on a human or on an operator hold does not count against that budget.

US-2 — Team lead approves an outbound email #

As a team lead, I approve the email my team's coworker drafted before it reaches a customer, so that nothing goes out unreviewed.

• Given a coworker owned by an employee on my team has drafted a customer email, when it calls the connector send tool, then the connector computes the audience's external reach server-side, the Action Gateway matches the seeded external-messages rule, the effect is require_approval, the action is not executed, the run moves to waiting_approval, and an approval_requests row is created in pending.
• When the same email is addressed only to colleagues inside the company, then it is allowed with audit rather than gated. Sending is conditional on computed reach, not on being email; a gate that fires forty times a day is a gate people learn to click through.
• When the audience cannot be resolved at all — an unexpandable group, a failed directory lookup — then the call is refused with CONNECTOR_REACH_UNDETERMINED rather than guessed in either direction, and no approval request is created, because there is no recipient list to put in front of an approver.
• Then the owner is notified first. When 30 minutes pass with no decision, then it escalates to me and I am notified.
• When I open the request, then I see the coworker, the run, every recipient address inline with the external ones badged, the subject, the full body, the rule that triggered it, and the requesting employee — enough to decide without leaving the screen. The recipient list is never collapsed to a count.
• When I approve, then the action executes exactly once, the run resumes from the same step, and approval.granted plus action.executed are written to the audit trail with my user id.
• When I deny with a reason, then the action is never executed, the reason is returned to the model as the tool result, and the run continues on its failure branch.
• When neither happens for 24 hours, then the request expires, which resolves the action as denied, and the run resumes on its failure branch with APPROVAL_TIMEOUT recorded. Expiry is never "allow".
• I cannot approve for a coworker outside my team; the API returns 403 NOT_APPROVER. If I were the one who asked for the email, I could not approve it either; that is 403 SELF_AUTHORISATION_REFUSED.

US-3 — Admin investigates a refused action #

As an admin, I find out exactly why a coworker was stopped, so that I can fix the rule or confirm the refusal was right.

• Given an employee reports "my coworker said it isn't allowed to do that", when I open Admin → Audit and filter by that coworker and the last hour, then I find an action.denied event.
• Then the event shows the action kind, the full intent string, the CEL evaluation context that was presented, the rule_id and rule expression that matched, the effect, and the run and step it belonged to.
• When no rule matched at all, then the event records reason: "no_matching_rule" and shows the deny-by-default outcome, so "nothing matched" and "something denied it" are never confused.
• When I edit the rule, then I must supply a justification string — a blank one is REASON_REQUIRED — and policy.rule_updated records the before and after expressions, my user id, and that justification.
• Then the previous version of the rule remains readable in the audit trail forever.
• When I attempt to delete the audit event through any interface, then there is no such interface: there is no POST, PATCH, or DELETE anywhere under the audit endpoints, and a direct database DELETE fails on a missing grant — on the parent and on every partition.

US-4 — Employee takes over at a login wall #

As an employee, I take the keyboard when my coworker hits a 2FA prompt, get it past, and hand control back, so that a login wall does not kill a two-hour job.

• Given my coworker's run reaches a page requiring a one-time code, when it calls ask_human with a help_requested reason, then the computer moves to human_control, the run moves to waiting_human, computer.help_requested is audited, and I am notified in-channel.
• When I click Take Control, then the Screen tab becomes interactive within 1 second, my keyboard and mouse events reach the container, and computer.control_taken records my user id and a start timestamp.
• While I hold control, then every coworker-initiated action is refused, not queued, and the gateway returns HTTP 423 with error code HUMAN_HAS_CONTROL. Every action token minted before the takeover is void, and one presented afterwards is refused with ACTION_TOKEN_EPOCH_STALE.
• When I type the one-time code, then it appears in the audit trail only as a redacted keystroke event with a character count.
• When I release control, then computer.control_released records the duration, the computer returns to busy, and the run resumes from the exact step it paused at.
• When I take control unprompted at any time, mid-action, then the in-flight action either completes or is cancelled with ACTION_CANCELLED, and no new action starts.
• When I stop interacting, then the session auto-releases on the idle timeout, and in no case may one person hold a computer past the configured maximum.

US-5 — Employee teaches a routine by demonstration #

As an employee, I show my coworker a weekly task once and it can repeat it, so that I stop doing it every Monday.

• Given I hold control of my coworker's computer, when I press Record and perform the task — log in, navigate, filter, export, save — then the recorder captures navigations, semantic element descriptors, typed values, waits, and extractions in the coworker's own browser.
• Then values injected by the vault are captured as redacted references, never as literals.
• When I press Stop, then the model induces a parameterised routine — named inputs, per-step assertions, and failure branches — and shows it to me for review.
• Then nothing is saved until I confirm; a save attempt on an unreviewed induction is DEMONSTRATION_NOT_REVIEWED. Review-before-save is mandatory, there is no auto-save path, and abandoning the review discards the induction while keeping the raw demonstration.
• When I edit a step's description or a parameter name and save, then the routine is stored at version: 1 and is immutable at that version.
• When the routine replays and a selector no longer matches, then it tries the semantic descriptor, then the fallback selector chain, then a bounded model-guided repair whose proposal is validated and must resolve to exactly one element and is re-decided by the gateway before it runs, and only then calls ask_human. A proposal that fails validation is ROUTINE_REPAIR_REJECTED and the ladder falls straight through to the human.
• When I correct it during replay, then a new immutable version is created and the previous version remains rollback-able.

US-6 — A group channel splits a launch checklist #

As a team lead, I put three coworkers and two humans in one channel and get coordinated work instead of a stampede.

• Given a group channel with a designated coordinator coworker, when I post the launch checklist, then only the coordinator assigns work. Non-coordinator coworkers act only when @mentioned or assigned, and an attempt by one of them to assign is HANDOFF_NOT_COORDINATOR.
• When I try to change the coordinator without owning or leading every coworker in the channel, then it is refused with CHANNEL_COORDINATOR_FORBIDDEN, naming the ones I do not own.
• When the coordinator issues a handoff.request to a second coworker, then the payload carries goal, context, artifact references, and deadline, and the receiving coworker explicitly accepts or declines with a reason.
• Then the receiving coworker's actions are evaluated under its own identity, grants, and credentials. Nothing is inherited across a handoff — not vault access, not connector accounts, not MCP grants — and a handoff that would only work by inheriting is refused with HANDOFF_WOULD_WIDEN rather than executed with the sender's reach.
• When a handoff chain reaches the configured depth, then the next handoff is refused with HANDOFF_DEPTH_EXCEEDED.
• When coworker A tries to hand back to a coworker already in the chain, then the cycle detector refuses it with HANDOFF_CYCLE_DETECTED.
• When coworker-to-coworker messages in one run reach the cap, then further inter-coworker messaging is refused with COWORKER_MESSAGE_LIMIT and the run reports the cap in-channel.

US-7 — Support employee asks a company question #

As a support employee, I ask the Knowledge coworker a policy question and get a cited answer, so that I do not guess at a customer.

• Given the Knowledge coworker with a retrieval-first standing role, when I ask "what's our refund window for annual plans", then it retrieves from the knowledge corpus by vector similarity with scope filtering applied as a pre-filter on the index scan, not as a filter on the results, before it answers.
• Then the answer cites the source documents it used, each as a resolvable link.
• When retrieval returns nothing above the relevance floor, then it says it does not know and does not answer from parametric memory.
• When I tell it "I always want the EU wording first", then it calls memory.write at user scope, explicitly and visibly — never silently — and the message carries a chip naming how many memories informed the answer.
• When I open Settings → My Memories, then I see every memory about me across every coworker and can delete any of them; deletion is immediate, removes the vector in the same statement, and writes memory.deleted.
• Then a memory written by a coworker owned by someone else, with private visibility, is never visible to my coworkers.
• Then none of this works at all unless an embedding model is configured — and a deployment with none configured never started, so there is no state in which retrieval silently degrades.

US-8 — Admin adds an MCP server #

As an admin, I connect an internal tool over MCP and grant exactly two of its tools to one coworker.

• Given an internal MCP server over streamable HTTP, when I register its URL, then loopback, link-local, and private ranges are refused with MCP_HOST_NOT_ALLOWED unless explicitly listed in CWH_MCP_ALLOWED_HOSTS, a name colliding with a first-class tool namespace is MCP_NAME_RESERVED, and a tool description that reads as instructions to the model rather than as documentation fails registration with MCP_DESCRIPTION_REJECTED.
• When registration succeeds, then the tool list is fetched and every tool is classified read or write; unknown tools and tools from custom servers default to write, and a tool the server itself annotates as destructive cannot be overridden down to read.
• Then no coworker can call any tool until I grant it. Grants are per coworker, per tool.
• When I grant search_tickets (read) and create_ticket (write) to one coworker, then only that coworker sees those two tools, and create_ticket is subject to policy evaluation with mcp.classification == "write" in the context.
• When a different coworker asks for that tool, then it is told the connector exists but is not granted to it — it is not left guessing.
• When the server later changes a tool's schema, description, title or annotations, then calls fail with MCP_TOOL_DEFINITION_CHANGED, every grant covering it is suspended rather than revoked, and accepting the diff restores exactly the grants that existed before.
• Then mcp.server_registered, mcp.tools_classified, and mcp.grant_created are audited with my user id.

2.6 The Fifteen Core Features #

1. Coworker Profiles & Standing Roles. A coworker is a durable, named entity — not a session, not a prompt. It has a name, a title, a role description that becomes the top of its system context, an avatar seed, an owning user, a visibility of private, team, or org, and a status of active, disabled, or hidden. The standing role is what makes a coworker feel like a colleague rather than a fresh chat: it is persistent, versioned, editable by the owner or an admin, and applied to every run the coworker performs, in every channel. It is injected as a job description and cannot widen what the coworker is permitted to do. Coworkers are soft-deleted so that their contributions to channel history remain readable as tombstones. Owned by Section 9.

2. Dedicated Virtual Computer per Coworker. Each coworker gets its own container: Chromium driven by a Playwright server, a persistent /workspace volume, and a shell executor. One container per coworker, never shared — so a browser profile, its cookies, its downloads, and its shell history belong to exactly one identity, and a compromise is bounded to one coworker. The computer has states stopped, starting, ready, busy, human_control, and error, with an idle ladder that freezes and then stops it (Section 12), and it is never reachable from the public network — nor from any network the supervisor's control API sits on. Cold start under 20 seconds, warm resume under 3. Owned by Sections 12–15.

3. Channels & Conversations. Work happens in channels. A direct channel is one human and one coworker; a group channel holds several humans and several coworkers. Messages are durable rows, not an in-memory transcript, so a channel survives an orchestrator restart, a deploy, and a host reboot with its full history and any in-flight run intact. A message body is an ordered array of exactly nine content-block types, of which a person or a coworker may author only the two prose ones. Membership is polymorphic — a member is a user or a coworker, never both. Owned by Section 10.

4. Live Screen & Activity Monitoring. You can watch a coworker work. Chromium screencast frames flow from the container through the supervisor and a dedicated binary WebSocket to a canvas in your browser at 5 fps, JPEG quality 60, capped at 1280×720, with backpressure that drops frames rather than queueing them so latency never accumulates. Frames are not persisted by default because they can contain secrets. The right to watch is re-evaluated for the life of the stream, not only at connect, and a viewer who loses it is disconnected within one tick. Alongside the pixels, the Activity tab shows the semantic record: what was navigated, run, read, and saved, with output — and file saves show path and size, never contents. Owned by Section 18.

5. Learn-by-Demonstration Routines. Show the coworker once. Recording happens in the coworker's own browser during a human control session — you drive, the recorder captures navigations, semantic element descriptors, typed values, waits, and extractions. The model then induces a parameterised routine with named inputs, assertions, and failure branches. You review and edit before anything is saved; nothing auto-saves. Replay is self-healing on a bounded ladder: semantic descriptor, then selector fallback, then a validated model-guided repair that is re-decided by the gateway before it runs, then ask a human. Corrections create a new immutable version. Owned by Section 19.

6. Multi-Coworker Coordination. Several coworkers in one channel, coordinated rather than stampeding. Exactly one coworker per group channel is the designated coordinator and is the only one that may assign work; the others act when @mentioned or assigned. handoff.request moves a task with a structured payload — goal, context, artifacts, deadline — and the receiver accepts or declines with a reason. Loop protection is explicit: a capped chain depth, a cycle detector that refuses A→B→A, and a cap on coworker-to-coworker messages per run. Identity never travels with a handoff, and a handoff that would only work by inheriting the sender's reach is refused outright. Owned by Section 20.

7. Human Takeover & Approval Gates. Two distinct mechanisms with one purpose. Takeover is a human seizing the keyboard — requested by the coworker at a login wall, 2FA prompt, or CAPTCHA, or grabbed by a human unilaterally at any moment; while held, every coworker action is refused with HTTP 423, not queued, and every token minted before the takeover is void. Approval gates pause a specific sensitive action, route it to the right human, and resume the run at the exact step on approval — and never to the person who asked for it. Both are fully audited with actor and duration. Owned by Section 17.

8. Policy & Permissions Engine. Deny by default, fail closed. Every browser, file, shell, MCP, and connector action is evaluated by a CEL rule set against a flat context of the action, the coworker, the actor, the page, the element, the file, the shell command, and the MCP tool. If no rule matches, the action is refused. If a rule fails to compile, times out, or errors, the action is refused — never allowed on error. If the policy store cannot be read at all, the action is refused. Deny rules evaluate before allow rules and a matching deny wins outright. A sensitive category is decided from facts the page cannot author. Three outcomes only: allow, deny, require_approval. Owned by Section 16.

9. Full Audit Trail. Every decision, every action, every admin change, in an append-only table with a gap-free sequence column, living in its own schema under its own owner role. The application role has no UPDATE or DELETE grant on it — on the parent or on any partition. Each event carries actor, subject, run, action, decision, and the evaluation context that produced it — enough to reconstruct not just what happened but why the system believed it was allowed. The chain is hashed, sealed daily, and witnessed off-host every five minutes, so a rewrite by someone with root is detectable rather than merely improbable. Nothing removes a row; archival exports and detaches a partition after its contents are checksummed, and even that is a different role's job. Owned by Section 26.

10. Integrations & Connectors. First-class connectors for Gmail, Outlook, Slack, and Google Drive — read, search, draft, send, files, sharing — all on per-user OAuth, acting as the requesting person, never a shared service account. Whether a send leaves the company is computed by the server from the expanded recipient set, never asserted by the model, and an audience that cannot be resolved is refused rather than guessed. Plus a general MCP framework for everything else, with registered servers, read/write tool classification defaulting to write, and per-coworker grants. Two access paths coexist: prefer the API connector, fall back to the coworker's browser for anything without API coverage — and the browser is never a way to send what the connector would not classify. Owned by Sections 23 and 24.

11. Credential Vault. Envelope-encrypted secrets: a root key wraps per-record data keys, AES-256- GCM. A coworker asks for a credential by name and the vault injects the value directly into the target — typed into the browser field, set as a process environment variable. The credential is bound to a host or a process, and an unbound one cannot be injected at all. The transcript and audit trail record which credential, by whom, for what target, and its character length. Never the value. GET on a credential never returns the value to anyone, including admins. Owned by Section 25.

12. Admin Console. One place for people and roles, computers and their state, policy rules with a test harness and a linter, credentials, connector accounts, MCP servers and grants, the audit trail with filters and export, and deployment settings. Every mutating action in the console writes an audit event with the acting admin's identity, and the destructive ones require a typed confirmation and a stated reason. Owned by Section 27.

13. Memory & Preference Learning. Three scopes: coworker for its own working knowledge, user for preferences about one person, org for shared facts. Memories are written explicitly by the memory.write tool plus a visible end-of-run reflection pass — never silently. Retrieval combines pgvector cosine similarity over a single deployment-wide 1536-dimension embedding space, recency, and scope filtering, top-k of 8 by default. Every user can view and delete every memory about themselves, immediately and audibly. Memory is never shared across private coworkers owned by different people. Owned by Section 21.

14. Skills Library. Reusable prompt and task templates at personal or org scope, with typed parameters, so that "do the weekly board summary" is a first-class object with a name, an owner, and a version rather than a paragraph somebody keeps re-pasting. A parameter marked secret is persisted nowhere — not in the message, not in the invocation row, not in the audit payload. Skills compose with routines: a skill describes intent, a routine executes deterministic steps. Owned by Section 22.

15. Company Login & Role-Based Access. Google, Microsoft, generic OIDC, and SAML 2.0. No local passwords in production, and one narrow, alerted, time-boxed break-glass account for the case where the identity provider is itself the outage. Group-to-role mapping so that your directory drives who is admin, lead, or employee — but the users table, not the provider, is the source of truth. Session cookies are HttpOnly, Secure, SameSite=Lax, rotated on privilege change, and a cookie alone never opens a WebSocket. Owned by Section 8.

2.7 Non-Goals #

Stated so that nobody spends a sprint on them.

2.8 Definition of Done for v1 #

v1 ships when every one of these is true and demonstrated on a clean host, not on a developer laptop.

1. A clean host goes from git clone to a signed-in admin in under 15 minutes following Section 33, with ./scripts/preflight.sh passing and cwh doctor reporting no failures.
2. All four identity providers — Google, Microsoft, generic OIDC, SAML — complete a sign-in against a real IdP, and group-to-role mapping is verified for at least one.
3. The three roles enforce the full permission matrix in Section 8, verified by an automated test per cell, including the negative cells, and every route named in that matrix exists in the endpoint catalogue of Section 7 — checked by a generated test in both directions, not by reading.
4. A coworker computer cold-starts in under 20 seconds and warm-resumes in under 3, at the large tier, measured at p95.
5. Fifty computers run concurrently at the large tier without a failed start, sustained for one hour.
6. Every one of the tool catalogue's calls passes through the Action Gateway, and an automated test proves there is no code path that reaches a computer without a valid single-use action token.
7. Deny-by-default is proven: with an empty rule set, every action kind is refused.
8. Fail-closed is proven four ways: a malformed CEL rule, an evaluation timeout, an unreadable policy store, and an unwritable audit row each cause refusal rather than allowance, and each is audited with its cause.
9. The seeded rule set gates the three sensitive categories — payments and financial commitment, external messages, and data deletion — and each category has a passing end-to-end approval test including the expiry-means-denial path. The set is verified as a set by cwh policy:verify, never asserted as a count in a runbook.
10. Approval escalation walks owner → lead → admin on the configured timeout, expiry denies, and a requester cannot authorise their own request at any role.
11. Human takeover refuses coworker actions with HTTP 423 while held, voids every token minted before it, and the run resumes at the exact step on release.
12. Live screen streaming sustains under 1 second frame latency at p95 with 10 concurrent viewers, drops frames rather than queueing under backpressure, and evicts a viewer whose authorisation is revoked mid-stream within one tick.
13. No screen frame is written to disk when retention is 0, verified by filesystem inspection during an active stream.
14. A routine is recorded, induced, reviewed, saved, replayed successfully, self-heals one broken selector through a validated and re-decided repair, and versions correctly after a correction.
15. A handoff chain hits the depth cap, the cycle detector, the message cap, and the would-widen refusal, each with the right error code.
16. All four connectors complete per-user OAuth, perform read and write operations, refresh tokens without user interaction, gate a send that leaves the company, allow one that does not, and refuse one whose audience cannot be resolved.
17. An MCP server registers, classifies tools with write as the unknown default, refuses an instruction-shaped tool description, suspends rather than revokes grants on a definition change, and enforces per-coworker grants.
18. A credential is stored, injected into a browser field, and used successfully — and a full-text search across the database, every log stream, every WebSocket frame, and every API response finds the plaintext value nowhere.
19. Envelope encryption key rotation completes on a populated deployment with zero credential loss, following the documented procedure.
20. The audit trail records every event type in Section 26; UPDATE and DELETE on audit_events both fail on a missing grant for the application role on the parent and on every partition; the daily seal chain verifies; and the chain head reconciles against its off-host anchor.
21. A user views and deletes memories about themselves; deletion is immediate and audited, and the vector goes with the row.
22. API p95 is under 200 ms for non-AI endpoints and channel message delivery is under 500 ms end-to-end, at the large tier under the Section 32 load profile, measured with clock-skew correction rather than raw client timestamps.
23. Backup and restore are executed end-to-end on a populated deployment, including the database-only and single-workspace partial restores, meeting the stated RPO and RTO — and the restored cluster has every database role, with the archivist's memberships intact.
24. Coverage meets the floors in Section 35: 70% lines overall, 80% on the gateway, policy engine and vault, and 100% lines, branches and functions on the four enforcement-path files, with coverage-exclusion comments banned by lint in all four.
25. WCAG 2.2 AA is verified by automated axe checks on every route plus a manual keyboard-only pass of the channel view, approvals, and admin console, in both light and dark themes.
26. Zero TODO, FIXME, XXX, or any in apps/ and packages/ — enforced by lint, not by convention.
27. Every CWH_* variable the code reads is in the Section 33 catalogue and in the boot schema, and every catalogued variable is read by something — a build-failing equivalence test in both directions, because a catalogue nobody checks is documentation, not configuration.

3. Glossary & Core Concepts #

Precise definitions. The rest of the document uses these terms exactly as defined here and never introduces a synonym for one of them.

3.1 Terms #

Coworker — A durable, named AI teammate with a persistent profile: name, title, role description, avatar seed, owning user, visibility (private, team, or org), and status (active, disabled, or hidden). Stored in coworkers. A coworker is not a session and not a conversation; it exists between conversations, owns exactly one computer, holds its own memories, grants, and credentials access, and is soft-deleted rather than removed. Every governed action is evaluated under the acting coworker's identity. disabled drains its work and stops its computer; hidden keeps it running but takes it out of rosters and pickers. There is no "paused" coworker.

Computer — The container dedicated to one coworker, holding Chromium with a Playwright server, a persistent /workspace volume, and a shell executor. Exactly one per coworker, never shared, never reachable from the public network and never on a network the supervisor's control API is on. Row in computers with state in stopped, starting, ready, busy, human_control, error. An idle computer is frozen and then stopped on the two-tier ladder Section 12 owns; resuming from either is the warm path. The container is hard-deleted on reset; the workspace volume is separate and survives unless explicitly wiped.

Channel — A durable conversation. kind is direct (exactly one human and one coworker) or group (several humans and several coworkers). Channels hold messages, runs, and membership, survive process restarts, and are soft-deleted so history stays readable.

Content block — One element of a message's ordered content_blocks array. There are exactly nine types, defined once in the shared contracts package and consumed by both server and renderer. Two are the prose plane (text, markdown) and may be authored by a person or a coworker; seven are the record plane (tool_call, action, approval, file_ref, screenshot_ref, handoff, error) and are server-authored only, each a pointer to a row rather than a carrier of its own verdict. A message that arrives with a record-plane block from a model turn is rejected whole, not sanitised. There is no tenth type: a skill invocation is posted as a text block carrying the rendered invocation.

Run — One unit of coworker work inside a channel: a goal, a lifecycle, and a budget. States are queued → planning → acting → waiting_approval → waiting_human → and terminally succeeded, failed, or cancelled. A run is fully persisted step by step, so it survives an orchestrator restart and resumes at the step it reached. Three budgets bound it — steps, wall clock, and tokens (Section 11) — and time spent waiting on a human, in a queue, or on an operator hold does not count against the wall clock.

Step — One model turn or one tool call inside a run, persisted as a run_steps row before and after execution. Steps are the unit of resumption and the unit of the step budget.

Action — A single governed act: a browser click, a file write, a shell command, an MCP call, a connector call. An actions row is written with its decision before execution and updated with its result after. Every action has exactly one policy decision. An action that was never decided was never executed.

Gateway (Action Gateway) — The single chokepoint through which every action passes, implemented as its own workspace package and called from orchestrator. It assembles the evaluation context, calls the policy engine, records the decision, issues a single-use action token on allow, and dispatches. There is no bypass: the computer container refuses any command that does not carry a valid, unused, unexpired gateway-issued token bound to that computer and that command shape.

Policy rule — A stored CEL expression with an effect of allow or deny, a priority, and a scope. Configurable data, not code. Deny rules evaluate before allow rules; a matching deny wins outright; no match means refusal; a compile error, an evaluation error, an evaluation timeout, or an unreadable rule store all mean refusal.

Structural signal / corroborating signal — The two kinds of input a sensitive-action classification may use. A structural signal comes from the server's own resolution or a server-side enum — the connector operation name, the expanded recipient set, the enclosing form's method, the resolved argv[0], the MCP tool name. A hostile page controls none of them. A corroborating signal is page-authored — an accessible name, visible text, a URL path. A category may never be satisfied by a corroborating signal alone, and a corroborating signal may never cancel a structural match. The rule editor enforces both mechanically.

Approval request — A paused sensitive action awaiting a human decision. States pending, approved, denied, expired, cancelled. Expiry resolves the action as denied. Routing is owner → owner's team lead → any admin, on a configurable timeout, and the person who requested the work may never be the person who authorises it.

Control session — A period during which a named human holds the keyboard and mouse of a coworker's computer. While one is open, the computer is in human_control and every coworker- initiated action is refused with HTTP 423 — refused, not queued. Taking control opens a new control epoch, and every action token minted before it is void.

Routine — A repeatable, parameterised workflow with steps, parameters, and an immutable version. Either authored directly or induced from a demonstration. Replay is self-healing on a bounded ladder and corrections produce new versions.

Demonstration — The raw capture recorded while a human drives a coworker's browser: navigations, semantic element descriptors, typed values (vault-sourced values recorded as redacted references), waits, and extractions. A demonstration is the input to induction; it is not itself executable.

Skill — A reusable prompt or task template with typed parameters, scoped personal or org. A skill describes intent; a routine executes steps. A parameter declared secret is replaced by a marker everywhere it is persisted.

Memory — A durable fact a coworker learned, scoped coworker, user, or org, with a 1536- dimension embedding for retrieval. Written explicitly by memory.write or by the visible end-of-run reflection pass, never silently. Every user can view and delete every memory about themselves, and the deletion removes the vector in the same statement.

Embedding space — One vector space, deployment-wide, exactly 1536 dimensions, shared by memories and knowledge chunks. The model that produces it is named by a required configuration value with no default; a deployment with none configured does not start, and one whose configured model disagrees with the vectors already stored does not start either. There is no lexical fallback, because vectors from two embedding models are not comparable and mixing them fails silently.

Connector — A first-class, per-user OAuth integration with Gmail, Outlook, Slack, or Google Drive, acting as the requesting person and never as a shared service account.

External reach — Whether a connector operation delivers to someone outside the company's identity boundary, computed server-side from the recipient set after directory expansion, never asserted by the model. A group inside a company domain that expands to include an outsider is external. An audience that cannot be resolved at all is neither internal nor external but undecidable, and an undecidable audience is refused rather than guessed.

MCP server — An admin-registered Model Context Protocol server reached over stdio or streamable HTTP, exposing tools that are classified read or write — with write as the default for unknown tools and custom servers, and no downward override of a tool the server itself marks destructive.

Grant — An explicit, per-coworker permission to use one MCP tool, one connector account, or one credential. Grants are never inherited, never implied, and never transferred by a handoff. A grant may be suspended — held intact but non-functional pending review — which is not the same as revoked.

Handoff — One coworker passing work to another with a structured payload of goal, context, artifacts, and deadline. The receiver accepts or declines with a reason, and its actions are evaluated under its own identity and grants. A handoff that would only work by inheriting the sender's reach is refused rather than executed.

Audit event — An append-only record in the audit schema of a decision, an action, or an administrative change, carrying actor, subject, run, action, decision, and evaluation context. The schema has its own owner role, separate from the role migrations run as; the application role holds SELECT and INSERT and nothing else, on the parent and on every partition. The table has a gap-free seq column in addition to its id, is hash-chained, is sealed daily, and has its head witnessed off-host.

Anchor — The off-host witness of the audit chain's head, published on an interval and immediately on any critical event. It is what makes tamper-evidence true against an attacker who has root on this host, because an attacker who can recompute the chain cannot recompute a value somebody else already holds.

Archivist — The one database role permitted to detach an audit partition, and the only lawful path by which anything ever leaves the hot table. It may act only after the partition's contents have been exported, checksummed and verified. The application role cannot detach anything, and the archivist cannot touch a live partition. Events are not destroyed; they move.

Standing role — The persistent role description attached to a coworker that is placed at the top of its assembled context on every run in every channel. It is what makes a coworker consistent rather than a blank chat, and it is a job description, not a permission grant: it cannot widen what the coworker may do.

Coordinator — The single coworker designated per group channel that is permitted to assign work. Exactly one per group channel. Non-coordinator coworkers act only when @mentioned or assigned. This is how a group channel avoids a stampede.

Sensitive action — An action falling into one of exactly three categories: payments and financial commitment, external messages, and data deletion. These, and only these, require human approval by default; everything else that matches an allow rule runs freely with audit logging, and anything matching nothing at all is refused. The categories ship as seeded, admin-editable policy rules — the rules are verified as a set at boot rather than counted in prose — and admins may add more.

Action token — A single-use, short-lived, gateway-signed bearer token bound to one action id, one computer, one command shape, and one control epoch. The computer container validates and burns it, holding only the public half of the signing key, which is why compromising a container mints no tokens. Its TTL is a configuration value (Section 33) chosen to exceed the longest action it must cover. It is hard-deleted after use and is never logged.

Egress proxy — The service through which every byte a computer container sends must pass. It is its own container, on its own networks, and the computer network has no default route, so it is not defence in depth — it is the only way out. It terminates the CONNECT, resolves the host, re-validates every resulting address, pins the connection to the address it validated, and tunnels opaque bytes. It performs no TLS interception and never sees plaintext.

Tombstone — The read-only remnant of a soft-deleted entity. A soft-deleted coworker's messages remain readable in channel history, attributed to a tombstoned identity, so that the conversational record stays intelligible without resurrecting the coworker.

3.2 Conceptual Model #

graph TD
  U["User (employee / lead / admin)"] -->|"member of"| T["Team"]
  U -->|"owns"| CW["Coworker"]
  T -->|"approval routing"| AR["Approval request"]
  CW -->|"has exactly one"| CP["Computer"]
  CW -->|"holds"| MEM["Memory"]
  CW -->|"granted"| GR["Grant"]
  GR --> MCP["MCP server tool"]
  GR --> CON["Connector account"]
  GR --> CRED["Credential"]
  U -->|"member of"| CH["Channel"]
  CW -->|"member of"| CH
  CH -->|"contains"| MSG["Message"]
  CH -->|"contains"| RUN["Run"]
  RUN -->|"composed of"| ST["Run step"]
  ST -->|"may request"| ACT["Action"]
  ACT -->|"always passes"| GW["Action Gateway"]
  GW -->|"consults"| PR["Policy rule (CEL)"]
  GW -->|"emits"| AE["Audit event"]
  AE -->|"head witnessed by"| ANC["Off-host anchor"]
  GW -->|"allow: issues"| TOK["Action token"]
  GW -->|"require_approval: creates"| AR
  AR -->|"decided by"| U
  TOK -->|"redeemed once at"| CP
  CP -->|"only route out"| EGR["Egress proxy"]
  RUN -->|"may execute"| RT["Routine"]
  RT -->|"induced from"| DEM["Demonstration"]
  DEM -->|"recorded during"| CS["Control session"]
  CS -->|"held by"| U
  CS -->|"locks"| CP
  RUN -->|"may invoke"| SK["Skill"]
  RUN -->|"may issue"| HO["Handoff"]
  HO -->|"to another"| CW
  CP -->|"streams"| SF["Screen frame"]
  ACT -.->|"3 sensitive categories"| AR

Read it in one line: a user owns a coworker, which owns a computer; work happens as runs in channels; runs produce actions; every action goes through the gateway, which consults policy, emits audit, and either issues a token, refuses, or asks a human — and the container can neither act without a token nor reach the network except through the proxy.

3.3 One Governed Action, End to End #

sequenceDiagram
    autonumber
    actor E as Employee
    participant W as web (SPA)
    participant A as api
    participant Q as Valkey / BullMQ
    participant O as orchestrator
    participant M as Model provider
    participant G as Action Gateway
    participant P as Policy engine
    participant S as supervisor
    participant C as Computer container
    participant D as PostgreSQL

    E->>W: "Email the supplier the corrected PO"
    W->>A: POST /api/v1/channels/{id}/messages
    A->>D: INSERT messages, INSERT runs (queued), INSERT event_outbox — one transaction
    A->>Q: enqueue run job
    A-->>W: 202 + run id, X-Request-Id
    A-->>W: WS run.state_changed (queued)

    Q->>O: dequeue run job
    O->>D: re-read every entity by id; run -> planning; assemble context
    Note over O: standing role, policy preamble,<br/>channel window, memories,<br/>knowledge, tools, active routine
    O->>M: messages + tool definitions
    M-->>O: tool_call connector.gmail.send
    O->>D: INSERT run_steps (tool_call)
    O->>D: run -> acting

    O->>G: dispatch(action)
    Note over G: connector resolves external reach server-side.<br/>Undecidable audience = refuse, not guess.
    G->>D: INSERT actions (decision pending)
    G->>P: evaluate(context)
    Note over P: deny rules first, then allow.<br/>No match = refuse.<br/>Eval error, timeout or<br/>unreadable store = refuse.
    P-->>G: require_approval (seeded external-messages rule)
    G->>D: UPDATE actions decision=require_approval
    G->>D: INSERT approval_requests (pending)
    G->>D: INSERT audit_events (action.approval_required)
    G-->>O: paused
    O->>D: run -> waiting_approval
    O->>A: notify(owner — never the requester)
    A-->>W: WS approval.created
    A-->>E: in-app notification, plus any configured relay

    E->>W: Approve
    W->>A: POST /api/v1/approval-requests/{id}/approve
    A->>D: approval -> approved; audit approval.granted
    A->>Q: enqueue run resume

    Q->>O: dequeue resume
    O->>G: resume(action)
    Note over G: re-evaluate. Target or context changed<br/>since the decision = void the approval.
    G->>D: UPDATE actions decision=allow
    G->>D: INSERT action_tokens (single use, bound to action + computer + epoch)
    G->>D: INSERT audit_events (action.allowed)
    G->>S: execute(action, token) over the UNIX socket
    S->>C: command + token over the per-coworker UNIX socket
    C->>C: verify signature with the gateway PUBLIC key, check epoch, burn token
    C-->>S: result
    S-->>G: result
    G->>D: UPDATE actions (result, duration); DELETE token
    G->>D: INSERT audit_events (action.executed)
    G-->>O: result
    O->>M: tool result appended, continue loop
    M-->>O: final answer
    O->>D: INSERT messages; run -> succeeded
    O->>A: publish
    A-->>W: WS message.created, run.state_changed
    W-->>E: "Sent. Here is what went out."

Three properties are worth naming explicitly. First, the actions row exists with a decision before anything executes — so a crash between decision and execution leaves a decided, unexecuted action, which is recoverable and auditable, rather than an unexplained side effect. Second, the token is minted at allow and burned at the container, and the container holds only the public half of the signing key: take the gateway out of the path and there is nothing to present, so the bypass does not exist because the credential to bypass with does not exist. Third, the gap between approving and executing is not assumed away — the gateway re-evaluates on resume, and an approval whose target or evaluation context has moved underneath it is void rather than honoured.

3.4 Mental Model in Five Sentences #

1. A coworker is a durable colleague with a persistent role and its own computer; it is not a chat session, and everything it does is attributed to it by name.
2. Work happens as runs inside channels, and a run is a persisted sequence of steps — model turns and tool calls — that survives a restart and resumes where it stopped.
3. Every consequential thing a coworker does is an action, and every action goes through one gateway that consults policy and returns exactly one of allow, deny, or require_approval — with refusal as the answer when nothing matches or anything errors.
4. Humans stay in the loop two ways: approval gates pause one specific action and resume the run on decision, and takeover lets a human hold the keyboard, during which coworker actions are refused rather than queued.
5. Nothing is trusted to memory or good intentions — decisions, actions, and admin changes land in an append-only audit trail whose head is witnessed off this host, and secrets move through a vault that injects values into targets without ever putting them in the transcript.

4. Technology Stack & Architecture #

4.1 The Canonical Version Table #

This is the only table of versions in the document. Every other section refers to a dependency by name without a number.

These version lines are a known-good floor, not a lockfile. At build time, install the current stable release of each dependency (pnpm add <pkg>@latest, or your ecosystem's equivalent), confirm the major line still matches, and let the lockfile record the exact resolved versions.

4.2 The Services #

Nine Compose services. Six are long-running, two are one-shot, and one is an image-only build target the supervisor instantiates at runtime. Four of them — api, orchestrator, supervisor, egress-proxy — share a single image and select their role from one configuration value, which is why the pull count is smaller than the service count.

graph TB
  subgraph PUB["Public network"]
    BR["Browser (employee / lead / admin)"]
  end

  subgraph EDGE["cwh_edge — bridge, NAT egress, the only published ports"]
    CADDY["caddy :80 :443 (tcp+udp)<br/>TLS termination, HTTP/3<br/>serves /srv/web, proxies /api/* and /ws"]
    WEBV[("cwh_web_dist volume<br/>built SPA bundle")]
  end

  subgraph CORE["cwh_internal — bridge, internal: true, no route out"]
    API["api<br/>Hono HTTP + WebSockets<br/>auth, DB, channels, admin"]
    ORCH["orchestrator<br/>agent loop + ACTION GATEWAY<br/>no inbound public route"]
    SVC["supervisor<br/>owns /var/run/docker.sock<br/>NOT attached to cwh_computer"]
    PG[("postgres<br/>PostgreSQL 18 + pgvector")]
    VK[("valkey<br/>queues, buckets, pub/sub")]
    MIG["migrate (one-shot, exits 0)"]
  end

  subgraph COMP["cwh_computer — bridge, internal: true, NO DEFAULT ROUTE"]
    C1["computer-a1b2<br/>Chromium + Playwright server<br/>/workspace, shell executor"]
    C2["computer-c3d4"]
    CN["computer-…"]
    EGR["egress-proxy<br/>the only way out"]
  end

  subgraph EGN["cwh_egress — bridge, NAT egress, nothing else attached"]
    OUT["allowlisted outbound only"]
  end

  BR -- "https / wss" --> CADDY
  CADDY --> WEBV
  CADDY -- "/api/v1/*, /ws" --> API
  API <--> PG
  API <--> VK
  ORCH <--> PG
  ORCH <--> VK
  MIG --> PG
  ORCH -- "UNIX socket /run/cwh/supervisor.sock + supervisor token" --> SVC
  ORCH -- "https" --> MODEL["Model provider API<br/>(the only outbound dependency)"]
  SVC -- "docker API" --> C1
  SVC -- "per-coworker UNIX socket" --> C1
  SVC -- "per-coworker UNIX socket" --> C2
  SVC -- "per-coworker UNIX socket" --> CN
  SVC -- "screencast frames" --> API
  C1 -- "http proxy, no other route" --> EGR
  EGR --> OUT
  OUT --> INET["Internet"]

Two dependency edges are deliberately absent and must not be added. supervisor does not depend on migrate: it tolerates a schema older than its own binary for the length of one upgrade window, which is what makes the rolling-restart order safe. egress-proxy does not depend on postgres: it reads its allowlist from configuration at boot and nothing else, because if it needed the database then a database outage would silently become an egress-policy outage, and a fail-closed proxy that cannot start is a fleet-wide stop.

caddy also does not depend on api being healthy. It starts as soon as the bundle exists and serves a maintenance page when api is down — an operator locked out of the admin console during an upgrade cannot finish the upgrade, so the edge must survive the tier behind it.

4.2.1 What Each Process Owns and Must Never Do #

4.3 Trust Boundaries #

Five boundaries, ordered from least to most trusted. Each is a place where input is re-validated; a value that crossed one boundary is never assumed safe at the next.

The rule that ties them together: the model is never inside a trust boundary. Model output is treated as an untrusted request for an action, identical in trust level to a form submission from the internet. It is validated, evaluated against policy, and executed only under a token. The corollary holds too — text the page wrote is untrusted in the same way, which is why a sensitive category may never be satisfied by a string a page chose.

4.4 Network Model #

Four Docker networks. Two of them are internal: true, which means Docker installs no NAT rule for them and a misconfigured host firewall cannot expose them.

What the browser can reach: the SPA at the public origin, the API under /api/v1/*, the multiplexed control WebSocket, and — while the Screen tab is open — the dedicated binary frame socket. That is the entire attack surface exposed to a user agent. Screen frames reach the browser through api; the browser never connects to a computer container, and no computer container is addressable from outside its internal network.

Metrics listeners bind to loopback by default. The supervisor's metrics endpoint reveals container inventory and host capacity, and binding it wide is how it becomes readable from a network a coworker container can see. Where a scraper needs them, they move to the service's internal address and a bearer token is set — they never appear on the public origin.

4.5 Data Flow: A Chat Message #

1. The browser POSTs to /api/v1/channels/{id}/messages. caddy terminates TLS and forwards with the X-Forwarded-* headers, which api honours only because the peer is in the edge subnet.
2. api validates the session cookie, checks CSRF and Sec-Fetch-Site, resolves the user and role, applies the per-user token bucket, and validates the body against the shared Zod schema.
3. api writes the messages row, a runs row in queued if the message addresses a coworker, and an event_outbox row — in one transaction, so a message that should start work never exists without its run, and a state change never exists without its notification.
4. api enqueues a BullMQ job carrying only ids, and returns 202 Accepted with the created message and the run id. It is deliberately not an AI route: the model has not been called and will not be before the response, which is what keeps the user-visible write path inside its latency target however slow the provider is.
5. The outbox dispatcher publishes message.created and run.state_changed to the channel topic on Valkey pub/sub; every subscribed WebSocket connection on any api replica fans it out to its browsers. Delivery target: under 500 ms end to end, measured with clock-skew correction rather than raw client timestamps.
6. orchestrator dequeues, re-reads every entity from PostgreSQL, and moves the run to planning. Context assembly follows Section 11. It calls the model provider, and every resulting tool call goes through the gateway as in Section 3.3.
7. Each state change and each new coworker message is persisted first and published second. Persist-then-publish through the outbox is the invariant: a dropped WebSocket frame costs a refetch, never data.
8. A browser that reconnects sends the last sequence number it saw; api replays the gap from its retained window, or tells the client to refetch when the gap is older than that window. Sequence numbers, not timestamps, define ordering.

4.6 Data Flow: A Screen Frame #

Screen frames travel on their own binary WebSocket, not on the multiplexed control socket. One control socket per browser tab, plus one frame socket while the Screen tab is live.

1. supervisor attaches to the coworker's Chromium over CDP and starts a screencast at the configured quality and maximum dimensions — only while at least one viewer is subscribed.
2. Each frame arrives as base64 JPEG. supervisor decodes, stamps it with computer id, a monotonically increasing frame sequence, and a capture timestamp, and forwards it to api over the internal publish endpoint as a binary payload.
3. api fans the frame out to subscribers of that computer's screen topic as a binary message with a small header. Authorisation is re-evaluated for the life of the stream, not only at connect: a viewer who leaves the channel, loses team membership, or has the coworker's visibility narrowed under them is closed with SCREEN_AUTHORIZATION_LOST within one tick and its slot released.
4. Backpressure drops, never queues. Each subscriber has a depth-1 slot; if a frame is pending when a new one arrives, the pending frame is discarded. Latency never accumulates, and a slow viewer degrades to a lower effective frame rate instead of falling minutes behind.
5. The client draws to a <canvas>. Adaptive rate: the configured nominal frame rate, reduced automatically when the client reports sustained decode lag. Two ceilings apply — one on viewers per computer, and one on concurrent streams across the deployment, because a per-computer cap does not bound total bandwidth.
6. Nothing is written to disk while screen-frame retention is 0, which is the default. With retention enabled — maximum 24 hours — frames are written to a dedicated volume, sampled down, and pruned by a scheduled job. The admin console states, on the setting itself, that frames may contain secrets. Password fields are masked in every persisted screenshot regardless of the setting; scanning persisted screenshots for known secret values is a separate, off-by-default control that never touches the live stream, because it cannot meet the frame-latency target.
7. The screencast is stopped when the last viewer unsubscribes, so an unwatched coworker costs no capture CPU. Frame latency target: under 1 second at p95, capture to render acknowledgement.

4.7 The Model Provider Abstraction #

One built-in engine. The reasoning vendor is a deploy-time configuration choice behind a thin internal interface — not a plug-in system, and not bring-your-own-agent. The orchestration loop, the tool catalogue, the prompts, and the gateway are ours in every case.

// packages/model/src/provider.ts

/** A single message in the model conversation. Wire-neutral by design. */
export interface ModelMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: ModelContentBlock[];
}

export type ModelContentBlock =
  | { type: 'text'; text: string }
  | { type: 'image'; mediaType: 'image/jpeg' | 'image/png'; dataBase64: string }
  | { type: 'tool_use'; id: string; name: string; input: unknown }
  | { type: 'tool_result'; toolUseId: string; isError: boolean; content: string };

export interface ToolDefinition {
  name: string;                 // e.g. "browser.click" — matches the catalogue in Section 11
  description: string;
  inputSchema: Record<string, unknown>; // JSON Schema, produced from the Zod schema in @cwh/contracts
}

export interface ModelRequest {
  model: string;
  system: string;
  messages: ModelMessage[];
  tools: ToolDefinition[];
  maxOutputTokens: number;
  temperature: number;          // 0.0–1.0; the loop uses a low value for acting
  stopSequences?: string[];
  metadata: { runId: string; coworkerId: string; requestId: string };
}

export type StopReason =
  | 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'content_filter';

export interface ModelResponse {
  content: ModelContentBlock[];
  stopReason: StopReason;
  usage: { inputTokens: number; outputTokens: number; cachedInputTokens: number };
  providerRequestId: string | null;  // for vendor-side support tickets; never contains content
}

export type ModelStreamEvent =
  | { type: 'text_delta'; text: string }
  | { type: 'tool_use_start'; id: string; name: string }
  | { type: 'tool_use_delta'; id: string; partialJson: string }
  | { type: 'tool_use_stop'; id: string }
  | { type: 'message_stop'; stopReason: StopReason; usage: ModelResponse['usage'] };

export interface EmbeddingRequest { model: string; inputs: string[] }
export interface EmbeddingResponse {
  vectors: number[][];          // MUST be exactly 1536 dimensions each (Section 6)
  usage: { inputTokens: number };
}

export interface ProviderHealth {
  ok: boolean;
  checkedAt: string;            // ISO 8601 with Z
  latencyMs: number | null;
  detail: string | null;
}

/** The entire surface the orchestrator is permitted to use. Nothing else. */
export interface ModelProvider {
  readonly id: 'anthropic' | 'openai' | 'stub';
  readonly capabilities: {
    streaming: boolean;
    imageInput: boolean;
    promptCaching: boolean;
    parallelToolCalls: boolean;
  };

  complete(req: ModelRequest, signal: AbortSignal): Promise<ModelResponse>;
  stream(req: ModelRequest, signal: AbortSignal): AsyncIterable<ModelStreamEvent>;
  embed(req: EmbeddingRequest, signal: AbortSignal): Promise<EmbeddingResponse>;
  countTokens(req: ModelRequest): Promise<number>;
  health(signal: AbortSignal): Promise<ProviderHealth>;
}

Note what the interface does not carry: a default model and a default embedding model. Model ids move faster than releases, and a default that silently goes stale degrades every coworker in a way nobody sees. Both are required configuration with no fallback.

The two shipped implementations, plus one that is not for you.

There is one key variable and one embedding selector, not one per vendor. Two provider-specific key names invite a deployment where both are set and neither is used; a separate embedding provider invites a deployment whose vectors came from two spaces. Both older shapes are recognised by the boot validator and refused by name, with their replacement stated (Section 33). Every application variable carries the CWH_ prefix without exception, per Section 5.3.

Selection happens once at orchestrator boot:

// packages/model/src/select.ts
export function selectProvider(cfg: ModelConfig): ModelProvider {
  switch (cfg.provider) {
    case 'anthropic': return new AnthropicProvider(cfg);
    case 'openai':    return new OpenAIProvider(cfg);
    case 'stub':      return new StubProvider(cfg);   // refused unless the environment permits it
    // exhaustive: adding a member to the union is a compile error until handled
    default: { const _never: never = cfg.provider; throw new Error(`unreachable: ${_never}`); }
  }
}

The value is validated by the boot-time configuration schema (Section 33). An unknown value is a hard startup failure with a readable message, never a silent fallback to the default — a deployment that thinks it is on one vendor and is quietly on another is a data-residency incident.

The embedding contract, stated once. embed() must return vectors of exactly 1536 dimensions, because that is the column type. Where a provider's native model is wider, the request uses the provider's own dimension parameter; where it is narrower, the adapter zero-pads, which changes neither dot products nor norms and so leaves cosine similarity mathematically identical. What the adapter may never do is return a different width and hope: the width is asserted at boot, the configured model is compared against the models recorded on stored rows, and either mismatch is a startup failure naming the re-embedding job. There is no runtime error path here and no lexical fallback, because a deployment that quietly loses semantic retrieval is worse than one that refuses to start.

What a third implementation must satisfy. Adding a provider is a code change in packages/model, reviewed like any other. It must:

1. Implement every method of ModelProvider. stream() may be implemented on top of complete() by emitting one message_stop, but it must not throw.
2. Honour the AbortSignal on every method, aborting the in-flight HTTP request within 1 second of the signal firing. Cancellation is how a run is stopped; a provider that ignores it is a bug.
3. Emit tool calls as tool_use blocks with a stable id that the loop can match to tool_result, and never emit a tool name outside the supplied tools array.
4. Return exactly 1536-dimension vectors from embed(), by whatever route the vendor offers.
5. Map every transport and vendor error onto the shared taxonomy — MODEL_RATE_LIMITED, MODEL_CONTEXT_OVERFLOW, MODEL_CONTENT_FILTERED, MODEL_UNAVAILABLE, MODEL_TIMEOUT, MODEL_PROTOCOL_ERROR — so the loop's retry policy works unchanged. The vendor's own identifiers are the vendor's vocabulary; translating them is the adapter's job.
6. Retry only on the retryable members of that taxonomy, with exponential backoff plus full jitter, within the configured attempt ceiling, honouring Retry-After. Never retry a tool-use response.
7. Report accurate token usage, because the run token budget and the local admission buckets are enforced from it.
8. Never log request or response content — only token counts, latency, model name, stop reason, and the provider request id. Enforced by the redaction rules in Section 5.6.
9. Pass the shared provider conformance suite, which every implementation runs against a recorded fixture set.

4.8 Build-Time versus Run-Time Dependencies #

Three rules follow. First, a build-time dependency that appears in a runtime image fails CI — the image audit asserts the absence of the TypeScript compiler and of devDependencies. Second, the computer image is built from a separate Dockerfile with no access to the workspace source, so application code cannot accidentally be shipped into the least-trusted container. Third, sharing one image across four roles does not mean sharing one capability set: the secrets Compose delivers per service and the required-variable subset per role are what actually bound each one, and api never receives the supervisor token.

4.9 Container Images #

All images are built for linux/amd64 and linux/arm64, pinned by digest in the Compose file — including Valkey and Caddy, because a floating tag is re-resolved by a routine docker compose pull during an upgrade the version policy calls always safe, and an unannounced minor with an on-disk format change is not something a rollback can read. Images are signed, verified before deploy, and scanned in CI; a high-severity vulnerability in a base image blocks the release.

4.10 Architectural Decision Records #

Fourteen decisions that would otherwise be re-litigated in every design review.

ADR-001 — One Action Gateway, not per-tool permission checks. Context: every browser, file, shell, MCP, and connector call needs a policy decision, an audit record, and an execution receipt. Decision: all of it goes through a single gateway, in its own package with its own coverage floor; the computer container refuses any command without a gateway-signed single-use token. Alternatives: per-tool checks in each tool implementation, rejected because coverage becomes a code review property that decays and a new tool ships ungoverned; a sidecar policy service, rejected as a network hop and a second failure mode on the hottest path. Consequence: the gateway is a hot path and a single point of failure — its enforcement call site and its token module are held to 100% line, branch and function coverage with exclusion comments banned by lint, and its latency budget is tight. In exchange, "is every action governed?" is answered by one integration test rather than by inspection.

ADR-002 — One container per coworker, not a shared computer pool. Context: coworkers need persistent browser profiles, cookies, downloads, and workspaces. Decision: one dedicated container and volume per coworker. Alternatives: a warm pool with per-run profile injection, cheaper on memory but leaks state between identities and makes "whose cookie is this?" unanswerable; one shared browser with contexts, which fails the isolation requirement outright since a compromise reaches every coworker. Consequence: memory scales linearly and the concurrency cap becomes a first-class configuration value. Idle containers are frozen and then stopped rather than destroyed, which is what makes the warm resume fast, and an idle-stopped computer keeps its host capacity reservation for a grace period so a resumed coworker does not find its host full.

ADR-003 — CEL for policy, not a hand-rolled DSL and not embedded JavaScript. Context: admins edit rules; rules must be safe, fast, and analysable. Decision: CEL expressions evaluated over a flat context object. Alternatives: a hand-rolled DSL, which means owning a parser, an error-message story, and a decade of feature requests; embedded JavaScript, which is arbitrary code execution inside the most security-critical component and has no evaluation bound; declarative JSON match trees, which cannot express page.host.endsWith(...) && !file.path.startsWith(...). Consequence: admins learn a small expression language, so the rule editor ships with a linter, inline documentation of every context field, and a test harness that evaluates a draft rule against recorded actions before saving. Rules are pre-compiled and cached; every failure mode — compile error, evaluation error, per-rule timeout, whole-set timeout, unreadable store — refuses the action and is audited. List-valued context fields are capped when the context is built, with a companion truncation flag rules can read, so an action carrying thousands of argv tokens cannot turn an evaluation into an alert storm.

ADR-004 — PostgreSQL with pgvector, not a separate vector database. Context: memories and knowledge chunks need similarity search at 1536 dimensions. Decision: vector(1536) columns in the same database, HNSW-indexed, one embedding space deployment-wide. Alternatives: a dedicated vector store, which adds a second datastore to deploy, secure, back up, and keep consistent, and makes "delete every memory about this user, immediately" a distributed-transaction problem. Consequence: recall and latency are bounded by pgvector rather than by a specialised engine, which is comfortably sufficient at the stated scale, and the index lives in page cache alongside the rest of the working set — a real line in the memory budget of Section 32. Deleting a memory removes its vector in the same statement, so there is no window in which a deleted memory is still retrievable. If the ceiling is ever reached, the retrieval interface in Section 21 is the seam to swap behind.

ADR-005 — Cursor pagination everywhere, never offset. Context: the highest-volume collections — audit events, actions, messages — are append-heavy and read while being written. Decision: opaque, signed cursors that carry the sort and filter digest. Alternatives: offset pagination, which duplicates and skips rows under concurrent inserts and degrades linearly with depth on exactly the tables that grow fastest. Consequence: no page-number UI and no "jump to page 40". The UI uses infinite scroll with filters, which is the better interaction for these datasets anyway, and a tampered cursor is distinguishable from a merely stale one — two different codes, so the logs can tell an attack from a bookmark.

ADR-006 — Soft delete for authored entities, hard delete for ephemera, never for audit. Context: deleting a coworker must not corrupt channel history; deleting a session must actually delete it; deleting an audit event must be impossible. Decision: three tiers. Soft delete for coworkers, channels, skills, routines, policy rules, MCP registrations, and connector accounts. Hard delete for sessions, action tokens, screen-frame buffers, idempotency keys, outbox rows, memories, knowledge, and expired approval requests. The audit tables are append-only with no UPDATE or DELETE grant for the application role. Alternatives: uniform soft delete, which retains bearer tokens forever and turns every privacy request into an argument; uniform hard delete, which turns channel history into orphaned foreign keys. Consequence: every query on a soft-deletable table filters for the tombstone predicate, enforced by repository helpers rather than by discipline (Section 5.9), soft-deleted coworkers appear in history as tombstones, and a purge ahead of the retention horizon is an explicit, confirmed, reasoned admin act that never touches an audit row.

ADR-007 — A multiplexed control WebSocket plus a dedicated binary frame socket, not SSE. Context: the channel view needs messages, run state, activity, and approvals concurrently, and the Screen tab additionally needs a high-rate binary stream. Decision: one multiplexed control socket per browser tab with topic subscribe and unsubscribe, sequence numbers, and gap-fill replay — plus a separate binary socket, opened only while the Screen tab is live, carrying frames and control input. Alternatives: SSE, which is text-only, so frames would need base64 inflation, and which has no client-to-server path for subscription changes; long polling, rejected on latency; putting frames on the control socket, rejected because a 5 fps binary stream head-of-line blocks approval delivery and because the two have genuinely different lifetimes, backpressure policies and authorisation re-checks. Consequence: we own reconnection, backoff, heartbeat, and replay, specified in Section 7, and both sockets require a single-use ticket — a cookie alone opens neither.

ADR-008 — Per-user OAuth for connectors, not a shared service account. Context: a coworker reads and sends mail, posts to Slack, and touches Drive. Decision: every connector call uses the requesting person's own OAuth grant, and the account being connected must belong to the person connecting it. Alternatives: a shared service account with broad domain-wide delegation, which is simpler to configure and catastrophic in practice — every coworker inherits access to every mailbox, the provider's own audit log attributes everything to one robot identity, and revoking one person's access is impossible. Consequence: a coworker can only do what the person who asked can do, which is the correct authorization boundary; the cost is that each user connects their own accounts, and a coworker acting on behalf of someone with no grant reports that plainly rather than silently using someone else's. It also means the deployment can compute external reach from the user's directory, which is what makes the external-message gate meaningful rather than a guess from a domain string.

ADR-009 — Docker Compose, not Kubernetes. Context: the target is a single company running one deployment on its own infrastructure. Decision: single-host Docker Compose is the supported topology. Alternatives: Kubernetes, which adds a cluster to operate, and whose scheduling model actively fights the supervisor's need for direct Docker socket control over per-coworker containers; Nomad, same objection with a smaller community. Consequence: no built-in multi-host high availability in v1 — upgrades take a maintenance window, stated plainly in Section 33. The full documented scale target fits one well-provisioned host, and Section 32 documents the multi-host split for the reasons that actually justify it — blast-radius separation, divergent capacity curves, and handing the database to a DBA team — rather than "we outgrew Compose". In that split the supervisor's UNIX socket is replaced by mutual TLS and never by an open port.

ADR-010 — One built-in agent engine, not a bring-your-own framework. Context: external agent frameworks exist and are tempting. Decision: one engine — our loop, our tools, our prompts, our gateway. Alternatives: adapters for external frameworks, which would let teams reuse existing agent code. Consequence: rejected because every guarantee in this document depends on owning the loop. An external framework calling its own tools is, by definition, a gateway bypass — no policy evaluation, no action token, no audit event. The extensibility that remains is deliberate and bounded: MCP servers for tools, routines for workflows, skills for prompts.

ADR-011 — snake_case on the wire, camelCase in TypeScript, converted only at the boundary. Context: the database is snake_case and idiomatic TypeScript is camelCase. Decision: JSON uses snake_case in both directions; conversion happens exactly once, in the Zod schemas and Drizzle column mappings at the HTTP boundary. Alternatives: camelCase on the wire, which puts conversion in the database layer where the ORM already maps names and creates two conversion points; converting nowhere, which leaks camelCase into SQL or snake_case into React. Consequence: hand-written case conversion is a code-review failure, and every API example in this document uses snake_case keys.

ADR-012 — A separate supervisor role owns the Docker socket, reachable only over a UNIX socket. Context: something must create and control containers. Decision: an isolated role with no database access, no model access, and no vault access, reached over a UNIX socket on a shared volume rather than over TCP — and attached to no network a coworker container can see. Alternatives: orchestrator mounting the Docker socket directly, which is one deserialisation bug away from host root in the same process that parses model output — an unacceptable adjacency; a TCP control API on a private interface, rejected because "private" is a property of a network configuration an operator can change and a socket path is not. Consequence: one more hop, at a few milliseconds per call. In exchange, the process handling untrusted model output has no path to the container runtime, the process with root-equivalent power has an attack surface of about a dozen typed methods behind a shared secret and no listener at all, and the supervisor reaches each computer the same way — a per-coworker UNIX socket, with no network path between them either.

ADR-013 — DB-side uuidv7() primary keys, bare UUIDs on the wire. Context: every table needs a key that is time-ordered, index-friendly, and safe to expose. Decision: id uuid PRIMARY KEY DEFAULT uuidv7() generated by PostgreSQL 18, exposed as a bare UUID string. Alternatives: bigserial, which leaks row counts and complicates merges; application-side UUIDv4, which fragments B-tree inserts on the largest tables; prefixed string ids, which are pleasant to read in logs but require every foreign key to carry the prefix and every parser to strip it. Consequence: ids sort by creation time, which makes cursor pagination on append-only tables trivial. The one exception is the audit trail's seq, an identity column that provides gap-free ordering for tamper-evidence, because UUIDv7 ordering is monotonic but not gap-free — and gap-free is the property a chain needs.

ADR-014 — Zod schemas in a shared contracts package, not OpenAPI-first code generation. Context: client and server must agree on every shape. Decision: one Zod schema per shape in @cwh/contracts, imported by the Hono validator and by the React form that posts to it; OpenAPI is generated from those schemas for documentation. Alternatives: OpenAPI-first with generated clients, which adds a generation step to every change, produces types that are structurally right and ergonomically poor, and still needs runtime validation written separately. Consequence: the schema is the single source of truth for types, runtime validation, form validation, and the generated tool input schemas the model receives. Two definitions of one shape is a code-review failure, and the closed enums that live there — error codes, action kinds, audit event types, WebSocket events, content-block types — are checked against the document's own tables by a build-failing test in both directions.

5. Repository Layout & Code Conventions #

5.1 The Workspace Tree #

A pnpm workspace: four applications, the shared packages, the computer container, and the deployment and test trees that sit beside them at the repository root. Annotated to file level where the file matters.

coworker-hub/
├─ package.json                    # root scripts only; no runtime dependencies here, ever
├─ pnpm-workspace.yaml             # packages: apps/*, packages/*
├─ tsconfig.base.json              # the compiler options in 5.12; every tsconfig extends it
├─ tsconfig.json                   # solution file: project references to every workspace package
├─ eslint.config.js                # flat config, shared by every package (5.11)
├─ .prettierrc.json                # formatting, shared (5.11)
├─ vitest.config.ts                # the coverage thresholds of Section 35; they FAIL the run
├─ .env.example                    # every variable from Section 33, with safe placeholder values
├─ docker-compose.yml              # the supported deployment topology (Section 33)
├─ docker-compose.dev.yml          # local overrides: bind mounts, exposed ports, no TLS
├─ docker-compose.compute.yml      # the multi-host compute-plane overlay (Section 33)
├─ CHANGELOG.md
├─ README.md
│
├─ apps/
│  ├─ web/                         # React SPA. NEVER contains a secret or a DB query.
│  │  ├─ index.html
│  │  ├─ vite.config.ts
│  │  └─ src/
│  │     ├─ main.tsx               # createRoot, providers, router mount
│  │     ├─ router.tsx             # the route table from Section 28, data router mode
│  │     ├─ api/
│  │     │  ├─ client.ts           # fetch wrapper: credentials, X-Request-Id, error decoding
│  │     │  ├─ queries.ts          # TanStack Query keys + query/mutation factories
│  │     │  ├─ ws.ts               # the multiplexed CONTROL socket: ticket, subscribe, replay
│  │     │  └─ screen-socket.ts    # the separate BINARY frame socket (Section 18); own lifetime
│  │     ├─ routes/                # one folder per route; colocated components and loaders
│  │     │  ├─ channels/  coworkers/  routines/  skills/
│  │     │  ├─ approvals/ settings/  admin/
│  │     ├─ features/              # cross-route feature modules
│  │     │  ├─ screen-viewer/      # canvas renderer, frame decode, control input
│  │     │  ├─ activity-feed/  approval-card/  routine-editor/
│  │     ├─ hooks/                 # useThing.ts only
│  │     ├─ stores/                # Zustand; client-only state, never server data
│  │     └─ styles/theme.css       # Tailwind CSS-first config; light + dark tokens
│  │
│  ├─ api/                         # Hono. The ONLY process the browser reaches.
│  │  └─ src/
│  │     ├─ main.ts                # boot: config, logger, db, server, graceful shutdown
│  │     ├─ app.ts                 # Hono app: global middleware order, route mounting
│  │     ├─ middleware/
│  │     │  ├─ request-id.ts       # generates/propagates X-Request-Id; first in the chain
│  │     │  ├─ logger.ts           # pino-http with the required fields from 5.6
│  │     │  ├─ session.ts          # cookie -> user; never throws for anonymous
│  │     │  ├─ rbac.ts             # requireRole('admin') and friends
│  │     │  ├─ csrf.ts             # double-submit + Sec-Fetch-Site on unsafe methods
│  │     │  ├─ rate-limit.ts       # Valkey token bucket, with the declared local fallback
│  │     │  └─ errors.ts           # LAST: AppError -> wire envelope (5.5)
│  │     ├─ routes/                # one file per resource, matching the catalogue in Section 7
│  │     ├─ services/              # use-case orchestration; transactions live here
│  │     ├─ authz/authorize.ts     # the ONLY place an RBAC decision is made (Section 8)
│  │     ├─ ws/                    # both sockets: registry, tickets, topics, pub/sub, replay
│  │     └─ auth/                  # OIDC and SAML flows, session issuance and rotation
│  │
│  ├─ orchestrator/                # the agent loop. Calls the gateway; does not contain it.
│  │  └─ src/
│  │     ├─ main.ts                # BullMQ workers, graceful drain
│  │     ├─ loop/
│  │     │  ├─ run.ts              # the state machine from Section 11
│  │     │  ├─ context.ts          # context assembly in the fixed order + the eviction ladder
│  │     │  └─ budget.ts           # step, token, and wall-clock budgets
│  │     ├─ tools/                 # one file per tool namespace; ALL route through @cwh/gateway
│  │     ├─ mcp/                   # client, registry, tool classification
│  │     ├─ memory/                # write, retrieve, end-of-run reflection
│  │     ├─ routines/              # induction and self-healing replay
│  │     └─ workers/               # run, approval-timeout, schedule, reflection, prune
│  │
│  └─ supervisor/                  # owns Docker. No DB, no model, no vault.
│     └─ src/
│        ├─ main.ts                # UNIX socket server + loopback health + metrics listener
│        ├─ docker.ts              # dockerode wrapper: create, start, freeze, stop, reset, reap
│        ├─ computer.ts            # lifecycle state machine, quota and capacity accounting
│        ├─ screencast.ts          # CDP attach/detach, frame relay, depth-1 backpressure
│        ├─ egress-proxy.ts        # the proxy role: allowlist, private-range block, resolve-and-pin
│        └─ token-verify.ts        # verifies gateway action tokens before any execution
│
├─ packages/
│  ├─ contracts/                   # @cwh/contracts — Zod schemas + inferred types. ZERO runtime deps
│  │  └─ src/                      #   beyond zod. Imported by web, api, orchestrator.
│  │     ├─ common.ts              # pagination, envelopes, id and timestamp primitives
│  │     ├─ errors.ts              # the closed error-code enum (Section 7.4.3)
│  │     ├─ content-block.ts       # THE nine-member content-block union (Section 10.5.1)
│  │     ├─ coworker.ts  channel.ts  run.ts  action.ts  policy.ts  approval.ts
│  │     ├─ routine.ts   skill.ts    memory.ts  credential.ts  mcp.ts  connector.ts
│  │     ├─ audit.ts     notification.ts  schedule.ts  user.ts
│  │     └─ ws.ts                  # every server->client event payload schema
│  │
│  ├─ config/                      # @cwh/config — the boot schema and the frozen Config object
│  │  └─ src/schema.ts             #   THE ONLY place process.env is read. Section 33.4.
│  │
│  ├─ db/                          # @cwh/db — Drizzle schema and repositories
│  │  ├─ migrations/               # numbered SQL, forward-only, NNNN_snake_case.sql
│  │  └─ src/
│  │     ├─ schema/                # one file per table cluster (Section 6)
│  │     ├─ repositories/          # the ONLY place SQL is written (5.9)
│  │     └─ client.ts              # pool, transaction helper, tracing hooks
│  │
│  ├─ policy/                      # @cwh/policy — CEL compile, cache, evaluate, explain
│  │  └─ src/
│  │     ├─ compile.ts             # compile + cache; a compile error is a REFUSAL, never a skip
│  │     ├─ decide.ts              # deny-first ordering, fail-closed. 100%-COVERED FILE.
│  │     ├─ context.ts             # the flat context type + list-field capping (Section 16)
│  │     ├─ lint.ts                # the rule linter; label-only and suppressing-label checks
│  │     └─ explain.ts             # human-readable "why" for the audit trail and the UI
│  │
│  ├─ gateway/                     # @cwh/gateway — THE chokepoint. Its own package on purpose.
│  │  └─ src/
│  │     ├─ enforce.ts             # the single call site every governed action passes through.
│  │     │                         #   100%-COVERED FILE. No other export dispatches.
│  │     ├─ token.ts               # action tokens: sign, bind to epoch, redeem, revoke.
│  │     │                         #   100%-COVERED FILE. Holds the PRIVATE key; containers do not.
│  │     ├─ context-builder.ts     # builds the flat CEL context from resolved facts only
│  │     └─ audit.ts               # every decision -> the audit trail, in the same transaction
│  │
│  ├─ vault/                       # @cwh/vault — envelope encryption and injection
│  │  └─ src/
│  │     ├─ unwrap.ts              # ciphertext -> usable secret. 100%-COVERED FILE.
│  │     ├─ wrap.ts  keyring.ts    # data keys, root-key generations, rotation
│  │     └─ inject.ts              # sealed transit to a field or a process env; no plaintext path
│  │
│  ├─ redaction/                   # @cwh/redaction — the never-log list and value-match scrubbing
│  │  └─ src/paths.ts              #   used by api, orchestrator, supervisor and egress-proxy
│  │
│  ├─ model/                       # @cwh/model — ModelProvider interface + implementations
│  │  └─ src/provider.ts  select.ts  anthropic.ts  openai.ts  stub.ts  errors.ts  tokens.ts
│  │
│  ├─ prompts/                     # @cwh/prompts — the system preamble and every fixed prompt,
│  │                               #   versioned, so a prompt change is a reviewable diff
│  ├─ skills/                      # @cwh/skills — template parse, render, secret-marker handling
│  ├─ connectors/                  # @cwh/connectors — gmail, outlook, slack, drive + reach
│  │  └─ src/types.ts              #   one interface, one contract test suite for all four
│  ├─ mcp-directory/               # @cwh/mcp-directory — the bundled first-party MCP server image
│  ├─ observability/               # @cwh/observability — logger, tracer, metric registries
│  ├─ design-tokens/               # @cwh/design-tokens — the token source of truth + contrast tests
│  ├─ computer-protocol/           # @cwh/computer-protocol — the wire contract to a computer
│  │  └─ src/                      #   Zod-validated commands and results, action-token envelope.
│  │                               #   Imported by gateway, supervisor, and the container image.
│  ├─ ui/                          # @cwh/ui — design system: Radix + Tailwind primitives
│  │  └─ src/                      #   Button, Dialog, Table, Toast. NO business logic,
│  │                               #   NO data fetching, NO app-specific vocabulary.
│  └─ testing/                     # @cwh/testing — factories, fixtures, containers, clock control
│     └─ src/factories.ts  containers.ts  clock.ts  db-per-file.ts
│
├─ containers/
│  └─ computer/                    # the coworker computer image. Built WITHOUT workspace source.
│     ├─ Dockerfile
│     ├─ seccomp.json
│     └─ src/                      # control API, Playwright driver, shell executor, token check
│
├─ e2e/                            # EVERYTHING E2E lives here, at the root, not under an app
│  ├─ playwright.config.ts
│  ├─ specs/                       # one file per named scenario (Section 35)
│  ├─ scripts/                     # scripted turn files for the stub model provider
│  └─ support/                     # helpers, including the axe pass every scenario calls
│
├─ bench/                          # load-test plans and results (Section 32)
│  └─ results/
│
├─ scripts/
│  ├─ preflight.sh                 # host checks; reports only, never modifies
│  └─ generate-secrets.sh          # writes ./secrets/* at 0600 and the age identity
│
├─ secrets/                        # gitignored. One value per file, mode 0600. NEVER committed.
│
├─ deploy/
│  ├─ caddy/Caddyfile              # + tls/ and maintenance/
│  ├─ postgres/                    # the pgvector-bearing derived image and init/
│  ├─ apparmor/cwh-computer
│  ├─ prometheus/  grafana/        # dashboards from Section 30
│  └─ scripts/                     # backup, restore, key rotation (Sections 33, 34)
│
└─ docs/
   ├─ spec.md                      # this document
   ├─ adr/                         # one file per ADR, extending Section 4.10
   ├─ runbooks/                    # the day-2 procedures from Section 33
   └─ api/openapi.json             # GENERATED from @cwh/contracts; never hand-edited

Four things about this tree are load-bearing and are not stylistic preferences.

The gateway, the policy engine and the vault are packages, not folders inside an app. They carry the document's hardest guarantees, they are held to per-package and per-file coverage floors that a path inside apps/ cannot express, and they must be unit-testable with no server around them. The orchestrator calls the gateway; it does not contain it.

packages/config is the only place process.env is read. Everything else receives a frozen, fully typed Config. This is enforced by a lint rule, not by convention, because a variable read directly at a call site is a variable that never appears in the boot report and never fails validation.

E2E lives at the repository root, not under apps/web. The suite drives a whole deployment — the api, the orchestrator, a real container, the egress proxy, the policy engine and the audit trail — so filing it under the SPA misdescribes what it tests and puts its Playwright configuration on the wrong side of a package boundary. There is one e2e/ tree and every spec is cited by that path.

deploy/ is the one operations tree. The Compose file, the Caddyfile, the AppArmor profile, the derived Postgres image, the dashboards and the operational scripts all live under it, and Section 33 names those paths directly. There is no second infra/ tree; a repository with two of them grows a Caddyfile in each.

5.2 What Belongs Where, and What Must Never #

5.3 File Naming #

Two of these are enforced rather than encouraged. The snake_case-on-the-wire and camelCase-in-TypeScript boundary is crossed exactly once, in the Zod schemas and Drizzle column mappings; a hand-written toCamel helper or a manual object remap in a route handler is a code-review failure (ADR-011). And the unit in an environment-variable name is the unit the code reads — there is no duration-string parsing anywhere, and a rename that changes a unit without changing the suffix is exactly how a rate limit ends up sixty times wrong.

5.4 Path Aliases and Import Ordering #

Aliases: the workspace packages resolve by their @cwh/* names through pnpm workspace links. Inside an application, ~/ resolves to that application's src/. There is no @/ alias and no deep relative chain — ../../../ is a lint error at depth three.

Import groups, in this order, separated by a blank line and enforced automatically:

// 1. Node built-ins, always node: prefixed
import { randomUUID } from 'node:crypto';

// 2. External packages
import { Hono } from 'hono';
import { z } from 'zod';

// 3. Workspace packages, alphabetically by package name
import { ApprovalRequestSchema } from '@cwh/contracts';
import { approvalRepository } from '@cwh/db';

// 4. Application-internal via the ~ alias, alphabetically
import { requireRole } from '~/middleware/rbac';
import { approvalService } from '~/services/approval';

// 5. Relative, same directory only
import { renderApprovalSummary } from './summary';

// 6. Type-only imports last within each group, using `import type`
import type { AppContext } from '~/app';

verbatimModuleSyntax is on, so a type import that is not written as import type is a compile error, not a bundler optimisation problem.

5.5 The Error-Handling Pattern #

One error type crosses every layer, and exactly one place turns it into a response. The vocabulary is a closed enum, it is the same vocabulary on the HTTP envelope and in a tool result, and what differs between those is the surface, not the code.

// packages/contracts/src/errors.ts
export const ERROR_CODES = [
  'UNAUTHENTICATED', 'SESSION_EXPIRED', 'FORBIDDEN', 'NOT_FOUND', 'CONFLICT',
  'VALIDATION_FAILED', 'RESOURCE_DELETED', 'UNPROCESSABLE', 'RATE_LIMITED',
  'REASON_REQUIRED', 'CONFIRMATION_MISMATCH', 'SELF_AUTHORISATION_REFUSED',
  'POLICY_DENIED', 'POLICY_EVALUATION_FAILED', 'POLICY_STORE_UNAVAILABLE',
  'APPROVAL_REQUIRED', 'APPROVAL_EXPIRED', 'NOT_APPROVER',
  'HUMAN_HAS_CONTROL', 'ACTION_TOKEN_EPOCH_STALE', 'ACTION_SCOPE_MISMATCH',
  'HANDOFF_DEPTH_EXCEEDED', 'HANDOFF_CYCLE_DETECTED', 'HANDOFF_WOULD_WIDEN',
  'CONNECTOR_REACH_UNDETERMINED', 'MODEL_RATE_LIMITED', 'MODEL_UNAVAILABLE',
  'RUN_BUDGET_EXCEEDED', 'AUDIT_UNAVAILABLE', 'INTERNAL_ERROR', 'SERVICE_UNAVAILABLE',
  // …the complete closed enum, with HTTP status, surface and retryability, is in Section 7.4.3.
] as const;
export type ErrorCode = (typeof ERROR_CODES)[number];

// packages/contracts/src/app-error.ts
export interface AppErrorOptions {
  details?: Record<string, unknown>;   // safe to show a user; never a secret, never a stack
  cause?: unknown;
  retryable?: boolean;                 // default false
  logLevel?: 'warn' | 'error';         // default: warn for 4xx, error for 5xx
}

export class AppError extends Error {
  readonly code: ErrorCode;
  readonly status: number;
  readonly details?: Record<string, unknown>;
  readonly retryable: boolean;
  readonly logLevel: 'warn' | 'error';

  constructor(code: ErrorCode, status: number, message: string, opts: AppErrorOptions = {}) {
    super(message, { cause: opts.cause });
    this.name = 'AppError';
    this.code = code;
    this.status = status;
    this.details = opts.details;
    this.retryable = opts.retryable ?? false;
    this.logLevel = opts.logLevel ?? (status >= 500 ? 'error' : 'warn');
  }

  /** The canonical wire envelope. Section 7.4.1 owns the shape; this is its only producer. */
  toWire(requestId: string) {
    return {
      error: {
        code: this.code,
        message: this.message,
        details: this.details ?? {},
        request_id: requestId,
      },
    };
  }

  static notFound(resource: string, id: string) {
    return new AppError('NOT_FOUND', 404, `${resource} not found.`, { details: { id } });
  }
  static forbidden(reason: string) {
    return new AppError('FORBIDDEN', 403, reason);
  }
}

Rules, all enforced in review:

1. Throw AppError, never a bare Error, anywhere a request can reach. A bare Error that escapes is caught by the error middleware, logged at error with its stack, and returned as INTERNAL_ERROR with a generic message. That is a bug, not a pattern.
2. One producer of the envelope. apps/api/src/middleware/errors.ts is the only place toWire is called. No route handler builds an error body. An unmapped exception never reaches the client with its own message.
3. The code must be in the enum, and the enum is checked against the registry in Section 7.4.3 by a build-failing test in both directions. A code in source and not in the registry fails the build; so does a code in the registry that nothing can construct. Inventing a second spelling for an existing condition is the specific failure this test exists to catch.
4. A code whose registered surface is tool may not be constructed with an HTTP status. The factory throws in development and degrades to INTERNAL_ERROR in production if one is.
5. message is user-safe. It is rendered in the UI. No stack traces, no SQL, no internal hostnames, and no credential names that would leak a vault layout to an unauthorized reader.
6. details is structured and safe. { "rule_id": "…" }, { "field": "name" }. Never a raw exception, never a value from the vault, and never a fact the caller is not entitled to — a 423 naming who holds a computer is a directory of who is at which desk unless the caller may already see that person.
7. Wrap, do not swallow. Catching to add context is right; catching to continue silently is a review failure. Use cause so the chain survives.
8. request_id is on every response, success and error, and as the X-Request-Id header. It is generated by the first middleware and threaded through every log line, audit event, and downstream call.
9. The client decodes symmetrically. apps/web/src/api/client.ts parses the envelope back into an AppError so React components branch on code, never on a message string.

5.6 The Logging Pattern #

Structured pino, JSON to stdout, collected by the container runtime. Optional file output exists for sites that need it, with size-based rotation the application configures and an age-based sweep the pruning job performs — but the size cap, not the age cap, is what bounds local history, and a deployment that needs days of it ships logs off-host (Section 33).

Required on every log line, injected by a child logger rather than passed at each call site:

// packages/observability/src/logger.ts
import pino from 'pino';
import { REDACT_PATHS } from '@cwh/redaction';

export const logger = pino({
  level: config.logLevel,
  base: { service: config.service, env: config.env, version: config.imageTag },
  redact: { paths: [...REDACT_PATHS, ...config.extraRedactPaths], censor: '[REDACTED]' },
  formatters: { level: (label) => ({ level: label }) },
});

Never logged, at any level, in any environment:

• Credential values, plaintext or ciphertext, and any data key.
• The root encryption key, the audit fingerprint key, the session secret, the supervisor token, and any action token — not even truncated.
• Session cookies, Authorization headers, OAuth access or refresh tokens, or Set-Cookie.
• Model prompt or completion content. Log the model name, token counts, latency, stop reason, and the provider request id — never the text. Run payloads live in run_steps with their own retention (Section 26), not in the log stream.
• File contents, screen frames, full page HTML, or email bodies. File operations log path and byte size only, and screencast frames are never logged at all.
• Query parameter values on a slow-query warning. The statement fingerprint, never the parameters.
• Personal data beyond a user id and a role. Names and email addresses belong in the database and the audit trail, not in the operational log stream.

Redaction runs two ways, and both are needed. Path-based redaction handles the keys we know the names of. Value-based redaction registers the resolved value of every secret at boot — plus the userinfo component of any connection URL and any headers variable — and scrubs outbound text by exact match, which is what catches a secret that reaches an output channel through a variable nobody thought to flag. A secret shorter than the configured floor is refused at creation time rather than registered, because registering a three-character secret would scrub that substring out of every log line, transcript and audit payload in the process.

Neither is the primary control. The primary control is that these values are not passed to the logger in the first place, and there is a test suite that asserts a serialized log line never matches a set of secret-shaped patterns and that a planted canary value appears in no output channel.

5.7 Async, Cancellation, and AbortSignal #

Cancellation is a product feature — a user can cancel a run, an approval can expire mid-flight, an orchestrator can drain for a deploy — so it is threaded, not bolted on.

1. Every async function that performs I/O takes signal: AbortSignal as its last parameter. Not optional, not defaulted. A function whose I/O cannot be cancelled is a function that will hang a deploy.
2. The signal is created at the entry point — an HTTP request, a BullMQ job, a WebSocket message — and passed down. Composite deadlines use AbortSignal.any([requestSignal, AbortSignal.timeout(ms)]).
3. Every outbound call honours it: fetch, the database client, the Valkey client, the model provider, the supervisor socket, the Docker API. A library that cannot be aborted is wrapped in a race that abandons the promise and marks the operation abandoned in telemetry.
4. Never async without await in a try. Returning a promise from a try block without awaiting it defeats the catch. Enforced by lint.
5. No floating promises. Every promise is awaited, returned, or explicitly handed to a void fireAndForget(p) helper that attaches a logging catch.
6. Concurrency is bounded. No unbounded Promise.all over a user-supplied array. Batch operations use a bounded pool with an explicit limit.
7. Timeouts are explicit at every hop — the model call, the supervisor call, each computer action kind, a connector call, an MCP call, a Docker API call, and a database statement all have their own budget, every one of them a configured value in Section 33 rather than a literal in the code. Each maps to a distinct error code in Section 7, never to a generic hang. The Docker API timeout is not optional: without it a hung daemon is undetectable, because ping keeps succeeding while create blocks forever.
8. Graceful shutdown: on SIGTERM, stop accepting new work, abort the root signal, wait up to the configured drain budget for in-flight work to persist its state, then exit 0. That budget is always set safely below the Compose stop grace period, so the process exits before Docker sends SIGKILL. A run interrupted this way is resumable because every step is persisted before it executes.

5.8 One Zod Schema Per Shape #

There is exactly one definition of any shape that crosses a boundary, it lives in @cwh/contracts, and it is imported by everyone who needs it.

// packages/contracts/src/coworker.ts
import { z } from 'zod';

export const CoworkerVisibility = z.enum(['private', 'team', 'org']);
export const CoworkerStatus     = z.enum(['active', 'disabled', 'hidden']);

export const CreateCoworkerRequest = z.object({
  name: z.string().min(1).max(80),
  title: z.string().min(1).max(120),
  role_description: z.string().min(1).max(8000),
  avatar_seed: z.string().max(64).optional(),
  visibility: CoworkerVisibility.default('private'),
});
export type CreateCoworkerRequest = z.infer<typeof CreateCoworkerRequest>;

export const Coworker = z.object({
  id: z.uuid(),
  name: z.string(),
  title: z.string(),
  role_description: z.string(),
  avatar_seed: z.string(),
  owner_user_id: z.uuid(),
  visibility: CoworkerVisibility,
  status: CoworkerStatus,
  version: z.number().int(),
  created_at: z.iso.datetime(),
  updated_at: z.iso.datetime(),
  deleted_at: z.iso.datetime().nullable(),
});
export type Coworker = z.infer<typeof Coworker>;

Consumed three ways from that one definition:

// apps/api — route validation
app.post('/coworkers', zValidator('json', CreateCoworkerRequest), async (c) => { … });

// apps/web — the same schema validates the form before it is ever sent
const form = useForm({ resolver: zodResolver(CreateCoworkerRequest) });

// apps/orchestrator — tool input schemas handed to the model are generated, not rewritten
const toolSchema = z.toJSONSchema(BrowserClickInput);

Rules: the schema is the source of truth and the TypeScript type is always z.infer, never hand-written alongside it. Wire keys are snake_case inside the schema. .strict() is applied to every request object so an unexpected key is a VALIDATION_FAILED rather than a silent ignore. Response schemas are .strip(), so a column added to a table does not accidentally become public. Every JSONB column has a schema in the same package, and it is validated on write and on read — because a row written by an older version is untrusted input.

5.9 Database Access Layering #

Three layers, one direction, no shortcuts.

route handler  →  service  →  repository  →  Drizzle  →  PostgreSQL
   validates       decides,     the ONLY place a query is written
   and maps        transacts

• Route handlers validate input, resolve the actor, call exactly one service, and map the result to a response. They contain no query, no transaction, and no business rule.
• Services own the use case and the transaction boundary. A transaction begins in a service and never spans an HTTP call, a model call, or a supervisor call — a lock held across a two-minute model call is an outage.
• Repositories are the only place SQL or a Drizzle query builder appears. Each exports narrow, named functions. Raw SQL in a route handler or a service is a code-review failure with no exceptions.

// packages/db/src/repositories/approval.ts
export async function findPendingForApprover(
  tx: Db,
  approverUserId: string,
  page: { limit: number; cursor: Cursor | null },
  signal: AbortSignal,
): Promise<ApprovalRequestRow[]> { … }

export async function markApproved(
  tx: Db, id: string, approverUserId: string, signal: AbortSignal,
): Promise<ApprovalRequestRow> { … }   // asserts state === 'pending'; throws CONFLICT otherwise

Every repository function on a soft-deletable table filters for the tombstone predicate by default and exposes an explicit includeDeleted: true parameter for the two places that legitimately need tombstones — channel history rendering and the audit trail. Forgetting the filter is the single most common bug this layering exists to prevent, so the base query helper applies it and opting out is explicit and greppable.

Repositories take a Db — a pool or a transaction — as their first argument, so any function can be composed into a transaction without a variant. They never authorize; they filter by whatever ownership predicate the service passes. Authorization is a service and middleware concern, and it is decided in exactly one function (Section 8).

The grants are part of the layering, not a deployment detail. The application role holds SELECT, INSERT, UPDATE, DELETE in the application schema and SELECT, INSERT in the audit schema, plus UPDATE on the single chain-head row and nothing else. It never holds TRUNCATE, never holds DDL, and never owns anything. Two separate owner roles exist — one for the application schema, one for the audit schema — so that the credential a migration runs under is not the credential that could rewrite the trail. A test enumerates every relation in the audit schema from the catalogue, including partitions created next month, and asserts the absence of UPDATE and DELETE on each.

5.10 Commits and Branches #

• Trunk-based. main is always releasable and always deployable. Branches are short-lived — under two days — and named <type>/<ticket>-<kebab-slug>, with type from the Conventional Commits set.
• Conventional Commits, with the workspace package as the scope: feat(policy): deny-first evaluation ordering, fix(api): rotate session cookie on role change, docs(spec): expand approval escalation. A breaking change carries ! and a BREAKING CHANGE: footer.
• Squash merge only. One commit per pull request on main, so the history is a list of changes rather than a list of keystrokes. CHANGELOG.md is generated from those messages.
• Every pull request requires: a green CI run — typecheck, lint, unit, integration, E2E, the coverage gate, the generated-registry equivalence tests, the secret scan, and the image audit — at least one approving review, and, for anything touching packages/policy, packages/gateway, or packages/vault, a second review from a maintainer of that area.
• Migrations are additive within a pull request. A pull request may add a migration; it may never edit a migration that has been merged. A merged migration is immutable, because it has run somewhere, and the migration runner verifies every applied file's hash on every boot precisely so that editing history is a hard failure rather than a mystery.
• No direct pushes to main, no force-push to main, no merge commits on main. Enforced by branch protection, not by convention.

5.11 Formatting and Lint #

Prettier owns formatting; ESLint owns correctness and never fights Prettier. Both are installed at their current stable release as development dependencies — they are tooling, not runtime, and they do not appear in the version table in Section 4.

// .prettierrc.json
{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "plugins": ["prettier-plugin-tailwindcss"]
}

// eslint.config.js — flat config, applied to every workspace package
import js from '@eslint/js';
import ts from 'typescript-eslint';
import react from 'eslint-plugin-react';
import hooks from 'eslint-plugin-react-hooks';
import a11y from 'eslint-plugin-jsx-a11y';
import importX from 'eslint-plugin-import-x';

export default ts.config(
  js.configs.recommended,
  ...ts.configs.strictTypeChecked,
  ...ts.configs.stylisticTypeChecked,
  {
    languageOptions: { parserOptions: { projectService: true } },
    plugins: { 'import-x': importX },
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/require-await': 'error',
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/consistent-type-imports': ['error', { fixStyle: 'separate-type-imports' }],
      '@typescript-eslint/no-unnecessary-condition': 'error',
      'no-console': 'error',                       // use the shared logger
      'no-restricted-syntax': ['error',
        { selector: 'TSEnumDeclaration', message: 'Use a const object + union type; enums are not erasable.' },
      ],
      'no-restricted-properties': ['error',
        { object: 'process', property: 'env',
          message: 'Read configuration from @cwh/config. It is the only module permitted to touch process.env.' },
      ],
      'import-x/order': ['error', { 'newlines-between': 'always', alphabetize: { order: 'asc' } }],
      'import-x/no-relative-parent-imports': ['error', { ignore: ['^\\.\\./[^/]+$'] }],
    },
  },
  {
    // @cwh/config is the one place that may read the environment.
    files: ['packages/config/src/**'],
    rules: { 'no-restricted-properties': 'off' },
  },
  {
    files: ['apps/web/**/*.tsx'],
    plugins: { react, 'react-hooks': hooks, 'jsx-a11y': a11y },
    rules: {
      ...hooks.configs.recommended.rules,
      ...a11y.configs.strict.rules,
      'react/jsx-no-bind': 'off',
    },
  },
  {
    // Nothing outside the gateway may reach the computer protocol's execute path.
    files: ['apps/orchestrator/src/**', 'apps/api/src/**'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { group: ['@cwh/computer-protocol/execute*'],
          message: 'All execution goes through @cwh/gateway. There is no bypass.' },
      ]}],
    },
  },
  {
    // Coverage cannot be manufactured by exclusion on the four enforcement-path files.
    files: [
      'packages/gateway/src/enforce.ts', 'packages/gateway/src/token.ts',
      'packages/policy/src/decide.ts',   'packages/vault/src/unwrap.ts',
    ],
    rules: {
      // A coverage-ignore comment in one of these four files would let the
      // 100% threshold be met by exclusion rather than by tests.
      'cwh/no-coverage-ignore': 'error',
    },
  },
  {
    files: ['apps/web/**'],
    rules: {
      'no-restricted-imports': ['error', { patterns: [
        { group: ['@cwh/db', '@cwh/policy', '@cwh/gateway', '@cwh/vault', '@cwh/model',
                  'ioredis', 'pg', 'drizzle-orm'],
          message: 'The browser bundle may not import server packages.' },
      ]}],
    },
  },
  {
    files: ['e2e/**'],
    rules: {
      'no-restricted-syntax': ['error',
        { selector: "CallExpression[callee.property.name='waitForTimeout']",
          message: 'Wait for a condition, never for a duration.' },
      ],
    },
  },
);

Additional gates in CI, all blocking: pnpm -r typecheck with zero errors; pnpm -r lint with --max-warnings=0, because a warning nobody fixes is a lie; prettier --check; zero occurrences of TODO, FIXME, or XXX in apps/ and packages/; a secret scan that fails on anything under secrets/ reaching a commit; the image audit asserting no devDependencies and no TypeScript compiler in a runtime image, and that no computer image was built with --no-sandbox; and the generated-registry equivalence tests that compare the closed enums in @cwh/contracts and the configuration schema in @cwh/config against the tables in Sections 7, 16, 26 and 33 in both directions.

5.12 TypeScript Compiler Options #

// tsconfig.base.json — every package extends this and overrides only lib/jsx/outDir
{
  "compilerOptions": {
    "target": "es2024",
    "lib": ["es2024"],
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noPropertyAccessFromIndexSignature": true,
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "incremental": true,
    "forceConsistentCasingInFileNames": true
  }
}

apps/web additionally sets "lib": ["es2024", "dom", "dom.iterable"], "jsx": "react-jsx", and "noEmit": true because Vite emits. Workspace packages emit declarations to dist/ via tsc -b; server applications compile to dist/ and run with node dist/main.js. There is no bundler on the server, deliberately: stack traces point at real files and a production debugging session does not start with a source map.

5.13 Reviewer's Checklist — the Fifteen Things That Fail Code Review #

1. A raw SQL string or Drizzle query outside packages/db/src/repositories/. No exceptions, not for a "quick" count, not in a script.
2. A query on a soft-deletable table that does not filter out tombstones, or an includeDeleted: true without a comment naming which of the two legitimate cases it is.
3. A path to a computer that does not go through @cwh/gateway. Any new tool must route through the gateway, and the lint rule that enforces it must not be suppressed.
4. A policy or gateway code path that can return allow on error, on a compile failure, on a timeout, on an unreadable rule store, on an unwritable audit row, or on no match. Fail-closed is the product; a catch that returns a permissive default is the single worst change that can be made to this codebase.
5. A sensitive-action classification satisfied by a page-authored string, or a page-authored string in a clause that cancels a structural match. Both are save-time errors on a seeded rule and warnings on an admin-authored one, and both are review failures in code.
6. A secret in a place a secret must never be: a log line, a run_steps payload, a message body, an error details, a WebSocket frame, a screenshot annotation, an API response, or a test fixture committed to the repository.
7. any, a non-null assertion (!), or an unchecked type assertion (as Foo). Use a Zod parse or a type guard. as const and the assertion in an exhaustiveness check are the only permitted ones.
8. A second definition of a shape or a second spelling of an error code that already exists in @cwh/contracts, or a hand-written type sitting beside a Zod schema instead of z.infer.
9. Hand-written case conversion between snake_case and camelCase anywhere but the Drizzle column map and the Zod boundary schemas.
10. An I/O function without an AbortSignal parameter, a floating promise, an unbounded Promise.all over a user-controlled array, or an outbound call with no timeout.
11. A transaction that spans a network call to the model provider, the supervisor, a connector, or an MCP server.
12. A new environment variable that is not in the catalogue in Section 33, in the boot schema, and in .env.example — or any read of process.env outside packages/config. A rename that changes a unit without changing the name's suffix is worse than a missing variable and is an automatic block.
13. A migration that edits an already-merged migration file, or a new migration without its documented manual rollback note, or one that runs CREATE INDEX CONCURRENTLY without the non-transactional marker on its first line.
14. A new user-facing surface with no keyboard path, no visible focus state, no accessible name, or a contrast ratio below WCAG 2.2 AA in either theme. Both themes, every time.
15. A change to the gateway, the policy engine, or the vault without tests that cover every branch — including every refusal branch — or a coverage-exclusion comment anywhere in the four 100%-covered enforcement files. Those thresholds fail the build, not the reviewer.

6. Data Model & Database Schema #

This section is the authoritative definition of persistent state in CoWorker Hub. Every other section refers to these tables and columns by name rather than restating them. The schema targets PostgreSQL 18 with the pgvector extension, is owned by the packages/db workspace package, and is applied exclusively through numbered drizzle-kit migrations (§6.21).

6.1 Modelling Conventions #

These conventions are applied without exception. Where a table deviates, the deviation is called out explicitly in that table's entry.

6.2 Entity Map #

Sixty tables in eight logical clusters. Cluster letters are used throughout this section and in the DDL ordering of §6.12.

Every table in the product is here. No other section contains a CREATE TABLE, and a feature section that needs a table describes its behaviour and cites this one for its shape. The rule exists because the executor is told to build the schema from this section alone: a table defined only in a feature section is a table that does not get created, and when that table is knowledge_acl the result is not a missing feature but a knowledge retriever with no access-control join — a silent authorisation bypass that every test still passes.

6.3 Shared Database Objects #

6.3.1 Extensions #

uuidv7() is a PostgreSQL 18 built-in and needs no extension. uuid-ossp is deliberately not installed.

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

6.3.2 Database roles #

Four roles and two schemas, created by the first migration. The separation is what makes the append-only guarantee on audit_events real rather than aspirational (§6.18).

Two schemas. public holds the application's fifty-seven tables. audit holds audit_events and its partitions, audit_chain_head, and audit_seals, and nothing else. The split is not organisational: it is what lets the append-only grant be written against a schema, so that the restriction is inherited by every monthly partition the maintenance job creates rather than having to be re-applied to each one and forgotten once.

6.3.3 The shared row-metadata trigger #

One function, attached to every table that has updated_at. It also drives optimistic concurrency: if the caller did not change version explicitly, it is incremented. Callers never set updated_at themselves.

CREATE OR REPLACE FUNCTION set_row_metadata() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
  NEW.updated_at := now();
  IF to_jsonb(NEW) ? 'version' AND NEW.version = OLD.version THEN
    NEW.version := OLD.version + 1;
  END IF;
  RETURN NEW;
END;
$$;

-- Attached per table, e.g.:
CREATE TRIGGER trg_users_row_metadata
  BEFORE UPDATE ON users
  FOR EACH ROW EXECUTE FUNCTION set_row_metadata();

The to_jsonb(NEW) ? 'version' guard lets a single function serve both versioned and unversioned tables, so there is exactly one trigger function in the database. audit_events and audit_seals get no such trigger — they are never updated at all.

6.3.4 The uuidv7 partition-boundary function #

Four tables are range-partitioned on their id column (§6.19). This is possible — and keeps id uuid PRIMARY KEY intact, per convention C1 — because a v7 UUID encodes a 48-bit big-endian millisecond timestamp in its first six bytes and PostgreSQL compares uuid values bytewise. A UUID whose first six bytes are the millisecond value of ts, whose version nibble is 7, and whose remaining bits are zero therefore sorts immediately below every real v7 UUID generated at or after ts, and above every one generated before it. That makes it an exact, inclusive lower bound.

CREATE OR REPLACE FUNCTION uuidv7_boundary(ts timestamptz) RETURNS uuid
LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
  SELECT encode(
           overlay(
             '\x00000000000070000000000000000000'::bytea
             PLACING substring(
               int8send((floor(extract(epoch FROM ts) * 1000))::bigint) FROM 3 FOR 6)
             FROM 1 FOR 6),
           'hex')::uuid;
$$;

Partition bounds are always computed with this function, never hand-written. Because the variant bits in the boundary are zero (0x00) while every real v7 UUID has variant bits 0b10 (0x80–0xBF), a boundary value can never collide with a generated key.

6.3.5 Standard column families #

Rather than repeating identical column definitions sixty times, three families are defined once and referenced by name in the per-table entries.

6.4 Cluster A — Identity & Access #

6.4.1 users #

One row per human employee who has ever signed in, plus any pre-provisioned invitee. Users are never deleted, only disabled or anonymised, because audit_events must retain a resolvable actor forever.

Foreign keys. identity_provider_id → identity_providers is ON DELETE SET NULL ON UPDATE CASCADE: removing a provider must not remove people, it only orphans the linkage so the next login re-binds.

Indexes.

Checks. ck_users_deactivated_consistency: (status = 'deactivated') = (deactivated_at IS NOT NULL). ck_users_anonymized_consistency: (status = 'anonymized') = (anonymized_at IS NOT NULL).

The erasure procedure, since this table is where it lands. A subject's right to erasure is satisfied by pseudonymising this row and hard-deleting the subject-scoped tables — memories about them, notifications addressed to them, sessions, notification_preferences. audit_events is neither modified nor deleted, and it does not have to be: an audit row carries no display name for a user actor (§6.11.1), only actor_user_id, and the name is resolved on read by joining this table. Once the row is tombstoned, every historical audit line renders the pseudonym — with zero audit rows rewritten and the hash chain intact. That is the entire mechanism. There is no second erasure design, no per-subject encryption of audit payloads, and no pii column anywhere in this schema; a payload scan for incidental personal data is a report, and what it reports is fixed at the emitting site, not by rewriting history.

The one thing that can stop it is a matching row in legal_holds, which records anonymization_blocked_reason and answers LEGAL_HOLD_ACTIVE. A hold outranks an erasure request until it is lifted, and the request is executed automatically when the last matching hold ends.

6.4.2 identity_providers #

Configuration for each configured company login method. There is no local password authentication anywhere in the product; sign-in is always federated.

Foreign keys. client_secret_credential_id → credentials is ON DELETE RESTRICT: deleting a credential that a live login method depends on must fail loudly, not silently break sign-in.

Checks. ck_idp_domains_required: cardinality(allowed_email_domains) > 0 OR NOT enabled. A provider may be saved without an allowlist only while it is disabled, so the unsafe state is unreachable rather than merely discouraged.

Indexes. uq_identity_providers_slug UNIQUE (slug); uq_identity_providers_name_lower UNIQUE (lower(name)); idx_identity_providers_enabled (enabled) WHERE enabled for the sign-in page query.

6.4.3 sessions #

One row per browser session. Sessions are hard-deleted, never soft-flagged — on sign-out, on revocation, on rotation, and by the hourly sweep of expired rows. There is deliberately no revoked_at column, because a row that says "revoked" is a row that can be un-said. Replay detection survives the delete through a short-lived tombstone held outside the database (§7.7.1).

The cookie carries <session_id>.<secret>. Only session_id is stored in the clear, as the lookup key; the secret is stored only as its SHA-256 and compared in constant time, so a database dump cannot be replayed as a login and a timing oracle cannot walk the verifier.

Indexes. The primary key on id is the hot path — one lookup per request, keyed by the session_id half of the cookie; idx_sessions_user (user_id, issued_at DESC) for "my sessions" and bulk revocation; idx_sessions_expiry (expires_at) for the retention sweep; idx_sessions_rotated_from (rotated_from_session_id) WHERE rotated_from_session_id IS NOT NULL.

6.4.4 teams #

A lead owns a team. Teams exist for approval routing (§6.8.4 and the Policy & Permissions Engine section) and for team-visibility scoping of coworkers, channels, and skills. Teams are archived rather than deleted so that historical approvals remain explainable.

Foreign keys. lead_user_id → users is ON DELETE RESTRICT. Since users are never hard-deleted this can only fire during a data-repair operation, and it should fire: a team without a lead has no escalation path.

Indexes. uq_teams_slug UNIQUE (slug); uq_teams_name_lower UNIQUE (lower(name)) WHERE archived_at IS NULL; idx_teams_lead (lead_user_id) for "teams I lead".

6.4.5 team_members #

Foreign keys. Both cascade: membership has no meaning without either side, and membership rows are not themselves audit evidence — the corresponding audit_events row is.

Indexes. uq_team_members_team_user UNIQUE (team_id, user_id); idx_team_members_user (user_id) for "which teams am I in", used on every approval-routing evaluation.

6.4.6 role_definitions #

A three-row reference table seeded by migration. It exists purely so the admin console can render role labels, descriptions, and a stable escalation ordering without hard-coding copy in the frontend. It is never consulted for an authorization decision — users.role and the fixed user_role enum are the only inputs to that.

6.5 Cluster B — Coworkers & Computers #

6.5.1 coworkers #

The durable bot profile. Everything a coworker "is" between runs lives here; everything it does lives in runs, actions, and audit_events. Soft-deleted: a removed coworker's channels stay readable as read-only tombstones.

Foreign keys. owner_user_id → users is ON DELETE RESTRICT — a coworker with no owner has no approver, which would violate the governance model. Ownership is transferred through POST /api/v1/coworkers/{id}/transfer (§7.17.5) before a user can be removed. team_id → teams is ON DELETE SET NULL; losing a team degrades escalation to "any admin" rather than breaking the coworker. default_channel_id → channels is ON DELETE SET NULL and is declared DEFERRABLE INITIALLY DEFERRED because coworker and channel are created in one transaction that references each other.

Indexes.

Checks. ck_coworkers_team_visibility: visibility <> 'team' OR team_id IS NOT NULL — a team-visible coworker must have a team.

6.5.2 computers #

One row per coworker container. Exactly one live row per coworker, enforced by a unique index. Rows are hard-deleted when a computer is destroyed; the container's whole history survives in actions and audit_events, so nothing of record is lost.

Foreign keys. coworker_id → coworkers cascades: the container is an attribute of the coworker, and deleting the coworker destroys the container.

Indexes. uq_computers_coworker UNIQUE (coworker_id); uq_computers_container_name UNIQUE (container_name) WHERE container_name IS NOT NULL; idx_computers_state (state, state_changed_at) for the supervisor reconciliation loop; idx_computers_idle (last_active_at) WHERE state IN ('ready','busy') for the idle-stop sweep; idx_computers_workspace (workspace_bytes DESC) for the admin storage view.

Checks. ck_computers_running_has_container: state IN ('stopped','error') OR container_id IS NOT NULL.

6.5.3 control_sessions #

A human takeover of a coworker's computer. While a row is active, the computer sits in human_control and every coworker-initiated action is refused outright with HTTP 423 (§7.4) — never queued.

Indexes. uq_control_sessions_active UNIQUE (computer_id) WHERE state = 'active' — the constraint that makes "one human at a time" a database invariant rather than an application convention; idx_control_sessions_user (user_id, started_at DESC); idx_control_sessions_expiry (last_heartbeat_at) WHERE state = 'active' for the expiry sweep; idx_control_sessions_coworker (coworker_id, started_at DESC).

Checks. ck_control_sessions_released: (state = 'active') = (released_at IS NULL).

6.5.4 screen_frame_segments #

The index of the encrypted screen-frame archive. No screen frame is ever stored in PostgreSQL. When an admin enables the retention window (default: off, maximum 24 hours — Section 18), frames are grouped into 60-second segments, each encrypted with AES-256-GCM under its own data key, and written as files to a dedicated Docker volume. This table holds one row per segment: where the file is, what period it covers, and the wrapped key needed to read it. Rows are hard-deleted by the pruning job, and the file is unlinked before the row, so a crash leaves an orphan row the next pass re-handles rather than an orphan file nobody indexes.

The rationale is stated here because it is the reason the table looks like this: a frame is an uncontrolled screenshot that may hold a password, a customer record or a colleague's private message. Keeping the pixels out of the primary datastore keeps them out of the backup path, out of every replica, and out of every dump taken for an unrelated purpose — and multi-megabyte binaries in rows would destroy vacuum performance besides. Section 18 owns the capture, encryption and pruning behaviour; this entry owns the shape.

Foreign keys, all real. Unlike a per-frame table, this one is written at most once per computer per minute, so referential integrity costs nothing and is kept. Both computer_id and coworker_id cascade: destroying either destroys the index rows in the same transaction, and the pruning job then unlinks the files those rows named. run_id and control_session_id are ON DELETE SET NULL — losing the association must never silently orphan an encrypted file.

Indexes. uq_screen_frame_segments_path UNIQUE (storage_path); idx_screen_frame_segments_expiry (expires_at) for the 5-minute pruning pass; idx_screen_frame_segments_lookup (computer_id, started_at DESC) — the replay query; idx_screen_frame_segments_run (run_id) WHERE run_id IS NOT NULL; idx_screen_frame_segments_coworker (coworker_id) for the delete-a-coworker sweep.

Checks. ck_screen_frame_segments_window: ended_at >= started_at. ck_screen_frame_segments_scope: num_nonnulls(run_id, control_session_id) >= 1 — a segment always belongs to something, so no archive file can exist that no retention scope accounts for.

6.6 Cluster C — Conversation #

6.6.1 channels #

A durable conversation. direct channels hold exactly one human and one coworker; group channels hold any mix of humans and coworkers with a designated coordinator. Channels survive process restarts because they are database rows, not in-memory sessions.

Foreign keys. All four are ON DELETE SET NULL: a channel outlives every entity it points at. last_message_id is DEFERRABLE INITIALLY DEFERRED because message insert and channel update happen in one transaction.

Indexes. idx_channels_last_message (last_message_at DESC NULLS LAST) WHERE deleted_at IS NULL; idx_channels_team_visibility (team_id, visibility) WHERE deleted_at IS NULL; idx_channels_kind (kind) WHERE deleted_at IS NULL; idx_channels_name_trgm GIN (name gin_trgm_ops); idx_channels_coordinator (coordinator_coworker_id) WHERE coordinator_coworker_id IS NOT NULL.

Checks. ck_channels_group_named: kind <> 'group' OR name IS NOT NULL. ck_channels_direct_unnamed: kind <> 'direct' OR coordinator_coworker_id IS NULL. ck_channels_team_visibility: visibility <> 'team' OR team_id IS NOT NULL.

6.6.2 channel_members #

Polymorphic membership: exactly one of user_id or coworker_id per row. Also carries per-user read state, which avoids a separate read-receipt table.

Indexes. uq_channel_members_user UNIQUE (channel_id, user_id) WHERE user_id IS NOT NULL; uq_channel_members_coworker UNIQUE (channel_id, coworker_id) WHERE coworker_id IS NOT NULL; idx_channel_members_user (user_id, channel_id) WHERE left_at IS NULL — the "my channels" query and the per-request authorization check, run on every channel read; idx_channel_members_coworker (coworker_id) WHERE left_at IS NULL.

Checks. ck_channel_members_xor: num_nonnulls(user_id, coworker_id) = 1. ck_channel_members_read_state: coworker_id IS NULL OR last_read_message_id IS NULL — coworkers do not carry read state; their context window is assembled per run.

6.6.3 messages #

Durable chat messages. Range-partitioned quarterly on id (§6.19). Soft-deleted so a deletion leaves a visible tombstone rather than silently rewriting history.

Foreign keys and the partition exception. channel_id, author_user_id, author_coworker_id, and the SOFTDEL actor all carry real foreign keys. run_id, thread_root_id, and reply_to_message_id do not, because PostgreSQL cannot create a foreign key pointing at a partitioned table's non-partition- key-aligned rows efficiently and self-references across partitions would force every insert to probe every partition. Those three are validated in the application layer and are always read with an explicit join guard.

Indexes.

Checks. ck_messages_author_xor: (author_kind = 'user' AND author_user_id IS NOT NULL AND author_coworker_id IS NULL) OR (author_kind = 'coworker' AND author_coworker_id IS NOT NULL AND author_user_id IS NULL) OR (author_kind = 'system' AND author_user_id IS NULL AND author_coworker_id IS NULL).

6.6.4 files #

Every byte-carrying artifact: user uploads, coworker-produced artifacts, knowledge source documents, and exports. Bytes live on the cwh-files Docker volume under a sharded path; the row is the index. There is no separate attachments join table — a file points at its message.

Indexes. uq_files_storage_key UNIQUE (storage_key); idx_files_message (message_id) WHERE message_id IS NOT NULL; idx_files_channel (channel_id, created_at DESC) WHERE deleted_at IS NULL; idx_files_checksum (checksum_sha256) for dedupe; idx_files_scan_pending (scan_state) WHERE scan_state = 'pending' for the scanner worker; idx_files_expiry (expires_at) WHERE expires_at IS NOT NULL.

Checks. ck_files_scan_terminal: scan_state = 'pending' OR scanned_at IS NOT NULL. A file is only downloadable when scan_state IN ('clean','skipped'); the API enforces this and returns VIRUS_DETECTED otherwise (§7.16.4).

6.7 Cluster D — Run Engine #

6.7.1 runs #

One unit of coworker work inside a channel. A run is the durable spine of the agent loop (Section 11): every step is persisted, so an orchestrator restart resumes rather than restarts.

Indexes.

Checks. ck_runs_terminal_consistency: (state IN ('succeeded','failed','cancelled')) = (finished_at IS NOT NULL). ck_runs_cancelled_reason: state <> 'cancelled' OR cancel_reason IS NOT NULL.

6.7.2 run_steps #

One model turn or one tool call. Range-partitioned monthly on id (§6.19). Append-mostly: a step is inserted when it starts and updated exactly once when it finishes.

Indexes. uq_run_steps_run_index UNIQUE (run_id, step_index) per partition — makes step numbering collision-proof and gives the transcript query its ordering; idx_run_steps_run (run_id, step_index); idx_run_steps_action (action_id) WHERE action_id IS NOT NULL; idx_run_steps_running (state) WHERE state = 'running' for stuck-step detection.

6.7.3 actions #

A single governed act. Every row is written before execution with its policy decision already recorded, then updated once with its result. This ordering is the reason the audit trail can prove that nothing executed without a decision. Range-partitioned monthly on id (§6.19).

Indexes.