th-8e3087: SmoothFlow engine e2e — real daemon, fake-agent manifests, hooks contract, th flow

[brentrager]

Problem

Brent: "can we write similar tests to orca / cmux". Lane A of th-6ac036 had engine unit tests, the macOS app its XCTests, the phones codec/reducer tests — nothing booted the real daemon and drove it the way a client, th flow or a harness's hook script does.

Solution

crates/smooth-daemon/tests/flow_e2e — a REAL smooth-daemon per test (isolated HOME, ephemeral port, private tmux server, no lock / tailscale / relay / gateway creds), driven over the flow WS, the HTTP siblings, the th binary and POST /api/flow/hooks. The agent under test is tests/fixtures/fake-agent, installed through harness manifests like any coding CLI, in four flavours — hooks / learned id / native / scrape — one per state source the engine supports.

24 tests, ~70 s wall (2 slow ones wait real backoff / usage-limit windows):

• shell lifecycle: new → attach → input echo → resize → snapshot → kill; exit 0 = done, exit 7 = dead
• agent transitions working / idle / needs_you / limited / done / dead; steering; the permission long-poll (all three decision shapes); usage-limit scheduling + the resume firing
• resume-on-death with --resume <id>; the three-resume give-up; learned-id binding from the first hook; the duplicate-resume guard (held)
• native (th code shape) and scrape (no hooks) state sources
• the hooks contract event by event; hooks unauthenticated, everything else gated
• th flow ls/new/snapshot/send/inbox/approve/handoff/kill --json + human lines; th harness list/add/hide/unhide/order/show
• the per-harness state-source matrix; sort/hide prefs reaching flow.hello, the WS broadcast and th harness list; th harness add <path> of a custom manifest then a session on it; real claude/opencode/codex/th-code launches (opt-in, SMOOTH_E2E_REAL_HARNESSES=1)
• proof the suite never touches the real ~/.smooth (daemon.addr, daemon.lock, operator-token, flow.db byte- and mtime-identical), teardown leaves nothing, and flow_e2e_server (the mac lane's host) is the same engine

Engine bugs the suite found on day one (fixed here, each with a unit test)

1. tmux rewrites control characters under a non-UTF-8 locale — the tab-joined #{pane_dead}\t#{pane_dead_status} query read 1_2, so a dead pane was NEVER detected for any daemon not started from a shell (launchd, CI). Every supervision rule was inert there. |-joined formats + pure parsers.
2. {daemon_url} rendered from the requested address — a port-0 daemon sent every pane's hooks to http://127.0.0.1:0. Resolved before the router is built.
3. A resumed or prompt-less harness sat in starting forever — SessionStart flipped the source to hooks (stopping the scraper) but mapped to nothing. SessionStart on a starting row ⇒ idle.
4. A held row flapped — the supervisor saw its dead tmux session as a crash and scheduled a resume the guard then refused, every backoff. Held rows are left alone.

CI

pr-checks.yml: tmux on the Linux leg and SMOOTH_E2E_STRICT=1 so a missing tmux/bash/curl/th fails the job instead of passing it having run nothing. Windows compiles the suite empty (#![cfg(unix)]). The suite runs inside the normal cargo nextest run --profile ci.

Verification

• cargo nextest run -p smooai-smooth-daemon --test flow_e2e: 24/24, 68.5 s wall on a dev box at load 25–40
• cargo test -p smooai-smooth-flow --lib: 75/75 (new: pane parsers, SessionStart ⇒ idle, held rows survive a tick, prefs test made PATH-independent)
• cargo test -p smooai-smooth-daemon --lib operator flow_route: green (new: ephemeral port resolution)
• cargo fmt --check, cargo clippy (no new warnings), pnpm format:check

Docs

docs/Engineering/SmoothFlow-Testing.md — the cmux/orca survey, the layers table, a per-test table, the rig, the fake-agent contract, runtimes, the CI split rule, gaps. Linked from docs/Architecture/SmoothFlow.md § Testing.

Pearl: th-8e3087 (epic th-6ac036). Sibling: th-a58a97 (#548, the macOS XCUITest lane).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q5YUmVQ5obDT27oLjgt7AL

[changeset-bot]

🦋 Changeset detected

Latest commit: 22939e2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@smooai/smooth	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR