@event4u/agent-config 9.7.0 → 9.9.0

package/docs/decisions/ADR-078-drive-health-panel.md

@@ -1,70 +0,0 @@
----
-adr: 078
-status: accepted
-date: 2026-06-09
-decision: drive-health-panel
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-078 — WorkspacePage drive-health panel (read-only)
-
-## Status
-
-**Accepted** · 2026-06-09. Closes the GUI debt deferred by
-[`ADR-073`](ADR-073-drive-health-kill-switch.md) ("a dedicated health panel")
-and [`ADR-075`](ADR-075-workspace-gui-drive.md) (deferred the drive-health UI).
-Small mechanical reuse — consumes the existing `GET /drive-health` (ADR-073);
-no server change, no council (read-only display of existing data).
-
-## Context
-
-The kill-switch (ADR-073/074) trips a host to inbox-only after repeated drive
-failures and auto-recovers it on a cooldown probe. `GET /drive-health` exposes
-that state, but the GUI only reflected `host_killed` / `recovered` transiently
-in a launch banner — an operator had no standing view of *which* host is paused
-and *why*.
-
-## Decision
-
-- A read-only **Host health** panel in the workspace rail, fed by the existing
-  `GET /drive-health` (fetched in `load()`, **non-critical**: a failed health
-  fetch never blocks the page — it falls back to an empty snapshot).
-- Surfaces **only unhealthy hosts** (killed, or with a non-zero failure
-  streak); the common all-healthy case shows a one-line "All hosts healthy."
-- Per host: state (`paused — auto-recovering` for an auto-trip, `paused
-  (manual)` for a manual kill, `degraded` for a streak without a trip), the
-  failure streak, and the last error kind.
-- **No reset action in v0** — reset stays a CLI op (`workspace_drive_health.py
-  reset`); auto-cooldown (ADR-074) handles the common recovery, so a GUI reset
-  button (which would need a new state-mutating endpoint) is deferred.
-
-## Consequences
-
-- An operator can see at a glance why a host isn't driving and whether it is
-  auto-recovering — the observability the kill-switch councils asked for.
-- Purely additive + non-critical: no server change, and a health-endpoint
-  failure degrades to "All hosts healthy" rather than breaking the workspace.
-
-## Alternatives considered
-
-- **A reset button in the panel** — deferred: needs a new POST endpoint
-  (state mutation); auto-recovery covers the common case, so v0 stays
-  read-only.
-- **Always list every host (including healthy)** — rejected: noise; the panel
-  earns its space only when something is wrong.
-- **Poll `/drive-health` on an interval** — deferred: a load-time snapshot +
-  the launch banner's live `host_killed`/`recovered` cover v0; live polling is
-  a later refinement.
-
-## Deferred to v1 (debt)
-
-A GUI reset button (+ its endpoint), live polling / refresh, and a full
-per-host history view (totals, trip count over time).
-
-## References
-
-- [`ADR-073`](ADR-073-drive-health-kill-switch.md) / [`ADR-074`](ADR-074-drive-kill-switch-auto-recovery.md) — the kill-switch + `GET /drive-health` this surfaces.
-- [`ADR-075`](ADR-075-workspace-gui-drive.md) — the GUI rail + patterns reused.

package/docs/decisions/ADR-079-workspace-host-picker.md

