docs(prds): write PRDs for tool/MCP completion, self-update transaction, extensions center

Covers the three ready epics with no settled design: archie-core-1786637493439-140-2cee2e9b
(tools/MCP/guardrails, mostly already shipped — scoped down to the five real gaps),
archie-core-hj1t (self-update artifact install/topology migration/journaled transaction),
and archie-core-1786637490708-35-38424ead (Extensions center). Child issues filed and
linked back to each doc's matching section.
This commit is contained in:
sam committed 2026-09-19 18:59:56 +10:00
1 parent 4b51722440
commit d203229f9c
3 files changed
+582

No files matched your search

+170
View File
@@ -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.
+193
View File
@@ -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.
+219
View File
@@ -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" | "<exact-version-pin>"`
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.