# Zopu Integration Smoke

The smoke harness is a repeatable integration lane for the thin Zopu MVP. It probes the local web app, authenticated Convex control plane, Flue `project-manager` route, AgentOS daemon/workspace contract, the CPA OpenAI-compatible gateway, and the Orb execution-plane dependencies (Docker, OpenCode, Gitea, repository writability) before it creates any project issue.

The harness does not edit CPA configuration, restart services, print bearer tokens/API keys, or run parallel worker calls. `minimax-m3` is the serial worker-loop model; `glm-5.2` performs the plan and the independent review.

## Preflight checks

| Check ID | Layer | What it probes |
| --- | --- | --- |
| `web` | Control plane | Web app HTTP reachability |
| `convex` | Control plane | Convex health query returns OK |
| `organization` | Control plane | Authenticated personal organization |
| `project-contract` | Control plane | Disposable project exists with a connected source |
| `agentos-workspace-contract` | Control plane | Issue-scoped artifacts present |
| `agentos-daemon` | Control plane | Online local daemon |
| `flue` | Agent service | project-manager Flue route reachable |
| `cpa-model-catalog` | Model gateway | minimax-m3 and glm-5.2 in catalog |
| `cpa-completion-minimax-m3` | Model gateway | minimax-m3 accepts a no-tools completion |
| `cpa-completion-glm-5.2` | Model gateway | glm-5.2 accepts a no-tools completion |
| `model-roles` | Model gateway | Role selection contract (worker/planner-reviewer) |
| `worker-gateway-config` | Model gateway | AGENT_MODEL_BASE_URL matches the CPA base URL |
| `docker-daemon` | Orb execution plane | Docker daemon responds to `docker version` |
| `opencode-package` | Orb execution plane | `@agentos-software/opencode` is resolvable |
| `gitea-reachable` | Orb execution plane | Gitea `/api/v1/version` endpoint reachable |
| `gitea-creds-valid` | Orb execution plane | Gitea token authenticates against `/api/v1/user` |
| `gitea-pr-creation` | Orb execution plane | Target repository accessible for PR creation |
| `repository-writable` | Orb execution plane | Orb workspace root is writable |

A missing or unreachable dependency reports the check as failed with the exact reason. The harness never fakes success.

## Setup

Use a disposable/test project that already has a connected repository source and the issue-scoped artifact set. Export a Better Auth/Convex access token for the signed-in user, the local daemon id, and the CPA key/base URL. The CPA URL must include its OpenAI-compatible `/v1` path.

```bash
export ZOPU_SMOKE_ACCESS_TOKEN='...'
export ZOPU_SMOKE_PROJECT_ID='...'
export ZOPU_SMOKE_DAEMON_ID='local-macbook'
export ZOPU_SMOKE_CPA_BASE_URL='https://ai.example.invalid/v1'
export ZOPU_SMOKE_CPA_API_KEY='...'
```

For the Orb execution-plane checks (Docker, Gitea PR creation), also export:

```bash
export GITEA_URL='https://git.example.com'
export GITEA_TOKEN='...'
export ZOPU_SMOKE_REPOSITORY_PATH='owner/repo'
```

The harness reuses `AGENT_MODEL_*`, `CONVEX_URL`, `DAEMON_ID`, `SITE_URL`, and `VITE_FLUE_URL` when their `ZOPU_SMOKE_*` equivalents are absent. It never rewrites those values. Override the tiny feature request with `ZOPU_SMOKE_FEATURE_REQUEST` when the disposable project needs a more specific target.

## Commands

Run capability probes only:

```bash
bun run smoke:zopu
```

Drive one issue through the project loop and review it:

```bash
bun run smoke:zopu --run --report /tmp/zopu-smoke.json
```

The command prints one of these stable markers:

- `ZOPU_SMOKE_PREFLIGHT_PASSED` means all probes passed and no mutation was requested.
- `ZOPU_SMOKE_COMPLETED` means the issue was created, the worker reported completion, the durable issue reached `completed`, and GLM approved the result.
- `ZOPU_SMOKE_CONTRACT_BLOCKED` means a required capability or configuration is missing; the JSON report names the exact check and next action.
- `ZOPU_SMOKE_FAILED` means runtime execution started but did not satisfy the worker/reviewer contract.

Exit codes are `0` for a passing preflight or completed run, `2` for a contract block, and `1` for a runtime failure. Reports contain only endpoint labels, statuses, counts, ids, and sanitized failure text; model transcripts and credentials are intentionally omitted.

## Cleanup

The harness does not create Docker containers or Orb workspaces in preflight mode. In run mode, the Flue `project-manager` agent owns its sandbox lifecycle. To clean up Orb proof fixtures or run artifacts:

```bash
docker container prune -f --filter "label=orb"
rm -rf /tmp/orb-* /tmp/orb-proof-*
```

## Current lane boundary

The smoke intentionally stops before mutation when the project source, issue-scoped AgentOS artifacts, or online daemon contract is absent. The Orb execution-plane checks (Docker, OpenCode, Gitea) report BLOCKED when those external dependencies are not available on the local MacBook; this is expected and does not indicate an implementation failure. See [docs/DOGFOOD_V0.md](./DOGFOOD_V0.md) for the full lifecycle.