zopu-code/docs/SMOKE.md

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, and the CPA OpenAI-compatible gateway 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.

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.

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='...'

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:

bun run smoke:zopu

Drive one issue through the project loop and review it:

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.

Current lane boundary

The smoke intentionally stops before mutation when the project source, issue-scoped AgentOS artifacts, or online daemon contract is absent. Those checks are the integration boundary for the project-loop and daemon lanes; do not paper over them in this harness or make a live gateway change to satisfy a failed probe.