fix(portal): freeze the attended console and wire the decision portal to a deployment target

[abrichr]

The defect, verified before changing anything

The mobile decision portal merged in #75 works from a source checkout and is dead in every signed installer. Both reported causes reproduce, and there are three more that only a behavioural test finds.

Verification was run against real installs of the exact pinned versions, not by reading code:

1. openadapt-flow==1.23.0 predates the module the portal renders.

$ pip install 'openadapt-flow==1.23.0'
$ ls site-packages/openadapt_flow/console/
__init__.py  actions.py  app.py  attention.py  data.py  server.py     # no human_decisions.py

1.23.0's /api/attention/{run_id} returns item.model_dump() — a bare attention item. 1.25.0 returns human_decisions.decision_detail(...). The portal shell (engine/portal/shell/app.js) reads body.task.allowed_actions, body.task.capability_digest, body.task.signature, detail.task_digest, and presentation.question; none of those keys exist in the 1.23.0 response, so the phone renders an empty decision and cannot submit one.

2. The pin requested no extras, so the console cannot start at all.

$ openadapt-flow console --attend --port 7899        # flow 1.23.0, no console extra
the operator console needs fastapi, uvicorn — install the console extra:  pip install 'openadapt-flow[console]'
$ echo $?
1

PortalService._start_console waits for a capability banner that never comes and fails closed.

3. (new) openadapt-flow[console]==1.25.0 is uninstallable against Desktop's openadapt-types==0.5.0.
Flow's console extra requires openadapt-types>=0.6.0,<0.7.0; human_decisions.py imports HUMAN_DECISION_TASK_SCHEMA and HumanDecisionTaskV1, neither of which exists in 0.5.0. The version bump was not optional.

4. (new) 1.25.0 moved Playwright out of Flow's core dependencies into its browser extra.
With [console] alone, the frozen Playwright driver became a build-only import and scripts/verify_build_artifact.py sidecar correctly refused the archive (build-only Python modules crossed frozen boundary: greenlet; playwright; …). The gate caught this; it is fixed by pinning [browser,console].

5. (new) The capability banner never survives the pipe in a frozen build.
Flow prints the console's one-time bearer capability with a plain print immediately before uvicorn.run(). A PyInstaller-frozen interpreter block-buffers stdout, so with everything else fixed the console was serving while its supervisor saw nothing:

[  5.0s ERR] INFO:     Uvicorn running on http://127.0.0.1:7876
              ... no #token= line, ever ...

PYTHONUNBUFFERED=1 does not reach a PyInstaller-frozen interpreter (tested). --python-option u does.

What changed

File	Change
pyproject.toml	openadapt-flow==1.23.0 → openadapt-flow[browser,console]==1.25.0; openadapt-types==0.5.0 → ==0.6.1. Exact pins kept — nothing unpinned, loosened, or vendored.
uv.lock	Regenerated. Adds exactly fastapi 0.140.7, starlette 1.3.1, uvicorn 0.51.0, annotated-doc 0.0.4; updates flow and types.
scripts/build_frozen_engine.py	New CONSOLE_COLLECTION: --collect-all uvicorn (its loop/protocol/lifespan implementations are resolved by string import at run time), --collect-submodules openadapt_flow.console, hidden imports for console.server/app/human_decisions, fastapi, starlette, and --copy-metadata for all three. Plus --python-option u for the banner. The deliberate refusal to --collect-all openadapt_flow (crown-jewel boundary) is untouched; only the narrow console subpackage is collected.
scripts/frozen_notices.py	FROZEN_RUNTIME_ROOTS now carries extras (openadapt-flow[browser,console]) so the notice closure resolves what is actually frozen. fastapi/starlette/uvicorn become audited runtime packages with mandatory notices rather than build-only imports. New shared bundled_flow_pin() refuses a pin missing a required extra.
scripts/verify_build_artifact.py, scripts/smoke_test_native_installer.py	Both now read the pin through that one parser, so the gate, the installer smoke, and the notice closure cannot disagree about what the installer ships.
scripts/sync_control_overlay_contract.py + src/overlay/generated/contract.ts	Regenerated for types 0.6.1. The only change is the provenance header — the v2 schema JSON hashes and every enum are byte-identical between 0.5.0 and 0.6.1 (verified before bumping).
scripts/smoke_test_frozen_flow.py	Extended with the behavioural acceptance test (below).
tests/, docs/	Regression tests for the pin/extras/collection invariants; installer notes and docs/DECISION_PORTAL.md updated.

How the frozen artifact was proved to serve the portal

The existing frozen smoke was extended rather than duplicated, so it runs in the existing python-sidecar job with no new workflow step and no second vision-runtime download (~15s added).

It starts the frozen attended console with the exact argument shape engine.portal.service spawns, reads stdout with the portal's own _parse_console_banner, and drives the routes through engine.portal.flow_client.FlowConsoleClient — Desktop's real seam, allowlist and header normalisation included:

{"artifact_bytes": 108479616, "console_banner_seconds": 5.095,
 "console_decision_question": true, "console_refuses_unbound_mutations": true,
 "console_unauthenticated_status": 401, ...}

Live responses from the frozen binary:

session       200  {"version": "1.25.0", "attend": true, "csrf_token": "..."}
notification  200  {"title": "OpenAdapt needs attention", "open_count": 1}   # passes assert_generic_notification
tasks         200  [{"id": "7dfbd8a7dbf135ff167c3639", "status": "halted", ...}]
task_detail   200  {"item": {...}, "task": null, "task_digest": null,
                    "presentation": {"question": "Is the live application ready for OpenAdapt to verify and continue?", ...}}
unauthenticated GET /api/session → 401

The item/task/task_digest/presentation shape is human_decisions.decision_detail — the thing 1.23.0 could not produce. (task is null here because the synthetic run carries no engine-issued pause capability; that is the correct fail-closed projection, and the shell's question comes from presentation.)

Archive inventory of the shipped PYZ:

fastapi: 38 modules      starlette: 22      uvicorn: 41      openadapt_flow.console: 8 (incl. human_decisions)
uvicorn dynamic: lifespan.{on,off}, loops.{auto,asyncio,uvloop},
                 protocols.http.{auto,h11_impl,httptools_impl},
                 protocols.websockets.{auto,websockets_impl,wsproto_impl}

Licensing / artifact boundary

scripts/verify_build_artifact.py sidecar passes on the built artifact. Every new closure member (fastapi, starlette, uvicorn, anyio, click, h11, annotated-doc) ships a concrete license file in its own wheel, so all are hash-bound in NOTICE-INVENTORY.json; no reviewed-external-notice exception and no vendored file was added. All are MIT/BSD — the copyleft scan, the AGPL/openIMIS member scan, the separately-provisioned-vision scan, and the build-only-import rejection all still run and all pass. uv build + verify_build_artifact.py python-distribution pass on the wheel and sdist.

Gates run locally with the exact pinned versions

• uv sync --locked --extra dev --extra build → uv run pytest tests/ -q → 757 passed
• uv run ruff check engine/ tests/ scripts/ → clean
• npm ci && npm run test:ui && npm run build → 37 passed, build clean
• uv run python scripts/check_release_consistency.py → synchronized
• uv sync --locked --extra build (CI-exact) → build_frozen_engine.py → verify_build_artifact.py sidecar → smoke_test_frozen_flow.py → all pass

What remains unvalidated, and what still needs a human

Platforms. Everything above was built and exercised on macOS 14 arm64 only (the local machine). Linux x86_64, Windows x86_64, and macOS Intel are unverified by me and rest on CI: PRs build the sidecar on ubuntu-22.04 only, and the full four-platform sidecar + installer matrix runs on exact main. Two platform-specific risks are worth watching on the merge build: PyInstaller collection differences for uvicorn on Windows, and the --python-option u behaviour under the Windows/Linux bootloaders.

portal_start now completes, and the open security question is resolved.

Both remaining portal-side defects are fixed in this PR, and the staged-config
lifetime question is decided on evidence rather than handed back.

What the staged config contains. data_dir/deployment.json is the
operator's file, and its schema carries reusable credentials —
rdp_password, rdp_username, rdp_domain, agent_token, agent_tls_pin —
alongside PHI-capable selectors (url, macos_window_title,
rdp_readiness_text, …). engine/private_flow_config.py already treats every
password/token/secret key as sensitive when deriving log redactions. This
is not "a backend and a URL".

Threat model. 0600 is owner-only, so an attacker with same-user code
execution already has the operator's own deployment.json and the console's
in-memory copy; no file lifetime changes that, and this change does not pretend
to. What duration genuinely bounds is a same-user backup, file-sync client,
crash reporter, or support bundle sweeping the staged copy — an RDP password
does not rotate on being read, so a file that survives being read once is a real
exposure whose severity is proportional to how long it sits there.

Decision: neither session-lived nor per-run — staged for the console's
startup only.

Session-lived is ruled out by the contents. Per-run re-staging is ruled out
because it would be theatre, and that is worth stating plainly: in the exact
pin this installer ships, openadapt_flow/__main__.py::_attended_service_from_args
resolves --config eagerly through load_deployment before it yields, and
AttendedActionService is constructed from the parsed DeploymentConfig object
and never sees the path again. Re-writing the file per run would not change one
byte of what the console executes with; it would only put the same secret back
on disk more times.

So the file lives exactly as long as Flow needs to read it. It is staged 0600,
the console is spawned, and it is removed the instant the capability banner
arrives. serve() — which prints that banner — runs strictly downstream of the
config load inside the same with statement, so the banner is a
happens-after proof, not a timing guess. Measured window on the frozen binary:
4.992s, versus the hours a portal session can last.

Removal is guaranteed by the finally in
private_flow_config.stage_private_yaml on every exit path — normal return, a
console that never announces itself, an unparseable config, any exception. The
one thing a finally cannot survive is SIGKILL, so portal start also sweeps
.deployment-*.yaml older than STALE_STAGING_AGE_S. That age bound is
deliberate: a config belonging to a console that is still starting is younger
than the start timeout, so a concurrent start can never have its own in-use file
deleted out from under it.

The two portal-side blockers, fixed.

1. PortalService now spawns console --attend --allow-actions --config <staged>. A missing or unparseable deployment config refuses on Desktop's
   side of the wire, before anything is spawned, naming the file the operator
   has to write. Flow's no-target refusal is preserved and still asserted
   against the frozen binary — it was not worked around.
2. PortalService.start no longer calls session into a closed port.
   _await_console_session polls to a real deadline (CONSOLE_READY_TIMEOUT_S)
   and gives up immediately if the console process exited, rather than burning
   the whole deadline on a corpse.

Behavioural evidence: the portal starts on the frozen binary.

The existing smoke was extended (same job, no new workflow step). It stages a
config through the same private_flow_config call the portal uses, starts the
frozen console with the exact portal_start argument shape, deletes the
staged file the moment the banner is parsed, and only then drives every portal
route through engine.portal.flow_client:

{"artifact_bytes": 111625184,
 "console_accepts_staged_config": true,
 "console_read_staged_config": true,
 "console_attended_session": true,
 "console_serves_without_staged_config": true,
 "console_attended_banner_seconds": 4.992,
 "console_refuses_unbound_mutations": true,
 "console_decision_question": true,
 "console_unauthenticated_status": 401, ...}

console_read_staged_config is proof rather than inference: the staged config
carries a backend.kind marker that exists nowhere in Flow, and the frozen
binary echoes it back verbatim. console_serves_without_staged_config means
every route above was served with the credential-bearing file already gone from
disk — so a future Flow that began re-reading the path would fail this smoke.

Flow requires an injected WindowClient for this backend on Linux by
design, so no attended session can attach on a headless runner. The Linux PR
leg therefore proves the config read; the full attended path runs on the
exact-main macOS and Windows sidecar legs, and was run locally on macOS 14
arm64 (above).

Local gates re-run after the change: 766 passed (was 757), ruff clean,
37 frontend tests + build clean, release consistency synchronized,
verify_build_artifact.py sidecar passes on the rebuilt artifact.

Other runtime pin drift found (report only, not fixed here).

Component	Installer ships	Latest	Note
openadapt-capture	1.1.1 (floor >=1.1.0)	1.2.1	Two minors behind, and below the >=1.2.0 floor Flow's own capture extra requires. Recommend a separate bump — capture 1.2.x changed sdist packaging, and tests/test_capture_runtime_contract.py asserts a native recorder contract that should be re-run against it.
onnxruntime	1.27.0	1.28.0	One minor behind; the pin is deliberate and macOS-Intel-aware.
openadapt-privacy, playwright, pyinstaller, segno	1.0.0 / 1.61.0 / 6.21.0 / 1.6.6	same	current

Flow extras deliberately not requested. privacy is intentionally omitted — engine/main.py::_normalize_flow_auto_scrub_capability documents Presidio/spaCy as an optional extra and keeps SCRUB=on failing closed. capture adds only openadapt-capture, already a direct Desktop dependency. Platform extras (macos/windows/linux) are unchanged by this PR and unverified either way; the Windows extra's requests dependency is worth checking if the frozen sidecar is ever expected to drive Flow's Windows agent backend.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM

[abrichr]

CI update: Linux now confirms the same behaviour

The PR body was written from a macOS 14 arm64 build. The Python sidecar (ubuntu-22.04) job has now reproduced it independently on Linux x86_64 — the artifact boundary/notice gate and the extended frozen smoke both pass on a machine that never saw my local environment:

Verified sidecar artifact: .../dist/openadapt-engine (130954408 bytes)
{"artifact_bytes": 130954408, "console_banner_seconds": 3.242,
 "console_decision_question": true, "console_refuses_unbound_mutations": true,
 "console_unauthenticated_status": 401, "outcome": "COMPLETED_UNVERIFIED", ...}

So the frozen console — banner over a pipe, human_decisions projection, capability enforcement, and the fail-closed refusal of unbound mutations — is now verified on macOS arm64 and Linux x86_64.

Still unverified: Windows x86_64 and macOS Intel. PR builds only the Linux sidecar; the four-platform sidecar and installer matrix runs on exact main. Worth watching on the merge build: uvicorn collection under the Windows bootloader, --python-option u on Windows/Linux installers, and the macOS Intel cryptography/onnxruntime universal2 lane.

All 14 checks pass; the native-installer matrix is skipped by design on PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM