@event4u/agent-config 5.10.1 → 6.1.0

package/docs/decisions/ADR-067-glama-registry-listing.md

@@ -0,0 +1,259 @@
+---
+adr: 067
+status: proposed
+date: 2026-06-08
+decision: glama-registry-listing
+supersedes: —
+superseded_by: —
+phase: road-to-glama-registry-listing (Phases 1–3)
+type: lightweight
+---
+
+# ADR-067 — Glama MCP registry listing
+
+## Status
+
+**Proposed** · 2026-06-08. Implements
+[`road-to-glama-registry-listing.md`](../../agents/roadmaps/archive/road-to-glama-registry-listing.md).
+Council convergence: claude-sonnet-4-5 + gpt-4o, design mode, 2 rounds +
+peer-review, 2026-06-08 — one of four candidate Glama moves survives the
+"no-bullshit" bar (registry listing only; Gateway, Inspector in CI, and Worker
+listing all dropped with reasons in the roadmap).
+
+## Context
+
+[Glama](https://glama.ai) indexes ~32k open-source MCP servers, provides a free
+registry listing, and surfaces them in tool-level search across Claude Code,
+Cursor, VS Code, and similar clients. The `agent-config` local stdio MCP server
+(`scripts/mcp_server/`, Python, `mcp_scope: full`) is not currently listed
+anywhere outside the package README. The listing is a one-way-door free
+experiment: costs nothing, creates no technical lock-in, and the only ongoing
+maintenance surface is a removable README badge.
+
+The listing targets **agent developers and contributors**, not end-users
+configuring pre-built agents. The stdio server requires a local checkout; there
+is no turnkey `npx`/`pip` install path (that is a separate roadmap:
+`road-to-mcp-stdio-end-user-packaging.md`, held at `status: draft` until a real
+demand signal fires). Listing the server for end-users without packaging would
+create friction and false support expectations — the audience scope below must be
+reflected verbatim in the Glama listing description.
+
+The experimental Cloudflare Worker (`internal/workers/mcp/`, `mcp_scope: lite`,
+not README-linked) is **never listed** here or anywhere else until it exits
+`experimental`. Listing it would create an incoherent support promise.
+
+## Decision
+
+List the local stdio MCP server in the Glama registry. Developer-first scope.
+This ADR documents the exact submission content, discovery channels, kill-switch
+criteria, and review trigger so the whole process is reproducible and auditable
+without re-litigating the council decision.
+
+---
+
+## Submission — exact steps (manual, one-time)
+
+1. Open: <https://glama.ai/mcp/servers/new> (or the "Add server" button on
+   <https://glama.ai/mcp/servers>).
+2. **Repository URL:** `https://github.com/event4u-app/agent-config`
+3. Paste the **listing description** from `## Listing description` below.
+4. **Tags / categories:** `governance`, `agent-tools`, `rules`, `skills`,
+   `prompts`, `resources`, `claude-code`, `cursor`, `windsurf`
+5. Submit.
+6. Record the resulting listing URL in this ADR (`## Listing URL` section below)
+   and add the README badge per `## README badge` below.
+
+---
+
+## Listing description
+
+> **agent-config — MCP governance server for AI coding agents**
+>
+> Exposes the package's read-only governance surface (skills, commands, rules,
+> guidelines) as MCP `prompts` and `resources`. Intended for **agent developers
+> and contributors** who want to load the governance content into Claude Code,
+> Cursor, Zed, or Continue without manual copy-paste.
+>
+> **Not a turnkey package** — requires a local checkout (`git clone` +
+> `task mcp:setup`). End-user turnkey packaging is a separate, future roadmap.
+>
+> **What it serves:** `prompts/list` + `prompts/get` (every skill, command, rule,
+> guideline as a named prompt) and `resources/list` + `resources/read` (same
+> content as addressable resources). Read-only; never executes code, never writes
+> files, never spawns shells.
+>
+> **Quick start (developers):**
+> ```bash
+> git clone https://github.com/event4u-app/agent-config
+> cd agent-config
+> task mcp:setup   # creates .venv-mcp/, installs MCP SDK
+> task mcp:run     # starts the server on stdio
+> ```
+>
+> Source: `src/scripts/mcp_server/` · Contract:
+> `docs/contracts/mcp-phase-1-scope.md` · Experimental hosted Worker (separate,
+> opt-in): `docs/setup/mcp-cloud-setup.md`
+
+---
+
+## Listing URL
+
+Live — Glama **auto-indexed** the GitHub repo (no manual form submission was
+needed):
+
+```
+https://glama.ai/mcp/servers/event4u-app/agent-config
+```
+
+Listing state as of 2026-06-08: License **MIT (permissive)**, Quality **not
+tested**, Maintenance **C-grade**, and a **"This server cannot be installed"**
+notice. The "cannot be installed" flag is expected and consistent with the
+developer-first scope — the stdio server is not a turnkey `npx`/`pip` package;
+it requires a local checkout + `task mcp:setup`. Resolving that flag is the job
+of the follow-up roadmap (`road-to-mcp-stdio-end-user-packaging.md`), not this
+one.
+
+---
+
+## README badge
+
+Glama does **not** expose an embeddable badge snippet for this listing, so a
+plain link is used instead of a badge image (avoids a broken-image surface). One
+discreet line was added to `README.md` in the MCP section (after the Worker
+"Scope — Lite, not Full" note):
+
+```markdown
+> The built-in **local stdio** server is listed for discovery in the
+> [Glama MCP Registry](https://glama.ai/mcp/servers/event4u-app/agent-config)
+> (agent developers / contributors; requires a local checkout, not a turnkey
+> install — see [ADR-067](docs/decisions/ADR-067-glama-registry-listing.md)).
+```
+
+This link is the **sole reputational signal** from the listing and is removable
+in a single commit. Removing it is the Phase-3 kill-switch for spam-farm
+scenarios; see `## Kill-switches` below.
+
+---
+
+## Discovery channels (cross-listing)
+
+The listing must not depend on Glama alone (network-effect lock-in risk per
+council). Two channels are active as of 2026-06-08:
+
+| Channel | State | How |
+|---|---|---|
+| Glama MCP Registry | **pending** (manual form) | This ADR |
+| GitHub topics | **active** | `model-context-protocol` added via `gh api` (see below) |
+| Awesome MCP list (`punkpeye/awesome-mcp-servers`) | **optional next step** | Open a PR; content below |
+
+### GitHub topics (done)
+
+`model-context-protocol` added to `event4u-app/agent-config` topics, alongside
+the existing `mcp` topic. Both surface the repo in
+`github.com/topics/model-context-protocol` and `github.com/topics/mcp` searches.
+
+Command run:
+```bash
+gh api -X PUT /repos/event4u-app/agent-config/topics \
+  --field 'names[]=claude-code' \
+  --field 'names[]=ai-agent' \
+  --field 'names[]=mcp' \
+  --field 'names[]=model-context-protocol' \
+  --field 'names[]=mcp-server' \
+  --field 'names[]=agent-governance' \
+  --field 'names[]=ai-video' \
+  --field 'names[]=cursor' \
+  --field 'names[]=llm' \
+  --field 'names[]=prompt-engineering' \
+  --field 'names[]=skills' \
+  --field 'names[]=windsurf'
+```
+
+### Awesome MCP list (optional future step)
+
+If Glama alone proves insufficient or to reach the GitHub-native audience, open
+a PR against `punkpeye/awesome-mcp-servers`:
+
+```bash
+gh repo fork punkpeye/awesome-mcp-servers --clone
+# Add to the appropriate section:
+# - [agent-config](https://github.com/event4u-app/agent-config) —
+#   MCP governance server for AI coding agents (skills, rules, commands,
+#   guidelines as prompts/resources). Developer-first; requires local checkout.
+gh pr create --repo punkpeye/awesome-mcp-servers \
+  --title "Add agent-config MCP governance server" \
+  --body "..."
+```
+
+**Kill-switch:** if Glama listing alone drives sufficient discovery (≥1 inbound
+issue referencing it within 12 months), skip this PR — it adds maintenance
+surface without additive benefit.
+
+---
+
+## Kill-switches
+
+Conditions under which to **remove the README badge** (the listing itself can
+harmlessly stay up — removing the badge severs the only active reputational
+signal):
+
+| Trigger | Action |
+|---|---|
+| (a) Glama makes listing **conditional on using their Gateway hosting** | Remove badge immediately; delist if possible. Rationale: migration to Glama hosting breaks the A0-cloud contract (version-pinned URLs, prebaked skillSetSignature, bearer-token control). Non-negotiable. |
+| (b) Registry degrades into a spam farm (>50 % low-quality entries dominate MCP search results) | Remove the badge; let the listing rot harmlessly (no maintenance cost). |
+| (c) Per-release listing maintenance exceeds ~5 min/release | Investigate whether Glama auto-syncs from GitHub releases (preferred); if not, evaluate removing the listing. |
+
+A listing **fee** is **not** an automatic remove trigger — evaluate the amount.
+A $5–10/month fee buys real distribution; an unreasonable fee does not.
+
+---
+
+## Review trigger (trigger-based, never calendar-based)
+
+**Do not set a 60/90-day calendar review.** This is OSS infrastructure, not a
+SaaS product; 60-day windows measure random noise.
+
+**Trigger:** the first GitHub issue, PR, or star note that references Glama.
+On that signal, assess:
+1. Did the user have a good experience? Could they actually run the server?
+2. If friction: fix docs or sharpen "developers only" in the listing description.
+3. If confusion about end-user use: link to the end-user packaging roadmap
+   (`road-to-mcp-stdio-end-user-packaging.md`) from the listing.
+
+**Timeout kill-switch:** if no inbound reference to Glama appears within
+12 months of the listing going live, treat the listing as low-signal. The
+badge removal cost is one commit.
+
+---
+
+## Consequences
+
+**Positive:**
+- Zero-cost discovery channel for agent developers. The Glama inspector also
+  lets potential users explore tools without cloning.
+- GitHub `model-context-protocol` + `mcp-server` topics reach the GitHub-native
+  audience independently of Glama.
+
+**Negative / risks:**
+- Listing implies a degree of support. Mitigated by the honest "developers only /
+  not a turnkey package" scope label in the description.
+- Network-effect lock-in if Glama becomes the de facto standard and adds
+  badge-gating for Gateway users. Kill-switch (a) handles this.
+- Registry could attract wrong-audience users (expecting `npx` one-liner).
+  Mitigated by explicit description language + link to future packaging roadmap
+  once it ships.
+
+**Not changed:**
+- No CI dependency added.
+- No hosting changed.
+- The Cloudflare Worker is not listed.
+- The `mcp_scope: full` contract is unchanged.
+- All three dropped options (Inspector in CI, Gateway hosting migration, manual
+  Inspector smoke) remain dropped.
+
+## See also
+
+- [`road-to-glama-registry-listing.md`](../../agents/roadmaps/archive/road-to-glama-registry-listing.md)
+- [`road-to-mcp-stdio-end-user-packaging.md`](../../agents/roadmaps/archive/road-to-mcp-stdio-end-user-packaging.md) — follow-up (completed + archived)
+- [`docs/contracts/mcp-phase-1-scope.md`](../contracts/mcp-phase-1-scope.md) — stdio kernel contract
+- [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md) — Worker A0-cloud contract