@@ -1,81 +0,0 @@
----
-adr: 079
-status: accepted
-date: 2026-06-09
-decision: workspace-host-picker
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-079 — WorkspacePage host picker (v1)
-
-## Status
-
-**Accepted** · 2026-06-09. Design + a focused tie-break converged via AI-council
-(claude-sonnet-4-5 + gpt-4o, design mode, 2026-06-09). **Reverses the v0
-deferral** in [`ADR-075`](ADR-075-workspace-gui-drive.md) (which hard-coded
-`host: 'claude-code'` "until real usage / if users demand it"): the backend now
-drives all three Tier-1 hosts (ADR-072), so surfacing the choice is the
-anticipated v1.
-
-## Context
-
-ADR-075 deferred a host picker citing "host ids ≠ model names (confusing), an
-N×M test matrix, an unrequested feature." With codex + gemini drive configs
-merged, the picker is the natural v1. This ADR confirms the reversal and
-addresses the UX concern the deferral raised.
-
-## Decision
-
-| # | Question | Verdict | Rationale |
-|---|---|---|---|
-| 1 | Labels | **Friendly label + id**: `Claude Code (claude-code)`, `Codex (codex)`, `Gemini (gemini)`. | Resolves the "ids are confusing" concern without hiding the id the backend uses. |
-| 2 | Placement | **Global header `<select>`** (one host per session) — **tie-break decision**. | Round 2 split (global vs per-task); the tie-break converged on global: v0 was already session-global, zero data on per-task switching, per-task + sessionStorage has the *same* stickiness with more UI repetition. |
-| 3 | Persistence | Default `claude-code`; persist in **`sessionStorage`** (per-session), not `localStorage`. | Cross-session stickiness without usage data is speculative ("spooky action"); session scope matches the picker's session-global model. |
-| 4 | Options | The **three Tier-1 hosts** only. | The inbox is already the automatic degrade when a CLI is absent — a manual inbox option is redundant chrome. |
-| 5 | Availability | A new **`GET /workspace/hosts`** returns each Tier-1 host's `cli_present`; the picker **disables an uninstalled host** with a "not installed" note. **Fail open** — no availability data → all hosts selectable. | The council's hardest hit: a "dumb" picker lets a user pick an absent host and waste a launch that only degrades to the inbox. The probe is side-effect-free (`shutil.which`), no API spend. |
-
-No feature flag: the picker **defaults to `claude-code`**, exactly v0's
-behaviour, so the safe fallback is the default itself.
-
-## Surface
-
-- `GET /api/v1/workspace/hosts` → `{ hosts: [{ id, cli_present, effective_tier }] }`
-  (Tier-1 only, via `workspace_hosts.py list`). Fail-open to `[]`.
-- `WorkspacePage`: a header `HostPicker` `<select>` (friendly labels, absent
-  hosts disabled) → `setSelectedHost` persists to `sessionStorage`; `launch()`
-  sends `selectedHost`. Continuation still resumes the session's recorded host
-  (unchanged).
-
-## Consequences
-
-- An employee can run a task on Codex or Gemini, not just Claude Code, and sees
-  which hosts are actually installed before picking.
-- Availability + host fetches are **non-critical** in `load()` — a failure
-  degrades to "all hosts enabled" / empty, never blocks the page.
-- Continuation (ADR-076) is unaffected — it always resumes the host recorded on
-  the session's turns, regardless of the current picker value.
-
-## Alternatives considered
-
-- **Per-task picker** — rejected at tie-break: same stickiness as the global
-  select with more per-launch chrome; no evidence for per-task host variance.
-- **localStorage persistence** — rejected: cross-session stickiness is
-  speculative without usage data.
-- **Manual "inbox hand-off" option** — rejected: redundant with the automatic
-  absent-CLI degrade.
-- **Dumb picker (no availability)** — rejected: wastes a launch on an absent
-  host; the cheap `which` probe avoids the first-run friction.
-
-## Deferred to v1+ (debt)
-
-Live availability polling (re-probe without a reload), a model-tier hint per
-host, and per-task host override (only if usage shows real per-task variance).
-
-## References
-
-- [`ADR-075`](ADR-075-workspace-gui-drive.md) — the v0 deferral this reverses.
-- [`ADR-072`](ADR-072-codex-gemini-drive-configs.md) — the codex/gemini drive configs that make the choice meaningful.
-- [`ADR-068`](ADR-068-host-tier-detection.md) — `workspace_hosts.py` detection the `/hosts` endpoint reuses.

package/docs/decisions/ADR-080-host-session-expired-410.md

@@ -1,92 +0,0 @@
----
-adr: 080
-status: accepted
-date: 2026-06-09
-decision: host-session-expired-410
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-080 — `/continue` 410 on an expired host session
-
-## Status
-
-**Accepted** · 2026-06-09. Implements the 410 mapping
-[`ADR-076`](ADR-076-workspace-multi-turn.md) deferred ("a 410 'host session
-expired' mapping needs per-host stderr detection → v1"). No council — ADR-076
-already fixed the *shape* (410, per-host stderr); this PR supplies the verified
-signatures.
-
-## Context
-
-`POST /sessions/:id/continue` resumes a host session by its recorded id. If the
-host has since garbage-collected / never had that session, resume fails — but
-ADR-076 returned a generic `{driven:false, error_kind}` indistinguishable from a
-transient failure. The GUI should tell the user "start a new conversation," not
-show a generic error.
-
-## Decision
-
-Detect an expired / unknown host session from the host CLI's stderr **only on
-the resume path** and map it to a distinct `error_kind: 'session-expired'`,
-which `/continue` answers as **HTTP 410 Gone** (`start a new conversation`).
-
-**Verified stderr signatures** (probed 2026-06-09 with a bogus session id —
-fast-fail, no LLM turn):
-
-| Host | Signature (substring, case-insensitive) |
-|---|---|
-| claude | `No conversation found with session ID` |
-| gemini | `Invalid session identifier` |
-| codex | `no rollout found for thread id` / `thread/resume failed` |
-
-Plus a generic `session not found` catch-all. `_is_session_expired(stderr)` is
-substring-matched and **best-effort + extensible** — a new host (or a vendor
-wording change) adds a signature; an unmatched failure stays the generic
-`nonzero-exit` / `bad-envelope`.
-
-**Scope guard:** the mapping fires **only when `resume_session_id` is set** — the
-identical stderr on a fresh launch stays `nonzero-exit` (a fresh launch has no
-session to expire).
-
-## Consequences
-
-- A continued conversation whose host session is gone returns **410** with a
-  clear "start a new conversation" message — the GUI can route the user to a
-  fresh launch rather than surfacing a confusing drive error.
-- 410 is the honest code: not 5xx (our system is fine), not 4xx (the request was
-  valid) — a gone resource.
-- The session log still records the `host.error(session-expired)` (audit trail);
-  health recording still applies (a probe that hits an expired session counts as
-  a failure, consistent with the kill-switch).
-
-## Alternatives considered
-
-- **Keep the generic error** — rejected: indistinguishable from a transient
-  failure; the user can't tell they need a fresh conversation.
-- **Parse exit codes instead of stderr** — rejected: the three CLIs use
-  different / overlapping exit codes; the stderr message is the reliable signal.
-- **A 409** — rejected: 409 already means "no host turn to continue" (ADR-076);
-  410 (gone) is the correct distinct semantics for an expired session.
-
-## Testing note
-
-The detector is covered hermetically by `workspace_drive.py` pytest (stubbed
-stderr with all three verified signatures + the resume-only scope guard). The
-Node `error_kind → 410` mapping is a trivial one-line map and is exercised
-through that detector — a Node-level vitest would need a real host CLI to emit
-the signature (absent in CI), so it follows the established pattern of covering
-real-drive paths in pytest, not vitest.
-
-## Deferred to v1+ (debt)
-
-A GUI affordance that, on a 410, offers a one-click "start a fresh conversation"
-(re-launch the same role/task). Signature drift monitoring (alert if an
-unmatched resume failure rate climbs — it may signal a new vendor wording).
-
-## References
-
-- [`ADR-076`](ADR-076-workspace-multi-turn.md) — `/continue` + the deferred 410 this closes.
-- [`ADR-072`](ADR-072-codex-gemini-drive-configs.md) — the three host CLIs whose stderr is matched.

package/docs/decisions/ADR-081-drive-health-reset-and-410-affordance.md

@@ -1,71 +0,0 @@
----
-adr: 081
-status: accepted
-date: 2026-06-09
-decision: drive-health-reset-and-410-affordance
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-081 — Drive-health reset endpoint + 410 follow-up affordance
-
-## Status
-
-**Accepted** · 2026-06-09. Closes two deferred GUI items: the reset button
-[`ADR-078`](ADR-078-drive-health-panel.md) deferred ("reset stays a CLI op …
-a GUI reset button needs a new state-mutating endpoint → deferred") and the
-410 affordance [`ADR-080`](ADR-080-host-session-expired-410.md) deferred ("a
-GUI 'start a fresh conversation' one-click on 410"). Mechanical — no council.
-
-## Context
-
-The kill-switch panel (ADR-078) was read-only; clearing a paused host meant the
-CLI. And a `/continue` 410 (ADR-080) only set a banner — the follow-up box
-stayed, inviting a retry that would 410 again.
-
-## Decision
-
-1. **`POST /api/v1/workspace/drive-health/:host/reset`** → `workspace_drive_health.py
-   reset` → returns the reset state. The operator escape hatch for a paused
-   host (and the *only* path for a sticky **manual** kill, which auto-recovery
-   never clears). An invalid host id → 400 (CLI charset/root guard).
-2. **Reset button** in the health panel, shown **only on a killed host**; click
-   → reset → re-fetch `/drive-health` → the row clears.
-3. **410 affordance:** when `/continue` returns 410 (host session expired), the
-   GUI sets a `sessionGone` flag → the follow-up form is **replaced** by
-   "Host session expired — pick a task above to start a new conversation."
-   `sessionGone` resets on the next launch.
-
-## Consequences
-
-- A paused host can be cleared from the browser — completing the kill-switch
-  UX (auto-recovery for transient trips, one-click reset for the rest +
-  sticky manual kills).
-- A 410 no longer leaves a dead follow-up box: the user is routed to start a
-  fresh conversation instead of retrying into another 410.
-- Reset is a low-risk local-cache mutation (clears `workspace/health/<host>.json`
-  flags); no model/data/infra surface, so no threat-model gate.
-
-## Alternatives considered
-
-- **Keep reset CLI-only** — rejected now: with the panel surfacing paused hosts,
-  a reset there is the obvious completion; the endpoint is a thin CLI wrapper.
-- **410 → just a banner (keep the form)** — rejected: invites a retry that
-  410s again; replacing the form is the honest dead-end signal.
-- **A one-click "re-launch same task" on 410** — deferred: needs to remember
-  the originating task + inputs; the "pick a task above" pointer is enough for
-  v1.
-
-## Deferred to v1+ (debt)
-
-A one-click re-launch (same role/task/inputs) on 410; a manual "pause this host"
-button (the inverse of reset) if operators want to force a host off; live
-polling so a reset / recovery elsewhere reflects without a reload.
-
-## References
-
-- [`ADR-078`](ADR-078-drive-health-panel.md) — the read-only panel this makes actionable.
-- [`ADR-080`](ADR-080-host-session-expired-410.md) — the 410 this gives a GUI affordance.
-- [`ADR-073`](ADR-073-drive-health-kill-switch.md) / [`ADR-074`](ADR-074-drive-kill-switch-auto-recovery.md) — the kill-switch + `reset` semantics.

package/docs/decisions/ADR-082-410-one-click-relaunch.md

@@ -1,58 +0,0 @@
----
-adr: 082
-status: accepted
-date: 2026-06-09
-decision: 410-one-click-relaunch
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-082 — One-click re-launch on a 410 (expired host session)
-
-## Status
-
-**Accepted** · 2026-06-09. Closes the deferral in
-[`ADR-081`](ADR-081-drive-health-reset-and-410-affordance.md) ("a one-click
-re-launch (same role/task/inputs) on 410"). GUI-only, mechanical — no council,
-no server change.
-
-## Context
-
-ADR-080/081 made `/continue` answer 410 on an expired host session and replaced
-the follow-up form with a "pick a task above to start a new conversation" note.
-That pointer made the user re-pick the role, re-open the task, and re-type the
-inputs — friction for what is just "run the same thing in a fresh session."
-
-## Decision
-
-- `launch()` remembers the originating `{ role, task, inputs }` in a
-  `lastLaunch` signal.
-- The 410 affordance renders a **"Start a new conversation"** button when
-  `lastLaunch` is set; clicking it re-invokes `launch(role, task, inputs)` — a
-  fresh session with the same parameters (and the current host pick). It falls
-  back to the "pick a task above" pointer only when there is no remembered
-  launch.
-
-## Consequences
-
-- A user whose host session expired re-runs the same task in one click, instead
-  of re-entering everything.
-- Re-launch goes through the normal `launch()` path — same kill-switch gate,
-  health recording, and `sessionGone` reset; the new turn replaces the expired
-  one in the result pane.
-- No new endpoint and no server change — `lastLaunch` is GUI state.
-
-## Alternatives considered
-
-- **Re-pick manually (the ADR-081 pointer)** — kept as the fallback when no
-  prior launch is remembered, but the button is the common case.
-- **Persist `lastLaunch` across reloads** — unnecessary: a 410 is acted on in
-  the same session it occurred; cross-reload memory adds no value.
-
-## References
-
-- [`ADR-081`](ADR-081-drive-health-reset-and-410-affordance.md) — the 410 affordance this completes.
-- [`ADR-080`](ADR-080-host-session-expired-410.md) — the 410 itself.
-- [`ADR-075`](ADR-075-workspace-gui-drive.md) — the `launch()` flow re-invoked.

package/docs/decisions/ADR-083-session-thread-and-arbitrary-continuation.md

@@ -1,85 +0,0 @@
----
-adr: 083
-status: accepted
-date: 2026-06-09
-decision: session-thread-and-arbitrary-continuation
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-083 — Session thread view + arbitrary continuation
-
-## Status
-
-**Accepted** · 2026-06-09. Design converged via AI-council (claude-sonnet-4-5 +
-gpt-4o, design mode, 2026-06-09). Ships in two PRs (council sequencing): **PR-1**
-the server record (this ADR + the `/continue` follow-up record); **PR-2** the
-GUI (clickable session strip + thread view + continuation target). Closes the
-last substantive ADR-075 deferral.
-
-## Context
-
-The workspace shows only the **latest** turn and only continues the **active**
-session. Two gaps: no full **thread** (each turn replaces the prior), and no
-**arbitrary continuation** (a past session in the strip isn't clickable).
-
-**Load-bearing log fact:** the session JSONL records `launcher.input` (opening
-task + inputs) + one `host.turn` per assistant reply — but the **user's
-follow-up prompts were not recorded**, so a thread would show replies without
-the questions that produced them.
-
-## Decision
-
-| # | Question | Verdict |
-|---|---|---|
-| 1 | Record follow-up prompts? | **Yes** — `/continue` appends a `launcher.input` with `followup: true` carrying the `prompt`, **before** driving (so the question survives a failed turn). **Reuse** `launcher.input` (no new record kind). |
-| 2/4 | Thread render | The result area renders the log as ordered blocks: opening task, then interleaved user (`launcher.input followup`) + assistant (`host.turn`) + error (`host.error`) blocks; reuse the 2000-char collapse. |
-| 3 | Continuation target | A selected session's id is the `/continue` target; 409 / 410 surface as before. |
-| 5 | State | **One "current session"** drives both the thread and the follow-up box; launching sets it to the new session, selecting a strip session sets it to that one. |
-
-**Privacy (council's hardest pushback — shared sessions):** defused by a fact —
-the workspace is **per-user / local** (`daily-workspace` § State scope: "Per-user.
-Local-only. One workspace per OS user. No multi-tenant view"). The follow-up
-prompt is the same user's text at the same encrypt-at-rest tier as every other
-record; recording it expands **no** privacy surface. (If the workspace ever
-gains multi-user session sharing, follow-up-prompt classification must be
-revisited — flagged here.)
-
-**Old sessions** (pre-recording) have no follow-up records → the thread shows
-the opening task + assistant turns, degrading gracefully (no crash, no
-placeholder noise).
-
-No feature flag: the record is additive + low-risk; rollback is a revert.
-
-## Consequences
-
-- A real thread (question → answer → question → answer) for sessions created
-  after PR-1; reply-only for older ones.
-- Any past session is continuable from the strip — the workspace becomes a
-  browseable, resumable conversation history, not just a launch pad.
-- One server record append per follow-up; the GUI keys the thread + follow-up
-  off a single current-session id.
-
-## Alternatives considered
-
-- **New `launcher.followup` record kind** — rejected: schema proliferation; a
-  `followup: true` field on `launcher.input` is enough.
-- **Assistant-turns-only thread (no recording)** — rejected: a thread without
-  the questions is confusing; the record is one cheap append.
-- **Two parallel result components (active vs selected)** — rejected: the
-  council's one-current-session model is cleaner; the thread view subsumes the
-  single-turn display.
-
-## Deferred to v1+ (debt)
-
-Idempotency on rapid double-submits (v0 has no retry semantics); progressive /
-streamed loading for very long session logs; a multi-user-sharing revisit of
-follow-up-prompt classification (only if session sharing is ever added).
-
-## References
-
-- [`ADR-076`](ADR-076-workspace-multi-turn.md) — `/continue` this records into.
-- [`ADR-075`](ADR-075-workspace-gui-drive.md) / [`ADR-082`](ADR-082-410-one-click-relaunch.md) — the GUI result area the thread view subsumes.
-- [`daily-workspace`](../contracts/daily-workspace.md) § State scope — the per-user/local fact that defuses the privacy concern.

package/docs/decisions/ADR-084-drive-health-refresh-on-drive.md

@@ -1,52 +0,0 @@
----
-adr: 084
-status: accepted
-date: 2026-06-09
-decision: drive-health-refresh-on-drive
-supersedes: —
-superseded_by: —
-phase: employee-product Phase 8 (road-to-employee-product-and-external-proof)
-type: structural
----
-
-# ADR-084 — Refresh drive-health after every drive
-
-## Status
-
-**Accepted** · 2026-06-09. Addresses the "live health" polish deferred by
-[`ADR-078`](ADR-078-drive-health-panel.md) (the panel was a load-time snapshot).
-Trivial, GUI-only — no council, no server change.
-
-## Context
-
-The drive-health panel (ADR-078) fetched once on page load and after a manual
-reset (ADR-081). But a host trips / auto-recovers **as a side effect of a
-drive** — so during a session the panel could show stale state (e.g. a host that
-just tripped on the last launch still shows healthy until a reload).
-
-## Decision
-
-Re-fetch `GET /drive-health` after every `launch` and `continue` (a small
-`refreshHealth()` helper, reused by the reset path). **Refresh-on-drive**, not
-`setInterval` polling: health only changes on a drive the user just initiated,
-so polling would be wasted requests + a timer to manage; refreshing exactly when
-state can change is sufficient and cheaper. Non-critical — a failed refresh
-leaves the panel as-is (same fail-open posture as the initial load).
-
-## Consequences
-
-- The panel reflects a host tripping / recovering immediately after the drive
-  that caused it, with no reload.
-- No timer, no background polling, no new endpoint — one extra GET per drive.
-
-## Alternatives considered
-
-- **`setInterval` polling** — rejected: health is event-driven (only a drive
-  changes it); polling burns requests for a local single-user tool and adds a
-  timer lifecycle to manage.
-- **Server push / SSE** — over-engineered for a local single-user panel.
-
-## References
-
-- [`ADR-078`](ADR-078-drive-health-panel.md) — the panel this keeps fresh.
-- [`ADR-081`](ADR-081-drive-health-reset-and-410-affordance.md) — the reset path the `refreshHealth()` helper is shared with.

package/docs/decisions/ADR-085-mcp-stdio-end-user-distribution-shape.md

@@ -1,158 +0,0 @@
----
-adr: 085
-status: accepted
-date: 2026-06-10
-decision: mcp-stdio-end-user-distribution-shape
-supersedes: —
-superseded_by: —
-phase: mcp-stdio-end-user-packaging Phase 1 (road-to-mcp-stdio-end-user-packaging)
-type: structural
----
-
-# ADR-085 — Distribution shape for the turnkey end-user stdio MCP server
-
-## Status
-
-**Accepted** · 2026-06-10. Phase 1 (decision-only, no code) of
-[`road-to-mcp-stdio-end-user-packaging`], promoted from `draft → ready` by an
-explicit maintainer decision (the demand trigger, recorded below). Resolved via
-a two-round peer-reviewed AI-council session plus a tie-break round
-(claude-sonnet-4-5 + gpt-4o, 2026-06-10) — split in round 1 (A2×B1 vs A1×B2),
-**converged on A2×B1** in the tie-break.
-
-## Context
-
-`@event4u/agent-config` already ships **two** MCP surfaces under a named-scope
-model:
-
-- `mcp_scope: lite` — a **hosted Cloudflare Worker** (`internal/workers/mcp/`,
-  TypeScript) serving governance content as read-only MCP prompts + resources
-  (skills/commands/rules/guidelines) plus a few read-only tools, from a
-  release-pinned R2 blob. Never executes, never touches consumer FS.
-- `mcp_scope: full` — a **local stdio kernel** (`src/scripts/mcp_server/`,
-  Python) that can execute tools and depends on ~112 on-disk scripts + a
-  consumer `.agent-settings.yml`. Launched today only from a cloned repo:
-  `PYTHONPATH=src .venv-mcp/bin/python -m scripts.mcp_server`.
-
-The npm bin already exists: `agent-config` → `dist/cli/agent-config.js` (Node
-≥20). There is **no** stdio client-config template for end-users; the only
-templates target the remote Worker via `mcp-remote`.
-
-**Gap.** End-users who *configure* pre-built agents (Claude Desktop / Cursor /
-Zed / Claude Code) cannot run a **local** stdio server without cloning the repo
-and building a venv. The decision is the whole design — two coupled axes:
-**scope** (full execution vs read-only lite) and **launch channel** (npm-Node vs
-pipx/uvx vs bundled-venv).
-
-### Demand trigger (recorded per the roadmap precondition)
-
-The roadmap is promoted on the precondition clause *"the maintainer decides to
-position the package for end-users explicitly."* That decision was made on
-2026-06-10 (maintainer instruction: "promote mcp-stdio, do Phase 1"). The
-trigger is **positioning for end-users who configure agents** — note it does
-**not** state those users need *execution*; it states they need local access to
-the content.
-
-## Decision
-
-**A2 × B1** — a local **stdio-lite** server, pure-Node, launched via the
-existing `@event4u/agent-config` npm bin. It serves the shipped `dist/`
-governance content (skills / commands / rules / guidelines) as MCP prompts +
-resources plus the read-only tools (`memory_lookup`, `list_*`,
-`read_resource_body`). **No Python, no venv, no execution, no consumer-FS
-writes.**
-
-This is architecturally proven: the hosted lite Worker already does exactly this
-in TypeScript from an R2 blob; the local server reads the bundled `dist/`
-instead. A local stdio-lite adds an **offline / no-account / Worker-outage
-fallback** path — a reliability hedge, cheap to ship in Node, with no
-Node→Python handoff.
-
-### Why not the alternatives
-
-- **A1×B1 (full Python kernel launched by the Node bin) — rejected as fatal.**
-  A long-running stdio daemon needs a clean stdin/stdout JSON-RPC contract; a
-  Node shim spawning Python leaks (npm update checks, debug logs, stderr) and
-  breaks the protocol. Both council members converged on this. The channel
-  **must** match the implementation language: A2→B1 (pure Node) or A1→B2 (pure
-  Python). No mixed handoff.
-- **A1×B2 (full Python kernel via pipx/uvx) — deferred, not chosen.** It ships
-  the ~112 executable scripts and therefore demands a platform matrix
-  (linux-x64 / darwin-arm64 / win32-x64), a supply-chain threat model, a
-  first-run consent flow, and a kill-switch — all Phase-1-blocking. There is **no
-  evidence** end-users need execution (vs content access); committing that
-  surface now is building the maximal surface for a speculative problem, against
-  `minimal-safe-diff` + YAGNI and the council's standing "do not build end-user
-  packaging on spec" caution.
-- **B3 (bundled venv / self-contained binary) — deferred.** Only justified if a
-  material fraction of the audience has *neither* Node nor Python; no such data
-  exists, and the stated clients (Claude Desktop / Cursor / Zed / Claude Code)
-  overwhelmingly carry Node.
-
-## Consequences
-
-### Trade-off the maintainer accepts
-
-**Zero local script execution in Phase 1.** A user who needs to *run* a script
-must file an issue or self-host the Python `full` kernel separately. The
-turnkey path serves content access only.
-
-### Phase-2 upgrade trigger (when the deferred execution axis flips)
-
-Flip to A1×B2 scoping (platform matrix + consent UI + sandboxing) when **any**
-of:
-
-- **≥ 3** end-user issues request execution of *named* scripts (any tier), **or**
-- **≥ 1** issue requests a *write / mutate* script (flips immediately — higher
-  risk), **or**
-- **≥ 1** corporate adopter requires auditable local execution.
-
-(The tie-break preferred this tighter, falsifiable trigger over a flat "≥ 20
-requests"; the threshold remains the maintainer's to tune.)
-
-### Phase-2 prerequisites surfaced now (council blind-spot fold-in)
-
-These are **not** Phase-1 work (Phase 1 is ADR-only) but the roadmap's later
-phases should land them so a Phase-2 flip is a configuration change, not a
-discovery project:
-
-- A **script-dependency manifest** (each script's PyPI/stdlib imports) +
-  **execution-tier tags** (read-only / mutate / network) + a one-time **CVE
-  baseline scan** (`pip-audit` / `safety`), e.g. `dist/scripts-meta.json`.
-- A **`list-scripts`** discoverability tool that surfaces the corpus with tier +
-  availability metadata ("execution: deferred to Phase 2") so end-users see what
-  exists without it being runnable.
-
-### Positive
-
-- Smallest turnkey path that solves the *stated* problem (local content access).
-- No new packaging toolchain, no venv, no platform matrix, no execution security
-  surface in Phase 1.
-- Multi-channel content consistency + a Worker-outage fallback.
-
-### Negative / cost
-
-- Read-only MCP tools (`memory_lookup`, `list_*`, `read_resource_body`) get a
-  Node reimplementation (~200–300 LOC) over the shipped `dist/` artefacts,
-  duplicating the Python handlers. Accepted as a one-time tax that buys the
-  elimination of the trust-boundary, platform-matrix, and rollback complexity
-  A1 would introduce.
-
-## Alternatives
-
-| Shape | Verdict |
-|---|---|
-| **A2×B1** pure-Node stdio-lite via npm bin | **Chosen** — minimal-safe-diff, no handoff, reliability hedge |
-| A1×B2 full Python kernel via pipx/uvx | Deferred — no execution-demand evidence; heavy security surface |
-| A1×B1 full kernel via Node bin | Rejected (fatal) — Node→Python stdout pollution breaks JSON-RPC |
-| B3 bundled venv / self-contained binary | Deferred — only for a no-runtime audience; no data |
-
-## References
-
-- Roadmap: `road-to-mcp-stdio-end-user-packaging` Phase 1 (under `agents/roadmaps/`).
-- [`ADR-067`](ADR-067-glama-registry-listing.md) — the Glama listing (targets
-  *contributors*; this ADR targets *end-users*).
-- [`mcp-cloud-scope`](../contracts/mcp-cloud-scope.md) — the lite/full scope model.
-- [`mcp-phase-1-scope`](../contracts/mcp-phase-1-scope.md) — owns `scripts/mcp_server/` (local stdio).
-- Council convergence: claude-sonnet-4-5 + gpt-4o, 2026-06-10 (round 1 split
-  A2×B1 / A1×B2, tie-break converged A2×B1).