@event4u/agent-config 5.10.1 → 6.0.0

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

@@ -0,0 +1,92 @@
+---
+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

@@ -0,0 +1,71 @@
+---
+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

@@ -0,0 +1,58 @@
+---
+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

@@ -0,0 +1,85 @@
+---
+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

@@ -0,0 +1,52 @@
+---
+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

@@ -0,0 +1,158 @@
+---
+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).