package/docs/decisions/ADR-068-host-tier-detection.md

@@ -0,0 +1,90 @@
+---
+adr: 068
+status: accepted
+date: 2026-06-08
+decision: host-tier-detection
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-068 — Host-agent tier detection (v0)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08), with one verdict reversed on review (see H3).
+
+## Context
+
+The workspace shells out to a host agent per ADR-023; `host-agent-protocol.md`
+is the source-of-truth inventory + tier matrix (Tier 1 = CLI-drivable: Claude
+Code / Codex / Gemini; Tier 3 = observe-only → inbox hand-off: Augment / Cursor
+/ Cline / Windsurf). Nothing detected a host's tier — `launch` took a free-text
+`host` string and recorded a session blindly. The **Tier-1 drive loop**
+(`claude -p …` turn loop) is unbuilt and stays so.
+
+## Decision
+
+### H1 — code map mirroring the contract + consistency test
+`workspace_hosts.py HOST_INVENTORY = {id: {tier, cli}}` mirrors the contract's
+inventory table. `tests/test_workspace_hosts.py::test_inventory_matches_contract_tiers`
+parses the contract table and asserts every tier agrees — so the human-readable
+contract stays canonical without fragile **runtime** markdown parsing (the
+parsing lives in the test, not the hot path).
+
+### H2 — effective tier = inventory tier capped by CLI presence
+`effective_tier = 1 iff (inventory_tier == 1 and shutil.which(cli)) else 3`.
+A Tier-1 host whose CLI is missing demotes to Tier 3 (the contract's fail-closed
+rule). Detection is **deterministic and side-effect-free** — PATH probe only, it
+**never spawns** a host CLI (a test asserts no `subprocess.run`/`Popen`). A
+`--version` probe (vs PATH-only) is v1 debt.
+
+### H3 — launch reports the tier; it does NOT drive (council verdict reversed)
+The design first proposed a Tier-1 `{tier:1, mode:'session-recorded'}` branch.
+**Rejected on review** as a phantom state — recording a Tier-1 "launch" that
+cannot execute is dead telemetry with no rollback. Instead `launch` resolves the
+effective tier and **reports** it (`effective_tier`, `cli_present`, `known`,
+`mode`) alongside the recorded session; `mode` is honest —
+`tier1-drive-pending` (drivable, drive unbuilt) or `handoff` (use the inbox).
+
+**Scope honesty:** the council assumed `launch` could auto-route Tier-3 to the
+inbox. It cannot in v0 — `launch` has only `role`+`task`, not a *rendered*
+prompt, and the prompt renderer is unbuilt. So `launch` **reports** the tier;
+the actual hand-off stays the explicit `POST /api/v1/workspace/inbox` (which
+takes a caller-rendered prompt + skill pre-render, ADR-065/066). Auto-routing
+`launch → inbox` is deferred to when the prompt renderer lands.
+
+### Unknown host — fail-soft in-process, fail-loud at the CLI
+`detect(host_id)` returns `known: false, effective_tier: 3` for an unregistered
+id (so `launch` never 500s on a host string), while the `detect` **CLI exits
+non-zero** on an unknown id (so tooling / tests catch typos). `local` (the
+legacy `launch` default) is unregistered → Tier-3 hand-off, `known: false`.
+
+### H4 — single PR
+Detector + `launch` tier-reporting + the contract-consistency test + cross-
+runtime tests, one PR. No dead code (a detector with no caller has no
+integration proof).
+
+## Consequences
+
+- `launch` now tells the caller whether a host is CLI-drivable or needs the
+  hand-off — the seam the UI/caller uses to pick the path.
+- No phantom Tier-1 sessions; no fabricated drive.
+- Plaintext, no cryptography dependency; detection is always-on (harmless —
+  read-only PATH probe).
+
+### Deferred (v1 debt)
+- `--version` probe instead of PATH-only presence.
+- A generated inventory manifest (vs the hand-maintained map + consistency test).
+- Detection circuit-breaker / error-rate metrics.
+- `launch → inbox` auto-routing (awaits the prompt renderer).
+- The Tier-1 drive loop itself (ADR-023 Tier-1 conversation surface).
+
+## References
+
+- ADR-023 — host-agent protocol (tier definitions).
+- ADR-065/066 — the Tier-3 inbox hand-off + skill pre-render this reports toward.
+- Contract: [`docs/contracts/host-agent-protocol.md`](../contracts/host-agent-protocol.md).
+- `src/cli/python/workspace_hosts.py`, `src/server/routes/workspace.ts`.

package/docs/decisions/ADR-069-prompt-renderer.md

@@ -0,0 +1,97 @@
+---
+adr: 069
+status: accepted
+date: 2026-06-08
+decision: prompt-renderer
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-069 — Role-prompt placeholder renderer (v0)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08): both members agreed on decisions 1–4; on
+decision 5 (CLI surface) claude-sonnet-4-5's minimal-surface argument prevailed
+over gpt-4o's "keep `--input k=v`" — see the verdict table below.
+
+## Context
+
+Role prompts live at `agents/roles/<role>/prompts/<name>.md` with YAML
+frontmatter declaring `inputs` (name / required / shape) and a `skill_hint`,
+plus a body with `{{name}}` placeholders. Nothing filled those placeholders:
+the launch endpoint stored a session header but never produced a usable prompt.
+
+The hand-off surfaces both need a *filled* prompt:
+
+- **Tier-3 inbox** (ADR-065) writes a rendered prompt for copy-paste, and
+  pre-renders a `skill_hint` body (ADR-066).
+- **Tier-1 hosts without a skill surface** (Codex / Gemini, per ADR-068 /
+  host-agent-protocol) need the prompt pre-rendered with skill context inlined.
+
+`workspace_render.py` is the missing pure function: prompt + `name → value`
+map → rendered prompt string. It mirrors the existing `workspace_*.py`
+Python-authoritative CLI shape.
+
+## Decision
+
+| # | Question | Verdict | Rationale |
+|---|---|---|---|
+| 1 | Missing **optional** input | **(a)** substitute empty string, leave the heading | Markdown-structure stripping ("this heading belongs to that placeholder") is fragile template-validation masquerading as runtime logic. An empty section is template-author feedback, not a renderer bug. |
+| 2 | Unknown `{{placeholder}}` (no declared input) | **Hard error** (CLI exit 1) | A broken template contract. Leaving the literal wastes host tokens — the agent tries to interpret template syntax as content. |
+| 3 | Value contains `{{...}}` | **Single-pass literal** substitution | Recursive expansion is a code-injection vector; one pass over the original body means an injected token is never re-expanded. |
+| 4 | `skill_hint` coupling | **Stay pure** — return the hint, never append the body | The inbox already owns skill pre-rendering (ADR-066). Appending here would double-append when the inbox calls the renderer. Tier-1 and inbox have different attach policies. |
+| 5 | CLI surface | **Minimal** — `render --role --prompt [--inputs-json <f\|->] [--root]` + `inspect` | `--input k=v` is a shell-escaping trap for multi-line paragraph inputs; `--json`-on-render duplicates `inspect`. Smallest surface that works; add flags when pain emerges. |
+
+The `shape` frontmatter field is **advisory documentation only** — the renderer
+does not enforce it (decision deferred to v1).
+
+### Node wiring
+
+`POST /api/v1/workspace/render` → `{role, prompt, inputs}` → `{rendered,
+skill_hint}`. Inputs flow to the CLI via a temp JSON file (mirrors the inbox
+`--body-file` path — values can be large / multi-line). A missing-required or
+undeclared-placeholder error surfaces as HTTP 400. Role prompts are read from
+the read-only `<packageRoot>/agents/roles` tree, never the write root.
+
+## Consequences
+
+- The renderer is a pure, side-effect-free function — trivially testable, no
+  store / crypto / network coupling.
+- The `skill_hint`-pure boundary means the inbox auto-routing flow is:
+  `render(role, prompt, inputs) → {rendered, skill_hint}` then
+  `inbox.write(rendered, skill_hint=skill_hint)` — the skill body is appended
+  exactly **once**, by the inbox. No double-append.
+- Tier-1 pre-rendering (Codex / Gemini) consumes the same `{rendered,
+  skill_hint}` and inlines the skill itself when the drive loop lands.
+
+## Alternatives considered
+
+- **Heading-aware empty-section stripping (decision 1b)** — rejected as
+  fragile Markdown-structure inference with no robust signal for "which heading
+  introduces which placeholder".
+- **Forgiving unknown placeholders (leave literal)** — rejected: silent
+  token-wasting bug; a template typo should fail loud.
+- **Renderer appends the skill body** — rejected: couples three concerns and
+  double-appends on the inbox path.
+- **`--input k=v` repeatable flag** — rejected for v0: multi-line paragraph
+  inputs make shell escaping unusable; `--inputs-json` (file / stdin) is the
+  one clean mechanism.
+
+## Deferred to v1 (debt)
+
+- Per-prompt **kill-switch** (disable a template by name without redeploying) —
+  belongs at the launch / inbox layer, not in this pure function.
+- **Shape validation** against declared `shape` hints.
+- Render success / failure **metrics**.
+
+## References
+
+- [`ADR-065`](ADR-065-tier3-inbox-handoff-v0.md) — Tier-3 inbox (first consumer).
+- [`ADR-066`](ADR-066-skill-body-prerendering.md) — skill pre-rendering (owns the append).
+- [`ADR-068`](ADR-068-host-tier-detection.md) — host-tier detection (drives whether to pre-render for Tier-1 or hand off to Tier-3).
+- [`host-agent-protocol`](../contracts/host-agent-protocol.md) — Tier-1 hosts without a skill surface.
+- [`daily-workspace`](../contracts/daily-workspace.md) — workspace surface contract (lists the `/render` endpoint).

