## Context

`apps/device-host-agent/host_agent/web/app.py` currently renders five HTML pages (login, status dashboard, devices, account, history) by composing f-string templates with a module-level `escape()` helper (a thin wrapper over `html.escape(..., quote=True)`). A shared `_chrome(title, body_html, session)` function acts as a hand-written base template; a `_CSS` string constant holds the inline stylesheet; the dashboard page embeds a `<script>` polling block whose JS braces are doubled (`{{`/`}}`) to survive f-string parsing.

This shape was an explicit decision in `openspec/changes/host-agent-local-console/design.md`, titled "Reuse FastAPI + Starlette's `HTMLResponse`, not a new micro-framework, not Jinja2", justified at the time by a "small page count" assumption (login, dashboard, devices, history) and the mitigation that "a single small `escape()`-wrapping helper used for every interpolated value" would keep the discipline manageable.

Two things have changed since that decision was made:

1. The page count has grown (account was added) and is about to grow again: `openspec/changes/task-execution-progress-visibility` (in flight) plans to add three more Host-Agent-side pages (task list, task detail, timeline). The timeline page in particular is a loop-rendered table of externally-influenced text (task summaries, tool calls, scene/element descriptions).
2. Every operator-controllable field (`device.name`, `device.driver_type`, `connection_info`, the upcoming task summaries) is one missed `escape(...)` call away from an XSS sink. The f-string approach offloads escaping discipline onto the author and reviewer of every change to `web/app.py`. This is acceptable when there are four pages written by one author in one PR; it stops being acceptable as the page set and author count grow.

`device-host-agent`'s current direct dependencies are `device-agent-runtime`, `device-cloud-platform`, `fastapi`, `httpx`, `uvicorn[standard]`. None of these force `jinja2` into the resolved `uv.lock` (starlette's `Jinja2Templates` is an optional extra that the Host Agent does not currently import), so adding Jinja2 is a genuine new direct dependency, not surfacing a transitively-resolved one.

## Goals / Non-Goals

**Goals:**

- Render every Host Agent console HTML page through a template engine whose autoescape is enabled by configuration, so the XSS-safety of any interpolated value no longer depends on the page author remembering to call `escape()`.
- Move the rendering shape closer to what `task-execution-progress-visibility` will need for its task/timeline pages (loops, conditionals, inheritance), so that change does not have to grow the f-string code further and then migrate later.
- Preserve the current pages' observable contract byte-for-byte where it matters to a browser or operator: same URLs, same form fields, same redirects, same session/CSRF behavior, same 5-second `/api/status` polling, same visual look.
- Keep the rendering stack boring and single-dependency: one template engine, no static-asset pipeline, no SPA tooling, no new framework.

**Non-Goals:**

- No new pages, no new routes, no new visual design, no CSS refactor — pages are migrated mechanically.
- No extraction of the inline `<style>` into a static `.css` file or pipeline (no `starlette.staticfiles`); the CSS block moves into `base.html` and stays inline. A future change can extract it if the stylesheet grows.
- No extraction of the inline dashboard polling `<script>` into a `.js` file; the JS stays in the template, just no longer f-string-escaped.
- No change to `host_agent/web/auth.py` (session store, CSRF, PBKDF2 verification).
- No change to `HostAgentConfig`, the console lifecycle wiring in `host_agent/app.py`, or the loopback-vs-non-loopback bind semantics.
- No change to the `console/` Runtime SPA or the `cloud-console/` SPA; both keep their Vue3 + Vite toolchains untouched.
- No move to Starlette's `Jinja2Templates` class — the Host Agent already uses `HTMLResponse(content=...)` and only needs a configured `jinja2.Environment` plus `template.render(...)`. Pulling in `Jinja2Templates` would couple rendering to a Starlette version-specific signature (`TemplateResponse(request, name, context=...)` changed across versions) for no functional gain. The `Environment` is called directly.

## Decisions

### D1: Jinja2 as the template engine

`jinja2` (pure-Python wheel, no C extension, single dependency) is added as a direct dependency of `device-host-agent`. The rendering code constructs a `jinja2.Environment` configured with `autoescape=select_autoescape(["html", "xml"])` and a `FileSystemLoader` pointing at a new `host_agent/web/templates/` directory.

