# Production Readiness Audit

Last updated: 2026-06-02.

This audit records the current delta between the repository and a polished
enterprise-production target. It is based on local source inspection, targeted
validators, GitHub security API checks, and parallel focused reviews across
security, architecture, correctness, CI/release, testing, dead code, and
documentation.

## Current Verdict

Open Cowork has a strong production baseline: Electron isolation is strict,
Cloud tenant boundaries are guarded, release supply-chain controls are mature,
and deployment templates have explicit production gates. No critical issue was
found in the current review.

The remaining work is concentrated in two areas:

- maintainability guardrails for the largest Cloud compatibility facades and
  generated or vendored surfaces
- shutdown and backpressure behavior for long-lived Cloud streams and queues

## Verified Baseline

- GitHub code scanning: 0 open alerts on `master` at
  `854fbd0eeaf02cfd3ac5c71836b279cf605c2280`.
- Dependabot alerts: 0 open alerts at the same point-in-time check.
- GitHub Actions checks on that `master` SHA were green for deploy, CodeQL,
  build, coverage, validate, docs, cloud-gates, macos-build, and linux-package.
- Secret scanning API returned 404 for this repository, which indicates secret
  scanning is not enabled or not available to the current token. Treat that as
  an external repository-governance gap until repo settings prove otherwise.
- Targeted local validators passed for deployment configuration, release gates,
  launch readiness, launch evidence manifest, private beta package validation,
  lint, preload channel checks, shared dist checks, and coverage summary.

## Fixed During This Audit

- Local/demo Cloud compose templates now publish Cloud, Gateway, and MinIO ports
  on `127.0.0.1` by default, with opt-in published-address environment
  variables for operators that intentionally expose them.
- `scripts/validate-deployment-configs.mjs` now rejects bare public demo port
  mappings for the Cloud compose templates.
- Deployment artifact tests now assert loopback compose defaults.
- The Workflow tool bridge now verifies bearer tokens with
  `timingSafeEqual`, matching the Agent tool bridge, with a same-length
  wrong-token regression test.
- Local credential editor IPC now returns descriptor-aware masked secret fields
  instead of raw provider or integration secrets. Non-secret descriptor fields
  can still be shown for editing, and echoed mask sentinels preserve the stored
  secret on save.
- Cloud worker command execution now aborts on lease-renewal loss, propagates
  `AbortSignal` through runtime command calls, uses stable OpenCode message IDs
  for prompt retries, and has regressions for active and cached lease renewal
  failure paths.
- Cloud observability hot paths are best-effort: composite adapters isolate
  failing sinks, worker/scheduler/HTTP record helpers suppress telemetry sink
  failures, and OTLP export uses bounded queues, drop counters, and periodic
  flush.
- Cloud HTTP shutdown now closes replay polling and active SSE streams before
  awaiting `server.close()`, with lifecycle regressions for open streams and
  shutdown during replay loading.
- Release promotion now has a separate tier-aware validator. CI and release
  preflight prove the public `local-self-host-beta` claim, and hosted
  promotion requires a private manifest with `private-pass` evidence plus
  strict per-item report metadata for load, soak, failover, restore, BYOK,
  support, rollback, commit SHA, image digests, and sanitized environment
  profile.
- Dead-code coverage now includes all source workspace packages in `knip.json`,
  including Gateway apps, channel/provider packages, and gateway test utilities.
  `tests/package-scripts.test.ts` derives the expected workspace list from
  actual `apps/*`, `packages/*`, and `mcps/*` package directories so future
  source workspaces cannot silently fall out of the dead-code gate.
- Cloud and Gateway Helm charts now default service-account token automounting
  to `false`; Gateway has an explicit service-account opt-in surface, and the
  static deployment validator checks the rendered chart templates keep that
  control wired.
- Dependabot now governs the digest-pinned Cloud and Gateway Dockerfiles with
  monthly Docker ecosystem updates, and contributor setup docs now match the
  enforced Node `>=22.12` engine.
- Telegram webhook ingress now deduplicates authenticated `update_id` values
  before handing updates to grammy, releases the claim if handling fails, and
  preserves Telegram `update_id` as the provider event id when mapping messages
  and callback interactions.
- Workflow run threads now start the same session-status reconciliation safety
  net used by normal prompts. If a runtime `session.idle` event is missed, the
  status poll fallback finalizes the saved workflow run instead of leaving it
  `running` until restart recovery marks it failed.
- Release policy now verifies the exact documented desktop artifact matrix
  before publish eligibility: macOS `x64`/`arm64` `.dmg` and `.zip`, Linux
  `x64` `.AppImage` and `.deb`, plus signed-only `latest-mac.yml` feed
  metadata. Fixture tests reject missing formats, missing architectures, and
  unexpected installer artifacts.
- OCI images now remain on release-candidate tags until the protected final
  publish job has downloaded and validated desktop artifacts, OCI evidence,
  SBOMs, checksums, and attestations. Final `v*` and unprefixed version tags
  are promoted immediately before GitHub Release creation, and both tags are
  verified back to the signed/scanned digest.
- Performance regression checks now require benchmark-name parity in both
  directions. New benchmarks without checked-in baselines fail `perf:check`,
  and the downstream catalog relationship benchmark is represented in every
  committed baseline.
- Coverage summary now has source-inventory ratchets for Node, Shared Package,
  and Workspace Node coverage inputs. CI still enforces the existing line,
  function, and branch thresholds, and now also fails if LCOV stops
  representing at least 90% of the configured production/shipped source
  inventory for those suites.
- Linux release artifacts now run the same packaged desktop smoke gate as CI:
  the release workflow resolves the packaged Linux executable with the shared
  resolver script, launches the packaged app under `xvfb`, and only uploads
  Linux release artifacts after that smoke passes.
- Production deployment smoke now has a fail-closed strict wrapper. It requires
  authenticated Cloud and managed Gateway endpoints, verifies runtime status,
  worker heartbeat visibility, Cloud/Gateway operator metrics, Desktop/Gateway
  mutation coverage with token revocation rejection, and Continuation rich
  projection with ephemeral-token cleanup.
- The `@open-cowork/cloud-client` and `@open-cowork/shared` manifests now
  match their documented workspace/source-package status: both are private,
  expose no `publishConfig`, and the Cloud client boundary test prevents an
  accidental npm-publishable state before standalone SDK publication,
  provenance, and support ownership exist.
- Workflow draft creation is now explicitly local-only across the renderer and
  shared preload contract: `workflows.startDraft` no longer advertises
  workspace options that the IPC handler intentionally rejects for non-local
  workspaces.
- The docs Mermaid runtime is now regenerated from the locked
  `mermaid@11.15.0` dependency, recorded in a version/hash manifest, and
  checked by lint so the self-hosted docs bundle cannot drift silently from the
  package lock.
- Webhook and Slack replay caches now enforce both per-source and global caps.
  A hot bridge target or Slack team cannot evict another source's replay claim
  before the signature window expires.
- Expired session lease and workflow claim reapers now process bounded batches
  per transaction, use expiry-leading Postgres indexes for global recovery
  scans, build those indexes concurrently outside the startup migration
  transaction, drain only a capped number of batches per worker/scheduler tick,
  and emit drain-cap-hit metrics when a tick exhausts the configured recovery
  cap.
- Workspace SSE reconnects now use retained-stream cursor metadata to detect
  retention gaps and replay only events newer than the client cursor. Gap
  detection no longer loads all retained workspace events from sequence `0`.
- Product diff fallback rows and aggregate summaries now carry explicit
  synthetic/mixed provenance when they are inferred from projected tool output
  instead of OpenCode SDK snapshot diffs, and the diff dialog plus thread
  summaries label those values as estimated.
- Runtime status now exposes a typed readiness/doctor timeline while preserving
  the existing `ready`/`error` status API. Diagnostics export includes redacted
  doctor JSON and sanitizes status, JSON sections, log output, and log-path
  headings.
- Shared projection contracts now include exact-identity fence tokens,
  checkpoints, fence-observed checks, and versioned automation event envelopes.
- Cloud session command mutation responses, including Gateway/channel prompt
  and approval/question routes, now return a `projectionFence` only when the
  refreshed response view proves the session projection advanced after a
  processed command; queued or unobserved commands return `null`.
