An approval, ask or park can be resolved by an operator, a rule, a classifier or automatically, so the vocabulary stops naming a person: - step type human.approve -> workflow.approve - park class needs_human -> needs_decision (ParkNeedsDecision) - event kinds human_* -> operator_* - alert kind task.needs_human -> task.needs_decision - status grouping "needs you" -> "needs attention" 0061 rewrites the stored values, including the approval step type in the workflow-definitions resource and each task's pinned definition, with the digest recomputed so resumed tasks still match.
e2e
Validation of the whole stack, run by hand or by an agent, never by
task check or CI. It needs PostgreSQL 18, five services, Vite and a browser,
which the gate must not. Docker is not needed: without it tasks queue and
park, which is useful data for the dashboard.
| File | What it does |
|---|---|
stack.sh |
Starts PostgreSQL 18 (port 55432) and the five services as local processes, then Vite on 5173 |
seed.sh |
Seeds the stack through the dashboard API; safe to rerun |
run.cjs |
Runs checks/*.cjs in Chromium; screenshots to out/ |
checks/ |
One module per behaviour |
results/ |
One committed report per release |
Run
task e2e:up # build, start everything, seed
task e2e:check # list available checks (no stack needed)
task e2e:check -- list # explicitly list checks
task e2e:check -- workflow-phone # one check
task e2e:check -- all # all checks
task e2e:check -- --headed accessibility # watch a check in Chromium
task e2e:check -- --headed all # watch every check
task e2e:down # stop; e2e/stack.sh reset also deletes the data
Headless is the default. --headed opens visible Chromium and slows browser
actions to 150ms so you can follow them; assertions and saved evidence are the
same in both modes. The terminal prints each check before it starts. Headed mode
requires a graphical desktop.
Nothing reads the installed config: stack.sh points the XDG directories at
${ARCHIE_DEV_DIR:-~/.local/state/archie-dev} and writes its overlay from
deployments/dev.toml. Logs are in its logs/. e2e/stack.sh restart archied
restarts one service. Run task e2e:down before starting again: startup refuses
occupied service ports and checks that each launched process stays alive.
The seed creates a local test administrator: operator@example.test, password
archie-local-e2e-password. Use it at http://localhost:5173; the browser
checks sign in with the same account. These are test fixtures for this
loopback-only stack. To use an existing test account, set ARCHIE_E2E_EMAIL
and ARCHIE_E2E_PASSWORD for both seeding and browser checks. Seeding never
resets an existing account or deletes test data.
The first run needs npm ci --prefix e2e and npx --prefix e2e playwright install chromium. In the cloud environment, Chromium and Playwright are
preinstalled; run with NODE_PATH=$(npm root -g).
Release evidence
node e2e/run.cjs --record v1.54.0 all
writes results/v1.54.0.md, the pass or fail of every check for that
release. Commit it with the release. Screenshots stay in out/.
Writing a check
A module in checks/ exports async ({ page, go, shot, fail }). go(path)
loads a dashboard route, shot(label) saves a screenshot, fail(msg) records
a problem without stopping. A throw, a fail, or any console or page error
fails the check. Wait for elements, never for networkidle: the event stream
never goes idle.
routes loads every static route and flags text with stray leading,
trailing or doubled spaces. seeded checks the seed is visible.
Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| State Store exits: server is older than PostgreSQL 18 | another server answered | stack.sh uses port 55432; set ARCHIE_DEV_PGPORT if that is taken |
| Startup says a port is in use | a stack or another process already owns it | Run task e2e:down, then task e2e:up; inspect any remaining listener with ss -ltnp |
| Your own shell is killed (exit 144) | pkill -f matched its own command line |
stack.sh stop or restart, which kill by PID |
npx shadcn-vue add cannot fetch the registry |
Node's fetch ignores the cloud agent proxy | curl the registry JSON and copy the files |
| Postgres aborts in the cloud | /tmp/claude-0 is reset to mode 700 |
stack.sh keeps the root cluster in /var/lib/archie-dev |