Alternatives considered:

- **Mako / Chameleon / Genshi**: smaller ecosystems, less familiarity, more fragile under modern Python toolchains. Jinja2 is the de facto default for Python server-rendered HTML (Django, Flask, FastAPI docs all use or reference it); picking anything else trades familiarity for no concrete benefit at this scale.
- **Starlette's `Jinja2Templates`**: see Non-Goals — rejected because the wrapper buys nothing the Host Agent needs (it is mainly useful when the same app mixes JSON and template responses behind the same routing conventions the Host Agent already has via `HTMLResponse`), and its signature has been unstable across Starlette versions. Calling `Environment.get_template(...).render(...)` directly keeps the rendering code version-agnostic and explicit.
- **stdlib `string.Template` + a custom autoescape wrapper**: would reproduce Jinja2 with less ergonomic syntax and no `{% for %}`/`{% if %}`/`{% extends %}` — i.e. would re-introduce the f-string pain with weaker tooling. Rejected.
- **Stay with f-strings and add a `bandit`/`semgrep` rule to flag bare interpolations**: lint-based mitigation does not change the mechanism; it adds a rule that has to be maintained and can be bypassed by any non-trivial builder pattern. Rejected in favor of removing the failure mode entirely.

### D2: One module-level `Environment`, `FileSystemLoader` rooted at `host_agent/web/templates/`

Templates live in `apps/device-host-agent/host_agent/web/templates/`:

```
host_agent/web/templates/
  base.html         # <!doctype>, <head>, <style>, header/nav, {% block body %}{% endblock %}
  login.html        # {% extends "base.html" %}
  dashboard.html
  devices.html
  account.html
  history.html
```

A single module-level `_ENV = jinja2.Environment(...)` is created at import time in `host_agent/web/app.py`. Jinja2 compiles templates lazily on first `get_template()` call and caches the compiled bytecode on the `Environment` for the lifetime of the process, so subsequent renders are dict-lookup + context-bind — no recompilation. The `Environment` is thread-safe for read-only use after construction; the console's only writes are during `Environment(...)` construction itself, which happens once.

`PackageLoader("host_agent.web", "templates")` was considered as an alternative to `FileSystemLoader`. Rejected because `PackageLoader` relies on `importlib.resources` semantics that interact awkwardly with editable/`uv sync` installs during local development (template changes not picked up without reinstall); `FileSystemLoader(__file__).parent / "templates"` resolves correctly under both wheel install and editable workspace layout, and is the pattern Jinja2's own documentation recommends for application code.

### D3: `autoescape=select_autoescape(["html", "xml"])` rather than `autoescape=True`

`select_autoescape(["html", "xml"])` enables autoescape for templates whose names end in `.html` or `.xml` and disables it for others. This is the recommended default in Jinja2's documentation. It provides:

- Automatic HTML escaping for every `{{ value }}` interpolation in `.html` templates, so the spec's XSS-safety property holds without author discipline.
- An opt-out path for the rare case where a template intentionally produces HTML markup from trusted Python-side builders (e.g. a pre-rendered fragment) — that case uses `{% autoescape false %}...{% endautoescape %}` or `| safe` filter. No current page needs this; the option is documented for future authors.

`autoescape=True` (always on) was considered and rejected because it would prevent any future `.txt`/`.csv`/`.json`-flavored template (none planned today, but the option is preserved at zero cost).

### D4: `base.html` replaces `_chrome()` and `_CSS`

The current `_chrome(title, body_html, session)` function becomes `base.html`:

```jinja
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ title }}</title>
  <style>{% block styles %}/* …current _CSS content… */{% endblock %}</style>
</head>
<body>
  <header>
    <strong>Host Agent Console</strong>
    {% block nav %}{% if session %}
      <nav>…same nav as today…</nav>
    {% endif %}{% endblock %}
  </header>
  <main>
    {% block body %}{% endblock %}
  </main>
</body>
</html>
```

