diff --git a/docs/prds/extensions-center.md b/docs/prds/extensions-center.md new file mode 100644 index 000000000..1b61f7fc2 --- /dev/null +++ b/docs/prds/extensions-center.md @@ -0,0 +1,170 @@ +# Extensions center + +Epic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` ("Replace Skills +with a bundled Extensions center"). + +Skills, Workflows, and Tools/MCP already exist as separate, working +inventories with their own APIs (`api_skills.go`, `api_workflows.go`, +config-driven MCP servers) and their own family-owned controller pattern +(`curator.Registry`, `health.Registry`, `image.Registry`, +`workflow.Registry` all already prove this shape). `plugin.Plugin` +(`internal/plugin/plugin.go:24-27`) is already metadata-only, per +`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here. +What's missing, confirmed by grep, is: any config schema for enabling or +disabling a capability, any "pending restart" state tracking, and any single +inventory that reconciles configured/bundled/discovered/active state across +families. This document decides those three things and the UI surface that +presents them. It extends `plugins-and-extensions.md` rather than replacing +it — that doc's decisions (metadata-only `Plugin`, typed capability +families, no generic dispatch) are unchanged. + +Out of scope: any remote or arbitrary-URL plugin installation path (the +epic's own acceptance criteria forbid this, and `plugin.LoadDir` +(`plugin.go:51-91`) already only reads `~/.config/archie/plugins/*.go` — this +document does not add a fetch-by-URL variant to it). + +## Problem + +`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no +`enabled` field (confirmed by the investigation grep). `api_config.go`'s +`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state +distinguishing "saved, takes effect now" from "saved, needs restart" — the +only existing reload path (`ReloadChannel`, `server.go:85`) is +channel-specific and explicitly does not cover plugins or MCP servers. +`server.go:28-147` already wires five separate optional inventories +(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as +independent fields with no unifying type — an operator today has no single +place to see "what's available, what's enabled, what's actually running, +and what's degraded" across all of them. `ui/src/` has `settings/`, +`skills/`, and `workflows/` directories already; there is no +`ui/src/extensions/`. + +## Design + +### Unified inventory type + +```go +package extensions // internal/domain/extensions — new, app-level aggregator + +type State string + +const ( + StateAvailable State = "available" // bundled, not configured + StateEnabled State = "enabled" // configured on, not yet live + StateActive State = "active" // configured on and running + StateDegraded State = "degraded" // active but unhealthy + StateSkipped State = "skipped" // optional, disabled by config + StatePendingRestart State = "pending_restart" // config changed, not yet live +) + +type Entry struct { + Family string // "skill" | "workflow" | "tool" | "plugin" | "integration" + Name string + Core bool // non-disableable + State State + Health string // reuses whatever the family's own registry already reports +} + +type Inventory interface { + List(ctx context.Context) ([]Entry, error) +} +``` + +**Decision.** `extensions.Inventory` is a read-only aggregator, not a new +domain that owns state. It queries each family's existing registry +(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client +set, `plugin.LoadDir`'s result) for live state, and compares that against +the config-desired state (below) to compute `StatePendingRestart` — the diff +is computed on read, not persisted, so there is no new durable state to keep +consistent with the registries themselves. This follows +`migration-decisions.md`'s rule that cross-cutting aggregation composes +existing domain-owned contracts rather than duplicating their state. + +**Call site.** New package `internal/domain/extensions/inventory.go`. +Composed in `internal/app/archied` (wherever `server.go`'s other optional +fields — Workflows, Skills, Curators — are already wired) since it needs +references to every family's registry, which only application-layer +composition has. + +### Config-backed enablement + +**Decision.** Add `enabled bool` (default `true` for pre-existing configured +entries, so no upgrade silently disables anything already configured) to +each family's config element: `MCPServer.Enabled`, and equivalent fields on +whatever config types back skills/workflows/plugins if they don't already +have an on/off switch. Core capabilities (identity, workflow engine, State +Store connectivity — named in `organisation.md`'s cross-cutting packages) +have no `enabled` field at all; a config value can't be added to something +that doesn't expose the toggle, which is the "non-disableable" property +enforced structurally rather than by a runtime check that could be +bypassed. + +**Call site.** `internal/config/config.go` — add the field per family +struct, not one generic `map[string]bool` (typed fields keep +`docsgen`/`contracts.json` generation working, per `tools/docsgen`'s +"treat flags as executable truth" rule — a generic map has no type to +generate from). `config.example.toml` documents each new field with its +default. + +**Reuse check.** The config `Holder` overlay system +(`internal/infrastructure/configuration`) already handles safe saves; this +adds fields to existing structs, it does not add a second config-write path. + +### Pending-restart and reconciliation + +**Decision.** No new "pending restart" flag is persisted. `Inventory.List` +computes `StatePendingRestart` by comparing the config's `Enabled` value +against whether the family's registry currently reports that entry as +live — if they disagree, the entry is pending restart. This is simpler than +tracking a flag through a save-then-restart cycle and can never go stale, +because it's recomputed on every read. + +**Call site.** `internal/domain/extensions/inventory.go`'s comparison logic. + +### API and UI surface + +**Decision.** New `api_extensions.go` alongside the existing `api_skills.go` +/`api_workflows.go` pattern, exposing `Inventory.List` and a save endpoint +that writes through the existing `UpdateConfig` seam (`api_config.go`) — +this document does not add a second config-write endpoint. New +`ui/src/extensions/` (colocated `.js`/`.css` per CLAUDE.md's frontend rule) +as an index/dashboard that **links to**, not replaces, the existing +`ui/src/skills/` and `ui/src/workflows/` detail views — Extensions center is +where an operator sees everything and toggles enablement; the family-specific +pages remain where they inspect a family's own detail. + +**Call site.** `internal/webui/api_extensions.go` (new, follows +`api_skills.go`'s shape), `ui/src/extensions/` (new). + +## Call site inventory + +| concern | file | change | +|---|---|---| +| Plugin metadata type | `internal/plugin/plugin.go:24-27` | none — already handles this | +| Family controllers (curator/health/image/workflow registries) | `internal/domain/curator/registry.go`, `internal/domain/health/health.go`, etc. | none — pattern already proven, reused not rewritten | +| Unified inventory | `internal/domain/extensions/inventory.go` | new | +| Composition wiring | `internal/app/archied/server.go` (near existing optional fields) | new | +| Config enablement fields | `internal/config/config.go` | new fields per family | +| Config docs | `config.example.toml` | new field documentation | +| API surface | `internal/webui/api_extensions.go` | new | +| Existing skills/workflows APIs | `internal/webui/api_skills.go`, `api_workflows.go` | none — linked from, not replaced | +| Config save path | `internal/webui/api_config.go` (`UpdateConfig`) | reused, not duplicated | +| UI | `ui/src/extensions/` | new | +| Existing UI detail views | `ui/src/skills/`, `ui/src/workflows/` | none — linked from Extensions center | + +## Execution: multi-agent team breakdown + +| sub-feature | issue | implementer scope | suggested council lenses | why | +|---|---|---|---|---| +| Unified inventory type + composition | file as child of `#56` | `internal/domain/extensions/inventory.go`, wiring in `server.go` | `lens-boundary`, `lens-deletionist` | boundary: aggregator must not duplicate family-owned state; deletionist: must not become a new domain that shadows existing registries | +| Config enablement fields | file as child of `#56` | `config.go` per-family `Enabled` fields, `config.example.toml` | `lens-contract` | config field is a wire contract other tooling (`docsgen`) generates from | +| API + UI surface | file as child of `#56` | `api_extensions.go`, `ui/src/extensions/` | `lens-maintainer` | new user-facing state machine (available/enabled/active/degraded/skipped/pending-restart) must be legible to an operator with no prior context | + +## File and link the beads + +- `#56` itself has no filed children yet — file the three rows above as + child issues linking to this doc's matching `##` heading. +- Each issue's acceptance criteria should restate this doc's per-family + `Enabled` default (`true` for existing config, no field at all for core + capabilities) so "non-disableable core" isn't re-litigated per bead. +- Add the suggested lenses to each issue. diff --git a/docs/prds/mcp-tool-completion.md b/docs/prds/mcp-tool-completion.md new file mode 100644 index 000000000..a9fabef39 --- /dev/null +++ b/docs/prds/mcp-tool-completion.md @@ -0,0 +1,193 @@ +# MCP client and tool-guardrail completion + +Epic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` ("[EPIC] Tools: +central registry, MCP client, guardrails"). + +Most of this epic already shipped. The central registry +(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE, +`internal/tools/mcp/transport*.go`), reconnect-with-backoff +(`transport.go:43-71,530-580`), guardrail loop detection +(`internal/tools/guardrail.go`), idempotent/mutating classification +(`internal/tools/classification.go`), concurrent tool dispatch (closed +`#183`), and progressive disclosure wiring +(`internal/app/archied/main.go:72-99`, confirmed production-wired, not just +tested) are settled and correct. Do not touch them. This document covers only +the five sub-features still open under the epic: MCP server-initiated +sampling, the per-server parallel-tool-calls flag, sandboxed MCP tool +servers, a Firecracker sandbox backend, and sequential dispatch with +per-result previews. + +## Problem + +`bd search "MCP client"` shows five closed transport beads and one open: +server-initiated sampling (`#151`). `internal/tools/mcp/client.go:34-37` +holds a single `callMu *sync.Mutex` that serializes every `tools/call` +regardless of server — `ParallelToolCalls` does not exist on the `MCPServer` +config struct (`internal/config/config.go:168-186`), confirming `#177` is a +real gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent, +sandboxed) and `#179` (Firecracker substrate) have no corresponding code — +MCP servers today run as whatever the config's `Command`/`Args` launches, +unsandboxed. `#182` (sequential tool dispatch with per-result previews) is +open; concurrent dispatch (`#183`) is closed, so there are two dispatch paths +and this PRD decides how they coexist. + +## Design + +Sub-features are independent; there is no new shared type this document +introduces. Each section below stands alone. + +## MCP server-initiated sampling (`#151`) + +**Decision.** Implement as a callback on `mcp.Client`, not a second +transport. The MCP spec's `sampling/createMessage` request flows server→client +over the same connection each transport already maintains +(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames). +Add a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)` +field to the client's config struct next to the existing transport fields, +defaulting to nil (server sampling requests get a JSON-RPC "not supported" +error when unset — never a silent drop). + +**Call site.** `internal/tools/mcp/client.go` — add the handler field and a +dispatch branch in whatever function currently demuxes incoming server +messages by method name (the same switch that already routes +`notifications/*` today). Wire a concrete handler in +`internal/app/archied/main.go` that routes the sampling request through the +same chat-model call path `chatGenerateOptions` already uses, so a +server-initiated sample gets the daemon's configured model, not a second +provider client. + +**Reuse check.** The chat model invocation path already exists +(`chatGenerateOptions`, `main.go:72-99`); this reuses it rather than adding a +parallel model-calling path for MCP sampling. + +**Failure mapping.** + +| condition | contract error | +|---|---| +| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec | +| handler returns error | JSON-RPC internal error, message from handler | +| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one | + +**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake +transport that emits a `sampling/createMessage` frame. No real backend +needed; belongs in `task check`. + +## Per-server parallel-tool-calls flag (`#177`) + +**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer` +in `internal/config/config.go:168-186`, next to `Transport`/`Command`. The +mutex in `client.go:34-37` becomes per-server: when `ParallelToolCalls` is +false (default, and the only behavior today), keep the single `callMu` +serializing that server's calls exactly as now; when true, drop the mutex for +that server's `Client` instance entirely and let the caller's own +concurrency (already proven by the closed concurrent-dispatch bead, `#183`) +handle it. This is additive — no server's behavior changes unless an operator +opts in. + +**Call site.** `internal/config/config.go` (struct field), +`internal/tools/mcp/client.go:34-37` (make the mutex conditional on the +field), and wherever `MCPServer` configs are turned into `Client` instances +at daemon startup (the constructor that reads `internal/config`'s MCP block). +`config.example.toml`'s commented MCP block gets the new field documented +with its default. + +**Testing.** Unit test asserting two concurrent `Call`s to the same +`Client` block on each other when the flag is false and don't when true — +fakeable with a slow fake transport. `task check`. + +## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substrate (`#179`) + +**Decision.** These two beads are one design decision, not two: `#179` is an +alternate execution backend for `#178`, not separate scope. Sandbox MCP +servers that a chat-turn config marks as untrusted (a new +`Sandboxed bool` field on `MCPServer`, default `false` — existing +configured servers are unaffected) behind the same `ContainerPool` the +daemon already uses to run agent work +(`internal/container/pool.go`, per CLAUDE.md's `WriteTaskJSON` trap and the +`Acquire`/`Release` lifecycle `daemon.go`'s `acquireTaskContainer` already +proves). Do not build a second sandbox mechanism: an MCP stdio server is a +subprocess exactly like an agent task container's entrypoint, so launching it +via `ContainerPool.Acquire` with stdio piped to the `mcp.Client` transport is +the smallest change, not new plumbing. + +Firecracker is **not** built now. `ContainerPool`'s existing Docker-backed +isolation is the shipped backend; Firecracker becomes a second +implementation of the same acquire/release contract only if a concrete +escape or resource-isolation gap is measured against Docker-backed sandboxing +in production. Recording this as the deletion/promotion gate keeps `#179` +honestly `OPEN` instead of speculatively building an unused backend, per +CLAUDE.md's Architectural Simplicity rule. + +**Call site.** `internal/config/config.go` (`MCPServer.Sandboxed`), the MCP +client constructor (route sandboxed servers' process launch through +`container.Pool.Acquire` instead of `os/exec` directly), and +`internal/container/pool.go` (confirm its `Acquire` contract accepts a +stdio-piped, non-worktree workload — if it currently assumes a git worktree +per CLAUDE.md's `WriteTaskJSON` note, add the narrower entrypoint variant +there rather than duplicating the pool). + +**Error/failure mapping.** + +| condition | contract error | +|---|---| +| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried | +| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go:530-580`), not a new retry loop | + +**Testing.** `Sandboxed=false` path is the existing, already-tested +unsandboxed flow — no change. `Sandboxed=true` needs a real +`ContainerPool` (Docker) — manual smoke command, not `task check`; document +the exact command in the runbook this PRD's issue links to once implemented. + +## Sequential tool dispatch with per-result previews (`#182`) + +**Decision.** This coexists with concurrent dispatch (`#183`, closed) as a +second, explicit mode selected by the caller — not a replacement. Concurrent +dispatch is for independent tool calls in one turn; sequential-with-preview +is for a turn where each result should be surfaced to the operator (or the +next tool call) before the next call fires — e.g. a mutating tool chain where +showing intermediate state matters. Add a `DispatchMode` enum +(`Concurrent`/`Sequential`) to whatever type currently selects the closed +`#183` concurrent path, defaulting to `Concurrent` (today's only behavior). + +**Call site.** The tool-dispatch entry point that `#183`'s closed +implementation lives in (grep the concurrent-dispatch symbol added for +`#183` — same file gets the sequential branch, not a parallel file). Preview +surfacing reuses whatever channel-adapter interface already streams +intermediate turn output (the same seam `internal/channels/telegram/` and +other adapters use for streaming deltas) — do not invent a second preview +transport. + +**Testing.** Fakeable with a fake tool that returns staged results; assert +preview callbacks fire in order before the next call starts. `task check`. + +## Call site inventory + +| concern | file | change | +|---|---|---| +| MCP client transports (stdio/HTTP/SSE) | `internal/tools/mcp/transport*.go` | none — already handles this | +| MCP client call serialization | `internal/tools/mcp/client.go:34-37` | change (`#177`) | +| MCP server config | `internal/config/config.go:168-186` | new fields: `ParallelToolCalls`, `Sandboxed` | +| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) | +| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` | +| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) | +| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this | +| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) | +| Guardrails / classification / registry / disclosure | `internal/tools/guardrail.go`, `classification.go`, `registry.go`, `disclosure.go` | none — already handles this | +| `config.example.toml` MCP block | `config.example.toml` | doc update for new fields | + +## Execution: multi-agent team breakdown + +| sub-feature | issue | implementer scope | suggested council lenses | why | +|---|---|---|---|---| +| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract | +| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behavior change must not leak into other servers' serialization | +| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding | +| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both | + +## File and link the beads + +- `#151`, `#177`, `#178`, `#179`, `#182` each get their description updated to + point at this doc's matching `##` heading instead of restating the design. +- Close `#179` as a design decision (link here) rather than leaving it open + as separate scope — it is not built now, and the doc records why. +- Add the suggested lenses to each issue directly. diff --git a/docs/prds/self-update-transaction.md b/docs/prds/self-update-transaction.md new file mode 100644 index 000000000..3195b878e --- /dev/null +++ b/docs/prds/self-update-transaction.md @@ -0,0 +1,219 @@ +# Self-update: artifact install, topology migration, journaled transaction + +Epic: `archie-core-hj1t` / GitHub `#804` ("[EPIC] Self-update: artifact +install, topology migration, journaled transaction"). + +The update *contract* (`internal/releaseupdate`: `Catalog.Check`, +`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by +this document — it stays a thin Go interface shelling out to +`CommandCatalog`/`CommandInstaller`. This document decides what the reference +adapter scripts (`scripts/archie-update-{check,install,watchdog}`) and +`install.sh` do behind that contract, and settles the one thing the epic's +own description got wrong: the dist-zip **is** already attached to GitHub +Releases (`.github/workflows/deploy.yml:283-316`, `gh release upload`), not +Actions-artifact-only. Artifact install is therefore a smaller change than +the epic assumed — pointing the installer at an existing asset, not standing +up new CI publishing. Topology migration and the journaled transaction are +genuinely greenfield: no topology-detection or transaction-journal code +exists anywhere in the tree today. + +Out of scope: rewriting the `internal/releaseupdate` Go interfaces +themselves, and any UI for triggering updates (channel dispatch, e.g. +Telegram `/update`, is unaffected — this only changes what happens once an +install is triggered). + +## Problem + +`scripts/archie-update-install:139-160` clones and compiles from source on +every update — the only path that exists. `deploy.yml` already publishes a +per-platform archive plus (implicitly) checksums as a release asset, so the +script not using it is a missed-reuse gap, not a missing-CI gap. +`install.sh:414-445` writes only `archied.service` while every shipped +deployment profile (`deployments/*.toml`) declares `[services.state]` and +`[services.gateway]` sections needing their own units — a fresh install +already reproduces the broken single-unit shape `deployment_contract_test.go` +(lines 70-105) doesn't even catch, because that test only checks profile +syntax, not installed topology. No code anywhere enumerates which systemd +units exist on a host or compares that against what a release requires — the +daemon fails at `bootstrap.go`'s `[services.state].target` check with no +prior diagnosis. The self-refresh trap is confirmed at +`scripts/archie-update-install:195-199`: new adapter copies land on disk but +bash keeps executing the in-memory copy, so a pre-flight check added to the +script only protects the *next* update. + +## Design + +### Artifact install (`#804` item 1) + +**Decision.** `CommandInstaller`'s default script downloads the per-platform +archive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check` +resolved (the same release `deploy.yml` already publishes to), verifies the +checksum, and stages it — it does not clone/compile. Source build +(`scripts/archie-update-install`'s current clone+compile body) is kept as an +opt-in path selected by an explicit `--from-source` flag or +`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on +every-host update is strictly slower and has a larger failure surface than +downloading a signed asset that CI already produced. + +**Call site.** `scripts/archie-update-install` — replace the body currently +at lines 139-160 with a download-and-verify step; move the existing +clone+compile body behind the opt-in flag rather than deleting it. +`internal/releaseupdate/command.go:44-48` (`CommandInstaller`) is unchanged — +it already just shells out. + +**Reuse check.** `deploy.yml:265-316` already builds and publishes the +archive and uploads it as both an Actions artifact and a release asset; no +new CI work is needed, only pointing the installer at what exists. + +**Testing.** Checksum-verification logic is a shell function, testable with +a fixture archive + `SHA256SUMS` pair — add to whatever test harness already +covers `scripts/`. Full download-from-real-release is a manual smoke command +(document the exact `archie-update-check`/`--dry-run` invocation once built), +not `task check`. + +### Topology migration (`#804` item 2) + +**Decision.** Add a topology *observer* to the daemon, not the shell +adapter — CLAUDE.md's own "known trap" note says the shell copy is defence +in depth only, and the daemon is what "knows the deployment and holds the +approved snapshot." The observer inspects which systemd user units exist +(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and +which config sections are present (`[services.state]`, `[services.gateway]`, +UI service config), producing an `ObservedTopology` value with one field per +unit: present/absent, and the config sections backing it. Each release's +`release.json` (already produced by `deploy.yml` per the artifact-install +work above) gains a `required_topology` field naming the units and config +sections that release's binaries need. `Catalog.Check` compares observed +against required; when the release needs a unit the host doesn't have, the +result is not an error — it's a `MigrationPlan` value naming exactly which +units and config blocks must be created and in what order (state store → +gateway → UI → daemon, per CLAUDE.md's process boundaries), which the +installer must apply before installing binaries, or refuse with that plan +printed to the operator. + +**Call site.** New topology-observation code lives in +`internal/app/archied/` next to `bootstrap.go` (which already owns the +`[services.state]`/`[services.gateway]` checks this reuses), not in +`internal/releaseupdate` — the update package consumes the daemon's +observation, it doesn't reimplement config parsing. `install.sh:414-445` +reads the same `required_topology` declaration (from whichever profile the +operator selected) so first-install and self-update stop diverging — this is +the fix for the "three docs describe four units, install.sh writes one" +gap: one topology source of truth, consumed by both entry points. +`deployment_contract_test.go` gains an assertion that each shipped profile's +declared topology matches the units `install.sh` would create for it. + +**Failure mapping.** + +| condition | contract error | +|---|---| +| observed topology cannot be determined (systemctl unavailable, non-systemd host) | refuse with "topology unknown" plan naming the manual steps, never guess | +| required units missing, migration plan derivable | apply plan before binary install, in dependency order | +| required units missing, no derivable plan (e.g. conflicting existing unit) | refuse, print the plan, do not proceed | + +**Testing.** `ObservedTopology`/`MigrationPlan` comparison logic is pure — +table-driven unit tests belong in `task check`. Actual `systemctl` inspection +needs a real systemd host; manual smoke test only. + +### Journaled transaction (`#804` item 3) + +**Decision.** Replace `archie-update-install`'s copy-and-trap body with: (1) +pre-flight (existing check at line 170, kept), (2) write an intent journal +to a path outside every directory the install touches — e.g. +`${XDG_STATE_HOME:-~/.local/state}/archie/update.journal` — recording the +candidate version, the topology plan (if any), and each binary's +current-and-candidate path before touching anything; (3) stage each new +binary under a `.new` suffix in the same directory as the live binary, then +atomically rename over the live path (`rename(2)` is atomic on the same +filesystem — this replaces whatever non-atomic copy the current script uses) +rather than overwriting in place; (4) run each replaced binary's existing +health/ready check (the same checks `internal/domain/health` already exposes +per the health registry pattern, not a new one) against the *candidate*, not +a hardcoded default port/binary; (5) hold the process open for a bounded +observation window (e.g. 120s) watching for crash-loop before declaring +success; (6) on any failure at any stage, roll back using the journal: +restore prior binaries via the same atomic rename, restore prior unit files +and config if the topology-migration step touched them, and delete the +journal only on confirmed rollback completion; (7) on daemon boot, check for +a journal file and resume rollback if one exists uncommitted (crash-during +-update recovery). A single-writer lock (`flock` on a lock file outside the +replaced paths, e.g. next to the journal) prevents two concurrent updates. + +**Call site.** `scripts/archie-update-install` (journal write, stage-then +-rename, lock acquisition), `internal/releaseupdate` package (health-check +invocation reusing whatever the health registry already exposes — cite the +concrete symbol once located, do not add a second health-check mechanism), +and `internal/app/archied` startup (resume-on-boot journal check, next to +existing bootstrap sequencing). + +**Failure mapping.** + +| condition | contract error | +|---|---| +| lock held by another update | refuse immediately, name the holder's PID/journal | +| health check fails post-switch | automatic rollback within the observation window, journal records the failure reason | +| crash mid-transaction, journal present at boot | daemon completes rollback before normal startup, logs it | + +**Testing.** Stage-then-rename and rollback logic against a fixture +directory tree is fully fakeable — `task check`. Real systemd unit +start/stop as part of rollback needs a real host; manual smoke command. + +### Channel, pinning, automation (`#804` item 4) + +**Decision.** Add `channel = "stable" | "next" | ""` +to whatever config section already governs update behavior (next to +`ARCHIE_UPDATE_CHANNEL`'s existing chat-channel field in +`internal/releaseupdate/command.go:62` — name this new field distinctly, +e.g. `ReleaseChannel`, to avoid colliding with the existing chat-notification +channel of the same word). `Catalog.Check` filters candidate releases by +this field before returning the newest match. Runtime image pinning: every +shipped profile already pins by digest +(`deployments/*.toml` confirmed), so the remaining gap is +`scripts/archie-update-install`'s fallback default — it must read the +digest from the active profile's config rather than falling back to +`:latest` when none is configured; refuse the update (don't silently pull +`:latest`) if no digest is resolvable and the profile requires a pinned +image. Opt-in auto-update refuses to start when the daemon reports work in +flight (reuse whatever "tasks currently running" signal the daemon already +exposes for graceful shutdown — do not add a second in-flight tracker). + +**Call site.** `internal/config/config.go` (new `ReleaseChannel` field), +`internal/releaseupdate` (`Catalog.Check` filtering), +`scripts/archie-update-install` (digest resolution, remove `:latest` +fallback), daemon shutdown/drain signal (reuse for the auto-update +in-flight check). + +**Testing.** Channel filtering is pure — `task check`. Digest-refusal path +is a shell-script unit test against a fixture profile. + +## Call site inventory + +| concern | file | change | +|---|---|---| +| Update contract (Catalog/Installer interfaces) | `internal/releaseupdate/service.go` | none — already handles this | +| Command adapters | `internal/releaseupdate/command.go:22,44-48,62` | new `ReleaseChannel` field distinct from existing chat-channel field | +| Install script body | `scripts/archie-update-install:139-160,170,195-199` | replace clone+compile default with download+verify; add journal, lock, stage-then-rename, digest check | +| CI release publishing | `.github/workflows/deploy.yml:265-316` | none — already handles this | +| Deployment profiles | `deployments/*.toml` | none — already digest-pinned | +| First-install unit creation | `install.sh:414-445` | change — consume shared topology declaration | +| Topology assertions | `deployment_contract_test.go:70-105` | new assertion: profile topology matches install.sh output | +| Topology observation | `internal/app/archied/bootstrap.go` (new sibling code) | new | +| Resume-on-boot rollback | `internal/app/archied` startup | new | +| Health check reuse for candidate verification | `internal/domain/health` | reuse — confirm exact symbol before implementing | + +## Execution: multi-agent team breakdown + +| sub-feature | issue | implementer scope | suggested council lenses | why | +|---|---|---|---|---| +| Artifact install | item 1 (file if unfiled) | `archie-update-install` download+verify, opt-in source-build flag | `lens-deletionist` | must not leave the clone+compile path as silent default cruft | +| Topology migration | item 2 (file if unfiled) | daemon-side observer, `release.json` schema, `install.sh` consumption, contract test | `lens-boundary`, `lens-operator` | boundary: observation belongs in daemon not shell; operator: refusal-with-plan is the whole safety property | +| Journaled transaction | item 3 (file if unfiled) | journal format, stage-then-rename, lock, resume-on-boot | `lens-operator`, `lens-maintainer` | operator: crash-mid-update is the core failure mode; maintainer: someone must be able to read a journal file during an incident | +| Channel/pinning/automation | item 4 (file if unfiled) | config field, catalog filtering, digest refusal, in-flight guard | `lens-contract` | digest-refusal changes what a config value is allowed to resolve to | + +## File and link the beads + +- The epic's four numbered work items are not yet individual child beads — + file one bead per item above, each linking to its matching `##` heading + here instead of restating the design, with acceptance criteria drawn from + this doc's failure-mapping tables. +- Add the suggested lenses to each new issue.