- Capability bundle manifests now have shared validation, install/update
  dry-run, and uninstall planners that fail closed for unsupported product modes,
  unclassified OpenCode plugins, dangerous MCP URL/stdio settings, and
  user-owned resource conflicts while preserving user-owned resources on
  uninstall.
- Runtime diagnostics now export provider, model, MCP, and skill provenance
  with stable reason codes while redacting credential values, raw headers, env
  values, and local command payloads.
- OpenCode compatibility now has a release-grade proof command and fixture:
  `pnpm proof:opencode:compatibility` validates the runtime diagnostics
  registry, exact bundled source version, proving tests, blocked plugin policy,
  and shim/private-assumption removal discipline before release.
- Canonical resource identity, remote approval policy, semantic UI status/action
  bridge/MCP tools, delegated permission inheritance checks, scoped file
  sessions with revision-checked writes and audit events, loopback-only
  headless check/start/status/doctor/stop state, sandbox mount/component policy,
  Docker/Apple Container lifecycle planning, and a strict sandboxed no-reply
  OpenCode session proof command now have typed contracts and focused
  fail-closed tests.
- Local release scenario evidence now has a six-scenario suite and runner wired
  into CI/release gates; it writes redacted JSON/Markdown evidence without
  replacing deterministic tests.

## High Priority

No open high-priority findings remain after the current audit remediations.

## Medium Priority

- Workspace coverage gates are too broad and low for deployable workspace code:
  `lines: 40`, `functions: 28`, and `branches: 68`. Split thresholds by
  package/service and remove generated dist noise from source coverage once the
  deployable workspaces have enough direct source-level coverage to support
  that stricter ratchet.
- Recovery and failover drills are currently evidence wrappers for public CI.
  Add an executable local compose recovery drill and require private
  environment drill evidence for hosted promotion.
- Queue processing needs fairness and backpressure caps across hot sessions,
  gateway deliveries, providers, and bindings.
- History replay still has a large heuristic child-task binding path. Persist
  live binding decisions or require explicit child session ids, keeping
  heuristic replay quarantined as fallback.
- Workflow setup policy is duplicated across kickoff prompt, generated agent
  config, and skill text. Centralize policy in a typed source and generate
  downstream text from it.

## Low Priority

- Cloud compatibility facades remain near their documented budgets:
  `postgres-control-plane-store.ts`, `in-memory-control-plane-store.ts`, and
  `session-service.ts` should be decomposed further before adding major Cloud
  scope, then budgets should ratchet down.
- TypeScript strictness can still improve with staged adoption of
  `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
  `noImplicitOverride`, and stronger promise/`any` lint rules.
- Remaining renderer HTML sinks are intentionally sanitized, but should be
  tracked by an explicit sink registry and regression tests.
- Docs roadmap references should be periodically reconciled with closed GitHub
  issue state so public docs do not imply active work that has already shipped.

## Validation Notes

Commands run locally during this audit included:

```bash
node scripts/run-node-tests.mjs tests/cloud-deployment-artifacts.test.ts
node scripts/run-node-tests.mjs tests/workflow-runtime.test.ts
node scripts/validate-deployment-configs.mjs
node scripts/lint.mjs
node scripts/check-preload-channels.mjs
node scripts/check-shared-dist.mjs
node scripts/run-node-tests.mjs tests/package-scripts.test.ts
node --no-warnings --experimental-strip-types --test tests/coverage-summary.test.ts tests/package-scripts.test.ts
node scripts/coverage-summary.mjs --check --no-write
./apps/desktop/node_modules/.bin/tsc -p apps/desktop/tsconfig.main.json --noEmit
./apps/desktop/node_modules/.bin/tsc -p apps/desktop/tsconfig.preload.json --noEmit
git diff --check
```

Local environment limits: `pnpm`, `corepack`, `gh`, Docker, and Helm were not
available in this shell. Docker/Helm checks therefore used the repository's
static deployment validators rather than live `docker compose config` or Helm
template execution.

`knip --production --files` could not execute in this macOS workspace because
Knip's native `oxc-parser` binding was rejected by the local Node runtime
code-signing loader. CI's Linux `pnpm lint:dead-code` job remains the
authoritative executable proof for the dead-code gate.