package/docs/decisions/ADR-070-tier1-drive-loop.md

@@ -0,0 +1,94 @@
+---
+adr: 070
+status: accepted
+date: 2026-06-08
+decision: tier1-drive-loop
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-070 — Tier-1 host drive loop (v0)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08): both members agreed on decisions 1, 2, 4, 5,
+6; on decision 3 (adapter shape) both sided with the **unified** adapter over
+three copy-paste functions. This ADR covers the **first PR** — the Python
+executor + tests, no HTTP endpoint (that is PR 2).
+
+## Context
+
+ADR-023 locks a CLI shell-out protocol with three tiers. Tier-1 hosts
+(Claude Code / Codex / Gemini) expose `launch` (`claude -p "<prompt>"
+--output-format json`) and a JSON envelope per turn. `detectHostTier`
+(ADR-068) already classifies a host as Tier 1, but reports
+`mode = tier1-drive-pending` — there was no executor. The rendered prompt now
+exists (`workspace_render.py`, ADR-069). The missing piece is the **drive
+loop**: spawn the host CLI, parse the envelope, record the turn.
+
+## Decision
+
+| # | Question | Verdict | Rationale |
+|---|---|---|---|
+| 1 | Turn model | **Single-turn.** Tool calls **recorded opaquely, never executed.** | Smallest useful cut. Agentic multi-turn (feed results back) + tool execution are v1 — recording tool-call JSON now keeps the session log complete without an executor. |
+| 2 | Envelope validation | **Explicit required/optional keys per host; fail closed.** Missing `result` or `is_error: true` → error turn, not a fabricated one. | "Named keys only" is too vague; an unrecognised envelope must degrade to the inbox, never invent a turn. |
+| 3 | Adapter shape | **Unified `drive(host, prompt, …)`** + per-host config (`build_args` + `normalise`). | The `ai-council` skill already drives all three hosts through one path; three copy-paste functions discard a proven abstraction. Variance is CLI flags, not control flow. |
+| 4 | Loop vs launch | **Sync drive inside `POST /launch`** when tier 1 (PR 2); no separate `/drive` endpoint. | A two-call split (header then drive) risks orphaned sessions with no rollback / dedup / lock. Sync-in-launch (202 on timeout) is sounder for v0. |
+| 5 | Timeout / failure | **90 s** default, configurable. CLI-missing / non-zero-exit / timeout / bad-envelope → `host.error` record + degrade to Tier-3 inbox. | 30 s is too short for LLM+tool turns; the user is never stuck because every failure path has an inbox fallback. |
+| 6 | First PR | `workspace_drive.py` (claude-code adapter) + stubbed-runner tests + a real-CLI **contract test** (skipped when `claude` absent). **No HTTP endpoint.** | The contract test catches Anthropic-side envelope drift (e.g. `result` renamed) the moment it runs where `claude` is present. The endpoint is PR 2. |
+
+### Uniform turn record
+
+`drive()` returns, on success:
+
+```json
+{"ok": true, "host": "claude-code", "text": "...", "model": null,
+ "usage": {"input_tokens": 12, "output_tokens": 34}, "session_id": "...",
+ "cost_usd": 0.01, "num_turns": 1, "tool_calls": []}
+```
+
+On any operational failure it returns `{"ok": false, "host", "error",
+"error_kind"}` (`error_kind` ∈ `unsupported-host` / `empty-prompt` / `timeout`
+/ `cli-missing` / `spawn-failed` / `nonzero-exit` / `bad-envelope`). It never
+raises for an operational failure — the caller records `host.error` via
+`workspace_sessions.py` and degrades to the Tier-3 inbox.
+
+## Consequences
+
+- The drive loop is the executor behind `tier1-drive-pending`; PR 2 wires it
+  into `POST /launch` so a Tier-1 launch actually drives a turn.
+- The session log stays the source of truth: every drive (success or error) is
+  one append, through the encrypted store (ADR-064) — `workspace_drive.py`
+  never writes JSONL itself.
+- `runner` injection keeps the test suite hermetic; the opt-in contract test is
+  the only path that touches a real host CLI.
+
+## Alternatives considered
+
+- **Multi-turn agentic loop in v0** — rejected: large surface, tool-execution
+  trust questions; single-turn is useful and shippable now.
+- **Three per-host functions** — rejected: discards the proven `ai-council`
+  unified adapter; the variance is purely CLI flags.
+- **Separate `POST /launch/:id/drive` endpoint** — rejected: orphaned-session
+  risk with no rollback / dedup / lock in v0.
+- **Hard-error on bad envelope** — rejected: leaves the user stuck; fail-closed
+  to the inbox is the protocol's stated posture (host-agent-protocol).
+
+## Deferred to v1 (debt)
+
+- Multi-turn agentic loops + **tool-call execution**.
+- `codex` / `gemini` host configs (the unified `drive()` is ready for them).
+- Drive **metrics** (success / timeout rate) + a kill-switch that flips Tier-1
+  to inbox-only when the failure rate crosses a threshold.
+- Error-taxonomy refinement (structured error codes).
+
+## References
+
+- [`ADR-023`](ADR-023-host-agent-protocol.md) — the three-tier CLI protocol.
+- [`ADR-068`](ADR-068-host-tier-detection.md) — detection (`tier1-drive-pending` is what this resolves).
+- [`ADR-069`](ADR-069-prompt-renderer.md) — produces the rendered prompt the drive loop consumes.
+- [`ADR-064`](ADR-064-append-jsonl-per-record-encryption.md) — the encrypted session store turns are appended to.
+- [`host-agent-protocol`](../contracts/host-agent-protocol.md) — fail-closed posture + envelope-as-contract.