Each page template starts with `{% extends "base.html" %}` and overrides `{% block body %}` (and optionally `{% block nav %}` or `{% block styles %}` for the rare page that needs to). The login page overrides `{% block nav %}` to empty (matching today's `_login_page` behavior where `session=None`).

The module-level `_CSS`, `_chrome`, and `escape` helpers in `host_agent/web/app.py` are removed in the same change; they are fully subsumed by `base.html` + autoescape.

### D5: Dashboard inline `<script>` moves into the template under `{% raw %}`

The dashboard's 5-second `/api/status` polling script currently lives inside `_dashboard_body` as an f-string, with every JS `{` and `}` doubled to `{{`/`}}` to escape from f-string interpolation. In Jinja2 the same collision exists (`{{ ... }}` is Jinja2 expression syntax). The script moves verbatim into `dashboard.html` wrapped in `{% raw %}...{% endraw %}`, which instructs Jinja2 to pass the content through without parsing.

Alternative considered: extract the script into a separate `.js` file served via `starlette.staticfiles`. Rejected for this change because (a) it would require a static-asset mount on the FastAPI sub-app, which D1's Non-Goals explicitly defers, and (b) the script is small and tightly coupled to the dashboard's DOM. If the script grows, the extraction can happen in a later change.

A regression assertion in tasks.md verifies the script body is byte-identical to the pre-migration version (modulo whitespace).

### D6: Route handlers call `_ENV.get_template(name).render(context)` and return `HTMLResponse(content=...)`

Each existing f-string handler becomes:

```python
@app.get("/devices", response_class=HTMLResponse)
async def devices_page(request: Request, session: SessionState = Depends(require_session)):
    devices = await asyncio.to_thread(config_store.list)
    edit_id = request.query_params.get("edit")
    edit_record = await asyncio.to_thread(config_store.get, edit_id) if edit_id else None
    html = _ENV.get_template("devices.html").render(
        session=session,
        csrf_token=session.csrf_token,
        devices=devices,
        edit_record=edit_record,
        error=None,
    )
    return HTMLResponse(html)
```

The shape mirrors the current code as closely as possible — same `asyncio.to_thread` calls, same data fetched, same single `HTMLResponse` return — so the diff is dominated by "swap f-string for `render(...)`" and reviewing it stays mechanical.

`TemplateResponse` (Starlette's helper) is not used; see D1's Non-Goals discussion. `HTMLResponse(content=html)` is what the code calls today and keeps working.

### D7: Forms and CSRF tokens keep using autoescape

CSRF tokens are random `secrets.token_urlsafe()` strings and contain no HTML metacharacters, so autoescape is a no-op on them semantically. But the spec requirement ("every interpolated field is escaped by mechanism") applies uniformly; CSRF tokens go through the same `{{ csrf_token }}` interpolation as everything else. This keeps the rule simple and means a future change to the token alphabet (e.g. including `=` padding) cannot silently introduce an escaping bug.

### D8: No template rendering inside `host_agent/web/auth.py`

`auth.py` deals with session tokens, CSRF, and PBKDF2 verification. It returns booleans, tokens, and `SessionState` objects to `app.py`, never HTML. That boundary is preserved: `app.py` is the only module that touches the `Environment`. This keeps the autoescape contract easy to audit — anything that renders HTML is in one file, and every render call goes through the same configured `Environment`.

## Risks / Trade-offs

- **[Risk] A new direct dependency (`jinja2`) widens `device-host-agent`'s supply chain.** → Mitigation: Jinja2 is pure-Python, single wheel, maintained by the Pallets organization (same as Flask/Sphinx/Werkzeug), no C extension, no transitive runtime dependencies beyond `markupsafe` (already transitively present via fastapi/starlette). `uv.lock` gains one direct package + zero new transitive runtime packages.
- **[Risk] First-render compile cost on each template (sub-millisecond).** → Accepted: it is paid once per process lifetime, cached thereafter, and the console is a low-traffic single-operator page. No measurable impact on startup time or request latency.
- **[Risk] A subtle behavior change slips in during the mechanical migration (a `escape()` call forgotten, a `| safe` filter introduced, a conditional inverted).** → Mitigation: tasks.md requires a regression test that takes the pre-migration HTML of each page (captured via the existing test snapshot or by running the current code) and asserts the post-migration HTML is structurally equivalent; an XSS probe test injects `<script>alert(1)</script>` into every operator-controlled field and asserts the escaped form appears in the output.
- **[Trade-off] The dashboard's `<script>` is now inside a `{% raw %}` block rather than extracted into a static asset.]** → Accepted: keeps the change scope tight (no static-asset mount) and the script co-located with the DOM it manipulates. Trade-off recorded for future revisit if the script grows.
- **[Trade-off] The original `host-agent-local-console` design's explicit decision against Jinja2 is hereby superseded for the rendering-mechanism question only.]** → Mitigation: recorded as an Open Question to be reconciled when `host-agent-local-console` is archived. Until then, this change's spec captures the autoescape requirement as a new capability (`host-agent-console-template-rendering`) rather than a MODIFIED delta against an unarchived pending spec, matching the precedent set by `task-execution-progress-visibility` and `cloud-planner-proxy` when they needed to reference `host-agent-local-console` / `ai-planner-runtime` before those were archived.

## Migration Plan

1. Add `jinja2>=3.1` to `apps/device-host-agent/pyproject.toml`'s `dependencies`. Run `uv lock --check` after `uv lock` to confirm the lockfile is in sync. Confirm `markupsafe` is the only new transitive package.
2. Create `host_agent/web/templates/` with `base.html` and one file per current page. Capture the byte-level structure of each current page (login, dashboard including the inline script, devices, account, history) before migration as a reference for the regression assertion.
3. In `host_agent/web/app.py`, construct the module-level `_ENV` and rewrite each route handler per D6. Remove `_chrome`, `_CSS`, `_login_page`, `_dashboard_body`, `_devices_body`, `_account_body`, `_history_body`, and the `escape` helper.
4. Add `apps/device-host-agent/tests/host_agent/web/test_templates.py` covering: (a) each template renders without raising for representative contexts; (b) the XSS probe appears HTML-escaped in every rendered page that interpolates an operator-controlled field; (c) the dashboard `<script>` body is byte-identical to the pre-migration reference.
5. Run the existing Host Agent test suite (`uv run --package device-host-agent pytest`) and the root non-integration suite; confirm no regressions.
6. Run `ruff check --fix`, `ruff format`, and `python -m compileall` over the changed files.
7. Run `openspec validate host-agent-console-jinja2-templates --strict`.
8. Manual browser verification: log in, view status dashboard auto-refresh, add/edit/remove a device, change password, view history, log out. Confirm no visual or behavior change versus the pre-migration pages.
9. Rollback: revert the commit. The change introduces no on-disk state format change (templates are code, not data) and no schema migration. The only artifact a previous run may leave is the same SQLite history file the unchanged code would have written; it is unaffected.

## Open Questions

- **Coordination with `task-execution-progress-visibility`.** That change's design.md D3 currently commits to "reuse `api/console.py`'s query patterns and f-string + `html.escape()` convention" for its new task list/detail/timeline pages. After this change lands, those pages SHOULD be written directly against the Jinja2 templates introduced here (extending `base.html`, looping over timeline entries with `{% for %}`). The two changes do not conflict at the code level (different files within `host_agent/web/`), but the D3 wording in `task-execution-progress-visibility/design.md` will need a follow-up edit. Options: (a) edit D3 in `task-execution-progress-visibility` once this change is on `master`; (b) defer the wording update until that change is next revised. Either is acceptable; the decision does not block this change.
- **Supersession of `host-agent-local-console`'s "not Jinja2" decision.** When `host-agent-local-console` is archived into `openspec/specs/host-agent-local-console/spec.md`, this change's `host-agent-console-template-rendering` capability becomes a sibling rather than a delta. The reconciler should decide at archive time whether to fold the autoescape requirement into `host-agent-local-console`'s spec directly (and retire `host-agent-console-template-rendering` as a standalone capability) or keep it as a sibling. Recorded for the archive step; not a blocker for this change.
- **Whether to introduce Starlette's `Jinja2Templates` for consistency with the broader FastAPI ecosystem.** Currently rejected (D1, Non-Goals). Revisit if a future change adds request-scoped rendering concerns (flash messages, per-request template overrides) that `Jinja2Templates` would simplify.