Address the second-pass review of the State Store ratification doc (beads archie-core-8cda.4.1):
- State migration-decisions.md section 4 remains authoritative and open; this PRD
does not replace it. The Task/Status/Source + interface relocation is flagged as
a minimal, pulled-forward Phase 2 prerequisite only.
- Fix stale WorkflowStore reference in service-decomposition.md Q4: the workflow
contract is the domain-owned workflow.Store, which supersedes internal/store's
WorkflowStore.
- Label internal/store as a TRANSITIONAL compatibility location (target
internal/infrastructure/store), matching dependencies-and-contracts.md.
- Call out the current-state outliers explicitly: workflow files/tests still import
internal/store, store.WorkflowStore is still in TaskContext, and the NATS storerpc
path is still wired -- the acceptance criterion is NOT yet met.
- Operationalize the agent gRPC handoff: who binds the in-process State Store
listener (daemon, mirroring serveGateway), Docker-bridge host-gateway address
selection (reuses the embedded-NATS container/network.go resolution), per-task
injection via containerEnv beside NATS_URL, per-incumbence bearer token lifecycle
+ gRPC-interceptor validation -> codes.Unauthenticated, and fail-closed on
non-loopback targets without TLS/token.
- Update beads archie-core-8cda.4.2/.4.5 descriptions to match the ratified scope
(type/interface relocation, RecordDispatch *sql.Tx drop, in-process serving,
agent gRPC handoff).
Address the review of the Phase 2 ratification doc (beads archie-core-8cda.4.1):
1. Domain-dependency contradiction: ownership splits by consumer layer. The
workflow domain owns a consumer-owned workflow.Store interface plus the
Task/Status/Source types (dependency rules #2/#7), so internal/domain/workflow
imports no internal/store — satisfying the Phase 2 acceptance criterion. The
daemon/webui store surfaces stay producer-owned in internal/store. The type +
interface relocation is a Phase 2 prerequisite pulled from migration-decisions
section 4 (store.Task -> WorkflowExecution).
2. Agent gRPC endpoint propagation: explicit boot handoff via STATE_STORE_URL /
STATE_STORE_TOKEN (mirrors the NATS handoff), added to agentworker.Settings and
the Transport.Store facade; per-call timeout + long-lived grpc client.
3. Transport security + error sanitisation: loopback-only + insecure default, agent
authenticates over the container bridge with a per-task bearer token; TLS/mTLS
is an operator choice for non-loopback/k8s. Sanitised public error details in
gRPC; full detail logged server-side only.
Also records RecordDispatch dropping *sql.Tx as a required interface migration
before .4.2. Cross-references updated in the service-decomposition PRD.
Define the authoritative Phase 2 State Store contract boundary and
transport design (beads archie-core-8cda.4.1): one StateStore gRPC
service (40 RPCs) behind the narrow typed store contracts, producer-owned
in internal/store, with a staterpc.Client remote adapter that satisfies
the same interfaces via explicit compile-time assertions. Records method
ownership, DTO/wire representation, error semantics (structured gRPC codes
rehydrated to store sentinels so errors.Is survives), limits, mode/config
shape (presence-based [services.state].target, default local), local-
adapter compatibility, and cutover/deletion rules. Fixes the RecordDispatch
wire blocker (*sql.Tx dropped; production passes nil) and keeps Close()
off the wire. References the new doc from the service-decomposition PRD.
Failed task actions in the dashboard rendered the same generic message
regardless of cause. ApiError already carried the HTTP status, but nothing
read it: a refused mutation (400/403/409 - bad input, CSRF, conflicting
state) looked identical to a broken one (5xx, network drop, timeout), and
an expired session (401, whether archied's own token cookie or an upstream
forward-auth proxy) showed a generic failure instead of prompting
re-authentication.
Add classifyActionError() in api.jsx to map a caught error to a refused /
broken / session-expired kind, and use it in tasks.jsx to render each with
distinct framing and coloring (reusing the existing warn/danger tokens
pill.css already establishes) - refused actions get "you can't do that",
broken ones get "try again, or check the daemon", and an expired session
gets a reload prompt.
Refs archie-core-h3lg.
Stands up archie-gateway as its own binary serving ChatContract over gRPC
and makes it the daemon's only transport for webui chat (Q3 part 5's
atomic flip -- the in-process serving path is deleted, not deprecated).
- contract seams + protobuf toolchain (Phase 0)
- single taskactions.Service across webui, daemon NATS responder and the
standalone gateway's client
- services.gateway.target is the only config surface left; mode is gone
now that remote is the only transport
- task dev launches archie-gateway alongside archied + Vite
Verified end-to-end against live infra: real GitHub token (zero repos
configured, so no repo was polled or touched) and the real
@heyarchie_home_bot Telegram bot, both processes booted together against
shared NATS/store, chat and /status round-tripped successfully.
# Conflicts:
# go.sum
Mode had exactly one legal value after the previous commit deleted the
in-process path, which made it dead config surface that could only
confuse an operator into thinking there was still a real choice.
ServiceConnection is now just a target address; composeChatContract only
checks it's non-blank, defaulting to 127.0.0.1:8585.
archie-gateway is now the sole owner of ChatContract; the daemon always
dials it over gRPC for webui chat, no in-process fallback left. Telegram
and email keep their own in-process routers unchanged (their streaming
responder is a callback that can't cross the wire-safe contract).
- composeChatContract only accepts mode="remote"; config defaults
Services.Gateway to remote + 127.0.0.1:8585 when unset
- deleted taskActionsActor (dead code once the local branch is gone)
- task dev now launches archie-gateway alongside archied + Vite
Verified end-to-end: archie-gateway + archied booted against a shared
NATS/store, webui's /api/chat/sessions round-tripped through the gRPC hop.
Phase 1 (extract the Gateway Service), first stage. Repairs the
half-migrated working tree so the default (inproc) daemon path works
again while keeping the WIP's direction:
- chatTaskActorAdapter is contract-only (no HTTP detour); nil contract
returns ErrChatCapabilityUnavailable instead of panicking.
- openStores opens the conversation store for both processes again;
the standalone gateway no longer owns it exclusively. Phase 1 keeps
the daemon's Telegram/email routers and session-memory curator
reading the same SQLite file; remote conversations arrive when a
process that cannot open the file needs them.
- setupLLMAndChat composes the local gateway (setupGatewayChat) in
default mode and a remote gRPC client in mode=remote; the returned
contract is never nil, and Run handles the error.
- taskactions.Service is now the single task-mutation implementation
shared by the dashboard (webui TaskActionService), the daemon's local
gateway actor, and the NATS responder. The daemon registers
taskactions.Register so the standalone Gateway's client can forward
actions; transport follows the repo's natsrpc pattern.
- uncommitted sessions.proto / SessionStoreService gRPC contract
deferred: it has no wired consumers (scope creep for this stage).
- task_action_adapter_test.go rewritten against the contract chain.
task check passes; archied and archie-gateway both build.
* feat(curator): add embedding client and sampler wave-1 prerequisites
Bead archie-core-1786637500752-415-434e5bb9 (GitHub #436) was closed with
no linked PR/commits, and the surprisal-sampling bead
archie-core-1786637500776-416-600a66e5 (GitHub #437) found none of its
stated prerequisites -- an embedding client, a Sampler interface, or the
four wave-1 cheap sampling strategies -- actually exist. This builds them:
- internal/domain/embedding + internal/infrastructure/embedding: a narrow
typed embedding client, config-driven via a providers table + a role in
[models], mirroring the existing chat model role convention. Degrades to
capability-unavailable (never fails startup or a call) for a missing
role, unknown provider, unsupported class, or unresolved credential.
Wired as an optional capability in bootstrap.go's setupEmbeddings.
- internal/domain/sampling: the Sampler interface plus recency, random,
all, and staleness-proxy strategies, per docs/prds/curator-sampler-wave1.md.
Deterministic given fixed inputs, matching GitHub #437's stated
acceptance criterion for the embedding-backed strategy it will add
behind this same interface (not part of this change).
Table-driven tests throughout; httptest for the embedding client, no live
service. No curator wiring yet -- nothing consumes either capability in
this change.
* no-mistakes(document): docs(architecture): mark curator sampling prereqs as landed
The chat agent had no way to know where it lives without probing the
filesystem (pwd, find, git remote), wasting turns on every orientation.
Per docs/architecture/identity.md the <env> block is Layer 1 invariants,
so the daemon's own facts belong there, driven from live configuration.
Render into the prompt's <env> block:
- workspace path (chat.workspace)
- repositories under management with forge host and default branch
- operator identity (chat.operator, which was dead plumbing)
Unconfigured values render explicitly as unknown / none configured
rather than a plausible-looking default, and a repo with no forge
reports forge unknown, so the model never claims a fact the daemon
cannot confirm. Repos are resolved per active chat identity, mirroring
chatTaskProfiles.
gateway: add RepoEnv, SystemPromptConfig Workspace/Repos/Operator,
TurnRunnerConfig Workspace/Repos.
app: chatRepoEnv resolver wired through newChatTurnRunner.
tests: prompt rendering (incl. explicit-unknown + hostile-SOUL guard)
and chatRepoEnv identity resolution. go.sum gains module-graph
/go.mod checksum lines.
ghcr.io/samcharles93/archie-agent:latest is re-published on every main
push that touches the runtime's package closure, so a bare :latest
reference can change under a running deployment with no warning and no
way to reproduce a prior build.
archie-agent has no published semver tag yet -- CI (deploy.yml) only
ever pushes :latest to GHCR, confirmed via the GHCR package API. Pin
docker-compose.yml and the GitHub deployment profiles to the verified
digest of :latest as of 2026-09-05
(sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090),
and document the pinning strategy -- including the semver-tag-once-
published preference and digest pinning for production -- in
deployments/systemd-user-service.md. Update the generic
docker-nats-stack.toml example to demonstrate the same convention.
Ref archie-core-kllw (GitHub #670)
Dolt is the source of truth and already syncs via its own git+ remote
(bd dolt push/pull). Committing the JSONL export separately produced a
steady stream of no-op "chore(beads)" commits that skewed commit counts
without adding information. Untrack the export files, disable
export.auto/git-add, and drop the beads-commit step from CLAUDE.md's
Session Completion Protocol.
Beads epic archie-core-8cda (with 8 phased child issues per the
resolved extraction order) has been filed for the service-decomposition
work; the PRD's completion-criteria "file a beads epic" line now points
to it. Filing the epic does not authorize implementation -- the PRD's
completion criteria still require the captain's separate explicit
go-ahead.
Compose the base registry with per-turn extras into a turn-local registry and
let ContextPressureGate decide full-vs-bridge disclosure per chat turn. The
three bridge tools (tool_search, tool_describe, tool_call) are now wired into
the chat toolset and only disclosed under context pressure, keeping the LLM's
schema footprint small while preserving full arsenal access on demand.
Per-turn extras are identity-bound per channel and cannot live in the
process-wide registry (agentexec.BuildToolSetFrom invariant), so the bridge is
composed turn-locally rather than registered globally. Thread the model's
context window through TurnModel.Prepare (TurnPrepareContext) so the gate
activates with a real window.
Refs #167
Implement drain control via an external marker file. The daemon polls
$XDG_CONFIG_HOME/archie/.drain_request.json (the repo's config-home
convention) for a drain request, validates it against the current
instantiation epoch (kernel boot id + PID 1 start time) and, only when
the marker is live, cancels the boot context to trigger the same
graceful shutdown an operator SIGTERM does.
A marker written against a prior instantiation (reboot or PID 1/container
restart) is stale and ignored, so a leftover request never drains a
daemon that came up after it was written. An unreadable marker or epoch
fails closed to no drain. The daemon never invents a new shutdown path.
domain/drain owns the pure decision (Epoch, Marker, Decide);
infrastructure/drain reads the marker file and /proc boot facts;
app/archied wires a poller that cancels the root context on a valid
request.
Path note: the epic named ~/.archie/.drain_request.json, but archied
resolves every per-user path under ${XDG_CONFIG_HOME:-~/.config}/archie
(see AGENTS.md 'Config path'), so the marker lives there too rather than
at a path this daemon never uses.
Refs bead archie-core-1786637496817-266-06b64a72 (drain control: marker
file and instantiation epoch), part of the operations epic
archie-core-1786637496703-262-1e49aef1.
Tests: table-driven Decide (epoch mismatch -> stale, matching -> valid,
nil -> none, unreadable -> stale), marker round-trip from operator JSON,
and monitor (valid -> shutdown, stale/none/error -> no shutdown).
Baseline `task check` failed on a clean main checkout, blocking unrelated
in-flight work. Fixes only those pre-existing failures:
- bootstrap.go: extract wireWebStoreSurfaces from setupObservability
(cyclop 16 > 15) and startEmbeddedNATS from connectNATS (nestif).
- telegram_setup_test.go: os.Setenv -> t.Setenv (usetesting).
- install_script_test.go: exec.Command -> exec.CommandContext with
t.Context() (noctx).
- Taskfile: add a ui:deps install step shared by `ui` and `test:ui`.
ui/node_modules is gitignored and nothing in the gate installed it, so
`task test:ui` died on a missing jsdom rather than a real test failure.
- shutdown_watchdog_test.go: `go fix` output adopted verbatim.
Refs bead archie-core-14cs.
* feat(webui): add /health and /health/detailed readiness endpoints (archie-core-1786637496789-265-b052b772)
Implements the Operations: readiness probes bead from the hermes gap analysis
(docs/prds/hermes-gap-analysis.md sections 9-10).
- GET /health: liveness, no auth, always 200 ok.
- GET /health/detailed: authenticated (dashboard token), JSON report with
overall ok/degraded status plus per-subsystem probe results.
New readiness probes, each reporting real current state:
- state_db: read-only StatusCounts against the store.
- config: configuration.Validate against the running config.
- disk: statfs, degraded above 90% used.
- model: active model configured + provider endpoint reachable.
- gateway: channel running/failed state + connected session count.
Layering: probe contract in internal/domain/health, implementations in
internal/infrastructure/readiness, wiring in internal/app/archied,
HTTP surface in internal/webui.
* no-mistakes(document): docs(archied): fix stale doc pointer in readiness probe comment
Once graceful shutdown begins (SIGINT/SIGTERM cancels the daemon's
signal context), start an out-of-loop watchdog timer for the drain
window plus a 60s grace period. If the shutdown chain has not completed
by the time that leash expires, force-exit the process (os.Exit) as a
backstop against a hung shutdown.
The watchdog runs in its own goroutine outside the daemon's event loop
and graceful-shutdown machinery, so it fires even when that machinery is
itself the thing that is stuck. It is disarmed via the FIRST registered
cleanup so it runs LAST in the LIFO shutdown chain: it stands down only
after every subsystem has shut down cleanly, and a hung subsystem never
reaches the disarm, letting the watchdog force-exit.
A shutdown that completes within the leash does not trigger the
watchdog; a shutdown that hangs past the leash results in a forced
process exit. The leash uses a test-only short timeout in tests.
Reference bead archie-core-1786637496842-267-8b2984f9.
Decision for channel/forge/module action keying in eda-playbook-engine.md:
one durable dedup record per (action, event) pair via a playbook_dispatches
ledger in internal/store, reusing binding_dispatches' INSERT OR IGNORE +
sentinel conventions, with record-before-invoke ordering (at-most-once, the
reverse of the binding loop's ordering, justified by the external-side-effect
harm profile). Key = (playbook_id, playbook_version, event_id, action_id):
event_id is the TaskEnvelope.IdempotencyKey() value already carried on
DispatchInput.TaskID; the key is a fixed structural composition, deliberately
not a CEL expression (event stays dyn; determinism under redelivery is the
binding constraint). Redelivery of a recorded action skips it and continues
the run at debug level, never surfaced as an error. Rows live as long as the
playbook exists, no time-based expiry.
Extends event-sources-and-reactions.md's contract without contradicting it:
PublishUnique's dedup is publish-path only (Nats-Msg-Id + 2-minute
DedupWindow), so consumer redelivery of side-effecting reactions was never
covered; the ledger adds exactly that consumer-side piece, reusing the
TaskEnvelope identity and the typed-family shape. The gap-2 prerequisites
(Playbook ID/Version, DispatchInput.TaskID) already landed in 1e736ef.
Documentation only: no code changes. Keying implementation is separate
follow-up work.
Refs: archie-core-t2db.17
Resolves archie-core-t2db.18. States stop-on-first-failure as the
committed default when a playbook action fails mid-run, grounded in
workflow.Run's three-way stage-failure distinction
(internal/domain/workflow/workflow.go:294, 317-336) and the t2db.9-12
load-collision drop-and-report rule (eda-playbook-engine.md:155-159),
with explicit reasoning why the default does not violate
event-sources-and-reactions.md's producer-only rule. Gap 2 (execution-time
idempotency) remains open. Documentation only; no code changes.
Land Q2 (contract definition mechanism: buf v2 + grpc-go, committed
proto/ tree, buf breaking gate) and Q3 (in-process-by-default
migration mechanism per organisation.md's Process boundaries rule) as
committed file edits, matching the style of already-resolved #1/#4/#5.
Transcribes decisions from a prior scout pass whose edits were
discarded when its worktree was torn down; codebase facts (go.mod,
organisation.md, servicediscovery.go, storerpc.go,
sessionstore_conformance_test.go, api_chat.go) re-verified in this
worktree before writing.
Adds internal/servicediscovery (broker-neutral ServiceRegistry contract,
zero internal imports) and internal/infrastructure/servicediscovery/nats
(NATS JetStream KV implementation: installed-marker bucket + heartbeat
bucket to express NotInstalled distinctly from Down/Unhealthy, per
docs/prds/service-decomposition.md). Additive and unwired -- no daemon
bootstrap path touched. Verified independently: go build ./... clean,
go vet clean, gofmt clean, full package tests pass with -race.
Add a broker-neutral service registry contract (Endpoint, EventKind,
Event, ServiceRegistry, ErrNotInstalled) and a NATS JetStream KV
implementation, plus the registration side a service uses to announce itself.
The contract's governing semantic -- NotInstalled is not Down -- is modeled
by two buckets: a durable installed marker (never expires) distinct from
expiring heartbeat keys. Instances heartbeat their key on an interval; a
stopped process leaves via TTL expiry. Register writes the marker once then
heartbeats; Resolve returns ErrNotInstalled only when the marker is absent,
and an empty roster for installed-but-down. Watch dedupes heartbeat refreshes
so it emits membership changes, not liveness pings.
Unwired: no daemon/bootstrap path consumes it yet. Deliberately uses a dot
key separator instead of the research sketch's slash so per-service watch
wildcards match.
Playbook now carries ID (path-relative to the configured root) and Version
(sha256 content hash recomputed on load), both populated in loadOne, mirroring
Binding.Version's provenance pin without a DB row. DispatchInput gains TaskID
carrying TaskEnvelope.IdempotencyKey(), the identity available at the
discovery point (pollNATS / webhook receiver compute kind+labels from a
TaskEnvelope before any store.Task row exists), NOT a store.Task.ID int64.
These are the two implementation prerequisites named by the t2db.17
idempotency resolution; the playbook_dispatches ledger is built on top.
Note: task check fails on 5 lint findings PRE-EXISTING at HEAD in unrelated
files (bootstrap.go cyclop/nestif, install_script_test.go noctx,
telegram_setup_test.go usetesting), reproduced in a clean worktree and not
caused by this change; the eda/playbook package is gofumpt/vet/lint clean.
Records the AWX pluggable-architecture and Ansible task-model inspiration
thread verbatim, the verified current-vs-ideal coupling analysis (webui's
in-process HTTP task-action detour, direct gateway internals access,
shared config.Holder), the external service-discovery research
(K8s-native primary + NATS fallback behind one ServiceRegistry seam), and
a Proposed-status PRD recording the target service shape and open
questions before any implementation work is filed.
Reconciled the helix/carina beads divergence via the Dolt remote. Carina held
28 beads absent from helix, but 23 were the same GitHub issues re-pulled under
freshly-minted IDs -- importing by ID would have duplicated them. Imported the
5 genuinely unique beads (462t, fwvf, n5fz, tzzn, w1d5) with comments intact,
and closed fwvf/n5fz/w1d5 to match GitHub #703/#709/#710, whose fixes had
already merged.