package/docs/decisions/ADR-071-launch-drive-integration.md

@@ -0,0 +1,95 @@
+---
+adr: 071
+status: accepted
+date: 2026-06-08
+decision: launch-drive-integration
+supersedes: —
+superseded_by: —
+phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
+type: structural
+---
+
+# ADR-071 — Wire the Tier-1 drive loop into `POST /launch` (v0)
+
+## Status
+
+**Accepted** · 2026-06-08. Design converged via AI-council (claude-sonnet-4-5 +
+gpt-4o, design mode, 2026-06-08). This is **PR 2** of the drive-loop work
+([`ADR-070`](ADR-070-tier1-drive-loop.md) was PR 1 — the executor). The council
+heavily stress-tested the failure paths; two facts defused the sharpest
+critiques and shaped the final design (see Consequences).
+
+## Context
+
+The pieces existed but were unwired: `workspace_render.py` (ADR-069) renders a
+task prompt; `workspace_drive.py` (ADR-070) drives one Tier-1 turn;
+`workspace_sessions.py` records encrypted events; `detectHostTier` (ADR-068)
+reported `tier1-drive-pending`. `POST /launch {role, task, host}` wrote a
+session header and stopped. This ADR makes a Tier-1 launch actually drive a
+turn, and degrades cleanly everywhere else.
+
+## Decision
+
+| # | Question | Verdict | Rationale |
+|---|---|---|---|
+| 1 | Where the prompt comes from | **Fat launch** — `POST /launch {role, task, inputs?, host}` resolves task→prompt, renders in-process, drives. | One round-trip is the natural UX; the render *endpoint* stays pure (launch calls the render module, doesn't re-implement it). Render failure → `host.error(render-error)` + `{driven:false}`, **no drive attempt**. |
+| 2 | Backwards compatibility | **Additive.** Header always written first; driving only when the task resolves to a prompt AND the host is tier 1. Inputs supplied to a no-prompt task → explicit `{driven:false, reason:"no-prompt-for-task", ignored_inputs:true}`. | The legacy `{role, task, host}` → header contract is unchanged; no silent input drops. |
+| 3 | What gets appended | Header (`launcher.input`), then **exactly one** `host.turn` (success) or `host.error` (render / drive failure). | Each launch mints a **fresh** session id → no shared-session append race; "single append" needs no lock in v0. |
+| 4 | Degrade matrix | Tier-3 host, or tier-1 drive failure: **best-effort** inbox hand-off when the flag is on (write rendered prompt, append `inbox.handoff`); flag off → header + tier only. | The session record is the source of truth; the inbox is a convenience, so its write is best-effort (try/catch, never fails the response). |
+| 5 | Timeout response | **HTTP 200** always, with `{driven:false, error_kind:"timeout"}`; never 202. | The session + error are recorded synchronously; a 202 would imply async continuation that does not exist. |
+
+### Response shape
+
+`POST /launch` always returns 200 with the session header fields + tier, plus:
+
+- success: `{driven:true, turn:{…uniform turn…}}`
+- no prompt: `{driven:false, reason:"no-prompt-for-task", ignored_inputs?:true}`
+- render error: `{driven:false, error_kind:"render-error", error}`
+- tier-3 / drive failure: `{driven:false, error_kind?, error?, handoff?}` (`handoff` present iff the inbox flag was on and the write succeeded)
+
+## Consequences
+
+- **No shared-session race** (council's biggest concern): every launch mints a
+  new session id, so two concurrent launches write two sessions, never a
+  double-append to one. The "single append" invariant is per-launch and needs
+  no lock in v0.
+- **No partial-output-on-timeout** (council's second concern): `claude -p
+  --output-format json` is non-streaming; on a timeout the subprocess is killed
+  with no parseable envelope, so `host.error(timeout)` carries metadata only.
+- The session log stays the single source of truth — every outcome (turn,
+  render-error, drive-error, handoff) is recorded through the encrypted store
+  (ADR-064); the response mirrors what was recorded.
+- Driving is opt-in and additive; existing GUI callers that send no inputs and
+  hit a no-prompt task keep their header-only behaviour.
+
+## Alternatives considered
+
+- **Thin launch (client renders via `/render`, passes the prompt to launch)** —
+  rejected for v0: two round-trips for the common path; the render endpoint
+  staying pure already preserves the separation the thin shape was protecting.
+- **Separate `POST /launch/:id/drive`** — rejected (ADR-070 decision 4):
+  orphaned-session risk with no rollback/dedup in v0.
+- **202 on timeout** — rejected: implies async continuation we do not have; the
+  error is recorded synchronously, so 200 is honest.
+- **Fail the response when the inbox degrade write fails** — rejected: the
+  session error is already recorded; the hand-off is a convenience, so its
+  failure must not mask a recorded outcome.
+
+## Deferred to v1 (debt)
+
+- Multi-turn / tool execution (inherited from ADR-070).
+- `codex` / `gemini` drive configs (the unified `drive()` is ready).
+- Pre-flight checks (disk / key validity) + write-ahead recovery for the
+  header→turn sequence — v0 relies on best-effort append + the always-present
+  header for recovery.
+- Drive metrics + a kill-switch flipping tier-1 to inbox-only on a failure-rate
+  threshold.
+
+## References
+
+- [`ADR-070`](ADR-070-tier1-drive-loop.md) — the drive executor (PR 1).
+- [`ADR-069`](ADR-069-prompt-renderer.md) — the renderer launch calls in-process.
+- [`ADR-068`](ADR-068-host-tier-detection.md) — tier detection gating the drive.
+- [`ADR-065`](ADR-065-tier3-inbox-handoff-v0.md) — the inbox the degrade path writes to.
+- [`ADR-064`](ADR-064-append-jsonl-per-record-encryption.md) — the encrypted session store.
+- [`daily-workspace`](../contracts/daily-workspace.md) — `/launch` surface contract.